Source code for fleetmesh_node.compartment.sidecar

"""A sidecar, and the bridge compartment that is the node's only way to reach it.

Three words, kept apart because the node had one word for two things (audit
2026-10-07-3, finding "two things called sidecar"):

  compartment   in-process. Built, wired, started, ticked, restarted and
                retired by the Registry; its whole lifecycle is the node's.

  sidecar       a separate process the node reaches but does not contain:
                fips (Rust), libp2p (sixty-three packages, trio, will not
                install on 3.14), bacalhau, grasp, strfry. Kept out because its
                codebase, its dependencies, its runtime or its licence do not
                belong in `fleetmesh_node/` - which is standard library plus
                `cryptography`, so that a second implementer never inherits
                any of it. The node never starts or supervises one
                (`supervised` is False, and stays False until code honours it).

  bridge        the ONE compartment that fronts one sidecar. Everything on the
                node that needs a sidecar goes through its bridge - names it in
                `requires`/`uses` and calls `bridge.call()` or a method the
                bridge offers - and nothing else opens the sidecar's socket.
                So the sidecar's settings (PARAMS: endpoint, timeout), what it
                says (CHANNELS), what it measures (METRICS), what an operator
                can ask of it (COMMANDS) and how it fails (LIFECYCLE) are
                declared once, on the bridge, the way every other compartment
                declares them.

What a bridge gets from this base, so that every sidecar is reached the same way:

  - `SIDECAR`, a manifest: the protocol it speaks (`family/major`), what it
    wraps upstream, the command that runs it standalone, and the request that
    proves it is there.
  - a link state - unknown, up, down, incompatible - moved only by `call()`,
    said once each way on three declared channels and counted:
    `<name>.sidecar.reachable|unreachable|incompatible`.
  - the version gate (audit S1): every reply carries the protocol the sidecar
    speaks, and a different family or major is refused - a bridge that read a
    `/2` reply as `/1` would be wrong silently. On a link that is not up the
    manifest's `probe` goes first as a handshake, so a sidecar that speaks
    another major is refused before it is sent anything that carries data.
  - two commands on the control socket: `<name>.sidecar` (the manifest and the
    link now) and `<name>.probe` (ask the sidecar now).
  - `Lifecycle(restart=True)`: a bridge holds a link and nothing more, so a
    restart forgets the link and the next call finds out afresh. A wedged link
    that trips the breaker is restarted by its quarantine trial.
  - trouble when the sidecar is wanted and down or incompatible, naming what
    this node loses (`CONSEQUENCE`).

Two ways a sidecar runs, both described by the same manifest:

  bridge mode     the sidecar is already running - ours, or one on the market
                  (a strfry, a bacalhau) - and the bridge compartment in the
                  node talks to it.
  standalone      `SIDECAR.standalone` is the command that runs it on its own,
                  beside the node or on another host; the bridge does not care
                  who started it, only that its endpoint answers.

The transport is a unix socket carrying one JSON object per line, which is what
announce, p2p and fips already speak. HTTP (the class-A manifests in
fleetmesh_node/sidecars: grasp, ncontainer, magpie) arrives with the first bridge that
needs it; `TRANSPORTS` says what is implemented and a manifest naming another
is refused at import rather than at the first call.

Named `sidecar_bridge` because `fleetmesh_node/bridge` is the Universal Nostr Relay
Bridge, a compartment called `bridge` that fronts relays rather than a sidecar.
A package rather than a root module for the reason fleetmesh_node/lifecycle is one.
Standard library only.
"""
from __future__ import annotations

import dataclasses
import json
import socket
import threading
import time
from typing import Any, Callable, Mapping, Optional, TypedDict

from .. import channels as ch_mod
from .. import metrics as mx_mod
from . import lifecycle as lifecycle_mod
from .base import Compartment
from .command import Command

TRANSPORTS: tuple[str, ...] = ('unix',)
MAX_LINE: int = 1 << 20

