go_webmods

README

Golang Web Modules

Common solution collection for quickly setting up Golang web applications. This library provides a modular plugin architecture with factory functions and config-driven initialization for common web application components.

📚 Documentation

Full API Documentation on pkg.go.dev →

🚀 Quick Start

Installation

go get github.com/poly-workshop/go-webmods

Basic Usage

package main

import (
    "log/slog"
    "github.com/poly-workshop/go-webmods/app"
    gormclient "github.com/poly-workshop/go-webmods/gormclient"
)

func main() {
    // Initialize application with configuration
    app.SetCMDName("myapp")
    app.Init(".")  // Loads config from ./configs/

    // Initialize database
    db := gormclient.NewDB(gormclient.Config{
        Driver:   "postgres",
        Host:     "localhost",
        Port:     5432,
        Username: "user",
        Password: "password",
        DbName:   "mydb",
        SSLMode:  "disable",
    })

    slog.Info("Application started successfully")
    _ = db
}

📦 Packages

app

Core application utilities including:

• Layered configuration management (Viper)
• Structured logging with context propagation (slog)
• Application initialization helpers

gormclient

Database client factory supporting:

• PostgreSQL
• MySQL
• SQLite
• Connection pooling configuration

mongoclient

MongoDB client factory using the v2 driver:

• MongoDB Atlas support
• Connection pooling and timeouts
• Ping verification on startup

redisclient

Redis client with:

• Single-node and cluster mode support
• Two-level caching (local + distributed)
• Automatic cache invalidation via pub/sub

kafkaclient

Kafka client helpers with:

• Reader factory (consumer group or partition)
• Writer factory with configurable batching and acknowledgements

objectstorage

Unified object storage interface supporting:

• Local filesystem
• MinIO / S3-compatible storage
• Volcengine TOS

grpcutils

gRPC server interceptors for:

• Structured logging
• Request ID generation and propagation
• Context-aware tracing

smtpmailer

SMTP email client with:

• TLS support
• HTML and plain text emails
• Multiple recipients support

🏗️ Architecture Patterns

Factory Pattern

Every component uses a Config struct and factory function:

component := package.NewComponent(package.Config{...})

Provider Pattern

Multi-backend support with unified interfaces:

storage, err := objectstorage.NewObjectStorage(objectstorage.Config{
    ProviderType: objectstorage.ProviderLocal,
    ProviderConfig: objectstorage.ProviderConfig{
        BasePath: "/data",
    },
})

Context-Aware Logging

Structured logging with automatic context propagation:

ctx = app.WithLogAttrs(ctx, slog.String("user_id", "123"))
slog.InfoContext(ctx, "User logged in") // Includes user_id automatically

⚙️ Configuration

Configuration uses Viper with layered loading:

1. configs/default.yaml - Base configuration
2. configs/{MODE}.yaml - Environment-specific overrides
3. Environment variables - Final overrides (using __ separator)

Example configs/default.yaml:

log:
  level: info
  format: tint

database:
  driver: postgres
  host: localhost
  port: 5432
  username: user
  password: pass
  name: mydb
  sslmode: disable

Set environment mode:

export MODE=production  # Loads configs/production.yaml

Override with environment variables:

export LOG__LEVEL=debug
export DATABASE__HOST=prod-db

📖 Examples

See the examples in pkg.go.dev for detailed usage examples of each package.

🧪 Development

Run Tests

go test ./...

Format Code

make fmt

Lint Code

make lint

📄 License

This repo is granted under the MIT License. Feel free to use it in your projects.

Documentation

Overview

Package go-webmods provides a collection of common web application components for Go services. It follows a modular plugin architecture where each package provides factory functions and config-driven initialization.

Overview

This library includes the following packages:

• app: Core application utilities for configuration, logging, and context management
• gormclient: Database client factory supporting PostgreSQL and SQLite
• redisclient: Redis client with caching support and cluster mode
• kafkaclient: Kafka client factories for readers and writers
• objectstorage: Multi-provider object storage interface (local, MinIO, Volcengine TOS)
• grpcutils: gRPC middleware and interceptors for logging and request ID tracking
• smtpmailer: SMTP email sender with TLS support

Installation

To install the package, use:

go get github.com/poly-workshop/go-webmods

Quick Start

The typical usage pattern follows these steps:

1. Initialize the application with configuration:

import "github.com/poly-workshop/go-webmods/app"

func main() {
    app.Init("/path/to/workdir") // Loads configs from workdir/configs/
    // ... rest of application
}

2. Initialize components using their factory functions:

import gormclient "github.com/poly-workshop/go-webmods/gormclient"

db := gormclient.NewDB(gormclient.Config{
    Driver:   "postgres",
    Host:     "localhost",
    Port:     5432,
    Username: "user",
    Password: "pass",
    DbName:   "dbname",
    SSLMode:  "disable",
})

Configuration

The app package uses Viper for layered configuration:

• default.yaml: Default configuration
• {MODE}.yaml: Environment-specific configuration (e.g., development.yaml, production.yaml)
• Environment variables: Override with LOG__LEVEL, DB__HOST, etc. (using __ separator)

Set the MODE environment variable to control which config file is loaded:

export MODE=production

Architecture Patterns

Factory Pattern: Every component uses a Config struct and factory function:

component := package.NewComponent(package.Config{...})

Provider Pattern: Multi-backend support (e.g., object storage):

storage, err := objectstorage.NewObjectStorage(objectstorage.Config{
    ProviderType: objectstorage.ProviderLocal,
    ProviderConfig: objectstorage.ProviderConfig{
        BasePath: "/data",
    },
})

Context-Aware Logging: Structured logging with context propagation:

ctx = app.WithLogAttrs(ctx, slog.String("user_id", "123"))
slog.InfoContext(ctx, "User logged in") // Automatically includes user_id

Example Application Structure

A typical application using go-webmods might look like:

package main

import (
    "log/slog"
    "github.com/poly-workshop/go-webmods/app"
    gormclient "github.com/poly-workshop/go-webmods/gormclient"
    redisclient "github.com/poly-workshop/go-webmods/redisclient"
)

func main() {
    // Initialize application
    app.SetCMDName("myapp")
    app.Init(".")

    // Initialize database
    db := gormclient.NewDB(gormclient.Config{
        Driver: "sqlite",
        DbName: "data/app.db",
    })

    // Initialize Redis
    rdb := redisclient.NewRDB(redisclient.Config{
        Urls:     []string{"localhost:6379"},
        Password: "",
    })

    slog.Info("Application started successfully")
    // ... rest of application logic
}

License

This project is licensed under the MIT License.