Files
golib/status/README.md
nabbar 942068222c 2025-11 Improvement, Tests, Documentations, Bug Fix, Optimization
Global Repos / Workflow
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- UPDATE workflow: split old workflow into multiple files
- UPDATE .gitignore: added cluster.old.tar.gz and build artifacts
- UPDATE .golangci.yml: enhanced linter rules and disabled deprecated linters

[archive]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- FIX extract: recursive decompression for nested archives (e.g., .tar.gz handling)
- FIX extract: ZIP archive support now properly uses ReaderAt interface with seek reset
- ADD extract: proper symlink and hard link handling in archives
- UPDATE tar/writer: improved error handling and file mode preservation
- UPDATE zip/writer: enhanced validation and error messages
- UPDATE compress/interface: added support for additional compression formats
- UPDATE helper/compressor: fixed typo in error handling

[artifact]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE artifact: improved error handling and context management
- UPDATE client/interface: enhanced API with better type safety and context propagation
- UPDATE client/model: refactored for better maintainability
- UPDATE github: removed unused error codes, improved model validation
- UPDATE gitlab: enhanced API pagination and error handling
- UPDATE jfrog: improved artifactory API compatibility
- UPDATE s3aws: enhanced S3 bucket operations and error messages

[atomic]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE cast: improved type conversion with better error handling
- UPDATE interface: enhanced atomic operations with generics support
- UPDATE synmap: fixed race conditions in concurrent access patterns
- UPDATE value: improved atomic value operations with better memory ordering

[aws]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE bucket: enhanced ACL and CORS configuration with validation
- UPDATE configAws/models: improved credential handling and region configuration
- UPDATE configCustom/interface: added support for custom endpoints
- UPDATE http/request: improved retry logic and timeout handling
- UPDATE interface: enhanced AWS client with context propagation
- UPDATE model: refactored for AWS SDK v2 compatibility
- UPDATE multipart/interface: improved chunk handling for large uploads
- UPDATE pusher: optimized hash calculation and upload progress tracking
- UPDATE resolver: enhanced endpoint resolution with custom DNS
- DELETE test files: removed bucket_test.go, group_test.go, object_test.go, policy_test.go, role_test.go, user_test.go

[cache]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD context: context-aware cache lifecycle management
- UPDATE interface: complete rewrite with Go generics for type-safe key-value operations
- ADD item package: generic cache item with expiration tracking (interface and model)
- UPDATE model: refactored to use generics (Cache[K comparable, V any])
- REFACTOR: split item.go into modelAny.go for better code organization

[certificates]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE auth/encode: improved PEM encoding with better error messages
- UPDATE auth/interface: enhanced authentication certificate handling
- UPDATE ca: improved CA certificate generation and validation
- UPDATE certs: enhanced certificate configuration with SAN support
- UPDATE cipher: improved cipher suite selection and validation
- UPDATE curves: enhanced elliptic curve handling with additional curves
- ADD deprecated.go: marked deprecated TLS versions and cipher suites
- UPDATE interface: enhanced certificate interface with context support
- UPDATE model: improved certificate model with better validation
- UPDATE rootca: enhanced root CA pool management
- UPDATE tlsversion: added TLS 1.3 support with proper validation
- UPDATE tools: improved certificate utility functions

[cobra]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE completion: improved shell completion generation (bash, zsh, fish, powershell)
- UPDATE configure: enhanced configuration file handling
- UPDATE printError: improved error formatting with color support
- UPDATE interface: enhanced cobra interface with context support
- UPDATE model: improved cobra model with better validation

[config]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE components: improved component lifecycle management
- UPDATE const/const: improved constant definitions
- UPDATE context: enhanced context handling with better propagation
- UPDATE errors: improved error definitions
- UPDATE events: enhanced event management
- UPDATE manage: improved configuration management with validation
- UPDATE model: refactored config model
- UPDATE shell: enhanced shell integration for interactive configuration
- UPDATE types: improved component and componentList types

[console]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD buff.go: BuffPrintf function for colored output to io.Writer (moved from ioutils/multiplexer)
- DELETE color.go: removed legacy color file (consolidated functionality)
- UPDATE error: improved error definitions with better messages
- ADD interface: console interface for abstraction
- ADD model: console model for state management
- UPDATE padding: enhanced string padding with Unicode support
- UPDATE prompt: improved interactive prompt handling

[context]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- DELETE config.go: removed deprecated configuration (replaced by Config[T] interface)
- UPDATE context: improved context handling with better cancellation support
- UPDATE gin/interface: enhanced Gin context integration with type safety
- ADD helper: context helper functions for common operations
- ADD interface: generic Config[T comparable] interface for type-safe context storage
- ADD map: MapManage[T] interface for concurrent-safe map operations
- ADD model: thread-safe context model implementation with sync.Map

[database]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE gorm/config: improved database configuration
- UPDATE gorm/driver: enhanced database driver with better connection pooling
- UPDATE gorm/driver_darwin: macOS-specific database optimizations
- UPDATE gorm/interface: improved GORM interface with context support
- UPDATE gorm/model: refactored model for better maintainability
- UPDATE gorm/monitor: enhanced monitoring for database connections
- UPDATE kvtypes: improved types for key-value store (compare, driver, item, table)

[duration]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE big: enhanced big.Duration for large time spans with arithmetic operations
- UPDATE encode: improved marshaling for JSON, YAML, TOML, Text, CBOR
- UPDATE format: enhanced human-readable formatting (ns, μs, ms, s, m, h, d, w)
- UPDATE interface: improved duration interface with arithmetic methods
- UPDATE model: refactored Duration type
- UPDATE operation: enhanced arithmetic operations (Add, Sub, Mul, Div)
- UPDATE parse: improved parsing with multiple format support
- UPDATE truncate: enhanced truncation for rounding durations

