7. Services & Lifecycle (fleetmesh_core.services)

The fleetmesh_core.services package provides service state machines, peer/service discovery definitions, NIP-90 Data Vending Machine (DVM) contracts, and nsite publishing logic.

7.1. Lifecycle State Machine

The node says it is alive, and the node says it is finished: heartbeat (21801) and revocation (11802).

Two kinds the specification defines and the reference had not built. Each is small, and each carries one rule that is only real once it is executable: a heartbeat that contradicts the descriptor is a misreport about itself, a leaf publishes none at all, and a revocation transfers nothing to a successor.

Writing the heartbeat found one construction the prose named and never defined: the endpoints digest. It is stated in constants.json (descriptor.endpoints_digest) and computed here.

retiring is the other thing a heartbeat can say, and it is the only thing in this protocol that tells a departure from a silence. Under FLP a node that went away and one that went quiet cannot be told apart, so a peer holding a schedule against a node that has retired records a partition it was told about in advance. FLP forbids inferring the difference. It does not forbid the node saying it.

The coverage claim moved to fleetmesh_core/peering/coverage.py, where the handover door lives with it.

fleetmesh_core.services.lifecycle.endpoints_digest(endpoint_tags)[source]

SHA256 over the canonical JSON of the sorted [scheme, address] pairs.

The preference value is left out on purpose: it is advice about which address to try first, not a fact about what is being served, and a node reordering its preferences has not changed where it can be reached.

Parameters:

endpoint_tags (Sequence[Sequence[str]])

Return type:

str

fleetmesh_core.services.lifecycle.heartbeat(pubkey, node_class, endpoint_tags, now, load=None, retiring=False)[source]

A kind 21801. Names no peer and carries nothing about accounting.

retiring says this node is going, now and on purpose. It is the only thing in this protocol that distinguishes a departure from a silence, and it exists because nothing else can: under FLP a dead node and a quiet one are the same, so a peer that keeps a schedule against a node which has retired records a partition it was told about in advance. The flag is advisory and carries no obligation - a reader that ignores it is where every reader already was.

Parameters:
Return type:

UnsignedNostrEvent

fleetmesh_core.services.lifecycle.is_retiring(hb)[source]

Does this heartbeat say its publisher is on its way out?

A statement about itself, like the class beside it, and trusted the same way: it costs the publisher its own liveness and buys it nothing. A node that lied about retiring would be telling its peers to stop expecting it, which is the one lie that cannot be made to pay.

Parameters:

