common

codefloe/common

A high-performance Go library for parsing environment variables into structs using struct tags, with pre-built CI/CD environment variable bindings.

Features

• ⚡ High Performance: Reflection-based field mapping is cached per type; hot-path operations use direct unsafe.Pointer arithmetic
• 🎯 Type Safe: Support for 15+ basic types including pointers, time.Duration, and slices
• 📦 JSON Objects: Parse JSON environment variables directly into Go structs with the object property
• 🔗 Embedded Structs: Automatic traversal of anonymous struct fields
• 🚀 Zero Allocation (scalars): Scalar field assignments are zero-allocation
• 📋 CI/CD Ready: Pre-defined environment bindings for standard CI/CD platforms

Installation

go get codefloe.com/actions/common

Table of Contents

• Quick Start
• ParseEnvironment
  • Supported Types
  • Pointer Types
  • JSON Objects
  • String Slices
  • Embedded Structs
  • Behavior Notes
• CI Environment
• Performance
• Examples
• License

Quick Start

Using Pre-defined CI Environment

package main

import (
    "fmt"
    "codefloe.com/actions/common"
)

func main() {
    env := common.NewEnvironment()

    fmt.Println("Repository:", env.Repo)
    fmt.Println("Branch:", env.CommitBranch)
    fmt.Println("Pipeline #:", env.PipelineNumber)
    fmt.Println("Full environment:", env) // JSON representation
}

Parsing Custom Configuration

package main

import (
    "time"
    "codefloe.com/actions/common"
)

type AppConfig struct {
    Host    string        `env:"APP_HOST"`
    Port    int           `env:"APP_PORT"`
    Debug   bool          `env:"APP_DEBUG"`
    Timeout time.Duration `env:"APP_TIMEOUT"`
}

func main() {
    var cfg AppConfig
    common.ParseEnvironment(&cfg)
    // cfg is now populated from environment variables
}

ParseEnvironment

ParseEnvironment(dst any) populates struct fields from environment variables using the env struct tag.

How it works:

1. Struct metadata is analyzed via reflection (done once and cached per type)
2. Environment variables are read via os.LookupEnv()
3. Values are parsed based on field type and written via direct pointer arithmetic
4. Subsequent calls use the cached metadata with zero reflection overhead

Supported Types

Duration examples: 100ms, 30s, 2m30s, 1h

Pointer Types

Pointer variants of all basic types are supported. This allows distinguishing between "not set" (nil) and "zero value":

type Config struct {
    // Value types: missing env var → zero value
    Name    string `env:"APP_NAME"`    // unset → ""
    Port    int    `env:"APP_PORT"`    // unset → 0
    Debug   bool   `env:"APP_DEBUG"`   // unset → false

    // Pointer types: missing env var → nil
    Verbose *bool  `env:"APP_VERBOSE"`   // unset → nil
    Workers *int   `env:"APP_WORKERS"`   // unset → nil
    Secret  *string `env:"APP_SECRET"`   // unset → nil
}

JSON Objects

Parse JSON environment variables directly into structs, maps, or slices using the object property:

type DatabaseConfig struct {
    Host     string `json:"host"`
    Port     int    `json:"port"`
    Username string `json:"username"`
}

type AppConfig struct {
    Name string            `env:"APP_NAME"`
    DB   DatabaseConfig    `env:"DB_CONFIG,object"`    // ← object property
    Features map[string]interface{} `env:"FEATURES,object"`
    AllowedHosts []string `env:"ALLOWED_HOSTS,object"`
}

Environment:

export APP_NAME=MyApp
export DB_CONFIG='{"host":"localhost","port":5432,"username":"admin"}'
export FEATURES='{"auth":true,"cache":false,"ratelimit":10}'
export ALLOWED_HOSTS='["localhost","127.0.0.1","api.example.com"]'

Result:

var cfg AppConfig
common.ParseEnvironment(&cfg)

// cfg.DB is now populated from JSON in DB_CONFIG
fmt.Println(cfg.DB.Host)  // "localhost"
fmt.Println(cfg.DB.Port)  // 5432

// cfg.Features contains parsed JSON object
fmt.Println(cfg.Features["auth"])  // true

Key behaviors:

• Invalid JSON silently fails (field remains unchanged)
• Missing environment variable leaves field unchanged
• Works with any struct type, map, slice, or primitive that implements json.Unmarshaler
• When object is specified, the field is treated as a complete JSON unit (no inner field recursion)

String Slices

String slices support three formats:

# Format 1: Single value
APP_TAGS=single

# Format 2: Comma-separated
APP_TAGS=a,b,c,d

# Format 3: Comma-separated with brackets
APP_TAGS=[a,b,c,d]

All three formats parse to []string{"..."}

Embedded Structs

Anonymous (embedded) struct fields are traversed automatically, exposing their env-tagged fields:

type BaseConfig struct {
    Name string `env:"APP_NAME"`
    Port int    `env:"APP_PORT"`
}

