valis / Reference / API reference

Fabric - API reference

Exported surface for the fabric subsystem. Part of the API reference.

Package valis/src/fabric

Conditions

module-manifest-read-failed

The module manifest could not be read because the file system failed the read, not because it is damaged. KIND tells a failure a later read may get past from a file this process is not permitted to read, which stays so until its owner changes it.

module-root-tree-unreadable

The tree the durable head names could not be read while the boot looked for its module manifest. Unlike a manifest that cannot be read, this is not a fault of the module set alone: the same tree holds everything else the node keeps, so the boot ends. KIND tells a fault a restart can clear, an I/O failure, from damage or a refused permission, which will be met again on every restart.

node-dns-serve-refused

Signalled when this node's DNS serve loop cannot be started over a socket the host agent sent, before any socket is touched: the loop is already running, or there is no DNS view and nothing to bind one over, or no handler is admitted to answer with. REASON says which, in words an owner's reply can carry.

node-mail-serve-refused

Signalled when this node's mail serve leg cannot be started. REASON is a keyword naming why: :already-serving, :no-store, or a reason start-mail-serve answered. DETAIL says the same in words an owner's reply can carry.

owner-key-required

Signalled fail-closed when start-fabric finds an existing durable store (a head in any form) but no owner keyfile. No new DID is minted on this path: the owner key must be acquired out of band. A clean install (no store head AND no keyfile) auto-creates the keyfile instead.

vouch-store-required

Signalled fail-closed when start-fabric must re-admit recorded modules and finds no vouch store at the path it names. PATH is that path. Nothing is written.

Generic functions

module-manifest-read-failed-cause

(module-manifest-read-failed-cause condition)

Undocumented: this exported symbol needs a docstring.

module-manifest-read-failed-kind

(module-manifest-read-failed-kind condition)

Undocumented: this exported symbol needs a docstring.

module-root-tree-unreadable-cause

(module-root-tree-unreadable-cause condition)

Undocumented: this exported symbol needs a docstring.

module-root-tree-unreadable-kind

(module-root-tree-unreadable-kind condition)

Undocumented: this exported symbol needs a docstring.

node-dns-serve-refused-reason

(node-dns-serve-refused-reason condition)

Undocumented: this exported symbol needs a docstring.

node-mail-serve-refused-detail

(node-mail-serve-refused-detail condition)

The reason the mail serve leg could not be started, in words an owner's reply can carry.

node-mail-serve-refused-reason

(node-mail-serve-refused-reason condition)

The keyword naming why the mail serve leg could not be started: :already-serving, :no-store, or a reason start-mail-serve answered, such as :no-arrival.

owner-key-required-keyfile

(owner-key-required-keyfile condition)

Undocumented: this exported symbol needs a docstring.

vouch-store-required-path

(vouch-store-required-path condition)

Undocumented: this exported symbol needs a docstring.

Functions

boot-trial-failure

(boot-trial-failure)

One line naming the rollback trial the running node's boot ended as failed, why it failed, and the generation the node returned to. NIL when the boot ended no trial, or no fabric is running.

claimed-held-descriptors

(claimed-held-descriptors held &key (owner-port +owner-terminus-port+) (dns-udp-port +dns-service-port+) (dns-tcp-port +dns-service-port+) (mail-port +inbound-mail-port+))

The descriptor in HELD each service takes, as the plist (:dns-udp :dns-tcp :edge :mail :owner), each value an fd or NIL. Selection is by bound port and transport only, never by the flag a descriptor arrived under, and a NIL port claims nothing. MAIL-PORT names the port inbound mail answers on. The DNS halves are claimed only as a pair; a second value is the fd of a lone half, or NIL.

earliest-presented-not-after

(earliest-presented-not-after)

The least not-after, a universal time, among the leaves presented on either leg: the live :443 base and every cell its set files, and every cell of the mail set in force. NIL when neither leg presents a leaf. An emptied cell counts for nothing, so after withdraw-expired-credentials this is the next live not-after.

installed-module-systems

(installed-module-systems)

