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