# The link, as the bridge last found it.
UNKNOWN = 'unknown'            # not asked since start (or restart)
UP = 'up'                      # the last call was answered, in a protocol this bridge speaks
DOWN = 'down'                  # the last call was not answered, or was refused
INCOMPATIBLE = 'incompatible'  # answered, in a protocol family or major this bridge does not speak
LINKS: tuple[str, ...] = (UNKNOWN, UP, DOWN, INCOMPATIBLE)


[docs]class SidecarError(Exception): """No sidecar, a sidecar that will not answer, or one that says no."""
[docs]class SidecarIncompatible(SidecarError): """A sidecar that answered in a protocol this bridge does not speak."""
[docs]class SidecarRecord(TypedDict): name: str protocol: str upstream: str transport: str standalone: str probe: str supervised: bool
[docs]class LinkRecord(TypedDict): sidecar: SidecarRecord endpoint: str link: str since: int protocol: str # what the sidecar last said it speaks; '' when it did not say last_error: str calls: int failures: int
[docs]class ProbeRecord(TypedDict, total=False): """What `<name>.probe` answers: the link, and the status or the error.""" link: str protocol: str status: object error: str
[docs]@dataclasses.dataclass(frozen=True) class Sidecar: """What a bridge fronts. Declared on the bridge as `SIDECAR`. name the sidecar's name; also the bridge compartment's protocol `family/major` this bridge speaks, e.g. 'fleetmesh-announce/1' upstream what the sidecar wraps, for a person: 'py-libp2p gossipsub' transport how it is reached; one of TRANSPORTS standalone the command that runs it on its own, for the docs and the `sidecar` command; '' when it has none probe the request that proves it is there and returns its status supervised False: the node depends on it and never starts or restarts it. Refused when True until the code that would honour it exists - a declared supervisor nothing runs is worse than none. """ name: str protocol: str upstream: str transport: str = 'unix' standalone: str = '' probe: str = 'status' supervised: bool = False def __post_init__(self) -> None: family, _, major = self.protocol.rpartition('/') if not family or not major.isdigit(): raise ValueError('sidecar %s: protocol is family/major, got %r' % (self.name, self.protocol)) if self.transport not in TRANSPORTS: raise ValueError('sidecar %s: transport %r is not implemented (have: %s)' % (self.name, self.transport, ', '.join(TRANSPORTS))) if self.supervised: raise ValueError('sidecar %s: supervised=True is not honoured yet; the node depends on a ' 'sidecar and never starts it' % self.name) @property def family(self) -> str: return self.protocol.rpartition('/')[0] @property def major(self) -> str: return self.protocol.rpartition('/')[2]
[docs] def compatible(self, said: str) -> bool: """Whether a sidecar that says it speaks `said` speaks this bridge's protocol. Same family, same major; a minor (`/1.3`) is additive. An unstated protocol is accepted - the sidecars predate the field - and the link records that it was not stated.""" if not said: return True family, _, version = said.rpartition('/') return family == self.family and version.split('.')[0] == self.major
[docs] def describe(self) -> SidecarRecord: return {'name': self.name, 'protocol': self.protocol, 'upstream': self.upstream, 'transport': self.transport, 'standalone': self.standalone, 'probe': self.probe, 'supervised': self.supervised}
[docs]def jsonline_call(path: str, cmd: str, timeout: float = 5.0, **args: Any) -> tuple[Any, str]: """One request, one reply, one connection, over a unix socket. Returns (result, the protocol the reply said it speaks, or ''). Raises SidecarError for all of no sidecar, a sidecar that will not answer, and a sidecar that says no. The wire was announce's; it is every unix sidecar's. """ s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) s.settimeout(timeout) try: try: s.connect(path) except OSError as e: raise SidecarError('no sidecar at %s (%s)' % (path, e.strerror or e)) try: s.sendall((json.dumps({'cmd': cmd, 'args': args}) + '\n').encode('utf-8')) buf = b'' while not buf.endswith(b'\n'): chunk = s.recv(65536) if not chunk: break buf += chunk if len(buf) > MAX_LINE: raise SidecarError('the sidecar answered with more than %d bytes' % MAX_LINE) except socket.timeout: raise SidecarError('the sidecar did not answer within %.0fs' % timeout) except OSError as e: raise SidecarError('the sidecar closed the socket (%s)' % (e.strerror or e)) finally: s.close() if not buf: raise SidecarError('the sidecar closed the socket without answering') try: reply = json.loads(buf.decode('utf-8')) except (ValueError, UnicodeDecodeError) as e: raise SidecarError('the sidecar answered something that is not JSON (%s)' % e) if not isinstance(reply, dict): raise SidecarError('a reply is an object') said = str(reply.get('protocol') or '') if not reply.get('ok'): raise SidecarError(str(reply.get('error') or 'refused')) return reply.get('result'), said
def probe_unix_socket(path: str, request: Mapping[str, Any], timeout: float = 1.0) -> Optional[Mapping[str, Any]]: """Send one JSON line over a unix socket and return the parsed JSON object, or None on error.""" try: s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) s.settimeout(timeout) s.connect(path) s.sendall(json.dumps(dict(request)).encode('utf-8') + b'\n') from ..transport import lineproto resp = lineproto.read_json_line(s, cap=MAX_LINE) s.close() if isinstance(resp, dict): return resp except Exception: pass return None # ---- what every bridge declares, derived from its manifest ---------------------
[docs]def bridge_channels(name: str) -> tuple[ch_mod.Channel, ...]: return ( ch_mod.Channel( name='%s.sidecar.reachable' % name, description='The %s sidecar answered, in a protocol this bridge speaks.' % name, level=ch_mod.INFO, wire=lambda endpoint, protocol: {'endpoint': endpoint, 'protocol': protocol}, say='sidecar up at {endpoint} ({protocol})', tags=(name, 'sidecar', 'bridge')), ch_mod.Channel( name='%s.sidecar.unreachable' % name, description='The %s sidecar did not answer, or refused; what needs it waits.' % name, level=ch_mod.NOTE, wire=lambda why, endpoint: {'why': why, 'endpoint': endpoint}, say='sidecar not reachable at {endpoint} ({why})', tags=(name, 'sidecar', 'bridge')), ch_mod.Channel( name='%s.sidecar.incompatible' % name, description='The %s sidecar answered in a protocol this bridge does not speak.' % name, level=ch_mod.TROUBLE, wire=lambda said, wants: {'said': said, 'wants': wants}, say='sidecar speaks {said}; this bridge speaks {wants}', tags=(name, 'sidecar', 'bridge')), )
[docs]def bridge_metrics(name: str) -> tuple[mx_mod.Metric, ...]: return ( mx_mod.Metric(name='%s_sidecar_reachable' % name, description='Times the %s sidecar was found reachable.' % name, kind=mx_mod.COUNTER, counts='%s.sidecar.reachable' % name, tags=(name, 'sidecar')), mx_mod.Metric(name='%s_sidecar_unreachable' % name, description='Times the %s sidecar was found unreachable.' % name, kind=mx_mod.COUNTER, counts='%s.sidecar.unreachable' % name, tags=(name, 'sidecar')), mx_mod.Metric(name='%s_sidecar_incompatible' % name, description='Times the %s sidecar answered in a protocol this bridge does not speak.' % name, kind=mx_mod.COUNTER, counts='%s.sidecar.incompatible' % name, tags=(name, 'sidecar')), )
[docs]def bridge_commands(sc: Sidecar) -> tuple[Command, ...]: return ( Command( key='sidecar', name='%s sidecar' % sc.name.capitalize(), description='the sidecar this bridge fronts - what it wraps, the protocol it must speak, how to ' 'run it standalone - and the link to it as last found', tags=(sc.name, 'sidecar', 'bridge'), permission='%s/sidecar' % sc.name, run='bridge_state', reply='{sidecar, endpoint, link, since, protocol, last_error, calls, failures}'), Command( key='probe', name='Probe %s sidecar' % sc.name, description='ask the sidecar now (its `%s` request) rather than wait for the next tick' % sc.probe, tags=(sc.name, 'sidecar', 'bridge'), permission='%s/probe' % sc.name, process=(sc.name,), run='probe', reply='{link, protocol, status | error}'), )
def _merged(base: tuple[Any, ...], own: tuple[Any, ...], key: Callable[[Any], str]) -> tuple[Any, ...]: """The bridge's own declarations, then the base's it did not declare itself.""" have = {key(x) for x in own} return tuple(own) + tuple(x for x in base if key(x) not in have)
[docs]class Bridge(Compartment, abstract=True): """The compartment that fronts one sidecar. Subclass, declare `SIDECAR`, implement `endpoint()`, and reach the sidecar only through `call()`. Optional hooks: `wanted()` (False turns the link checks and trouble off, e.g. a sidecar the config has not enabled) and `forget()` (what the bridge must forget when its link is reset, at start and on every restart). """ SIDECAR: Optional[Sidecar] = None # What this node loses while the sidecar is down, for the trouble line. CONSEQUENCE: str = 'what needs it waits' LIFECYCLE: lifecycle_mod.Lifecycle = lifecycle_mod.Lifecycle(restart=True) timeout: float = 5.0 def __init_subclass__(cls, **kw: Any) -> None: sc = cls.__dict__.get('SIDECAR') if isinstance(sc, Sidecar): if cls.name and cls.name != sc.name: raise TypeError('bridge %s fronts sidecar %s: a bridge is named for its sidecar' % (cls.name, sc.name)) name = sc.name cls.CHANNELS = _merged(bridge_channels(name), tuple(cls.__dict__.get('CHANNELS', ())), lambda c: c.name) cls.METRICS = _merged(bridge_metrics(name), tuple(cls.__dict__.get('METRICS', ())), lambda m: m.name) cls.COMMANDS = _merged(bridge_commands(sc), tuple(cls.__dict__.get('COMMANDS', ())), lambda c: c.key) super().__init_subclass__(**kw)
[docs] def __init__(self, node: Any, clock: Optional[Callable[[], int]] = None) -> None: super().__init__(node, clock) self._link_lock: threading.Lock = threading.Lock() self._reset_link()
# ---- what a subclass provides --------------------------------------------- @property def sidecar(self) -> Sidecar: if self.SIDECAR is None: raise TypeError('%s declares no SIDECAR' % type(self).__name__) return self.SIDECAR
[docs] def endpoint(self) -> str: raise NotImplementedError('%s must say where its sidecar listens' % type(self).__name__)
[docs] def wanted(self) -> bool: return True
[docs] def forget(self) -> None: """What a reset link must take with it. Nothing, by default."""
# ---- the link -------------------------------------------------------------- def _reset_link(self) -> None: self.link: str = UNKNOWN self.link_since: int = self._now() self.link_protocol: str = '' self.link_error: str = '' self.calls: int = 0 self.call_failures: int = 0 self._up: Optional[bool] = None # the reachability the journal was last told self._said: Optional[str] = None # the last unreachable reason it was told
[docs] def start(self) -> None: # A fresh link: the next call finds out. Nothing is dialled here, so a # sidecar that hangs cannot hold the node's start. with self._link_lock: self._reset_link() self.forget()
[docs] def stop(self) -> Any: with self._link_lock: self._reset_link() return None
def _now(self) -> int: return int(getattr(self, 'clock', time.time)())
[docs] def call(self, cmd: str, **args: Any) -> Any: """The only way to the sidecar. Moves the link and says so once each way. On a link that is not up, the manifest's `probe` request goes first, as a handshake: the version gate must refuse BEFORE a request carrying data reaches a sidecar that would misread it, not after. One extra round trip per (re)connection, none while the link is up. Raises SidecarError (SidecarIncompatible for a protocol this bridge does not speak); the caller decides what a missing sidecar costs it. """ if self.link != UP and cmd != self.sidecar.probe: self._exchange(self.sidecar.probe, {}) return self._exchange(cmd, args)
def _exchange(self, cmd: str, args: Mapping[str, Any]) -> Any: now = self._now() kw = dict(args) to = float(kw.pop('timeout', self.timeout)) try: result, said = jsonline_call(self.endpoint(), cmd, timeout=to, **kw) except SidecarError as e: self.call_failures += 1 self._down(str(e), now) raise if not self.sidecar.compatible(said): self.call_failures += 1 self._incompatible(said, now) raise SidecarIncompatible('the %s sidecar speaks %s; this bridge speaks %s' % (self.sidecar.name, said, self.sidecar.protocol)) self.calls += 1 self.link_protocol = said self._reachable() return result
[docs] def probe(self) -> ProbeRecord: """Ask the sidecar now. Never raises: the answer says what happened.""" try: status = self.call(self.sidecar.probe) except SidecarError as e: return {'link': self.link, 'protocol': self.link_protocol, 'error': str(e)} return {'link': self.link, 'protocol': self.link_protocol, 'status': status}
def _move_link(self, to: str, now: int, error: str = '') -> bool: with self._link_lock: moved = to != self.link if moved: self.link, self.link_since = to, now self.link_error = error return moved def _down(self, why: str, now: int) -> None: self._move_link(DOWN, now, why) if self._up is not False or self._said != why: self.say('%s.sidecar.unreachable' % self.sidecar.name, why, self.endpoint()) self._said = why self.refusals.refuse('sidecar', 'not reachable', subject=self.endpoint(), detail={'error': why}, at=now) self._up = False self.forget() # it must be told again what it was told before def _incompatible(self, said: str, now: int) -> None: if self._move_link(INCOMPATIBLE, now, 'speaks %s' % said): self.say('%s.sidecar.incompatible' % self.sidecar.name, said, self.sidecar.protocol) self.refusals.refuse('sidecar', 'incompatible', subject=self.endpoint(), detail={'said': said, 'wants': self.sidecar.protocol}, at=now) self._up = False self.forget() def _reachable(self) -> None: self._move_link(UP, self._now()) if self._up is not True: self.say('%s.sidecar.reachable' % self.sidecar.name, self.endpoint(), self.link_protocol or 'protocol unstated') self._up = True self._said = None @property def available(self) -> bool: """Whether a compartment that depends on this sidecar should try now.""" return self.link == UP # ---- being watched ---------------------------------------------------------
[docs] def bridge_state(self) -> LinkRecord: return {'sidecar': self.sidecar.describe(), 'endpoint': self.endpoint(), 'link': self.link, 'since': self.link_since, 'protocol': self.link_protocol, 'last_error': self.link_error, 'calls': self.calls, 'failures': self.call_failures}
[docs] def sections(self) -> Mapping[str, Any]: return {'bridge': self.bridge_state()}
[docs] def trouble(self) -> list[str]: if not self.wanted(): return [] if self.link == INCOMPATIBLE: return ['the %s sidecar at %s %s; this bridge speaks %s - upgrade one of them' % (self.sidecar.name, self.endpoint(), self.link_error, self.sidecar.protocol)] if self.link == DOWN: return ['the %s sidecar is not reachable at %s; %s' % (self.sidecar.name, self.endpoint(), self.CONSEQUENCE)] return []
[docs]def bridges(compartments: Any) -> list[Bridge]: """The bridges among a node's compartments: every sidecar it reaches.""" return [c for c in compartments if isinstance(c, Bridge)]
__all__ = [ 'Bridge', 'DOWN', 'INCOMPATIBLE', 'LINKS', 'LinkRecord', 'MAX_LINE', 'ProbeRecord', 'Sidecar', 'SidecarError', 'SidecarIncompatible', 'SidecarRecord', 'TRANSPORTS', 'UNKNOWN', 'UP', 'bridge_channels', 'bridge_commands', 'bridge_metrics', 'bridges', 'jsonline_call', ]