golib

Comprehensive Go library collection providing production-ready packages for cloud services, web infrastructure, data management, security, monitoring, and development utilities. Built for enterprise-grade applications with extensive testing and documentation.

Overview

golib is a comprehensive collection of production-ready Go packages designed to accelerate enterprise application development. Each package is independently usable, thoroughly tested, and follows Go best practices with a focus on performance, thread safety, and observability.

This library provides building blocks for cloud-native applications, web services, data processing, secure communications, production operations, and development productivity.

Design Philosophy

Modularity: Self-contained packages with minimal cross-dependencies
Production-Ready: Comprehensive testing with 11,818 specs across 131 packages
Performance-First: Streaming operations, zero-allocation paths, optimized throughput
Thread-Safe: All concurrent operations validated with race detector
Observable: Structured logging, Prometheus metrics, health checks, monitoring
Standards-Compliant: Go idioms, semantic versioning, standard library interfaces

Repository Statistics

Total Packages:       165 (131 with tests, 34 utility/types packages)
Documented Packages:  62 packages with individual README.md files
Test Specifications:  11,818
Test Assertions:      23,080
Benchmarks:           151
Pending Tests:        18
Skipped Tests:        6
Average Coverage:     75.49%
Packages ≥80%:        71/131 (54.2%)
Packages ≥90%:        43/131 (32.8%)
Go Version:           1.24+ (1.25+ recommended)
Platforms:            Linux, macOS, Windows
Thread Safety:        ✅ Zero race conditions
CI/CD:                GitHub Actions with race detection

Key Features

🌩️ Cloud & Infrastructure

AWS Integration: S3 storage, IAM management, MinIO compatibility (aws)
Artifact Management: GitHub, GitLab, JFrog Artifactory, S3 artifact handling (artifact)
Archive & Compression: Streaming TAR/ZIP with GZIP, BZIP2, LZ4, XZ support (archive)

🌐 Web & Networking

HTTP Server: Pool management with TLS, multi-handler, monitoring, graceful shutdown (httpserver)
HTTP Client: Advanced client with DNS mapping, retries, timeouts (httpcli)
Router: Gin-based routing with auth headers, CORS, request validation (router)
Socket Communication: TCP, UDP, Unix domain socket servers and clients (socket)

💾 Data Management

I/O Utilities: Stream aggregation, multiplexing, progress tracking, delimiters (ioutils)
Database: GORM integration for MySQL, PostgreSQL, SQLite, SQL Server (database)
Cache: In-memory cache with TTL, atomic operations, thread-safe (cache)
File Operations: Bandwidth control, progress tracking, permission management (file)

🔒 Security & Communication

Certificates: TLS certificate management, CA operations, cipher suites (certificates)
Authentication: LDAP integration, OAuth clients, password generation (ldap, oauth, password)
Email: Complete SMTP solution with TLS/STARTTLS, templating, composition, queuing (mail)
FTP: FTP client with connection management (ftpclient)

📊 Monitoring & Logging

Structured Logging: Multi-output (file, syslog, stdout/stderr), field injection, rotation (logger)
Prometheus Metrics: Custom metrics, bloom filters, web metrics endpoints (prometheus)
Health Monitoring: System info, status checks, health endpoints (monitor)
Status Management: Component status tracking, mandatory checks, control (status)

🛠️ Utilities & Helpers

Error Management: Error codes, stack traces, hierarchies, thread-safe pools (errors)
Encoding: AES encryption, SHA256 hashing, hex encoding, remote random reader for HSM (encoding)
Type Utilities: Semantic versioning, byte sizes, extended duration with days, protocols (version, size, duration, network)
Configuration: Component lifecycle orchestration with hot-reload (config, viper), version-aware serialization (retro)

⚡ Concurrency & Control

Atomic Types: Type-safe atomic primitives with default values and type casting (atomic)
Semaphores: Weighted semaphores, WaitGroups with progress tracking (semaphore)
Lifecycle: Start/Stop patterns, ticker management, context control (runner)
Context: Gin context wrappers, enhanced context utilities (context)

🧪 Development Tools

CLI Framework: Cobra extensions with enhanced features (cobra)
Shell: Interactive shell with command management, TTY handling (shell)
Console: Terminal formatting, colored output, progress indicators (console)
Static File Server: Secure static file serving with WAF/IDS/EDR integration, rate limiting, path security (static)

Architecture

Package Organization

The library is organized into 37 top-level packages, each focused on a specific domain:

