fleetmesh-node 0.2.0__py3-none-any.whl

node/app/plugins.py

@@ -0,0 +1,76 @@
+"""Plugin loading and sidecar manifest helpers for NodeApp."""
+from __future__ import annotations
+
+import importlib
+from typing import Any, Sequence
+
+from .. import compartment as compartment_mod
+from ..planes.services.sidecars import compartment as sidecars_mod
+
+__all__ = [
+    'load_plugins',
+    'plugin_sidecars',
+]
+
+
+def load_plugins(
+    specs: Sequence[Any],
+    manifest: Sequence[type[compartment_mod.Compartment]],
+) -> tuple[type[compartment_mod.Compartment], ...]:
+    """The manifest with each configured plugin class spliced in after its anchor.
+
+    A plugin ref is `package.module:Class`; the class must be a Compartment
+    with a name no manifest compartment uses. `after` names the compartment
+    it ticks right after (default: the end, before `updates` if that is
+    present, since updates reports on everything before it). Every failure
+    is a ValueError naming the ref: a node would rather not start than start
+    with a plugin it could not load, which is also why loading happens here
+    and not lazily in a tick.
+
+    This imports operator-declared code into the node's process. It is a
+    trust decision the config file states; see PluginsConfig.
+    """
+    out = list(manifest)
+    names: set[str] = {str(c.name) for c in out}
+    for spec in specs:
+        mod_name, _, cls_name = spec.ref.partition(':')
+        try:
+            mod = importlib.import_module(mod_name)
+        except ImportError as e:
+            raise ValueError('plugin %s: cannot import %s (%s)' % (spec.ref, mod_name, e)) from e
+        cls = getattr(mod, cls_name, None)
+        if not (isinstance(cls, type) and issubclass(cls, compartment_mod.Compartment)):
+            raise ValueError('plugin %s: %s is not a Compartment class' % (spec.ref, cls_name))
+        pname = getattr(cls, 'name', None)
+        if not pname:
+            raise ValueError('plugin %s declares no name' % spec.ref)
+        if pname in names:
+            raise ValueError('plugin %s: a compartment named %r already exists' % (spec.ref, pname))
+        if spec.after is None:
+            idx = len(out)
+            if out and out[-1].name == 'updates':
+                idx -= 1
+        else:
+            if spec.after not in names:
+                raise ValueError('plugin %s: after=%r names no compartment (have: %s)'
+                                 % (spec.ref, spec.after, ' '.join(sorted(names))))
+            idx = next(i for i, c in enumerate(out) if c.name == spec.after) + 1
+        out.insert(idx, cls)
+        names.add(pname)
+    return tuple(out)
+
+
+def plugin_sidecars(cls: type[Any]) -> list[sidecars_mod.Sidecar]:
+    """The sidecar manifests a plugin class declares, parsed and linted
+    (`sidecars = ({...}, '@/etc/x.json')`). Every failure is a ValueError
+    naming the plugin, so the same message serves startup and `plugin-check`."""
+    out: list[sidecars_mod.Sidecar] = []
+    for i, raw in enumerate(getattr(cls, 'sidecars', ()) or ()):
+        try:
+            if isinstance(raw, str) and raw.startswith('@'):
+                out.append(sidecars_mod.manifest_mod.load_file(raw[1:], origin=sidecars_mod.RESERVED_ORIGIN))
+            else:
+                out.append(sidecars_mod.manifest_mod.parse(raw, origin=sidecars_mod.RESERVED_ORIGIN))
+        except (sidecars_mod.ManifestError, OSError, ValueError) as e:
+            raise ValueError('plugin %s: sidecars[%d]: %s' % (getattr(cls, 'name', cls.__name__), i, e)) from e
+    return out

node/app/router.py

