golib/socket/config

Socket Config

Configuration structures for declarative socket client and server setup with validation.

---

Table of Contents

• Overview
  • Design Philosophy
  • Key Features
• Architecture
  • Component Diagram
  • Limitations
• Performance
  • Benchmarks
  • Recommendations
• Use Cases
• Quick Start
  • Installation
  • Basic TCP Client
  • Basic TCP Server
  • Unix Socket with Permissions
• Examples
• Contributing
• Improvements & Security
• Resources
• AI Transparency
• License

---

Overview

The socket/config package provides a configuration-first approach to socket programming in Go. Instead of creating sockets directly, you define configuration structures that can be validated before instantiation. This pattern is particularly useful when:

• Loading socket parameters from external sources (files, environment variables, databases)
• Validating configuration at application startup rather than during runtime
• Supporting multiple socket types through a unified interface
• Requiring platform-specific validation (e.g., Unix sockets on non-Windows systems)

Design Philosophy

Configuration Separation: Socket parameters are defined independently from socket instances, enabling validation before connection attempts.

Declarative API: Configuration uses simple struct field assignments rather than complex builder patterns or method chaining.

Fail-Fast Validation: The Validate() methods catch configuration errors early, before network operations are attempted.

Platform Awareness: Built-in checks for platform-specific limitations (e.g., Unix sockets on Windows).

Security by Default: TLS/SSL configuration is validated to ensure proper certificate handling and protocol restrictions.

Key Features

• Protocol Flexibility: Single configuration API supports TCP, UDP, Unix, and Unixgram sockets
• TLS Support: First-class TLS/SSL configuration for TCP connections with certificate validation
• Unix Socket Permissions: Fine-grained control over Unix socket file permissions and group ownership
• Connection Management: Configurable idle timeouts for connection-oriented protocols
• Validation Guarantees: Comprehensive validation catches address format errors, protocol mismatches, platform incompatibilities, and TLS configuration issues

---

Architecture

Component Diagram

The package consists of two main configuration structures:

┌────────────────────────────────────────────────────────────┐
│                     socket/config                          │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌──────────────┐              ┌───────────────┐           │
│  │   Client     │              │   Server      │           │
│  ├──────────────┤              ├───────────────┤           │
│  │ Network      │              │ Network       │           │
│  │ Address      │              │ Address       │           │
│  │ TLS          │              │ PermFile      │           │
│  │              │              │ GroupPerm     │           │
│  │ + Validate() │              │ ConIdleTimeout│           │
│  └──────────────┘              │ TLS           │           │
│                                │               │           │
│                                │ + Validate()  │           │
│                                │ + DefaultTLS()│           │
│                                │ + GetTLS()    │           │
│                                └───────────────┘           │
│                                                            │
│  ┌────────────────────────────────────────────┐            │
│  │              Error Types                   │            │
│  ├────────────────────────────────────────────┤            │
│  │ ErrInvalidProtocol                         │            │
│  │ ErrInvalidTLSConfig                        │            │
│  │ ErrInvalidGroup                            │            │
│  └────────────────────────────────────────────┘            │
└────────────────────────────────────────────────────────────┘
           │                              │
           │                              │
           ▼                              ▼
┌────────────────────┐         ┌────────────────────┐
│ socket/client      │         │ socket/server      │
│ implementations    │         │ implementations    │
└────────────────────┘         └────────────────────┘

Configuration flows from external sources → config structs → validation → socket implementations.

Limitations

1. Platform-Specific Features: Unix domain sockets are not available on Windows
2. TLS Protocol Restrictions: TLS/SSL is only supported for TCP-based protocols
3. No Dynamic Reconfiguration: Changing configuration does not affect existing sockets
4. Group Permission Limits: Unix socket group IDs are limited to MaxGID (32767)
5. No IPv6 Scope IDs: Zone/scope IDs in link-local addresses may have platform-specific behavior

Performance

The configuration structures are designed for infrequent creation (e.g., application startup) rather than high-frequency operations.

Benchmarks

From the test suite performance measurements:

• Client Creation: < 100µs per instance
• Server Creation: < 100µs per instance
• TCP Validation: < 1ms average
• UDP Validation: < 1ms average
• Structure Copy: < 10µs (small memory footprint)

Recommendations

For hot-path operations:

• Cache validated configurations rather than re-validating
• Create socket instances once and reuse them
• Avoid calling Validate() in request handling loops

The structs are small (< 100 bytes) and safe to copy by value.

---

Use Cases

Configuration File Loading

Load socket parameters from YAML, JSON, or TOML files and validate them before starting services:

# config.yaml
client:
  network: tcp
  address: localhost:8080

This catches configuration errors at startup rather than during operation.

