valis / Reference / API reference

Development - API reference

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

Package valis/src/dev/host-trigger

Conditions

development-request-refused

Signalled for a file named as a development request that is not read: PROBLEM is :not-regular-file, :owner, :links or :unopenable. INODE and MTIME identify the file as it stood, when it could be examined.

Generic functions

development-request-refused-inode

(development-request-refused-inode condition)

Undocumented: this exported symbol needs a docstring.

development-request-refused-mtime

(development-request-refused-mtime condition)

Undocumented: this exported symbol needs a docstring.

development-request-refused-path

(development-request-refused-path condition)

Undocumented: this exported symbol needs a docstring.

development-request-refused-problem

(development-request-refused-problem condition)

Undocumented: this exported symbol needs a docstring.

Functions

development-actor-token-p

(development-actor-token-p text)

True when TEXT is 1 to 64 ASCII letters, digits, dots, underscores, and hyphens.

development-nonce-p

(development-nonce-p text)

True when TEXT is a nonce: exactly 32 lower-case hexadecimal digits.

development-reply-files

(development-reply-files root)

The (path . nonce) of every entry in the runtime root ROOT named as a reply, in name order.

development-reply-path

(development-reply-path root nonce)

The path of the reply named by NONCE in the runtime root ROOT.

development-request-files

(development-request-files root)

The (path . nonce) of every entry in the runtime root ROOT named as a request, in name order, whatever kind of file it is. A temporary name being written is not one.

development-request-octets

(development-request-octets nonce verb actor)

The request line for NONCE, VERB (:open or :close) and ACTOR, newline included, as octets.

development-request-path

(development-request-path root nonce)

The path of the request named by NONCE in the runtime root ROOT.

development-status-path

(development-status-path root)

The path of the status file in the runtime root ROOT.

fresh-development-nonce

(fresh-development-nonce)

A new nonce: 16 octets from /dev/urandom as 32 lower-case hexadecimal digits. Drawn from the kernel, never from RANDOM, since every process started from one saved image begins from the same Lisp random state.

parse-development-request

(parse-development-request octets)

Read OCTETS as a request line. Answers the verb (:open or :close), the nonce and the actor. A line that is not a request answers NIL, the nonce when its third field reads as one or else NIL, and a one-line reason. Never uses the Lisp reader.

read-development-file

(read-development-file path limit)

The text of the regular file at PATH as UTF-8, at most LIMIT octets of it, or NIL when nothing is there. Never follows a symbolic link and never waits on a FIFO. Signals development-request-refused for anything but a regular file, and sb-posix:syscall-error when this account may not open it.

read-request-safely

(read-request-safely path)

The octets of the request at PATH, at most one more than development-request-limit so an oversized request is seen as one, or NIL when nothing is there. Examines PATH without following it, then opens it without following a symbolic link and examines the descriptor, so the file checked is the file read. Signals development-request-refused for anything but a regular file, owned by the account development-request-effective-uid-function answers or by root, with one link.

write-private-file-atomically

(write-private-file-atomically path octets &key (mode 384))

Replace PATH with OCTETS at MODE: a temporary name in the same directory, created exclusively without following a symbolic link and closed on exec, then set to MODE, written, synced, and renamed over PATH. Signals sb-posix:syscall-error when the directory cannot be written.

Variables

*development-request-effective-uid-function*

A function of no arguments answering the account a request must belong to, besides root.

+development-request-header+

The first two fields of a request line, naming its format and version.

+development-request-limit+

The most octets a request holds, its newline included.

+development-status-file-name+

The status file's name in the runtime root.

Package valis/src/dev/listener-control

Functions

%session-actor

(%session-actor)

The actor of the session served on this thread: owner for the node's own key, the label of the enrolled device key it presented, or unknown when no keyed principal is bound or the key is on no keyring.

announce-development-listener-open

(announce-development-listener-open state)

Notify the owner by mail of the open STATE, on a thread of its own, and answer that thread. A boot or recovery open made before the mail store is up is kept pending instead, for send-pending-development-listener-notice, and answers NIL.

close-development-listener

(close-development-listener &key route actor)