[encoding]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE aes: improved AES encryption with reader/writer interfaces
- UPDATE hexa: enhanced hexadecimal encoding with better error handling
- UPDATE mux: improved multiplexer/demultiplexer for stream handling
- UPDATE randRead: enhanced random data generation
- UPDATE sha256 package: SHA-256 hashing with reader/writer interfaces

[errors]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD pool package: thread-safe error pool for collecting multiple errors with concurrent access
- UPDATE code: improved error code definition and lookup
- UPDATE errors: enhanced error creation with better stack trace
- UPDATE interface: improved error interface with more methods
- UPDATE mode: enhanced error mode handling (production vs development)
- UPDATE return: improved error return handling with context
- UPDATE trace: enhanced error tracing with file and line information

[file]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE bandwidth: improved bandwidth tracking with concurrency tests
- UPDATE perm: enhanced file permission handling with Unix/Windows support
- UPDATE perm/encode: improved marshaling for JSON, YAML, TOML
- UPDATE perm/format: enhanced permission formatting (e.g., "rwxr-xr-x")
- UPDATE perm/parse: improved parsing of permission strings and octal values
- UPDATE progress: enhanced progress tracking for file I/O operations
- UPDATE progress/io*: improved reader, writer, seeker, closer interfaces with progress callbacks

[ftpclient]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE config: improved FTP configuration with TLS support
- UPDATE errors: enhanced error definitions
- UPDATE interface: improved FTP client interface
- UPDATE model: refactored FTP client model

[httpcli]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE cli: improved HTTP client with retry logic and timeout handling
- UPDATE dns-mapper: enhanced DNS mapping for custom resolution
- UPDATE dns-mapper/config: improved DNS mapper configuration
- UPDATE dns-mapper/errors: enhanced error handling
- UPDATE dns-mapper/interface: improved DNS mapper interface
- UPDATE dns-mapper/transport: enhanced HTTP transport with DNS override
- UPDATE errors: improved error definitions
- UPDATE options: enhanced client options with context support

[httpserver]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE config: improved server configuration with TLS and middleware support
- UPDATE handler: enhanced request handler with better error handling
- UPDATE interface: improved server interface with context support and monitoring integration
- UPDATE model: refactored server model with better validation
- UPDATE monitor: enhanced monitoring integration with status tracking
- UPDATE pool: improved server pool management (config, interface, list, model)
- UPDATE run: enhanced server runtime with graceful shutdown
- UPDATE server: improved core server implementation with better lifecycle
- ADD testhelpers/certs.go: certificate generation utilities for testing
- UPDATE types: improved const, fields, and handler types

[ioutils]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE bufferReadCloser: improved buffered reader/writer with closer
- UPDATE fileDescriptor: enhanced file descriptor limit management (platform-specific for Linux/macOS/Windows)
- UPDATE ioprogress: improved progress tracking for I/O operations
- UPDATE iowrapper: enhanced I/O wrapper with custom interfaces
- UPDATE mapCloser: improved map of closers for resource management
- UPDATE maxstdio: enhanced C implementation for max stdio file descriptor retrieval
- DELETE multiplexer/model.go: removed legacy multiplexer (functionality moved to console/buff.go and retro/)
- UPDATE nopwritecloser: improved no-op write closer
- UPDATE tools: enhanced I/O utility functions

[ldap]
- UPDATE ldap: improved LDAP client with better connection handling and search operations

[logger]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE config: improved default values, file options, and syslog configuration
- UPDATE entry/interface: enhanced log entry with context support
- UPDATE fields: improved field handling with JSON cloning
- UPDATE gorm/interface: enhanced GORM logger with trace ID support
- UPDATE hashicorp/interface: improved HashiCorp logger integration
- FIX hookfile/system: use os.OpenRoot for secure file operations (prevents path traversal)
- FIX hookfile/system: fixed import path from libsrv "golib/server" to "golib/runner"
- ADD hookfile: IsRunning() method to track file hook state
- UPDATE hookstderr/interface: enhanced stderr hook with better buffering
- UPDATE hookstdout/interface: enhanced stdout hook with better buffering
- UPDATE hooksyslog: improved syslog integration with channel and priority handling
- ADD hookwriter package: generic io.Writer hook for custom output destinations
- UPDATE interface: enhanced logger interface with context propagation
- UPDATE level: improved log level handling and comparison
- UPDATE log: enhanced logging with better formatting
- UPDATE manage: improved logger lifecycle management
- UPDATE model: refactored logger model for better maintainability

[mail]
- UPDATE sender: improved mail sender with better MIME handling
- UPDATE interface: enhanced interface with monitoring support
- UPDATE monitor: added monitoring integration for mail operations

[monitor]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD status package: new subpackage for status management with Status type (KO, Warn, OK)
- ADD status/encode: marshaling support for JSON, YAML, TOML, Text, CBOR
- ADD status/format: human-readable status formatting
- ADD status/interface: Status type with Parse and String methods
- UPDATE encode: improved encoding with better error handling
- UPDATE error: enhanced error definitions
- UPDATE info: improved system info collection (CPU, mem, disk, network)
- UPDATE interface: enhanced monitor interface with status support and better component integration
- UPDATE metrics: improved metrics collection and export
- UPDATE middleware: enhanced monitoring middleware for HTTP
- UPDATE pool/interface: enhanced pool interface with better monitoring integration
- UPDATE pool/metrics: improved metrics collection in pool
- UPDATE pool/model: refactored pool model for better maintainability
- UPDATE pool/pool: enhanced pool implementation with better lifecycle
- UPDATE server: enhanced server monitoring with status tracking
- UPDATE types/monitor: improved monitor type definitions