The system names of the installed modules the durable module manifest names, or NIL when the node holds no durable store. Signals as %installed-modules does when the manifest or its root tree cannot be read.

installed-module-systems-at

(installed-module-systems-at store-data-dir)

The system names of the installed modules the durable module manifest names in the store rooted at STORE-DATA-DIR, read without a running fabric, or NIL when no store head is there. Signals as %installed-modules does when the manifest or its root tree cannot be read.

loopback-host-p

(loopback-host-p host)

Return T when HOST names a loopback interface: IPv4 127.0.0.1, IPv6 ::1, or the symbolic name localhost (case-insensitive). Mirrors seven's own loopback allowlist; kept here so valis does not import from seven's CLI package.

module-manifest-unreadable

(module-manifest-unreadable)

Why the running node could not read its module manifest, when its boot stood up the resident set with no installed modules for that reason, or NIL when it read the manifest, there was none, or no fabric is running.

modules-refused-at-boot

(modules-refused-at-boot)

Each module the running node is not serving because its boot refused it, as (name . reason): the recorded modules it left out, by system name in the manifest's order, then each module whose active part did not start, by its system name when it was admitted and otherwise by the name that part registered. Empty when every recorded module came up, and when no fabric is running.

node-dns-serving-p

(node-dns-serving-p)

True while this node's own DNS serve loop runs: the one its boot started over the descriptors the launch handed down, or one started later over a socket the host agent sent.

node-mail-ports

(node-mail-ports)

The ports this node's mail serve leg registered its protocol under, or NIL when no leg runs.

node-mail-serving-p

(node-mail-serving-p)

True while this node's mail serve leg runs, whoever started it.

note-module-refused-at-boot

(note-module-refused-at-boot name reason)

Add NAME, a module the boot left out after the fabric came up, to those modules-refused-at-boot names, with REASON, after the ones already there.

open-public-edge-from-custody

(open-public-edge-from-custody leaves)

Open the :443 edge over the arrival start-fabric recorded in public-edge-arrival, from LEAVES, one read of custody, and answer T when it opened, else NIL. Opens only when all of these hold:

  • no :443 listener is admitted;
  • an arrival is recorded;
  • edge.domain names a domain;
  • LEAVES holds a usable leaf for it.

The base cell and the served-name set are built from LEAVES before the lock is taken; the check for a live listener and the start run under served-configuration-lock. The handle goes to tls-serve-started-by-boot, so every stop path tears it down. Claims no port into the served set and never reads custody. A refusal or a condition from the start is logged once at WARN until an open succeeds or the arrival is cleared, and never signalled. Lock order: custody-reload-lock before served-configuration-lock, never the reverse.

ports-other-services-take

(ports-other-services-take)

The ports claimed-held-descriptors selects a descriptor on for a service other than the owner terminus, at their defaults: DNS, the public edge, and inbound mail.

presented-certificates-for-name

(presented-certificates-for-name name)

Answer two values: what a client asking for NAME by SNI is handed on :443, then on :25 after STARTTLS. Each is the summary of that leaf, a plist of :fingerprint and :not-after. When there is no such leaf, :443 answers :no-edge with no listener admitted and :none when the credential it would hand out is empty; :25 answers :not-offered when the mail leg is not running or offers no STARTTLS. On both legs the leaf is the credential covering NAME, else the base. Holds no key material.

public-edge-held-p

(public-edge-held-p)

True when this fabric holds a :443 edge handle, whether the boot opened it or a custody re-read opened it after start.

record-module-stand-up

(record-module-stand-up event system phase &key designation)

Stand-up observer that keeps the module boot record: on :begin, name SYSTEM in PHASE on disk before its code runs; on :end, clear that name.

register-module-mailbox

(register-module-mailbox name)

Register a mailbox named NAME on the live valis bus and return the mailbox-dir. Signals an error if the fabric is not running (valis-bus is nil). That is a programmer error: a module should not try to register its mailbox before start-fabric has run.

reload-certificates-from-custody

(reload-certificates-from-custody)

