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 = "github.com/gombit-dev/gombit"
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 with a local path)")
ErrFrameworkVersionUnresolved is returned when go.mod names the framework but its version cannot be reported as a resolvable module version — a local filesystem replace directive (a framework dev checkout) being the common case. A host cannot pin such a build, so this is surfaced rather than guessed. A version-to-version replace (e.g. to a published fork) IS resolvable and its target version is reported instead.
Functions ¶
func FrameworkVersion ¶
FrameworkVersion reads the version of the Gombit framework the app in workDir builds against, straight from its go.mod require directive. It deliberately parses the *declared* dependency rather than running the go toolchain, so it is offline and deterministic.
A replace of the framework module wins over the require: a version-to-version replace (or a published fork with a version) reports its target version, while a local filesystem replace is unresolvable for a host and returns ErrFrameworkVersionUnresolved. A go.mod that does not require the framework at all is an error — it is not a Gombit app.
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