[nats]
- UPDATE client: improved NATS client with better subscription handling
- UPDATE config: enhanced NATS configuration with cluster support
- UPDATE monitor: added monitoring integration for NATS operations
- UPDATE server: improved NATS server integration with monitoring

[network]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE bytes: improved byte size handling for network operations
- UPDATE number: enhanced number utilities for network data
- UPDATE protocol/encode: improved protocol encoding
- ADD protocol/format: protocol formatting utilities
- UPDATE protocol/interface: enhanced protocol interface
- UPDATE protocol/model: refactored protocol model

[password]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE password: improved password utilities with strength validation and secure generation

[pidcontroller]
- UPDATE interface: improved PID controller interface
- UPDATE model: enhanced PID controller model with better tuning parameters

[pprof]
- UPDATE tools: improved pprof utilities for profiling integration

[prometheus]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE bloom/bloom: improved bloom filter with better concurrency handling
- UPDATE bloom/collection: enhanced bloom filter collection operations
- UPDATE interface: enhanced prometheus interface with better type safety
- UPDATE metrics/interface: enhanced metrics interface with better registration
- UPDATE metrics/model: refactored metrics model for better maintainability
- UPDATE model: refactored prometheus model with better validation
- UPDATE pool: enhanced metric pool with concurrent access
- UPDATE pool/interface: enhanced pool interface
- UPDATE pool/model: refactored pool model
- UPDATE route: improved routing for metric endpoints
- UPDATE types: enhanced type definitions for metrics
- UPDATE webmetrics: improved existing metrics (requestBody, requestIPTotal, requestLatency, requestSlow, requestTotal, requestURITotal, responseBody)
- ADD webmetrics/activeConnections: gauge for tracking concurrent HTTP connections
- ADD webmetrics/requestErrors: counter for HTTP request errors
- ADD webmetrics/responseSizeByEndpoint: histogram for response size distribution by endpoint
- ADD webmetrics/statusCodeTotal: counter for HTTP status codes

[request]
- UPDATE interface: enhanced request interface with better type safety
- UPDATE model: refactored request model for better maintainability
- UPDATE options: improved request options with better validation
- UPDATE url: enhanced URL handling with better parsing

[retro]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE encoding: improved encoding utilities with better format support
- UPDATE format: enhanced formatting functions for retro compatibility
- UPDATE model: refactored retro model with better validation
- UPDATE utils: improved utility functions for version handling
- UPDATE version: enhanced version utilities for retro compatibility

[router]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE auth/interface: enhanced authentication interface with better validation
- UPDATE auth/model: improved authentication model
- UPDATE authheader/interface: enhanced authentication header interface
- UPDATE default: improved default router configuration
- UPDATE error: enhanced error definitions for router
- UPDATE header/config: improved header configuration
- UPDATE header/interface: enhanced header interface
- UPDATE header/model: refactored header model
- UPDATE interface: improved router interface with better type safety
- UPDATE middleware: improved router middleware with better error handling
- UPDATE model: refactored router model for better maintainability
- UPDATE router: enhanced core router implementation
- UPDATE tools: enhanced router utilities for route registration

[runner]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE package: move package for lifecycle management of long-running services (moved from server/runner)
- ADD interface: Runner interface with Start, Stop, Restart, IsRunning, and Uptime methods
- ADD startStop package: service lifecycle with blocking start and graceful stop (interface, model, comprehensive tests)
- ADD ticker package: periodic task execution at regular intervals (interface, model, comprehensive tests)
- ADD tests: concurrency, construction, errors, lifecycle, and uptime tests for both startStop and ticker
- ADD tools: RecoveryCaller for panic recovery in goroutines

[semaphore]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- FIX bar/bar: Dec method now properly decrements (was calling Inc64, now calls Dec64 with negative value)
- UPDATE bar: improved progress bar with better MPB integration
- UPDATE bar/context: enhanced context handling for cancellation
- UPDATE bar/interface: added methods for Total() and better progress tracking
- UPDATE bar/model: improved model with atomic operations
- UPDATE bar tests: enhanced bar_operations_test, edge_cases_test, integration_test, and semaphore_test
- UPDATE context: enhanced context propagation
- UPDATE interface: improved semaphore interface with weighted operations
- UPDATE model: refactored model for better thread safety
- UPDATE progress: enhanced progress tracking with multiple bars
- UPDATE sem/interface: added IsRunning() method for state tracking
- UPDATE sem/ulimit: improved ulimit handling for file descriptors
- UPDATE sem/weighted: enhanced weighted semaphore operations
- UPDATE types: improved type definitions for bar, progress, and semaphore

[server]
- REFACTOR: moved runner subpackage to root-level runner package
- DELETE: empty package after moved runner subpackage

[shell]
- UPDATE goprompt: improved interactive prompt handling with better input validation

[size]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD arithmetic.go: NEW file with arithmetic operations (Add, Sub, Mul, Div with overflow detection)
- UPDATE encode: improved marshaling for JSON, YAML, TOML, Text, CBOR
- UPDATE format: enhanced human-readable formatting (B, KB, MB, GB, TB, PB, EB)
- UPDATE interface: added arithmetic methods (Mul, MulErr, Div, DivErr, Add, AddErr, Sub, SubErr)
- UPDATE model: refactored Size type with better validation
- UPDATE parse: improved parsing with unit detection (IEC and SI standards)

[smtp]
- UPDATE client: improved SMTP client with better error handling
- UPDATE config: enhanced configuration with validation
- UPDATE config/error: improved error definitions
- UPDATE config/interface: enhanced interface with context support
- UPDATE config/model: refactored model for better maintainability
- UPDATE interface: improved SMTP interface with monitoring support
- UPDATE monitor: added monitoring integration for SMTP operations
- DELETE network/network.go: removed legacy network handling (consolidated into client)
- UPDATE tlsmode/tls: enhanced TLS mode handling (None, TLS, StartTLS)
- UPDATE types/interface: improved type interface

