Network - API reference

One special-purpose range: where it is, what it is called, which RFC sets it aside, and whether it is :special (refused for a destination somebody else chose unless the owner allows it) or :floor (never reached at all).

Signalled when what is presented as an address of a family is not one: not a vector, not the family's width, or holding a value that is not an octet. A classification is never made of an address read at the wrong width or of a value no address can hold.

(address-not-of-family-family condition)

Undocumented: this exported symbol needs a docstring.

(address-not-of-family-octets condition)

Undocumented: this exported symbol needs a docstring.

(address-range-cidr instance)

Undocumented: this exported symbol needs a docstring.

(address-range-family instance)

Undocumented: this exported symbol needs a docstring.

(address-range-floor-p range)

True when RANGE is one no connection is opened to, whoever chose it.

(address-range-length instance)

Undocumented: this exported symbol needs a docstring.

(address-range-name instance)

Undocumented: this exported symbol needs a docstring.

(address-range-p object)

Undocumented: this exported symbol needs a docstring.

(address-range-prefix range)

The octets RANGE starts at, as a fresh vector a caller may change freely.

(address-range-rfc instance)

Undocumented: this exported symbol needs a docstring.

(address-range-tier instance)

Undocumented: this exported symbol needs a docstring.

(address-within-prefix-p octets prefix length)

True when the first LENGTH bits of OCTETS are those of PREFIX. Both are octet vectors of one width.

(carried-ipv4-address octets)

The IPv4 address the sixteen OCTETS carry, as four octets, or NIL when they carry none.

(classify-address octets family)

The special-purpose range OCTETS falls in, or NIL when it falls in none. FAMILY is :internet for four octets or :internet6 for sixteen; anything else, including a vector holding a value that is not an octet, signals ADDRESS-NOT-OF-FAMILY rather than being classified. An IPv6 address carrying an IPv4 one is classified by the IPv4 address it carries.

(special-purpose-ranges)

Every special-purpose range the classifier knows, as a fresh list. Nothing a caller does to the list or to what it holds changes what the classifier reads: the rows are read-only and ADDRESS-RANGE-PREFIX hands out a copy of a row's octets.

Signalled when a range is written with a bit set past its prefix length. 10.0.0.1/8 more likely names one host mistyped than the range 10.0.0.0/8, so it is read as neither.

Signalled when the text does not spell a range at all.

The root of the refusals PARSE-CIDR signals. No report repeats the text, which a caller may be holding on somebody else's behalf.

(floor-range-containing octets length family)

The one floor row the whole range of LENGTH bits starting at OCTETS lies inside, or NIL when no single floor row holds all of it. FAMILY is :internet or :internet6. A range wider than a floor row and covering it is not inside it, so 0.0.0.0/0 returns NIL.

(parse-cidr text)

The range TEXT names, written address/length, as three values: its first address as octets, its prefix length, and its family, :internet or :internet6. Text that does not spell a range signals CIDR-MALFORMED, and a range with a bit set past its prefix length signals CIDR-HOST-BITS-SET.

Signalled when an address a dial refused lies in the floor: the unspecified addresses, multicast or limited broadcast. None of them is one peer, and the kernel reads the unspecified addresses as this host, so no grant and no owner allowance reaches them. A floor address is reported ahead of any other refused address of the same dial, because no allowance reaches it; another address of the same destination may still lie in a range the owner could allow.

Signalled when a dial resolved its destination and connected to none of its addresses because of the special-purpose range they lie in: every address was refused, or a caller abandoned the dial at a refusal. No socket is opened to a refused address.

ADDRESS is the refused address the dial reports: one in the floor ahead of any other, otherwise the first refused, or the one a caller abandoned the dial at. RANGE is the row of the special-purpose table it fell in, so a report says 10.0.0.0/8 private-use (RFC 1918) rather than only that it was refused. CHOOSER and CLIENT are the marks of the grant the dial was made under: who chose the destination, and the holder the owner can allow a range for.