type ServerConfig struct {
    BaseConfig  // ← fields automatically exposed
    TLS bool    `env:"SERVER_TLS"`
}

var cfg ServerConfig
common.ParseEnvironment(&cfg)

// cfg.Name comes from APP_NAME
// cfg.Port comes from APP_PORT
// cfg.TLS comes from SERVER_TLS

Important: If an embedded struct field has an env tag with object property, it's treated as JSON data and not recursively processed.

Behavior Notes

• Skipped fields: Fields without an env tag or with env:"-" are ignored
• Missing variables: If an env var is not set, the field is left untouched (preserves initialization)
• Parse errors: If parsing fails (e.g., "abc" for int), the field retains its current value
• Nil on unset: Only pointer-type fields become nil when env var is not set; value types retain zero values

CI Environment

NewEnvironment() returns a *Environment struct pre-populated with standard CI/CD variables. The struct covers these variable groups:

Example

env := common.NewEnvironment()

// General
fmt.Println(env.Repo)              // e.g., "owner/repo"
fmt.Println(env.RepoPrivate)       // e.g., true

// Commit
fmt.Println(env.CommitSHA)         // e.g., "abc123..."
fmt.Println(env.CommitBranch)      // e.g., "main"
fmt.Println(env.CommitMessage)     // commit message

// Pipeline
fmt.Println(env.PipelineNumber)    // e.g., 42
fmt.Println(env.PipelineEvent)     // e.g., []string{"push"}

// System
fmt.Println(env.SystemName)        // e.g., "woodpecker"
fmt.Println(env.ForgeType)         // e.g., "github"

Performance

Caching Strategy

Struct metadata is compiled once via reflection per unique struct type and cached globally in a sync.Map. This means:

• First call: ~microseconds (reflection overhead)
• Subsequent calls: nanoseconds (cached metadata)

Benchmark Results

BenchmarkParseEnvironment-20    ~340,000 ops    ~3.3 µs/op    1104 B/op    3 allocs/op

Allocation breakdown:

• 3 allocations from []string fields split via strings.Split() (PipelineEvent, PipelineFiles)
• 0 allocations for all scalar field assignments (due to direct pointer writes)

Optimization Details

On the hot path, ParseEnvironment:

1. Retrieves cached field metadata (lock-free read from sync.Map)
2. Reads environment variables via os.LookupEnv() (OS call)
3. Writes parsed values via unsafe pointer arithmetic (direct memory write)
4. Zero reflection calls after first invocation

This design makes it suitable for high-frequency parsing scenarios.

Examples

Example 1: Web Server Configuration

package main

import (
    "log"
    "codefloe.com/actions/common"
)

type ServerConfig struct {
    Host    string        `env:"SERVER_HOST"`
    Port    int           `env:"SERVER_PORT"`
    TLS     bool          `env:"SERVER_TLS"`
    Timeout time.Duration `env:"SERVER_TIMEOUT"`
}

func main() {
    var cfg ServerConfig
    common.ParseEnvironment(&cfg)

    log.Printf("Server: %s:%d (TLS=%v, Timeout=%v)",
        cfg.Host, cfg.Port, cfg.TLS, cfg.Timeout)
}

Environment:

SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_TLS=true
SERVER_TIMEOUT=30s

Example 2: Database with JSON Configuration

type DatabaseConfig struct {
    Host     string `json:"host"`
    Port     int    `json:"port"`
    Username string `json:"username"`
    Password string `json:"password"`
}

type AppConfig struct {
    AppName string           `env:"APP_NAME"`
    DB      DatabaseConfig   `env:"DB_CONFIG,object"`
    Debug   bool             `env:"DEBUG"`
}

func main() {
    var cfg AppConfig
    common.ParseEnvironment(&cfg)

    // Connect with cfg.DB.Host, cfg.DB.Port, etc.
}

Environment:

APP_NAME=MyService
DB_CONFIG='{"host":"db.local","port":5432,"username":"admin","password":"secret"}'
DEBUG=false

Example 3: Multiple Environments with Embedded Structs

type CommonConfig struct {
    Name string `env:"APP_NAME"`
    Env  string `env:"APP_ENV"`
}

type ProductionConfig struct {
    CommonConfig
    LogLevel string   `env:"LOG_LEVEL"`
    Replicas int      `env:"REPLICAS"`
}

func main() {
    var cfg ProductionConfig
    common.ParseEnvironment(&cfg)

    fmt.Printf("App: %s (env=%s, level=%s, replicas=%d)\n",
        cfg.Name, cfg.Env, cfg.LogLevel, cfg.Replicas)
}

Example 4: Feature Flags via JSON

type FeatureFlags struct {
    Flags map[string]bool `env:"FEATURE_FLAGS,object"`
}

func main() {
    var cfg FeatureFlags
    common.ParseEnvironment(&cfg)

    if cfg.Flags["newUI"] {
        // Use new UI
    }
}

Environment:

FEATURE_FLAGS='{"newUI":true,"betaAPI":false,"darkMode":true}'

License

Apache License 2.0. See LICENSE for details.