fleetmesh-node 0.2.0__py3-none-any.whl

node/compartment/problem.py

@@ -0,0 +1,521 @@
+"""Class-driven problem and runtime trouble definitions for compartments.
+
+Every compartment declares what it is (SCHEMA, COMMANDS, NEEDS, STORES,
+WORKERS, EVERY, CHANNELS, METRICS, LIFECYCLE). When a declaration is invalid,
+`declaration_problems` collects `Problem` instances rather than loose strings,
+carrying the surface, semantic code, target, and human-readable message.
+
+Similarly, when a compartment is in an abnormal state, `trouble()` returns
+`Trouble` instances carrying the fault code, severity, timestamp, and optional
+remediation hint.
+
+Both `Problem` and `Trouble` inherit from `str` so that:
+  - String formatting (`str(p)`, `f"{p}"`) produces the sentence directly.
+  - Substring checks (`'twice' in p`, `'relay' in t`) continue to pass.
+  - List comparisons (`[p] == ['message']`) evaluate True against raw strings.
+  - Existing callers, tests, and json encoders require zero breaking changes.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, TypeVar, TypedDict
+
+P = TypeVar('P', bound='Problem')
+T_tr = TypeVar('T_tr', bound='Trouble')
+
+
+class ProblemDict(TypedDict, total=False):
+    """Concrete dictionary structure for a declaration problem."""
+
+    message: str
+    surface: str
+    code: str
+    target: str
+    hint: Optional[str]
+    reference: str
+    expected: str
+    got: str
+    owner: str
+
+
+class Problem(str):
+    """A structured declaration problem.
+
+    Subclasses str for complete backwards compatibility with tests and callers
+    expecting str messages, while exposing structured metadata for linters,
+    checkers, and IDE diagnostics.
+    """
+
+    surface: str
+    code: str
+    target: str
+    message: str
+    hint: Optional[str]
+
+    def __new__(
+        cls: type[P],
+        message: str,
+        *,
+        surface: str = '',
+        code: str = '',
+        target: str = '',
+        hint: Optional[str] = None,
+    ) -> P:
+        obj = super().__new__(cls, message)
+        obj.surface = str(surface)
+        obj.code = str(code)
+        obj.target = str(target)
+        obj.message = str(message)
+        obj.hint = hint
+        return obj
+
+    def to_dict(self) -> ProblemDict:
+        """Dictionary representation for structured reporting."""
+        d: ProblemDict = {
+            'message': self.message,
+            'surface': self.surface,
+            'code': self.code,
+        }
+        if self.target:
+            d['target'] = self.target
+        if self.hint is not None:
+            d['hint'] = self.hint
+        return d
+
+
+class DuplicateProblem(Problem):
+    """An item was declared twice on the same surface."""
+
+    def __new__(
+        cls,
+        surface: str,
+        target: str,
+        message: Optional[str] = None,
+        hint: Optional[str] = None,
+    ) -> DuplicateProblem:
+        msg = message if message is not None else f"{surface} declares {target!r} twice"
+        return super().__new__(
+            cls,
+            msg,
+            surface=surface,
+            code='duplicate',
+            target=target,
+            hint=hint or 'remove or rename the duplicate declaration',
+        )
+
+
+class InvalidIdentifierProblem(Problem):
+    """An identifier name does not follow the required naming pattern."""
+
+    def __new__(
+        cls,
+        surface: str,
+        target: str,
+        message: Optional[str] = None,
+        hint: Optional[str] = None,
+    ) -> InvalidIdentifierProblem:
+        msg = message if message is not None else f"{surface} identifier {target!r} is not a valid identifier"
+        return super().__new__(
+            cls,
+            msg,
+            surface=surface,
+            code='invalid_identifier',
+            target=target,
+            hint=hint or 'identifiers must start with a letter/underscore and contain only alphanumeric characters',
+        )
+
+
+class ReferenceProblem(Problem):
+    """A declaration references an entity that is unknown or missing."""
+
+    reference: str
+
+    def __new__(
+        cls,
+        surface: str,
+        target: str,
+        reference: str,
+        message: Optional[str] = None,
+        hint: Optional[str] = None,
+    ) -> ReferenceProblem:
+        msg = message if message is not None else f"{surface} {target} references unknown {reference!r}"
+        obj = super().__new__(
+            cls,
+            msg,
+            surface=surface,
+            code='unknown_reference',
+            target=target,
+            hint=hint,
+        )
+        obj.reference = str(reference)
+        return obj
+
+    def to_dict(self) -> ProblemDict:
+        d = super().to_dict()
+        d['reference'] = self.reference
+        return d
+
+
+class TypeMismatchProblem(Problem):
+    """A declaration entry has the wrong type or does not implement the expected class."""
+
+    expected: str
+    got: str
+
+    def __new__(
+        cls,
+        surface: str,
+        expected: str,
+        got: str,
+        message: Optional[str] = None,
+        hint: Optional[str] = None,
+    ) -> TypeMismatchProblem:
+        msg = message if message is not None else f"{surface} holds {expected}, not {got}"
+        obj = super().__new__(
+            cls,
+            msg,
+            surface=surface,
+            code='type_mismatch',
+            target=got,
+            hint=hint or f"use instances of {expected}",
+        )
+        obj.expected = str(expected)
+        obj.got = str(got)
+        return obj
+
+    def to_dict(self) -> ProblemDict:
+        d = super().to_dict()
+        d['expected'] = self.expected
+        d['got'] = self.got
+        return d
+
+
+class ShadowingProblem(Problem):
+    """A declared key would shadow a method or class attribute."""
+
+    owner: str
+
+    def __new__(
+        cls,
+        surface: str,
+        target: str,
+        owner: str,
+        message: Optional[str] = None,
+        hint: Optional[str] = None,
+    ) -> ShadowingProblem:
+        msg = message if message is not None else f"{surface} {target} would shadow {owner}.{target}; pick another key"
+        obj = super().__new__(
+            cls,
+            msg,
+            surface=surface,
+            code='shadows_attribute',
+            target=target,
+            hint=hint or 'pick another key to avoid overwriting attributes',
+        )
+        obj.owner = str(owner)
+        return obj
+
+    def to_dict(self) -> ProblemDict:
+        d = super().to_dict()
+        d['owner'] = self.owner
+        return d
+
+
+class IncompatibleProblem(Problem):
+    """Two declarations or declarations and method implementations are incompatible."""
+
+    def __new__(
+        cls,
+        surface: str,
+        target: str,
+        message: str,
+        hint: Optional[str] = None,
+    ) -> IncompatibleProblem:
+        return super().__new__(
+            cls,
+            message,
+            surface=surface,
+            code='incompatible',
+            target=target,
+            hint=hint,
+        )
+
+
+class Problems(list[Any]):
+    """A list of Problem instances providing query methods and surface filtering."""
+
+    def for_surface(self, surface: str) -> list[Problem]:
+        """Return all problems recorded for a specific declaration surface."""
+        return [p for p in self if isinstance(p, Problem) and p.surface == surface]
+
+    def by_code(self, code: str) -> list[Problem]:
+        """Return all problems with a specific semantic code."""
+        return [p for p in self if isinstance(p, Problem) and p.code == code]
+
+    def surfaces(self) -> set[str]:
+        """Set of surfaces that have problems."""
+        return {p.surface for p in self if isinstance(p, Problem) and p.surface}
+
+    def codes(self) -> set[str]:
+        """Set of unique problem codes."""
+        return {p.code for p in self if isinstance(p, Problem) and p.code}
+
+    def to_dicts(self) -> list[ProblemDict]:
+        """Serialize all problems to dictionaries."""
+        return [p.to_dict() if isinstance(p, Problem) else {'message': str(p), 'surface': '', 'code': ''} for p in self]
+
+    def add(
+        self,
+        problem_or_message: Any,
+        *,
+        surface: str = '',
+        code: str = '',
+        target: str = '',
+        hint: Optional[str] = None,
+    ) -> None:
+        """Append a problem or wrap a string message into a Problem."""
+        if isinstance(problem_or_message, Problem):
+            self.append(problem_or_message)
+        else:
+            self.append(Problem(str(problem_or_message), surface=surface, code=code, target=target, hint=hint))
+
+
+# ---- Runtime Trouble --------------------------------------------------------
+
+class TroubleDict(TypedDict, total=False):
+    """Concrete dictionary structure for runtime trouble."""
+
+    message: str
+    code: str
+    severity: str
+    compartment: str
+    since: Optional[int]
+    hint: Optional[str]
+    metadata: Mapping[str, Any]
+
+
+class Trouble(str):
+    """What an operator should be told without having to ask for it.
+
+    Subclasses str so that existing tests asserting against `trouble()`
+    strings, substring matches (`'relay' in t`), list equality (`[t] == ['foo']`),
+    and string formatting continue to work 100% identically without breaking changes.
+    """
+
+    code: str
+    compartment: str
+    message: str
+    severity: str
+    since: Optional[int]
+    hint: Optional[str]
+    metadata: Mapping[str, Any]
+
+    def __new__(
+        cls: type[T_tr],
+        message: str,
+        *,
+        code: str = 'fault',
+        compartment: str = '',
+        severity: str = 'trouble',
+        since: Optional[int] = None,
+        hint: Optional[str] = None,
+        **metadata: Any,
+    ) -> T_tr:
+        obj = super().__new__(cls, message)
+        obj.code = str(code)
+        obj.compartment = str(compartment)
+        obj.message = str(message)
+        obj.severity = str(severity)
+        obj.since = since
+        obj.hint = hint
+        obj.metadata = metadata
+        return obj
+
+    def to_dict(self) -> TroubleDict:
+        """Serialize to a JSON-compatible dictionary."""
+        d: TroubleDict = {
+            'message': self.message,
+            'code': self.code,
+            'severity': self.severity,
+        }
+        if self.compartment:
+            d['compartment'] = self.compartment
+        if self.since is not None:
+            d['since'] = self.since
+        if self.hint is not None:
+            d['hint'] = self.hint
+        if self.metadata:
+            d['metadata'] = self.metadata
+        return d
+
+
+class TroubleList(list[Any]):
+    """A list of Trouble items offering filtering and serialization."""
+
+    def for_compartment(self, compartment: str) -> list[Trouble]:
+        """Filter troubles belonging to a specific compartment."""
+        return [t for t in self if isinstance(t, Trouble) and t.compartment == compartment]
+
+    def by_code(self, code: str) -> list[Trouble]:
+        """Filter troubles by fault code."""
+        return [t for t in self if isinstance(t, Trouble) and t.code == code]
+
+    def by_severity(self, severity: str) -> list[Trouble]:
+        """Filter troubles by severity ('trouble', 'warning', 'fatal', etc.)."""
+        return [t for t in self if isinstance(t, Trouble) and t.severity == severity]
+
+    def codes(self) -> set[str]:
+        """Set of unique trouble codes."""
+        return {t.code for t in self if isinstance(t, Trouble) and t.code}
+
+    def compartments(self) -> set[str]:
+        """Set of compartments reporting trouble."""
+        return {t.compartment for t in self if isinstance(t, Trouble) and t.compartment}
+
+    def to_dicts(self) -> list[TroubleDict]:
+        """Serialize all troubles to dictionaries."""
+        return [t.to_dict() if isinstance(t, Trouble) else {'message': str(t), 'code': 'fault', 'severity': 'trouble'} for t in self]
+
+    def add(
+        self,
+        trouble_or_message: Any,
+        *,
+        code: str = 'fault',
+        compartment: str = '',
+        severity: str = 'trouble',
+        since: Optional[int] = None,
+        hint: Optional[str] = None,
+        **kw: Any,
+    ) -> None:
+        """Append a trouble item or wrap a raw string into a Trouble instance."""
+        if isinstance(trouble_or_message, Trouble):
+            self.append(trouble_or_message)
+        else:
+            self.append(Trouble(
+                str(trouble_or_message),
+                code=code,
+                compartment=compartment,
+                severity=severity,
+                since=since,
+                hint=hint,
+                **kw,
+            ))
+
+
+# ---- Runtime Notes ----------------------------------------------------------
+
+T_note = TypeVar('T_note', bound='Note')
+
+
+class NoteDict(TypedDict, total=False):
+    """Concrete dictionary structure for runtime notes."""
+
+    message: str
+    topic: str
+    level: str
+    compartment: str
+    since: Optional[int]
+    metadata: Mapping[str, Any]
+
+
+class Note(str):
+    """What an operator would want to read, that is not a fault.
+
+    A relay cooling after a rate-limit, a peer that announced it is
+    leaving: the node behaving, and the reason a quiet mesh is quiet.
+    Kept apart from `trouble()` so no reader has to classify prose.
+    Subclasses str so that existing tests asserting against `notes()`
+    strings, substring matches, or list equality continue to work 100% identically.
+    """
+
+    topic: str
+    compartment: str
+    message: str
+    level: str
+    since: Optional[int]
+    metadata: Mapping[str, Any]
+
+    def __new__(
+        cls: type[T_note],
+        message: str,
+        *,
+        topic: str = 'general',
+        compartment: str = '',
+        level: str = 'info',
+        since: Optional[int] = None,
+        **metadata: Any,
+    ) -> T_note:
+        obj = super().__new__(cls, message)
+        obj.topic = str(topic)
+        obj.compartment = str(compartment)
+        obj.message = str(message)
+        obj.level = str(level)
+        obj.since = since
+        obj.metadata = metadata
+        return obj
+
+    def to_dict(self) -> NoteDict:
+        """Serialize to a JSON-compatible dictionary."""
+        d: NoteDict = {
+            'message': self.message,
+            'topic': self.topic,
+            'level': self.level,
+        }
+        if self.compartment:
+            d['compartment'] = self.compartment
+        if self.since is not None:
+            d['since'] = self.since
+        if self.metadata:
+            d['metadata'] = self.metadata
+        return d
+
+
+class NoteList(list[Any]):
+    """A list of Note items offering filtering and serialization."""
+
+    def for_compartment(self, compartment: str) -> list[Note]:
+        """Filter notes belonging to a specific compartment."""
+        return [n for n in self if isinstance(n, Note) and n.compartment == compartment]
+
+    def by_topic(self, topic: str) -> list[Note]:
+        """Filter notes by topic."""
+        return [n for n in self if isinstance(n, Note) and n.topic == topic]
+
+    def by_level(self, level: str) -> list[Note]:
+        """Filter notes by level ('info', 'notice', 'debug', etc.)."""
+        return [n for n in self if isinstance(n, Note) and n.level == level]
+
+    def topics(self) -> set[str]:
+        """Set of unique note topics."""
+        return {n.topic for n in self if isinstance(n, Note) and n.topic}
+
+    def compartments(self) -> set[str]:
+        """Set of compartments reporting notes."""
+        return {n.compartment for n in self if isinstance(n, Note) and n.compartment}
+
+    def to_dicts(self) -> list[NoteDict]:
+        """Serialize all notes to dictionaries."""
+        return [n.to_dict() if isinstance(n, Note) else {'message': str(n), 'topic': 'general', 'level': 'info'} for n in self]
+
+    def add(
+        self,
+        note_or_message: Any,
+        *,
+        topic: str = 'general',
+        compartment: str = '',
+        level: str = 'info',
+        since: Optional[int] = None,
+        **kw: Any,
+    ) -> None:
+        """Append a note item or wrap a raw string into a Note instance."""
+        if isinstance(note_or_message, Note):
+            self.append(note_or_message)
+        else:
+            self.append(Note(
+                str(note_or_message),
+                topic=topic,
+                compartment=compartment,
+                level=level,
+                since=since,
+                **kw,
+            ))
+

node/compartment/refusals.py

@@ -0,0 +1,120 @@
+"""Every 'no' a compartment says, counted by reason and kept with detail.
+
+Split out of node/compartment.py when it became a package; see that package's
+docstring for why a refusal that is not recorded is indistinguishable from
+silence.
+"""
+from __future__ import annotations
+
+import collections
+import threading
+import time
+from typing import Any, Callable, Counter, Deque, Mapping, NamedTuple, Optional, TypedDict
+
+
+class Refusal(NamedTuple):
+    at: int
+    kind: str
+    subject: Optional[str]
+    why: str
+    detail: Mapping[str, Any]
+
+
+class RefusalRecentSummary(TypedDict):
+    at: int
+    kind: str
+    subject: Optional[str]
+    why: str
+    detail: Mapping[str, Any]
+
+
+class RefusalsStateReport(TypedDict):
+    total: int
+    by_reason: dict[str, int]
+    recent: list[RefusalRecentSummary]
+
+
+class Refusals:
+    """Every 'no' one compartment said, counted by reason and kept with detail.
+
+    Counted so a rate is visible; kept so the last few can be read. A reason is
+    a short stable string and never a formatted id, because a reason is a
+    category and the ids belong in the detail where they cannot explode the
+    key space.
+    """
+
+    def __init__(self, name: Optional[str], keep: int = 200,
+                 clock: Optional[Callable[[], int]] = None) -> None:
+        self.name: Optional[str] = name
+        self.keep: int = keep
+        # Stamps and windows read this clock when a caller gives no `at`/`now`.
+        # A compartment hands its own, so a refusal and the trouble() that
+        # reads it never disagree about what "now" is.
+        self.clock: Callable[[], int] = clock or (lambda: int(time.time()))
+        self._lock: threading.Lock = threading.Lock()
+        self.counts: Counter[str] = collections.Counter()
+        self.recent: Deque[Refusal] = collections.deque(maxlen=keep)
+
+    def refuse(
+        self,
+        kind: str,
+        why: str,
+        subject: Optional[str] = None,
+        detail: Optional[Mapping[str, Any]] = None,
+        at: Optional[int] = None,
+    ) -> Refusal:
+        r = Refusal(int(at if at is not None else self.clock()), kind, subject, why, detail or {})
+        with self._lock:
+            self.counts['%s: %s' % (kind, why)] += 1
+            self.recent.append(r)
+        return r
+
+    def total(self) -> int:
+        return sum(self.counts.values())
+
+    def last(self, n: int = 5) -> list[Refusal]:
+        with self._lock:
+            return list(self.recent)[-n:]
+
+    def within(
+        self,
+        seconds: int,
+        now: Optional[int] = None,
+        kind: Optional[str] = None,
+        why: Optional[str] = None,
+    ) -> list[Refusal]:
+        """Refusals from the last `seconds`, which is what trouble means.
+
+        Trouble is what is wrong NOW. Reading the whole buffer reports a fault
+        that has been fixed until the buffer happens to roll, and an operator
+        who is shouted at about something already mended learns to stop reading
+        the shouting. The counts keep the history; this answers the present.
+        """
+        cut = int(now if now is not None else self.clock()) - seconds
+        with self._lock:
+            rows = [r for r in self.recent if r.at >= cut]
+        if kind is not None:
+            rows = [r for r in rows if r.kind == kind]
+        if why is not None:
+            rows = [r for r in rows if r.why == why]
+        return rows
+
+    def state(self, n: int = 5) -> RefusalsStateReport:
+        return {
+            'total': self.total(),
+            'by_reason': dict(self.counts),
+            'recent': [
+                {
+                    'at': r.at,
+                    'kind': r.kind,
+                    'subject': (r.subject or '')[:16] or None,
+                    'why': r.why,
+                    'detail': r.detail,
+                }
+                for r in self.last(n)
+            ],
+        }
+
+
+def why_detail(e: BaseException) -> dict[str, str]:
+    return {'error': '%s: %s' % (type(e).__name__, e)}