It is a sibling of DIAL-NOT-PERMITTED rather than a kind of it, because that refusal promises no name was looked up, and this one happens only after the name became addresses. It is not a connection failure either: nothing was tried on the wire, and a caller that retries on a connection failure would retry a refusal forever. An operator reading it learns that the destination points somewhere this node will not go, which is a different fault from a destination that does not exist.

Signalled for each address a dial refuses because of its range, before the dial moves on to the next. REFUSAL is the DIAL-ADDRESS-NOT-PERMITTED that address would be reported as.

A notice, not an error, so a caller that handles every dial error around a dial is not handed the first refused address while a permitted one remains to be tried. Observe it with HANDLER-BIND. Two restarts are offered while it is signalled: SKIP-ADDRESS moves on, as returning does, and ABANDON-DIAL signals REFUSAL as the dial's own error, for a caller that wants nothing from a destination that pointed even once where it may not go. No restart permits the address: only the owner widens what a client may reach.

Parent of the ways a resolved address did not yield a connection. ADDRESS is always populated on this branch, which is what separates it from the resolution branch above.

Signalled when the peer answered and declined. A refusal is reported the moment it arrives rather than after a deadline elapses: a host that is down and a path that swallows packets want opposite operator responses, and a refusal reported as a timeout erases the difference.

Root of every way an outbound connection can fail.

DESTINATION is the name or address literal exactly as the caller gave it, never a canonicalised or resolved form, so an operator reading a report sees the value they configured. ADDRESS is the address actually attempted and is NIL when the failure happened before any address existed, which is itself the distinction between a policy or resolution failure and a connection failure. BRANCH names the half that broke. CAUSE carries the underlying condition or errno.

Signalled when the network reported the address as unreachable. Distinct from a refusal, which proves something was listening at the far end, and from a deadline, which proves nothing at all.

Parent of the ways a destination name did not become an address. A caller that only needs to know 'the name half failed' handles this one class; a caller that must respond differently to a missing name than to a misconfigured node handles the subclasses.

Signalled when the name genuinely has no record. The fault is in the destination or in what configured it, not in this node.

Signalled when the resolver refused because this network namespace holds no configured address of the requested family.

The operating system reports this identically to a name that does not exist, and it means the opposite. Keeping the two apart is the reason this hierarchy is worth its weight: read as 'no such name' it sends an operator to the zone data, when the fault is that this node was confined without an address of that family and cannot reach anything by that family at all.

Signalled when the capability check refuses a dial.

Nothing observable leaves this process on this path: no query is emitted, no address is learned, no descriptor is created. That is the property the whole seam is built to have, and this condition is where it becomes visible. A refused dial that had already resolved the name would have published the destination to whoever watches this node's queries while still reporting a refusal to the caller, which is worse than no refusal at all.

Signalled when code opens an outbound connection without passing through the seam. CALLER names the offending call site so the report identifies what to migrate rather than only that something needs migrating.

Defined alongside the rest of the vocabulary so the failure set is complete in one file and a reader learns the whole shape at once. The runtime check that signals it is built separately, and it refuses rather than resolving: a check that resolved on a caller's behalf and handed back an address would rebuild, one layer lower, exactly the resolve-then-connect-elsewhere path this seam removes.

Signalled when the configured nameserver could not be reached at all, so nothing was learned about the name either way. The fault is in this node's own configuration. This is never inferred from a name lookup failing: a failed lookup is ambiguous, and guessing between the branches here would lose the distinction the two classes above exist to preserve.

Signalled when this node would not create a socket for the address being tried, so nothing was sent toward it. A kernel with IPv6 disabled refuses every IPv6 socket this way.

It is a fact about this node and that address's family rather than about the peer, so a walk moves past it to the next address, and when another address failed on the wire that failure is the one reported. CAUSE carries the system call's own condition.

Signalled when the outbound socket could not take the egress source address the caller required, or took a different one.

REQUESTED and BOUND are both carried because the two failures are not the same: an address that cannot be assigned means this node does not hold it, while a different address bound means the routing table chose, which is exactly the delegation an explicit source exists to prevent. A peer that authorises by source address drops traffic from anywhere else without replying, so this failure is otherwise silent.

