Source code for fleetmesh_node.interfaces

"""Formal interfaces, protocols, and data contracts for meshnode.

Standard library only. All wire types reflect the normative JSON Schemas in
schemas/ and the protocol invariants verified in fleetmesh_core/.
"""
from __future__ import annotations

from typing import (
    Any,
    Counter,
    Mapping,
    Optional,
    Protocol,
    Sequence,
    TypedDict,
    runtime_checkable,
)

# Core wire, event, filter, and DIDComm shapes are defined once in
# fleetmesh_core.wire.interfaces and re-exported here to ensure exact parity.
from fleetmesh_core.wire.interfaces import (
    DIDCommAttachment,
    DIDCommAttachmentData,
    DIDCommMessage,
    DeliveryEnvelope,
    DeliveryHop,
    EventLike,
    GrantLimits,
    GrantPayload,
    GrantScope,
    NostrEvent,
    NostrFilter,
    Tag,
    TagList,
    UnsignedNostrEvent,
    ProtocolHealth,
    RouteMatch,
    ProtocolHostRouter,
    ProtocolIdentityAdapter,
    ProtocolPackage,
)

__all__ = [
    'DeliveryEnvelope', 'DeliveryHop', 'GrantLimits', 'GrantPayload', 'GrantScope',
    'Tag', 'TagList', 'NostrEvent', 'UnsignedNostrEvent', 'EventLike', 'NostrFilter',
    'DIDCommAttachmentData', 'DIDCommAttachment', 'DIDCommMessage',
    'RelayHealthRow', 'AwaitingAckRow', 'ThrottledRow', 'ReceiptRefusedRow',
    'GrantStatusRow', 'PendingGrantRow', 'EvaluationRow', 'RepricedRow',
    'HealthStatusDict', 'NodeStatusDict', 'CommandSpec',
    'KeyStoreProtocol', 'TransportProtocol', 'EventStoreProtocol', 'CompartmentProtocol',
    'ProtocolHealth', 'RouteMatch', 'ProtocolHostRouter', 'ProtocolIdentityAdapter', 'ProtocolPackage',
]


