compose

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MPL-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package compose is the client-side library for Hikyo's Docker Compose delivery path (compose-integration ADR). It holds pure logic and filesystem primitives only — no network, no store/service/server/cli imports — so every piece is unit-testable in isolation. The CLI verbs (hikyo run, hikyo compose render|sync|doctor) are thin wiring over this package.

hikyo-compose.yaml — the project config file

A committed, NON-SECRET file at the compose project root, located by the verbs by walking up from --project-directory/cwd the way Compose finds compose.yaml. It holds no credential and the spec says so explicitly, because a file that *could* hold a token eventually does — the token reaches the CLI through --token-file and HIKYO_TOKEN only.

version: 1
instance: https://hikyo.example.internal   # origin; must match the trust store
org: org_…
project: prj_…
environment: env_…
runtime_dir: /run/hikyo/acme-web-production # optional; default per ops-spec § 6
snapshot:
  offline_serve: false     # opt-in per stack
  max_age: 168h            # optional, DOWNWARD-only override of the 7 d default
targets:
  api:
    keys: [key_…, key_…]                 # immutable key ids (schema ADR)
    services: [api, worker]
    acknowledge_loader_control: [PATH]   # per-target, by name

Parsing is STRICT: unknown fields are errors (yaml.v3 KnownFields). instance must be an https origin (loopback http permitted for local dev). Target names match ^[a-z][a-z0-9-]*$ because they become path segments and the stamp variable HIKYO_GEN_<UPPER_SNAKE>. A token/token_file/credential key anywhere is refused, naming the two real channels.

Index

Constants

View Source
const (

	// DefaultGenerationsKept is the retention per target beyond the current
	// stamp (ops-spec § 6: current + previous 3).
	DefaultGenerationsKept = 3
)
View Source
const DefaultSnapshotMaxAge = 7 * 24 * time.Hour

DefaultSnapshotMaxAge is the ADR's hard maximum (ops-spec § 6: 7 d). A per-stack max_age may only lower it.

Variables

View Source
var (
	ErrSnapshotExpired  = errors.New("compose: snapshot expired")
	ErrSnapshotRollback = errors.New("compose: snapshot issuance is not newer than the recorded high-water mark")
	ErrSnapshotContext  = errors.New("compose: snapshot context does not match local context")
)

ErrSnapshotExpired, ErrSnapshotRollback and ErrSnapshotContext are the policy refusals, each distinguishable from an AEAD failure (crypto.ErrDecrypt).

View Source
var ComposeVersionFloor = [3]int{2, 30, 0}

ComposeVersionFloor is the path-2 minimum (format: raw landed in 2.30.0).

Functions

func Append

func Append(stateDir string, records []OfflineRecord) error

Append writes records as ONE new batch file, 0600, fsynced (file + dir) before returning. Every record is validated first — a single invalid record fails the whole batch, so no partial, unauditable disclosure record is written. Callers MUST call Append and confirm success BEFORE releasing any plaintext to the workload.

func CurrentStamps

func CurrentStamps(projectDir string) (map[string]string, error)

CurrentStamps parses the managed block of <projectDir>/.env into a target→stamp map, with the same strict validation as parseManagedBlock. A file with no managed block yields an empty map.

func DefaultArgMax

func DefaultArgMax() int

DefaultArgMax on Linux and the BSDs. There is no cross-platform sysconf in golang.org/x/sys/unix (it is Solaris-only there), so this reproduces glibc's _SC_ARG_MAX derivation: one quarter of the stack rlimit, which is the kernel bound on the combined argv+envp region (MAX_ARG_STRLEN aside). Clamped to a conservative 128 KiB floor and a 6 MiB ceiling; a failed lookup uses the floor. Stated, not silent: the CLI passes an explicit limit in production and this is only the fallback source.

func EligibleCursor

func EligibleCursor(state *CursorState, want CursorBinding, currentStamps map[string]string, runtimeDir string) (string, bool)