Signalled when no address of the destination shares the egress source's family, so nothing could be dialled from it. No socket is opened to learn this.

It is a kind of unbound source, because the source cannot be left from, but unlike its parent it is a fact about this destination rather than about the node: the same source may reach every other destination. A caller that abandons all its work over an unbound source should contain this one to the destination it names.

Signalled when the connection deadline elapsed with no answer of any kind. This is the one connect outcome that carries no information about the peer, so it is kept apart from the two that do.

(dial-address-not-permitted-chooser condition)

Undocumented: this exported symbol needs a docstring.

(dial-address-not-permitted-client condition)

Undocumented: this exported symbol needs a docstring.

(dial-address-not-permitted-range condition)

Undocumented: this exported symbol needs a docstring.

(dial-address-passed-over-refusal condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-address condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-branch condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-cause condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-destination condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-family condition)

Undocumented: this exported symbol needs a docstring.

(dial-error-port condition)

Undocumented: this exported symbol needs a docstring.

(dial-outside-the-seam-caller condition)

Undocumented: this exported symbol needs a docstring.

(dial-source-address-unbound-bound condition)

Undocumented: this exported symbol needs a docstring.

(dial-source-address-unbound-requested condition)

Undocumented: this exported symbol needs a docstring.

(dial grant destination port &key (type :stream) (family :internet) source (deadline *dial-deadline*))

Open a connection to DESTINATION at PORT under GRANT.

Answers three values: an integer file descriptor, the peer that answered as text, and its address family.

GRANT is required and positional. Calling without one is a program error at the call site rather than a dial that happens to be unchecked, which is the property that makes this the only door.

The first value is pinned as an integer descriptor and is meant to stay one. A consumer that wraps the connection in transport security takes an integer descriptor or a stream, and accepts neither of the socket objects the socket libraries hand out, so answering an object here would push a conversion into every caller and the mistake would only be discovered at the far end of the stack.

The caller owns the descriptor and its close from the moment this returns. Nothing here holds a reference to it, and nothing closes it later.

TYPE :DATAGRAM answers a socket already fixed to the one destination, so the caller sends without naming a recipient. SOURCE names the egress address to leave from, which is bound and proved before the connection is attempted. A source naming no interface, or no address, is refused before any name is looked up, and an address of the destination that does not share the source's family is passed over without a socket being opened for it. DEADLINE bounds each address attempt rather than the dial as a whole.

Every address the destination resolves to is judged before a socket exists for it. The floor (the unspecified addresses, multicast and limited broadcast) is never dialled, whoever chose the destination. Under a grant marked as somebody other than the owner's choice, an address in any other special-purpose range, loopback and the private networks among them, is passed over unless the owner allows that range for the grant's client. I check each address at each dial, and hold no answer between dials, because what a name resolves to can change under it and an owner who narrows an allowance should not wait for anything to expire. When nothing connects because of that rule you get DIAL-ADDRESS-NOT-PERMITTED, or DIAL-ADDRESS-IN-FLOOR, naming the address, its range, and the grant's chooser and client, so you can tell a destination that points somewhere this node will not go from one that does not exist.

The function that answers which special-purpose ranges the owner allows a client to reach, or NIL, which allows none to anyone.

Called with a client name whenever a destination somebody other than the owner chose resolves into such a range, and answering a list of ranges, each written address/length. It is asked at every such dial, so a change the owner makes applies to the next connection with nothing to reissue. A running node installs its reader of the owner's configuration here. A function that signals, or answers anything but a proper list of strings, allows nothing, and the failure is logged.

Seconds a single address is given to answer before the attempt is abandoned.

Applies per address rather than per dial, so a destination with several addresses can cost this much for each of them. A caller with a tighter budget passes its own; the default is chosen to outlast an ordinary intercontinental round trip and a retransmit, and to be well short of the kernel's own connect timeout, which runs into minutes and is far past the point any caller still wants the answer.

Source addresses that name no interface. Binding one of these succeeds and leaves the routing table to choose, which is the delegation an explicit source exists to prevent, so they are refused before a socket is opened.

