Common Modules Reference

This skill provides detailed usage instructions for all modules in github.com/weedbox/common-modules.

Module Index

Core

HTTP

Database

Messaging

Scheduling

Cache

Utilities

⚠️ Critical Rules

Source of Truth — Do NOT Fetch from GitHub

This file and its sub-files (modules/*.md) are the complete reference for weedbox/common-modules. They contain all necessary code examples, configuration guides, and dependency injection patterns. DO NOT browse github.com/weedbox/common-modules to look up source code.

Use Interface Types, NOT Concrete Implementations

When referencing common-modules in Params, you MUST use interface types:

// ✅ Correct - use interface
type Params struct {
    weedbox.Params
    Database database.DatabaseConnector  // interface type
}

// ❌ Wrong - using concrete implementation
type Params struct {
    weedbox.Params
    Database *sqlite_connector.SQLiteConnector  // concrete type
}

Common-modules Do NOT Need name Tag (Single-Load Default)

When a single connector / module is loaded, inject it without a name tag:

// ✅ Correct
Database   database.DatabaseConnector
HTTPServer *http_server.HTTPServer

// ❌ Wrong - do not add a name tag for single-load modules
Database   database.DatabaseConnector `name:"database"`
HTTPServer *http_server.HTTPServer    `name:"http_server"`

Exception — multi-load DatabaseConnector: when you load sqlite_connector.Module("cache") and postgres_connector.Module("main") into the same fx.App, each registers itself as name:"<scope>" and consumers MUST disambiguate with the name tag:

type Params struct {
    fx.In
    Cache database.DatabaseConnector `name:"cache"` // sqlite
    Main  database.DatabaseConnector `name:"main"`  // postgres
}

The first connector loaded in the process also claims the unnamed default slot, so existing single-load code keeps working. See database.md for full details and the fxmodule.ResetClaim test caveat.

Pick Multi-Instance-Safe Backends for Production

Production runs multiple replicas. Two modules in this library are single-node only: scheduler mode = "gorm" (every replica fires every job) and the embedded nats_jetstream_server (development / single-node tool). With more than one replica, use scheduler mode = "postgres" or "nats", an external NATS cluster via nats_connector, postgres_connector instead of sqlite_connector, and redis_connector for cross-instance shared state. Full decision table: root skill § Design for Multi-Instance Deployment by Default.

Quick Start

Installation

go get github.com/weedbox/common-modules

Basic Application Setup

Important:

• configs.NewConfig() automatically reads config.toml from current directory or ./configs/
• Use fx.New().Run() to start the application (not weedbox.Run())

package main

import (
    "os"

    "github.com/spf13/cobra"
    "github.com/weedbox/common-modules/configs"
    "github.com/weedbox/common-modules/daemon"
    "github.com/weedbox/common-modules/http_server"
    "github.com/weedbox/common-modules/logger"
    "go.uber.org/fx"
)

var config *configs.Config

func main() {
    rootCmd := &cobra.Command{
        Use: "myapp",
        RunE: func(cmd *cobra.Command, args []string) error {
            modules, _ := initModules()
            app := fx.New(modules...)
            app.Run()
            return nil
        },
    }

    // Initialize config - automatically reads config.toml
    config = configs.NewConfig("MYAPP")

    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

func initModules() ([]fx.Option, error) {
    return []fx.Option{
        // Phase 1: Preload
        fx.Supply(config),
        logger.Module(),

        // Phase 2: Load
        http_server.Module("http_server"),

        // Phase 3: After (daemon must be last)
        daemon.Module("daemon"),
    }, nil
}

Module Loading Order

Modules should be loaded in three phases:

Important: The daemon module must be placed last because it marks the service as ready after all other modules initialize. When post-start / pre-stop hooks are needed, place lifecycle right before daemon so readiness flips only after the PostStart phase completes — see lifecycle.md.

Configuration

All modules support configuration via:

1. TOML files - Structured configuration
2. Environment variables - Override settings per environment

TOML Example

[http_server]
host = "0.0.0.0"
port = 8080
mode = "release"

[database]
host = "localhost"
port = 5432
dbname = "myapp"
user = "postgres"
password = "secret"

[nats]
host = "nats://localhost:4222"

[redis]
host = "localhost"
port = 6379

[mailer]
host = "smtp.gmail.com"
port = 587
tls = true

[swagger]
enabled = true
base_path = "/swagger"
title = "API Reference"

Environment Variables

Environment variables use the prefix defined in configs.NewConfig():

# With prefix "MYAPP"
export MYAPP_HTTP_SERVER_PORT=8080
export MYAPP_DATABASE_HOST=localhost
export MYAPP_DATABASE_PASSWORD=secret

Dependency Injection

Modules are injected via Uber Fx parameter structs:

type Params struct {
    fx.In
    Logger      *zap.Logger
    HTTPServer  *http_server.HTTPServer
    Database    database.DatabaseConnector
    NATS        *nats_connector.NATSConnector
    Redis       *redis_connector.RedisConnector
    Mailer      *mailer.Mailer
    Swagger     *swagger.Swagger
}

Related Skills

• project-dev - Project structure and application setup
• module-dev - Custom module development
• user-modules - User management, authentication, and RBAC modules