[socket]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- ADD client/interface_darwin: macOS-specific socket client options
- UPDATE client/interface_linux: platform-specific socket options for Linux
- UPDATE client/interface_other: platform-specific socket options for other platforms
- UPDATE client/tcp/error: improved TCP client error handling
- UPDATE client/tcp/interface: enhanced TCP client interface
- UPDATE client/tcp/model: improved TCP client model
- UPDATE client/udp/error: improved UDP client error handling
- UPDATE client/udp/interface: enhanced UDP client interface
- UPDATE client/udp/model: improved UDP client model
- UPDATE client/unix/error: improved Unix socket client error handling
- UPDATE client/unix/ignore: enhanced ignore functionality
- UPDATE client/unix/interface: enhanced Unix socket client interface
- UPDATE client/unix/model: improved Unix socket client model
- UPDATE client/unixgram/error: improved Unix datagram client error handling
- UPDATE client/unixgram/ignore: enhanced ignore functionality
- UPDATE client/unixgram/interface: enhanced Unix datagram client interface
- UPDATE client/unixgram/model: improved Unix datagram client model
- UPDATE config/client: improved client configuration
- UPDATE config/server: improved server configuration
- DELETE delim: moved legacy delimiter to I/O package
- UPDATE interface: improved socket interface
- UPDATE io: enhanced I/O operations
- DELETE multi: moved legacy multi to I/O package
- ADD server/interface_darwin: macOS-specific socket server options
- UPDATE server/interface_linux: platform-specific server options for Linux
- UPDATE server/interface_other: platform-specific server options for other platforms
- UPDATE server/tcp/error: improved TCP server error handling
- UPDATE server/tcp/interface: enhanced TCP server interface
- UPDATE server/tcp/listener: improved TCP server listener
- UPDATE server/tcp/model: improved TCP server model
- UPDATE server/udp/error: improved UDP server error handling
- UPDATE server/udp/interface: enhanced UDP server interface
- UPDATE server/udp/listener: improved UDP server listener
- UPDATE server/udp/model: improved UDP server model
- UPDATE server/unix/error: improved Unix socket server error handling
- UPDATE server/unix/ignore: enhanced ignore functionality
- UPDATE server/unix/interface: enhanced Unix socket server interface
- UPDATE server/unix/listener: improved Unix socket server listener
- UPDATE server/unix/model: improved Unix socket server model
- UPDATE server/unixgram/error: improved Unix datagram server error handling
- UPDATE server/unixgram/ignore: enhanced ignore functionality
- UPDATE server/unixgram/interface: enhanced Unix datagram server interface
- UPDATE server/unixgram/listener: improved Unix datagram server listener
- UPDATE server/unixgram/model: improved Unix datagram server model

[static]
- UPDATE interface: improved static interface with monitoring support
- UPDATE model: refactored static model
- UPDATE monitor: added monitoring integration for static file operations

[status]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE cache: improved status cache with better synchronization
- UPDATE config: improved status configuration
- UPDATE control/encode: improved control encoding
- UPDATE control/interface: enhanced control interface with status tracking
- UPDATE control/model: refactored control model
- UPDATE encode: improved status encoding
- UPDATE error: enhanced error definitions for status
- UPDATE info: improved status info handling
- UPDATE interface: enhanced status interface
- UPDATE listmandatory/interface: improved list mandatory interface
- UPDATE listmandatory/model: refactored list mandatory model
- UPDATE mandatory/interface: enhanced mandatory interface
- UPDATE mandatory/model: refactored mandatory model
- UPDATE model: refactored status model
- UPDATE pool: improved status pool
- UPDATE route: enhanced status route handling

[test]
- DELETE: all manual tests are or will be replaced by proper automated test suites in respective packages

[version]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE error: improved error definitions for version
- UPDATE license: enhanced license handling
- UPDATE version: improved version utilities

[viper]
- ADD/UPDATE documentation: comprehensive documentation with monitoring patterns
- ADD/UPDATE tests: enhanced benchmark, config, encoding, example, integration, lifecycle, metrics, security, transitions
- UPDATE interface: enhanced viper interface with context support
- UPDATE model: refactored viper model for better maintainability
2025-11-15 21:09:32 +01:00

28 KiB

Status Package

License: MIT Go Version

Comprehensive health check and status monitoring system for HTTP APIs with flexible control modes, caching, and multi-format output support.


Table of Contents


Overview

This package provides production-ready health check and status monitoring for Go HTTP APIs. It integrates with the Gin web framework to expose status endpoints that aggregate component health checks with configurable validation strategies.

Design Philosophy

  1. Flexible Validation: Multiple control modes (Must, Should, AnyOf, Quorum) for different component criticality levels
  2. Performance-Focused: Built-in caching with atomic operations reduces overhead for frequent health checks
  3. Thread-Safe: Full concurrency support with proper synchronization primitives
  4. Multi-Format: JSON and plain text output for different consumption scenarios
  5. Integration-Ready: Works seamlessly with github.com/nabbar/golib/monitor for component monitoring

Key Features

  • Component Monitoring: Aggregate health from multiple monitored components
  • Control Modes: Flexible validation strategies (Ignore, Should, Must, AnyOf, Quorum)
  • Caching: 3-second default cache with atomic operations for high-frequency checks
  • Multi-Format Output: JSON (default) and plain text via query parameters or headers
  • Verbosity Control: Short (status only) or full (with component details) responses
  • Thread-Safe: Atomic operations and mutex protection for concurrent access
  • Configurable HTTP Codes: Customize return codes for OK (200), Warn (207), KO (500) states
  • Version Tracking: Include application name, version, and build information
  • Gin Integration: Drop-in middleware for Gin web framework

Installation

go get github.com/nabbar/golib/status