One place permitted to reach the network without passing through the seam.

Signalled when an exemption naming a caller is made without saying who chooses that caller's destinations.

(outbound-exemption-without-chooser-caller condition)

Undocumented: this exported symbol needs a docstring.

(make-outbound-exemption &rest initargs &key caller chooser &allow-other-keys)

One exemption, refused with OUTBOUND-EXEMPTION-WITHOUT-CHOOSER when it names a caller and no chooser.

(note-outbound-escape caller)

Count one connection CALLER was let through on, and answer the entry it matched.

(outbound-exemption-caller instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-callers)

The package-qualified function names permitted to dial outside the seam.

(outbound-exemption-chooser instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-disposition instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-escapes instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-p object)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-path instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemption-paths)

The repo-relative paths the outbound sweep does not read.

(outbound-exemption-reason instance)

Undocumented: this exported symbol needs a docstring.

(outbound-exemptions-by-disposition)

The registry as an alist of disposition to entries, unmigrated debt first.

(outbound-exemptions-with-disposition disposition)

The entries carrying DISPOSITION, in registry order.

(report-outbound-exemptions &optional (stream *standard-output*))

Print what still reaches the network outside the seam, unmigrated first, and answer the registry grouped by disposition.

(reset-outbound-escape-counts)

Clear every entry's escape count, so a later count is read against a known start.

Every place permitted to reach the network outside the seam, with its reason.

The one tracked tree of Lisp sources the outbound sweep deliberately skips.

Signalled when a chain of redirects outruns its bound.

A redirect chain is destination changes chosen by the responses rather than by the caller, so an unbounded walk is a loop somebody else controls. Abandoning the chain is the only answer that ends.

Signalled for a URL whose scheme is neither http nor https.

Refused rather than guessed at. A scheme nobody wrote a meaning for would otherwise take the port of one that was written, and reach a destination the caller did not name.

(redirect-limit-exceeded-hops condition)

Undocumented: this exported symbol needs a docstring.

(redirect-limit-exceeded-url condition)

Undocumented: this exported symbol needs a docstring.

(unsupported-request-scheme-scheme condition)

Undocumented: this exported symbol needs a docstring.

(unsupported-request-scheme-url condition)

Undocumented: this exported symbol needs a docstring.

(seam-http-request url &rest keys)

Fetch URL through the outbound seam and answer (values body status headers).

The three answers are what a certificate client reads: the status and the headers carry its replay nonce and its problem documents, so the shape is the HTTP client's own and is not a place to improve on it. The client's remaining answers describe a connection this seam has already given back, and are deliberately not passed on rather than handed over as something that is gone.

KEYS are the HTTP client's own request options. A :REDIRECT among them sets how far the chain here is followed, NIL answering a redirect rather than taking it; it is never passed on, because leaving the client to follow a redirect would put the next connection outside this seam entirely.

The connection comes from the seam under the capability bound at the time of the call, so an unauthorised destination is refused before any name is looked up. Every hop is dialled separately and decided separately, and every descriptor is given back on both the answering and the signalling path.

The outbound capability requests are made under, or NIL when none is held.

Bound for the extent of the order that was granted it rather than set once, so the authority sits on the path that holds it instead of standing in the image for whatever happens to make a request next. NIL refuses, which is what a request with no grant behind it has to do.

How many times a response may redirect before the chain is abandoned.

The same bound the HTTP client applies on its own, kept deliberately: taking its redirect handling away changes where the walk happens and must not quietly change how far it goes.

A permission that was granted, and the grant it rests on.

Answered rather than merely implied by returning normally, so what allowed a dial can be reported and audited instead of reconstructed by reading code.

The authority a principal presents to dial.

DESIGNATION names what the grant reaches. HASH identifies the grant itself and is what an owner names when withdrawing it, so a grant issued without one can never be withdrawn and its decisions are never held.