Close the development listener this control opened and return its final state, or NIL when none was open. ROUTE and ACTOR name who closed it, as for open-development-listener. Every route but :shutdown resets development.listener, so the listener stays closed across a restart; :shutdown, the node's own teardown, leaves it as it is. Logs development-listener.closed at WARN with the seconds it was open.

development-listener-state

(development-listener-state)

A copy of the open listener's state, or NIL when it is closed.

development-listener-state-actor

(development-listener-state-actor instance)

Undocumented: this exported symbol needs a docstring.

development-listener-state-path

(development-listener-state-path instance)

Undocumented: this exported symbol needs a docstring.

development-listener-state-persisted

(development-listener-state-persisted instance)

Undocumented: this exported symbol needs a docstring.

development-listener-state-route

(development-listener-state-route instance)

Undocumented: this exported symbol needs a docstring.

development-listener-state-since

(development-listener-state-since instance)

Undocumented: this exported symbol needs a docstring.

development-listener-status-lines

(development-listener-status-lines &optional (state (development-listener-state)))

The status text's key lines for STATE, the listener's state or NIL when closed, as (key . value) strings in order, and as a second value the traceback lines. Reads development-listener-mode, development-listener-analysis in recovery, and development-status-release-facts. Never signals: a fact that cannot be read is unknown.

development-listener-status-text

(development-listener-status-text &optional (state (development-listener-state)))

The status text for STATE, as the package documentation describes it: the header, one line per key of development-listener-status-lines, then the traceback lines, each ended by a newline. Never signals.

development-listener-switch-on-p

(development-listener-switch-on-p)

True when development.listener is set on in the node's open store. NIL with no store open.

open-development-listener

(open-development-listener &key route actor)

Open the development listener at the resolved socket path, set development.listener on, and return its state. ROUTE is a keyword naming the door (:boot, :host, :owner, :config, :recovery) and ACTOR is text naming who asked. The setting is written after the bind, so a store that cannot be written leaves the listener open with persisted NIL in its state. Opening while open returns the current state, binds nothing, and writes nothing. A refusal from the bind signals a development-listener-refused and records nothing. Logs development-listener.opened at WARN. A fresh open then notifies the owner by mail on a thread of its own (see announce-development-listener-open); the open never waits on it.

reconcile-development-listener

(reconcile-development-listener)

The rebinding function of development.listener: open the listener with route :config when the setting is on and it is closed, close it with route :config when the setting is off and it is open, and do nothing when they already agree or while this control is writing the setting itself. The actor is that of the session served on the calling thread. Returns :restart where no serving node's store is installed, since no resident is there to act. A refused open is passed on.

resolve-development-socket-path

(resolve-development-socket-path)

The pathname the development listener binds: development.socket-path when set, else development.sock in the runtime root. Always a pathname, never a namestring, since slynk binds a local socket only when given a pathname.

resolve-runtime-root

(resolve-runtime-root)

The runtime root as a directory pathname: runtime.root (seeded from VALISRUNTIMEROOT), or run/valis/valis when it is unset or blank.

send-pending-development-listener-notice

(send-pending-development-listener-notice)

Send the mail notice of a boot open that was kept pending, on a thread of its own, and answer that thread. Answer NIL, sending nothing, when no notice is pending; a notice is sent at most once.

start-development-listener-watch

(start-development-listener-watch &key (tick *development-listener-watch-seconds*) (reminder *development-listener-reminder-seconds*) (runtime-root (resolve-runtime-root)))

Start the thread named development-listener-watch, which runs %development-listener-watch-tick every TICK seconds over RUNTIME-ROOT with reminders every REMINDER seconds. Writes development.status in RUNTIME-ROOT before it returns; RUNTIME-ROOT NIL serves no host requests and writes no status. The thread runs with the node store, the mode, the recovery analysis, the release facts, and the substrate log stream in force here. Starting while it runs starts nothing. Returns the thread.

stop-development-listener-watch

(stop-development-listener-watch)

Stop the watch thread and wait for it to end, which takes no more than one tick, then remove the status file and any replies left in the runtime root it served. Stopping while none runs does nothing. Returns no values.

Variables

*development-listener-analysis*