Withdraw every leaf in force past its not-after on both legs, through withdraw-expired-credentials, before custody is read and whatever the read then answers; those :expired entries open the report and are logged even when custody cannot be read. Then read certificate custody once and bring both legs to what a start over that custody would present, from that one read: the mail set first, then the :443 base credential, reloaded in place or emptied, then the set the live :443 edge holds. A node whose boot held an arrival for :443 and has no :443 listener opens it from this read when custody holds a usable base for edge.domain, through open-public-edge-from-custody, and reports each name it serves :added. A name whose pair reads inconsistent keeps the unexpired leaf in force for it. A removed or expired base leaf empties the base, so every :443 handshake is refused until custody holds a usable one, and logs cert.edge-dark once. Custody read and holding nothing installs that empty outcome on both legs. While an engaged operator-state pool cannot be read, the names in force stay served as custody holds them and names owned zones would add wait. Answer the change report, a list of plists, one per leg and name whose presented leaf changed or was held: :leg :443 or :25, :name, :old and :new fingerprints or NIL, and :reason, one of :replaced, :removed, :expired, :added or :held-inconsistent; an entry with :reason :additions-waited and no name says additions waited on operator state. NIL when nothing changed. Each change is logged once, with fingerprints only. When custody cannot be read, neither leg changes beyond those expired withdrawals, cert.custody-unreadable is logged once until a read succeeds, and the answer is :custody-unreadable. After anything is installed or withdrawn on either leg, the session-ticket key is replaced at once and once more after the handshake deadline, so no session resumes under a certificate no longer in force; a re-read that installs nothing replaces no key. Serialized by custody-reload-lock. Unreadable custody, a failed withdrawal and a :443 set that cannot be rebuilt, which keeps the set in force, are logged, not signalled.

serve-node-dns-over-socket

(serve-node-dns-over-socket udp-fd)

Start this node's DNS serve loop over UDP-FD, a UDP socket bound to the DNS port that the host agent sent, and return its handle. The agent sends one when 53 is configured and the node holds no UDP socket for it: at boot on a node launched without the DNS pair, or when the owner declares 53 later. The loop answers UDP on that socket and TCP on whatever the steer delivers for the DNS port, and it is wired as the boot wires the loop it starts over the pair the launch hands down: the refresh push and outbound NOTIFY beside it, and the whole of it torn down by stop-fabric.

A node whose boot bound no DNS view binds one first, over the zone source the boot was given for this, so a node launched without the pair serves the same zones a node launched with it would.

UDP-FD stays the caller's: the loop answers on a copy of its own. Signals when the loop is already running, when there is no view and no zone source to bind one over, or when any step fails. A loop that started and could not have its companions wired is stopped again before the signal leaves; a view bound on the way stays bound and is torn down with the fabric. Runs under the served configuration lock, which stop-fabric also takes, so a loop started here is either stopped by that stop or started after it with nothing left to start on.

serve-node-mail

(serve-node-mail)

Start this node's mail serve leg over the durable store in pub-store and return its handle. Binds the mail configuration first, then starts c3po's engine on the arrival the node has, in this order: when the boot holds a steered source, the protocol claims inbound-mail-port on it and no source is built, so nothing is bound and the teardown never closes the boot's socket; else the descriptor the launch handed down when one is recorded in mail-descriptor-inherited-by-boot; else a self-bound socket on mail-self-bind-port when that is set; and nothing otherwise. Records the handle in mail-serve-started-by-boot, so stop-node-mail-serve and every stop-fabric path tear the leg down, and claims each port the protocol registered under with claim-service-port once registration succeeds, so the effective served set names it.

Signals node-mail-serve-refused, before any socket is touched, when the leg already runs or pub-store is not a store-store, and when start-mail-serve refuses. Runs under the served configuration lock, which stop-fabric also takes.

start-fabric

