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 gqlclient provides a low level GraphQL client.
|
Package gqlclient provides a low level GraphQL client. |
|
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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.