hb (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.lifecycle.check_heartbeat(hb, descriptor)[source]

Everything a reader may hold a heartbeat to. Returns (problems, findings).

problems are structural and make the heartbeat invalid. findings are (severity, why) against the publisher: a class that contradicts the live descriptor is a misreport about itself, which the ladder prices as S2.

Parameters:
Return type:

tuple[list[str], list[tuple[str, str]]]

fleetmesh_core.services.lifecycle.descriptor_is_stale(hb, descriptor)[source]

True when the heartbeat’s endpoint digest differs from the descriptor’s.

This is the reason the digest exists: a peer holding a descriptor learns it has gone stale without dialling every address in it.

Parameters:
Return type:

bool

fleetmesh_core.services.lifecycle.heartbeat_due(node_class, last_at, now, shortest_grant_window=None)[source]

Anchors MUST publish at least hourly, and at least once per their shortest active grant window if that is shorter. Edges SHOULD. Leaves never.

Parameters:
  • node_class (str)

  • last_at (int | None)

  • now (int)

  • shortest_grant_window (int | None)

Return type:

bool

fleetmesh_core.services.lifecycle.revocation(pubkey, reason, now, successor=None, content='')[source]

A kind 11802. The key being retired publishes it, so pubkey is that key.

Parameters:
Return type:

UnsignedNostrEvent

fleetmesh_core.services.lifecycle.check_revocation(ev)[source]

Structural. Whether the key holder is the operator or a thief is not decidable here, which is the whole reason a successor inherits nothing.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

list[str]

fleetmesh_core.services.lifecycle.successor_of(ev)[source]
Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

str | None

7.2. Service Discovery

Kind 30166: the node’s relay face described for anyone who reads NIP-66.

A relay list or an explorer that knows nothing about fleetmesh finds relays through NIP-66 discovery events. A node with a public face MAY publish one about itself, one per endpoint, so that it is found the way any relay is.

It says what the face is and what it accepts and nothing about how well it performs. NIP-66 has rtt tags for a monitor that dialled the relay; a node timing itself would be publishing a claim about itself, which is the thing the heartbeat was designed not to do. Liveness and latency belong to a monitor. Everything here is read from things the node already publishes or serves: the descriptor’s endpoints, the face’s NIP-11 document, the shards it claims. The shape is discovery in constants.json.

fleetmesh_core.services.discovery.network(url)[source]

NIP-66’s n tag for an address: tor, i2p or clearnet, by the host.

Parameters:

url (str)

Return type:

str

fleetmesh_core.services.discovery.requirement_tags(nip11)[source]

One R tag per limitation the face declares, false ones prefixed with !. A limitation the document does not mention is not asserted either way.

Parameters:

nip11 (NIP11RelayInfo | Mapping[str, Any] | None)

Return type:

list[list[str]]

fleetmesh_core.services.discovery.settled(event)[source]

What a discovery event claims, with the moving parts taken out.

A node republishes one of these when what it says changes, and decided that by comparing the whole event to the last one. The document carries an absolute timestamp, so nothing ever compared equal and “only when it changes” meant every tick: a kind 30166 to every relay every 35 seconds, about 2,500 a day per node, for a face that had not moved in a week.

The published event still carries the live value. This is only the question of whether it is worth publishing again.

Parameters:

event (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

str

fleetmesh_core.services.discovery.discovery(descriptor, nip11, shards, now=None)[source]

The kind 30166 events a node publishes about its own face: one per ws or wss endpoint the descriptor declares, unsigned. Nothing to declare means nothing to publish.

Parameters:
Return type:

list[UnsignedNostrEvent]

fleetmesh_core.services.discovery.check_discovery(event, descriptor=None)[source]

Everything a reader may hold a discovery event to. Returns problems.

Parameters:
Return type:

list[str]

7.3. Discovery Definitions

discover-features/2.0 on the wire: a peer asks what this node speaks, and the answer is the descriptor’s c tags said back in DIDComm’s shape.

The protocol is DIDComm’s (https://didcomm.org/discover-features/2.0), reused unchanged: queries carries [{feature-type, match}], disclose carries [{feature-type, id}]. What fleetmesh fixes is the source of the answer. The descriptor is the binding declaration, so a disclose that names a protocol the descriptor does not is a lie this node will not tell and a peer may report; fleetmesh_core/peering/peering.Node.disclose is the pure answer and this module is the envelope around it.

Only feature-type protocol is answered. A query for another type gets an empty disclosure, which is what DIDComm says a node that does not have the feature says.

class fleetmesh_core.services.discover.QueryItem

Bases: TypedDict

match: str
class fleetmesh_core.services.discover.DiscloseItem

Bases: TypedDict

id: str
class fleetmesh_core.services.discover.QueriesBody

Bases: TypedDict

queries: list[QueryItem]
class fleetmesh_core.services.discover.DiscloseBody

Bases: TypedDict

disclosures: list[DiscloseItem]
class fleetmesh_core.services.discover.Queries

Bases: TypedDict

id: str
type: str
from: str
to: list[str]
body: QueriesBody
class fleetmesh_core.services.discover.Disclose

Bases: TypedDict

id: str
type: str
from: str
to: list[str]
thid: str
body: DiscloseBody
fleetmesh_core.services.discover.queries(from_did, to_did, matches, msg_id)[source]

A queries message asking about the protocols that match each entry; a match ending in * is a prefix, anything else must equal the id.

Parameters:
Return type:

Queries

fleetmesh_core.services.discover.is_queries(msg)[source]
Parameters:

msg (Queries | DIDCommMessage | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.discover.query_list(msg)[source]

The queries a message carries, malformed entries dropped. An empty list means everything, which is DIDComm’s reading of no filter.

Parameters:

msg (Queries | DIDCommMessage | Mapping[str, Any])

Return type:

list[dict[str, str]]

fleetmesh_core.services.discover.disclose(from_did, to_did, thid, disclosures, msg_id=None)[source]

The reply: disclosures is what fleetmesh_core/peering/peering.Node.disclose returned, threaded to the queries that asked.

Parameters:
Return type:

Disclose

fleetmesh_core.services.discover.disclosed_ids(msg)[source]

The protocol identifiers a disclose names, in order.

Parameters:

msg (Disclose | DIDCommMessage | Mapping[str, Any])

Return type:

list[str]

7.4. NIP-90 Data Vending Machine (DVM)

NIP-90 ingress (profile nip90-ingress): the bytes a DVM gateway speaks.

Three things are pinned here and in vectors/nip90.json, nothing else:

  1. A request (kind 5000-5999) parses to one ParsedRequest: i tags are inputs, param tags a str->str map (last wins), output the mime, bid msat, relays only ws/wss entries.

  2. A parsed request maps to a job descriptor by executor, chosen in the order zk, llm, bacalhau, agent, then WASM - from the kind first, then the executor/engine params. The WASM job’s input.sha256 is the sha256 of the canonical JSON of {prompt, inputs, params}.

  3. Feedback is kind 7000 with tags e, p, status[, extra]; a result is kind request+1000 with tags e, p, request (the request event in the protocol’s canonical form - constants.json canonical.form), then amount / commit when non-zero.

The job descriptor is what the gateway hands its compute compartment; a second node may run a different executor set but MUST produce these descriptors for these requests, since the result’s request tag and commit are compared against them downstream.

exception fleetmesh_core.services.dvm.DVMError[source]

Bases: ValueError

class fleetmesh_core.services.dvm.ParsedRequest[source]

Bases: TypedDict

id: str
pubkey: str
kind: int
content: str
inputs: list[list[str]]
params: dict[str, str]
output_mime: str
bid_msat: int
relays: list[str]
class fleetmesh_core.services.dvm.ZkProof[source]

Bases: TypedDict

pi_a: Sequence[str]
pi_b: Sequence[Sequence[str]]
pi_c: Sequence[str]
protocol: str
curve: str
class fleetmesh_core.services.dvm.ZkInput[source]

Bases: TypedDict

request_id: str
curve: str
proof: ZkProof | Mapping[str, Any]
public_inputs: list[Any]
vk: Any
vk_sha256: str
class fleetmesh_core.services.dvm.LLMSampling[source]

Bases: TypedDict

max_tokens: int
temperature: float
top_p: float
seed: int
class fleetmesh_core.services.dvm.LLMGrammar[source]

Bases: TypedDict

type: str
definition: str
json_schema: Any
response_format: str
guided_regex: str
class fleetmesh_core.services.dvm.LLMMessage[source]

Bases: TypedDict

role: str
content: str
class fleetmesh_core.services.dvm.WasmModule[source]

Bases: TypedDict

runtime: str
sha256: str
url: str
class fleetmesh_core.services.dvm.WasmInput[source]

Bases: TypedDict

request_id: str
sha256: str
raw: str
class fleetmesh_core.services.dvm.StorageMount[source]

Bases: TypedDict

cas_provider: str
source_cid: str
mount_path: str
class fleetmesh_core.services.dvm.MediaInput[source]

Bases: TypedDict

request_id: str
profile: str
source_url: str
source_sha256: str
source_tree_root: str
duration_sec: float
duration_limit_sec: float
start_sec: float
is_audio: bool
width: int
height: int
video_bitrate_kbps: int
audio_bitrate_kbps: int
audio_sample_rate_hz: int
vod_id: str
source_path: str
output_path: str
allow_synthetic: bool
sha256: str
data: str
type: str
start: float
duration: float
class fleetmesh_core.services.dvm.JobVerify[source]

Bases: TypedDict

mode: str
proof_system: str
sample_rate: float
class fleetmesh_core.services.dvm.Job[source]

Bases: TypedDict

executor: str
module: WasmModule | Mapping[str, Any]
input: ZkInput | WasmInput | MediaInput | Mapping[str, Any]
verify: JobVerify | Mapping[str, Any]
fuel_max: int
model: str
prompt: str
messages: list[LLMMessage | Mapping[str, Any]]
sampling: LLMSampling | Mapping[str, Any]
grammar: LLMGrammar | Mapping[str, Any]
engine: str
image: str
entrypoint: list[str]
storage_mounts: list[StorageMount | Mapping[str, Any]]
resources: Mapping[str, int | str | float]
task: str
max_steps: int
wasi_profile: str
nonce: str
blob_store: Any
blossom_servers: Sequence[str]
fleetmesh_core.services.dvm.is_request(ev)[source]
Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.dvm.is_result(ev)[source]
Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.dvm.result_kind(request_kind)[source]
Parameters:

request_kind (int)

Return type:

int

fleetmesh_core.services.dvm.parse_request(ev)[source]
Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

ParsedRequest

fleetmesh_core.services.dvm.is_zk(p)[source]
Parameters:

p (ParsedRequest)

Return type:

bool

fleetmesh_core.services.dvm.is_llm(p)[source]
Parameters:

p (ParsedRequest)

Return type:

bool

fleetmesh_core.services.dvm.is_bacalhau(p)[source]
Parameters:

p (ParsedRequest)

Return type:

bool

fleetmesh_core.services.dvm.is_agent(p)[source]
Parameters:

p (ParsedRequest)

Return type:

bool

fleetmesh_core.services.dvm.is_media(p)[source]
Parameters:

p (ParsedRequest)

Return type:

bool

fleetmesh_core.services.dvm.executor_of(p)[source]
Parameters:

p (ParsedRequest)

Return type:

str

fleetmesh_core.services.dvm.zk_job(p, fuel_max=2500000000)[source]

Groth16 proof verification: proof, public inputs and vk from content or i tags.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.llm_job(p, fuel_max=2500000000)[source]

An inference request: messages, sampling and an optional grammar.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.bacalhau_job(p, fuel_max=2500000000)[source]

A container job: image, entrypoint, Blossom-mounted inputs, resources.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.agent_job(p, fuel_max=2500000000)[source]

A ReAct agent task with a step cap.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.media_job(p, fuel_max=2500000000)[source]

A NIP-90 kind=5201 video/audio transcode job for FfmpegTranscodeExecutor.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.wasm_job(p, executor='wasm', fuel_max=2500000000)[source]

The deterministic WASM job. The module is named by the requester (param module <sha256>, optional param module_url); with none named there is nothing real to run and a gateway refuses rather than inventing.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.request_to_job(ev, executor='wasm', fuel_max=2500000000)[source]

Map a NIP-90 request into the job descriptor the mesh runs.

Parameters:
Return type:

Job

fleetmesh_core.services.dvm.feedback(signer_sk, request_ev, status, now, extra='', extra_tags=None)[source]

Kind 7000: tags e, p, status[, extra]; content is extra or the status.

Parameters:
Return type:

NostrEvent

fleetmesh_core.services.dvm.result(signer_sk, request_ev, content, now, amount_msat=0, commit='', extra_tags=None)[source]

Kind request+1000: tags e, p, request, then amount / commit / extras.

Parameters:
Return type:

NostrEvent

7.5. nsite Decentralized Hosting

nsite (NIP-5A static websites): the pure part of the host server.

Everything here is a function of its arguments - no sockets, no stores - so a node’s compartment (meshnode: node/nsite.py) can be thin and these rules are held to vectors/nsite.json and the NIP’s own vectors (core/tests/test_nsite.py).

What the NIP says, in the order a request meets it:

  1. A site is an event. Kind 15128 is the pubkey’s ROOT site (replaceable, no d), kind 35128 a NAMED site (d = site id), kind 5128 a SNAPSHOT (regular event; an immutable copy of a manifest at one moment).

  2. The host parses the LEFT-MOST DNS label of the Host header:

    npub1… root site of that pubkey v + 50 base36 chars snapshot by event id 50 base36 chars + 1-13 [a-z0-9-] named site: base36(pubkey) + d tag

    Anything else is “not found”.

  3. The manifest’s path tags map an absolute path to a sha256. A request path that does not end in a file name gets index.html appended. A path with no tag falls back to /404.html; without that too, 404.

  4. The blob comes from the manifest’s server tags first, then the author’s kind-10063 (BUD-03) server list, then whatever the operator configured. Its sha256 MUST match before a byte is served.

The aggregate function is the NIP’s site version hash: sha256 of the sorted <sha> <path>n lines of the path tags, nothing else.

The domain tag is NOT in NIP-5A. It is this node’s extension: a manifest that carries [“domain”, “example.com”] consents to being served under that name, so a DNS record alone cannot make a gateway front someone’s site under a look-alike domain. The node that serves checks it; this module only reads it.

fleetmesh_core.services.nsite.b36_encode(raw)[source]

32 bytes -> 50 lowercase base36 chars, zero-padded on the left.

Parameters:

raw (bytes)

Return type:

str

fleetmesh_core.services.nsite.b36_decode(s)[source]

50 base36 chars -> 32 bytes; None if it is not that.

Parameters:

s (str)

Return type:

bytes | None

class fleetmesh_core.services.nsite.SiteRef[source]

Bases: object

Which manifest a request is for.

kind is KIND_ROOT, KIND_NAMED or KIND_SNAPSHOT. pubkey is hex (empty for a snapshot, whose author is whoever signed it), d the named-site id (’’ otherwise), event_id the snapshot id (’’ otherwise).

kind: int
pubkey: str
d: str
event_id: str
property label: str

The canonical left-most DNS label for this site.

filter()[source]

The REQ filter that fetches this manifest.

Return type:

NostrFilter

__init__(kind, pubkey='', d='', event_id='')
Parameters:
Return type:

None

fleetmesh_core.services.nsite.parse_label(label)[source]

The NIP’s left-most-label grammar. None means ‘not found’.

Parameters:

label (str)

Return type:

SiteRef | None

fleetmesh_core.services.nsite.parse_host(host, suffixes)[source]

A Host header against the gateway’s configured suffixes.

host may carry a port. For npub1x.nsite.example.org with suffix nsite.example.org the label is npub1x. A host that is exactly a suffix (the gateway’s own landing page) or under no suffix is None.

Parameters:
Return type:

SiteRef | None

fleetmesh_core.services.nsite.parse_txt_binding(txt)[source]

A _nsite.<domain> TXT value: npub1…, npub1…:<d> or v<snapshot>.

The named-site form takes the d tag after a colon so the domain owner does not have to produce the base36 label by hand.

Parameters:

txt (str)

Return type:

SiteRef | None

fleetmesh_core.services.nsite.is_manifest(ev, ref, *, allow_legacy=False)[source]

Does this event answer ref? Kind, author, d, id as the NIP demands.

Signature verification is the caller’s (fleetmesh_core.crypto.giftwrap.verify_event); this is only the shape check, so a snapshot cannot be substituted for a root.

Parameters:
Return type:

bool

fleetmesh_core.services.nsite.tag_value(tags, name)[source]
Parameters:
Return type:

str | None

fleetmesh_core.services.nsite.tag_values(tags, name)[source]
Parameters:
Return type:

list[str]

fleetmesh_core.services.nsite.paths_of(ev)[source]

path tags as {absolute path: sha256}. Malformed tags are skipped, not fatal: one bad tag must not take down the pages that are fine.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

dict[str, str]

fleetmesh_core.services.nsite.aggregate(ev)[source]

The NIP’s aggregate hash: sha256 over sorted `<sha> <path> ` lines.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

str

fleetmesh_core.services.nsite.claimed_domains(ev)[source]

domain tags (this node’s extension), normalised.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

set[str]

fleetmesh_core.services.nsite.normalize_domain(d)[source]
Parameters:

d (str)

Return type:

str

fleetmesh_core.services.nsite.allows_embed(ev)[source]

Whether the manifest opts into cross-origin iframe embedding ([“embed”, “allow”]).

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.nsite.frame_ancestors_of(ev)[source]

Explicit frame-ancestor origins declared via [“frame-ancestors”, “<origin>”] or [“embed”, “https://…”].

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

list[str]

fleetmesh_core.services.nsite.wants_cross_origin_isolation(ev)[source]

Whether the manifest requests COOP/COEP headers ([“isolation”, “coop-coep”]) for SharedArrayBuffer WASM.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

bool

fleetmesh_core.services.nsite.blossom_servers(ev, user_servers, fallback)[source]

Where to look for the site’s blobs, in the NIP’s order, de-duplicated: manifest server tags, the author’s 10063 server tags, then the operator’s fallback list.

Parameters:
Return type:

list[str]

class fleetmesh_core.services.nsite.Resolved[source]

Bases: object

What to serve: the blob and how to label it. status is 200 for the asked-for path, 404 when /404.html stood in for it.

path: str
sha256: str
content_type: str
status: int
__init__(path, sha256, content_type, status=200)
Parameters:
Return type:

None

fleetmesh_core.services.nsite.resolve_path(paths, request_path)[source]

Map a request path onto the manifest as the NIP says.

Directory requests (no file name, or a trailing slash) become index.html. .. and // are collapsed before lookup so a manifest cannot be walked. A miss serves /404.html with status 404 when the site has one; None means the site has nothing to say for this path.

Parameters:
Return type:

Resolved | None

fleetmesh_core.services.nsite.guess_type(path)[source]
Parameters:

path (str)

Return type:

str

7.6. Telemetry Collection

Kind 21802: the diagnostic telemetry a node may publish about itself.

Opt-in, and deliberately coarse. One event per sample window, aggregated over the whole node: how many wraps came in, how many were duplicates a relay replayed, how many were dropped before they reached a handler, and how much strain the node recorded. Nothing names a peer, a shard or a transport, which is why the counters are binned instead of exact: a reader learns whether the node is busy, not who is making it so.

Alpha measurement only. The bins and tag names are the protocol; the choice of what to count is this reference’s and a second node may count differently as long as it bins the same way.

fleetmesh_core.services.telemetry.bin_of(n)[source]

The coarse bin a counter lands in: the largest BINS entry at or below it, written as a floor. 0, 1, 10, 100, 1000 or 10000; a reader sees an order of magnitude and nothing finer.

Parameters:

n (int)

Return type:

str

fleetmesh_core.services.telemetry.telemetry(pubkey, now, sample_window, counters, expiration=None)[source]

One kind 21802. sample_window is the seconds the counters cover; counters is metric name -> raw count, binned here. Unknown metric names are dropped rather than carried, so a node cannot leak a per-peer counter under a name of its own. Tags: sample_window, metric (name, bin) per metric in METRICS order, expiration if given.

Parameters:
Return type:

UnsignedNostrEvent

fleetmesh_core.services.telemetry.check_telemetry(ev)[source]

Structural. Returns problems; empty means the event is well-formed.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

list[str]

fleetmesh_core.services.telemetry.read(ev)[source]

metric -> bin floor, for a well-formed event. Raises on a malformed one.

Parameters:

ev (NostrEvent | UnsignedNostrEvent | Mapping[str, Any])

Return type:

dict[str, int]

7.7. Unplug & Graceful Teardown

The unplug: a process that cannot reach a network, and a scan for what it might reach for.

The specification makes one claim about dependence and repeats it in three places. No bootstrap host, DNS domain or single operator is a hardwired constant. relay.example.org is an example and nothing else. Losing every seed domain slows a first run and does nothing to an established node. § Conformance turns that into a test: the whole suite again with every default anchor deleted, every fleetmesh.org lookup failing, and the bootstrap list stripped.

A claim like that decays quietly. Nobody adds a dependency on purpose; somebody adds a convenience, and a year later the network has a single point of failure nobody chose. So this is two mechanisms, not one:

cut_the_network() makes any socket or name lookup raise. Run a suite

under it and a suite that reaches out cannot pass.

reachable_constants() reads the source for addresses. A name nothing

resolves is still a dependency the day someone writes the code that resolves it.

The second needs a rule for what an address is, because this protocol is full of https:// strings that are names rather than locations - the DIDComm protocol identifiers, which the specification says are never dereferenced. The rule:

an example host example.org and friends. Fine, and the only host a

document is allowed to write down.

a loopback address 127.0.0.1 or localhost. Nothing to unplug: it

never leaves the machine.

a host with no dot wss://one. A placeholder nothing could resolve. a declared identifier a protocol URI schema/messages.json names, or a

didcomm.org protocol. Never fetched.

anything else reported. Including our own domain: a URL under

fleetmesh.org that is not one of the identifiers is something a node would fetch, and the unplug test deletes it.

Standard library only.

exception fleetmesh_core.services.unplug.Reached[source]

Bases: FleetmeshError, RuntimeError

Something tried to open a socket or resolve a name. Under the unplug test that is the failure, not an error on the way to one.

fleetmesh_core.services.unplug.cut_the_network()[source]

Make the network unavailable to this process, loudly.

Not a firewall and not a sandbox: it replaces the four entry points in socket that everything else in the standard library goes through, so a urllib call, an http.client call or a raw connect all end in Reached with the thing they were reaching for in the message.

Return type:

Callable[[…], Any]

fleetmesh_core.services.unplug.declared_identifiers(root)[source]

Protocol URIs that name a protocol rather than a location.

Read from schema/messages.json rather than listed here, so a protocol added to the schema does not have to be added twice, and a URL that is not in the schema cannot pass as an identifier by looking like one.

Parameters:

root (str)

Return type:

set[str]

fleetmesh_core.services.unplug.classify(url, identifiers)[source]

Why this URL is allowed to be here, or None if it is not.

Parameters:
Return type:

str | None

fleetmesh_core.services.unplug.reachable_constants(root, scanned=('fleetmesh_core', 'schema', 'manifests'))[source]

Every address in the shipped source that a node could actually go to.

Returns [(relative path, url, host)]. Empty is the claim: the reference, the digested constants and the example manifests name no host anyone has to reach.

test_*.py is skipped. A test is not something a node runs, and this suite has to be able to write down the URLs it rejects in order to check that it rejects them. The suites are covered by the other half of this module instead: they run with the network cut, so a test that reaches out fails rather than being scanned for.

Parameters:
Return type:

list[tuple[str, str, str]]