EligibleCursor returns the stored cursor and true only when the full eligibility test holds against the current local delivery state: the binding matches `want` (every field and the exact target set), and for EVERY target the cursor's generation equals the managed-block stamp, is present and complete, and its <target>.env file exists in the generation directory.

func ExecPreflight

func ExecPreflight(env, argv []string, argMax int) (ok bool, detail string)

ExecPreflight is the POSIX leg: it checks the combined argv+environment byte size against argMax minus the 64 KiB margin and returns a refusal reason naming the overage. Pass DefaultArgMax() when no explicit limit is known.

func ExecSizePOSIX

func ExecSizePOSIX(env, argv []string, argMax int) (total int, ok bool)

ExecSizePOSIX sums len(entry)+1 over env and len(arg)+1 over argv — the per-string NUL the kernel counts — and reports whether the total fits within argMax - 64 KiB. It returns the computed total so the caller can name the overage.

func ExecSizeWindows

func ExecSizeWindows(env, argv []string) (cmdlineUnits, envUnits int, ok bool)

ExecSizeWindows counts the command line and the environment block in UTF-16 code units the way CreateProcess does, and reports whether EACH fits under 32767 (no margin). The command line is the argv AFTER per-argument quoting (escapeArg, the syscall.EscapeArg rule Go's os/exec applies) joined by single spaces, plus a terminating NUL — joining the RAW argv undercounts every argument that gains surrounding quotes or doubled backslashes. The environment block is each "name=value\0" plus a final terminating NUL.

func GenerationState

func GenerationState(runtimeDir, stamp string) (present, complete bool)

GenerationState reports whether a generation directory is present and whether it carries its completion marker. It is a read-only check used by doctor and the cursor over a resolved, absolute runtime dir.

func IsTmpfs

func IsTmpfs(path string) (bool, error)

IsTmpfs reports whether path is backed by tmpfs (or ramfs) via statfs. The caller (the CLI) feeds the result to doctor; the renderer does NOT refuse a non-tmpfs path — a default path must be tmpfs, but an explicitly configured one is the operator's call. This check is Linux-only; see the non-Linux leg.

func MarkFlushed

func MarkFlushed(stateDir string, handles []string) error

MarkFlushed deletes the batch files named by the given OPAQUE handles after the server accepted their records. A handle MUST be a bare basename produced by Pending; anything with a path separator, "..", or that resolves outside stateDir/offline-records/ is refused, so this can never be steered into deleting an arbitrary path. Reconciliation is idempotent, so a crash before deletion only re-sends.

func NewRecordID

func NewRecordID() (string, error)

NewRecordID returns a random 128-bit hex id — no dependency, sufficient collision resistance for an idempotency key.

func SaveCursor

func SaveCursor(stateDir string, c CursorState) error

SaveCursor writes cursor.json atomically (0600). The CLI calls it ONLY after a successful, committed render — NEVER after a refused or failed one.

func SaveSnapshot

func SaveSnapshot(keys *crypto.LocalKeys, binding crypto.SnapshotBinding, payload SnapshotPayload) error

SaveSnapshot seals payload under keys with the binding's canonical AAD, frames the self-describing container, and writes snapshot.bin atomically (0600). It advances snapshot.hwm to (issued_at, header-digest) and REFUSES to save an issuance older than the current high-water mark (a rollback attempt).

func TargetStamp

func TargetStamp(keys *crypto.LocalKeys, target string, content []byte) string

TargetStamp is the stamp over one target's rendered content, BOUND to the target name: the canonical input is "hikyo-target-content-v1\x00" + target + "\x00" + content, fed to the keyed stamp. Binding the name is why two DIFFERENT targets that happen to render byte-identical content still get DIFFERENT stamps (and thus different generation directories) — without it, the second target would find the first target's complete directory and fail to re-verify its own absent <target>.env. Keep the two domain prefixes in their two layers — this one here, crypto.Stamp's inside.

Types

type AbsentKeyPolicy

type AbsentKeyPolicy string

AbsentKeyPolicy tells the pure planner what a configured key missing from the source means. Live and snapshot adapters name their refusal independently; config-only adapters skip because projected-out secrets are absent entirely.

const (
	AbsentKeySkip                AbsentKeyPolicy = "skip"
	AbsentKeyRefuseNotDelivered  AbsentKeyPolicy = "refuse-not-delivered"
	AbsentKeyRefuseNotInSnapshot AbsentKeyPolicy = "refuse-not-in-snapshot"
)

type Collision

type Collision struct {
	Key string
}

Collision reports, by KEY NAME ONLY, a key present in both sources with differing values that was permitted by allowOverride (informational; hard-error collisions come back as the error). It carries NO values: a value in a result or error string reaches a `docker compose up` warning or a structured `%v` log and discloses a secret, and only the colliding name is needed.

func MergeEnv

func MergeEnv(inherited []string, fetched map[string]string, allowOverride []string) ([]string, []Collision, error)

MergeEnv merges fetched values into the inherited environment. inherited is a slice of "K=V" entries (os.Environ() shape); fetched is the delivered map. Inherited order is kept stable; fetched-only keys are appended sorted.

A key in both whose values differ is an error UNLESS listed in allowOverride, in which case it is a reported Collision (fetched still wins). Identical values are a silent no-op.

type ComposeConfig

type ComposeConfig struct {
	Services map[string]ComposeService `json:"services"`
}

ComposeConfig is the subset of `docker compose config --format json` doctor needs — the RESOLVED (interpolated) config.

func ParseComposeConfig

func ParseComposeConfig(data []byte) (*ComposeConfig, error)

ParseComposeConfig decodes the resolved compose JSON.

type ComposeService

type ComposeService struct {
	EnvFile []EnvFileRef      `json:"env_file"`
	Labels  map[string]string `json:"labels"`
}

ComposeService is one service's resolved env_file entries and labels.

type Config

type Config struct {
	Version     int    `yaml:"version"`
	Instance    string `yaml:"instance"`
	Org         string `yaml:"org"`
	Project     string `yaml:"project"`
	Environment string `yaml:"environment"`
	RuntimeDir  string `yaml:"runtime_dir"`
	// Slug is the OPTIONAL explicit project slug. When empty the CLI derives
	// one from the org/project/env ids; when set it becomes the state-dir and
	// default-runtime-dir path segment, so it is grammar-checked as a path
	// segment. It carries no delivery meaning.
	Slug     string            `yaml:"slug"`
	Snapshot SnapshotSettings  `yaml:"snapshot"`
	Run      RunSettings       `yaml:"run"`
	Targets  map[string]Target `yaml:"targets"`
	// contains filtered or unexported fields
}

Config is a parsed, validated hikyo-compose.yaml.

func ParseConfig

func ParseConfig(data []byte) (*Config, error)

ParseConfig strictly parses and validates a hikyo-compose.yaml document.

func (*Config) SnapshotMaxAge

func (c *Config) SnapshotMaxAge() time.Duration

SnapshotMaxAge is the effective snapshot max age (default or the downward override).

func (*Config) TargetNames

func (c *Config) TargetNames() []string

TargetNames returns the configured target names, sorted.

type CursorBinding

type CursorBinding struct {
	CredentialID   string `json:"credential_id"`
	Environment    string `json:"environment"`
	ConfigOnly     bool   `json:"config_only"`
	PinnedRevision int64  `json:"pinned_revision"` // 0 = unpinned (current)
	// Projection is the authorized delivery capability list, canonicalized.
	Projection []string `json:"projection"`
	// TargetKeyIDs is the render-target membership: target name → its immutable
	// key ids. Both the key set and the target set are compared exactly.
	TargetKeyIDs map[string][]string `json:"target_key_ids"`
}

CursorBinding is the full set of authorization-bound coordinates a cursor is tied to. Any change to any field invalidates the cursor.

func (CursorBinding) Equal

func (b CursorBinding) Equal(other CursorBinding) bool

Equal reports whether two bindings are identical after canonicalization, including the EXACT target set (an extra or missing target → not equal).

type CursorState

type CursorState struct {
	Cursor           string            `json:"cursor"`
	Binding          CursorBinding     `json:"binding"`
	GenerationStamps map[string]string `json:"generation_stamps"`
}

CursorState is the persisted cursor plus the binding that makes it eligible and the per-target generation stamps the cursor was issued against.

func LoadCursor

func LoadCursor(stateDir string) (*CursorState, error)

LoadCursor strictly parses cursor.json. A missing file returns (nil, nil): no cursor is a legitimate state (a full fetch follows).

type DoctorInput

type DoctorInput struct {
	ComposeVersion string         // `docker compose version --short`, e.g. "2.29.7"/"v2.30.0"
	Config         *ComposeConfig // resolved `docker compose config --format json`
	RawComposeYAML string         // raw compose text, where ${HIKYO_GEN_*:?} is visible
	ManagedStamps  map[string]string
	RuntimeDir     string
	RuntimeTmpfs   bool              // CLI probes IsTmpfs(RuntimeDir) and passes the result
	ServerStamps   map[string]string // target -> stamp over the server's current content
	ConfigTargets  map[string]Target
	ExistingKeyIDs map[string]bool // server's current key ids
	TokenFile      *FileMode
	StateEntries   []StateEntry

	SystemdInvocation       bool // INVOCATION_ID set
	TokenFromCredentialsDir bool // token passed from $CREDENTIALS_DIRECTORY
}

DoctorInput is everything doctor checks against.

type EnvFileRef

type EnvFileRef struct {
	Path     string `json:"path"`
	Format   string `json:"format"`
	Required bool   `json:"required"`
}

EnvFileRef is a resolved env_file entry.

type FileMode

type FileMode struct {
	Perm        os.FileMode
	OwnedByEUID bool
}

FileMode carries a token/state file's permission bits and whether the euid owns it — the CLI computes ownership so this package stays cross-platform.

type Finding

type Finding struct {
	Severity Severity
	Code     string
	Message  string
}

Finding is one doctor result.

func Doctor

func Doctor(in DoctorInput) []Finding

Doctor runs every check and returns findings sorted by (Code, Message) for a deterministic report.

type OfflineRecord

type OfflineRecord struct {
	RecordID        string `json:"record_id"`
	KeyID           string `json:"key_id"`
	KeyName         string `json:"key_name"`
	Classification  string `json:"classification"`
	OccurredAt      string `json:"occurred_at"` // client-asserted RFC3339
	CredentialID    string `json:"credential_id"`
	Generation      string `json:"generation"`
	ServedFrom      string `json:"served_from"`
	SnapshotReceipt string `json:"snapshot_receipt"`
}

OfflineRecord is one disclosed key during an offline serve. Every field is required: an unattributable record is worse than useless at reconciliation. RecordID is the idempotency key; it MUST be set by the caller before the plaintext op (so a retry re-sends the same id).

func Pending

func Pending(stateDir string) (records []OfflineRecord, handles []string, err error)

Pending returns all buffered records (flattened) and OPAQUE handles for the batch files holding them, sorted by handle so the local nanos ordering is stable. A handle is the batch file's bare basename; it is only meaningful to MarkFlushed, which resolves it strictly under stateDir/offline-records/.

type Probe

type Probe interface {
	AfterGenerationDirCreated(stamp string) error
	BeforeGenerationComplete(stamp string) error
	BeforeStampRename() error
	AfterGenerationMaterialized(target, stamp string) error
	AfterStampCommit() error
	BeforeGarbageCollection() error
	BeforeGenerationRemoval(stamp string) error
}

Probe is the crash seam (mirrors service.DeliveryConformanceProbe). Production leaves it nil; tests inject an error to simulate a crash at a deterministic durability boundary and assert the recovery invariant.

type PublishPhase

type PublishPhase string

PublishPhase is the latest durable stage reached by a publication.

const (
	PublishPhaseMaterializing PublishPhase = "materializing"
	PublishPhaseSwitching     PublishPhase = "switching"
	PublishPhaseCollecting    PublishPhase = "collecting"
	PublishPhaseComplete      PublishPhase = "complete"
)

type PublishPlan

type PublishPlan struct {
	RuntimeDir string
	Keys       *crypto.LocalKeys
	Targets    map[string][]byte
}

PublishPlan is the complete filesystem input for one Compose publication. Targets contains final rendered bytes only; snapshot rows, cursors, offline records, and other persistent bookkeeping deliberately remain outside this filesystem publication because they do not share its commit point.

type PublishResult

type PublishResult struct {
	Stamps       map[string]string
	Materialized map[string]bool
	Phase        PublishPhase
	ActiveStamps map[string]string
}

PublishResult records how far one recoverable filesystem publication got. Stamps are the plan's candidate stamps, Materialized reports whether each immutable generation was newly written, and ActiveStamps are the generations selected by the stamp file. A nil ActiveStamps means the active selection could not be inspected after an uncertain stamp-switch failure.

func (PublishResult) CandidateActive

func (r PublishResult) CandidateActive() bool

CandidateActive reports whether the candidate stamp selection is active.

type Refusal

type Refusal struct {
	Key    string
	Reason string
}

Refusal names a key that cannot be represented as a raw line and why.

func EncodeRaw

func EncodeRaw(rows []Row) ([]byte, []Refusal, error)

EncodeRaw renders rows to raw dotenv bytes. When any row is unrepresentable it returns (nil, refusals, nil): a partial file is never written. Row order is preserved.

type RenderInput

type RenderInput struct {
	AbsentKeys AbsentKeyPolicy
	Targets    []RenderTarget
	Rows       []RenderSourceRow
}

RenderInput contains every policy and datum needed to build a render plan. BuildRenderPlan performs no I/O and retains no reference to these slices.

type RenderLock

type RenderLock struct {
	// contains filtered or unexported fields
}

RenderLock is the held writer lock and the capability to mutate the runtime dir and the stamp file. It is returned by BeginRender and released by Close.

func (*RenderLock) Close

func (rl *RenderLock) Close() error

Close releases the writer lock. A second Close is refused, not a silent double-unlock.

func (*RenderLock) CommitStamps

func (rl *RenderLock) CommitStamps(stamps map[string]string) error

CommitStamps rewrites the managed block of <projectDir>/.env with the given per-target stamps and atomically renames it into place — the single commit point. The existing file is validated as carrying exactly one well-formed managed block BEFORE any rewrite; every non-managed line is preserved byte-for-byte; the file's mode and ownership are preserved (never widened), and a file that does not exist yet is created 0600.

func (*RenderLock) GC

func (rl *RenderLock) GC(runtimeDir string, keep int) error

GC removes generation directories not named by any current stamp beyond the `keep` most recent PER TARGET (by mtime). Current stamps are derived by reading the managed block itself, not trusted from a caller. It NEVER removes a current generation, removes INCOMPLETE directories regardless of age, and errors on a foreign entry. It is a method on the held lock.

func (*RenderLock) Publish

func (rl *RenderLock) Publish(plan PublishPlan) (PublishResult, error)

Publish owns the complete recoverable filesystem sequence for one render: materialize every immutable target generation, atomically switch the stamp file once, then collect superseded generations. It does not claim atomicity with snapshot, cursor, or offline-record persistence performed by callers.

On error, result states which stamps remain active and which deterministic candidates a retry will reuse. Before Committed, the previous stamp selection remains active. After Committed, the candidate selection is active even if GC fails.

func (*RenderLock) Recover

func (rl *RenderLock) Recover(runtimeDir string) error

Recover removes torn generation directories — those lacking their completion marker — under runtimeDir. Every top-level entry must be a valid stamp directory; a foreign entry is a hard error naming it. It is a method on the held lock, so it can only run under serialization.

func (*RenderLock) WriteGeneration

func (rl *RenderLock) WriteGeneration(runtimeDir string, keys *crypto.LocalKeys, target string, content []byte) (string, bool, error)

WriteGeneration writes an immutable generation directory <runtimeDir>/<stamp>/ holding one <target>.env (0600), fsynced, then a .complete marker written LAST, where <stamp> is computed here as TargetStamp(keys, content) — never supplied by the caller. The target name is grammar-validated and all I/O is directory-relative under an os.Root, so a crafted target or stamp cannot escape the runtime dir. It returns the stamp and whether it MATERIALISED the generation on disk (wrote it because the directory was absent or incomplete). A re-materialisation with an unchanged stamp is what tells `sync` to re-apply after a wiped tmpfs (R1-10): the config hash did not move, but the env_file vanished and must be recreated.

An existing COMPLETE directory is re-verified: its <target>.env bytes must re-stamp to the same name (immutable-by-construction), else it is a hard error, not a silent trust or overwrite. An existing INCOMPLETE one is a torn write: removed and rewritten.

type RenderOmission

type RenderOmission struct {
	Target string             `json:"target"`
	KeyID  string             `json:"key_id"`
	Name   string             `json:"name,omitempty"`
	Kind   RenderOmissionKind `json:"kind"`
}

RenderOmission records a configured row intentionally omitted from output.

type RenderOmissionKind

type RenderOmissionKind string
const (
	RenderOmissionAbsent  RenderOmissionKind = "absent"
	RenderOmissionNoValue RenderOmissionKind = "no-value"
)

type RenderPlan

type RenderPlan struct {
	Targets   []RenderTargetPlan `json:"targets"`
	Omissions []RenderOmission   `json:"omissions"`
	Refusals  []RenderRefusal    `json:"refusals"`
}

RenderPlan is the complete pure decision for one render attempt.

func BuildRenderPlan

func BuildRenderPlan(in RenderInput) (RenderPlan, error)

BuildRenderPlan applies target selection, absent-key policy, loader-control checks, raw-dotenv encoding, and snapshot-row collection.

type RenderRefusal

type RenderRefusal struct {
	Target string            `json:"target"`
	Key    string            `json:"key"`
	Kind   RenderRefusalKind `json:"kind"`
	Reason string            `json:"reason,omitempty"`
}

RenderRefusal is a typed, source-stable refusal owned by the plan. CLI adapters add command-specific framing without re-running policy.

type RenderRefusalKind

type RenderRefusalKind string
const (
	RenderRefusalKeyNotDelivered  RenderRefusalKind = "key-not-delivered"
	RenderRefusalKeyNotInSnapshot RenderRefusalKind = "key-not-in-snapshot"
	RenderRefusalSecretUnrevealed RenderRefusalKind = "secret-unrevealed"
	RenderRefusalLoaderControl    RenderRefusalKind = "loader-control"
	RenderRefusalEncoding         RenderRefusalKind = "encoding"
)

type RenderRowState

type RenderRowState string

RenderRowState is what an adapter-normalized delivery row carries. The three states are mutually exclusive, so a row cannot be both unrevealed and valued.

const (
	RenderRowValued           RenderRowState = "valued"
	RenderRowNoValue          RenderRowState = "no-value"
	RenderRowUnrevealedSecret RenderRowState = "unrevealed-secret"
)

type RenderSourceRow

type RenderSourceRow struct {
	KeyID          string
	Name           string
	Classification string
	State          RenderRowState
	Value          string
	Receipt        string
}

RenderSourceRow is one adapter-normalized delivery row. Value holds the plaintext only when State is RenderRowValued.

type RenderTarget

type RenderTarget struct {
	Name                     string
	KeyIDs                   []string
	AcknowledgeLoaderControl []string
}

RenderTarget is one ordered target selection supplied by an adapter.

type RenderTargetPlan

type RenderTargetPlan struct {
	Name         string        `json:"name"`
	Content      []byte        `json:"content"`
	SnapshotRows []SnapshotRow `json:"snapshot_rows"`
}

RenderTargetPlan is one target's exact bytes and snapshot rows.

type Row

type Row struct {
	Name  string
	Value string
}

Row is one raw-dotenv entry.

type RunSettings

type RunSettings struct {
	AcknowledgeLoaderControl []string `yaml:"acknowledge_loader_control"`
}

RunSettings is the top-level `run:` block: policy for `hikyo run --`, which delivers the whole environment rather than a per-target subset. Its loader-control acknowledgement mirrors the per-target field (compose ADR § "Loader-control keys"): `run` has no target, so the acknowledgement lives at the stack level.

type Severity

type Severity string

Severity levels.

const (
	SeverityError Severity = "error"
	SeverityWarn  Severity = "warn"
)

type SnapshotPayload

type SnapshotPayload struct {
	Rows             []SnapshotRow     `json:"rows"`
	GenerationStamps map[string]string `json:"generation_stamps"`
}

SnapshotPayload is the plaintext a snapshot seals: the delivered rows and the generation stamps that fetch produced.

func LoadSnapshot

LoadSnapshot validates the expected binding before reading snapshot.bin, parses its self-describing header into a delivery-complete binding, checks the offline-known scope, enforces rollback and expiry, then decrypts. maxAge is the per-stack downward override; the effective expiry is the earlier bound.

type SnapshotRow

type SnapshotRow struct {
	Name           string `json:"name"`
	KeyID          string `json:"key_id"`
	Classification string `json:"classification"`
	Value          string `json:"value"`
	Receipt        string `json:"snapshot_receipt"`
}

SnapshotRow is one delivered key inside a snapshot. KeyID is the immutable server key id: it travels INSIDE the sealed payload so the offline path can map row→key_id for its per-key reconciliation records without a cleartext sidecar (the self-describing snapshot subsumed the old offline.meta.json).

type SnapshotSettings

type SnapshotSettings struct {
	OfflineServe bool   `yaml:"offline_serve"`
	MaxAge       string `yaml:"max_age"` // e.g. "168h"; validated downward-only
}

SnapshotSettings is the per-stack offline snapshot policy.

type StateEntry

type StateEntry struct {
	Path        string
	Perm        os.FileMode
	IsDir       bool
	OwnedByEUID bool
}

StateEntry is one client state-directory node.

type Target

type Target struct {
	Keys                     []string `yaml:"keys"`
	Services                 []string `yaml:"services"`
	AcknowledgeLoaderControl []string `yaml:"acknowledge_loader_control"`
}

Target is one render target: the immutable key ids it delivers, the services that consume it, and any per-target loader-control acknowledgements.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer owns a per-project state directory and mints RenderLocks.

func NewWriter

func NewWriter(stateDir string, probe Probe) *Writer

NewWriter returns a Writer over stateDir. probe is nil in production.

func (*Writer) BeginRender

func (w *Writer) BeginRender(projectDir string) (*RenderLock, error)

BeginRender takes the non-blocking per-project writer lock and returns a handle scoped to projectDir (whose managed .env block is the stamp file). A second holder fails fast — a crash releases the lock (the OS drops it on process death), unlike an O_EXCL lock file that would wedge forever.

Jump to

Keyboard shortcuts

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