Architecture

Package Structure

The package is organized into focused subpackages with clear responsibilities:

status/
├── control/             # Validation mode definitions
│   ├── interface.go     # Mode type and constants
│   ├── encode.go        # Marshaling support (JSON, YAML, TOML, CBOR)
│   └── format.go        # String parsing and formatting
├── mandatory/           # Single component group management
│   ├── interface.go     # Mandatory interface
│   └── model.go         # Thread-safe implementation
├── listmandatory/       # Multiple group management
│   ├── interface.go     # ListMandatory interface
│   └── model.go         # Collection handling
├── interface.go         # Main Status interface
├── model.go             # Core implementation
├── config.go            # Configuration structures
├── cache.go             # Status caching
├── route.go             # HTTP endpoint handler
└── encode.go            # Response marshaling

Component Overview

┌──────────────────────────────────────────────────────┐
│                  Status Package                      │
│  HTTP Endpoint + Component Health Aggregation       │
└──────────────┬────────────┬──────────────┬──────────┘
               │            │              │
      ┌────────▼───┐  ┌────▼─────┐  ┌────▼────────┐
      │  control   │  │mandatory │  │listmandatory│
      │            │  │          │  │             │
      │ Validation │  │  Group   │  │ Collection  │
      │   Modes    │  │ Manager  │  │  Manager    │
      └────────────┘  └──────────┘  └─────────────┘
               │            │              │
               └────────────┴──────────────┘
                            │
                  ┌─────────▼──────────┐
                  │  monitor/types     │
                  │  Component Health  │
                  └────────────────────┘
Component Purpose Thread-Safe Marshaling
status Main coordinator, HTTP endpoint JSON, Text
control Validation mode definitions JSON, YAML, TOML, CBOR
mandatory Component group with mode N/A
listmandatory Multiple group management N/A

Data Flow

[HTTP Request]
      ↓
[MiddleWare] → Parse query params/headers
      ↓
[getStatus] → Walk monitor pool
      ↓
[Control Mode Logic]
  ├─ Ignore: Skip component
  ├─ Should: Warn only (no failure)
  ├─ Must: Must be healthy
  ├─ AnyOf: At least one healthy
  └─ Quorum: Majority (>50%) healthy
      ↓
[Encode] → JSON or Text format
      ↓
[HTTP Response] → With status code

Performance

Caching

The package implements efficient caching to reduce overhead:

  • Default Cache: 3 seconds (configurable)
  • Atomic Operations: Lock-free reads via atomic.Value
  • Thread-Safe: Safe for concurrent health checks
  • Cache Methods:
    • IsCacheHealthy(): Check >= Warn (accepts warnings)
    • IsCacheStrictlyHealthy(): Check == OK (strict)

Performance Impact: Cached checks complete in <10ns (no component walking)

Benchmark Results

BenchmarkNew-12                    13,963,723      77.33 ns/op      72 B/op    4 allocs/op
BenchmarkSetMode-12               135,494,511       9.02 ns/op       0 B/op    0 allocs/op
BenchmarkGetMode-12               174,430,036       6.77 ns/op       0 B/op    0 allocs/op
BenchmarkKeyAdd-12                 23,573,498      45.56 ns/op      40 B/op    2 allocs/op
BenchmarkKeyHas-12                100,000,000      10.04 ns/op       0 B/op    0 allocs/op
BenchmarkKeyList-12                21,103,474      57.20 ns/op      80 B/op    1 allocs/op
BenchmarkConcurrentReads-12        37,712,851      32.36 ns/op      48 B/op    1 allocs/op
BenchmarkConcurrentWrites-12       10,351,329     118.60 ns/op      40 B/op    2 allocs/op
BenchmarkMixedOperations-12        31,084,405      38.72 ns/op      15 B/op    0 allocs/op

Measured on AMD Ryzen 9 7900X3D, Linux, Go 1.21+

Concurrency

  • Atomic State: atomic.Int32, atomic.Int64, atomic.Value for cache
  • Mutex Protection: sync.RWMutex for configuration and pool access
  • Zero Races: Verified with go test -race (no data races detected)

Use Cases

This package is designed for scenarios requiring robust health monitoring:

Microservices Health Checks

  • Aggregate health from databases, caches, queues, external APIs
  • Configure critical (Must) vs optional (Should) dependencies
  • Return appropriate HTTP codes for load balancers and orchestrators

Kubernetes/Docker Health Probes

  • Liveness probe: Use IsStrictlyHealthy() for restart signals
  • Readiness probe: Use IsHealthy() to tolerate warnings
  • Startup probe: Check with cached status for efficiency

API Gateway Integration

  • Expose /health and /status endpoints
  • JSON for programmatic consumption
  • Text format for quick visual inspection

Monitoring Systems

  • Integrate with Prometheus, Datadog, New Relic
  • Cache reduces load on monitoring components
  • Detailed component status for diagnostics

Distributed Systems

  • AnyOf mode: Redis cluster with multiple nodes (any healthy = OK)
  • Quorum mode: Database replicas (majority must be healthy)
  • Must mode: Core dependencies (all must be healthy)

Quick Start

Basic Status Endpoint

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/nabbar/golib/context"
    "github.com/nabbar/golib/status"
    "github.com/nabbar/golib/monitor/pool"
    "github.com/nabbar/golib/monitor/info"
)

func main() {
    // Create context
    ctx := context.NewGlobal()
    
    // Create status instance
    sts := status.New(ctx)
    
    // Set application info
    sts.SetInfo("my-api", "v1.0.0", "abc123")
    
    // Create and register monitor pool
    monPool := pool.New(ctx)
    sts.RegisterPool(func() montps.Pool { return monPool })
    
    // Add a component monitor
    dbMonitor := info.New(func(context.Context) (monsts.Status, string, error) {
        // Check database health
        if dbHealthy() {
            return monsts.OK, "Database connected", nil
        }
        return monsts.KO, "Database connection failed", nil
    })
    monPool.MonitorAdd(dbMonitor)
    
    // Set up Gin router
    r := gin.Default()
    r.GET("/status", func(c *gin.Context) {
        sts.MiddleWare(c)
    })
    
    r.Run(":8080")
}

