Environment Contract

link-env-contract is the environment file, read strictly as every spec is, its stages, and the wire requests and process clients other modules reach an environment through. It also gives a run the secrets its file asks for that you approved for it. Running it is lnk-env's.

The environment file

file reads it (read, from a path, every file it names checked; parse, from text, by its type alone), refusing an unknown key, a missing spec or input, and a value that can't be, each naming its line. It reads version 1 (VERSION).

What it names

It names no harness, no cloud and no box: its name (lowercase letters, digits and dashes, which its boxes and images are named by), its os (none, any, with an image for each), its workdir (where a job's command and an agent start, from the home folder), variables given to every run as they are, its stages and its services.

A stage of the file

Each has run, a command line for sh -c; sandbox, the sandbox spec it runs in, from the file's folder; user, who it runs as; inputs, files whose contents count in the image's hash; timeout; and when it runs, saved in the image or at every start.

A service of the file

Each has run, a command line that runs until it's stopped; its sandbox and user (root only on a box of its own); reset, a command line putting it back as the image had it; and how it's ready: a port on the machine's loopback taking a connection, or a run that passes in its sandbox, waited on for its timeout, 60 seconds when the file says nothing (READY_TIMEOUT).

Its image's hash

hash is what an image is found by on a platform, an OS and a processor. It covers the environment name, work directory, variables, and saved stages, including their commands, users, sandbox files, and declared input contents. Start-only stages and services do not change the image hash.

How a job is kept apart

isolation reads it from what the job may do and who started it, never chosen: a job needs a box of its own when someone other than you started it, or when its command runs as root (own_box_because).

Stages

stage is the one stage shape, shared by environments, jobs and compositions: a stage alone or a parallel group of them (check_groups checks the groups before any command starts, where stages are sent from and where they run).

Run

A stage as the machine it runs on is sent it: its name, run, its sandbox spec as text so nothing is read there from a path (none for root), a protected sandbox the runner verifies its spec against, its user, and its own timeout within the whole run's.

Timeout

Timeout bounds how long an operation may run, from a second to a day. It accepts duration strings such as 30s, 10m or 2h, which callers apply within the whole run's deadline.

Each step timed

A run's steps, its setup, a service made ready or a stage, are each timed whatever their outcome (Timed), and lnk env here says each outcome after the stage's seconds.

lnk env here

here is what lnk env here is asked on its input's first line, once it has said what to seal to on its output: the environment's name, its file, the action, the secrets sealed to a key that run made, and the mark each line saying how it went starts with, so a command's own output can't pass for one.

Its actions

image, the stages saved in an image; setup, the same with no image saved, on a computer only those in a sandbox; start, the stages run at every start then the services, which outlive it; run, those stages, the services it needs, then the stages given, the first that fails ending it with its exit code (124 at its timeout); reset of a service; and stop, which stops services previously started in the background.

A run's own folder

A run may be given variables, secrets by name, a folder made new for its stages to leave files in (Out, from the home folder, its path in a LNK_... variable), and a profile to sample.

Where its files are

An environment's files are in Link's settings on a machine, which no sandbox reads or writes (files_dir).

Secrets a run is given

values gives a run the secrets its environment's file names that you hold, each plain or sealed as its file names it, once you've said yes (approvals). of takes an Asker, you at a terminal or no one, and of_yours asks on this process's terminal where there is one; a name with no yes that no one can answer is refused, naming the command that approves it. A job's run (of_job, of_unattended) is given none.

Approvals

approvals keeps your yes in the Safe (~/.lnk/safe/envs/approvals.toml), each for a spec's real path, its name, the secret's ID (secret:<id>) and the name the spec asks it by. It reads your secrets through the secret contract (list, for_you), and leaves out an approval whose secret is no longer kept, dropping it at the next write, so deleting a secret removes its approvals.

An image's build

An image's build is given nothing, since an image keeps what its stages wrote, so a file naming a secret is refused there (sealed).

Blanked in output

Blank replaces every value given in a text with *** (BLANK), as GitHub does in its logs: a backstop, not the wall, since a value encoded on its way out isn't caught. Read as a stream, a value split between pieces is still caught.

An environment carried and run

The contract carries reviewed files and prepares them on the target machine, while the remote runner and profiler report execution through existing module interfaces.

Packed

Packed carries the environment file, its declared text files and its image hash, never secret values. Capture holds authoring directories open and refuses symbolic links, hard links, non-regular files and paths outside that origin. Prepared is lnk env prepare and import's answer, with paths on the machine that prepared it.

On a box

remote runs the environment on a box from your computer, each step a lnk box ... command as a person would type it, and what runs there is lnk env here, over SSH (lnk box run). A box it makes is never signed in to its account, since an image build or a job runs code it was handed.

Private base preparation

remote::prepare_private copies captured files to an existing private guest and applies uncached preparation there without selecting or publishing an image. Its GuestLogin says what the guest's login gives: Root for a Linux guest, or Ordinary with a macOS guest's approved user. check_login then refuses any stage or service running as root or as another user before a file is copied. Startup and services follow preparation when requested. Existing root, secret and sandbox checks still apply. A borrowed machine can receive the current files without rerunning image preparation.

A job's profile

profile samples a job's processes at each stage's edges and every while: memory used and its peak, core-seconds, and bytes read and written, each named as the measure contract names it, and none, never zero, where it can't be read.

Where it runs

cli::at resolves shared Slots into At::Here, At::Box, or At::Cloud. --here selects this machine, --on names a box or a machine of the Local Cloud, and --cloud selects a cloud account with an optional zone. The caller supplies those slots while the contract carries the work.