altiquum-core

altiquum-core is the flagship repository of the ALTIQUUM organization, establishing shared engineering primitives and conventions for our distributed systems, infrastructure, and AI engineering services.

We prioritize correctness, simplicity, robustness, and observability. This library has zero external dependencies and is built on top of Go's robust standard library.

---

Technical Overview & Primitives

1. Robust Error Handling (errors)

Standardized errors with machine-readable error codes and stack trace capture. Chaining is supported via Go's standard wrapping mechanism (%w).

• Codes: ErrorCodeInternal, ErrorCodeInvalidArgument, ErrorCodeNotFound, ErrorCodeUnauthorized, ErrorCodePermissionDenied, ErrorCodeDeadlineExceeded, etc.
• Stack Traces: Recorded automatically when the error is initialized via errors.New or errors.Errorf.

2. Context-Aware Structured Logging (logging)

Built on top of Go's standard log/slog package.

• Trace Propagation: Extracts log correlation IDs (trace IDs) from context.Context to trace request lifecycles.
• Formatters: JSON format for production environments; clean, colorized/localized text for development.
• Secrets Masking: Redacts sensitive values (e.g. passwords, secrets, API keys, tokens) to prevent accidental data leaks.

3. Concurrency (concurrency)

Type-safe, generic bounded concurrency primitives.

• Pool[Req, Res]: A bounded worker pool that runs a limited number of parallel goroutines, manages context-based cancellation, captures errors, handles worker panics safely without crashing the main process, and aggregates results.

4. Exponential Backoff & Retry (retry)

Provides a resilient execution wrapper for network calls, database queries, and external APIs.

• Full Jitter: Prevents the "thundering herd" problem by adding randomized noise to backoff calculations.
• Retryable Check: Supports an optional custom predicate to retry only transient failures (e.g., connection timed out vs. permission denied).

5. Strict Configuration Loader (config)

A zero-dependency struct-based configuration parser.

• Tags: Supports env, default, and required tags.
• Strict Validation: Fails fast with descriptive errors if required values are missing.
• Redaction: Redacts sensitive configuration structures when logged.

6. Cryptography (crypto)

Core security primitives:

• Cryptographically secure random tokens and bytes.
• AES-GCM 256-bit symmetric encryption and decryption.
• HMAC-SHA256 digital signatures for data integrity verification.

---

Directory Structure

altiquum-core/
├── go.mod          # Go module declaration
├── README.md       # Technical guide (this file)
├── LICENSE         # Apache License 2.0
├── Makefile        # Task automation
├── config/         # Strict struct-based env config parser
├── concurrency/    # Bounded generic worker pool
├── crypto/         # Cryptography (AES-GCM, HMAC, secure rand)
├── errors/         # Stacked error definitions and codes
├── logging/        # Context-aware slog logger & redactor
├── retry/          # Exponential backoff retry with jitter
└── examples/       # Combined integration example

---

Installation

go get github.com/altiquum/altiquum-core

---

License

Apache License 2.0. See LICENSE for details.