golib/
├── Cloud & Infrastructure
│   ├── archive/              Archive & compression (TAR, ZIP, GZIP, BZIP2, LZ4, XZ)
│   ├── artifact/             Artifact management (GitHub, GitLab, JFrog, S3)
│   └── aws/                  AWS SDK integration (S3, IAM, MinIO)
│
├── Web & Networking
│   ├── httpcli/              Advanced HTTP client with DNS mapping
│   ├── httpserver/           HTTP/HTTPS server pool with TLS and multi-handler
│   ├── router/               Gin-based router with auth and middleware
│   └── socket/               TCP/UDP/Unix socket servers and clients
│
├── Data Management
│   ├── cache/                In-memory cache with TTL
│   ├── database/             GORM integration and key-value stores
│   ├── file/                 File operations with progress tracking
│   └── ioutils/              I/O utilities (aggregation, multiplexing, delimiters)
│
├── Security & Communication
│   ├── certificates/         TLS certificate management
│   ├── ftpclient/            FTP client
│   ├── ldap/                 LDAP authentication
│   ├── mail/                 Complete SMTP with TLS/STARTTLS, templating, queuing
│   ├── nats/                 NATS messaging
│   ├── oauth/                OAuth clients
│   └── password/             Password generation
│
├── Monitoring & Logging
│   ├── logger/               Structured logging with multiple outputs
│   ├── monitor/              System monitoring and health checks
│   ├── prometheus/           Prometheus metrics integration
│   └── status/               Component status management
│
├── Utilities & Helpers
│   ├── config/               Component lifecycle orchestration with hot-reload
│   ├── duration/             Extended duration with days (1d=24h) and large ranges
│   ├── encoding/             Encryption, hashing, remote random reader (HSM)
│   ├── errors/               Advanced error management
│   ├── network/              Network protocol utilities
│   ├── retro/                Version-aware struct serialization
│   ├── size/                 Byte size arithmetic
│   ├── version/              Semantic versioning
│   └── viper/                Viper configuration wrapper
│
├── Concurrency & Control
│   ├── atomic/               Type-safe atomic primitives with defaults
│   ├── context/              Enhanced context utilities
│   ├── runner/               Lifecycle management (Start/Stop, Ticker)
│   └── semaphore/            Weighted semaphores with WaitGroups and progress
│
└── Development Tools
    ├── cobra/                Cobra CLI extensions
    ├── console/              Terminal formatting
    ├── pprof/                Profiling utilities
    ├── request/              HTTP request helpers
    ├── shell/                Interactive shell
    └── static/               Security-focused static file server with caching

Package Count: 37 top-level, 165 total (including subpackages)

Dependency Model

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  (Your application imports specific golib packages)         │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   High-Level Packages                       │
│  httpserver, router, config, monitor, mail, archive         │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Mid-Level Packages                        │
│  logger, errors, runner, status, database, httpcli          │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Low-Level Packages                        │
│  atomic, context, semaphore, ioutils, encoding              │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Foundation Packages                       │
│  version, size, duration, network, password                 │
└─────────────────────────────────────────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   Go Standard Library                       │
└─────────────────────────────────────────────────────────────┘

Design Principles:

Layered Architecture: Clear separation between application, business, and infrastructure layers
Minimal Coupling: Packages depend on abstractions, not concrete implementations
Interface-Based: Most packages define interfaces for extensibility
Standard Library First: Leverage Go standard library where possible

Installation

Requirements

Go: 1.24 or higher (required for os.OpenRoot API)
Platform: Linux, macOS, or Windows
CGO: Optional (required for race detector during testing)

Quick Setup

# Install entire library
go get github.com/nabbar/golib

# Install specific packages
go get github.com/nabbar/golib/logger
go get github.com/nabbar/golib/archive
go get github.com/nabbar/golib/httpserver
go get github.com/nabbar/golib/errors
go get github.com/nabbar/golib/ioutils

Import in Your Project

package main

import (
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/errors"
    "github.com/nabbar/golib/httpserver"
)

func main() {
    // Use packages as needed
}

Updating

# Update all packages
go get -u github.com/nabbar/golib/...

# Update specific package
go get -u github.com/nabbar/golib/logger

Package Catalog

Detailed list of all packages with coverage statistics and links to documentation.

Total: 62 packages with individual README.md documentation across 165 Go packages.

Note: Many parent packages have multiple documented subpackages:

encoding: 6 documented packages (base + aes, hexa, mux, randRead, sha256) - See encoding/README.md
ioutils: 11 documented packages (base + aggregator, bufferReadCloser, delim, fileDescriptor, ioprogress, iowrapper, mapCloser, maxstdio, multi, nopwritecloser) - See ioutils/README.md
mail: 5 documented packages (base + queuer, render, sender, smtp) - See mail/README.md
monitor: 3 documented packages (base + info, pool) - See monitor/README.md
prometheus: 2 documented packages (base + webmetrics) - See prometheus/README.md
socket: 3 documented packages (base + client, server) - See socket/README.md

