prostack-go

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT

README

prostack-go — Reusable Go backend infrastructure

Build your business logic on a foundation you do not have to rebuild.

prostack-go is a Go infrastructure library for backend services: application bootstrap, HTTP and gRPC, PostgreSQL, MongoDB, Redis, NATS JetStream, Kafka, configuration, structured logging, health checks, and OpenTelemetry integration. Use individual packages in an existing application or assemble a service with the shared lifecycle.

prostack means production stack. It grew out of repeating the same infrastructure setup across projects and companies before writing business code. This repository contains the reusable foundation; prostack-go-showcase demonstrates it in a runnable application.

I also saw organizations with many services and teams, each assembling its own mix of technologies and infrastructure conventions. I wanted a shared baseline for recurring concerns—lifecycle, errors, telemetry, and tests—to standardize engineering practices across teams and make it easier for developers to move between projects. Teams can choose the components their applications need.

Quick start · Explore the packages · Integration guide

Why prostack-go?

Database and broker clients solve individual problems. A backend also needs consistent startup, configuration, telemetry, error transport, health probes, shutdown, and tests. prostack-go connects these recurring concerns while keeping your domain and business rules in your own Go packages.

  • Adopt what you need. Import a PostgreSQL adapter or the event publisher without adopting the showcase's three-service architecture.
  • Keep familiar clients. Database adapters expose pgx, MongoDB driver, and go-redis types, so your repositories use their existing APIs.
  • Share lifecycle conventions. Register handlers, probes, background workers, and cleanup in one setup function.
  • Follow real examples. The showcase demonstrates an HTTP → gRPC → PostgreSQL transactional outbox → NATS and Kafka → email workflow, with integration tests.

This is for Go developers and teams building backend services or standardizing infrastructure across applications. Your application owns its domain model, repositories, schemas, API contracts, and deployment.

Quick start

Start with prostack-go-showcase, a runnable application with configuration, migrations, API contracts, and local infrastructure already connected.

Create a user and follow the complete workflow: HTTP → gRPC → PostgreSQL + transactional outbox → NATS JetStream and Kafka → email consumer. The walkthrough shows how to:

  • Create a user with an HTTP request, receive 201 Created, and fetch the stored user.
  • Follow user.created from the database transaction through both brokers to a logged fake welcome email and a delivery record in MongoDB.
  • Inspect request traces and asynchronous span links in Jaeger, plus health and metrics endpoints.

prostack-go supplies the shared lifecycle, instrumented clients and transports, error handling, and event publishing worker. The showcase demonstrates how to connect those pieces to application business logic and persistence.

Run the showcase for the required tools, dependency setup, migrations, application startup, and verification steps.

Packages

Each link opens the implementation in this repository. Import the packages relevant to your application; connections are created when you call their setup functions.

Package What you get
ps_bootstrap Application setup, HTTP and optional gRPC listeners, probes, worker draining, and cleanup.
ps_config Typed configuration from YAML, local overrides, declared environment variables, and validation.
logger Zap development/production presets, context-aware logging, and an OpenTelemetry log bridge.
ps_http, ps_controller Instrumented HTTP serving, JSON responses, and conversion of gRPC error details into HTTP errors.
ps_grpc, ps_error Instrumented gRPC servers/clients, unary recovery/error interceptors, and typed application errors.
ps_pg Instrumented pgx connection pools and connection health verification.
ps_mongo Instrumented MongoDB connections and database selection from the URI.
ps_redis go-redis clients with tracing, metrics, and an initial connection check.
ps_nats JetStream stream setup, concurrent consumers, publisher support, and trace propagation.
ps_kafka Kafka publishing, concurrent consumers, ordered partition commits, and trace propagation.
ps_event Outbox/publisher interfaces, a background publishing worker, and fanout to multiple publishers.
ps_otel, ps_metrics OpenTelemetry initialization and an application Prometheus registry.
ps_healthcheck /healthz, /readyz, and /startupz handlers.
ps_swagger, ps_asyncapi Embedded documentation UIs for your supplied OpenAPI and AsyncAPI documents.
ps_test Testcontainers helpers for PostgreSQL, MongoDB, NATS, Kafka, plus gRPC test utilities.

Development

From a checkout of this repository:

make mod-download
make help
make test

The test suite uses real containerized dependencies and requires a reachable Docker daemon, tested with Docker 29.8.2. Library Testcontainers tests do not require the showcase Compose stack.

Command Purpose
make test Run all foundation packages, including integration tests.
make lint Install the pinned linter if needed and lint the library.
make proto-gen Regenerate the shared error protobuf; requires Buf 1.74.0. Go generator versions are pinned by Make.
make mod-tidy Reconcile module dependencies after code changes.

Reusable Make fragments can also be included by a consuming repository. The showcase Makefile demonstrates app discovery, build/run/test targets, migrations, and local Compose commands. Those application targets belong to the consuming repository; the foundation's Makefile focuses on library development.

Troubleshooting

Symptom What to check
Exporters try to reach a local collector Use the exporter settings from the minimal bootstrap example or configure your own OTLP endpoint.
No OpenTelemetry metrics at /metrics Scrape /otel-metrics with OTEL_METRICS_EXPORTER=ps_prometheus; /metrics is a separate registry.
Configuration files are not found Check the process working directory and your declared configuration tags.
Ctrl+C does not exit immediately Allow the fixed 10-second load-balancer delay and handler/worker draining to finish.
/readyz succeeds while a dependency is unavailable Register a probe for that dependency; readiness only runs registered checks.
Private or unpublished source cannot be downloaded Ensure the pinned commit is reachable and configure Git access for the repository, or use a local replace while developing.

Contributing

Open an issue with reproduction steps, tool versions, and relevant logs with secrets removed. Focused fixes, tests, and documentation improvements are welcome; follow project conventions and run the relevant checks.

Infrastructure changes belong here. Application workflows and runnable examples belong in prostack-go-showcase.

License

MIT.

Directories

Path Synopsis
pkg
Package ps_healthcheck exposes the standard k8s probes (/healthz, /readyz, /startupz) on an HTTP mux.
Package ps_healthcheck exposes the standard k8s probes (/healthz, /readyz, /startupz) on an HTTP mux.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL