"""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: ...
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]: ...