api-reference.md

layout	page
title	API Reference
permalink	/api-reference/

API Reference

The complete, always-current API reference is generated from the source and hosted on pkg.go.dev:

→ pkg.go.dev/github.com/datariot/forge

Rather than duplicate godoc here (where it drifts out of date), this page orients you to the packages. Follow the links for full type and method documentation.

Packages

Package	Purpose	Reference
framework	Application lifecycle, the App builder, Component/Bundle/HealthContributor interfaces, functional options	godoc
config	BaseConfig, environment-aware defaults, validation	godoc
health	Report, Check, Registry, liveness/readiness model	godoc
forgeerrors	Structured DomainError with codes and classification	godoc
testutil	Test helpers for framework consumers	godoc
bundles/postgresql	Pooled PostgreSQL via pgx	godoc
bundles/redis	Cache, pub/sub, locks, rate limiting	godoc
bundles/jwt	Service-to-service JWT auth	godoc
bundles/httpclient	Resilient HTTP client	godoc
bundles/prometheus	Metrics + automatic request instrumentation	godoc
bundles/configloader	Multi-source config with hot reload	godoc

Core building blocks

Your service implements these framework interfaces:

// Business logic — started in registration order, stopped in reverse.
type Component interface {
    Start(ctx context.Context) error
    Stop(ctx context.Context) error
}

// Optional: contribute health checks.
type HealthContributor interface {
    HealthChecks() []health.Check
}

// Optional: register gRPC services.
type Registrar interface {
    RegisterGRPC(server *grpc.Server) error
}

And compose the application with functional options:

app, err := framework.New(
    framework.WithConfig(&cfg),
    framework.WithVersion("1.0.0"),
    framework.WithComponent(svc),
    framework.WithBundle(postgresql.NewBundle(dbConfig)),
    framework.WithHealthContributor(svc),
    framework.WithGRPCRegistrar(svc), // starts the gRPC server
)

See Getting Started for a full walkthrough and Bundles for per-integration configuration.