The table below lists all 165 Go packages with their test coverage and links to their 62 individual README.md documentation files.

Cloud & Infrastructure

Package	Coverage	Specs	Description	Documentation
archive	8.6%	89	Streaming archive and compression	README
artifact	23.4%	19	Artifact management (GitHub/GitLab/JFrog/S3)	README
artifact/client	98.6%	21	Generic artifact client interface	-
aws	5.4%	220	AWS SDK integration (S3, IAM, MinIO)	README
static	82.6%	229	Security-focused static file server with embed.FS, rate limiting, WAF integration	README

Web & Networking

Package	Coverage	Specs	Description	Documentation
httpcli	71.4%	34	Advanced HTTP client with retries	README
httpcli/dns-mapper	71.7%	26	DNS mapping for HTTP clients	-
httpserver	52.5%	84	HTTP/HTTPS server pool management with TLS, monitoring and multi-handler support	README
httpserver/pool	63.1%	78	Multi-server orchestration and pooling	-
network	75.4%	162	Network utilities and protocol handling	README
network/protocol	98.7%	298	Network protocol constants and helpers	-
router	91.0%	61	Gin-based router with auth	README
router/auth	96.3%	12	Authentication middleware	-
router/authheader	100%	11	Authorization header parsing	-
router/header	83.3%	29	HTTP header utilities	-
socket	No tests	-	Socket communication base	README
socket/client	No tests	-	Socket client base	README
socket/client/tcp	74.0%	119	TCP client implementation	-
socket/client/udp	72.8%	68	UDP client implementation	-
socket/client/unix	76.3%	67	Unix domain socket client	-
socket/client/unixgram	76.8%	65	Unix datagram socket client	-
socket/server	No tests	-	Socket server base	README
socket/server/tcp	84.6%	117	TCP server implementation	-
socket/server/udp	72.0%	18	UDP server implementation	-
socket/server/unix	73.5%	23	Unix domain socket server	-
socket/server/unixgram	70.8%	20	Unix datagram socket server	-

Data Management

Package	Coverage	Specs	Description	Documentation
cache	96.7%	43	In-memory cache with TTL	README
cache/item	96.7%	21	Cache item implementation	-
database/gorm	19.6%	41	GORM integration	README
database/kvdriver	38.4%	20	Key-value store driver	-
database/kvitem	76.4%	33	Key-value item	-
database/kvmap	66.7%	30	Key-value map	-
database/kvtable	65.9%	24	Key-value table	-
file/bandwidth	77.8%	25	Bandwidth-limited I/O	README
file/perm	88.9%	141	File permission utilities	-
file/progress	71.1%	90	File operation progress tracking	-
ioutils	88.2%	31	I/O utilities base	README
ioutils/aggregator	84.9%	115	Thread-safe write aggregator that buffers and serializes concurrent writes	README
ioutils/bufferReadCloser	100%	44	Lightweight wrappers adding io.Closer to bytes.Buffer and bufio types	README
ioutils/delim	98.6%	95	Delimiter-based stream processing	README
ioutils/fileDescriptor	85.7%	28	Cross-platform file descriptor limit management	README
ioutils/ioprogress	84.7%	54	I/O progress tracking	README
ioutils/iowrapper	100%	88	Generic I/O wrappers	README
ioutils/mapCloser	80.8%	82	Thread-safe, context-aware manager for multiple io.Closer instances	README
ioutils/maxstdio	No tests	-	Stdio limit management	README
ioutils/multi	80.8%	112	Thread-safe adaptive multi-writer extending io.MultiWriter	README
ioutils/nopwritecloser	100%	54	Wrapper implementing io.WriteCloser with no-op Close()	README

Security & Communication

Package	Coverage	Specs	Description	Documentation
certificates	44.6%	2	TLS certificate management	README
certificates/auth	73.0%	13	Certificate authentication	-
certificates/ca	64.1%	17	Certificate authority operations	-
certificates/certs	48.4%	2	Certificate utilities	-
certificates/cipher	51.2%	6	Cipher suite management	-
certificates/curves	51.6%	4	Elliptic curve management	-
certificates/tlsversion	54.5%	4	TLS version utilities	-
ftpclient	6.2%	22	FTP client implementation	README
ldap	No tests	-	LDAP authentication	README
mail	No tests	-	Complete email solution with SMTP (TLS/STARTTLS), templating, composition and queuing	README
mail/queuer	90.8%	102	Email queuing with pooling	README
mail/render	89.6%	123	Email template rendering	README
mail/sender	81.4%	252	Email sending utilities	README
mail/smtp	90.1%	104	SMTP client implementation	README
mail/smtp/config	92.7%	222	SMTP configuration	-
mail/smtp/tlsmode	98.8%	165	SMTP TLS mode handling	-
nats	No tests	-	NATS messaging client	-
oauth	No tests	-	OAuth client integration	-
password	84.6%	6	Password generation	README

