fleetmesh-node 0.2.0__py3-none-any.whl

node/compartment/every.py

@@ -0,0 +1,108 @@
+"""EVERY: periodic work declared on a compartment."""
+from __future__ import annotations
+
+import inspect
+import math
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Union
+
+from .problem import Problem, Problems, ReferenceProblem, TypeMismatchProblem
+
+SecondsType = Union[int, float, Callable[[Any], Union[int, float]], Any]
+ReportType = Optional[Union[str, Callable[..., Any]]]
+
+
+@dataclass(frozen=True)
+class Every:
+    """A periodic job declared on a compartment class.
+
+    Attributes:
+        seconds: How often to run the job, in seconds. Can be an int, float,
+                 a callable receiving the compartment instance, or a Parameter.
+                 A callable that resolves to zero or less turns the job off
+                 (see `is_off`): that is how a setting like `check_every: 0`
+                 says "only on command".
+        run: The method name on the compartment to call when due.
+        name: A unique name for the job within the compartment (defaults to `run`).
+        report: Optional method name or callable to convert the method's return value
+                into a list of `[(what, ...)]` tuples for the tick log.
+    """
+    seconds: SecondsType
+    run: str
+    name: str = ''
+    report: ReportType = None
+    # Whether `run` takes `now`, per class. inspect.signature ran for every
+    # due job on every tick (audit 2026-10-15, E6); a method's arity does not
+    # change between ticks.
+    _takes_now: dict = field(default_factory=dict, init=False, repr=False, compare=False, hash=False)
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            object.__setattr__(self, 'name', self.run)
+
+    def get_seconds(self, instance: Any) -> float:
+        """Resolve the interval in seconds against a compartment instance."""
+        sec = self.seconds
+        if callable(sec):
+            return float(sec(instance))
+        if hasattr(sec, 'value') and callable(sec.value):
+            return float(sec.value())
+        if hasattr(sec, 'default'):
+            def_val = sec.default() if callable(sec.default) else sec.default
+            return float(def_val)
+        return float(sec)
+
+    def is_off(self, instance: Any) -> bool:
+        """Whether the interval says this job does not run on a schedule.
+
+        Zero, a negative number, or anything not finite. Updates used to spell
+        "off" as infinity, and `report()` died on `int(inf)` - which took the
+        whole health report with it, every tick (audit 2026-10-15, B1). Off is
+        now one rule, read here, and never a number anyone does arithmetic on.
+        """
+        sec = self.get_seconds(instance)
+        return not math.isfinite(sec) or sec <= 0
+
+    def due(self, instance: Any, now: int) -> bool:
+        """True if this job has never run or if at least `seconds` have passed since last run.
+        Never true for a job that is off, including on its first tick."""
+        if self.is_off(instance):
+            return False
+        every_last = getattr(instance, '_every_last', None)
+        if every_last is None:
+            return True
+        last = every_last.get(self.name)
+        if last is None:
+            return True
+        return (now - last) >= self.get_seconds(instance)
+
+    def execute(self, instance: Any, now: int) -> Any:
+        """Call the target method on instance, passing `now` if accepted."""
+        method = getattr(instance, self.run, None)
+        if method is None:
+            raise AttributeError(f"{type(instance).__name__} has no method {self.run!r}")
+        cls = type(instance)
+        takes = self._takes_now.get(cls)
+        if takes is None:
+            takes = self._takes_now[cls] = len(inspect.signature(method).parameters) > 0
+        if takes:
+            return method(now)
+        return method()
+
+    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('EVERY', 'non-empty str', type(self.run).__name__,
+                                           message=f"Every job {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('EVERY', f"Every job {self.name!r}", self.run,
+                                        message=f"Every job {self.name!r}: method {self.run!r} does not exist on {cls.__name__}"))
+        if isinstance(self.report, str) and not getattr(cls, 'abstract', False) and not hasattr(cls, self.report):
+            out.append(ReferenceProblem('EVERY', f"Every job {self.name!r}", self.report,
+                                        message=f"Every job {self.name!r}: report method {self.report!r} does not exist on {cls.__name__}"))
+        if isinstance(self.seconds, (int, float)) and self.seconds <= 0:
+            out.append(Problem(f"Every job {self.name!r}: seconds must be positive, got {self.seconds!r}",
+                               surface='EVERY', code='invalid_interval', target=self.name))
+        return out
+

node/compartment/handler.py

