pycfdp 0.2.2__py3-none-any.whl

cfdp/core.py

@@ -0,0 +1,895 @@
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from typing import TYPE_CHECKING, Any
+
+from . import logger
+from .constants import (
+    DEFAULT_ACK_TIMER_EXPIRATION_LIMIT,
+    DEFAULT_ACK_TIMER_LIMIT,
+    DEFAULT_FAULT_HANDLERS,
+    DEFAULT_INACTIVITY_TIMEOUT,
+    DEFAULT_MAX_FILE_SEGMENT_LEN,
+    DEFAULT_NAK_TIMER_EXPIRATION_LIMIT,
+    DEFAULT_NAK_TIMER_INTERVAL,
+    ChecksumType,
+    ConditionCode,
+    Direction,
+    DirectiveCode,
+    DirectiveSubTypeCode,
+    MachineState,
+    PduTypeCode,
+    TransactionStatus,
+    TransmissionMode,
+)
+from .event import Event, EventType
+from .meta import process_user_message as meta_process_user_message
+from .pdu import (
+    AckPdu,
+    EofPdu,
+    FiledataPdu,
+    FinishedPdu,
+    KeepAlivePdu,
+    MetadataPdu,
+    NakPdu,
+    PduHeader,
+    PromptPdu,
+)
+from .pure.transaction import TransactionId
+from .shell import Dispatcher, EffectExecutor, FileTable, MachineRegistry
+from .shell.checksum_service import ChecksumService
+from .shell.timer_service import TimerService
+from .transaction_handle import TransactionHandle
+
+if TYPE_CHECKING:
+    from .filestore.base import VirtualFileStore
+    from .transport.base import Transport
+
+
+class CfdpEntity:
+    """The public CFDP entity — the one object callers construct and drive.
+
+    A thin facade over the functional-core / imperative-shell stack (design
+    ``docs/design/machine-decoupling.md``): it holds the shell collaborators
+    (``Dispatcher``, ``MachineRegistry``, ``EffectExecutor``, ``TimerService``,
+    ``ChecksumService``, ``FileTable``) and exposes the user-facing verbs
+    (``put``, ``cancel``, ``suspend``, ``resume``, ``report``, ``freeze``,
+    ``thaw``, ``start``/``stop``). One entity serves both roles (sender and
+    receiver) for many concurrent transactions.
+
+    ``self.machines`` is the live ``tid -> machine`` map, keyed by transaction
+    id — a ``(source_entity_id, seq_number)`` tuple; the ``MachineRegistry``
+    shares this same dict.
+
+    Constructor knobs:
+
+    * ``entity_id`` — this entity's CFDP id (protocol-opaque).
+    * ``filestore`` — the :class:`~cfdp.filestore.base.VirtualFileStore` backing
+      file reads/writes.
+    * ``transport`` — the :class:`~cfdp.transport.base.Transport` used to send
+      and receive PDUs.
+    * ``*_indication_required`` — per-indication opt-in flags controlling which
+      optional indications fire.
+    * ``default_fault_handlers`` — condition-code -> action map applied when a
+      remote/put config does not override a handler.
+    * ``transaction_inactivity_limit`` — seconds of silence before the
+      inactivity timer faults a transaction.
+    * ``positive_ack_timer_interval`` / ``positive_ack_timer_expiration_limit``
+      — ACK-timer period (seconds) and its expiration count before faulting.
+    * ``nak_timer_interval`` / ``nak_timer_expiration_limit`` — NAK-timer period
+      (seconds) and its expiration count before faulting.
+    * ``maximum_file_segment_length`` — max Filedata payload bytes per PDU.
+    * ``inter_pdu_delay`` — seconds to pace between outbound file-data segments
+      (0.0 = as fast as the transport accepts).
+    * ``completed_transaction_ttl`` — seconds a completed machine is retained
+      before reaping.
+    * ``remote_entity_configs`` — optional ``{entity_id: RemoteEntityConfig}``
+      per-peer overrides.
+
+    Every knob has a spec-derived default; only ``entity_id``, ``filestore``,
+    and ``transport`` are required.
+    """
+
+    # Minimum yield inserted before re-enqueuing the file-data pump when the
+    # transport is not writable, so an unready link idles rather than spinning
+    # (design R4 / issue #20). Read in trigger_event.
+    _BACKPRESSURE_YIELD = 0.01
+
+    def __init__(
+        self,
+        entity_id: Any,
+        filestore: VirtualFileStore,
+        transport: Transport,
+        eof_sent_indication_required: bool = False,
+        eof_received_indication_required: bool = False,
+        filesegment_received_indication_required: bool = False,
+        transaction_finished_indication_required: bool = False,
+        suspended_indication_required: bool = False,
+        resumed_indication_required: bool = False,
+        default_fault_handlers: dict = DEFAULT_FAULT_HANDLERS,
+        transaction_inactivity_limit: float = DEFAULT_INACTIVITY_TIMEOUT,
+        positive_ack_timer_interval: float = DEFAULT_ACK_TIMER_LIMIT,
+        positive_ack_timer_expiration_limit: int = DEFAULT_ACK_TIMER_EXPIRATION_LIMIT,
+        nak_timer_interval: float = DEFAULT_NAK_TIMER_INTERVAL,
+        nak_timer_expiration_limit: int = DEFAULT_NAK_TIMER_EXPIRATION_LIMIT,
+        maximum_file_segment_length: int = DEFAULT_MAX_FILE_SEGMENT_LEN,
+        inter_pdu_delay: float = 0.0,
+        completed_transaction_ttl: float = 60.0,
+        remote_entity_configs: dict | None = None,
+        write_to_destination_directly: bool = False,
+    ) -> None:
+        self.entity_id = entity_id
+        self.filestore = filestore
+        self.transport = transport
+        self.eof_sent_indication_required = eof_sent_indication_required
+        self.eof_received_indication_required = eof_received_indication_required
+        self.filesegment_received_indication_required = (
+            filesegment_received_indication_required
+        )
+        self.transaction_finished_indication_required = (
+            transaction_finished_indication_required
+        )
+        self.suspended_indication_required = suspended_indication_required
+        self.resumed_indication_required = resumed_indication_required
+        self.default_fault_handlers = default_fault_handlers
+        self.transaction_inactivity_limit = transaction_inactivity_limit
+        self.positive_ack_timer_interval = positive_ack_timer_interval
+        self.positive_ack_timer_expiration_limit = positive_ack_timer_expiration_limit
+        self.nak_timer_interval = nak_timer_interval
+        self.nak_timer_expiration_limit = nak_timer_expiration_limit
+        self.maximum_file_segment_length = maximum_file_segment_length
+        self.inter_pdu_delay = inter_pdu_delay
+        self.completed_transaction_ttl = completed_transaction_ttl
+        # Receive-side option: write incoming file data straight into the
+        # destination file instead of buffering to a temp file and copying it at
+        # Finished time. Lets a remote-service filestore show download progress.
+        # Interpreted entirely in the shell (EffectExecutor); the pure machines
+        # are unaware of it. Default False preserves the temp-file behaviour.
+        self.write_to_destination_directly = write_to_destination_directly
+        self._remote_entity_configs = remote_entity_configs or {}
+        self._transaction_seq_counter = 0
+        self._seq_lock = threading.Lock()
+        self.machines: dict[TransactionId, Any] = {}
+        self._completion_times: dict[TransactionId, float] = {}
+
+        self._event_queue: queue.Queue = queue.Queue()
+        # Typed Any, not Thread: start() attaches a dynamic ``.kill`` flag to the
+        # thread object that the handler loops poll, so these are not plain
+        # threading.Thread instances. Retyping that shutdown mechanism is out of
+        # scope for the annotation pass.
+        self._event_thread: Any = None
+
+        self._messages_to_user_queue: queue.Queue = queue.Queue()
+        self._message_thread: Any = None
+
+        self._started = False
+        self._transaction_inter_pdu_delays: dict[TransactionId, float] = {}
+        self._completion_events: dict[TransactionId, threading.Event] = {}
+
+        # Live file-data pacing timers (issue #31). The E1 re-enqueue paces via a
+        # ``threading.Timer``; untracked, one could fire after ``stop()`` and push
+        # onto a drained queue / leave an unjoined thread (tripping the suite's
+        # active-thread-count assertions). We track them so ``stop()`` can cancel
+        # and join every pending one. Guarded by its own lock: timers are armed on
+        # the event thread but fire (and self-remove) on their own timer threads.
+        self._pacing_timers: set[threading.Timer] = set()
+        self._pacing_lock = threading.Lock()
+
+        # Functional-core / imperative-shell stack (design
+        # docs/design/machine-decoupling.md; issues #16 / #20 / #22). Both
+        # Class-1 (UNACKNOWLEDGED) and Class-2 (ACKNOWLEDGED) transfers route
+        # through the pure machines + shell collaborators. The registry shares
+        # this entity's ``machines`` dict so every lookup path sees the machines
+        # uniformly.
+        self._file_table = FileTable()
+        # The wall-clock timer table (design D6 / issue #17). Owns real timers
+        # per (tid, kind); an expiry re-enters via trigger_event onto the shared
+        # FIFO (design D8). The executor drives it from StartTimer/CancelTimer/
+        # SuspendTimer/ResumeTimer effects.
+        self._timer_service = TimerService(self)
+        # The async-checksum worker (design R1 / issue #21). A RequestChecksum
+        # effect computes the whole-file checksum off the event thread and
+        # injects E42_CHECKSUM_READY onto the shared FIFO, so a large-file
+        # checksum no longer stalls every other transaction on the dispatcher.
+        self._checksum_service = ChecksumService(self, self._file_table)
+        self._effect_executor = EffectExecutor(
+            self, self._file_table, self._timer_service, self._checksum_service
+        )
+        self._machine_registry = MachineRegistry(
+            self, self._file_table, machines=self.machines
+        )
+        self._dispatcher = Dispatcher(
+            self, self._machine_registry, self._effect_executor
+        )
+
+        # Callback attributes — set to a callable to receive indications
+        self.on_transaction_finished = None
+        self.on_metadata_received = None
+        self.on_eof_sent = None
+        self.on_eof_received = None
+        self.on_filesegment_received = None
+        self.on_suspended = None
+        self.on_resumed = None
+        self.on_report = None
+        self.on_fault = None
+        self.on_abandoned = None
+        self.on_unrecognized_message = None
+
+    def start(self) -> None:
+        """Begin the event thread, message thread, and transport receive loop."""
+        if self._started:
+            return
+        self._started = True
+        self._event_thread = threading.Thread(target=self._event_handler, daemon=True)
+        self._event_thread.kill = False
+        self._message_thread = threading.Thread(
+            target=self._message_handler, daemon=True
+        )
+        self._message_thread.kill = False
+        self._event_thread.start()
+        self._message_thread.start()
+        self.transport.start(self.pdu_received)
+
+    def stop(self) -> None:
+        """Set the kill flag, send sentinels, and join both threads."""
+        if not self._started:
+            return
+        self._started = False
+        self._event_thread.kill = True
+        self._message_thread.kill = True
+        self._event_queue.put(("stop",))
+        self._messages_to_user_queue.put(0)
+        self._event_thread.join()
+        self._message_thread.join()
+        # Cancel and join every pending file-data pacing timer (issue #31) so
+        # none fires after shutdown to push onto the drained queue or leave an
+        # unjoined thread. Done after the event thread is joined, so no new
+        # pacing timer can be armed here.
+        with self._pacing_lock:
+            pending = list(self._pacing_timers)
+            self._pacing_timers.clear()
+        for timer in pending:
+            timer.cancel()
+            timer.join(timeout=1)
+        # Cancel every outstanding wall-clock timer so no timer thread leaks
+        # past shutdown (design D6 / issue #17). Done after the event thread is
+        # joined so no start/cancel can race an in-flight timer here.
+        self._timer_service.stop()
+        # Join any in-flight checksum worker so none leaks past shutdown
+        # (design R1 / issue #21). After the event thread is joined no new
+        # RequestChecksum can be issued, so this drains the last workers.
+        self._checksum_service.stop()
+
+    def _increment_transaction_seq_counter(self):
+        with self._seq_lock:
+            self._transaction_seq_counter += 1
+            return self._transaction_seq_counter
+
+    def _invoke_callback(self, cb, *args):
+        if cb is None:
+            return
+        try:
+            cb(*args)
+        except Exception:
+            logger.exception("Unhandled exception in callback")
+
+    def trigger_event(self, event, pdu=None):
+        if event.type == EventType.E1_SEND_FILE_DATA:
+            delay = self._transaction_inter_pdu_delays.get(
+                event.transaction.id, self.inter_pdu_delay
+            )
+            # Backpressure-aware rescheduling (design R4 / issue #20). The pure
+            # file-data pump re-emits E1_SEND_FILE_DATA every step even when the
+            # transport could not accept a segment. Left
+            # unchecked, an unwritable link would spin the event thread at 100%
+            # CPU re-servicing E1s that send nothing. Here — the one place that
+            # owns the E1 re-enqueue timing — we detect an unready transport and
+            # apply a minimum yield so the pump idles instead of busy-spinning.
+            # FIFO re-enqueue already gives inter-transaction fairness (design
+            # D8); this only fixes the CPU spin.
+            if delay <= 0 and not self._transport_ready():
+                delay = self._BACKPRESSURE_YIELD
+            if delay > 0:
+                self._schedule_paced_enqueue(delay, [event, pdu])
+                return
+        self._event_queue.put([event, pdu])
+
+    def _schedule_paced_enqueue(self, delay, item):
+        """Enqueue ``item`` after ``delay`` on a tracked timer (issue #31).
+
+        The timer is registered before it starts and self-removes when it fires,
+        so a pending pacing timer is visible to ``stop()`` (which cancels and
+        joins every one) and a timer that fires normally does not accumulate.
+        """
+        holder = {}
+
+        def _fire():
+            with self._pacing_lock:
+                self._pacing_timers.discard(holder["timer"])
+            self._event_queue.put(item)
+
+        timer = threading.Timer(delay, _fire)
+        holder["timer"] = timer
+        with self._pacing_lock:
+            self._pacing_timers.add(timer)
+        timer.start()
+
+    def _transport_ready(self):
+        """Best-effort local transport writability check (never raises)."""
+        is_ready = getattr(self.transport, "is_ready", None)
+        if is_ready is None:
+            return True
+        try:
+            return is_ready()
+        except Exception:
+            return True
+
+    def _get_remote_config(self, destination_entity_id):
+        return self._remote_entity_configs.get(destination_entity_id)
+
+    def _resolve_id(self, transaction_id):
+        if isinstance(transaction_id, TransactionHandle):
+            return transaction_id.id
+        return transaction_id
+
+    def is_complete(self, transaction_id) -> bool:
+        tid = self._resolve_id(transaction_id)
+        evt = self._completion_events.get(tid)
+        if evt is None:
+            # No record of this transaction — treat as complete
+            return True
+        return evt.is_set()
+
+    def _reap_expired_machines(self):
+        now = time.monotonic()
+        expired = [
+            tid
+            for tid, ts in list(self._completion_times.items())
+            if now - ts >= self.completed_transaction_ttl
+        ]
+        for tid in expired:
+            self.machines.pop(tid, None)
+            self._completion_times.pop(tid, None)
+            self._transaction_inter_pdu_delays.pop(tid, None)
+            self._completion_events.pop(tid, None)
+            # Close and forget any file handle the shell held for a reaped
+            # transaction (design D10). No-op for a transaction that never opened
+            # a file.
+            self._file_table.cleanup(tid)
+            # Drop any outstanding wall-clock timers for the reaped transaction
+            # so no timer thread outlives it (design D6 / issue #17).
+            self._timer_service.cancel_all(tid)
+
+    def _event_handler(self):
+        thread = threading.current_thread()
+        while not thread.kill:
+            item = None
+            try:
+                item = self._event_queue.get(timeout=1)
+            except queue.Empty:
+                self._reap_expired_machines()
+                continue
+            if thread.kill:
+                break
+            try:
+                if isinstance(item, tuple):
+                    self._handle_control_message(item)
+                else:
+                    # Normal [event, pdu] from trigger_event() or timers
+                    event, pdu = item
+                    self._dispatch_event(event, pdu)
+            except Exception:
+                logger.exception("Unhandled exception in event handler")
+            self._reap_expired_machines()
+
+    def _dispatch_event(self, event, pdu):
+        machine = self.machines.get(event.transaction.id)
+        if not machine:
+            return
+        # The pure machine has a single input door and reads any inbound PDU off
+        # ``event.pdu``. The Dispatcher walks its returned output list (execute
+        # effects inline, re-enqueue internal events) and reports completion via
+        # _on_pure_machine_complete.
+        event.pdu = pdu
+        self._dispatcher.dispatch(machine, event)
+
+    def _on_pure_machine_complete(self, tid):
+        """Mark a pure-machine transaction complete (called by the Dispatcher)."""
+        if tid not in self._completion_times:
+            self._completion_times[tid] = time.monotonic()
+        # Cancel any armed timers immediately on completion rather than waiting
+        # for the TTL reap: an ACK/NAK/inactivity timer that fires into an
+        # already-completed machine would inject a stale event. ``cancel_all``
+        # on an already-empty tid is a safe no-op, so this never double-cancels
+        # harmfully with the reap path (which also calls ``cancel_all``).
+        self._timer_service.cancel_all(tid)
+        ce = self._completion_events.get(tid)
+        if ce is not None:
+            ce.set()
+
+    def _handle_control_message(self, item):
+        tag = item[0]
+
+        if tag == "stop":
+            return
+
+        elif tag == "pdu_raw":
+            _, data = item
+            try:
+                pdu = self._get_pdu_object(data)
+            except Exception:
+                logger.exception("Failed to decode incoming PDU")
+                return
+            mode = pdu.pdu_header.transmission_mode
+            direction = pdu.pdu_header.direction
+            transaction_id = pdu.pdu_header.transaction_id
+            existing = self.machines.get(transaction_id)
+            if existing and existing.transmission_mode == mode:
+                if existing.state is not MachineState.COMPLETED:
+                    self._send_pdu_to_state_machine(existing, pdu)
+                else:
+                    del self.machines[transaction_id]
+                    self._completion_times.pop(transaction_id, None)
+                    ce = self._completion_events.pop(transaction_id, None)
+                    if ce is not None:
+                        ce.set()
+                    self._run_action_for_incoming_pdu(
+                        mode, direction, transaction_id, pdu
+                    )
+            else:
+                self._run_action_for_incoming_pdu(mode, direction, transaction_id, pdu)
+
+            # If handling this PDU left no live machine owning the transaction,
+            # nothing will ever drive it to completion. ``pdu_received`` pre-
+            # registers a completion event for every inbound PDU (so is_complete
+            # is False while it is queued), but a *stateless* response — e.g.
+            # Ack-ing a Finished-cancel that a peer legitimately retransmits after
+            # we already completed and reaped (issue #23) — would otherwise leave
+            # that freshly-created event unset forever, flipping is_complete back
+            # to False. Mark it complete: no owner means done.
+            if transaction_id not in self.machines:
+                ce = self._completion_events.get(transaction_id)
+                if ce is not None:
+                    ce.set()
+
+        elif tag == "cancel_tid":
+            _, tid = item
+            machine = self.machines.get(tid)
+            if machine:
+                self._dispatch_event(
+                    Event(machine.transaction, EventType.E33_RECEIVED_CANCEL_REQUEST),
+                    None,
+                )
+
+        elif tag == "suspend_tid":
+            _, tid = item
+            machine = self.machines.get(tid)
+            if machine:
+                self._dispatch_event(
+                    Event(machine.transaction, EventType.E31_RECEIVED_SUSPEND_REQUEST),
+                    None,
+                )
+
+        elif tag == "resume_tid":
+            _, tid = item
+            machine = self.machines.get(tid)
+            if machine:
+                self._dispatch_event(
+                    Event(machine.transaction, EventType.E32_RECEIVED_RESUME_REQUEST),
+                    None,
+                )
+
+        elif tag == "report_tid":
+            _, tid = item
+            machine = self.machines.get(tid)
+            if machine:
+                self._dispatch_event(
+                    Event(machine.transaction, EventType.E34_RECEIVED_REPORT_REQUEST),
+                    None,
+                )
+
+        elif tag == "freeze_entity":
+            _, receiving_entity_id = item
+            for transaction_id, machine in list(self.machines.items()):
+                if transaction_id[0] == self.entity_id:
+                    if machine.transaction.destination_entity_id == receiving_entity_id:
+                        self._dispatch_event(
+                            Event(machine.transaction, EventType.E40_RECEIVED_FREEZE),
+                            None,
+                        )
+
+        elif tag == "thaw_entity":
+            _, receiving_entity_id = item
+            for transaction_id, machine in list(self.machines.items()):
+                if transaction_id[0] == self.entity_id:
+                    if machine.transaction.destination_entity_id == receiving_entity_id:
+                        self._dispatch_event(
+                            Event(machine.transaction, EventType.E41_RECEIVED_THAW),
+                            None,
+                        )
+
+    def _message_handler(self):
+        thread = threading.current_thread()
+        while not thread.kill:
+            try:
+                message = self._messages_to_user_queue.get(timeout=1)
+                if thread.kill:
+                    break
+                logger.info("Processing user message %s" % str(message))
+                self.process_user_message(message)
+            except queue.Empty:
+                pass
+            except Exception:
+                logger.exception("Unhandled exception in message handler")
+
+    """ CFDP service requests """
+
+    def put(
+        self,
+        destination_id,
+        source_filename=None,
+        destination_filename=None,
+        segmentation_control=None,  # not implemented
+        fault_handler_overrides=None,
+        flow_label=None,  # not implemented
+        transmission_mode=TransmissionMode.ACKNOWLEDGED,
+        closure_requested=False,  # not implemented
+        messages_to_user=None,
+        filestore_requests=None,
+        checksum_type=ChecksumType.MODULAR,
+        maximum_file_segment_length: int | None = None,
+    ) -> TransactionHandle:
+        """Initiate a file-delivery transaction.
+
+        Parameters
+        ----------
+        destination_id : int
+            Entity ID of the receiving entity.
+        source_filename : str or None
+            VFS path of the file to send. ``None`` sends a metadata-only PDU.
+        destination_filename : str or None
+            VFS path at the receiver where the file will be written.
+        transmission_mode : TransmissionMode
+            ``ACKNOWLEDGED`` (Class 2, default) or ``UNACKNOWLEDGED`` (Class 1).
+        checksum_type : ChecksumType
+            Checksum algorithm to use (default: MODULAR).
+        messages_to_user : list or None
+            Optional TLV messages to include in the Metadata PDU.
+        filestore_requests : list or None
+            Optional filestore-request TLVs.
+        maximum_file_segment_length : int or None
+            Override the entity-level segment length for this transaction.
+        """
+        if closure_requested:
+            raise NotImplementedError("closure_requested is not yet implemented")
+        if flow_label:
+            raise NotImplementedError("flow_label is not yet implemented")
+        if segmentation_control:
+            raise NotImplementedError("segmentation_control is not yet implemented")
+
+        seq_number = self._increment_transaction_seq_counter()
+
+        remote_cfg = self._get_remote_config(destination_id)
+        effective_delay = (
+            remote_cfg.inter_pdu_delay
+            if remote_cfg is not None and remote_cfg.inter_pdu_delay is not None
+            else self.inter_pdu_delay
+        )
+
+        # Build a pure sender via the registry (which folds config into a frozen
+        # snapshot and injects the query port). Both Class-1 (UNACKNOWLEDGED) and
+        # Class-2 (ACKNOWLEDGED) route here (issues #16 / #20).
+        resolved_segment_length = (
+            maximum_file_segment_length
+            if maximum_file_segment_length
+            else self.maximum_file_segment_length
+        )
+        machine, transaction = self._machine_registry.create_sender(
+            seq_number=seq_number,
+            destination_id=destination_id,
+            source_filename=source_filename,
+            destination_filename=destination_filename,
+            checksum_type=checksum_type,
+            transmission_mode=transmission_mode,
+            maximum_file_segment_length=resolved_segment_length,
+            messages_to_user=messages_to_user,
+            filestore_requests=filestore_requests,
+            fault_handler_overrides=fault_handler_overrides,
+            remote_config=remote_cfg,
+        )
+        self._completion_events[transaction.id] = threading.Event()
+        self._transaction_inter_pdu_delays[transaction.id] = effective_delay
+        self.trigger_event(Event(transaction, EventType.E0_ENTERED_STATE))
+        self.trigger_event(Event(transaction, EventType.E30_RECEIVED_PUT_REQUEST))
+        return TransactionHandle(self, transaction.id)
+
+    def cancel(self, transaction_id: Any) -> None:
+        self._event_queue.put(("cancel_tid", self._resolve_id(transaction_id)))
+
+    def suspend(self, transaction_id: Any) -> None:
+        self._event_queue.put(("suspend_tid", self._resolve_id(transaction_id)))
+
+    def resume(self, transaction_id: Any) -> None:
+        self._event_queue.put(("resume_tid", self._resolve_id(transaction_id)))
+
+    def report(self, transaction_id: Any) -> None:
+        self._event_queue.put(("report_tid", self._resolve_id(transaction_id)))
+
+    """ CFDP indication dispatch — called from machine base class """
+
+    def _as_handle(self, transaction_id):
+        if isinstance(transaction_id, TransactionHandle):
+            return transaction_id
+        return TransactionHandle(self, transaction_id)
+
+    def _indication_transaction(self, transaction_id):
+        logger.info("[%s] Transaction indication" % str(transaction_id))
+
+    def _indication_eof_sent(self, transaction_id):
+        logger.info("[%s] EOF sent indication" % str(transaction_id))
+        self._invoke_callback(self.on_eof_sent, self._as_handle(transaction_id))
+
+    def _indication_transaction_finished(
+        self,
+        transaction_id,
+        condition_code,
+        file_status,
+        delivery_code,
+        filestore_responses=None,
+        status_report=None,
+    ):
+        logger.info("[%s] Transaction finished indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_transaction_finished,
+            self._as_handle(transaction_id),
+            condition_code,
+            file_status,
+            delivery_code,
+            filestore_responses,
+            status_report,
+        )
+
+    def _indication_metadata_received(
+        self,
+        transaction_id,
+        source_entity_id,
+        file_size=None,
+        source_filename=None,
+        destination_filename=None,
+        messages_to_user=None,
+    ):
+        logger.info(
+            "[%s] Metadata received indication (%s bytes)"
+            % (str(transaction_id), str(file_size))
+        )
+        self._invoke_callback(
+            self.on_metadata_received,
+            self._as_handle(transaction_id),
+            source_entity_id,
+            file_size,
+            source_filename,
+            destination_filename,
+            messages_to_user,
+        )
+
+    def _indication_filesegment_received(self, transaction_id, offset, length):
+        logger.info(
+            "[%s] Filesegment received indication (offset %s, length %s)"
+            % (transaction_id, offset, length)
+        )
+        self._invoke_callback(
+            self.on_filesegment_received,
+            self._as_handle(transaction_id),
+            offset,
+            length,
+        )
+
+    def _indication_suspended(self, transaction_id, condition_code):
+        logger.info("[%s] Suspended indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_suspended, self._as_handle(transaction_id), condition_code
+        )
+
+    def _indication_resumed(self, transaction_id, progress):
+        logger.info("[%s] Resumed indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_resumed, self._as_handle(transaction_id), progress
+        )
+
+    def _indication_report(self, transaction_id, status_report):
+        logger.info("[%s] Report indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_report, self._as_handle(transaction_id), status_report
+        )
+
+    def _indication_fault(self, transaction_id, condition_code, progress):
+        logger.info("[%s] Fault indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_fault, self._as_handle(transaction_id), condition_code, progress
+        )
+
+    def _indication_abandoned(self, transaction_id, condition_code, progress):
+        logger.info("[%s] Abandoned indication" % str(transaction_id))
+        self._invoke_callback(
+            self.on_abandoned, self._as_handle(transaction_id), condition_code, progress
+        )
+
+    def _indication_eof_received(self, transaction_id):
+        logger.info("[%s] EOF received indication" % str(transaction_id))
+        self._invoke_callback(self.on_eof_received, self._as_handle(transaction_id))
+
+    """ Link state procedures """
+
+    def freeze(self, receiving_entity_id) -> None:
+        self._event_queue.put(("freeze_entity", receiving_entity_id))
+
+    def thaw(self, receiving_entity_id) -> None:
+        self._event_queue.put(("thaw_entity", receiving_entity_id))
+
+    def pdu_received(self, data) -> None:
+        """Queue raw PDU bytes for processing on the event thread (CCSDS 720.2-G-3 §5.4).
+
+        Pre-creates a completion event so is_complete() returns False (not True)
+        for transactions that are queued but not yet processed.
+        """
+        try:
+            pdu_header = PduHeader.decode(data)
+            tid = pdu_header.transaction_id
+            self._completion_events.setdefault(tid, threading.Event())
+        except Exception:
+            # A header we cannot even decode enough to key a completion event
+            # (truncated/corrupt bytes). Processing still enqueues the raw PDU
+            # below, where _get_pdu_object surfaces the decode failure; this
+            # pre-registration is best-effort, so log and carry on rather than
+            # dropping the PDU silently.
+            logger.debug("Could not pre-register completion event for incoming PDU")
+        self._event_queue.put(("pdu_raw", data))
+
+    def _get_pdu_object(self, raw_pdu):
+        "Take the raw input and return proper PDU object"
+
+        pdu_header = PduHeader.decode(raw_pdu)
+
+        # determine type of PDU
+        if pdu_header.pdu_type == PduTypeCode.FILE_DATA:
+            pdu = FiledataPdu.decode(raw_pdu)
+
+        elif pdu_header.pdu_type == PduTypeCode.FILE_DIRECTIVE:
+            code = raw_pdu[len(pdu_header)]
+
+            if code == DirectiveCode.EOF:
+                pdu = EofPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.FINISHED:
+                pdu = FinishedPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.ACK:
+                pdu = AckPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.METADATA:
+                pdu = MetadataPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.NAK:
+                pdu = NakPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.PROMPT:
+                pdu = PromptPdu.decode(raw_pdu)
+
+            elif code == DirectiveCode.KEEP_ALIVE:
+                pdu = KeepAlivePdu.decode(raw_pdu)
+
+            else:
+                raise ValueError(f"unknown file-directive code: {code!r}")
+
+        else:
+            raise ValueError(f"unknown PDU type: {pdu_header.pdu_type!r}")
+
+        return pdu
+
+    def _send_pdu_to_state_machine(self, machine, pdu):
+        if isinstance(pdu, MetadataPdu):
+            self.trigger_event(
+                Event(machine.transaction, EventType.E10_RECEIVED_METADATA), pdu
+            )
+
+        elif isinstance(pdu, FiledataPdu):
+            self.trigger_event(
+                Event(machine.transaction, EventType.E11_RECEIVED_FILEDATA), pdu
+            )
+
+        elif isinstance(pdu, EofPdu):
+            if pdu.condition_code == ConditionCode.NO_ERROR:
+                self.trigger_event(
+                    Event(machine.transaction, EventType.E12_RECEIVED_EOF_NO_ERROR), pdu
+                )
+            else:
+                self.trigger_event(
+                    Event(machine.transaction, EventType.E13_RECEIVED_EOF_CANCEL), pdu
+                )
+
+        elif isinstance(pdu, AckPdu):
+            if pdu.directive_code_ack == DirectiveCode.EOF:
+                self.trigger_event(
+                    Event(machine.transaction, EventType.E14_RECEIVED_ACK_EOF), pdu
+                )
+            elif pdu.directive_code_ack == DirectiveCode.FINISHED:
+                self.trigger_event(
+                    Event(machine.transaction, EventType.E18_RECEIVED_ACK_FINISHED), pdu
+                )
+            else:
+                raise NotImplementedError
+
+        elif isinstance(pdu, FinishedPdu):
+            if pdu.condition_code == ConditionCode.NO_ERROR:
+                self.trigger_event(
+                    Event(
+                        machine.transaction, EventType.E16_RECEIVED_FINISHED_NO_ERROR
+                    ),
+                    pdu,
+                )
+            else:
+                self.trigger_event(
+                    Event(machine.transaction, EventType.E17_RECEIVED_FINISHED_CANCEL),
+                    pdu,
+                )
+
+        elif isinstance(pdu, NakPdu):
+            self.trigger_event(
+                Event(machine.transaction, EventType.E15_RECEIVED_NAK), pdu
+            )
+
+        else:
+            raise TypeError(f"unroutable PDU type: {type(pdu).__name__}")
+
+    def _run_action_for_incoming_pdu(self, mode, direction, transaction_id, pdu):
+        """See CCSDS 720.2-G-3, Chapter 5.4, Table 5-5"""
+
+        if (
+            direction == Direction.TOWARD_SENDER
+            and mode == TransmissionMode.UNACKNOWLEDGED
+        ):
+            # ignore
+            pass
+
+        elif (
+            direction == Direction.TOWARD_SENDER
+            and mode == TransmissionMode.ACKNOWLEDGED
+        ):
+            if isinstance(pdu, FinishedPdu):
+                logger.debug(f"[{transaction_id}] Send Ack Finished")
+                ack_pdu = AckPdu(
+                    direction=Direction.TOWARD_RECEIVER,
+                    transmission_mode=pdu.pdu_header.transmission_mode,
+                    source_entity_id=pdu.pdu_header.source_entity_id,
+                    transaction_seq_number=pdu.pdu_header.transaction_seq_number,
+                    destination_entity_id=pdu.pdu_header.destination_entity_id,
+                    #
+                    directive_code_ack=DirectiveCode.FINISHED,
+                    directive_subtype_code=DirectiveSubTypeCode.ACK_FINISHED,
+                    condition_code=ConditionCode.NO_ERROR,
+                    transaction_status=TransactionStatus.UNDEFINED,
+                )
+                self.transport.send(ack_pdu.encode())
+
+        elif direction == Direction.TOWARD_RECEIVER:
+            # start a new state machine
+            if (
+                isinstance(pdu, MetadataPdu)
+                or isinstance(pdu, FiledataPdu)
+                or isinstance(pdu, EofPdu)
+            ):
+                # Build a pure receiver via the registry. It picks Receiver1
+                # (UNACKNOWLEDGED) or Receiver2 (ACKNOWLEDGED) off the inbound PDU
+                # header (issues #16 / #20).
+                remote_cfg = self._get_remote_config(pdu.pdu_header.source_entity_id)
+                machine, transaction = self._machine_registry.create_receiver(
+                    pdu, remote_config=remote_cfg
+                )
+                self._completion_events.setdefault(transaction.id, threading.Event())
+                self.trigger_event(Event(transaction, EventType.E0_ENTERED_STATE))
+                self._send_pdu_to_state_machine(machine, pdu)
+
+    def process_user_message(self, message):
+        meta_process_user_message(self, message)