compose

package
v0.1.0-rc9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 17, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

View Source
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"
)
View Source
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

func Load(ctx context.Context, opts Options) (*types.Project, error)

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

func WarnUnsupportedKeys(w io.Writer, data []byte, origin string)

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

func (h HealthTCP) ProbeBudget() (interval, total time.Duration)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL