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
- Variables
- func Append(stateDir string, records []OfflineRecord) error
- func CurrentStamps(projectDir string) (map[string]string, error)
- func DefaultArgMax() int
- func EligibleCursor(state *CursorState, want CursorBinding, currentStamps map[string]string, ...) (string, bool)
- func ExecPreflight(env, argv []string, argMax int) (ok bool, detail string)
- func ExecSizePOSIX(env, argv []string, argMax int) (total int, ok bool)
- func ExecSizeWindows(env, argv []string) (cmdlineUnits, envUnits int, ok bool)
- func GenerationState(runtimeDir, stamp string) (present, complete bool)
- func IsTmpfs(path string) (bool, error)
- func MarkFlushed(stateDir string, handles []string) error
- func NewRecordID() (string, error)
- func SaveCursor(stateDir string, c CursorState) error
- func SaveSnapshot(keys *crypto.LocalKeys, binding crypto.SnapshotBinding, ...) error
- func TargetStamp(keys *crypto.LocalKeys, target string, content []byte) string
- type AbsentKeyPolicy
- type Collision
- type ComposeConfig
- type ComposeService
- type Config
- type CursorBinding
- type CursorState
- type DoctorInput
- type EnvFileRef
- type FileMode
- type Finding
- type OfflineRecord
- type Probe
- type PublishPhase
- type PublishPlan
- type PublishResult
- type Refusal
- type RenderInput
- type RenderLock
- func (rl *RenderLock) Close() error
- func (rl *RenderLock) CommitStamps(stamps map[string]string) error
- func (rl *RenderLock) GC(runtimeDir string, keep int) error
- func (rl *RenderLock) Publish(plan PublishPlan) (PublishResult, error)
- func (rl *RenderLock) Recover(runtimeDir string) error
- func (rl *RenderLock) WriteGeneration(runtimeDir string, keys *crypto.LocalKeys, target string, content []byte) (string, bool, error)
- type RenderOmission
- type RenderOmissionKind
- type RenderPlan
- type RenderRefusal
- type RenderRefusalKind
- type RenderRowState
- type RenderSourceRow
- type RenderTarget
- type RenderTargetPlan
- type Row
- type RunSettings
- type Severity
- type SnapshotPayload
- type SnapshotRow
- type SnapshotSettings
- type StateEntry
- type Target
- type Writer
Constants ¶
const ( // DefaultGenerationsKept is the retention per target beyond the current // stamp (ops-spec § 6: current + previous 3). DefaultGenerationsKept = 3 )
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 ¶
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).
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
ParseConfig strictly parses and validates a hikyo-compose.yaml document.
func (*Config) SnapshotMaxAge ¶
SnapshotMaxAge is the effective snapshot max age (default or the downward override).
func (*Config) TargetNames ¶
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 ¶
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 ¶
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 ¶
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 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 ¶
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 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 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 ¶
func LoadSnapshot(keys *crypto.LocalKeys, expect crypto.SnapshotBinding, now time.Time, maxAge time.Duration) (SnapshotPayload, crypto.SnapshotBinding, error)
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 ¶
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 (*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.