README
¶
sdk-go
A monorepo of Go libraries by Downsized Devs — logging, config, auth, scheduling, storage, and ~35 other small, well-scoped packages designed to be imported individually.
Installation
go get github.com/downsized-devs/sdk-go
Or pull a single package — Go resolves the module graph minimally:
go get github.com/downsized-devs/sdk-go/logger
Quick Navigation
Pick the entry-point package for what you're trying to build. The full catalogue lives in docs/PACKAGE_REGISTRY.md.
| Category | Packages |
|---|---|
| Configuration & bootstrap | appcontext, configbuilder, configreader, featureflag |
| Logging, errors, observability | logger, errors, codes, audit, instrument, tracker |
| Data & storage | sql, nosql, redis, storage, localstorage, query, null |
| Auth & security | auth, security, ratelimiter |
| Messaging & integrations | email, messaging, slack, gqlclient |
| I18n & locale | language, translator |
| Time & jobs | clock, dates, scheduler |
| Files & documents | files, pdf, parser |
| Primitives & helpers | character, checker, convert, num, operator, stringlib, header |
| Tooling | tests (gomock fixtures). The scaffolding CLI is now scaffolder-go. |
Common Use Cases
| I need… | Reach for… |
|---|---|
| Structured logging that follows my request context | logger + appcontext |
| Typed errors with codes that survive across HTTP boundaries | errors + codes |
| A SQL database with leader/follower routing | sql (use query for dynamic clause building) |
| Redis caching with distributed locks | redis |
| MongoDB CRUD | nosql |
| S3 upload/download with presigned URLs | storage |
| Background cron jobs | scheduler (lock across replicas with redis) |
| Firebase authentication | auth |
| AES encryption / password hashing | security |
| Per-route HTTP rate limiting (Gin) | ratelimiter |
| Prometheus metrics for HTTP/DB/jobs | instrument |
| Send transactional email with MJML templates | email |
| Send Slack notifications | slack |
| Multi-language responses | language + translator |
| Generate API boilerplate | go run github.com/downsized-devs/scaffolder-go --entity_name X --file_location ./svc --api "create,edit,get,delete" |
Minimal example
package main
import (
"context"
"github.com/downsized-devs/sdk-go/appcontext"
"github.com/downsized-devs/sdk-go/logger"
)
func main() {
log := logger.Init(logger.Config{Level: "info"})
ctx := appcontext.SetRequestId(context.Background(), "boot")
log.Info(ctx, "hello, sdk-go")
}
Repository layout
Every top-level directory is a self-contained package. Internal dependencies form a DAG with logger, codes, and errors as the most-depended-on nodes — see docs/DEPENDENCY_GRAPH.md.
/<package>/ # one package per directory (40 in total)
/docs/ # cross-cutting documentation
/tests/mock/ # gomock fixtures, one subdir per mockable package
Makefile, go.mod # repository root
Documentation
- Contributing Guide — code style, test thresholds, release process.
- Stability Policy — per-package maturity levels, breaking-change policy.
- Package Registry — full catalogue with purpose, features, stability, import paths.
- Dependency Graph — mermaid + matrices + critical paths.
- Package README Template — for authors adding
<pkg>/README.md. - Looking for worked examples? Every package has its own README; start with
logger,auth, orredis.
Migration & breaking changes
From v1.0.0 onward, every package is Stable and follows the binding semver policy in STABILITY.md. Each major release ships a MIGRATION-vX.md in docs/ describing renamed symbols, removed packages, and field reshapes.
If a breaking change is unavoidable in a minor release, expect:
- A deprecation notice in code (
// Deprecated: …) and in STABILITY.md. - The new symbol shipped alongside the old one for one minor cycle.
- Removal only at the next major version.
Roadmap
- v1.0 — every package Stable; semver becomes binding (see STABILITY.md).
- Post-v1 — additive only on Stable interfaces. Deprecations carry one minor cycle before removal at the next major.
Code scaffolder
The code-scaffolding CLI lives in its own repo: scaffolder-go.
go run github.com/downsized-devs/scaffolder-go \
--entity_name <EntityName> \
--file_location <output-path> \
--api "create,edit,get,activate,delete"
Tooling
make build # compile every package
make run-tests # full unit-test suite
make mock-all # regenerate gomock stubs across packages
CI is GitHub Actions; coverage is reported to Codecov; CodeQL runs from .github/workflows/codeql.yml.
License
MIT — see LICENSE.
Support
Open an issue for bugs and feature requests. Security-sensitive issues should be reported privately — contact a maintainer before filing publicly.
Quality Metrics
Repository Stats
Code Health
Community
Directories
¶
| Path | Synopsis |
|---|---|
|
Package appcontext defines typed accessors and setters for request-scoped values (request id, user agent, IP, body, headers, timings) carried through a context.Context.
|
Package appcontext defines typed accessors and setters for request-scoped values (request id, user agent, IP, body, headers, timings) carried through a context.Context. |
|
Package audit emits structured audit records (HTTP captures and domain-level Record events) as zerolog log lines, enriched from the surrounding appcontext and the resolved user identity.
|
Package audit emits structured audit records (HTTP captures and domain-level Record events) as zerolog log lines, enriched from the surrounding appcontext and the resolved user identity. |
|
Package auth wraps the Firebase Admin SDK to provide ID-token verification, password sign-in, refresh-token exchange, and user CRUD.
|
Package auth wraps the Firebase Admin SDK to provide ID-token verification, password sign-in, refresh-token exchange, and user CRUD. |
|
Package checker provides small validation predicates (phone, email) and generic slice helpers (Contains, Deduplicate) used throughout the SDK.
|
Package checker provides small validation predicates (phone, email) and generic slice helpers (Contains, Deduplicate) used throughout the SDK. |
|
Package clock exposes a tiny seam over time.Now and time.Since so callers can inject deterministic clocks in tests.
|
Package clock exposes a tiny seam over time.Now and time.Since so callers can inject deterministic clocks in tests. |
|
Package convert offers type-coercion helpers (To/Int64, ToArrInt64, ToFloat64, etc.) backed by reflection and the go-conv library.
|
Package convert offers type-coercion helpers (To/Int64, ToArrInt64, ToFloat64, etc.) backed by reflection and the go-conv library. |
|
Package dates collects small date/time helpers (differences, formatting) that the rest of the SDK and consumers reuse.
|
Package dates collects small date/time helpers (differences, formatting) that the rest of the SDK and consumers reuse. |
|
Package files contains small file-system helpers: extension parsing and existence checks that never panic on permission errors.
|
Package files contains small file-system helpers: extension parsing and existence checks that never panic on permission errors. |
|
Package gqlclient provides a low level GraphQL client.
|
Package gqlclient provides a low level GraphQL client. |
|
Package localstorage stores and reads files on the local filesystem using a configurable base directory.
|
Package localstorage stores and reads files on the local filesystem using a configurable base directory. |
|
Package messaging is a thin wrapper over Firebase Cloud Messaging (FCM).
|
Package messaging is a thin wrapper over Firebase Cloud Messaging (FCM). |
|
Package num contains numeric utility helpers — currently a safe division primitive that hides divide-by-zero handling behind a configurable fallback.
|
Package num contains numeric utility helpers — currently a safe division primitive that hides divide-by-zero handling behind a configurable fallback. |
|
Package pdf is a thin in-memory wrapper around pdfcpu (encryption, merge, split, watermark, page count) plus ledongthuc/pdf for text extraction.
|
Package pdf is a thin in-memory wrapper around pdfcpu (encryption, merge, split, watermark, page count) plus ledongthuc/pdf for text extraction. |
|
Package query is a struct-tag-driven SQL clause builder.
|
Package query is a struct-tag-driven SQL clause builder. |
|
Package sql is a sqlx-backed SQL client with leader/follower routing, transactions, prepared statements, and optional Prometheus instrumentation.
|
Package sql is a sqlx-backed SQL client with leader/follower routing, transactions, prepared statements, and optional Prometheus instrumentation. |
|
Package storage wraps the AWS S3 v1 SDK with a small Interface covering upload, download, delete, presigned URL generation, and static URL construction.
|
Package storage wraps the AWS S3 v1 SDK with a small Interface covering upload, download, delete, presigned URL generation, and static URL construction. |
|
Package stringlib provides string utilities: random-string generation, trimming, case helpers, and other small reusable string operations.
|
Package stringlib provides string utilities: random-string generation, trimming, case helpers, and other small reusable string operations. |
|
tests
|
|
|
mock/audit
Package mock_audit is a generated GoMock package.
|
Package mock_audit is a generated GoMock package. |
|
mock/auth
Package mock_auth is a generated GoMock package.
|
Package mock_auth is a generated GoMock package. |
|
mock/clock
Package mock_clock is a generated GoMock package.
|
Package mock_clock is a generated GoMock package. |
|
mock/configbuilder
Package mock_configbuilder is a generated GoMock package.
|
Package mock_configbuilder is a generated GoMock package. |
|
mock/configreader
Package mock_configreader is a generated GoMock package.
|
Package mock_configreader is a generated GoMock package. |
|
mock/email
Package mock_email is a generated GoMock package.
|
Package mock_email is a generated GoMock package. |
|
mock/featureflag
Package mock_featureflag is a generated GoMock package.
|
Package mock_featureflag is a generated GoMock package. |
|
mock/gqlclient
Package mock_gqlclient is a generated GoMock package.
|
Package mock_gqlclient is a generated GoMock package. |
|
mock/instrument
Package mock_instrument is a generated GoMock package.
|
Package mock_instrument is a generated GoMock package. |
|
mock/localstorage
Package mock_localstorage is a generated GoMock package.
|
Package mock_localstorage is a generated GoMock package. |
|
mock/logger
Package mock_logger is a generated GoMock package.
|
Package mock_logger is a generated GoMock package. |
|
mock/messaging
Package mock_messaging is a generated GoMock package.
|
Package mock_messaging is a generated GoMock package. |
|
mock/nosql
Package mock_nosql is a generated GoMock package.
|
Package mock_nosql is a generated GoMock package. |
|
mock/parser
Package mock_parser is a generated GoMock package.
|
Package mock_parser is a generated GoMock package. |
|
mock/pdf
Package mock_pdf is a generated GoMock package.
|
Package mock_pdf is a generated GoMock package. |
|
mock/query
Package mock_query is a generated GoMock package.
|
Package mock_query is a generated GoMock package. |
|
mock/ratelimiter
Package mock_ratelimiter is a generated GoMock package.
|
Package mock_ratelimiter is a generated GoMock package. |
|
mock/redis
Package mock_redis is a generated GoMock package.
|
Package mock_redis is a generated GoMock package. |
|
mock/scheduler
Package mock_scheduler is a generated GoMock package.
|
Package mock_scheduler is a generated GoMock package. |
|
mock/security
Package mock_security is a generated GoMock package.
|
Package mock_security is a generated GoMock package. |
|
mock/slack
Package mock_slack is a generated GoMock package.
|
Package mock_slack is a generated GoMock package. |
|
mock/sql
Package mock_sql is a generated GoMock package.
|
Package mock_sql is a generated GoMock package. |
|
mock/storage
Package mock_storage is a generated GoMock package.
|
Package mock_storage is a generated GoMock package. |
|
mock/tracker
Package mock_tracker is a generated GoMock package.
|
Package mock_tracker is a generated GoMock package. |
|
mock/translator
Package mock_translator is a generated GoMock package.
|
Package mock_translator is a generated GoMock package. |
|
Package tracker pushes ad-hoc counter metrics to a Prometheus PushGateway and forwards event payloads to a configured webhook URL.
|
Package tracker pushes ad-hoc counter metrics to a Prometheus PushGateway and forwards event payloads to a configured webhook URL. |
Click to show internal directories.
Click to hide internal directories.