(start-fabric port &key (host "127.0.0.1") (keyfile (merge-pathnames "keyfile" (%valis-data-root))) (revocation-path (merge-pathnames "revocation" (%valis-data-root))) (pub-data-dir nil) (store-data-dir nil) (pub-store-backend :store) (evacuative nil) (local-domains nil) (dns-zone-source nil) (dns-descriptor-version +descriptor-admission-contract-version+) (held-descriptors nil) (dns-udp-port +dns-service-port+) (dns-tcp-port +dns-service-port+) (dns-serve-make-exchange nil) (dns-zone-source-on-declare nil) (mail-resolver (make-mail-resolver-source (%configured-mail-resolver))) (edge-tcp-port nil) (edge-credential-cell nil) (mail-tcp-port nil) (mail-port +inbound-mail-port+) (owner-port +owner-terminus-port+) (session-max-idle *session-max-idle-seconds*) (module-source-root nil) (module-boot-record nil) (vouch-store-path nil) (publisher-custody-directory nil))

Bring up the 9P fabric: build the namespace tree (the /proto, /bus, /id, /cap, /pub children), then start seven's listener on HOST:PORT against a fresh valis-root. PORT 0 selects an ephemeral port; the bound port is readable via (listener-port nine-p-listener).

SESSION-MAX-IDLE bounds how long an owner session may go untouched before its next operation fences it, in seconds, or NIL for no bound. It defaults to whatever the deployment has already configured, and that is NIL out of the box: an upgrade must not start cutting sessions off that nobody asked it to cut off. A node that wants the bound sets it, and RECOMMENDED-SESSION-MAX-IDLE-SECONDS is the value to reach for absent a reason to differ.

MODULE-SOURCE-ROOT is the directory the modules recorded in the durable manifest are read from, one identity directory per module, when a boot over an existing head re-admits them, whether or not it evacuates. The resident passes the root its operator configured; it defaults to NIL, and a stand-up that then finds a module to re-admit refuses that module rather than reading it from anywhere else. A recorded module that is refused does not run: it is logged by name with its reason, the node serves everything else, and modules-refused-at-boot names it for as long as the node runs.

MODULE-BOOT-RECORD is the path of the module boot record, which names on disk the recorded module a boot is standing up before its code runs. A boot that finds a module named there counts a death against it, and a module the node died in on module-boot-attempts boots running is left out, by name, without loading any of it. It defaults to NIL: nothing is read or written, as every scratch fabric wants.

KEYFILE is the path the factotum custody store is rooted at; it carries the owner's Ed25519 secret seed so the same did:key survives image restarts. REVOCATION-PATH is the persistence path of the capability revocation store. Both default to keyfile and revocation under the XDG valis data root (<xdg-data-home>/valis/), so a bare (start-fabric port) roots durable state where a launcher can point it with $XDGDATAHOME. Tests pass scratch paths so a test run never reads or writes the operator's real owner key.

VOUCH-STORE-PATH is where the owner's vouch store is kept: the publishers this node trusts, their vouches and lists, and the owner's grants. It defaults to NIL, which resolves to the revocation store's path with the type vouch, so a scratch revocation path keeps a test's vouch store scratch too. When no vouch store is there, the node begins and writes an empty one, unless its durable module manifest names installed modules: their credentials are missing, so it refuses with vouch-store-required, whatever kind of boot this is.

PUBLISHER-CUSTODY-DIRECTORY is where mercer keeps the publisher's signing key for the owner's signing door, cap/sign. It defaults to NIL, which resolves to publisher in the revocation store's directory, the node's data root in production. Nothing is written there until the owner provisions a key, and no node backup carries it: a lost signing key is replaced and its delegation revoked, never restored.

PUB-DATA-DIR is the root directory for the publication filesystem store. Defaults to nil, which resolves to <xdg-data-home>/valis/publications/ at start time. Tests pass a temporary directory so no test run touches the operator's real publication data.

PUB-STORE-BACKEND selects which backend serves /pub. :store (the default) wires the durable content-addressed store rooted at its own data directory. :fs wires the POSIX filesystem store under PUB-DATA-DIR, retained so an operator can fall back to the v1 backend. Any other value signals.

STORE-DATA-DIR is the durable store's own root, distinct from PUB-DATA-DIR (the head and blocks are decoupled from the POSIX publication layout). Defaults to nil, which resolves to <xdg-data-home>/valis/pub-store/ at start time. Tests pass a temporary directory so no test run accretes into the operator's durable store.