Environment-Based Configuration

Read socket settings from environment variables (12-factor app pattern):

network := os.Getenv("SOCKET_NETWORK")  // "tcp"
address := os.Getenv("SOCKET_ADDRESS")  // ":8080"

Create properly validated socket instances for different deployment environments.

Dynamic Service Discovery

Receive socket addresses from service discovery systems (Consul, etcd) and validate them before establishing connections.

Multi-Protocol Services

Configure services to listen on multiple socket types simultaneously:

// Network access via TCP
tcpCfg := config.Server{
    Network: protocol.NetworkTCP,
    Address: ":8080",
}

// Local IPC via Unix socket
unixCfg := config.Server{
    Network: protocol.NetworkUnix,
    Address: "/tmp/app.sock",
    PermFile: 0660,
}

Secure Service Communication

Define TLS/SSL parameters for encrypted client-server communication with proper certificate validation.

---

Quick Start

Installation

go get github.com/nabbar/golib/socket/config

Basic TCP Client

package main

import (
    "log"
    
    "github.com/nabbar/golib/socket/config"
    libptc "github.com/nabbar/golib/network/protocol"
)

func main() {
    // Create configuration
    cfg := config.Client{
        Network: libptc.NetworkTCP,
        Address: "localhost:8080",
    }
    
    // Validate before use
    if err := cfg.Validate(); err != nil {
        log.Fatal("Invalid configuration:", err)
    }
    
    // Configuration is valid, proceed with client creation
    log.Println("Client configuration validated successfully")
}

Basic TCP Server

package main

import (
    "log"
    
    "github.com/nabbar/golib/socket/config"
    libptc "github.com/nabbar/golib/network/protocol"
)

func main() {
    // Create configuration
    cfg := config.Server{
        Network: libptc.NetworkTCP,
        Address: ":8080",
    }
    
    // Validate before use
    if err := cfg.Validate(); err != nil {
        log.Fatal("Invalid configuration:", err)
    }
    
    // Configuration is valid, proceed with server creation
    log.Println("Server configuration validated successfully")
}

Unix Socket with Permissions

package main

import (
    "log"
    "runtime"
    
    "github.com/nabbar/golib/socket/config"
    libptc "github.com/nabbar/golib/network/protocol"
)

func main() {
    // Check platform compatibility
    if runtime.GOOS == "windows" {
        log.Fatal("Unix sockets not supported on Windows")
    }
    
    // Create configuration with permissions
    cfg := config.Server{
        Network:   libptc.NetworkUnix,
        Address:   "/tmp/app.sock",
        PermFile:  0660,  // Owner and group can read/write
        GroupPerm: 1000,  // Set to group 1000
    }
    
    // Validate
    if err := cfg.Validate(); err != nil {
        log.Fatal("Invalid configuration:", err)
    }
    
    log.Println("Unix socket configuration validated")
}

Examples

Multiple Server Types

// Network server for remote access
tcpCfg := config.Server{
    Network:        libptc.NetworkTCP,
    Address:        ":8080",
    ConIdleTimeout: 10 * time.Minute,
}

// Unix socket for local IPC (if not on Windows)
var unixCfg *config.Server
if runtime.GOOS != "windows" {
    unixCfg = &config.Server{
        Network:  libptc.NetworkUnix,
        Address:  "/tmp/app.sock",
        PermFile: 0660,
    }
}

// Validate all configurations before starting
if err := tcpCfg.Validate(); err != nil {
    log.Fatal("TCP config error:", err)
}

if unixCfg != nil {
    if err := unixCfg.Validate(); err != nil {
        log.Fatal("Unix socket config error:", err)
    }
}

Configuration from Environment

// Read from environment variables
network := os.Getenv("SOCKET_NETWORK")
if network == "" {
    network = "tcp"  // Default
}

address := os.Getenv("SOCKET_ADDRESS")
if address == "" {
    address = ":8080"  // Default
}

// Parse network protocol
var proto libptc.NetworkProtocol
switch network {
case "tcp":
    proto = libptc.NetworkTCP
case "udp":
    proto = libptc.NetworkUDP
case "unix":
    proto = libptc.NetworkUnix
default:
    log.Fatalf("Unknown network type: %s", network)
}

// Create and validate configuration
cfg := config.Server{
    Network: proto,
    Address: address,
}

if err := cfg.Validate(); err != nil {
    log.Fatal("Invalid configuration:", err)
}

Error Handling

cfg := config.Client{
    Network: libptc.NetworkUnix,
    Address: "/tmp/test.sock",
}

