pycfdp 0.2.2__py3-none-any.whl

cfdp/pure/config.py

@@ -0,0 +1,141 @@
+"""Per-transaction configuration snapshot (design D9).
+
+``TransactionConfig`` is a frozen snapshot that merges every per-transaction
+knob **once** at machine-creation time with the precedence
+
+    entity defaults  <-  remote-entity config  <-  per-``put`` overrides
+
+and folds in the resolved fault-handler map. ``get_fault_handler`` is then a
+pure dict lookup — no ``kernel`` access — which removes the last reason a
+machine or ``Transaction`` needs a ``kernel`` reference.
+
+Three plain input layers are modelled here so the merge is testable in
+isolation and the shell (issue #16) can build them without leaking itself:
+
+* :class:`EntityDefaults` — the entity-level knobs (always concrete values).
+* :class:`~cfdp.remote_entity_config.RemoteEntityConfig` — optional per-peer
+  overrides (existing type; ``None`` fields mean "no opinion").
+* :class:`PutOverrides` — optional per-``put`` overrides (``None`` fields mean
+  "no opinion").
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..constants import DEFAULT_FAULT_HANDLERS
+
+
+@dataclass(frozen=True)
+class EntityDefaults:
+    """Entity-level knob values — the lowest-precedence layer."""
+
+    transaction_inactivity_limit: float
+    ack_timer_interval: float
+    ack_timer_expiration_limit: int
+    nak_timer_interval: float
+    nak_timer_expiration_limit: int
+    maximum_file_segment_length: int
+    inter_pdu_delay: float = 0.0
+    # The entity's default fault-handler map. Codes it omits still fall back to
+    # DEFAULT_FAULT_HANDLERS during resolution.
+    fault_handlers: dict[Any, Any] = field(
+        default_factory=lambda: dict(DEFAULT_FAULT_HANDLERS)
+    )
+
+
+@dataclass(frozen=True)
+class PutOverrides:
+    """Per-``put`` knob overrides — the highest-precedence layer.
+
+    Every field defaults to ``None`` meaning "defer to the lower layers".
+    """
+
+    transaction_inactivity_limit: float | None = None
+    ack_timer_interval: float | None = None
+    ack_timer_expiration_limit: int | None = None
+    nak_timer_interval: float | None = None
+    nak_timer_expiration_limit: int | None = None
+    maximum_file_segment_length: int | None = None
+    inter_pdu_delay: float | None = None
+    fault_handler_overrides: dict[Any, Any] | None = None
+
+
+def _pick(*candidates_high_to_low):
+    """Return the first non-``None`` candidate (highest precedence first)."""
+    for value in candidates_high_to_low:
+        if value is not None:
+            return value
+    return None
+
+
+@dataclass(frozen=True)
+class TransactionConfig:
+    """Frozen, fully-resolved per-transaction configuration."""
+
+    transaction_inactivity_limit: float
+    ack_timer_interval: float
+    ack_timer_expiration_limit: int
+    nak_timer_interval: float
+    nak_timer_expiration_limit: int
+    maximum_file_segment_length: int
+    inter_pdu_delay: float
+    fault_handlers: dict[Any, Any]
+
+    @classmethod
+    def resolve(cls, entity_defaults, remote_config=None, put_overrides=None):
+        """Merge the three layers into an immutable snapshot.
+
+        Precedence for every scalar knob: ``put_overrides`` (if not ``None``)
+        beats ``remote_config`` (if not ``None``) beats ``entity_defaults``.
+        """
+        e = entity_defaults
+        r = remote_config
+        p = put_overrides
+
+        def pick(name, entity_value, remote_value=_UNSET):
+            put_value = getattr(p, name, None) if p is not None else None
+            if remote_value is _UNSET:
+                remote_value = getattr(r, name, None) if r is not None else None
+            return _pick(put_value, remote_value, entity_value)
+
+        # RemoteEntityConfig has no maximum_file_segment_length field, so its
+        # remote-layer value is always absent (None).
+        maximum_file_segment_length = _pick(
+            p.maximum_file_segment_length if p is not None else None,
+            e.maximum_file_segment_length,
+        )
+
+        return cls(
+            transaction_inactivity_limit=pick(
+                "transaction_inactivity_limit", e.transaction_inactivity_limit
+            ),
+            ack_timer_interval=pick("ack_timer_interval", e.ack_timer_interval),
+            ack_timer_expiration_limit=pick(
+                "ack_timer_expiration_limit", e.ack_timer_expiration_limit
+            ),
+            nak_timer_interval=pick("nak_timer_interval", e.nak_timer_interval),
+            nak_timer_expiration_limit=pick(
+                "nak_timer_expiration_limit", e.nak_timer_expiration_limit
+            ),
+            maximum_file_segment_length=maximum_file_segment_length,
+            inter_pdu_delay=pick("inter_pdu_delay", e.inter_pdu_delay),
+            fault_handlers=_resolve_fault_handlers(e, r, p),
+        )
+
+    def get_fault_handler(self, fault):
+        """Pure lookup of the resolved fault-handler action for ``fault``."""
+        return self.fault_handlers[fault]
+
+
+_UNSET = object()
+
+
+def _resolve_fault_handlers(entity_defaults, remote_config, put_overrides):
+    """Layer the fault-handler maps: spec default <- entity <- remote <- put."""
+    merged = dict(DEFAULT_FAULT_HANDLERS)
+    merged.update(entity_defaults.fault_handlers or {})
+    if remote_config is not None and remote_config.default_fault_handlers is not None:
+        merged.update(remote_config.default_fault_handlers)
+    if put_overrides is not None and put_overrides.fault_handler_overrides is not None:
+        merged.update(put_overrides.fault_handler_overrides)
+    return merged

cfdp/pure/indications.py

@@ -0,0 +1,130 @@
+"""Pure builders for the CFDP indication effects (design D3/D8).
+
+Every pure machine emits the same family of indications — TransactionFinished,
+Suspended, Resumed, Report, Abandoned, plus the various send/receive milestones.
+The tuple *shape* of each indication is protocol-fixed and identical across all
+four machines (only the *source* of the values differs, e.g. Receiver2 reads a
+late-recovered filename from machine state where Receiver1 reads it off the
+frozen transaction). The shapes therefore live here once, as free functions,
+instead of being re-spelled in every machine.
+
+These are deliberately **free functions, not methods on a shared base class**.
+They take the values they package explicitly and hold no state, so they cannot
+reach into a machine's ``self`` and cannot reintroduce the kernel / mutable-
+lifecycle coupling the cutover removed with the old ``machines/base.py``
+(issue #22). A machine wraps a call in its own ``self._emit`` so the emission
+point — and which ``self`` fields feed the tuple — stays visible at the call
+site:
+
+    self._emit(
+        indications.transaction_finished(
+            self.transaction.id,
+            self.condition_code,
+            self.file_status,
+            self.delivery_code,
+            self.filestore_responses,
+            self.status_report,
+        )
+    )
+
+Each function returns a single :class:`~cfdp.pure.outputs.EmitIndication`; the
+shell maps ``kind`` to the matching ``CfdpEntity._indication_*`` call (see
+``EffectExecutor._emit_indication``).
+"""
+
+from typing import Any
+
+from .outputs import EmitIndication, IndicationKind
+from .transaction import TransactionId
+
+
+def transaction(tid: TransactionId) -> EmitIndication:
+    """Transaction indication — a transaction has been started (send side)."""
+    return EmitIndication(IndicationKind.TRANSACTION, (tid,))
+
+
+def eof_sent(tid: TransactionId) -> EmitIndication:
+    """EOF-Sent indication — the sender has transmitted its EOF."""
+    return EmitIndication(IndicationKind.EOF_SENT, (tid,))
+
+
+def eof_received(tid: TransactionId) -> EmitIndication:
+    """EOF-Received indication — the receiver has seen the EOF."""
+    return EmitIndication(IndicationKind.EOF_RECEIVED, (tid,))
+
+
+def metadata_received(
+    tid: TransactionId,
+    source_entity_id: Any,
+    file_size: int,
+    source_filename: str | None,
+    destination_filename: str | None,
+    messages_to_user: Any,
+) -> EmitIndication:
+    """Metadata-Received indication — inbound Metadata has been processed.
+
+    ``source_filename`` / ``destination_filename`` / ``messages_to_user`` are
+    passed explicitly by the caller: Receiver1 supplies them from the frozen
+    transaction (Metadata always arrives first), while Receiver2 supplies them
+    from machine state (they may have arrived on a late-recovered Metadata).
+    """
+    return EmitIndication(
+        IndicationKind.METADATA_RECEIVED,
+        (
+            tid,
+            source_entity_id,
+            file_size,
+            source_filename,
+            destination_filename,
+            messages_to_user,
+        ),
+    )
+
+
+def filesegment_received(
+    tid: TransactionId, offset: int, length: int
+) -> EmitIndication:
+    """File-Segment-Received indication — a Filedata segment has been stored."""
+    return EmitIndication(IndicationKind.FILESEGMENT_RECEIVED, (tid, offset, length))
+
+
+def transaction_finished(
+    tid: TransactionId,
+    condition_code: Any,
+    file_status: Any,
+    delivery_code: Any,
+    filestore_responses: Any,
+    status_report: Any,
+) -> EmitIndication:
+    """Transaction-Finished indication — the transaction has completed."""
+    return EmitIndication(
+        IndicationKind.TRANSACTION_FINISHED,
+        (
+            tid,
+            condition_code,
+            file_status,
+            delivery_code,
+            filestore_responses,
+            status_report,
+        ),
+    )
+
+
+def suspended(tid: TransactionId, condition_code: Any) -> EmitIndication:
+    """Suspended indication — the transaction has been suspended."""
+    return EmitIndication(IndicationKind.SUSPENDED, (tid, condition_code))
+
+
+def resumed(tid: TransactionId, progress: int) -> EmitIndication:
+    """Resumed indication — the transaction has been resumed."""
+    return EmitIndication(IndicationKind.RESUMED, (tid, progress))
+
+
+def report(tid: TransactionId, status_report: Any) -> EmitIndication:
+    """Report indication — a requested status report."""
+    return EmitIndication(IndicationKind.REPORT, (tid, status_report))
+
+
+def abandoned(tid: TransactionId, condition_code: Any, progress: int) -> EmitIndication:
+    """Abandoned indication — the transaction has been abandoned."""
+    return EmitIndication(IndicationKind.ABANDONED, (tid, condition_code, progress))

cfdp/pure/machines/__init__.py

@@ -0,0 +1,25 @@
+"""Pure state machines (design ``docs/design/machine-decoupling.md``).
+
+Each machine here obeys the machine contract exactly:
+
+    Machine(transaction, config, query_port)
+    update_state(event) -> list[Output]
+
+No ``kernel`` reference, no threads, no open file descriptors, no wall clock.
+Effects are returned as :mod:`cfdp.pure.outputs` values; local + fast reads go
+through the injected :class:`~cfdp.pure.query_port.QueryPort`; timeouts and
+async results arrive as injected events.
+
+These are the only state machines in the codebase. They were originally built in
+parallel with an older, kernel-coupled implementation and verified against it by
+differential trace testing; at the cutover (issue #22) the old implementation was
+removed and its golden traces frozen to ``tests/golden_fixtures/`` (see
+``tests/trace_recorder.py``). The shell that runs them is ``cfdp.shell``.
+"""
+
+from .receiver1 import Receiver1
+from .receiver2 import Receiver2
+from .sender1 import Sender1
+from .sender2 import Sender2
+
+__all__ = ["Sender1", "Receiver1", "Sender2", "Receiver2"]