Monitoring & Logging

Package	Coverage	Specs	Description	Documentation
logger	68.0%	81	Structured logging framework	README
logger/config	85.3%	127	Logger configuration	-
logger/entry	85.1%	119	Log entry management	-
logger/fields	49.2%	49	Log field injection	-
logger/gorm	100%	34	GORM logger integration	-
logger/hashicorp	96.6%	89	Hashicorp logger adapter	-
logger/hookfile	19.6%	22	File output hook	-
logger/hookstderr	100%	30	Stderr output hook	-
logger/hookstdout	100%	30	Stdout output hook	-
logger/hooksyslog	53.5%	20	Syslog output hook	-
logger/hookwriter	90.2%	31	Generic writer hook	-
logger/level	65.9%	42	Log level management	-
monitor	81.9%	103	System monitoring	README
monitor/info	100%	95	System information collection	README
monitor/pool	76.2%	153	Monitor pooling	README
monitor/status	98.4%	181	Status reporting	-
prometheus	60.0%	137	Prometheus metrics	README
prometheus/bloom	94.7%	45	Bloom filter metrics	-
prometheus/metrics	95.5%	179	Custom metrics	-
prometheus/pool	72.5%	74	Prometheus pooling	-
prometheus/types	100%	36	Prometheus type definitions	-
prometheus/webmetrics	No tests	-	Web metrics endpoint	README
status	85.9%	120	Status management	README
status/control	95.0%	102	Status control	-
status/listmandatory	86.0%	29	Mandatory status list	-
status/mandatory	76.1%	55	Mandatory status checks	-

Utilities & Helpers

Package	Coverage	Specs	Description	Documentation
config	61.9%	93	Component lifecycle orchestration with dependency resolution and hot-reload	README
config/components/aws	40.7%	183	AWS component config	-
config/components/database	39.0%	196	Database component config	-
config/components/head	84.6%	185	Header component config	-
config/components/http	71.7%	257	HTTP component config	-
config/components/httpcli	86.0%	137	HTTP client component config	-
config/components/ldap	70.5%	90	LDAP component config	-
config/components/log	88.0%	191	Logger component config	-
config/components/mail	64.8%	68	Mail component config	-
config/components/request	43.3%	35	Request component config	-
config/components/smtp	51.5%	73	SMTP component config	-
config/components/tls	82.1%	171	TLS component config	-
duration	91.5%	179	Extended duration with days support (1d=24h) and arithmetic operations	README
duration/big	91.0%	250	Large durations beyond time.Duration range (seconds precision, ~292B years)	-
encoding	No tests	-	Unified encoding interface with remote random reader for HSM operations	README
encoding/aes	91.5%	126	AES encryption	README
encoding/hexa	89.7%	97	Hexadecimal encoding	README
encoding/mux	81.7%	59	Encoding multiplexer	README
encoding/randRead	81.4%	32	Buffered random reader from remote sources (APIs, HSM) for cryptographic operations	README
encoding/sha256	84.8%	61	SHA256 hashing	README
errors	87.6%	222	Advanced error management	README
errors/pool	100%	83	Error pool management	-
retro	84.2%	156	Version-aware struct serialization for configuration evolution and backward compatibility	README
size	95.4%	352	Byte size arithmetic	README
version	93.8%	173	Semantic versioning	README
viper	73.3%	104	Viper configuration wrapper	README

Concurrency & Control

Package	Coverage	Specs	Description	Documentation
atomic	91.8%	49	Type-safe atomic primitives with default values and type casting helpers	README
context	87.5%	80	Context utilities	README
context/gin	76.9%	77	Gin context wrapper	-
runner	No tests	-	Lifecycle management base	README
runner/startStop	88.8%	42	Start/Stop pattern	-
runner/ticker	90.2%	88	Ticker management	-
semaphore	97.4%	33	Weighted semaphores, WaitGroups and progress tracking with MPB integration	README
semaphore/bar	96.6%	68	Semaphore with progress bar	-
semaphore/sem	100%	66	Semaphore implementation	-

Development Tools

