Source code for fleetmesh_node.app.socket

"""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


[docs]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`."""
[docs] 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
[docs]class ControlError(Exception): pass
[docs]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
[docs]class Server(object): """Serves dispatch(cmd, args) -> result over the socket, one request per connection."""
[docs] 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
[docs] 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 # fleetmesh_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
[docs] 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
[docs] 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:])}
[docs]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()
[docs]def running(directory: str) -> bool: return os.path.exists(socket_path(directory))
[docs]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')
[docs]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: fleetmesh_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))