gamertan
9d9fc83dd0
Export the reviewed allowlisted snapshot from private source commit 8aab3db43f35e6a49aa497f45d73701b13fc9f32 and tree 992132ea4703437dc13ffdbb04a077816c02caf9. This includes routed singleton continuity, deployment evidence, strict schema-2 configuration, restricted transport, and the independently compilable public-tree guard. AI-Assisted: OpenAI Codex Signed-off-by: Cole Speelman <crspeelman@gmail.com>
81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# Architecture
|
|
|
|
Tend has three deliberately separate boundaries.
|
|
|
|
## Package boundary
|
|
|
|
`tend package` accepts only a clean checkout whose `HEAD` exactly matches the
|
|
configured pushed branch. It rejects Go module replacements and unversioned
|
|
dependencies, builds the configured main package twice with `GOWORK=off`, and
|
|
requires byte-identical output. The resulting archive contains only:
|
|
|
|
- the service binary;
|
|
- `RELEASE.json`;
|
|
- `BUILDINFO.json`;
|
|
- `SBOM.spdx.json`; and
|
|
- `SHA256SUMS`.
|
|
|
|
The external archive digest is the release identity used by deployment.
|
|
|
|
## Transport boundary
|
|
|
|
`tend push` sends one bounded protocol frame to a dedicated account through a
|
|
pinned OpenSSH host key. It uses an argument vector, disables config files,
|
|
forwarding, PTYs, local commands, and proxy commands, and requests exactly
|
|
`tend-receive-v1`. The account's forced command invokes only the root-owned
|
|
receiver. The receiver's root-owned policy maps an allowlisted service name to
|
|
one exact configuration path and size ceiling.
|
|
|
|
The target receives no source, repository credential, Go cache, dependency, or
|
|
arbitrary command. The artifact digest must equal both the produced digest and
|
|
the separately supplied approved digest before it is staged.
|
|
|
|
## Target-host boundary
|
|
|
|
Schema-2 configurations live below `/etc/tend/services/`. Secrets live only in
|
|
separate `/etc/tend/environment/*.env` files that are root-owned, non-symlink,
|
|
and mode `0600`. Configurations contain the path, never the values. Candidate
|
|
and installed units read the same file; Tend overrides only the candidate's
|
|
loopback listen address.
|
|
|
|
Dry-run validation extracts into a temporary directory and does not touch the
|
|
release tree. Activation acquires the shared lock, installs a content-addressed
|
|
release, verifies all embedded checksums and manifest fields, and starts the
|
|
candidate without evaluating configuration as shell code.
|
|
|
|
## Activation boundary
|
|
|
|
Blue/green mode points the inactive slot at the new release, restarts and
|
|
probes it, atomically replaces one imported Caddy handler, validates the full
|
|
Caddy configuration, reloads Caddy, and records the prior active slot.
|
|
|
|
Singleton mode starts the new release in a hardened transient systemd unit on a
|
|
separate loopback address and probes it. Tend then validates and atomically
|
|
routes the imported Caddy handler to that candidate. While the candidate serves
|
|
the canonical origin, Tend changes the current release pointer, restarts and
|
|
probes the installed fixed-address unit, validates Caddy again, and routes back
|
|
to it. The candidate remains healthy through the activation window and stops
|
|
only after the handoff succeeds.
|
|
|
|
After the local post-activation probes, Tend also checks configured HTTPS public
|
|
origins throughout a bounded activation window. Blue/green mode also probes the
|
|
previous slot, and singleton mode probes the handoff candidate, for health and
|
|
readiness throughout that window. Any failure before success is recorded
|
|
restores the previously observed Caddy bytes and/or release pointers. State
|
|
records desired, candidate, active, previous, and last-attempt
|
|
release identities, including failed attempts without claiming they became
|
|
active. Rollback is a separate explicit command
|
|
over the recorded state. It rechecks local health/readiness and public reachability,
|
|
but deliberately does not apply a future release's content marker to an older
|
|
release whose routes may differ. Pruning preserves both active and previous releases.
|
|
|
|
## Evidence boundary
|
|
|
|
Every attempted activation and explicit rollback emits bounded, versioned JSONL
|
|
events with an operation ID, service, approved artifact digest, source commit,
|
|
release version, phase, slot, elapsed duration, and outcome. Values are
|
|
validated rather than copied from command output. The log contains no
|
|
environment values, arbitrary process output, HTTP bodies, or secret paths.
|
|
Identity, entropy, file, and downstream observability failures are deliberately
|
|
best effort and cannot control Tend's deployment or rollback result.
|