common

go-common

A shared Go utility library for building HTTP APIs. Provides query parameter parsing, JSON request/response handling, structured logging, and request validation.

Installation

go get github.com/wispberry-tech/go-common

import common "github.com/wispberry-tech/go-common"

HTTP Utilities

Query Parameter Parsing

Parse query parameters with type safety and default values. All parsers return the default when the key is missing or the value is invalid.

// Integers
page := common.ParseQueryInt(r, "page", 1)           // ?page=3 → 3
id := common.ParseQueryInt64(r, "id", 0)              // ?id=9223372036854775807 → 9223372036854775807

// Floats
price := common.ParseQueryFloat64(r, "price", 0.0)    // ?price=19.99 → 19.99

// Booleans — accepts true/1/yes and false/0/no (case-insensitive)
active := common.ParseQueryBool(r, "active", false)    // ?active=yes → true

// Timestamps — expects RFC3339 format
since := common.ParseQueryTime(r, "since")             // ?since=2024-01-15T10:30:00Z → time.Time

// Optional strings — returns *string (nil when missing)
name := common.ParseQueryStringPtr(r, "name")          // ?name=alice → &"alice", missing → nil

// String slices — supports repeated keys
tags := common.ParseQueryStringSlice(r, "tag")         // ?tag=go&tag=rust → ["go", "rust"]

Pagination

Parse limit and offset query parameters with clamping.

// Reads ?limit=50&offset=10, clamps limit to [1, maxLimit], offset to >= 0
p := common.ParsePaginationParams(r, 20, 100) // defaultLimit=20, maxLimit=100
p.Limit  // 50
p.Offset // 10

JSON Responses

All responses are wrapped in a ResponseEnvelope with data, error, and meta fields.

// Success response — {"data": {"id": 1, "name": "alice"}}
common.WriteJSONResponse(w, http.StatusOK, user)

// Error response — {"error": {"code": "NOT_FOUND", "message": "User not found"}}
common.WriteJSONError(w, http.StatusNotFound, common.ErrCodeNotFound, "User not found", nil)

// Error with details — {"error": {"code": "VALIDATION_ERROR", "message": "...", "details": [...]}}
common.WriteJSONError(w, http.StatusBadRequest, common.ErrCodeValidationError, "Invalid input", details)

Error Code Constants

Pre-defined error codes for consistent API responses:

Reading Request Bodies

var req CreateUserRequest
if err := common.ReadJSONBody(r, &req); err != nil {
    common.WriteJSONError(w, http.StatusBadRequest, common.ErrCodeInvalidJSON, "Invalid JSON body", nil)
    return
}

Logging

Structured, colorized logging built on charmbracelet/log.

Initialization

Call InitializeLogger once at startup. Options override defaults (info level, timestamps enabled, caller reporting enabled, 15:04:05 time format).

// Use defaults
common.InitializeLogger()

// Or customize with options
common.InitializeLogger(
    common.WithLevel("debug"),
    common.WithTimeFormat("2006-01-02 15:04:05"),
    common.WithCaller(false),
    common.WithTimestamp(true),
)

Log Messages

Structured logging with key-value pairs:

common.LogInfo("User logged in", "user_id", 123, "ip", "10.0.0.1")
common.LogError("Database error", "error", err, "query", "SELECT ...")
common.LogWarn("Rate limit approaching", "requests", 950, "limit", 1000)
common.LogDebug("Cache hit", "key", "user:123")

Formatted logging:

common.LogInfof("Processing %d items", count)
common.LogErrorf("Failed to connect to %s: %v", host, err)
common.LogWarnf("Retrying in %s", backoff)
common.LogDebugf("Query took %dms", elapsed)

Change Log Level at Runtime

common.SetLogLevel("debug") // "debug", "info", "warn", "error"

// Convenience toggles
common.EnableDebugLogging()
common.DisableDebugLogging()

Context-Aware Logging

Attach a logger to a context for request-scoped logging:

// Store logger in context
ctx := common.WithContext(r.Context(), logger)

// Retrieve later in the call chain
logger := common.FromContext(ctx)

Validation

Request validation using go-playground/validator, with automatic conversion of validation errors to API-friendly responses.

Basic Usage

Use the global Validate instance to validate structs with validate tags:

type CreateUserRequest struct {
    Email    string `json:"email" validate:"required,email"`
    Name     string `json:"name" validate:"required,min=2,max=100"`
    Password string `json:"password" validate:"required,min=8"`
}

if err := common.Validate.Struct(req); err != nil {
    resp := common.FormatValidationErrors(err)
    common.WriteJSONError(w, http.StatusBadRequest, common.ErrCodeValidationError, resp.Error, resp.Details)
    return
}

This produces a response like:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {"field": "email", "message": "email must be a valid email address", "value": "notanemail"},
      {"field": "password", "message": "password must be at least 8 characters long", "value": "short"}
    ]
  }
}

Custom Display Names with Struct Tags

Use the display struct tag to control how field names appear in error messages. Pass the struct to FormatValidationErrorsFor to enable tag lookup:

type CreateUserRequest struct {
    Email string `json:"email" validate:"required,email" display:"Email Address"`
    Age   int    `json:"age" validate:"required,gte=18" display:"Your Age"`
}

if err := common.Validate.Struct(req); err != nil {
    resp := common.FormatValidationErrorsFor(err, req) // pass the struct for display tag lookup
    // → "Email Address must be a valid email address"
    // → "Your Age must be greater than or equal to 18"
}

Without display tags, field names are derived by splitting camelCase (e.g., ClientUUID becomes Client UUID).

Supported Validation Tags

FormatValidationErrors generates human-readable messages for these validation tags:

Dependencies

• charmbracelet/log — Structured, colorized logging
• charmbracelet/lipgloss — Log styling
• go-playground/validator/v10 — Struct validation

License

GPL-3.0