Documentation
¶
Overview ¶
Package compose wraps compose-spec/compose-go's project loader with the hull-specific behavior (file-size caps, the urunc x-* extensions) layered on top of the typed *types.Project model it returns.
Index ¶
Constants ¶
const ( // XHypervisorKey and XOneShotKey are exported so callers that need to // synthesize these extensions (compose config's hydration of computed // values, cmd/hull/compose.go) write the same key Hypervisor and // OneShot read, instead of duplicating the string literal. XHypervisorKey = "x-hypervisor" XOneShotKey = "x-oneshot" )
const MaxUserFileBytes = 8 << 20 // 8 MiB
MaxUserFileBytes caps the user-supplied text files the loader reads: a compose file, an env file, or a file pulled in via `include:`. A compose file or an env file is a document; without a cap, pointing one at an endless stream like /dev/zero hangs the process while it consumes the machine's memory. Matches maxTextFileBytes, the limit the bespoke loader enforced in cmd/hull/compose.go.
Variables ¶
This section is empty.
Functions ¶
func Hypervisor ¶
func Hypervisor(svc types.ServiceConfig) string
Hypervisor returns the service's x-hypervisor value, or "" when the key is absent or not a string.
func Load ¶
Load parses, validates, interpolates and merges the project the way docker compose does, then returns the typed model.
func OneShot ¶
func OneShot(svc types.ServiceConfig) bool
OneShot reports whether the service declares x-oneshot: true.
func WarnUnsupportedKeys ¶
WarnUnsupportedKeys walks the raw YAML and emits one warning per key this runtime does not act on, at every level: top-level elements, service keys, and the nested depends_on / x-healthcheck-tcp mappings. The key is reported as a dotted path ("services.web.restart") so a warning is unambiguous no matter how deep the key sits. origin names the file when it is one an include pulled in, because the dotted path alone would send the reader looking for the key in the file they named on the command line.
Types ¶
type HealthTCP ¶
type HealthTCP struct {
Port int
Interval time.Duration
Retries int
StartPeriod time.Duration
// Declared distinguishes an x-healthcheck-tcp key that was present but
// useless (empty mapping, port 0) from the key being absent, so the
// former can warn instead of vanishing.
Declared bool
}
HealthTCP mirrors the bespoke healthTCP (cmd/hull/compose.go:453): x-healthcheck-tcp accepts a bare port (x-healthcheck-tcp: 5432) or a mapping with docker-style tuning: {port, interval, retries, start_period}. The probe itself is a plain TCP connect: it proves a listener exists, not that the app is ready — start_period is the tool for services that restart during init.
func HealthTCPFor ¶
func HealthTCPFor(svc types.ServiceConfig) (HealthTCP, error)
HealthTCPFor decodes the service's x-healthcheck-tcp extension. Declared is false when the key is absent; HealthTCPFor returns the zero HealthTCP in that case.
Unlike the bespoke yaml.Node-based UnmarshalYAML this ports (which had a YAML line number available for its error messages), the typed compose-go model hands extension values back as already-decoded `any` with no source position attached, so the "line %d: " prefix the bespoke errors carried is dropped here.
func (HealthTCP) ProbeBudget ¶
ProbeBudget returns the TCP-connect retry interval and the total time budget (start_period plus interval*retries) a caller should allow before giving up. Same defaults as the bespoke implementation: a 1s interval and 60 retries when unset.
type Options ¶
type Options struct {
Files []string // -f list; empty means default discovery in WorkingDir
ProjectName string // sanitized -p / COMPOSE_PROJECT_NAME / dirname
WorkingDir string
EnvFiles []string // --env-file list; nil means default .env discovery
Profiles []string // --profile / COMPOSE_PROFILES; "*" = all
Environ []string // caller passes os.Environ(); injectable for tests
// Warn receives one line per unsupported compose key encountered in the
// main config file(s) and any file pulled in via `include:` (see
// WarnUnsupportedKeys). A nil Warn silently drops the warnings, the same
// as pointing it at io.Discard.
Warn io.Writer
// SkipUnreadableIncludes tolerates a top-level `include:` entry naming a
// file that cannot be opened: that entry (and the services it would
// have contributed) is dropped instead of failing the whole Load. A
// reload of a live project sets this — see reloadProject in
// cmd/hull and stripUnreadableIncludes's own doc comment for
// why, and for the one-level scope limit. A command a user is waiting
// on (config, up) never sets it: there, a missing include is the whole
// point of the error.
SkipUnreadableIncludes bool
}
Options carries everything a compose command invocation determines.