@@ -0,0 +1,83 @@
+"""Declarative protocol message router for DIDComm PIURI dispatch.
+
+Routes inbound envelopes to registered subsystem handlers based on their
+PIURI (Protocol Identification URI) prefix or exact message type.
+Standard library only.
+"""
+from __future__ import annotations
+
+import collections
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+HandlerFunc = Callable[[Any], Optional[Tuple[Any, ...]]]
+
+
+class ProtocolRouter:
+    """DIDComm protocol router mapping message types to subsystem handlers."""
+
+    def __init__(self) -> None:
+        self._exact_routes: Dict[str, HandlerFunc] = {}
+        self._prefix_routes: Dict[str, HandlerFunc] = {}
+        self._catchalls: List[HandlerFunc] = []
+        self._dispatch_counts: collections.Counter[str] = collections.Counter()
+
+    def register_exact(self, msg_type: str, handler: HandlerFunc) -> None:
+        """Register a handler for an exact DIDComm message type."""
+        self._exact_routes[msg_type] = handler
+
+    def register(self, prefix: str, handler: HandlerFunc) -> None:
+        """Register a handler for a PIURI prefix (e.g. 'https://fleetmesh.org/sync/1.0')."""
+        self._prefix_routes[prefix] = handler
+
+    def register_catchall(self, handler: HandlerFunc) -> None:
+        """Register a fallback handler invoked when no prefix matches or handler yields None."""
+        self._catchalls.append(handler)
+
+    def unregister(self, prefix_or_type: str) -> None:
+        """Remove a previously registered route."""
+        self._exact_routes.pop(prefix_or_type, None)
+        self._prefix_routes.pop(prefix_or_type, None)
+
+    def route_for(self, msg_type: str) -> Optional[HandlerFunc]:
+        """Find the most specific registered handler for a message type."""
+        if not msg_type:
+            return None
+        if msg_type in self._exact_routes:
+            return self._exact_routes[msg_type]
+        # Match longest prefix first
+        for prefix in sorted(self._prefix_routes.keys(), key=len, reverse=True):
+            if msg_type.startswith(prefix):
+                return self._prefix_routes[prefix]
+        return None
+
+    def dispatch(self, inbound: Any) -> Optional[Tuple[Any, ...]]:
+        """Dispatch an inbound envelope to the matching handler.
+
+        Returns the handler result (typically a status tuple), or None if unhandled.
+        """
+        msg = getattr(inbound, 'message', inbound)
+        msg_type = msg.get('type', '') if isinstance(msg, dict) else ''
+
+        handler = self.route_for(msg_type)
+        if handler is not None:
+            res = handler(inbound)
+            if res is not None:
+                self._dispatch_counts[msg_type] += 1
+                return res
+
+        for catchall in self._catchalls:
+            res = catchall(inbound)
+            if res is not None:
+                self._dispatch_counts[msg_type or 'catchall'] += 1
+                return res
+
+        return None
+
+    def registered_prefixes(self) -> List[str]:
+        """Return all registered PIURI prefixes."""
+        return sorted(self._prefix_routes.keys())
+
+    @property
+    def counts(self) -> collections.Counter[str]:
+        """Dispatch count by message type."""
+        return self._dispatch_counts

node/app/socket.py

