fleetmesh-node 0.2.0__py3-none-any.whl

node/compartment/wire.py

@@ -0,0 +1,225 @@
+"""WireProtocol: base class for compartments that speak a wire protocol.
+
+A compartment that speaks one or more PIURIs declares what it handles
+(HANDLERS) and what it emits (OUTBOUND).
+The base class verifies the declarations at class definition time and
+binds a WireClient (`self.wire`) to manage outbound sends, requests, replies,
+and correlation.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Optional
+
+from fleetmesh_core.wire import schema_files
+
+from .base import Compartment
+from .handler import Handler
+from .problem import Problem, Problems, TypeMismatchProblem
+
+
+class Outbound:
+    """An outbound message kind declared by a WireProtocol.
+
+    States what message kind this compartment emits over the wire, what
+    reply kinds it expects in return (if an RPC request), and what documentation
+    explains its role.
+    """
+
+    def __init__(
+        self,
+        kind: str,
+        reply: Optional[str | tuple[str, ...]] = None,
+        reads: tuple[str, ...] = (),
+        writes: tuple[str, ...] = (),
+        doc: str = '',
+    ) -> None:
+        self.kind: str = str(kind)
+        if isinstance(reply, str):
+            self.reply: tuple[str, ...] = (reply,)
+        elif reply is None:
+            self.reply = ()
+        else:
+            self.reply = tuple(reply)
+        self.reads: tuple[str, ...] = tuple(reads)
+        self.writes: tuple[str, ...] = tuple(writes)
+        self.doc: str = str(doc)
+
+    def __repr__(self) -> str:
+        rep = f", reply={self.reply!r}" if self.reply else ""
+        return f"Outbound({self.kind!r}{rep})"
+
+
+class WireClient:
+    """The client adapter bound to self.wire on a WireProtocol compartment."""
+
+    def __init__(self, protocol: WireProtocol) -> None:
+        self._protocol: WireProtocol = protocol
+
+    @property
+    def transport(self) -> Any:
+        return getattr(self._protocol, 'transport', None)
+
+    def kind_of(self, message: Mapping[str, Any]) -> Optional[str]:
+        """Extract the message kind relative to this protocol's declared PIURIs."""
+        t = str(message.get('type', ''))
+        for piuri in self._protocol.piuris:
+            if t.startswith(piuri + '/'):
+                return t[len(piuri) + 1:]
+        return None
+
+    def send(
+        self,
+        to_pubkey: str,
+        message: Mapping[str, Any],
+        *,
+        anonymous: bool = False,
+        stored: bool = False,
+    ) -> Any:
+        """Dispatch one message to to_pubkey over the transport ladder."""
+        tr = self.transport
+        if tr is None:
+            raise RuntimeError(f"{self._protocol.name}: no transport to send {message.get('type')}")
+        try:
+            return tr.send(message, to_pubkey, anonymous=anonymous, stored=stored)
+        except TypeError:
+            try:
+                return tr.send(message, to_pubkey, stored=stored)
+            except TypeError:
+                return tr.send(message, to_pubkey)
+
+    def request(
+        self,
+        to_pubkey: str,
+        message: Mapping[str, Any],
+        *,
+        timeout: float = 30.0,
+        anonymous: bool = False,
+    ) -> Optional[Any]:
+        """Dispatch a request message and await a correlated reply."""
+        tr = self.transport
+        if tr is None:
+            raise RuntimeError(f"{self._protocol.name}: no transport to request {message.get('type')}")
+        try:
+            return tr.request(message, to_pubkey, timeout=timeout, anonymous=anonymous)
+        except TypeError:
+            try:
+                return tr.request(message, to_pubkey, timeout=timeout)
+            except TypeError:
+                return tr.request(message, to_pubkey)
+
+    def reply(
+        self,
+        inbound: Any,
+        message: Any,
+        *,
+        sender: Optional[str] = None,
+        anonymous: bool = False,
+    ) -> Any:
+        """Reply in-band to an inbound message, carrying forward its thread id."""
+        m = getattr(inbound, 'message', inbound)
+        to_peer = sender or getattr(inbound, 'sender', None)
+        if to_peer is None and isinstance(m, dict):
+            to_peer = m.get('from')
+        if to_peer is None:
+            raise ValueError(f"{self._protocol.name}: cannot reply to inbound without sender")
+        thid = m.get('thid') or m.get('id') if isinstance(m, dict) else None
+        if thid:
+            message['thid'] = thid
+        return self.send(str(to_peer), message, anonymous=anonymous)
+
+
+class WireProtocol(Compartment, abstract=True):
+    """A compartment that speaks one or more DIDComm wire protocols (PIURIs)."""
+
+    piuris: tuple[str, ...] = ()
+    HANDLERS: tuple[Handler, ...] = ()
+    OUTBOUND: tuple[Outbound, ...] = ()
+
+    @classmethod
+    def declaration_problems(cls) -> list[str]:
+        out = Problems(super().declaration_problems())
+        if cls.abstract:
+            return out
+
+        # 1. piuris validation
+        piuris = getattr(cls, 'piuris', ())
+        if not piuris:
+            out.append(Problem(
+                f"{cls.__name__} must declare non-empty piuris",
+                surface='PIURIS',
+                code='missing_piuris',
+                target='piuris',
+            ))
+        else:
+            for p in piuris:
+                if not isinstance(p, str) or not p.startswith('https://'):
+                    out.append(Problem(
+                        f"piuri {p!r} must be an https:// URI",
+                        surface='PIURIS',
+                        code='invalid_piuri',
+                        target='piuris',
+                    ))
+
+        # 2. HANDLERS validation
+        handlers = getattr(cls, 'HANDLERS', ())
+        if not handlers:
+            out.append(Problem(
+                f"{cls.__name__} must declare HANDLERS",
+                surface='HANDLERS',
+                code='missing_handlers',
+                target='HANDLERS',
+            ))
+        else:
+            for h in handlers:
+                if not isinstance(h, Handler):
+                    out.append(TypeMismatchProblem('HANDLERS', 'Handler', type(h).__name__))
+
+        # 3. OUTBOUND validation
+        outbound = getattr(cls, 'OUTBOUND', ())
+        for ob in outbound:
+            if not isinstance(ob, Outbound):
+                out.append(TypeMismatchProblem('OUTBOUND', 'Outbound', type(ob).__name__))
+
+        # 4. Schema conformance check against schema/messages.json
+        try:
+            schema_protocols = schema_files.load_messages().get('protocols', {})
+        except Exception:
+            schema_protocols = {}
+
+        known_protocols = [p for p in piuris if p in schema_protocols]
+        if known_protocols:
+            allowed_msgs = set()
+            for p in known_protocols:
+                allowed_msgs.update(schema_protocols[p].get('messages', []))
+
+            for h in handlers:
+                if isinstance(h, Handler) and not getattr(h, 'exact', False) and h.kind != '*':
+                    if h.kind not in allowed_msgs:
+                        out.append(Problem(
+                            f"handler {h.kind!r} is not declared in schema for {known_protocols}",
+                            surface='HANDLERS',
+                            code='schema_mismatch',
+                            target=h.kind,
+                        ))
+            for ob in outbound:
+                if isinstance(ob, Outbound) and ob.kind not in allowed_msgs:
+                    out.append(Problem(
+                        f"outbound message {ob.kind!r} is not declared in schema for {known_protocols}",
+                        surface='OUTBOUND',
+                        code='schema_mismatch',
+                        target=ob.kind,
+                    ))
+
+        return out
+
+    def __init__(
+        self,
+        node: Any = None,
+        clock: Optional[Callable[[], int]] = None,
+        cfg: Optional[Any] = None,
+        says: Optional[Any] = None,
+        db: Optional[Any] = None,
+        **kw: Any,
+    ) -> None:
+        super().__init__(node=node, clock=clock, cfg=cfg, says=says, db=db, **kw)
+        self.wire_client: WireClient = WireClient(self)