func dbHealthy() bool {
    // Your health check logic
    return true
}

With Configuration

import (
    "net/http"
    "github.com/nabbar/golib/status"
    "github.com/nabbar/golib/status/control"
    monsts "github.com/nabbar/golib/monitor/status"
)

func setupStatus() status.Status {
    sts := status.New(ctx)
    sts.SetInfo("my-api", "v1.0.0", "abc123")
    
    // Configure HTTP return codes and mandatory components
    cfg := status.Config{
        ReturnCode: map[monsts.Status]int{
            monsts.OK:   http.StatusOK,           // 200
            monsts.Warn: http.StatusMultiStatus,  // 207
            monsts.KO:   http.StatusServiceUnavailable, // 503
        },
        MandatoryComponent: []status.Mandatory{
            {
                Mode: control.Must,
                Keys: []string{"database", "cache"},
            },
            {
                Mode: control.Should,
                Keys: []string{"email-service"},
            },
            {
                Mode: control.AnyOf,
                Keys: []string{"redis-1", "redis-2", "redis-3"},
            },
        },
    }
    sts.SetConfig(cfg)
    
    return sts
}

Health Check Methods

// In your application
sts := setupStatus()

// Check if healthy (tolerates warnings)
if sts.IsHealthy() {
    log.Println("Service is healthy")
}

// Check specific components
if sts.IsHealthy("database", "cache") {
    log.Println("Core components healthy")
}

// Strict check (no warnings allowed)
if sts.IsStrictlyHealthy() {
    log.Println("Service is perfectly healthy")
}

// Cached checks (efficient for frequent calls)
if sts.IsCacheHealthy() {
    // Uses cached status (3s default)
}

Subpackages

control Subpackage

Validation mode definitions for component health evaluation.

Available Modes

package control

type Mode uint8

const (
    Ignore Mode = iota  // No validation (component ignored)
    Should              // Warning only (doesn't cause failure)
    Must                // Must be healthy (causes failure if not)
    AnyOf               // At least one in group must be healthy
    Quorum              // Majority (>50%) must be healthy
)

Mode Behavior

Mode Component Status Overall Impact
Ignore Any No impact (skipped)
Should KO → Warn (not KO)
Should Warn → Warn
Should OK No impact
Must KO → KO
Must Warn → Warn
Must OK No impact
AnyOf All KO → KO
AnyOf At least 1 OK No impact
AnyOf Only Warn → Warn
Quorum ≤50% OK+Warn → KO
Quorum >50% OK+Warn No impact or → Warn

String Parsing

import "github.com/nabbar/golib/status/control"

// Parse from string (case-insensitive)
mode := control.Parse("must")      // → Must
mode = control.Parse("ANYOF")      // → AnyOf
mode = control.Parse("invalid")    // → Ignore (default)

// Format to string
str := control.Must.String()       // → "Must"

Marshaling Support

The Mode type implements multiple encoding interfaces:

// JSON
data, _ := json.Marshal(control.Must)  // → "Must"
var mode control.Mode
json.Unmarshal([]byte(`"must"`), &mode)

// YAML
data, _ := yaml.Marshal(control.Must)
yaml.Unmarshal([]byte("must"), &mode)

// TOML
data, _ := mode.MarshalTOML()

// CBOR (binary)
data, _ := mode.MarshalCBOR()

// Plain text
data, _ := mode.MarshalText()

See GoDoc for complete API.


mandatory Subpackage

Manages a single component group with an associated validation mode.

Features

  • Thread-safe key management
  • Atomic mode operations
  • Lock-free reads for high performance

API Example

import (
    "github.com/nabbar/golib/status/mandatory"
    "github.com/nabbar/golib/status/control"
)

// Create new group
m := mandatory.New()

// Set validation mode
m.SetMode(control.Must)

// Add component keys
m.KeyAdd("database", "cache", "queue")

// Check if key exists
if m.KeyHas("database") {
    fmt.Println("Database is in mandatory group")
}

// Get current mode
mode := m.GetMode()  // → Must

// List all keys
keys := m.KeyList()  // → ["database", "cache", "queue"]

// Remove keys
m.KeyDel("queue")

Thread Safety

// Safe for concurrent use
var wg sync.WaitGroup
m := mandatory.New()

for i := 0; i < 100; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        m.KeyAdd(fmt.Sprintf("component-%d", id))
    }(i)
}
wg.Wait()

fmt.Println(m.KeyList())  // All 100 components added safely

See GoDoc for complete API.


listmandatory Subpackage

Manages multiple mandatory groups as a collection.

Features

  • Thread-safe collection operations
  • Iterator pattern with Walk method
  • Automatic cleanup of invalid entries

API Example

import (
    "github.com/nabbar/golib/status/listmandatory"
    "github.com/nabbar/golib/status/mandatory"
    "github.com/nabbar/golib/status/control"
)

// Create list
list := listmandatory.New()

// Create and add groups
coreGroup := mandatory.New()
coreGroup.SetMode(control.Must)
coreGroup.KeyAdd("database", "cache")
list.Add(coreGroup)

optionalGroup := mandatory.New()
optionalGroup.SetMode(control.Should)
optionalGroup.KeyAdd("email", "sms")
list.Add(optionalGroup)

redisCluster := mandatory.New()
redisCluster.SetMode(control.AnyOf)
redisCluster.KeyAdd("redis-1", "redis-2", "redis-3")
list.Add(redisCluster)