NIL, or the analysis of the failed run a recovery start reports, as a plist. Keys, each optional: :failure-condition and :failure-message, strings; :failure-rung, a string; :failed-starts, an integer; :run-ends, a list of at most five strings; :changed-since-good, a list of at most ten strings; :next-step, a string; :traceback, a list of frame function names as strings; :launch-reason, :release-running, :failed-trial and :jailed, strings. Read only in recovery mode; a failure key it lacks reads unknown, and a release key it lacks reads from development-status-release-facts.

*development-listener-keyring-source*

A function of no arguments answering the owner keyring that names a session's actor, or NIL. Found late because the factotum lives in a layer this one does not load.

*development-listener-mode*

The mode the node runs in, :normal or :recovery, as the status text reports it.

*development-listener-reminder-seconds*

Seconds between development-listener.still-open reminders while the listener is open.

*development-listener-watch-seconds*

Seconds between the watch thread's ticks.

*development-notice-thread*

The thread that most recently began sending an open's mail notice, or NIL.

*development-status-release-facts*

NIL, or a function of no arguments answering the release report's facts as a plist of strings: :launch-reason, :release-running, :failed-trial and :jailed. Set by the resident at boot, so this layer reads the release report without loading it. NIL, or a function that signals, reads unknown for all four.

+default-runtime-root+

The runtime root when runtime.root is unset. It matches that key's declared default: the run account's directory beneath the host agent's own runtime directory, run/valis.

+development-socket-name+

The socket's file name within the runtime root when development.socket-path is unset.

+development-status-header+

The first line of the status text, naming its format and version.

+host-close-refused-in-recovery+

The reply to a host request to close the listener while the node runs in recovery.

Package valis/src/dev/listener-notice

Functions

compose-development-listener-notice

(compose-development-listener-notice facts domain &key (time (get-universal-time)) (host (machine-instance)) message-id (close-command (%node-host-close-command)))

The notice that the development listener opened, as RFC 5322 octets in UTF-8 with CRLF line ends, from and to postmaster at DOMAIN. FACTS is a plist of strings as the status text gives them: :socket, :route, :actor, :since and :mode. HOST names the node's host in the commands the body gives. TIME sets the Date header; MESSAGE-ID, when given, replaces the generated one. CLOSE-COMMAND is the host route's close command the body gives, by default one naming this node's account and data root and the installed binary.

deliver-development-notice-locally

(deliver-development-notice-locally store head)

Run one pass of the delivery stages over STORE and HEAD when no standing delivery loop is running: promote-incoming-once, then deliver-local-once. Answer the names of the entries delivered, or NIL when the loop is running and no pass ran. Every :local-deliver entry on the queue is delivered, as one loop cycle would; relay entries are left in the active window.

development-host-command

(development-host-command subcommand data-root account &key (executable (native-namestring *runtime-pathname*)) runtime-root)

The shell command that runs `development SUBCOMMAND –host` as ACCOUNT against the node whose data root is DATA-ROOT, as command-as-account builds it. ACCOUNT is written as sudo -u takes it and is not quoted further. EXECUTABLE is the absolute path of the valis binary. RUNTIME-ROOT, when given, is passed as –runtime-root.

development-notice-lander-ready-p

(development-notice-lander-ready-p)

True when a lander is set, so a notice can be landed now.

development-notice-runner

(development-notice-runner facts)

A function of no arguments that sends the notice for FACTS under the lander, local domains, notice domains, owner resolver, and log stream current when this is called, for a thread of its own. It never signals: a condition is logged as notice-failed with its class.

make-development-notice-lander

(make-development-notice-lander store head provenance-function &key (mode :queue))

A lander for development-notice-lander over the mail block STORE and its fenced HEAD. PROVENANCE-FUNCTION, of no arguments, answers the submission provenance at each landing. MODE :queue lands through land-message onto the transport queue; :direct, for a node without the queue, delivers through deliver-message-directly into the owner's Maildir.

send-development-listener-notice

(send-development-listener-notice facts)

