fleetmesh-node 0.2.0__py3-none-any.whl

node/compartment/command.py

@@ -0,0 +1,458 @@
+"""COMMANDS: what a compartment can be asked to do, declared where it is.
+
+Split out of node/compartment.py when it became a package. node/commands
+re-exports these for callers that think in commands rather than compartments.
+"""
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import Any, Callable, Mapping, Optional, Sequence, TypedDict, Union
+
+from ..config.parameter import Parameter, ParameterRecord
+from ..interfaces import CommandSpec
+from .problem import (DuplicateProblem, Problem, Problems, ReferenceProblem,
+                      TypeMismatchProblem)
+
+ParameterValue = Any
+
+
+class CommandRecord(TypedDict, total=False):
+    """A command as `meshnode commands`, control socket, and docs read it."""
+    key: str
+    name: str
+    description: str
+    tags: list[str]
+    parameters: list[ParameterRecord]
+    permission: str
+    permission_enforced: bool
+    process: list[str]
+    process_enforced: bool
+    reply: str
+    reads: list[str]
+    writes: list[str]
+    compartment: str
+
+
+class CommandError(ValueError):
+    """The caller asked wrongly: an argument missing, unknown, or not what
+    the command takes. A refusal the caller reads, never a fault in the
+    node - the control socket answers it as one (`ControlError`) and keeps
+    it out of the error ring that counts bugs."""
+
+
+@dataclasses.dataclass(frozen=True)
+class Command:
+    """One operation a compartment exposes, declared where the compartment is.
+
+    Declared once, in the compartment's COMMANDS, and answered by the base:
+    `Compartment.command` finds the declaration, checks the arguments against
+    it, and calls what `run` names. A compartment that declares COMMANDS does
+    not write its own `command()` - the if-chain that used to sit beside a
+    hand-kept `commands` dict was the second copy of every declaration.
+
+    Fields:
+      key: short name of the command on the compartment (e.g. 'show', 'test')
+      name: human-readable title (e.g. 'Show announce status')
+      description: full prose explanation of what it does
+      tags: categorization tags (e.g. ('announce', 'status'))
+      parameters: the arguments it takes, as Parameters. Nothing else is
+        accepted: an argument it does not declare is refused by name, so a
+        misspelt optional one is an error rather than silently its default.
+      permission: UCAN ability required (e.g. 'announce/show') - declared,
+        not yet enforced (see `describe`)
+      process: sequence of required processes / sidecars (e.g. ('sidecar',))
+      run: what answers it. The name of a method on the compartment, taking
+        either nothing or the checked arguments as one dict; or a callable
+        `(compartment, args)`. Checked when the compartment class is defined
+        (`problems`), so a name that does not resolve never reaches a node.
+      reply: description of return structure
+      reads / writes: the stores it reads and writes - this compartment's by
+        key, another's as `name.key` (one it requires or uses). Checked when
+        the compartment class is defined; the census reads them to say what
+        data each command touches.
+    """
+    key: str
+    name: str
+    description: str
+    tags: tuple[str, ...] = ()
+    parameters: tuple[Parameter[Any], ...] = ()
+    permission: str = ''
+    process: tuple[str, ...] = ()
+    run: Optional[Union[Callable[..., Any], str]] = None
+    reply: str = ''
+    reads: tuple[str, ...] = ()
+    writes: tuple[str, ...] = ()
+
+    def __init__(
+        self,
+        key: str,
+        name: str,
+        description: str,
+        tags: Sequence[str] = (),
+        parameters: Sequence[Parameter[Any]] = (),
+        permission: str = '',
+        process: Sequence[str] | str = (),
+        run: Optional[Union[Callable[..., Any], str]] = None,
+        reply: str = '',
+        *,
+        reads: Sequence[str] = (),
+        writes: Sequence[str] = (),
+    ) -> None:
+        object.__setattr__(self, 'key', key)
+        object.__setattr__(self, 'name', name)
+        object.__setattr__(self, 'description', description)
+        object.__setattr__(self, 'tags', tuple(tags))
+        object.__setattr__(self, 'parameters', tuple(parameters))
+        object.__setattr__(self, 'permission', permission)
+        procs = (process,) if isinstance(process, str) else tuple(process)
+        object.__setattr__(self, 'process', tuple(p for p in procs if p))
+        object.__setattr__(self, 'run', run)
+        object.__setattr__(self, 'reply', reply)
+        object.__setattr__(self, 'reads', tuple(reads))
+        object.__setattr__(self, 'writes', tuple(writes))
+
+    def resource(self, subsystem: str, node_did: str = '') -> str:
+        """The UCAN resource this command is, as `with` would name it.
+
+        Matches `Parameter.resource()` convention:
+        `command/<subsystem>.<key>`, prefixed with node_did if present.
+        """
+        path = 'command/%s.%s' % (subsystem, self.key)
+        return '%s#%s' % (node_did, path) if node_did else path
+
+    # ---- checked when the compartment class is defined ----------------------
+    def problems(self, cls: type) -> list[str]:
+        """Everything wrong with this declaration on compartment `cls`, as
+        sentences - collected by `Compartment.declaration_problems`, so a
+        command that cannot be answered fails at import, not on first use."""
+        out = Problems()
+        seen: set[str] = set()
+        # The annotations promise Parameters and a str-or-callable run; this
+        # is for the declaration that broke the promise, so look at what it
+        # actually holds.
+        params: tuple[object, ...] = tuple(self.parameters)
+        run: object = self.run
+        for p in params:
+            if not isinstance(p, Parameter):
+                out.append(TypeMismatchProblem('COMMANDS', 'node.config.Parameter', type(p).__name__,
+                                               message='command %s: parameters are node.config.Parameter, not %s' % (self.key, type(p).__name__)))
+                continue
+            if p.key in seen:
+                out.append(DuplicateProblem('COMMANDS', p.key, message='command %s declares parameter %r twice' % (self.key, p.key)))
+            seen.add(p.key)
+        if run is None:
+            out.append(Problem('command %s has no run: name the method that answers it' % self.key, surface='COMMANDS', code='missing_run', target=self.key))
+        elif isinstance(run, str):
+            fn = getattr(cls, run, None)
+            if fn is None or not callable(fn):
+                out.append(ReferenceProblem('COMMANDS', f"command {self.key}", run,
+                                            message='command %s runs %r, which %s has no method called' % (self.key, run, cls.__name__)))
+            elif _takes(fn, bound=False) is None:
+                out.append(Problem('command %s runs %s.%s, which must take nothing or one argument (the args)' % (self.key, cls.__name__, run),
+                                   surface='COMMANDS', code='invalid_signature', target=self.key))
+        elif not callable(run):
+            out.append(TypeMismatchProblem('COMMANDS', 'method name or a callable', type(run).__name__,
+                                           message='command %s: run is a method name or a callable, not %s' % (self.key, type(run).__name__)))
+        else:
+            try:
+                inspect.signature(run).bind(None, None)
+            except TypeError:
+                out.append(Problem('command %s: a callable run takes (compartment, args)' % self.key,
+                                   surface='COMMANDS', code='invalid_signature', target=self.key))
+            except ValueError:
+                pass            # a builtin with no signature to read; called as declared
+        return out
+
+
+    # ---- answered -----------------------------------------------------------
+    def validate_args(self, args: Optional[Mapping[str, Any]] = None) -> Mapping[str, ParameterValue]:
+        """The arguments, checked against what this command declares.
+
+        Every declared one is present in what comes back - the caller's
+        value coerced and checked, or the default. A required one missing,
+        a value that is not what the parameter states, or an argument the
+        command does not take at all is a CommandError naming it.
+        """
+        raw = dict(args or {})
+        declared = {p.key for p in self.parameters}
+        unknown = sorted(k for k in raw if k not in declared)
+        if unknown:
+            raise CommandError('%s takes no argument %s; it takes %s'
+                               % (self.key, ', '.join(map(repr, unknown)),
+                                  ', '.join(sorted(declared)) or 'none'))
+        resolved: dict[str, ParameterValue] = {}
+        for p in self.parameters:
+            v = raw.get(p.key)
+            if v is None:
+                if p.required:
+                    raise CommandError('%s needs %s' % (self.key, p.key))
+                resolved[p.key] = p.value()
+                continue
+            try:
+                v = _coerced(p, v)
+            except (TypeError, ValueError) as e:
+                raise CommandError('%s: %s %s' % (self.key, p.key, _must(p, e))) from e
+            if p.validate is None and not p.ok(v):
+                raise CommandError('%s: %s %s, not %r' % (self.key, p.key, _must(p), str(v)[:32]))
+            resolved[p.key] = v
+        return resolved
+
+    def execute(self, target: Any, args: Optional[Mapping[str, Any]] = None) -> Any:
+        """Answer this command on `target` (the compartment instance)."""
+        resolved = self.validate_args(args)
+        # If target has a check_command_dependencies hook, verify them
+        if hasattr(target, 'check_command_dependencies'):
+            target.check_command_dependencies(self)
+        if isinstance(self.run, str):
+            fn = getattr(target, self.run)
+            return fn(resolved) if _takes(fn, bound=True) else fn()
+        if callable(self.run):
+            return self.run(target, resolved)
+        raise TypeError('command %s has no run' % self.key)
+
+    def to_spec(self, subsystem: str = '') -> CommandSpec:
+        """Convert to legacy CommandSpec dictionary for backward compatibility."""
+        args_spec: dict[str, str] = {}
+        params: tuple[object, ...] = tuple(self.parameters)
+        for p in params:
+            # Derived at class creation, before the lint: a non-Parameter is
+            # left for `problems()` to name rather than crashing here.
+            if not isinstance(p, Parameter):
+                continue
+            if getattr(p, 'required', False):
+                args_spec[p.key] = 'required'
+            elif getattr(p, 'choices', None):
+                args_spec[p.key] = ' | '.join(str(c) for c in p.choices)
+            else:
+                args_spec[p.key] = 'optional'
+        spec: CommandSpec = {
+            'args': args_spec,
+            'does': self.description,
+            'reply': self.reply,
+        }
+        if subsystem:
+            spec['subsystem'] = subsystem
+        return spec
+
+    def describe(self) -> CommandRecord:
+        out: CommandRecord = {
+            'key': self.key,
+            'name': self.name,
+            'description': self.description,
+            'tags': list(self.tags),
+            'permission': self.permission,
+            'process': list(self.process),
+        }
+        # A declared ability must never read as an enforced one. `execute`
+        # validates arguments and asks the target to check dependencies; it
+        # does not check `permission`, and nothing authenticates a principal
+        # yet - the control socket is chmod 0o600 with no peer credential and
+        # no token. This is the same footing, and the same reason, as
+        # `Parameter.requires` and `config.change.ACCESS_DECLARED_ONLY`, and
+        # `requires_enforced: False` on a parameter row. Stated on the row
+        # because a row is what an operator reads.
+        if self.permission:
+            out['permission_enforced'] = False
+        # The dependency check is advisory in the same way: `execute` calls
+        # `check_command_dependencies` only when the target happens to have
+        # one, so a compartment without the hook declares its sidecars and
+        # nothing verifies them.
+        if self.process:
+            out['process_enforced'] = False
+        if self.reply:
+            out['reply'] = self.reply
+        if self.reads:
+            out['reads'] = list(self.reads)
+        if self.writes:
+            out['writes'] = list(self.writes)
+        if self.parameters:
+            out['parameters'] = [
+                {
+                    'key': p.key,
+                    'name': getattr(p, 'name', p.key),
+                    'description': getattr(p, 'description', ''),
+                    'type': getattr(getattr(p, 'type', object), '__name__', str(getattr(p, 'type', ''))),
+                    'default': getattr(p, 'default', None),
+                    'required': bool(getattr(p, 'required', False)),
+                    'live': bool(getattr(p, 'live', False)),
+                    'tags': list(getattr(p, 'tags', [])),
+                }
+                for p in self.parameters
+            ]
+        return out
+
+    def bind(self, target: Any) -> BoundCommand:
+        """Bind this command to a compartment instance."""
+        return BoundCommand(self, target)
+
+
+@dataclasses.dataclass(frozen=True)
+class Alias(Command):
+    """A command alias that forwards execution to a compartment command.
+
+    Declared in NODE_COMMANDS or a compartment's COMMANDS: exposes an alias
+    key (e.g. 'strain') that forwards to a target command (e.g. 'strain.show')
+    via the node's compartment registry.
+    """
+    target: str = ''
+
+    def __init__(
+        self,
+        key: str,
+        target: str,
+        description: str = '',
+        reply: str = '',
+        parameters: Sequence[Parameter[Any]] = (),
+        name: str = '',
+        tags: Sequence[str] = (),
+        permission: str = '',
+        process: Sequence[str] | str = (),
+    ) -> None:
+        super().__init__(
+            key=key,
+            name=name or key,
+            description=description,
+            tags=tags,
+            parameters=parameters,
+            permission=permission,
+            process=process,
+            run=None,
+            reply=reply,
+        )
+        object.__setattr__(self, 'target', target)
+
+    def problems(self, cls: type) -> list[str]:
+        out = Problems()
+        seen: set[str] = set()
+        params: tuple[object, ...] = tuple(self.parameters)
+        for p in params:
+            if not isinstance(p, Parameter):
+                out.append(TypeMismatchProblem('COMMANDS', 'node.config.Parameter', type(p).__name__,
+                                               message='alias %s: parameters are node.config.Parameter, not %s' % (self.key, type(p).__name__)))
+                continue
+            if p.key in seen:
+                out.append(DuplicateProblem('COMMANDS', p.key, message='alias %s declares parameter %r twice' % (self.key, p.key)))
+            seen.add(p.key)
+        if not self.target or not isinstance(self.target, str):
+            out.append(Problem('alias %s has no target: name the command it forwards to' % self.key,
+                               surface='COMMANDS', code='missing_target', target=self.key))
+        return out
+
+
+    def execute(self, target: Any, args: Optional[Mapping[str, Any]] = None) -> Any:
+        resolved = self.validate_args(args)
+        subsystems = getattr(target, 'subsystems', None)
+        if subsystems is None and hasattr(target, 'node'):
+            subsystems = getattr(target.node, 'subsystems', None)
+        if subsystems is not None:
+            return subsystems.dispatch(self.target, resolved)
+        raise RuntimeError('cannot dispatch alias %s to %s: target has no subsystems' % (self.key, self.target))
+
+
+@dataclasses.dataclass(frozen=True)
+class BoundCommand:
+    """A Command bound to a specific compartment instance."""
+    command: Command
+    target: Any
+
+    @property
+    def key(self) -> str:
+        return self.command.key
+
+    @property
+    def name(self) -> str:
+        return self.command.name
+
+    @property
+    def description(self) -> str:
+        return self.command.description
+
+    @property
+    def tags(self) -> tuple[str, ...]:
+        return self.command.tags
+
+    @property
+    def parameters(self) -> tuple[Parameter[Any], ...]:
+        return self.command.parameters
+
+    @property
+    def permission(self) -> str:
+        return self.command.permission
+
+
+    @property
+    def process(self) -> tuple[str, ...]:
+        return self.command.process
+
+
+    def __call__(self, args: Optional[Mapping[str, Any]] = None, **kw: Any) -> Any:
+        merged: dict[str, ParameterValue] = dict(args or {})
+        merged.update(kw)
+        return self.command.execute(self.target, merged)
+
+
+
+def _takes(fn: Callable[..., Any], bound: bool) -> Optional[bool]:
+    """Whether a run method takes the args: True, False, or None when it
+    takes something else. `bound` says whether `self` is already applied.
+
+    The args go only to a REQUIRED positional parameter. A method whose
+    positionals all have defaults - `sweep(self, now=None)` - is called bare:
+    its optional parameter is its own, and handing it the args dict would
+    set `now = {}`."""
+    try:
+        params = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError):
+        return None
+    if not bound:
+        params = params[1:]                 # self
+    positional = [p for p in params if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+    required = [p for p in positional if p.default is p.empty]
+    if len(required) > 1 or any(p.kind == p.KEYWORD_ONLY and p.default is p.empty for p in params):
+        return None
+    return len(required) == 1
+
+
+def _coerced(p: Parameter[Any], v: Any) -> Any:
+    """What the caller sent, as the parameter's type. A command line sends
+    every value as a string, so an integer or a number given as one is
+    taken - and only those: a string is never read as a bool or a list."""
+    if p.coerce is not None:
+        return p.coerce(v)
+    if isinstance(v, bool):
+        return v
+    if p.type is int and isinstance(v, (str, float)):
+        if isinstance(v, float) and not v.is_integer():
+            raise ValueError('not a whole number')
+        return int(v)
+    if p.type is float and isinstance(v, (str, int)):
+        return float(v)
+    if p.type is tuple and isinstance(v, list):
+        return tuple(v)
+    return v
+
+
+def _must(p: Parameter[Any], e: Optional[BaseException] = None) -> str:
+    if p.must:
+        return 'must ' + p.must
+    what = getattr(p.type, '__name__', str(p.type))
+    return 'must be %s%s' % ('one of %s' % ', '.join(map(str, p.choices)) if p.choices else 'a ' + what,
+                             ' (%s)' % e if e is not None else '')
+
+
+def declared(obj: Any) -> tuple[Command, ...]:
+    """The commands a compartment declares, or () for one not yet converted."""
+    return tuple(getattr(obj, 'COMMANDS', ()) or ())
+
+
+def every_command(compartments: Sequence[Any]) -> list[CommandRecord]:
+    """Every declared command across compartments."""
+    out: list[CommandRecord] = []
+    for c in compartments:
+        c_name = getattr(c, 'name', '') or getattr(c, 'key', '') or getattr(c, '__name__', str(c))
+        for cmd in declared(c):
+            row = cmd.describe()
+            row['compartment'] = c_name
+            out.append(row)
+    return out

node/compartment/context.py

@@ -0,0 +1,163 @@
+"""The shared surface a compartment is built from.
+
+Every compartment used to be constructed by hand in node/app/core.py from
+whichever of the node's stores and services it happened to need, in one of
+six different signature styles, with `node=self` passed alongside so the
+compartment could reach anything the signature forgot. `NodeContext` is the
+one typed object that replaces that: the stores, the transport, the face, the
+clock, the config, and the handful of node-level callables a compartment
+still has to reach. A compartment's `from_context(ctx)` says, in one place,
+what it takes from the node, and a third party writing a compartment against
+`subsystem/1` has a stable thing to write against.
+
+`node` stays on the context as a labelled escape hatch, not a hidden one:
+`scheduler` calls `node.propose`/`node.pull` and `trust` calls
+`node.regrant`, which are NodeApp methods and not stores. Anything reaching
+for `ctx.node` beyond those is a dependency that should be named here instead.
+
+Standard library only.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, NamedTuple, Optional, Sequence, TypeVar
+
+from ..channels import NodeEventBus
+from ..interfaces import NostrEvent
+from ..config.base import Block
+from ..config.node import NodeConfigDict
+
+
+class NodeStores(NamedTuple):
+    """The four durable stores a node keeps, as one argument."""
+    events: Any       # eventstore.NodeStore
+    grants: Any       # grants.GrantStore
+    accounts: Any     # accounts.AccountStore
+    blobs: Any        # blobstore.BlobStore
+
+
+def _no_descriptor() -> Optional[NostrEvent]:
+    return None
+
+
+B = TypeVar('B', bound=Block)
+
+
+@dataclass
+class NodeContext:
+    """Explicit, typed context handed to every compartment at assembly.
+
+    `cfg` is the live config dict the node mutates on reload; a compartment
+    that must see changes reads through `cfg_of(key)` on each tick rather than
+    copying a section at construction. `descriptor` is a getter because the
+    descriptor is mined or loaded in start() and does not exist at the time
+    the context is made.
+    """
+    dir: str
+    ks: Any                                   # keystore.Keystore
+    cfg: NodeConfigDict
+    clock: Callable[[], int]
+    events: NodeEventBus
+    stores: NodeStores
+    relays: list[str]
+    transport: Optional[Any] = None           # transport.TransportRouter
+    router: Optional[Any] = None              # router.ProtocolRouter
+    face: Optional[Any] = None                # relayserver.RelayServer
+    host: Optional[Any] = None                # transport.host.ProtocolHostRouter
+    peers: Optional[Any] = None               # peers.Peers
+    policy: Optional[Any] = None              # fleetmesh_core.peering.Policy
+    ledger: Optional[Any] = None              # fleetmesh_core.accounting.standing.Ledger
+    timeout: float = 15.0
+    stop: threading.Event = field(default_factory=threading.Event)
+    descriptor: Callable[[], Optional[NostrEvent]] = _no_descriptor
+    digest: Optional[str] = None              # schema digest this node speaks
+    node: Optional[Any] = None                # the NodeApp; see module docstring
+    says: Optional[Any] = None                # node log / channels router
+    # Write `cfg` back to the node directory. A compartment that changes
+    # what this node claims (coverage, a price) calls this rather than
+    # importing the app's config writer - the node owns its directory and
+    # the file is what the next tick reads. No-op outside a running node.
+    persist_cfg: Callable[[], None] = lambda: None
+    # Rebuild and republish the descriptor from what the compartments say
+    # now. For a compartment whose declaration can change after start (a
+    # sidecar whose self-tests begin or stop passing). No-op outside a
+    # running node, where there is no descriptor to correct.
+    redescribe: Callable[[], Any] = lambda: None
+    # Node-internal methods reached by compartments:
+    regrant: Callable[..., Any] = lambda *a, **kw: None
+    propose: Callable[..., Any] = lambda *a, **kw: ('declined', None)
+    pull: Callable[..., Any] = lambda *a, **kw: {}
+    amend: Callable[..., Any] = lambda *a, **kw: (None, None)
+    build_descriptor: Callable[[], Any] = lambda: None
+
+    @property
+    def _amend(self) -> Callable[..., Any]:
+        return self.amend
+
+    # ---- derived -------------------------------------------------------------
+    @property
+    def pubkey(self) -> str:
+        return getattr(self.ks, 'node_pk', '')
+
+    @property
+    def did(self) -> str:
+        return getattr(self.ks, 'did', '')
+
+    @property
+    def node_class(self) -> str:
+        return str(self.cfg.get('class', 'edge'))
+
+    def cfg_of(self, key: str, default: Any = None) -> Any:
+        """A top-level config key as it is *now*, for compartments that read
+        live. The same contract `Compartment.config()` keeps."""
+        return self.cfg.get(key, default)
+
+    def cfg_getter(self) -> Callable[[], Mapping[str, Any]]:
+        """The `lambda: self.cfg` several compartments take, named."""
+        return lambda: self.cfg
+
+    def block(self, block_cls: type[B]) -> B:
+        """A compartment's config section as its typed block, *now*.
+
+        `block_cls.key` names the section; an absent section is the default
+        block. The file was checked at the door (load_config) and on every
+        reload, so from_dict here cannot meet a shape it refuses - a block
+        that reads live calls this each tick and gets the current values.
+        """
+        raw = self.cfg.get(block_cls.key)
+        return block_cls.from_dict({} if raw is None else raw)
+
+    def block_getter(self, block_cls: type[B]) -> Callable[[], B]:
+        """`lambda: ctx.block(cls)`, for a compartment that reads live."""
+        return lambda: self.block(block_cls)
+
+    def path(self, *parts: str) -> str:
+        return os.path.join(self.dir, *parts)
+
+    def optional(self, name: str) -> Optional[Any]:
+        """A compartment named in the caller's `uses`, if the node built it;
+        None when it is off. Resolved once at construction: the manifest
+        orders `uses` before the user, so a present one is already built.
+        Tests that assemble without a node fall back to the attribute set on
+        `node` by assemble(), which is the same object either way."""
+        reg = getattr(self, '_registry', None)
+        if reg is not None:
+            res = reg.get(name)
+            if res is not None:
+                return res
+        registry = getattr(self.node, 'subsystems', None) if self.node is not None else None
+        if registry is not None:
+            res = registry.get(name)
+            if res is not None:
+                return res
+        return getattr(self.node, name, None) if self.node is not None else None
+
+    # ---- the previous keyword-style constructor, kept for callers ------------
+    @classmethod
+    def build(cls, directory: str, ks: Any, cfg: NodeConfigDict, clock: Callable[[], int],
+              events: NodeEventBus, stores: NodeStores, relays: Sequence[str],
+              transport: Optional[Any] = None, router: Optional[Any] = None, **more: Any) -> NodeContext:
+        return cls(dir=directory, ks=ks, cfg=cfg, clock=clock, events=events, stores=stores,
+                   relays=list(relays), transport=transport, router=router, **more)