// Get count
count := list.Len()  // → 3

// Walk through groups
list.Walk(func(m mandatory.Mandatory) bool {
    fmt.Printf("Mode: %s, Keys: %v\n", m.GetMode(), m.KeyList())
    return true  // Continue iteration
})

// Remove a group
list.Del(optionalGroup)

See GoDoc for complete API.


Configuration

Config Structure

type Config struct {
    // HTTP status codes for each health state
    ReturnCode map[monsts.Status]int
    
    // Component groups with validation modes
    MandatoryComponent []Mandatory
}

type Mandatory struct {
    Mode control.Mode  // Validation mode
    Keys []string      // Component names
}

Default Values

If ReturnCode is empty, defaults are:

  • monsts.OK → 200 (http.StatusOK)
  • monsts.Warn → 207 (http.StatusMultiStatus)
  • monsts.KO → 500 (http.StatusInternalServerError)

Configuration Examples

Standard Web API

cfg := status.Config{
    ReturnCode: map[monsts.Status]int{
        monsts.OK:   200,  // OK
        monsts.Warn: 200,  // Treat warnings as OK
        monsts.KO:   503,  // Service Unavailable
    },
    MandatoryComponent: []status.Mandatory{
        {Mode: control.Must, Keys: []string{"database"}},
        {Mode: control.Should, Keys: []string{"cache"}},
    },
}

Kubernetes Health Probes

// Liveness: Strict (restart if any issue)
livenessCfg := status.Config{
    ReturnCode: map[monsts.Status]int{
        monsts.OK:   200,
        monsts.Warn: 500,  // Treat warnings as failure
        monsts.KO:   500,
    },
    MandatoryComponent: []status.Mandatory{
        {Mode: control.Must, Keys: []string{"core"}},
    },
}

// Readiness: Tolerant (accept warnings)
readinessCfg := status.Config{
    ReturnCode: map[monsts.Status]int{
        monsts.OK:   200,
        monsts.Warn: 200,  // Accept warnings
        monsts.KO:   503,
    },
}

Distributed System

cfg := status.Config{
    MandatoryComponent: []status.Mandatory{
        // Core database: must be healthy
        {Mode: control.Must, Keys: []string{"postgres"}},
        
        // Redis cluster: any node OK
        {Mode: control.AnyOf, Keys: []string{
            "redis-master", "redis-replica-1", "redis-replica-2",
        }},
        
        // Kafka cluster: quorum required
        {Mode: control.Quorum, Keys: []string{
            "kafka-1", "kafka-2", "kafka-3",
        }},
        
        // Optional services
        {Mode: control.Should, Keys: []string{"email", "sms"}},
    },
}

HTTP API

Endpoint Configuration

r := gin.Default()

// Simple endpoint
r.GET("/status", func(c *gin.Context) {
    sts.MiddleWare(c)
})

// With generic context
r.GET("/health", func(c *gin.Context) {
    sts.Expose(c)
})

Query Parameters

Parameter Values Description
short true, 1 Return only overall status (no component details)
format text, json Output format (default: JSON)

HTTP Headers

Header Values Description
X-Verbose false Return short output (same as short=true)
Accept text/plain, application/json Content negotiation

Response Formats

JSON Response (default)

{
  "name": "my-api",
  "release": "v1.0.0",
  "hash": "abc123",
  "date_build": "2024-11-13T08:00:00Z",
  "status": "OK",
  "message": "",
  "component": {
    "database": {
      "status": "OK",
      "message": "Database connected",
      "options": {}
    },
    "cache": {
      "status": "OK",
      "message": "Redis operational",
      "options": {}
    }
  }
}

JSON Response (short)

{
  "name": "my-api",
  "release": "v1.0.0",
  "hash": "abc123",
  "date_build": "2024-11-13T08:00:00Z",
  "status": "OK",
  "message": ""
}

Text Response

OK: my-api (v1.0.0 - abc123)

Text Response (verbose)

OK: my-api (v1.0.0 - abc123)
  database: OK - Database connected
  cache: OK - Redis operational

HTTP Status Codes

The HTTP status code in the response depends on configuration:

Health Status Default Code Meaning
OK 200 All components healthy
Warn 207 Some warnings present
KO 500 One or more critical components failed

Customize codes via Config.ReturnCode (see Configuration).

Usage Examples

cURL

# JSON (default)
curl http://localhost:8080/status

# JSON short
curl http://localhost:8080/status?short=true

# Text format
curl http://localhost:8080/status?format=text

# Text format with details
curl -H "Accept: text/plain" http://localhost:8080/status

# Short via header
curl -H "X-Verbose: false" http://localhost:8080/status

Go Client

resp, err := http.Get("http://localhost:8080/status")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

if resp.StatusCode == http.StatusOK {
    log.Println("Service is healthy")
}

var status struct {
    Name    string `json:"name"`
    Release string `json:"release"`
    Status  string `json:"status"`
}
json.NewDecoder(resp.Body).Decode(&status)

Best Practices

Component Organization

Group by Criticality

cfg := status.Config{
    MandatoryComponent: []status.Mandatory{
        // Critical: Must be healthy for service to function
        {Mode: control.Must, Keys: []string{
            "database",
            "auth-service",
        }},
        
        // Important: Warnings acceptable, but not failures
        {Mode: control.Should, Keys: []string{
            "cache",
            "search-index",
        }},
        
        // Redundant: Any one instance is sufficient
        {Mode: control.AnyOf, Keys: []string{
            "worker-1", "worker-2", "worker-3",
        }},
    },
}

Health Check Implementation

Good Practices

// 1. Fast health checks (<100ms)
func checkDatabase() (monsts.Status, string, error) {
    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel()
    
    if err := db.PingContext(ctx); err != nil {
        return monsts.KO, "Database unreachable", err
    }
    return monsts.OK, "Database connected", nil
}

