platform/go-pkg
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

feat(platform): add shared service platform packages #1

Merged
hayshin merged 21 commits from feat/service-skeleton into main 2026-07-10 12:41:09 +05:00
Conversation 0 Commits 21 Files changed 193 +11805 -201
hayshin commented 2026-07-10 12:40:27 +05:00
Owner
Copy link
  • add reusable service lifecycle, telemetry, HTTP/gRPC transport stacks, metadata propagation, and shared client helpers for platform services.
  • introduce PostgreSQL migrations, transaction/idempotency APIs, transactional outbox with NATS relay support, and integration-test utilities.
  • document package usage and architecture so teams can adopt the shared Go platform library consistently.
- add reusable service lifecycle, telemetry, HTTP/gRPC transport stacks, metadata propagation, and shared client helpers for platform services. - introduce PostgreSQL migrations, transaction/idempotency APIs, transactional outbox with NATS relay support, and integration-test utilities. - document package usage and architecture so teams can adopt the shared Go platform library consistently.
- add srv lifecycle primitives: Serveable, ServiceContext, Group/WithGroup
  (errgroup fail-fast), and ServeStartStop with a 15s graceful drain
- add Prometheus RED metrics helpers (grpcmetrics, httpmetrics) plus
  core/routeinfo so HTTP metrics label by route pattern, bounding cardinality
- add transport module/stack/server trees for gRPC (grpcmod/grpcstack/grpcsrv)
  and chi-based HTTP (httpmod/httpstack/httpsrv); gRPC errmap reuses errx/grpcerr
  for error mapping and panic recovery, logging adapts core/logging.Logger
- add telemetrysrv exposing /metrics, /healthz, /readyz, /startupz with
  registerable probes, plus pg/redis/nats probe helpers in a subpackage
- add chi/v5, prometheus/client_golang, grpc prometheus provider and otelgrpc;
  promote golang.org/x/sync to a direct dependency
- add gRPC + HTTP client stacks mirroring the server side: grpcclient/
  grpcclientstack with otelgrpc tracing, client metrics (wire up the
  previously-unused NewDefaultClientMetrics), logging, and native
  service-config retry; httpclient builds an instrumented http.Client
  (otelhttp, client metrics, safe-method retry) via a RoundTripper chain
- add idempotency modules: grpcmod/idempotent (unary, static proto
  response registry) and httpmod/idempotent (2xx caching via a
  write-through recorder, 409 on in-progress), fail-open and opt-in
  through grpcstack/httpstack
- add core/ctxmeta carrying request/correlation ID and principal, a
  RequestIDHook in defaultHooks, and inbound/outbound transport modules
  so an X-Request-Id now reaches gRPC logs and downstream calls
- remove dead srv.Serve/Server abstraction; preserve its graceful-then-force logic as reusable srv.StopGracefully with tests
- fix grpcsrv shutdown to bound GracefulStop by the stop context, falling back to Stop() so stuck streams can't hang past the timeout
- add srv.Run bootstrap (signal context + startup/shutdown logging) that finally exercises appinfo.Info
- surface the real tracer build error via telemetrysrv Tracer() instead of a generic message
- release non-cacheable gRPC idempotency slots and default/validate idempotency TTLs
- sanitize SMTP headers, fix pg page-token decoding, and default partial gRPC retry configs
- align credential env helpers and centralize shared ctxmeta/metrics helpers
- prefer pgtx.Manager with explicit repository binding and deprecate context-injected PG helpers
- add core/idempotent.Run to centralize reserve/replay/complete/release orchestration
- refactor HTTP and gRPC idempotency modules onto the shared state machine with coverage
- rename Redis and S3 credential fields to match Config naming.
- make tracing and PostgreSQL pool env vars service-prefixed and explicit.
- remove misleading NATS env tags from Credentials so Config owns env loading.
- add core/clients/pg/pgmigrate with goose-backed runner, lifecycle holder, and config loading
- honor pg.Config.Schema by creating the schema and setting search_path for migrations
- document usage and add tests for schema parsing helpers
- relocate core/clients/pg/pgmigrate → migrations/pgmigrate so migration
  tooling lives separate from pg client infrastructure