The durable default starts empty on first boot: a fresh content-addressed store serves an empty /pub. Existing fs-store publications under PUB-DATA-DIR are NOT migrated into the durable store (migration is a later phase). An operator who needs continuity of existing /pub content on the first durable boot should pass :pub-store-backend :fs.

For a non-loopback HOST, fabric-auth-enabled-p must be T: seven's start-listener does not gate the host string itself, so this is the in-process equivalent of seven's CLI validate-loopback-host check.

EVACUATIVE selects the stand-up regime over an existing durable head. Default nil is the coincident regime: a stand-up over an existing head shares the store unfenced, performing no head bump and no fence: a scaling peer must never fence a sibling. Non-nil is the evacuative regime: the stand-up fences the superseded instance as its first durable act, appending the prior generation's fence to the revocation log, advancing the head over the same root tree, then sweeping the prior writer's live grants. A genesis create takes no fence: there is no prior generation to supersede. So a bare (start-fabric port) keeps the prior coincident behavior. Either regime over an existing head stands the installed modules back up; only the fence and the head bump belong to evacuation.

LOCAL-DOMAINS is the set of mail domains this fabric delivers locally (a list of domain strings). It answers the router's recipient-local-p seam: a recipient in one of these domains delivers into the owner's inbox, and any other recipient is non-local. Unpassed, it is read from mail.local-domains. With no local domain configured every recipient is non-local, so nothing is locally delivered and the open-relay guard governs every relay attempt.