// 2. Use cached status for efficiency
if sts.IsCacheHealthy() {
    // Serve traffic (uses 3s cache)
}

// 3. Distinguish between warnings and failures
func checkCache() (monsts.Status, string, error) {
    if err := cache.Ping(); err != nil {
        // Cache down but not critical
        return monsts.Warn, "Cache unavailable", err
    }
    return monsts.OK, "Cache operational", nil
}

// 4. Provide meaningful messages
return monsts.KO, fmt.Sprintf("Connection pool exhausted: %d/%d", active, max), nil

Bad Practices

// 1. Slow health checks (blocks thread)
func checkBad() (monsts.Status, string, error) {
    time.Sleep(5 * time.Second) // Too slow!
    return monsts.OK, "", nil
}

// 2. Ignoring cache benefits
for {
    if sts.IsHealthy() { // Recalculates every time
        // Heavy operation repeated unnecessarily
    }
    time.Sleep(100 * time.Millisecond)
}

// 3. Generic error messages
return monsts.KO, "Error", err // Not helpful for debugging

// 4. Silent failures
func checkSilent() (monsts.Status, string, error) {
    db.Ping() // Ignoring error
    return monsts.OK, "", nil
}

Error Handling

Always Handle Errors

// ✅ Good
if err := sts.MonitorAdd(monitor); err != nil {
    log.Printf("Failed to add monitor: %v", err)
    return err
}

// ❌ Bad
sts.MonitorAdd(monitor) // Ignoring error

Kubernetes Integration

Liveness Probe (Restart on failure)

livenessProbe:
  httpGet:
    path: /status?short=true
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

Readiness Probe (Remove from service on failure)

readinessProbe:
  httpGet:
    path: /status?short=true
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 2

Startup Probe (Initial health check)

startupProbe:
  httpGet:
    path: /status?short=true
    port: 8080
  initialDelaySeconds: 0
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 30  # Allow 150s for startup

Monitoring Integration

Prometheus Metrics

import "github.com/prometheus/client_golang/prometheus"

var (
    healthStatus = prometheus.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "app_health_status",
            Help: "Health status (0=KO, 1=Warn, 2=OK)",
        },
        []string{"component"},
    )
)

func updateMetrics(sts status.Status) {
    sts.MonitorWalk(func(name string, mon montps.Monitor) bool {
        status := mon.Status()
        healthStatus.WithLabelValues(name).Set(float64(status.Int()))
        return true
    })
}

Performance Optimization

Use Cached Methods

// High-frequency checks (every request)
func middleware(c *gin.Context) {
    if !sts.IsCacheHealthy() {
        c.AbortWithStatus(503)
        return
    }
    c.Next()
}

// Background monitoring
go func() {
    ticker := time.NewTicker(10 * time.Second)
    for range ticker.C {
        if !sts.IsHealthy() {
            alerting.Trigger("service-unhealthy")
        }
    }
}()

Component Monitoring Best Practices

  • Keep checks lightweight (<100ms)
  • Use timeouts to prevent hanging
  • Cache expensive checks in the monitor itself
  • Return specific error messages
  • Use appropriate control modes (Must vs Should)

Testing

Test Suite: 306 specs across 4 packages with 85.6% overall coverage

# Run all tests
go test ./...

# With coverage
go test -cover ./...

# With race detection (recommended)
CGO_ENABLED=1 go test -race ./...

# Benchmarks
go test -bench=. -benchmem ./mandatory/

Test Results

status/                120 specs    85.6% coverage   10.7s
status/control/        102 specs    95.0% coverage   0.01s
status/listmandatory/   29 specs    75.4% coverage   0.5s
status/mandatory/       55 specs    76.1% coverage   0.1s

Quality Assurance

  • Zero data races (verified with -race)
  • Thread-safe concurrent operations
  • Comprehensive edge case coverage
  • Benchmark performance validation

See TESTING.md for detailed testing documentation.


Contributing

Contributions are welcome! Please follow these guidelines:

Code Contributions

  • Do not use AI to generate package implementation code
  • AI may assist with tests, documentation, and bug fixing
  • All contributions must pass go test -race
  • Maintain or improve test coverage (≥80%)
  • Follow existing code style and patterns

Documentation

  • Update README.md for new features
  • Add examples for common use cases
  • Keep TESTING.md synchronized with test changes

Testing

  • Write tests for all new features
  • Test edge cases and error conditions
  • Verify thread safety with race detector
  • Add comments explaining complex scenarios

Pull Requests

  • Provide clear description of changes
  • Reference related issues
  • Include test results
  • Update documentation

See CONTRIBUTING.md for detailed guidelines.


Future Enhancements

Potential improvements for future versions:

Control Modes

  • Custom validation logic via function callbacks
  • Weighted quorum (different components have different weights)
  • Time-based validation (require health for N consecutive checks)

Caching

  • Per-component cache duration
  • Cache invalidation hooks
  • Configurable cache strategies (LRU, TTL, etc.)

Monitoring

  • Built-in metrics export (Prometheus format)
  • Health check history and trends
  • Circuit breaker integration for failing components

Output Formats

  • XML output support
  • GraphQL endpoint support
  • Structured logging output

Advanced Features

  • Dependency graphs (component A depends on B)
  • Health check scheduling (different intervals per component)
  • Multi-region health aggregation
  • gRPC health check protocol support

Suggestions and contributions are welcome via GitHub issues.


AI Transparency Notice

In accordance with Article 50.4 of the EU AI Act, AI assistance has been used for testing, documentation, and bug fixing under human supervision.


License

MIT License - See LICENSE file for details.


Resources


Version: Go 1.18+ on Linux, macOS, Windows
Maintained By: Status Package Contributors