node/compartment/worker.py

@@ -0,0 +1,61 @@
+"""WORKERS: background worker threads declared on a compartment."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Union
+
+from .problem import Problem, Problems, ReferenceProblem, TypeMismatchProblem
+
+WhenType = Optional[Union[str, Callable[[Any], bool]]]
+
+
+@dataclass(frozen=True)
+class Worker:
+    """A background worker thread declared on a compartment class.
+
+    The base Compartment starts declared workers during `start()` and
+    signals them to stop and joins them during `stop()`.
+
+    Attributes:
+        run: The method name on the compartment to run in a thread.
+        name: A unique name for the worker/thread (defaults to `run`).
+        timeout: How long in seconds to wait for the thread to join on stop().
+        daemon: Whether the thread is a daemon thread (defaults to True).
+        when: Optional condition to run: attribute name (checked for truthiness)
+              or callable receiving the compartment instance.
+    """
+    run: str
+    name: str = ''
+    timeout: float = 1.0
+    daemon: bool = True
+    when: WhenType = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            object.__setattr__(self, 'name', self.run)
+
+    def should_run(self, instance: Any) -> bool:
+        """True if any `when` condition holds."""
+        if self.when is None:
+            return True
+        if callable(self.when):
+            return bool(self.when(instance))
+        val = getattr(instance, self.when, None)
+        if callable(val):
+            return bool(val())
+        return bool(val)
+
+    def problems(self, cls: type[Any]) -> list[str]:
+        """Lint this declaration against the target class."""
+        out = Problems()
+        if not isinstance(self.run, str) or not self.run:
+            out.append(TypeMismatchProblem('WORKERS', 'non-empty str', type(self.run).__name__,
+                                           message=f"Worker {self.name!r}: run must be a non-empty string method name"))
+        elif not getattr(cls, 'abstract', False) and not hasattr(cls, self.run):
+            out.append(ReferenceProblem('WORKERS', f"Worker {self.name!r}", self.run,
+                                        message=f"Worker {self.name!r}: method {self.run!r} does not exist on {cls.__name__}"))
+        if self.timeout < 0:
+            out.append(Problem(f"Worker {self.name!r}: timeout must be non-negative, got {self.timeout!r}",
+                               surface='WORKERS', code='negative_timeout', target=self.name))
+        return out
+

node/config/__init__.py

@@ -0,0 +1,43 @@
+"""The node's configuration as typed, frozen dataclasses.
+
+    base          Block, Problems, ConfigError, the predicates
+    records       Endpoint, PeerPull, CoverageClaim, TrustDecision, FaceConfig, PolicyConfig
+    compartments  one block per compartment (BridgeConfig, DVMConfig, ...)
+    node          NodeConfig: the whole file
+
+node.app.config keeps the file I/O and the dict the compartments still read;
+its DEFAULTS and validate_config are derived from here.
+"""
+from .base import Block, ConfigError, Problems
+from .compartments import (AnnounceConfig, BlobReplicationConfig, BlobWireConfig, BlobsConfig, BridgeConfig,
+                           BridgeEgress, BridgeIngress, COMPARTMENT_BLOCKS, CapacityConfig, STRFRY_MOVED, STRFRY_PLUGIN_REF,
+                           CashuRail, ComputeConfig, DEFAULT_DVM_KINDS, DEFAULT_EGRESS_KINDS,
+                           DEFAULT_INGRESS_FILTERS, DEFAULT_INGRESS_KINDS, DEFAULT_MAX_EVENT_BYTES,
+                           DEFAULT_MAX_FUTURE_SECONDS, DEFAULT_RATE_LIMIT_PER_MIN, DVMConfig, NsiteConfig,
+                           FetchPricingConfig, LanConfig, MediationConfig, PluginSpec, PluginsConfig, SidecarsConfig, SidecarEntry, SIDECAR_KEYS_MOVED, SIDECAR_MOVED, sidecars_of,
+                           P2PConfig, PRICING_RULE_KEYS, PROJECT_RELEASE_KEY, PricingRule, default_release_key, SettlementConfig,
+                           StorageConfig, TRACK_NOT_YET, TransportConfig, UPDATE_POLICIES, UpdatesConfig)
+from .node import DEFAULT_CAPABILITIES, DEFAULT_PROTOCOLS, NodeConfig
+from .records import (CLASSES, COMPLETENESS, CoverageClaim, Endpoint, FaceConfig, HANDOVER, PeerPull,
+                      PolicyConfig, TIERS, TrustDecision)
+
+# A literal list, not built from splats: pyflakes reads __all__ statically and
+# only a literal tells it these re-exports are used.
+__all__ = [
+    # base
+    'Block', 'ConfigError', 'Problems',
+    # node
+    'NodeConfig', 'DEFAULT_CAPABILITIES', 'DEFAULT_PROTOCOLS',
+    # compartments
+    'AnnounceConfig', 'BlobReplicationConfig', 'BlobWireConfig', 'BlobsConfig', 'BridgeConfig', 'BridgeEgress',
+    'BridgeIngress', 'COMPARTMENT_BLOCKS', 'STRFRY_MOVED', 'STRFRY_PLUGIN_REF', 'CapacityConfig', 'CashuRail', 'ComputeConfig',
+    'DEFAULT_DVM_KINDS', 'DEFAULT_EGRESS_KINDS', 'DEFAULT_INGRESS_FILTERS', 'DEFAULT_INGRESS_KINDS',
+    'DEFAULT_MAX_EVENT_BYTES', 'DEFAULT_MAX_FUTURE_SECONDS', 'DEFAULT_RATE_LIMIT_PER_MIN', 'DVMConfig', 'NsiteConfig',
+    'FetchPricingConfig', 'LanConfig', 'MediationConfig', 'SidecarsConfig', 'SidecarEntry', 'SIDECAR_KEYS_MOVED', 'SIDECAR_MOVED', 'sidecars_of',
+    'P2PConfig', 'PluginSpec', 'PluginsConfig', 'PRICING_RULE_KEYS', 'PricingRule',
+    'SettlementConfig', 'StorageConfig', 'TransportConfig', 'UpdatesConfig', 'PROJECT_RELEASE_KEY',
+    'default_release_key', 'UPDATE_POLICIES', 'TRACK_NOT_YET',
+    # records
+    'CLASSES', 'COMPLETENESS', 'CoverageClaim', 'Endpoint', 'FaceConfig', 'HANDOVER', 'PeerPull', 'PolicyConfig',
+    'TIERS', 'TrustDecision',
+]

node/config/base.py

@@ -0,0 +1,116 @@
+"""The pieces every config block is built from.
+
+A block is a frozen dataclass with a `from_dict` that reads the operator's
+JSON and a `check` that names every problem in it. Problems are collected,
+not raised one at a time: an operator fixes a file once, not one line per
+restart. The messages are the interface the tests and the operator read, so
+they say which field and what it must be.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any, Callable, ClassVar, Mapping, Optional, TypeVar
+
+from fleetmesh_core.wire import spelling
+
+T = TypeVar('T', bound='Block')
+
+
+class ConfigError(ValueError):
+    """config.json says something the node cannot run on. The message lists
+    every problem, because an operator fixes a file once, not one line per
+    restart."""
+
+
+class Problems:
+    """Sentences about what is wrong, in file order."""
+
+    def __init__(self) -> None:
+        self.items: list[str] = []
+
+    def add(self, sentence: str) -> None:
+        self.items.append(sentence)
+
+    def __bool__(self) -> bool:
+        return bool(self.items)
+
+    def __iter__(self):
+        return iter(self.items)
+
+
+def is_hex64(v: Any) -> bool:
+    return spelling.is_hex(v, 64)
+
+
+def is_int(v: Any) -> bool:
+    return spelling.is_int(v)
+
+
+def is_relay_url(v: Any) -> bool:
+    return isinstance(v, str) and v.startswith(('ws://', 'wss://'))
+
+
+def is_http_url(v: Any) -> bool:
+    return isinstance(v, str) and v.startswith(('http://', 'https://'))
+
+
+def all_str(v: Any) -> bool:
+    return isinstance(v, list) and all(isinstance(x, str) for x in v)
+
+
+def all_int(v: Any) -> bool:
+    return isinstance(v, list) and all(is_int(x) for x in v)
+
+
+def opt(raw: Mapping[str, Any], key: str, pred: Callable[[Any], bool], p: Problems, must: str) -> None:
+    """When `key` is present, it has to satisfy `pred`; otherwise say `must`."""
+    if key in raw and not pred(raw[key]):
+        p.add(must)
+
+
+def positive_int(v: Any) -> bool:
+    return is_int(v) and v > 0
+
+
+def non_negative_int(v: Any) -> bool:
+    return is_int(v) and v >= 0
+
+
+@dataclasses.dataclass(frozen=True)
+class Block:
+    """A typed section of config.json.
+
+    `check(raw, p)` names what is wrong with the raw object; `from_dict(raw)`
+    builds the block from a raw object that `check` passed. Subclasses write
+    both: the first is the sentence an operator reads, the second the shape
+    the compartment reads. `key` is the top-level name the block lives under,
+    `label` the prefix its sentences use (defaults to the key).
+    """
+    key: ClassVar[str] = ''
+    label: ClassVar[str] = ''
+
+    @classmethod
+    def check(cls, raw: Any, p: Problems) -> None:
+        if not isinstance(raw, Mapping):
+            p.add('%s must be an object' % (cls.label or cls.key))
+
+    @classmethod
+    def from_dict(cls: type[T], raw: Any) -> T:
+        raise NotImplementedError
+
+    @classmethod
+    def parse(cls: type[T], raw: Any) -> T:
+        """check then from_dict, raising ConfigError with every sentence."""
+        p = Problems()
+        cls.check(raw, p)
+        if p:
+            raise ConfigError('; '.join(p))
+        return cls.from_dict(raw)
+
+    def to_dict(self) -> Mapping[str, Any]:
+        """The JSON shape, tuples made lists, as the file would carry it."""
+        return json.loads(json.dumps(dataclasses.asdict(self)))
+
+__all__ = ['Block', 'ConfigError', 'Problems', 'is_hex64', 'is_int', 'is_relay_url', 'is_http_url', 'all_str',
+           'all_int', 'opt', 'positive_int', 'non_negative_int', 'Optional']