[docs]@runtime_checkable class KeyStoreProtocol(Protocol): """The node keys and identity.""" node_sk: str node_pk: str did: str
[docs] def multikeys(self) -> dict[str, str]: ...
[docs] def kid(self, which: str = 'agreement') -> str: ...
[docs] def save(self, directory: Any) -> str: ...
[docs]@runtime_checkable class TransportProtocol(Protocol): """The transport adapter interface: sends and receives DIDComm envelopes.""" scheme: str health: Mapping[str, Mapping[str, Any]] drop_counts: Counter[str]
[docs] def send(self, peer_pk: str, message: DIDCommMessage | Mapping[str, Any], authenticated: bool = True) -> Any: ...
[docs] def request(
self, peer_pk: str, message: DIDCommMessage | Mapping[str, Any], timeout: Optional[float] = None, authenticated: bool = True, ) -> Optional[DIDCommMessage | Mapping[str, Any]]: ...
[docs] def close(self) -> None: ...
[docs]@runtime_checkable class EventStoreProtocol(Protocol): """Storage for Nostr events and provenance."""
[docs] def insert_event(self, event: NostrEvent) -> str: ...
[docs] def get_event(self, event_id: str) -> Optional[NostrEvent]: ...
[docs] def has_event(self, event_id: str) -> bool: ...
[docs] def note_origin(self, event_id: str, origin: str) -> None: ...
[docs] def origin_of(self, event_id: str) -> Optional[str]: ...
[docs] def any_replicated(self, event_ids: Sequence[str]) -> bool: ...
[docs] def fingerprint_range(self, filt: NostrFilter | Mapping[str, Any], since: int, until: int, now: int) -> str: ...
# ---- what `meshnode status` and `meshnode health` format ------------------- # # A compartment's state() is free-form: it is JSON-serialised the moment it is # read, and the CLI prints most of it with .get(). These are the rows whose # fields the CLI formats by name, so a compartment that renames one is caught # where it is written rather than where an operator reads it. total=False # because status.json on disk predates every one of them.
[docs]class RelayHealthRow(TypedDict, total=False): connected: bool confirmed: bool # the relay answered the REQ, not merely received it since: Optional[int] reconnects: int last_event_at: Optional[int] last_error: Optional[str]
[docs]class AwaitingAckRow(TypedDict, total=False): peer: str type: str at: int relays: list[str] heard_at: Optional[int] # unacknowledged rows only: when the peer last spoke
[docs]class ThrottledRow(TypedDict, total=False): peer: str shard: str why: str until: int
[docs]class ReceiptRefusedRow(TypedDict, total=False): peer: Optional[str] window: Optional[int] named: Optional[str] acceptable: list[str] at: int
[docs]class GrantStatusRow(TypedDict, total=False): peer: str direction: str tier: Optional[str] status: str
[docs]class PendingGrantRow(TypedDict, total=False): peer: str tier: Optional[str] from_epoch: int
[docs]class EvaluationRow(TypedDict, total=False): peer: str epoch: int severity: Optional[str] # None for a silent window: nothing was priced state: str
[docs]class RepricedRow(TypedDict, total=False): peer: str epoch: int was: str severity: str remedy_cancelled: bool
[docs]class HealthStatusDict(TypedDict, total=False): subsystem_trouble: list[str] config_error: Optional[str] handler_failures: int tick_failures: int last_tick_error: Optional[str] rejected: Mapping[str, int] relays: Mapping[str, RelayHealthRow] sessions_refused: int receipts_refused: list[ReceiptRefusedRow] awaiting_ack: list[AwaitingAckRow] throttled: list[ThrottledRow] grants: list[GrantStatusRow] evaluations: list[EvaluationRow] repriced: list[RepricedRow] subsystems: Mapping[str, Any]
class VisibilityState(TypedDict, total=False): """A node's resolved visibility (plan D2): the default, the overrides, and whether each of its protocols and capabilities is public. What `status` carries and what a `set-visibility` reply answers.""" default: str overrides: Mapping[str, str] public: bool protocols: Mapping[str, str] capabilities: Mapping[str, str] descriptor: str | None relays: Mapping[str, tuple[bool, str]] waits: str NodeStatusDict = TypedDict('NodeStatusDict', { 'at': int, 'did': str, 'node_did': str, 'pubkey': str, 'class': str, 'release': Mapping[str, Any], 'face': str, 'relays': list[str], 'descriptor': str, 'visibility': VisibilityState, 'events_stored': int, 'grants': list[GrantStatusRow], 'pending_grants': list[PendingGrantRow], 'evaluations': list[EvaluationRow], 'repriced': list[RepricedRow], 'reports_published': int, 'pending_findings': int, 'refused_sessions': int, 'last_tick': list[list[str]], 'uptime': int | float, 'health': HealthStatusDict, 'compartments': Mapping[str, Any], 'subsystems': Mapping[str, Any], }, total=False)
[docs]class CommandSpec(TypedDict, total=False): """One control-socket command as the socket documents it under `commands`: the dispatch table is the documentation, so it cannot drift from it.""" args: Mapping[str, str] # name -> required | optional | a short note does: str reply: str subsystem: str # set by the registry when it prefixes the name
[docs]@runtime_checkable class CompartmentProtocol(Protocol): """A compartment of the node, assembled and ticked uniformly.""" name: Optional[str] reads: tuple[str, ...] live: tuple[str, ...] commands: Mapping[str, CommandSpec]
[docs] def start(self) -> None: ...
[docs] def tick(self, now: int) -> list[tuple[Any, ...]]: ...
[docs] def stop(self) -> Any: ...
[docs] def state(self) -> Mapping[str, Any]: ...
[docs] def trouble(self) -> list[str]: ...
[docs] def notes(self) -> list[str]: ...
[docs] def report(self) -> Mapping[str, Any]: ...
[docs] def command(self, name: str, args: Mapping[str, Any]) -> Any: ...
[docs] def capability_protocols(self) -> Sequence[str]: ...
[docs] def descriptor_tags(self) -> Sequence[Sequence[str]]: ...