CHOOSER says who picked the destination the grant reaches. :OWNER means node code built the grant from the owner's own configuration; :THIRD-PARTY means the destination came from anyone else: a vouched module, a peer, or a record fetched off the network. A grant is :THIRD-PARTY unless something deliberately says otherwise, so a grant built without thought carries the stricter mark rather than the looser one.

CLIENT is the name of the holder the grant was issued to, so a decision can be made per client rather than for every holder at once, or NIL when nothing names it. PORTS lists the ports the grant was issued for, NIL for any; a dial to any other port is refused before its destination is looked up.

(allowance-client-name-p text)

Whether TEXT can name a client in the owner's allowance of address ranges: lower-case ASCII letters, digits, dots and hyphens, starting with a letter or a digit. Every name the owner can write there satisfies this, and nothing else does.

(clear-dial-decisions)

Drop every held decision. Returns no meaningful value.

(dial-decision-designation instance)

Undocumented: this exported symbol needs a docstring.

(dial-decision-destination instance)

Undocumented: this exported symbol needs a docstring.

(dial-decision-p object)

Undocumented: this exported symbol needs a docstring.

(dial-decision-port instance)

Undocumented: this exported symbol needs a docstring.

(dial-grant-chooser instance)

Undocumented: this exported symbol needs a docstring.

(dial-grant-client instance)

Undocumented: this exported symbol needs a docstring.

(dial-grant-designation instance)

Undocumented: this exported symbol needs a docstring.

(dial-grant-hash instance)

Undocumented: this exported symbol needs a docstring.

(dial-grant-p object)

Undocumented: this exported symbol needs a docstring.

(dial-grant-ports instance)

Undocumented: this exported symbol needs a docstring.

(dial-scope designation)

What DESIGNATION reaches: :EVERY-DESTINATION, the one destination its trailing segment names, or NIL when it is not a designation this file recognises.

The trailing segment carries the reach in the shape the listener-bind designation already established for a parameter carried in a designation, so an operator reading a grant-set sees what a dial grant reaches in the designation itself rather than having to look it up somewhere else.

An unrecognised designation answers NIL rather than being treated as a harmless unknown, because a designation nobody wrote a meaning for is exactly the shape a mistake takes.

This is the one place the rule is written. A second reading of the same string somewhere else would be a second rule, and the two would drift apart quietly on a string that decides where a principal may go.

(evaluate-dial grant destination port)

Answer the decision that permits GRANT to dial DESTINATION at PORT, or refuse.

Refuses by signalling DIAL-NOT-PERMITTED rather than by answering NIL, so a caller cannot proceed by ignoring a value. The refusal carries a keyword naming which refusal happened, so an operator reading a report can tell a principal holding nothing from one holding a grant for somewhere else, and either from one whose grant the owner has since withdrawn: :NO-GRANT, :GRANT-WITHDRAWN, :OUTSIDE-GRANT-PORTS, :UNRECOGNISED-DESIGNATION, :NAMED-SCOPE-UNWIRED, :OUTSIDE-GRANT-SCOPE, or :REFUSED-BY-OPERATOR-POLICY. A keyword rather than a sentence, because a caller can dispatch on the first and can only print the second. A grant issued for particular ports reaches no other port on any destination.

A grant naming a set rather than a destination is decided against the members this node works out at this moment, and its decision is never held: membership follows the operator's configuration, which changes without any grant being withdrawn, so a held decision would go on permitting a destination the operator had already removed.

Called from inside the dial verb before any name is looked up and before any socket exists.

The withdrawal is consulted ahead of the held decisions rather than behind them. The owner's withdrawal already empties what it named through the eviction the fabric chains onto it, and asking again here costs one lookup and means the answer does not depend on that wiring having been installed.

(evict-dial-decisions-by-hash hash-32-bytes)

Drop every decision held for the grant HASH-32-BYTES names.

The fabric chains this onto the same hook the owner's revocation already calls, so withdrawing a grant empties its decisions as part of the withdrawal rather than as a second act somebody has to remember. Returns no meaningful value.

(make-dial-grant &key designation hash (chooser :third-party) client ports)

A dial grant for DESIGNATION, marked with CHOOSER, CLIENT and PORTS.

