Documentation
¶
Overview ¶
Package appkit is the service runtime: one constructor that wires the infrastructure a service would otherwise hand-roll in main() — logging, database cluster, event publisher/subscriber, audit client, event signing, health checks, the standard middleware stack and graceful shutdown.
The runtime never builds a router. Handler decorates whatever http.Handler the service brings with the standard middleware and the operational endpoints, and Run serves it:
a, err := app.New("orders",
app.WithDatabase(),
app.WithOptionalEventPublisher(),
)
if err != nil {
return err
}
defer a.Close()
mux := http.NewServeMux()
// ... register service routes on mux ...
a.Run(a.Handler(mux))
Schema migration is a service concern: WithMigration takes a func(*sql.DB) error, so goose, Atlas or an ORM's automigration all plug in without the runtime depending on any of them.
Index ¶
- type App
- func (a *App) Close()
- func (a *App) DetailedHealthHandler() http.HandlerFunc
- func (a *App) Handler(routes http.Handler) http.Handler
- func (a *App) HealthCheckers() []middleware.HealthChecker
- func (a *App) ReadinessCheckers() []middleware.HealthChecker
- func (a *App) Run(handler http.Handler, cleanup ...func() error)
- func (a *App) SQLDB() *sql.DB
- type Option
- func WithAudit() Option
- func WithDatabase() Option
- func WithEventPublisher() Option
- func WithEventSubscriber() Option
- func WithHealthCheck(check middleware.HealthChecker) Option
- func WithMigration(migrate func(*sql.DB) error) Option
- func WithOptionalAudit() Option
- func WithOptionalEventPublisher() Option
- func WithOptionalEventSubscriber() Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type App ¶
type App struct {
Name string
Port string
Signing *eventbus.SignatureConfig
DBManager *pgcluster.ClusterManager
RabbitNodes []string
EventPub eventbus.PublisherInterface
EventSub *amqpcluster.ClusterSubscriber
Audit *audit.AuditClient
Health *health.HealthChecker
Tomb *lifecycle.Manager
// contains filtered or unexported fields
}
App holds the wired infrastructure for one service instance.
func New ¶
New wires the requested infrastructure for the named service. On error the already-created resources are released; callers treat an error as fatal.
func (*App) Close ¶
func (a *App) Close()
Close releases everything New created, in reverse order. Safe to call after a failed New and idempotent enough to defer immediately after it.
func (*App) DetailedHealthHandler ¶
func (a *App) DetailedHealthHandler() http.HandlerFunc
DetailedHealthHandler exposes the rich health report; services typically mount it inside their authenticated API surface.
func (*App) Handler ¶
Handler decorates routes with the standard middleware stack in the canonical order — tracing, metrics, request logging — and serves the operational endpoints every service must expose: /health, /ready, /metrics, and the profiling endpoints when the debug gate is open. Anything else falls through to routes.
CORS is deliberately absent: the allowed origins are a deployment policy, so a service that needs them wraps the result in middleware.CORS itself.
func (*App) HealthCheckers ¶
func (a *App) HealthCheckers() []middleware.HealthChecker
HealthCheckers reports on every dependency the service touches, including ones it can run degraded without.
func (*App) ReadinessCheckers ¶
func (a *App) ReadinessCheckers() []middleware.HealthChecker
ReadinessCheckers gates traffic on hard dependencies only: the database, and the event bus when the publisher was required rather than optional.
type Option ¶
type Option func(*options)
Option configures which infrastructure New wires up.
func WithAudit ¶
func WithAudit() Option
WithAudit wires the signed audit client; New fails if the broker is unreachable, audit being a compliance dependency.
func WithDatabase ¶
func WithDatabase() Option
WithDatabase connects the database cluster and exposes the writer pool through SQLDB.
func WithEventPublisher ¶
func WithEventPublisher() Option
WithEventPublisher wires a signed event publisher; New fails if the broker is unreachable.
func WithEventSubscriber ¶
func WithEventSubscriber() Option
WithEventSubscriber wires a signed event subscriber; New fails if the broker is unreachable.
func WithHealthCheck ¶
func WithHealthCheck(check middleware.HealthChecker) Option
WithHealthCheck adds a check to the /health report. It does not gate readiness; only the runtime's own hard dependencies do.
func WithMigration ¶
WithMigration connects the database cluster and runs migrate against the writer pool before New returns. New fails if the migration fails.
func WithOptionalAudit ¶
func WithOptionalAudit() Option
WithOptionalAudit wires the audit client if the broker is reachable and degrades to a nil Audit with a warning otherwise.
func WithOptionalEventPublisher ¶
func WithOptionalEventPublisher() Option
WithOptionalEventPublisher wires the publisher if the broker is reachable and degrades to a nil EventPub with a warning otherwise.
func WithOptionalEventSubscriber ¶
func WithOptionalEventSubscriber() Option
WithOptionalEventSubscriber wires the subscriber if the broker is reachable and degrades to a nil EventSub with a warning otherwise.
Source Files