MAIL-RESOLVER is the outbound MX resolver the /mail axis threads into the /ctl drain, defaulting to one built from the node's configuration by %configured-mail-resolver. It resolves a relay recipient's MX over the real wire (DoT) at drain time. Defaults fail-closed: with no DoT upstream configured (or runciter's real-wire resolver absent), build-mail-resolver yields nil, and a nil resolver makes the drain DEFER every relay entry (there is no smarthost fallback), so mail never leaves over an unresolved or unauthenticated channel. A caller may inject a resolver directly.

DNS-ZONE-SOURCE is the zone-data-source the DNS view binds over at boot (in production a pg-zone-source over the operator's own zone data). Defaults to nil: a bare (start-fabric port) binds no DNS adapter and keeps the prior DNS-seam behavior exactly, and (because this boot bound nothing) leaves any same-name adapter bound elsewhere untouched on every teardown path. A non-nil source first clears the descriptor-admission precondition, then binds the DNS view. The precondition runs inside this bring-up's unwind, so a refused precondition leaves no DNS adapter behind. No :53 socket is opened here; this wires the bind path only, and no foreign module code is admitted on it.

DNS-ZONE-SOURCE-ON-DECLARE is the zone-data-source the DNS view binds over when the node starts answering DNS on a socket the host agent sends and no view is bound: once the fabric is up, on a node configured for 53 and launched without the DNS pair, or later when the owner declares 53. start-fabric itself never reads it, so a node with no zone data to serve still comes up. Defaults to nil, and DNS is then reported as not answering.

DNS-DESCRIPTOR-VERSION is the descriptor-admission contract version threaded into that precondition. Defaults to this valis's own supported version, so a bare boot always clears; a caller (a descriptor steered in from upstream) supplying a version that skews from the supported set refuses the boot bind fail-closed through the same precondition. The precondition also refuses when the pinned admission chokepoint symbol is absent. The owner-vouched-hash admission of a steered descriptor runs on the path where the descriptor is actually steered in, upstream of which this precondition is the gate.

HELD-DESCRIPTORS is what this node was handed: the already-interrogated sockets it holds, each carrying the port it is bound to and whether it is a stream or a datagram. The fabric wires a service to the one that answers for that service's own port, so which argument a descriptor arrived in means nothing here and no parameter name encodes a service. Defaults to nil, holding nothing, which is the bare boot: every service falls to whatever it does when nobody handed it a socket.

How a port reaches this process is the host agent's question, settled on host-OS grounds this node holds no opinion about. What the fabric asks is only whether a socket for the port a service answers on is already in hand.

The transport is part of that question rather than a detail beside it: :53 answers over UDP and TCP at once, and the two take deliberately different concurrency paths, so a query reaching one socket whose reply left by the other would be answered by nobody.

DNS-UDP-PORT and DNS-TCP-PORT name the port the DNS service answers on, per transport, and default to the protocol's own 53. DNS has no self-bind at all: it serves only over descriptors handed to it, and holding one without the other wires nothing.

OWNER-PORT names the port the routable owner terminus answers on and defaults to

  1. Hold a descriptor for it and the terminus comes up over that socket beside

the loopback management fabric, gated on the auth seam being engaged. Hold none and no terminus comes up, which is the default-closed posture.

MAIL-PORT names the port inbound mail answers on and defaults to 25. A descriptor held for it is recorded in mail-descriptor-inherited-by-boot and nothing is started on it here: whether mail runs on the wire is the mail switch's decision, taken once the fabric is up by follow-configured-mail-serve, which adopts the descriptor when the switch is on. MAIL-TCP-PORT is accepted and ignored. With a store-store and the operator-state database engaged (as mail-queue-check answers), the start binds the mail configuration and starts the standing delivery loop; neither a held mail descriptor nor a port takes part in that.

EDGE-TCP-PORT is the dev loopback fallback for the :443 edge, retained unchanged: nil selects an ephemeral loopback port, and the public edge's own descriptor is recognised by the port a public edge answers on rather than by this value. EDGE-CREDENTIAL-CELL is the shared mercer server credential the :443 listener holds by reference, the same cell a renewal reloads, so the public surface never drops. The :443 edge is cert-gated: it wires only when the cell holds a usable chain+key, and start-tls-serve refuses otherwise, so a bare boot (nil cell, no issued cert) leaves :443 dark and still completes bring-up. Defaults nil so the prior behavior of a boot that wires no public edge is unchanged.

Returns the listener handle. On failure, the namespace seam variables and nine-p-listener are left nil so a subsequent stop-fabric or start-fabric sees a clean slate.

start-owner-terminus

(start-owner-terminus owner-fd owner-port root)

Serve ROOT, a 9P attach root, as the routable owner terminus over OWNER-FD, an inherited listening descriptor answering for OWNER-PORT, and claim OWNER-PORT in the protocol registry. Sets owner-terminus-listener and owner-terminus-port-claim and returns the listener; a NIL OWNER-FD starts nothing and returns NIL. Signals when the auth seam is disengaged: a routable terminus that admitted an attach without the Noise handshake would be an open owner surface. A refused claim signals with the listener already recorded, so the caller's unwind has a listener to stop. The adopted socket source dups OWNER-FD, so stop-owner-terminus closes the dup and never the inherited descriptor. The claim carries a handshake deadline and an origin cap: the terminus is reachable from off the host, and a silent or crowding origin would otherwise hold slots the public ports share.

start-recovery-mail-transport

(start-recovery-mail-transport &key (data-root (%valis-data-root)) (store-backend :store))

Bring up the mail transport for a recovery start, with no 9P listener, edge, DNS, or module work, and answer the names of the pieces it could not start, as strings, in order. Under DATA-ROOT, in order:

  • read the owner's custody from the keyfile, never creating one;
  • open the durable store;
  • engage the operator-state PostgreSQL the transport queue lives in;
  • bind the mail configuration and mail.local-domains;
  • wire the /mail seams with the local-delivery resolver and the notice lander, as start-fabric does;
  • start the standing delivery loop when the operator-state engaged (as mail-queue-check answers for it); otherwise wire /mail with the inbox alone and the notice lander in direct mode, and log mail.delivery-loop skipped with reason no-operator-state.

STORE-BACKEND is :store, or :fs for a node on the filesystem fallback, which keeps no durable mail store. Each piece it cannot start logs recovery.rung at WARN naming it: no-store-store, owner-key, or durable-store end the rung there; operator-state, no-local-domain, and delivery-loop-still-running leave the rest standing. Logs recovery.rung at INFO when nothing is missing. Never signals.

start-recovery-owner-door

(start-recovery-owner-door owner-fd owner-port &key (data-root (%valis-data-root)))

Serve the status-only owner door of a recovery start on OWNER-FD, the inherited owner descriptor answering for OWNER-PORT (NIL for owner-terminus-port), and answer true when it serves. The door is the owner terminus start-fabric stands up (start-owner-terminus), over a recovery root: the same handshake, keyring and owner gate, and a frame holding /node/development/status and /node/release/report only. It reads the owner's custody from DATA-ROOT's keyfile when none is held, never creating one. A piece it cannot start logs recovery.rung at WARN with rung owner-door and answers NIL: owner-descriptor when OWNER-FD is NIL, owner-key when the keyfile is absent or unreadable, owner-terminus when the terminus does not start. Logs recovery.rung at INFO when it serves. Never signals.

stop-fabric

(stop-fabric)

Stop the 9P fabric cleanly. Idempotent: calling on an already-stopped fabric is a no-op. Clears nine-p-listener, the edge seam's cached sessions and grant, and all namespace seam variables so a subsequent start-fabric begins from a known state. The edge seam is reset first, before the 9P listener stops, so the seam never holds a session into a partially-torn-down tree.

stop-node-dns-serve

(stop-node-dns-serve)

Stop this node's DNS serve loop and close every socket it answered on, and answer whether a loop was running. UDP and TCP on the loop's own descriptors stop answering, and so does TCP on the DNS port arriving over the steer. When the loop was answering on the pair the launch handed down, that pair is closed as well, so the node holds nothing bound to a port it no longer serves.

This is the one place the inherited pair is ever closed, and it closes it once: the record of the pair is taken and cleared before either descriptor is closed, and nothing else keeps the numbers once the boot is up. A number the kernel hands out again afterwards belongs to whatever opened it, and no later stop or undeclare reaches it.

The DNS view, the refresh push and outbound NOTIFY stay as they are: they follow the zone data rather than a socket, and a loop started again later picks them up. Each release is attempted whatever the others did, and a release that fails is logged. Runs under the served configuration lock, which stop-fabric also takes, so a stop and an owner's change cannot both act on one loop.

stop-node-mail-serve

(stop-node-mail-serve &key (drain-seconds *mail-serve-drain-timeout-seconds*) background)

Stop this node's mail serve leg accepting, and answer the number of sessions running at that moment, or NIL when no leg ran. A leg that bound its own socket closes it; a claim-mode leg serving over the resident's steered socket leaves that socket open. Each port the leg claimed is released first; releasing a port already released does nothing. The running sessions are drained as stop-mail-serve drains them, for up to DRAIN-SECONDS, on this thread or with BACKGROUND true on a thread of their own. A descriptor the launch handed down is closed too, once, whether or not a leg adopted it: the record is taken and cleared before the close. The standing delivery loop and the mail configuration stay as they are, so mail already landed is still delivered. A stop or close that fails is logged. Runs under the served configuration lock.

stop-owner-terminus

(stop-owner-terminus)

Withdraw the owner terminus's port claim, then stop its listener, and clear both. A listener that does not stop cleanly is logged and passed over. Doing it again, or with nothing started, does nothing. Returns no values.

stop-recovery-mail-transport

(stop-recovery-mail-transport)

Stop what start-recovery-mail-transport started: the delivery loop, the mail configuration, the /mail seams, the operator-state pool, and the custody it set, each reset fail-closed. Doing it again, or with nothing started, does nothing. Returns no values.

stop-recovery-owner-door

(stop-recovery-owner-door)

Stop what start-recovery-owner-door started: the owner terminus, then the custody it set. Doing it again, or with nothing started, does nothing. Returns no values.

unclaimed-held-descriptors

(unclaimed-held-descriptors held &rest selection &key owner-port dns-udp-port dns-tcp-port mail-port)

The members of HELD that claimed-held-descriptors names for no service, in HELD's order; a second value lists those among them that are a lone DNS half. SELECTION takes the same keyword arguments as start-fabric's OWNER-PORT, DNS-UDP-PORT, DNS-TCP-PORT, and MAIL-PORT.

withdraw-expired-credentials

(withdraw-expired-credentials &optional (now (get-universal-time)))

Withdraw every credential in force on either leg whose leaf's not-after is at or before NOW, a universal time, reading no custody. On :443 an expired base cell is emptied, refusing every handshake and logging cert.edge-dark once, and an expired non-base cell leaves the live set, so its names fall to the base. On :25 the mail set in force is replaced by one without its expired cells; an expired canonical cell withdraws STARTTLS. Answer two values: the :expired change-report entries, unlogged, and T when anything was installed. Call it with custody-reload-lock held.

Variables

*custody-watch-started-by-boot*

The custody watcher this start of the fabric started, or NIL when it started none. stop-fabric and the failed-start cleanup stop it before anything else.

*fabric-auth-enabled-p*

Policy flag for non-loopback binds. When T, start-fabric will bind a non-loopback host because valis-root's node-auth returns a NoiseXX responder and seven's Tauth/Tattach path will use it to require a real handshake before admitting the attach. When NIL, start-fabric refuses a non-loopback bind. A full capability check will eventually replace the meaning of this flag; until then it is the policy gate.

*mail-descriptor-inherited-by-boot*

The mail descriptor the launch handed down, or nil. start-fabric records it and starts nothing on it; serve-node-mail adopts it when the mail switch is on. stop-node-mail-serve is the one place it is closed: it takes and clears the record before the close, so the descriptor is closed once, whether or not a leg adopted it.

*mail-queue-check*

A function of one argument, whether the operator-state database engaged at this start, answering true when this node has the mail queue. start-fabric starts the standing delivery loop over a store-store only when it answers true. The default answers its argument. A test harness that shares a test transaction's connection through mail-with-connection without engaging a pool binds it to answer true.

*mail-self-bind-port*

The port the mail leg binds for itself when it has no descriptor for the mail port, 0 for an ephemeral port, or NIL to bind nothing. A development and test seam: a resident never sets it, so a node with no other arrival for the mail port refuses to serve rather than binding one unprivileged.

*nine-p-listener*

The seven listener handle for the 9P fabric port, or nil when stopped. Set by start-fabric; cleared by stop-fabric. Read by stop-fabric and by run-foreground to advertise the bound port.

*owner-terminus-handshake-deadline-seconds*

Seconds a connection the owner terminus claims has to complete its handshake before its pending read is aborted and the connection is closed. Read when the fabric starts.

*owner-terminus-listener*

The keyed listener serving the owner 9P fabric over an inherited owner-port descriptor, or nil when no owner terminus is up. It is a SECOND keyed listener against the same valis-root as nine-p-listener: the loopback fabric stays the local management path and the owner terminus is the routable addition, present only when the node holds a descriptor answering for the owner port it serves. Set by start-fabric; stopped and cleared by stop-fabric and by start-fabric's own failure unwind.

*public-edge-arrival*

What this node holds to open its :443 edge on after start, as the plist (:tcp-fd :tcp-port :make-bound-source :mux), or NIL when the boot held no arrival for the edge port. start-fabric records it whether or not the boot opened :443; stop-fabric and the failed-start cleanup clear it. Changed only under served-configuration-lock.

+dns-service-port+

The port the DNS service of the :names group answers on, over both transports. A protocol's own number, the same fact every resolver on the wire already holds. It says nothing about how a socket for it reaches this process, which is the host agent's question and settled on host-OS grounds this node holds no opinion about.

+owner-terminus-port+

The port valis serves the routable owner 9P terminus on. 564 is IANA's registered 9P (styx/p9) port.

This number is now what the fabric looks the owner descriptor up under, so it is a declaration rather than a record: the node serves the terminus here, and a host agent that means the terminus to come up must make this port arrive. Hand down a descriptor bound to some other number and the node holds it and serves nothing on it, which is visible as a terminus that never opened.

That is the reverse of the arrangement this constant used to describe, where the host agent's config chose the number and valis adopted whatever descriptor it was given. A deployment whose agent names a different owner port needs valis told the same number through OWNER-PORT, and a node that has to be told at boot wants a declaration of its own rather than the launcher's word for it.