Refuses a mark the grant could not honestly carry, here where the grant is built, so a malformed one never exists to be presented.

(module-dial-client system)

The client a dial grant handed to the module admitted as SYSTEM is issued to, or NIL when it can be issued to none.

The client is the ASDF system name itself, exactly as the owner writes it in an allowance: a module admitted as example-client is reached by example-client=10.0.0.0/8. A name the owner could not write there, one with an upper-case letter, a slash or any other character an allowance refuses, and a name one of the node's own clients already carries, give NIL, so no allowance reaches that module and its dials keep to public addresses. I never rewrite a name to make it fit: ASDF tells Foo from foo and a/b from a.b, so any rewriting could hand one module's allowance to another.

(named-scope-p scope)

Whether SCOPE names a set the node works out rather than a single destination.

(register-named-scope name function)

Answer NAME's members through FUNCTION, called with the dial's subject. NIL unwires NAME.

An operator narrowing of what a grant reaches, or NIL for none.

A function of the grant, the destination and the port, answering true to let a dial proceed. It runs in addition to the grant's own scope and never in place of it, so it can only refuse what the grant already permitted. A hook able to widen would move the reach of a grant off the grant structure the owner controls and onto a function somebody installed, which the owner could not see by reading the grant.

Changing it does not reach decisions already held. A narrowing is an operator's configuration act, so an operator who wants it to bite on what is already held empties the cache with CLEAR-DIAL-DECISIONS.

The record of the grants the owner has withdrawn, or NIL when none is wired.

The fabric installs the node's own store here at start, the same append-only store the capability verifier consults, so a grant withdrawn once is withdrawn everywhere rather than separately in each seam that honours it.

NIL means this image holds no such record: the case in a unit test and on a node that has not started. Nothing has been withdrawn there because there is nowhere to have withdrawn it.

What the dial being evaluated is made on behalf of, offered to a named scope.

Scope name to the function this node answers that scope's members with.

The designation of a grant that reaches every destination.

The prefix of a grant whose reach is narrowed by its trailing segment, in the shape the listener-bind designation already established for a parameter carried in a designation.

The designation held by something permitted to reach those secondaries and nothing else.

The scope naming the secondaries this node's zones are configured to notify.

Every trailing segment that names a set of destinations rather than one destination.

The clients node code issues dial grants to. A module never takes one of these names, so an allowance the owner wrote for the node's own work never reaches a module that happens to be called the same.

(%resolve-destination destination &key (family :internet) port)

The addresses to try for DESTINATION, in the order they should be tried, as conses of address and family.

An address literal is answered as it was given and no resolver is consulted: a literal was never a name, and querying for one would put a destination on the wire that valis had no reason to ask about.

PORT is carried only so a failure names the whole destination the caller meant. Signals a subtype of the resolution failure when no address results.

(clear-name-cache)

Drop every cached answer.

Seconds an answer is held when the answer carries no lifetime of its own. The system resolver reports none, so one is supplied here; a resolver that does report one passes it through instead.

The function that answers whether this namespace holds an address of a family. A seam for the same reason as the resolver above: a development host holds addresses of both families, so the interesting answer cannot occur there.

The function a name is resolved through. A seam, so the two outcomes the system reports identically can be presented to a test directly. Without it the distinction this file draws could not be exercised anywhere but on a confined node, and a passing suite would imply a check that had never run.

(forget-reported-exempt-reaches)

Forget which reaches have been logged, so the next reach of each is logged again.

(install-outbound-tripwire)

Put the refusing check in front of the socket libraries' connect verbs. Idempotent.

(outbound-tripwire-escape-list)

The call sites this check lets through, as package-qualified function names.

(outbound-tripwire-installed-p)

True while the check stands in front of the socket libraries.

(uninstall-outbound-tripwire)

Put the socket libraries' own connect verbs back as they were. Idempotent.

How many stack frames the walk reads before giving up, in which case the connection is refused.

True for the extent of the seam's own connection attempt, and no longer.

The function called with an exemption entry, the address and the port each time a listed site connects.