ropemother 0.1.0.dev8__py3-none-any.whl

ropemother/__init__.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# ropemother/__init__.py
+
+"""A module for publish-subscribe broadcast messaging."""
+
+from importlib import import_module
+from typing import Any
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-07-05T15:40:19+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"
+
+
+_EXPORTS = {
+    "AsyncDirectMessageBus": "ropemother.broker.asyncdirect",
+    "CAPTURE_PORTABLE_FORMAT": "ropemother.format.portableformat",
+    "CaptureMode": "ropemother.broker.directcore",
+    "DirectMessageBus": "ropemother.broker.direct",
+    "InMemoryCaptureSink": "ropemother.capture.memorysink",
+    "JSONLinesCaptureSink": "ropemother.capture.filesink",
+    "JSON_PORTABLE_FORMAT": "ropemother.format.portableformat",
+    "MessageBusBaseException": "ropemother.exceptions",
+    "PayloadSerializationError": "ropemother.exceptions",
+    "PortableFormat": "ropemother.format.portableformat",
+    "RAW_BYTES_PORTABLE_FORMAT": "ropemother.format.portableformat",
+    "ReceivedMessage": "ropemother.message.records",
+    "connect_async_message_bus": "ropemother.service.environment",
+    "connect_message_bus": "ropemother.service.environment",
+    "exact_topic": "ropemother.message.selectors",
+    "topic_tree": "ropemother.message.selectors",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(name)
+
+    module = import_module(_EXPORTS[name])
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

ropemother/bootstrap/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+# ropemother/bootstrap/__init__.py
+
+"""Implements startup message buffering policy."""
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-07-01T20:13:04+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"

ropemother/bootstrap/buffer.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# ropemother/bootstrap/buffer.py
+
+"""Support for bootstrap buffering of capture records at startup."""
+
+from dataclasses import dataclass
+
+from ropemother.capture.sink import CaptureSink
+from ropemother.capture.writer import CaptureRecord, CaptureRecordWriter
+from ropemother.exceptions import MessageBusBaseException
+from ropemother.format.registry import PortableFormatRegistration
+from ropemother.message.records import CapturedMessage
+from ropemother.message.symbols import MessageSymbolRegistration
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-07-02T07:00:19+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"
+
+
+DEFAULT_BOOTSTRAP_BUFFER_BYTES = 4 * 1024 * 1024
+DEFAULT_BOOTSTRAP_BUFFER_RECORD_LIMIT = 256
+
+
+class BootstrapBufferError(MessageBusBaseException):
+    """Base exception for bootstrap buffer errors."""
+    pass
+
+
+class InvalidBootstrapBufferLimitError(ValueError, BootstrapBufferError):
+    """Raised when bootstrap buffer limits are invalid."""
+    pass
+
+
+class BootstrapBufferLimitExceededError(BufferError, BootstrapBufferError):
+    """Raised when bootstrap buffering exceeds configured limits."""
+    pass
+
+
+@dataclass(frozen=True, kw_only=True)
+class BootstrapBufferLimits:
+    """Record and payload byte limits for bootstrap buffering."""
+    max_records: int = DEFAULT_BOOTSTRAP_BUFFER_RECORD_LIMIT
+    max_payload_bytes: int = DEFAULT_BOOTSTRAP_BUFFER_BYTES
+
+    def __post_init__(self) -> None:
+        if self.max_records < 1:
+            raise InvalidBootstrapBufferLimitError(
+                "bootstrap buffer record limit must be positive"
+            )
+        if self.max_payload_bytes < 0:
+            raise InvalidBootstrapBufferLimitError(
+                "bootstrap buffer payload byte limit must not be negative"
+            )
+
+
+class BootstrapBuffer(CaptureRecordWriter):
+    """Temporary capture record writer used during broker bootstrap."""
+    _limits: BootstrapBufferLimits
+    _records: list[CaptureRecord]
+    _payload_bytes: int
+
+    def __init__(self, *, limits: BootstrapBufferLimits | None = None) -> None:
+        if limits is None:
+            limits = BootstrapBufferLimits()
+
+        self._limits = limits
+        self._records = []
+        self._payload_bytes = 0
+
+    @property
+    def pending_record_count(self) -> int:
+        return len(self._records)
+
+    @property
+    def pending_payload_bytes(self) -> int:
+        return self._payload_bytes
+
+    def pending_records(self) -> tuple[CaptureRecord, ...]:
+        return tuple(self._records)
+
+    def clear(self) -> None:
+        self._records.clear()
+        self._payload_bytes = 0
+
+    def flush_to(self, capture_sink: CaptureSink) -> None:
+        for record in self._records:
+            capture_sink.write_record(record)
+
+        self.clear()
+
+    def write_message_record(self, message: CapturedMessage) -> None:
+        self._append_record(message)
+
+    def write_format_registration(
+        self, registration: PortableFormatRegistration
+    ) -> None:
+        self._append_record(registration)
+
+    def write_symbol_registration(
+        self, registration: MessageSymbolRegistration
+    ) -> None:
+        self._append_record(registration)
+
+    def _append_record(self, record: CaptureRecord) -> None:
+        candidate_payload_bytes = self._payload_byte_count(record)
+        next_record_count = len(self._records) + 1
+        next_payload_bytes = self._payload_bytes + candidate_payload_bytes
+
+        if next_record_count > self._limits.max_records:
+            raise BootstrapBufferLimitExceededError(
+                "bootstrap buffer record limit exceeded"
+            )
+        if next_payload_bytes > self._limits.max_payload_bytes:
+            raise BootstrapBufferLimitExceededError(
+                "bootstrap buffer payload byte limit exceeded"
+            )
+
+        self._records.append(record)
+        self._payload_bytes = next_payload_bytes
+
+    def _payload_byte_count(self, record: CaptureRecord) -> int:
+        if isinstance(record, CapturedMessage):
+            return len(record.serialized_payload.payload_bytes)
+        return 0

ropemother/bootstrap/policy.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+# ropemother/bootstrap/policy.py
+
+"""Bootstrap traffic policy objects."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import StrEnum
+
+from ropemother.exceptions import MessageBusBaseException
+from ropemother.message.records import BusMessage, BusOperation
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-07-02T07:03:33+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"
+
+
+DEFAULT_LIFECYCLE_TOPIC_ROOT = "lifecycle"
+DEFAULT_LIFECYCLE_OPERATIONS = frozenset({BusOperation.PUBLISH})
+
+
+class BootstrapPolicyError(MessageBusBaseException):
+    """Base exception for bootstrap policy errors."""
+    pass
+
+
+class BootstrapMessageRejectedError(RuntimeError, BootstrapPolicyError):
+    """Raised when bootstrap message traffic is rejected."""
+    pass
+
+
+class LifecycleMessageType(StrEnum):
+    """Built-in lifecycle message types allowed during bootstrap."""
+    STARTED = "started"
+    READY = "ready"
+    FAILED = "failed"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+
+
+DEFAULT_LIFECYCLE_MESSAGE_TYPES = frozenset(
+    message_type.value for message_type in LifecycleMessageType
+)
+
+
+@dataclass(frozen=True, kw_only=True)
+class BootstrapDecision:
+    """Decision result for bootstrap message traffic."""
+    accepted: bool
+    reason: str = ""
+
+
+class BootstrapPolicy(ABC):
+    """Policy interface for deciding bootstrap message traffic."""
+    @abstractmethod
+    def decide_message(self, message: BusMessage) -> BootstrapDecision:
+        pass
+
+
+class RejectBootstrapPolicy(BootstrapPolicy):
+    """Bootstrap policy that rejects all message traffic."""
+    def decide_message(self, message: BusMessage) -> BootstrapDecision:
+        decision = BootstrapDecision(
+            accepted=False,
+            reason="bootstrap message traffic is not allowed",
+        )
+        return decision
+
+
+@dataclass(frozen=True, kw_only=True)
+class LifecycleBootstrapPolicy(BootstrapPolicy):
+    """Bootstrap policy that permits selected lifecycle messages."""
+    topic_root: str = DEFAULT_LIFECYCLE_TOPIC_ROOT
+    msg_types: frozenset[str] = DEFAULT_LIFECYCLE_MESSAGE_TYPES
+    operations: frozenset[BusOperation] = DEFAULT_LIFECYCLE_OPERATIONS
+
+    def decide_message(self, message: BusMessage) -> BootstrapDecision:
+        if message.bus_operation not in self.operations:
+            decision = BootstrapDecision(
+                accepted=False,
+                reason="bootstrap message operation is not allowed",
+            )
+        elif not _topic_matches_root(message.msg_topic, self.topic_root):
+            decision = BootstrapDecision(
+                accepted=False,
+                reason="bootstrap message topic is not allowed",
+            )
+        elif message.msg_type not in self.msg_types:
+            decision = BootstrapDecision(
+                accepted=False,
+                reason="bootstrap message type is not allowed",
+            )
+        else:
+            decision = BootstrapDecision(accepted=True)
+
+        return decision
+
+
+def _topic_matches_root(msg_topic: str, topic_root: str) -> bool:
+    matches_root = msg_topic == topic_root
+    matches_child = msg_topic.startswith(topic_root + ".")
+    return matches_root or matches_child

ropemother/broker/__init__.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# ropemother/broker/__init__.py
+
+"""Supports and implements runtime publish-subscribe services."""
+
+from importlib import import_module
+from typing import Any
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-06-30T18:59:10+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"
+
+
+_EXPORTS = {
+    "AsyncDirectMessageBus": "ropemother.broker.asyncdirect",
+    "AsyncEmitter": "ropemother.broker.asyncendpoints",
+    "AsyncReceiver": "ropemother.broker.asyncendpoints",
+    "CaptureMode": "ropemother.broker.directcore",
+    "DirectMessageBus": "ropemother.broker.direct",
+    "Emitter": "ropemother.broker.endpoints",
+    "Receiver": "ropemother.broker.endpoints",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(name)
+
+    module = import_module(_EXPORTS[name])
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

ropemother/broker/asyncbase.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+# ropemother/broker/asyncbase.py
+
+"""Asynchronous abstract interface for message bus implementation."""
+
+import abc
+
+from ropemother.broker.asyncendpoints import AsyncEmitter, AsyncReceiver
+from ropemother.capture.sink import CaptureSink
+from ropemother.client.asyncendpointfactory import AsyncMessageEndpointFactory
+from ropemother.format.portableformat import (
+    PortableFormat,
+    JSON_PORTABLE_FORMAT,
+)
+from ropemother.message.selectors import (
+    OptionalSymbolInput,
+    SubscriptionTopicInput,
+    SymbolCollectionInput,
+)
+from ropemother.message.typeformats import SupportedTypeFormatsInput
+
+__author__ = "Joe Granville"
+__email__ = "874605+jwgranville@users.noreply.github.com"
+__date__ = "2026-08-20T17:37:34+00:00"
+__license__ = "MIT"
+__version__ = "0.1.0.dev8"
+__status__ = "Development"
+
+
+class AsyncMessageBus(AsyncMessageEndpointFactory):
+    """Abstract broker interface for async message bus implementations."""
+    @abc.abstractmethod
+    def register_emitter(
+        self,
+        *,
+        msg_topic: str,
+        msg_producer: str,
+        msg_type: str,
+        additional_msg_types: SymbolCollectionInput = (),
+        allow_unlisted_type_formats: bool = False,
+        payload_format: PortableFormat = JSON_PORTABLE_FORMAT,
+        supported_type_formats: SupportedTypeFormatsInput | None = None,
+    ) -> AsyncEmitter:
+        ...
+
+    @abc.abstractmethod
+    def subscribe(
+        self,
+        *,
+        msg_topic: SubscriptionTopicInput,
+        msg_producer: OptionalSymbolInput = None,
+        msg_type: OptionalSymbolInput = None,
+    ) -> AsyncReceiver:
+        ...
+
+    @abc.abstractmethod
+    def set_capture_sink(self, capture_sink: CaptureSink) -> None:
+        ...