@@ -0,0 +1,131 @@
+"""HANDLERS: what a compartment can receive from the wire, declared where it is.
+
+A wire compartment declares its message dispatch table as a tuple of typed
+Handler entries on the class attribute HANDLERS. Like COMMANDS, WORKERS, and
+CHANNELS, it is declared once, validated at class definition time by the base
+Compartment, and dispatched uniformly by the base `handle(inbound)`.
+"""
+from __future__ import annotations
+
+import dataclasses
+import inspect
+from typing import Any, Callable, Optional, Sequence
+
+from .problem import (
+    InvalidIdentifierProblem,
+    Problem,
+    Problems,
+    ReferenceProblem,
+    TypeMismatchProblem,
+)
+
+
+
+@dataclasses.dataclass(frozen=True)
+class Handler:
+    """One inbound wire protocol message handler."""
+
+    kind: str
+    run: str
+    schema: Optional[Any] = None
+    doc: str = ''
+    exact: bool = False
+    reads: tuple[str, ...] = ()
+    writes: tuple[str, ...] = ()
+
+    def __init__(
+        self,
+        kind: str,
+        run: str | Callable[..., Any],
+        *,
+        schema: Optional[Any] = None,
+        doc: str = '',
+        exact: bool = False,
+        reads: Sequence[str] = (),
+        writes: Sequence[str] = (),
+    ) -> None:
+        object.__setattr__(self, 'kind', str(kind))
+        run_name = run if isinstance(run, str) else getattr(run, '__name__', str(run))
+        object.__setattr__(self, 'run', run_name)
+        object.__setattr__(self, 'schema', schema)
+        object.__setattr__(self, 'doc', str(doc))
+        is_exact = exact or (kind.startswith(('http://', 'https://')) and not exact)
+        object.__setattr__(self, 'exact', bool(is_exact))
+        object.__setattr__(self, 'reads', tuple(reads))
+        object.__setattr__(self, 'writes', tuple(writes))
+
+    def matches(self, msg_type: str, piuris: Sequence[str] = ()) -> bool:
+        """Check if this handler matches the given message type URI."""
+        if not msg_type:
+            return False
+        if self.kind == '*':
+            if not piuris:
+                return True
+            return any(msg_type.startswith(p + '/') for p in piuris)
+        if self.exact or self.kind.startswith(('http://', 'https://')):
+            return msg_type == self.kind
+        # Suffix / sub-path matching: https://fleetmesh.org/compute/1.0/quote
+        if msg_type.endswith('/' + self.kind):
+            if not piuris:
+                return True
+            prefix = msg_type.rsplit('/', 1)[0]
+            return any(prefix == p or prefix.startswith(p) for p in piuris)
+        return False
+
+    def problems(self, cls: type) -> list[str]:
+        """Validate this Handler against the declaring compartment class."""
+        out = Problems()
+        if not self.kind or not isinstance(self.kind, str):
+            out.append(InvalidIdentifierProblem('HANDLERS', str(self.kind), 'Handler must specify a message kind'))
+        if not self.run or not isinstance(self.run, str):
+            out.append(Problem(
+                f'Handler {self.kind} must specify a target run method',
+                surface='HANDLERS',
+                code='missing_run',
+                target=self.kind,
+            ))
+        else:
+            fn = getattr(cls, self.run, None)
+            if fn is None:
+                out.append(ReferenceProblem(
+                    'HANDLERS', f'{cls.__name__}.{self.run}', self.run,
+                    f"handler {self.kind!r}: method {self.run!r} does not exist on {cls.__name__}"
+                ))
+            elif not callable(fn):
+                out.append(TypeMismatchProblem(
+                    'HANDLERS', 'callable', type(fn).__name__,
+                    f"handler {self.kind!r}: attribute {self.run!r} on {cls.__name__} is not callable"
+                ))
+        return out
+
+    def execute(self, instance: Any, inbound: Any, *args: Any, **kw: Any) -> Any:
+        """Dispatch an inbound message to this handler on the compartment instance."""
+        fn = getattr(instance, self.run)
+        sig = inspect.signature(fn)
+        num_params = len(sig.parameters)
+        msg = getattr(inbound, 'message', inbound)
+        sender = getattr(inbound, 'sender', msg.get('from', '') if isinstance(msg, dict) else '')
+
+        # Validate against schema if declared
+        if self.schema is not None and isinstance(msg, dict):
+            body = msg.get('body')
+            if callable(self.schema):
+                try:
+                    self.schema(body)
+                except Exception as e:
+                    return ('refused', sender, f'invalid schema: {e}')
+
+        available = (inbound, sender) + args
+        if num_params == 0:
+            return fn()
+        elif num_params == 1:
+            return fn(inbound)
+        elif num_params == 2:
+            return fn(inbound, sender)
+        elif num_params <= len(available):
+            return fn(*available[:num_params], **kw)
+        else:
+            return fn(inbound, sender)
+
+
+__all__ = ['Handler']