README
¶
paper-board/sdk
Phase: 2 — migrator/, log/, errors/, auth/ shipped at v0.3.0. obs/ placeholder; real OTLP exporter Phase 1.5.
Shared Go library for paper-board services. SemVer 2.0 disciplined.
Packages
migrator/— golang-migrate wrapper with cobra CLI; per-service advisory lock; embed.FS source. See ADR-0004.log/— slog-based structured logging; ctx-awarePkg(ctx)helper auto-injects request_id, trace_id, org_id, user_id.auth/— JWT + API-key middleware backed by identity gRPC. Drop-in for any paper-board service post-Phase 2.obs/— OpenTelemetry SDK setup; Phase 1.0 placeholder, Phase 1.5 real OTLP exporter.errors/— sentinel errors + gRPC code mapping (ToGRPCStatus,FromGRPCStatus).
Install
go get github.com/paper-board/sdk@latest
Each minor/patch tag triggers a Renovate auto-PR in every dependent service repo.
Usage
// cmd/migrator/main.go (in your service repo, ~30 lines)
package main
import (
"context"
"log"
"os"
"github.com/paper-board/sdk/migrator"
"github.com/paper-board/identity/migrations" // your service's embed
)
func main() {
cfg := migrator.Config{
DBURL: os.Getenv("MIGRATION_DB_URL"),
Schema: "identity",
EmbedFS: migrations.SchemaFS,
EmbedRoot: "schema",
}
if err := migrator.Run(context.Background(), cfg, os.Args[1:]); err != nil {
log.Fatal(err)
}
}
Versioning
SemVer strict:
- major — breaking API change
- minor — additive (new function, new field)
- patch — bug fix, doc fix
Each minor/patch bump triggers Renovate auto-PR in dependent service repos.
Development
go mod tidy
go test -race -count=1 ./...
Integration tests use testcontainers-go for Postgres. Requires Docker.
Standards
Code follows go-coding-conventions.md. Test discipline follows testing.md. All public APIs SemVer-versioned per ADR-0008.
Further Reading
Contributing
Issues + PRs welcome. Open issues for breaking proposals before coding; the SemVer-major bump cost is high (Renovate-driven cascade across all services). See paper-board/.github for community files.
License
MIT — see ADR-0008 for licensing policy. LICENSE file lands Phase 5.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides per-route HTTP middleware for verifying caller identity against the paper-board identity gRPC AuthService.
|
Package auth provides per-route HTTP middleware for verifying caller identity against the paper-board identity gRPC AuthService. |
|
mock
Package mock provides test doubles for the identity gRPC AuthService.
|
Package mock provides test doubles for the identity gRPC AuthService. |
|
Package clock provides an injectable time source for paper-board services.
|
Package clock provides an injectable time source for paper-board services. |
|
Package config provides an env-only configuration loader for paper-board services.
|
Package config provides an env-only configuration loader for paper-board services. |
|
Package errors provides shared sentinel errors and gRPC mapping for paper-board services.
|
Package errors provides shared sentinel errors and gRPC mapping for paper-board services. |
|
Package healthcheck provides composable readiness probes for paper-board services.
|
Package healthcheck provides composable readiness probes for paper-board services. |
|
Package httpclient provides a default *http.Client for outbound HTTP, wrapped with otelhttp.NewTransport so spans propagate W3C TraceContext.
|
Package httpclient provides a default *http.Client for outbound HTTP, wrapped with otelhttp.NewTransport so spans propagate W3C TraceContext. |
|
Package httpmw provides shared HTTP middleware for paper-board services.
|
Package httpmw provides shared HTTP middleware for paper-board services. |
|
Package idempotency provides HTTP middleware that implements the Idempotency-Key header semantics (Stripe-style).
|
Package idempotency provides HTTP middleware that implements the Idempotency-Key header semantics (Stripe-style). |
|
Package log provides slog-based structured logging for paper-board services.
|
Package log provides slog-based structured logging for paper-board services. |
|
Package migrator provides a thin wrapper around golang-migrate for paper-board services.
|
Package migrator provides a thin wrapper around golang-migrate for paper-board services. |
|
Package obs provides OpenTelemetry SDK setup, propagation, and shutdown for paper-board services.
|
Package obs provides OpenTelemetry SDK setup, propagation, and shutdown for paper-board services. |
|
Package store provides shared Postgres helpers used across paper-board services.
|
Package store provides shared Postgres helpers used across paper-board services. |
|
Package testfixture provides Postgres test infrastructure for paper-board services: a process-shared testcontainers Postgres, schema-bootstrap, and per-test truncation.
|
Package testfixture provides Postgres test infrastructure for paper-board services: a process-shared testcontainers Postgres, schema-bootstrap, and per-test truncation. |
Click to show internal directories.
Click to hide internal directories.