Dist - API reference

The dist client's surface, as the seven calls this file makes of it.

Everything this file asks of the client goes through one value, so the boundary can be replaced whole. A suite that stubbed the registration itself would be grading a stub of our code; a suite that replaces the CLIENT grades ours, which is the only arrangement worth having.

PRESENT-P answers whether the image carries a client at all. WITH-HOME calls a thunk with the client rooted at a directory, which is how a registration lands in the node's own state rather than in whichever home the process inherited. INSTALL registers a pointer and answers the supplier's name. SUPPLIERS reports every supplier in the current home as a plist of :NAME, :PREFERENCE and :ENABLED. PREFER sets one supplier's preference by name. WITHDRAW removes any supplier recorded but not enabled. VERSION answers a supplier's version by name.

⚠ Suppliers are reported as plists and addressed by NAME, never as client objects and never by identity. The client builds a fresh object for each supplier every time a home is enumerated, so the handle in one reading is not the handle in the next, and an identity comparison is false for the very supplier that was just installed.

Signalled when the running image has no dist client at all.

Nothing about this is retryable and nothing about it is configuration. The answer is an image built to carry a client.

Signalled when the dist client refused the registration.

Whatever the attempt wrote has been removed before this is signalled, so a node that reports this refusal holds no partial supplier.

Root of every way registering a node's dependency source can refuse.

LOCATION is the dist pointer the attempt was driving, exactly as the caller gave it, so a report names the value the operator invoked with. CAUSE carries the underlying condition, never a rendered string, because being able to dispatch on it is why this hierarchy exists.

Signalled when nothing names the dist to register.

SETTING is the name of the setting that answers it, so the refusal tells the operator what to fill in rather than that something is missing.

Signalled when the image cannot reach the configured location.

SCHEME is the URL scheme that has no client here. Distinct from a registration failure because nothing was attempted: no request was made and no dist home was touched.

Signalled when a file the dist client asked for did not arrive.

Deliberately NOT under DEPENDENCY-SOURCE-ERROR. It is a cause rather than a refusal: it reaches the caller as the CAUSE slot of a registration failure, and putting it under that root would let it leave the registration untranslated, carrying a status where the caller expects a refusal it can act on.

(dependency-source-error-cause condition)

Undocumented: this exported symbol needs a docstring.

(dependency-source-error-location condition)

Undocumented: this exported symbol needs a docstring.

(dependency-source-unconfigured-setting condition)

Undocumented: this exported symbol needs a docstring.

(dependency-transport-absent-scheme condition)

Undocumented: this exported symbol needs a docstring.

(dist-fetch-rejected-status condition)

Undocumented: this exported symbol needs a docstring.

(dist-fetch-rejected-url condition)

Undocumented: this exported symbol needs a docstring.

(dependency-client-present-p &optional (client (%client)))

True when CLIENT can register anything, which for the image's own client means that the image carries one.

The client is not a declared dependency of valis and never has been. It reaches a delivery image because the build loads the build host's own dist setup and then dumps that same process, which makes its presence a property of the machine the binary was built on. Reporting it is what turns that from an accident nobody would notice into a fact a node states about itself.

(dist-client-p object)

Undocumented: this exported symbol needs a docstring.

(image-dist-client)

The client this image carries, driven through the client tree it was built with.

(make-dist-client &key ((:present-p present-p) nil) ((:with-home with-home) nil) ((:install install) nil) ((:suppliers suppliers) nil) ((:prefer prefer) nil) ((:withdraw withdraw) nil) ((:version version) nil))

Undocumented: this exported symbol needs a docstring.

(register-dependency-dist &key location home (lookup (function config-lookup)) (client (%client)))

Register the private dist as this node's dependency source, make it authoritative, and answer a plist reporting what was registered.

LOCATION is the dist pointer, defaulting to what the site configuration names. HOME is where the registration is recorded, defaulting to the node's durable state. LOOKUP is the setting reader and CLIENT is the dist client, so the whole registration can be driven without touching either the process environment or this image's own suppliers.

Running it a second time against the same home leaves the node with exactly one registration rather than an error, which is what a re-run of provisioning needs and is worth stating because losing it turns the second run into a failure.

Refuses with DEPENDENCY-CLIENT-ABSENT, DEPENDENCY-SOURCE-UNCONFIGURED, DEPENDENCY-TRANSPORT-ABSENT or DEPENDENCY-REGISTRATION-FAILED, each of which is a different next act for the operator. A RETRY restart stands around the whole registration, so a caller in a position to fix a transient reach can take one and have the attempt made afresh.

(resolve-dependency-dist-home &optional (lookup (function config-lookup)))

The directory the registration is recorded in.

Rooted under the node's durable state by default, so it lands in the directory the unit was already given and survives a restart, and overridable for a node whose operator has put durable state somewhere the default does not reach.

(resolve-dependency-dist-location &optional (lookup (function config-lookup)))

The dist pointer this node registers, dist.url, or NIL when nothing names one.

LOOKUP is the setting reader and defaults to config-lookup, so a caller can supply the value without touching the node's configuration or the process environment.

The client registrations are driven through, or NIL to use this image's own.

Bound rather than set, so a suite drives a whole registration against a client it supplies and grades this file's decisions instead of the dist client's.

The setting that overrides where the registration is recorded.

The setting that names the dist a node registers as its dependency source.