foundation

README

foundation

Shared Go libraries for Vortex fintech services.

Packages

Package	Description
contactutil	Contact normalization (email, phone E.164)
domain	Domain primitives for event-driven flows
domainutil	Revision-based consistency, UTC helpers
errors	Transport-agnostic error model (HTTP/gRPC)
geo	Country code normalization (ISO 3166-1 alpha-2)
hash	Deterministic hashing for idempotency keys
idutil	Type-safe UUID v7 identifiers with generics
logger	Zap-based structured logger with tracing
logutil	Log-safe output sanitization
netutil	Timeout sanitization for network clients
piiutil	PII masking for logs and responses
retry	Retry helpers for transient failures
textutil	Text canonicalization and validation
timeutil	Time abstraction for deterministic tests
validator	Request validation with fintech rules

Quick Start

import (
    "github.com/vortex-fintech/go-lib/foundation/logger"
    "github.com/vortex-fintech/go-lib/foundation/errors"
    "github.com/vortex-fintech/go-lib/foundation/validator"
    "github.com/vortex-fintech/go-lib/foundation/piiutil"
)

func main() {
    // Initialize logger
    log, err := logger.New("payment-service", "production")
    if err != nil {
        panic(err)
    }
    defer log.SafeSync()

    // Validate request
    if errs := validator.Validate(req); errs != nil {
        log.Warnw("validation failed", "errors", errs)
        errors.ValidationFields(errs).ToHTTP(w)
        return
    }

    // Log with masked PII
    log.Infow("payment processed",
        "email", piiutil.MaskEmail(user.Email),
        "phone", piiutil.MaskPhone(user.Phone),
    )
}

By Category

Core Infrastructure

Package	Purpose
logger	Structured logging with trace_id/request_id
errors	Unified error model across HTTP/gRPC
validator	Request validation

Domain & Events

Package	Purpose
domain	Event primitives, EventBuffer
domainutil	Revision CAS, UTC time helpers
idutil	Typed identifiers for domain entities

Data Handling

Package	Purpose
contactutil	Normalize email/phone
textutil	Text canonicalization
geo	Country code normalization
hash	Idempotency key hashing

Security & Privacy

Package	Purpose
piiutil	Mask PII in logs/responses
logutil	Sanitize sensitive fields

Networking & Reliability

Package	Purpose
retry	Exponential backoff, permanent errors
netutil	Timeout sanitization

Testing Utilities

Package	Purpose
timeutil	FrozenClock, deterministic time

Common Patterns

Service Bootstrap

log, err := logger.New("service-name", env)
if err != nil {
    return fmt.Errorf("bootstrap logger: %w", err)
}
defer log.SafeSync()

Request Validation

if errs := validator.Validate(req); errs != nil {
    return errors.ValidationFields(errs)
}

Error Handling

account, err := repo.GetAccount(ctx, id)
if err != nil {
    return errors.NotFoundID("account", id)
}

PII Logging

log.Infow("user action",
    "email", piiutil.MaskEmail(user.Email),
    "phone", piiutil.MaskPhone(user.Phone),
)

Deterministic Testing

frozen := timeutil.NewFrozenClock(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC))
restore := timeutil.WithDefault(frozen)
defer restore()

Testing

# Run all tests
go test -tags unit ./foundation/...

# Run with race detector
go test -race -tags unit ./foundation/...