- drop configureDB (pool semantics don't apply to a sequential migration
  runner); use SetMaxOpenConns(1) instead
- simplify Close() — the r.db fallback branch was dead code since
  provider.Close() already closes the db
- add Status() method to Runner
- add migrations/pgtest with OpenPoolWithMigrations: runs migrations once
  per schema per process (sync.Once), opens pool with search_path=
  "schema,public" so extension types remain visible, registers t.Cleanup

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Ports five packages from the reference shared library:
- core/clients/clickhouse: ClickHouse connection via clickhouse-go/v2
- core/clients/k8s: Kubernetes Clientset with namespace/config accessors and IsInCluster helper
- core/clients/vault: Vault client with static token and K8s service-account auth, automatic token renewal
- srv/loop: periodic background task abstraction implementing srv.Serveable
- core/testflag: context-carried feature flags with signed HTTP header propagation for test environments

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Ports grpcmid (gRPC interceptor framework with logging and context flags)
and httpmid (grpc-gateway HTTP middleware binder) from lab/pkg/middlewares.
Import paths updated to this module; emperror.dev/errors replaced with fmt.Errorf.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Port missing transport modules from lab/pkg: errorhandler (generic
error-mapping interceptor), routermd (x-m4-route-* header propagation),
testflag, recovery (panic recovery with logging), optshelper, and
grpcmod/meta (x-m4-md typed-proto metadata propagation). Add HTTP
http2mod (h2c) and httpmod/routermd. Add core/meta with a typed
proto-message KV store in context and metaencoding that is wire-compatible
with lab/pkg (preamble byte + protowire map + zstd + base64 URL).
Promote klauspost/compress and golang.org/x/net to direct deps.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- telemetrysrv: fail Serve fast when a requested tracer fails to build instead of silently running without traces
- telemetrysrv: resolve metrics/tracer once after options run, fixing metrics double-mount and a leaked tracer when options override defaults
- telemetrysrv: bound tracer Shutdown with a 5s timeout so a stuck exporter cannot hang process shutdown
- loop: make interval an atomic re-read each tick so WithTimeout is concurrency-safe and effective; add loop tests
- srv: log info.String() consistently in Run; document probe 503-vs-500 mapping and when to use StopGracefully vs ServeStartStop
- add core/clients/pg/pgoutbox: Event, Repo (embeds pgtx.Repo), and a
  Serveable Relay that claims unpublished rows with FOR UPDATE SKIP LOCKED,
  publishes them, and marks published/retry/failed with exponential backoff
- add core/clients/nats/natsoutbox: JetStream Publisher that sets Nats-Msg-Id
  to the event id for at-least-once delivery with consumer-side dedup
- ship the outbox table as an embedded goose migration via MigrationFS
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- add domain outbox port with PostgreSQL adapter for reusable event publishing
- add offset pagination tokens and JetStream stream ensure helper
- add pgmigrate source runner for multi-table migration workflows
- Add devenv.nix with Go tooling, formatting, linting, and test scripts.
- Provide default local environment variables for package integration helpers.
- Include common infrastructure clients for debugging shared client packages.
- add devenv lock and git-hooks input metadata for reproducible shells
- add a ds shortcut to re-enter the devenv shell from project scripts
- ignore local devenv, build, editor, OS, and runtime artifacts
- add test/integration helpers to start docker compose dependencies from tests
- document shared compose usage and opt-in cleanup behavior in README
- expand README.md with a documentation index and grouped package map
- add cross-cutting guides for bootstrap, observability, outbox, idempotency, and testing
- document HTTP, gRPC, PostgreSQL, outbox, metadata, and telemetry package usage
hayshin deleted branch feat/service-skeleton 2026-07-10 12:41:09 +05:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
platform/go-pkg!1
No description provided.