@@ -0,0 +1,431 @@
+"""The control socket: how an operator asks a running node to do something.
+
+A running node owns its directory and its relay face port, so a second
+process cannot stand one up beside it to act on its behalf. Declarative
+state - peers, trust, coverage - goes through the config file, which the
+daemon re-reads every tick. An action - pull now, terminate a peering, ask
+a peer about a third node, force a tick - needs the daemon itself, and this
+is the channel: a unix socket in the node directory, one JSON object per
+line each way, readable and writable by the node's own user and nobody else.
+
+The protocol is named and versioned: `meshnode-control/1`. A request is
+{"cmd": name, "args": {...}}; a reply is {"ok": true, "protocol": ...,
+"result": ...} or {"ok": false, "protocol": ..., "error": reason}. The
+commands, their arguments and what each answers are served by the socket
+itself under `commands`, from the same table the daemon dispatches on, so
+what it says about itself cannot drift from what it does. A field is only
+ever added to a reply within a major version; a field removed or renamed is
+`meshnode-control/2`.
+
+The socket path is derived from the directory on both sides, so nothing
+has to be looked up. macOS limits a unix socket path to about a hundred
+bytes, and a test's temporary directory is longer than that, so a directory
+whose path will not fit gets a socket in the temp directory named by the
+hash of the real path. An operator's /var/lib/meshnode fits.
+"""
+from __future__ import annotations
+
+import hashlib
+import inspect
+import json
+import os
+import socket
+import tempfile
+import threading
+import time
+from typing import Any, Callable, Iterator, Mapping
+
+SOCK: str = 'control.sock'
+PROTOCOL: str = 'meshnode-control/1'
+MAX_LINE: int = 1 << 20
+
+
+class Stream(object):
+    """A dispatcher returns one of these for a verb that answers more than
+    once. The server sends the ack line, then one line per envelope `pull`
+    yields until the client closes or `pull` returns None past `idle`
+    seconds of silence with the client gone. `close` runs once at the end.
+    A streaming connection does not count against the request semaphore:
+    a reader that holds on for an hour must not starve `health`."""
+
+    def __init__(self, ack: Any, pull: Callable[[float], Any], close: Callable[[], None] | None = None) -> None:
+        self.ack: Any = ack
+        self.pull: Callable[[float], Any] = pull
+        self.close: Callable[[], None] | None = close
+
+
+class ControlError(Exception):
+    pass
+
+
+def socket_path(directory: str) -> str:
+    real = os.path.realpath(directory)
+    p = os.path.join(real, SOCK)
+    if len(p.encode()) < 100:
+        return p
+    return os.path.join(tempfile.gettempdir(),
+                        'meshnode-%s.sock' % hashlib.sha256(real.encode()).hexdigest()[:16])
+
+
+def _recv_line(conn: socket.socket) -> bytes:
+    buf = b''
+    while not buf.endswith(b'\n'):
+        chunk = conn.recv(65536)
+        if not chunk:
+            break
+        buf += chunk
+        if len(buf) > MAX_LINE:
+            raise ControlError('request too large')
+    return buf
+
+
+def _reader_alive(conn: socket.socket) -> bool:
+    try:
+        conn.setblocking(False)
+        try:
+            conn.recv(1, socket.MSG_PEEK)
+        finally:
+            conn.setblocking(True)
+    except BlockingIOError:
+        return True
+    except OSError:
+        return False
+    return False          # EOF, or the reader spoke: either way this stream is over
+
+
+class Server(object):
+    """Serves dispatch(cmd, args) -> result over the socket, one request per connection."""
+
+    def __init__(self, directory: str, dispatch: Callable[..., Any], max_conns: int = 16,
+                 max_streams: int = 32) -> None:
+        self.path: str = socket_path(directory)
+        self.dispatch: Callable[..., Any] = dispatch
+        # Whether the dispatcher wants to know who is calling. Decided once,
+        # here, rather than guessed per request: a dispatcher written before
+        # actors existed takes two arguments and keeps working, and one that
+        # wants attribution says so by accepting `actor`.
+        try:
+            self._wants_actor: bool = 'actor' in inspect.signature(dispatch).parameters
+        except (TypeError, ValueError):
+            self._wants_actor = False
+        self._stop: threading.Event = threading.Event()
+        self.sock: socket.socket | None = None
+        self.served: int = 0
+        self.streams: int = 0            # live streaming connections
+        self.max_conns: int = max_conns
+        self.max_streams: int = max_streams
+        self.errors: list[str] = []
+        self._sem: threading.BoundedSemaphore = threading.BoundedSemaphore(max_conns)
+        self._slock = threading.Lock()
+        self._inode: int | None = None
+
+    def start(self) -> Server:
+        try:
+            os.unlink(self.path)
+        except OSError:
+            pass
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        old_umask = os.umask(0o177)
+        try:
+            self.sock.bind(self.path)
+            os.chmod(self.path, 0o600)
+        finally:
+            os.umask(old_umask)
+        # Remember which inode is ours, so stop() never removes a socket a
+        # newer node bound at the same path after this one lost it.
+        try:
+            self._inode = os.stat(self.path).st_ino
+        except OSError:
+            self._inode = None
+        # 0600 on the socket means nothing if another user can rename the
+        # directory entry out from under it before the operator connects.
+        try:
+            mode = os.stat(os.path.dirname(self.path)).st_mode
+        except OSError:
+            mode = 0
+        if mode & 0o022:
+            self.errors.append('the directory holding %s is group/world-writable; another user could replace the socket'
+                               % self.path)
+        self.sock.listen(max(64, self.max_conns * 2))
+        self.sock.settimeout(0.5)
+        threading.Thread(target=self._loop, daemon=True).start()
+        return self
+
+    def _refuse_busy(self, conn: socket.socket) -> None:
+        """Told off its own thread: a slow client must not stall accept()."""
+        try:
+            conn.settimeout(5.0)
+            reply = {'ok': False, 'protocol': PROTOCOL, 'error': 'too many concurrent control requests'}
+            conn.sendall((json.dumps(reply) + '\n').encode('utf-8'))
+        except OSError:
+            pass
+        finally:
+            conn.close()
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                assert self.sock is not None
+                conn, _ = self.sock.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            if not self._sem.acquire(blocking=False):
+                threading.Thread(target=self._refuse_busy, args=(conn,), daemon=True).start()
+                continue
+            threading.Thread(target=self._one_wrapped, args=(conn,), daemon=True).start()
+
+    def _one_wrapped(self, conn: socket.socket) -> None:
+        released = False
+        try:
+            stream = self._one(conn)
+            if stream is not None:
+                # Hand the slot back before the long part: the stream has its own cap.
+                self._sem.release()
+                released = True
+                self._stream(conn, stream)
+        finally:
+            if not released:
+                self._sem.release()
+
+    def _stream(self, conn: socket.socket, stream: Stream) -> None:
+        # The slot was taken in _one, when the cap was checked; this only
+        # hands it back.
+        try:
+            conn.settimeout(None)
+            conn.setblocking(True)
+            while not self._stop.is_set():
+                env = stream.pull(1.0)
+                if env is None:
+                    # Nothing to send. A reader that went away shows as EOF on
+                    # a non-blocking peek (a live one that has nothing to say
+                    # raises EWOULDBLOCK); the protocol has the reader say
+                    # nothing after the request, so anything else it sends is
+                    # also taken as "done".
+                    if not _reader_alive(conn):
+                        break
+                    continue
+                try:
+                    conn.sendall((json.dumps(env, default=str) + '\n').encode('utf-8'))
+                except OSError:
+                    break
+        finally:
+            with self._slock:
+                self.streams -= 1
+            if stream.close is not None:
+                try:
+                    stream.close()
+                except Exception:
+                    pass
+            try:
+                conn.close()
+            except OSError:
+                pass
+
+    def _one(self, conn: socket.socket) -> Stream | None:
+        """Answer one request. Returns the Stream to keep serving, or None when the connection is done."""
+        stream: Stream | None = None
+        raw_stream: Stream | None = None
+        reserved = False            # a stream slot taken below, handed to _stream or back
+        try:
+            conn.settimeout(30)
+            try:
+                try:
+                    req = json.loads(_recv_line(conn).decode('utf-8'))
+                except (UnicodeDecodeError, json.JSONDecodeError) as e:
+                    # The client's fault, not a bug in a command: say so and
+                    # keep it out of the error ring an operator reads.
+                    raise ControlError('a request is one line of JSON: %s' % e)
+                if not isinstance(req, dict) or not isinstance(req.get('cmd'), str):
+                    raise ControlError('a request is {"cmd": ..., "args": {...}}; `commands` lists them')
+                if not isinstance(req.get('args') or {}, dict):
+                    raise ControlError('args is an object')
+                # Who is asking, established at the boundary. SO_PEERCRED
+                # can only be read off the live connection, so this is the
+                # one place it exists; by the time a command runs the socket
+                # is a detail nobody downstream can recover.
+                #
+                # The claimed operator comes from the request and is exactly
+                # that - claimed. `Actor.assurance` and the proof ladder say
+                # what was actually established, and `peercred` names a unix
+                # user rather than a DID, so it corroborates and never
+                # identifies. Nothing here checks an ability: see the note in
+                # node/config/change.py on why enforcing one against a
+                # 0600 socket would be a control that protects nothing.
+                if self._wants_actor:
+                    result = self.dispatch(req['cmd'], req.get('args') or {},
+                                           actor=actor_of(conn, req))
+                else:
+                    result = self.dispatch(req['cmd'], req.get('args') or {})
+                if isinstance(result, Stream):
+                    # Check the cap and take the slot in one step, before the
+                    # ack goes out. The count used to rise only once _stream
+                    # began, after the ack, so a reader holding its ack was
+                    # not counted yet, and a second request in that gap passed
+                    # the check: two streams over a cap of one. CI hit it under
+                    # a parallel suite (audit 2026-10-15 follow-up).
+                    with self._slock:
+                        full = self.streams >= self.max_streams
+                        if not full:
+                            self.streams += 1
+                            reserved = True
+                    if full:
+                        if result.close is not None:
+                            result.close()
+                        raise ControlError('too many open streams (%d); close one' % self.max_streams)
+                    stream = result
+                    raw_stream = result
+                    result = result.ack
+                reply: Mapping[str, Any] = {'ok': True, 'protocol': PROTOCOL, 'result': result}
+            except ControlError as e:
+                reply = {'ok': False, 'protocol': PROTOCOL, 'error': str(e)}
+            except Exception as e:          # a bug in one command answers one request
+                if len(self.errors) >= 200:
+                    self.errors.pop(0)
+                self.errors.append('%s: %s' % (type(e).__name__, e))
+                reply = {'ok': False, 'protocol': PROTOCOL, 'error': '%s: %s' % (type(e).__name__, e)}
+            self.served += 1
+            conn.sendall((json.dumps(reply, default=str) + '\n').encode('utf-8'))
+        except OSError:
+            stream = None
+        finally:
+            if stream is None:
+                if reserved:            # the ack never reached the reader: no stream to serve
+                    with self._slock:
+                        self.streams -= 1
+                    if raw_stream is not None and raw_stream.close is not None:
+                        raw_stream.close()
+                conn.close()
+        return stream
+
+    def stop(self) -> None:
+        self._stop.set()
+        try:
+            if self.sock is not None:
+                self.sock.close()
+        except (OSError, AttributeError):
+            pass
+        # Only remove the socket this server bound. A node that lost the
+        # path to a newer one (a stale-socket replacement, a restart racing
+        # a slow shutdown) must not make the live node unreachable on its
+        # way out.
+        try:
+            if self._inode is not None and os.stat(self.path).st_ino == self._inode:
+                os.unlink(self.path)
+        except OSError:
+            pass
+
+    def state(self) -> Mapping[str, Any]:
+        """What `health` says about this socket."""
+        with self._slock:
+            streams = self.streams
+        return {'path': self.path, 'served': self.served, 'streams': streams,
+                'errors': list(self.errors[-5:])}
+
+
+def stream(directory: str, cmd: str, timeout: float | None = None, **args: Any) -> Iterator[Any]:
+    """Ask for a streaming verb and yield each envelope as it arrives. The
+    first value yielded is the ack (the request's own result); then one per
+    line until the node closes or the caller stops iterating. `timeout` is
+    how long to wait for the next line, None forever."""
+    path = socket_path(directory)
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.settimeout(timeout if timeout is not None else 90.0)
+    try:
+        s.connect(path)
+    except OSError as e:
+        s.close()
+        raise ControlError('no node is running in %s (%s)' % (directory, e.strerror or e))
+    try:
+        s.sendall((json.dumps({'cmd': cmd, 'args': args}) + '\n').encode('utf-8'))
+        # The ack and the first envelopes may arrive in one read; keep the remainder.
+        buf = b''
+        while b'\n' not in buf:
+            chunk = s.recv(65536)
+            if not chunk:
+                raise ControlError('the node closed the socket without answering')
+            buf += chunk
+            if len(buf) > MAX_LINE:
+                raise ControlError('reply too large')
+        raw, buf = buf.split(b'\n', 1)
+        reply = json.loads(raw.decode('utf-8'))
+        if not reply.get('ok'):
+            raise ControlError(reply.get('error') or 'refused')
+        yield reply.get('result')
+        s.settimeout(timeout)
+        while True:
+            while b'\n' in buf:
+                line, buf = buf.split(b'\n', 1)
+                if line:
+                    yield json.loads(line.decode('utf-8'))
+            try:
+                chunk = s.recv(65536)
+            except socket.timeout:
+                raise ControlError('no event within %.0fs' % (timeout or 0))
+            if not chunk:
+                return
+            buf += chunk
+    finally:
+        s.close()
+
+
+def running(directory: str) -> bool:
+    return os.path.exists(socket_path(directory))
+
+
+def call(directory: str, cmd: str, timeout: float = 90.0, request: Mapping[str, Any] | None = None, **args: Any) -> Any:
+    """Ask the node running in `directory` to do one thing. Raises ControlError
+    when there is no node to ask, or when the node says no.
+
+    `timeout` is how long this client waits. A request argument that shares
+    the name (pull's own `timeout`) goes in `request`, which is merged over
+    `args`; before that, `meshnode pull --timeout` never reached the daemon."""
+    path = socket_path(directory)
+    if request:
+        args = {**args, **request}
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.settimeout(timeout)
+    try:
+        s.connect(path)
+    except OSError as e:
+        s.close()
+        raise ControlError('no node is running in %s (%s)' % (directory, e.strerror or e))
+    try:
+        s.sendall((json.dumps({'cmd': cmd, 'args': args}) + '\n').encode('utf-8'))
+        raw = _recv_line(s)
+    except socket.timeout:
+        raise ControlError('the node did not answer within %.0fs' % timeout)
+    finally:
+        s.close()
+    if not raw:
+        raise ControlError('the node closed the socket without answering')
+    reply = json.loads(raw.decode('utf-8'))
+    if not reply.get('ok'):
+        raise ControlError(reply.get('error') or 'refused')
+    return reply.get('result')
+
+
+def actor_of(conn: 'socket.socket', req: Mapping[str, Any]) -> Any:
+    """Who made this request, with every rung that answered recorded.
+
+    Built here because SO_PEERCRED can only be read off a live connection.
+    The operator and session are whatever the caller sent - a claim, marked
+    as one - and the peercred rung corroborates that a local user made the
+    call without ever claiming to identify a DID.
+
+    Imported lazily: node/control.py is reached by the CLI as well as the
+    daemon, and the config package pulls in the whole typed config tree.
+    """
+    from ..config import change as change_mod            # noqa: PLC0415
+    claimed = str(req.get('operator') or '')
+    proofs = [change_mod.asserted(claimed)] if claimed else []
+    cred = change_mod.peercred_of(conn)
+    if cred is not None:
+        proofs.append(cred)
+    return change_mod.Actor(
+        operator=claimed,
+        session=str(req.get('session') or ''),
+        tool=str(req.get('tool') or change_mod.LOCAL_TOOL),
+        at=int(time.time()),
+        proofs=tuple(proofs))

node/app/systemd.py

@@ -0,0 +1,36 @@
+"""sd_notify: the one line the node says to systemd.
+
+Separate because it touches a socket and nothing else here does; the
+config module should not need `socket`.
+"""
+from __future__ import annotations
+
+import os
+import socket
+
+
+def sd_notify(state: str) -> bool:
+    """Send state notification to systemd's service manager via NOTIFY_SOCKET.
+
+    Zero-dependency Unix datagram implementation supporting filesystem and abstract sockets.
+    Returns True if sent successfully, False otherwise.
+    """
+    notify_socket = os.environ.get('NOTIFY_SOCKET')
+    if not notify_socket:
+        return False
+
+    if notify_socket.startswith('@'):
+        notify_socket = '\0' + notify_socket[1:]
+
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+        try:
+            payload = state.encode('utf-8')
+            if not payload.endswith(b'\n'):
+                payload += b'\n'
+            sock.sendto(payload, notify_socket)
+            return True
+        finally:
+            sock.close()
+    except Exception:
+        return False