Package	Coverage	Specs	Description	Documentation
cobra	76.7%	156	Cobra CLI extensions	README
console	60.0%	182	Terminal formatting	README
pprof	No tests	-	Profiling utilities	-
request	No tests	-	HTTP request helpers	-
shell	48.4%	120	Interactive shell	README
shell/command	81.8%	93	Shell command management	-
shell/tty	44.7%	126	TTY handling	-

Quick Start

Logging

package main

import (
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/logger/level"
)

func main() {
    // Create logger with stdout output
    log := logger.New(nil)
    log.SetLevel(level.InfoLevel)
    
    // Basic logging
    log.Info("Application started")
    log.Error("An error occurred")
    
    // Structured logging with fields
    log.WithField("user", "john").Info("User logged in")
    log.WithFields(map[string]interface{}{
        "method": "GET",
        "path":   "/api/users",
        "status": 200,
    }).Info("Request processed")
}

HTTP Server

package main

import (
    "context"
    "github.com/nabbar/golib/httpserver"
    "github.com/nabbar/golib/logger"
)

func main() {
    log := logger.New(nil)
    
    // Create HTTP server
    srv := httpserver.New(context.Background(), log)
    srv.SetListenAddress(":8080")
    
    // Add routes
    srv.RegisterHandler("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })
    
    // Start server
    if err := srv.Start(context.Background()); err != nil {
        log.Fatal(err)
    }
    defer srv.Stop()
    
    // Wait for interrupt
    select {}
}

Archive & Compression

package main

import (
    "github.com/nabbar/golib/archive"
    "os"
)

func main() {
    // Create tar.gz archive
    input, _ := os.Open("source-dir")
    output, _ := os.Create("archive.tar.gz")
    defer output.Close()
    
    // Stream compression
    if err := archive.Compress(input, output, "tar", "gzip"); err != nil {
        panic(err)
    }
    
    // Extract archive
    archiveFile, _ := os.Open("archive.tar.gz")
    if err := archive.Extract(archiveFile, "dest-dir"); err != nil {
        panic(err)
    }
}

Error Handling

package main

import (
    "github.com/nabbar/golib/errors"
)

func main() {
    // Create error with code
    err := errors.New("database connection failed").
        SetCode(500).
        AddParent(errors.New("network timeout"))
    
    // Check error
    if err != nil {
        // Get error code
        code := errors.GetCode(err)
        
        // Get full error chain
        chain := errors.GetParent(err)
        
        // Log with stack trace
        println(err.Error())
    }
}

Configuration

package main

import (
    "github.com/nabbar/golib/viper"
    "github.com/nabbar/golib/config"
)

func main() {
    // Load configuration from file
    cfg := viper.New()
    cfg.SetConfigFile("config.yaml")
    cfg.ReadInConfig()
    
    // Access configuration
    port := cfg.GetInt("server.port")
    host := cfg.GetString("server.host")
    
    println("Starting server on", host, ":", port)
}

Performance

Test Suite Metrics

Based on complete coverage analysis with coverage-report.sh:

Total Packages:       165
Packages with Tests:  127 (77.0%)
Packages without Tests: 38 (23.0%)

Test Specifications:  10,964
Test Assertions:      21,470
Benchmarks:           92
Pending Tests:        18

Execution Time:       Variable (cached results shown)
Race Conditions:      0 (verified with -race flag)

Coverage Analysis

Distribution by Coverage Level:

Coverage Range	Count	Percentage	Package Examples
100%	14	11.0%	errors/pool, logger/gorm, router/authheader, semaphore/sem
90-99%	24	18.9%	atomic (91.8%), version (93.8%), size (95.4%)
80-89%	29	22.8%	ioutils (88.2%), mail/queuer (90.8%), static (82.6%), context (87.5%)
70-79%	19	15.0%	cobra (76.7%), viper (73.3%), file/bandwidth (77.8%)
60-69%	10	7.9%	config (61.9%), logger (68.0%), database/kvmap (66.7%)
<60%	31	24.4%	archive (8.6%), aws (5.4%), httpserver (52.5%)

Average Coverage: 73.9% (weighted across all 127 tested packages)

Performance Highlights

High-Performance Packages (>90% coverage):

atomic: 91.8% coverage, 49 specs - Generic atomic operations
mail/smtp/config: 92.7% coverage, 222 specs - SMTP configuration
version: 93.8% coverage, 173 specs - Semantic versioning
size: 95.4% coverage, 352 specs - Byte size arithmetic
prometheus/metrics: 95.5% coverage, 179 specs - Custom metrics

Well-Tested Core Packages:

ioutils: 90.4% average across 10 subpackages, 776 specs
mail: 89.0% average across 6 subpackages, 970 specs
logger: 74.7% base + 85%+ in config/entry, 573 specs
errors: 87.6% base + 100% pool, 305 specs
monitor: 88.5% base + 100% info, 572 specs

Packages Needing Improvement (<40% coverage):

archive (8.6%), aws (5.4%), artifact implementations
database/kvdriver (38.4%), config/components (39-43%)
ftpclient (6.2%), shell/tty (44.7%)

See TESTING.md for detailed test suite documentation.

Use Cases

1. Cloud-Native Microservices

Scenario: Build a microservice handling S3 uploads, monitoring, and structured logging.

import (
    "github.com/nabbar/golib/aws"
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/monitor"
    "github.com/nabbar/golib/prometheus"
)

// Microservice with full observability
type Service struct {
    storage    aws.Client
    log        logger.Logger
    monitor    monitor.Monitor
    metrics    prometheus.Registry
}

Packages Used: aws, logger, monitor, prometheus, httpserver

2. API Gateway with Advanced Routing

Scenario: HTTP API gateway with authentication, rate limiting, and request/response logging.

import (
    "github.com/nabbar/golib/router"
    "github.com/nabbar/golib/httpcli"
    "github.com/nabbar/golib/logger"
)

// Gateway with middleware stack
r := router.New()
r.Use(router.Auth())
r.Use(router.RateLimiter())
r.Use(router.Logging(log))

Packages Used: router, httpcli, logger, context, errors

3. Data Pipeline with Streaming

Scenario: ETL pipeline processing large archives with progress tracking and error handling.

import (
    "github.com/nabbar/golib/archive"
    "github.com/nabbar/golib/ioutils"
    "github.com/nabbar/golib/file/progress"
)

// Stream processing with progress
progress := ioprogress.NewReader(reader, func(n int64) {
    fmt.Printf("Processed: %d bytes\n", n)
})

archive.Extract(progress, destDir)

Packages Used: archive, ioutils, file, errors, logger

4. Distributed Task Queue

Scenario: Background job processing with concurrency control and monitoring.

import (
    "github.com/nabbar/golib/semaphore"
    "github.com/nabbar/golib/runner"
    "github.com/nabbar/golib/status"
)

// Concurrent task executor
sem := semaphore.New(maxWorkers)
for _, task := range tasks {
    sem.Acquire()
    go func(t Task) {
        defer sem.Release()
        processTask(t)
    }(task)
}

Packages Used: semaphore, runner, status, monitor, errors

5. Configuration Management System

Scenario: Multi-environment configuration with validation and hot-reload.

import (
    "github.com/nabbar/golib/config"
    "github.com/nabbar/golib/viper"
)

// Environment-aware config
cfg := config.New()
cfg.Load("config.yaml")
cfg.Watch() // Hot reload on file change

Packages Used: config, viper, logger, errors

Best Practices

✅ DO

Use Structured Logging:

// ✅ GOOD: Structured fields for filtering/analysis
log.WithFields(map[string]interface{}{
    "user_id": userID,
    "action":  "login",
    "ip":      remoteAddr,
}).Info("User authentication")

// ❌ BAD: Unstructured string concatenation
log.Info("User " + userID + " logged in from " + remoteAddr)

Handle Errors Properly:

// ✅ GOOD: Error wrapping with context
if err != nil {
    return errors.New("database query failed").
        AddParent(err).
        SetCode(500)
}

// ❌ BAD: Ignoring errors
result, _ := database.Query()

Leverage Context for Cancellation:

// ✅ GOOD: Context-aware operations
ctx, cancel := context.WithTimeout(parent, 5*time.Second)
defer cancel()

if err := service.Process(ctx, data); err != nil {
    // Handle timeout or cancellation
}

// ❌ BAD: No cancellation support
service.Process(data)

Use Interfaces for Testing:

// ✅ GOOD: Interface-based dependencies
type UserService struct {
    storage Storage // interface
    logger  logger.Logger // interface
}

// ❌ BAD: Concrete dependencies
type UserService struct {
    storage *PostgresDB // concrete type
}

Stream Large Files:

// ✅ GOOD: Streaming with constant memory
reader := ioutils.NewReader(file)
writer := ioutils.NewWriter(dest)
io.Copy(writer, reader)

// ❌ BAD: Loading entire file into memory
data, _ := ioutil.ReadAll(file)
ioutil.WriteFile(dest, data, 0644)

❌ DON'T

Don't Ignore Resource Cleanup:

// ❌ BAD: No cleanup
file, _ := os.Open("data.txt")
data, _ := ioutil.ReadAll(file)

// ✅ GOOD: Proper cleanup
file, err := os.Open("data.txt")
if err != nil {
    return err
}
defer file.Close()

Don't Block Main Goroutine:

// ❌ BAD: Blocking indefinitely
server.Start()

// ✅ GOOD: Non-blocking with graceful shutdown
go server.Start()
<-ctx.Done()
server.Stop()

Don't Ignore Race Conditions:

// ❌ BAD: Shared state without synchronization
var counter int
for i := 0; i < 10; i++ {
    go func() { counter++ }()
}

// ✅ GOOD: Use atomic or mutex
var counter atomic.Int64
for i := 0; i < 10; i++ {
    go func() { counter.Add(1) }()
}

Don't Hardcode Configuration:

// ❌ BAD: Hardcoded values
db := sql.Open("postgres", "postgres://localhost:5432/db")

// ✅ GOOD: External configuration
cfg := config.Load()
db := sql.Open("postgres", cfg.GetString("database.url"))

Don't Skip Error Checking:

// ❌ BAD: Ignoring potential errors
json.Unmarshal(data, &result)

// ✅ GOOD: Always check errors
if err := json.Unmarshal(data, &result); err != nil {
    return errors.New("JSON parsing failed").AddParent(err)
}

Testing

Comprehensive test suite with 10,964 specifications across 127 packages.

See TESTING.md for detailed testing documentation.

Build Configuration

Build Tags

The library supports platform-specific builds using Go build tags:

# Build for specific architecture
go build -tags=386 ./...      # 32-bit
go build -tags=amd64 ./...    # 64-bit

# Platform-specific features
go build -tags=linux ./...
go build -tags=darwin ./...
go build -tags=windows ./...

Build Scripts

Two build helper scripts are provided:

build.386: Build for 32-bit architecture
build.amd64: Build for 64-bit architecture

# Use build scripts
./build.amd64
./build.386

Compile-Time Requirements

Go Version: 1.24+ (required for os.OpenRoot API introduced in Go 1.24)
CGO: Optional (needed for race detector: CGO_ENABLED=1)
Platform: Linux, macOS, Windows (some packages have platform-specific implementations)

Optimization Flags

Recommended build flags for production:

# Optimized production build
go build -ldflags="-s -w" -trimpath ./...

# With race detector (development only, significant performance impact)
CGO_ENABLED=1 go build -race ./...

# Static binary (Linux)
CGO_ENABLED=0 go build -ldflags="-s -w -extldflags '-static'" ./...

Cross-Compilation

# Linux from macOS
GOOS=linux GOARCH=amd64 go build ./...

# Windows from Linux
GOOS=windows GOARCH=amd64 go build ./...

# macOS from Linux
GOOS=darwin GOARCH=amd64 go build ./...

Contributing

Contributions are welcome! Please follow these guidelines:

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
AI Usage Policy
- ❌ Do NOT use AI for implementing package functionality or core logic
- ✅ AI may assist with:
  - Writing and improving tests
  - Documentation and comments
  - Debugging and troubleshooting
- All AI-assisted contributions must be reviewed and validated by humans
Testing
- Add tests for new features
- Use Ginkgo v2 / Gomega for test framework
- Ensure zero race conditions
- Maintain coverage above 80%
Documentation
- Update GoDoc comments for public APIs
- Add examples for new features
- Update README.md if adding packages
- Update TESTING.md if changing test structure
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

Future Enhancements

Potential improvements and new features for consideration:

Test Coverage Improvements

Priority Packages (current coverage <40%):

archive (8.6% → target 80%+)
- Add tests for TAR/ZIP operations
- Stream processing edge cases
- Format detection scenarios
aws (5.4% → target 80%+)
- S3 operations testing
- IAM integration tests
- MinIO compatibility tests
artifact subpackages (6-23% → target 80%+)
- GitHub/GitLab/JFrog client tests
- Authentication scenarios
- Error handling coverage
config/components (39-43% → target 80%+)
- Component configuration validation
- Integration tests
- Edge case handling
database/kvdriver (38.4% → target 80%+)
- Key-value store operations
- Transaction handling
- Concurrent access tests

New Features

High Priority:

Distributed Tracing: OpenTelemetry integration for distributed systems
Service Mesh: Istio/Linkerd compatibility helpers
gRPC Support: gRPC server and client implementations
Event Streaming: Kafka, RabbitMQ integration packages
Circuit Breaker: Resilience patterns for failure handling

Medium Priority:

GraphQL: GraphQL server and client utilities
WebSocket: Enhanced WebSocket support
Rate Limiting: Advanced rate limiting algorithms (token bucket, sliding window)
Caching: Redis integration, distributed caching
Secrets Management: Vault, AWS Secrets Manager integration

Low Priority:

Machine Learning: Model serving utilities
Blockchain: Ethereum, Hyperledger integration
IoT: MQTT protocol support
Mobile: Mobile-specific optimizations

Performance Optimizations

Zero-Copy I/O: Extend zero-copy operations to more packages
SIMD: Leverage SIMD instructions for data processing
Memory Pooling: Reduce allocations in hot paths
Async I/O: io_uring support for Linux
Compilation: Pre-compiled binaries for common platforms

Documentation Enhancements

Interactive Examples: Runnable examples in documentation
Architecture Diagrams: Detailed architecture visualizations
Migration Guides: Upgrade guides between major versions
Best Practices: Extended best practices documentation
Video Tutorials: Video content for common use cases

Tooling Improvements

CLI Tool: golib command-line tool for scaffolding
Code Generator: Generate boilerplate for common patterns
Linter: Custom linter for golib best practices
Performance Profiler: Built-in profiling utilities
Dependency Analyzer: Analyze package dependencies

Community & Ecosystem

Plugin System: Extensible plugin architecture
Marketplace: Community-contributed packages
Templates: Project templates for common scenarios
Integration Tests: Comprehensive integration test suite
Benchmarking Suite: Cross-package performance benchmarks

Note: These enhancements are suggestions based on current gaps and industry trends. Actual implementation priorities depend on community feedback and real-world usage patterns.

Resources

Internal Documentation

GoDoc - Complete API documentation
TESTING.md - Test suite documentation
CONTRIBUTING.md - Contribution guidelines
SECURITY.md - Security policy

Package Documentation

Individual package READMEs available in each subdirectory.

External References

Go Documentation - Official Go documentation
Effective Go - Go best practices
Go Blog - Official Go blog

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.

Maintained by: Nicolas JUHEL
Repository: github.com/nabbar/golib
Version: See releases

Name		Name	Last commit message	Last commit date
Latest commit History 535 Commits
.github		.github
archive		archive
artifact		artifact
atomic		atomic
aws		aws
cache		cache
certificates		certificates
cobra		cobra
config		config
console		console
context		context
database		database
duration		duration
encoding		encoding
errors		errors
file		file
ftpclient		ftpclient
httpcli		httpcli
httpserver		httpserver
ioutils		ioutils
ldap		ldap
logger		logger
mail		mail
monitor		monitor
nats		nats
network		network
oauth		oauth
password		password
pidcontroller		pidcontroller
pprof		pprof
prometheus		prometheus
request		request
retro		retro
router		router
runner		runner
semaphore		semaphore
shell		shell
size		size
socket		socket
static		static
status		status
version		version
viper		viper
.gitignore		.gitignore
.golangci.yml		.golangci.yml
CHANGELOG		CHANGELOG
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
build.386		build.386
build.amd64		build.amd64
cluster.old.tar.gz		cluster.old.tar.gz
coverage-report.sh		coverage-report.sh
go.mod		go.mod

License

nabbar/golib

Folders and files

Latest commit

History

Repository files navigation

golib

Table of Contents

Overview

Design Philosophy

Repository Statistics

Key Features

🌩️ Cloud & Infrastructure

🌐 Web & Networking

💾 Data Management

🔒 Security & Communication

📊 Monitoring & Logging

🛠️ Utilities & Helpers

⚡ Concurrency & Control

🧪 Development Tools

Architecture

Package Organization

Dependency Model

Installation

Requirements

Quick Setup

Import in Your Project

Updating

Package Catalog

Cloud & Infrastructure

Web & Networking

Data Management

Security & Communication

Monitoring & Logging

Utilities & Helpers

Concurrency & Control

Development Tools

Quick Start

Logging

HTTP Server

Archive & Compression

Error Handling

Configuration

Performance

Test Suite Metrics

Coverage Analysis

Performance Highlights

Use Cases

1. Cloud-Native Microservices

2. API Gateway with Advanced Routing

3. Data Pipeline with Streaming

4. Distributed Task Queue

5. Configuration Management System

Best Practices

✅ DO

❌ DON'T

Testing

Build Configuration

Build Tags

Build Scripts

Compile-Time Requirements

Optimization Flags

Cross-Compilation

Contributing

Future Enhancements

Test Coverage Improvements

New Features

Performance Optimizations

Documentation Enhancements

Tooling Improvements

Community & Ecosystem

Resources

Internal Documentation

Package Documentation

External References

AI Transparency

License

About

Resources

License

Packages