if err := cfg.Validate(); err != nil {
    switch {
    case errors.Is(err, config.ErrInvalidProtocol):
        log.Println("Unsupported protocol (possibly Windows)")
    case errors.Is(err, config.ErrInvalidTLSConfig):
        log.Println("TLS configuration error")
    case errors.Is(err, config.ErrInvalidGroup):
        log.Println("Invalid group permission")
    default:
        log.Printf("Validation error: %v", err)
    }
    return
}

Batch Validation

configs := []config.Server{
    {Network: libptc.NetworkTCP, Address: ":8080"},
    {Network: libptc.NetworkTCP, Address: ":8081"},
    {Network: libptc.NetworkUDP, Address: ":9000"},
}

// Validate all configurations before starting any servers
for i, cfg := range configs {
    if err := cfg.Validate(); err != nil {
        log.Fatalf("Configuration %d invalid: %v", i, err)
    }
}

log.Printf("All %d configurations validated successfully", len(configs))

---

Contributing

Contributions are welcome! Please follow these guidelines:

1. Code Quality

   • Follow Go best practices and idioms
   • Maintain or improve code coverage (target: >80%)
   • Pass all tests including race detector
   • Use gofmt and golint

2. AI Usage Policy

   • ❌ AI must NEVER be used to generate package code or core functionality
   • ✅ AI assistance is limited to:
     • Testing (writing and improving tests)
     • Debugging (troubleshooting and bug resolution)
     • Documentation (comments, README, TESTING.md)
   • All AI-assisted work must be reviewed and validated by humans

3. Testing

   • Add tests for new features
   • Use Ginkgo v2 / Gomega for test framework
   • Use gmeasure for benchmarks
   • Ensure zero race conditions

4. Documentation

   • Update GoDoc comments for public APIs
   • Add examples for new features
   • Update README.md and TESTING.md if needed

5. Pull Request Process

   • Fork the repository
   • Create a feature branch
   • Write clear commit messages
   • Ensure all tests pass
   • Update documentation
   • Submit PR with description of changes

---

Improvements & Security

Current Status

The package is production-ready with no urgent improvements or security vulnerabilities identified.

Code Quality Metrics

• ✅ 89.4% test coverage (target: >80%)
• ✅ Zero race conditions detected with -race flag
• ✅ Thread-safe configuration reading
• ✅ Platform-aware validation logic
• ✅ Memory-safe with no panics

Future Enhancements (Non-urgent)

The following enhancements could be considered for future versions:

1. YAML/JSON Serialization: Built-in marshaling/unmarshaling support for configuration files
2. Configuration Hot Reload: Support for reloading socket configurations without restart
3. Extended Protocol Support: SCTP, raw sockets, or other specialized protocols
4. Configuration Templates: Predefined templates for common use cases

These are optional improvements and not required for production use. The current implementation is stable and well-tested.

---

Resources

Package Documentation

• GoDoc - Complete API reference with function signatures, method descriptions, and runnable examples. Essential for understanding the public interface and usage patterns.

• doc.go - In-depth package documentation including design philosophy, architecture diagrams, performance considerations, and limitations. Provides detailed explanations of configuration structures and validation logic.

• TESTING.md - Comprehensive test suite documentation covering test architecture, BDD methodology with Ginkgo v2, coverage analysis (89.4%), performance benchmarks, and guidelines for writing new tests. Includes troubleshooting and CI integration examples.

Related golib Packages

• github.com/nabbar/golib/network/protocol - Network protocol definitions (TCP, UDP, Unix, etc.) used by the configuration structures. Provides the NetworkProtocol interface implemented by all supported protocols.

• github.com/nabbar/golib/certificates - TLS/SSL certificate configuration used for secure connections. Provides the Config and TLSConfig interfaces for certificate management and validation.

• github.com/nabbar/golib/socket/client - Socket client implementations that use these configuration structures. Shows real-world usage of Client configuration for establishing connections.

• github.com/nabbar/golib/socket/server - Socket server implementations that use these configuration structures. Shows real-world usage of Server configuration for accepting connections.

External References

• Effective Go - Official Go programming guide covering best practices for struct design, error handling, and interface usage. The config package follows these conventions for idiomatic Go code.

• Go net Package - Standard library networking package. The config package wraps net's address resolution and validation functions with additional type safety and platform checks.

• Unix Domain Sockets - Background on Unix domain sockets, their use cases, and how they differ from network sockets. Relevant for understanding Unix socket configuration options.

---

AI Transparency

In compliance with EU AI Act Article 50.4: AI assistance was used for testing, documentation, and bug resolution under human supervision. All core functionality is human-designed and validated.

---

License

MIT License - See LICENSE file for details.

Copyright (c) 2025 Nicolas JUHEL

---

Maintained by: Nicolas JUHEL
Package: github.com/nabbar/golib/socket/config
Version: See releases for versioning