Documentation
¶
Overview ¶
Package appcontract projects a stable, machine-readable description of a Gombit application — the HOST-1 application contract (ADR-015). A deployment host (e.g. Gombit Cloud) reads it to learn how to build, health-check, and migrate an ordinary handwritten Gombit app without inferring anything from repository trivia.
Every field is projected from the app's *declared* configuration (typed config.Config / gombit.yaml, the resolved framework version, documented defaults) — never guessed by walking the source tree (build plan §10, 6.2). The contract is versioned by ContractVersion, independent of the framework version, so a host can fail loudly on an unknown shape (DESIGN.md §53, §55).
Index ¶
Constants ¶
const ( LivenessPath = "/livez" ReadinessPath = "/readyz" )
Health probe paths are the stable operational contract from HOST-2 (ADR-015, docs/health.md). They are fixed so a host can rely on them.
const ( DefaultBuildCommand = "gombit build --embed" DefaultBuildArtifact = "bin/server" // DefaultMigrationsPath mirrors migrations.defaultMigrationDir. DefaultMigrationsPath = "database/migrations" )
Documented build defaults (build plan M5-5; build.DefaultOut = "bin/server").
const ContractVersion = 1
ContractVersion is the schema version of the emitted contract. It is independent of the framework version; bump it only on a breaking shape change, and document the change.
const FrameworkModulePath = frameworkmod.ModulePath
FrameworkModulePath is the module a Gombit application requires.
const FrameworkName = "gombit"
FrameworkName is the framework a Gombit application contract describes.
Variables ¶
var ErrFrameworkVersionUnresolved = errors.New("appcontract: framework version is unresolved (replaced by a local path or another module)")
ErrFrameworkVersionUnresolved is returned when go.mod names the framework but no framework release: it is replaced by a local filesystem path (a framework dev checkout, the common case) or by another module (a fork, whose version is not a framework release). A host cannot pin such a build as a framework version, so this is surfaced rather than guessed. A replace by the framework module itself at another version IS resolvable, and that version is reported instead.
Functions ¶
func FrameworkVersion ¶
FrameworkVersion reads the version of the Gombit framework the app in workDir builds against, from its go.mod. It deliberately parses the *declared* dependency rather than running the go toolchain, so it is offline and deterministic. It is internal/frameworkmod's Release, the same answer gombit upgrade baseline gives for go.mod.
The replace directive that applies to the required version (as the go command picks it) wins over the require: a replace by the framework module at another version reports that version, while a local filesystem replace or a fork is not a framework release and returns ErrFrameworkVersionUnresolved. A go.mod that does not require the framework at all, or that the go command refuses (the framework required twice, conflicting replaces), is an error.
Types ¶
type Contract ¶
type Contract struct {
ContractVersion int `json:"contract_version"`
Framework Framework `json:"framework"`
Build Build `json:"build"`
Runtime Runtime `json:"runtime"`
Database Database `json:"database"`
Migrations Migrations `json:"migrations"`
}
Contract is the machine-readable application description (DESIGN.md §9).
type Database ¶
Database is the app's datastore dependency. Required is true when the framework refuses to start without a database for the declared configuration.
type Inputs ¶
type Inputs struct {
// FrameworkVersion the app builds against (e.g. "v0.5.0"). Required — an
// empty value is a hard error, never a silent default (DESIGN.md §55).
FrameworkVersion string
// HTTPAddr is the declared listen address (config.HTTP.Addr, e.g. ":8080").
HTTPAddr string
// DatabaseDriver is the configured driver (config.Database.Driver).
DatabaseDriver string
// DatabaseRequired is whether the framework requires a database to start
// for this configuration (currently: auth enabled — framework/app.go).
DatabaseRequired bool
// MigrationsPath locates versioned migrations; DefaultMigrationsPath when "".
MigrationsPath string
// BuildCommand / BuildArtifact override the documented defaults when set.
BuildCommand string
BuildArtifact string
}
Inputs are the declared values a Contract is projected from. The CLI maps a typed config.Config onto these; keeping Project free of config keeps it trivially testable and lets a host reuse the type.
type Migrations ¶
type Migrations struct {
Path string `json:"path"`
}
Migrations locates the app's versioned migrations.
Source Files