Land the notice for FACTS (see compose-development-listener-notice) through development-notice-lander, from the null reverse-path to postmaster at the first member of local-domains, or, when that is empty, of development-notice-domains, and, when no standing delivery loop runs, deliver it into the owner's Maildir with one pass. A receipt whose placement carries :disposition :delivered, from a direct lander, is already in the Maildir: no pass runs and no queue is read. Answer :no-mail-store, :no-local-domain or :no-local-routing when it was skipped, :queued when the running loop will deliver it, :delivered, or :not-delivered. Logs notice-skipped, notice-landed, notice-delivered, or notice-failed. A condition from the lander or the delivery stages is passed on. A domain from development-notice-domains is local to this message only: local-domains is bound to it on this thread while the notice lands and its own entry is delivered, and no other entry is delivered. With a standing loop running, which would route it as relay mail, the notice is skipped as no-local-routing.

Variables

*development-notice-domains*

The mail domains the notice may address when local-domains is empty: the node's mail.local-domains, set by the fabric beside the lander. The notice treats the first as local for its own message only, and nothing else reads this variable.

*development-notice-lander*

NIL, or a function of body octets, envelope sender, null-sender flag and recipient list that lands one message through land-message. It answers the mail receipt, then the block store and fenced head it landed into. Set by the fabric while the durable mail store is up; NIL otherwise.

Package valis/src/dev/recovery-analysis

Functions

%frame-names

(%frame-names &key (limit +frame-limit+))

The function names of the frames below the signalling machinery on this thread's stack, innermost first, at most LIMIT. Called inside a handler at signal time, the first names the function that signalled.

%redact-report

(%redact-report text &key (secrets (funcall *secret-setting-values-source*)))

TEXT, a condition's report, as one line of at most 200 printable ASCII characters, with every string in SECRETS and the userinfo of every URL replaced by <secret>. The replacement runs on the whole text before it is cut, so a cut never leaves part of a secret.

assemble-recovery-analysis

(assemble-recovery-analysis &rest arguments &key failed-starts run-ends data-root release-root facts settings modules socket)

The recovery analysis as a plist with every analysis key of the development status text, and :earlier-fault. The status text keys: :failure-condition :failure-message :failure-rung :launch-reason :failed-starts :run-ends :release-running :failed-trial :jailed :changed-since-good :next-step :traceback :earlier-fault is the fault record an earlier run of the streak left, or NIL. A fault record whose run is not the one the run start record names is that earlier fault: its fields stay out of the failure keys and the traceback, and :failure-message says how the last run ended and names it as earlier. Reads the boot fault record, the run start record, and the module boot record under DATA-ROOT (default recovery-data-root), the release report for RELEASE-ROOT and FACTS (defaults release-root and launch-facts), and changes-since-last-good over SETTINGS, MODULES, and the running release (by default the node's settings and installed modules as they read now). FAILED-STARTS and RUN-ENDS are what the host agent passed, the run ends as strings; SOCKET, the development socket's path. A part that cannot be read is unknown. Never signals.

boot-fault-record-path

(boot-fault-record-path &optional (data-root *recovery-data-root*))

The fault record's pathname under DATA-ROOT, or NIL when DATA-ROOT is NIL.

changes-since-last-good

(changes-since-last-good &key (data-root *recovery-data-root*) (release "unknown") (settings :unknown) (modules :unknown))

What differs between the last-good-boot record under DATA-ROOT and this run, never a value: release when RELEASE differs from the recorded one, setting:<key> for each node key whose digest or set state differs or that only one side has, and module:<system> for each module added and then each removed. RELEASE is the running release; SETTINGS, the node setting rows list-settings gives; MODULES, the installed modules' system names. A part given or recorded as unknown is not compared. At most ten items, the tenth more:N when more differ. Answers :unknown when there is no readable record, or no part could be compared.

current-installed-module-systems

(current-installed-module-systems)

The installed modules' system names installed-module-systems-source answers, or :unknown when it is NIL or signals.

current-node-setting-rows

(current-node-setting-rows)

The node setting rows, as node-settings gives them, or :unknown when the node store is not open or cannot be read.

last-good-boot-record-path

(last-good-boot-record-path &optional (data-root *recovery-data-root*))

The last-good-boot record's pathname under DATA-ROOT, or NIL when DATA-ROOT is NIL.

make-run-identity

(make-run-identity &optional (now (get-universal-time)))

A new run identity: NOW as YYYY-MM-DDTHH:MM:SSZ, a hyphen, and eight random lower-case hex digits, so two runs started in one second differ.

parse-run-end

(parse-run-end text)

TEXT as one run end the host agent passes: three values, the kind (:exit, :signal, or :unrecorded), the code, and the seconds the run lasted. unrecorded@- answers :unrecorded with no code and no duration: a run whose end the host agent never saw, such as a watchdog abort or a kill. NIL when TEXT is not exit:N@S, signal:N@S or exactly unrecorded@-, N and S one to ten decimal digits.

parse-run-end-list

(parse-run-end-list text)

TEXT, the value of –recovery-run-ends, as a list of run-end strings. The empty string is no run ends. Answers a second value NIL, and the first NIL, when TEXT holds more than five ends or an end parse-run-end refuses; T otherwise.

read-boot-fault-record

(read-boot-fault-record &optional (data-root *recovery-data-root*))

The boot fault record under DATA-ROOT, read as text, never by the Lisp reader. Two values: a plist (:condition :message :rung :time :release :run :frames, :run absent from a record written without it) or NIL, and :present, :absent, or :unknown when the file cannot be read, does not parse, or does not match its digest. Never signals.

read-last-good-boot-record

(read-last-good-boot-record &optional (data-root *recovery-data-root*))

The last-good-boot record under DATA-ROOT, read as text, never by the Lisp reader. Two values: a plist (:time :release :version :commit :settings :modules) or NIL, and :present, :absent, or :unknown when the file cannot be read, does not parse, or does not match its digest. :settings holds (key kind value) lists, kind setting or secret, or :unknown; :modules, system names or :unknown. Never signals.

read-recovery-fault-record

(read-recovery-fault-record &optional (data-root *recovery-data-root*))

The recovery fault record under DATA-ROOT, the fault that ended a recovery run, as read-boot-fault-record answers its record. Never signals.

read-run-start-record

(read-run-start-record &optional (data-root *recovery-data-root*))

The identity of the last normal run to start, from the run start record under DATA-ROOT, read as text, never by the Lisp reader. NIL when there is none, or it cannot be read, does not parse, or does not match its digest. Never signals.

recovery-fault-record-path

(recovery-fault-record-path &optional (data-root *recovery-data-root*))

The recovery fault record's pathname under DATA-ROOT, or NIL when DATA-ROOT is NIL.

recovery-next-step

(recovery-next-step &key module release-changed setting killed unrecorded socket)

The one step to try first, as a sentence of at most 200 characters, by the first rule that holds: MODULE, a system name, retire that module; RELEASE-CHANGED, roll back to the last good release; SETTING, a key, set it back to its last good value, which the last-good-boot record holds only as a digest (a reset leaves a key seeded from the environment unset, and the next start refuses); KILLED, the runs ended by signals with no fault record (UNRECORDED when some ended unrecorded); otherwise attach and read the traceback. Every sentence names the REPL on the development socket at SOCKET, its path, since the owner door serves status only in recovery. A module name longer than 48 characters, a setting key longer than 30, or a path longer than 56, is cut.

remove-boot-fault-record

(remove-boot-fault-record &optional (data-root *recovery-data-root*))

Remove the fault record under DATA-ROOT. True when one was removed.

run-start-record-path

(run-start-record-path &optional (data-root *recovery-data-root*))

The run start record's pathname under DATA-ROOT, or NIL when DATA-ROOT is NIL.

write-boot-fault-record

(write-boot-fault-record condition &key (data-root *recovery-data-root*) (frames nil frames-p) (now (get-universal-time)))

Write the fault record for CONDITION under DATA-ROOT, as the file's header comment describes: the boot fault record, or, inside with-recovery-fault-recording, the recovery fault record, leaving the boot fault record as it is. FRAMES defaults to %frame-names, so call this inside a handler at signal time. A message that cannot be cleared of secrets is recorded as unknown. Logs boot.fault-recorded. Returns the record's pathname, or NIL when DATA-ROOT is NIL. Signals a file-system error when the record cannot be written.

write-last-good-boot-record

(write-last-good-boot-record &key (data-root *recovery-data-root*) (release (%running-release)) version commit (settings :unknown) (modules :unknown) (now (get-universal-time)))

Write the last-good-boot record under DATA-ROOT, as the file's header comment describes. SETTINGS is the node setting rows list-settings gives, or :unknown; MODULES, the installed modules' system names, or :unknown. A secret key is recorded as set or unset only, so a secret changed while it stays set is not seen. Returns the record's pathname, or NIL when DATA-ROOT is NIL. Signals a file-system error when the record cannot be written.

write-run-start-record

(write-run-start-record &key (data-root *recovery-data-root*) (run *run-identity*))

Record RUN under DATA-ROOT as the last normal run to start, as the file's header comment describes, replacing any earlier one. Call once at a normal start, before bring-up. Returns the record's pathname, or NIL when DATA-ROOT or RUN is NIL. Signals a file-system error when the record cannot be written.

Macros

with-bring-up-rung

(with-bring-up-rung (rung) &body body)

Run BODY with bring-up-rung bound to RUNG.

with-recovery-fault-recording

(with-recovery-fault-recording nil &body body)

Run BODY, a recovery run, with its faults recorded in the recovery fault record.

Variables

*bring-up-rung*

The bring-up step running on this thread, a keyword or a string, or NIL. Read by write-boot-fault-record at signal time.

*installed-module-systems-source*

NIL, or a function of no arguments answering the installed modules' system names. Set by the resident once its store is up; NIL, or a function that signals, reads the module set as unknown.

*recording-recovery-faults*

True while a recovery run is under way: write-boot-fault-record then writes the recovery fault record, never the boot fault record the analysis read.

*recovery-data-root*

The data root directory both records live in, or NIL, when nothing is written or read.

*run-identity*

This supervised run's identity, as make-run-identity answers it, or NIL outside a supervised run. Read by write-boot-fault-record and write-run-start-record.

*secret-setting-values-source*

Function of no arguments answering the verbatim values a fault record's message must not hold.

+boot-fault-record-name+

Undocumented: this exported symbol needs a docstring.

+last-good-boot-record-name+

Undocumented: this exported symbol needs a docstring.

+recovery-fault-record-name+

Undocumented: this exported symbol needs a docstring.

+run-start-record-name+

Undocumented: this exported symbol needs a docstring.

Constants

+fault-record-octet-limit+

The most octets a fault record occupies.

Package valis/src/dev/slynk

Conditions

development-listener-host-not-loopback

Signalled when a caller asks for a listener on anything but a loopback address. Loopback is not a default that a caller may override: the deployment host's interfaces are publicly routable, so a listener bound to any real address is remote code execution offered to the open internet. The refusal is unconditional.

development-listener-invalid-port

Signalled when the requested port is not an (unsigned-byte 16). Refusing is what keeps a typo from becoming a bind on some other, unexpected port.

development-listener-not-compiled-in

Signalled when the SLYNK package is absent from the running image.

Every shipped valis node carries slynk, so this refusal should not fire in a delivery build; seeing it means the image was built without the listener, not that the listener was withheld by policy. The condition is kept because such an image remains buildable and must fail with a named cause rather than a mystery, and because the caller that meets it needs to tell it apart from a listener that was configured wrong.

development-listener-path-occupied

Signalled before the bind when something other than a socket owned by the effective uid is at the socket path. KIND is :regular-file, :symbolic-link, :directory, :socket (another uid's) or :other; OWNER is its uid. The occupant is left exactly as it was.

development-listener-path-too-long

Signalled before the bind when the socket path is longer than 107 octets as UTF-8. The kernel would cut a longer path short, so two paths differing past the cut would name one socket.

development-listener-refused

Base type for every refusal to start the development listener. A caller handles this to mean "the listener is not running and here is precisely why"; the subtypes below name the individual causes so a handler never has to guess which one it caught.

development-listener-runtime-root-unusable

Signalled before the bind when the directory the socket goes in is unusable. REASON is :absent, :not-directory, :not-owner (not owned by the effective uid) or :writable-by-others (its group or anyone else may write it, and so swap the path). The directory is never created or changed here.

development-listener-socket-unprotected

Signalled when the file slynk bound is not a socket owned by the effective uid and gid with mode 0660. The listener is stopped and its file removed before this is signalled, since whoever can connect evaluates code as the node.

development-listener-socket-unsupported

Signalled before the bind when slynk is present but its backend lacks create-pathname-socket. Without it slynk would read a path as a host name and bind TCP.

development-listener-start-failed

Signalled when slynk is present and the arguments were admitted, but the bind itself failed (an already-occupied port, for instance). The underlying condition travels in CAUSE rather than being discarded, so the wrap narrows the type without losing the diagnosis.

Generic functions

development-listener-occupant-kind

(development-listener-occupant-kind condition)

Undocumented: this exported symbol needs a docstring.

development-listener-occupant-owner

(development-listener-occupant-owner condition)

Undocumented: this exported symbol needs a docstring.

development-listener-path-octets

(development-listener-path-octets condition)

Undocumented: this exported symbol needs a docstring.

development-listener-refused-host

(development-listener-refused-host condition)

Undocumented: this exported symbol needs a docstring.

development-listener-refused-path

(development-listener-refused-path condition)

Undocumented: this exported symbol needs a docstring.

development-listener-refused-port

(development-listener-refused-port condition)

Undocumented: this exported symbol needs a docstring.

development-listener-runtime-root-reason

(development-listener-runtime-root-reason condition)

Undocumented: this exported symbol needs a docstring.

development-listener-start-failure-cause

(development-listener-start-failure-cause condition)

Undocumented: this exported symbol needs a docstring.

Functions

development-listener-available-p

(development-listener-available-p)

True when the SLYNK package is present in this image, which every shipped valis node is built to be.

This answers whether a listener could be started here, never whether one is running: for that, ask DEVELOPMENT-LISTENER-LISTENING-P. It is the predicate form of DEVELOPMENT-LISTENER-NOT-COMPILED-IN, so a caller can find out in advance what a start attempt would refuse with in an image built without slynk.

development-listener-listening-p

(development-listener-listening-p)

True when a development listener has been started in this image and is listening.

This is the fact that varies from node to node now that slynk ships everywhere. The code being present says nothing; only a caller that bound a port or a local socket makes this true.

start-development-listener

(start-development-listener port &key (host "127.0.0.1"))

Start the development listener on PORT at HOST and return both as values, so a caller reports what was bound rather than repeating what it hoped for.

Refuses, with a defined condition under DEVELOPMENT-LISTENER-REFUSED, when HOST is not loopback, when PORT is not a TCP port, when this image has no slynk compiled in, or when the bind fails. It never returns NIL to mean "did not start": the caller either has a listener or has a condition naming why it does not.

The checks run host, then port, then availability, so a non-loopback request is refused identically in every build: a production image must not answer a routable-address request with "no slynk here" and leave the caller thinking the address was the acceptable part.

Nothing here is ambient. There is no global that turns the listener on, no autostart at load time, and no state left behind: it starts only when something calls this function. That is so the single call site can later be placed behind valis's own capability system (a designation alongside /active/zone-write and /edge/listen/<port>) without having to first dismantle an install of hooks.

start-development-socket-listener

(start-development-socket-listener pathname)

Start the development listener on a local socket at PATHNAME and return PATHNAME.

Binds through slynk's pathname interface, which takes a pathname and never a namestring: a string takes slynk's TCP branch. The socket is given mode 0660 between its bind and its listen, so no peer connects under another mode. After the bind the file must be a socket owned by the effective uid and gid with mode 0660; anything else stops the listener, removes the file, and signals development-listener-socket-unprotected.

Before the bind, in this order: a path over 107 octets is refused (development-listener-path-too-long); an image without slynk, or whose slynk lacks the pathname interface, is refused (development-listener-not-compiled-in, development-listener-socket-unsupported); the directory must be one the effective uid owns and neither its group nor others may write (development-listener-runtime-root-unusable); and the path must be empty or hold a socket the effective uid owns, which is removed as stale. Anything else at the path is refused and left untouched (development-listener-path-occupied). A failed bind signals development-listener-start-failed. Every refusal is a development-listener-refused.

stop-development-listener

(stop-development-listener)

Stop the development listener open in this image, on its local socket or its port, and answer true, or NIL when none is open.

Closes the Slynk connections accepted through this listener, so an attached client reads end of file, and no other: the image may hold Slynk connections of its own, a tooling worker's among them. Then removes the socket file when it is still a socket owned by the effective uid, and clears the listening state.

Variables

*development-listener-socket*

The pathname of the local socket a development listener is bound at in this image, or NIL when none is. Set only after the bind and its checks succeed.