pycfdp 0.2.2__py3-none-any.whl

cfdp/pure/machines/receiver1.py

@@ -0,0 +1,433 @@
+"""Pure Class-1 (unacknowledged) receiver machine (issue #15).
+
+A pure function of ``(state, event)`` returning an ordered ``list[Output]``. It
+obeys the machine contract:
+
+    Receiver1(transaction, config, query_port)
+    update_state(event) -> list[Output]
+
+No ``kernel`` reference, no threads, no open file descriptors, no wall clock.
+
+The receiver is **PDU-driven**: the triggering inbound PDU rides on the single
+input door as ``event.pdu`` (see :class:`cfdp.event.Event`), so the contract's
+one-door rule holds and no out-of-contract parameter is added. File handling is
+expressed purely as effects — :class:`OpenTemp`, :class:`WriteSegment`,
+:class:`Finalize`, :class:`CloseFile`. The temp-file *size* read-back is a
+synchronous :class:`~cfdp.pure.query_port.QueryPort` call, but *checksum*
+verification is asynchronous (issue #21): the machine emits
+:class:`RequestChecksum` and completes in the ``E42_CHECKSUM_READY`` continuation
+so a large-file checksum never blocks the dispatcher (design D3/D5/D10/R1). The
+machine holds positions and a received-segment map, never a file descriptor.
+
+Class 1 has no NAKs and only the inactivity timer, driven as
+:class:`StartTimer` effects.
+
+Verified by differential trace testing against frozen golden fixtures captured
+from the pre-cutover implementation — see ``tests/test_pure_receiver1.py``. In
+particular the pre-cutover machine closed the temp file **twice** on the happy
+EOF path (``close_tempfile`` then ``shutdown``); this machine reproduces both
+:class:`CloseFile` outputs on purpose (the second close is a no-op).
+"""
+
+from cfdp.constants import (
+    ConditionCode,
+    DeliveryCode,
+    FaultHandlerAction,
+    FileStatus,
+    MachineState,
+    TransmissionMode,
+)
+from cfdp.event import Event, EventType
+
+from .. import indications
+from ..config import TransactionConfig
+from ..outputs import (
+    CancelTimer,
+    CloseFile,
+    ExecuteFilestoreRequests,
+    Finalize,
+    InternalEvent,
+    OpenTemp,
+    Output,
+    PostUserMessage,
+    RequestChecksum,
+    StartTimer,
+    TimerKind,
+    WriteSegment,
+)
+from ..query_port import QueryPort
+from ..transaction import Transaction
+
+
+class Receiver1:
+    """Pure implementation of the Class 1 (unacknowledged transfer) receiver."""
+
+    def __init__(
+        self,
+        transaction: Transaction,
+        config: TransactionConfig,
+        query_port: QueryPort,
+    ) -> None:
+        self.transaction = transaction
+        self.config = config
+        self.query_port = query_port
+
+        self.transmission_mode = TransmissionMode.UNACKNOWLEDGED
+        self.state = MachineState.WAIT_FOR_MD
+
+        # Request payload received off the inbound Metadata PDU (design D3). The
+        # old machine stashes these on the mutable Transaction via
+        # process_metadata_options; here they are machine state.
+        self.filestore_requests = None
+        self.messages_to_user = None
+
+        self._initialize()
+
+    # -- state reset (mirrors Machine.initialize) -------------------------- #
+
+    def _initialize(self):
+        # as per CCSDS 720.2-G-3, Page 5-13, g)
+        self.condition_code = ConditionCode.NO_ERROR
+        self.delivery_code = DeliveryCode.DATA_INCOMPLETE
+        self.frozen = False
+        self.metadata_received = False
+        self.pdu_received = False
+        self.suspended = False
+        self.file_status = FileStatus.UNREPORTED
+        self.filestore_responses = None
+        self.status_report = None
+
+        self.received_file_size = 0
+        # Whether a temp file handle is open (formerly transaction.file_handle
+        # truthiness). shutdown() emits CloseFile only if one was opened.
+        self._temp_open = False
+        self.received_file_segments = {}
+        # Progress advances as segments arrive (formerly transaction._progress).
+        self._progress = 0
+        # Async-checksum verification (issue #21): the EOF-carried checksum to
+        # compare against, remembered across the RequestChecksum -> E42 hop while
+        # the shell computes the temp-file checksum off the event thread.
+        self._expected_checksum = None
+
+    # -- the single input door --------------------------------------------- #
+
+    def update_state(self, event: Event) -> list[Output]:
+        """See state table given in CCSDS 720.2-G-3, Table 5-2.
+
+        Returns the ordered list of :class:`~cfdp.pure.outputs.Output` produced
+        by handling ``event``. The triggering inbound PDU, if any, is read from
+        ``event.pdu``.
+        """
+        self._out: list[Output] = []
+        pdu = getattr(event, "pdu", None)
+
+        # as per CCSDS 720.2-G-3, 5.3.7: any inbound PDU restarts inactivity.
+        if pdu is not None:
+            self._restart_inactivity_timer()
+
+        if self.state == MachineState.WAIT_FOR_MD:
+            self._update_wait_for_md(event, pdu)
+        elif self.state == MachineState.WAIT_FOR_EOF:
+            self._update_wait_for_eof(event, pdu)
+
+        out, self._out = self._out, []
+        return out
+
+    # -- WAIT_FOR_MD state ------------------------------------------------- #
+
+    def _update_wait_for_md(self, event, pdu):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self._initialize()
+            self._restart_inactivity_timer()
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E10_RECEIVED_METADATA:
+            self._issue_metadata_received_indication(pdu.file_size)
+            if self._is_file_transfer():
+                self._open_tempfile()
+            self._process_metadata_options(pdu)
+            self.state = MachineState.WAIT_FOR_EOF
+
+        elif event.type == EventType.E12_RECEIVED_EOF_NO_ERROR:
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._restart_inactivity_timer()
+            self._fault_inactivity()
+
+        elif event.type == EventType.E33_RECEIVED_CANCEL_REQUEST:
+            self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+            self._emit(InternalEvent(EventType.E3_NOTICE_OF_CANCELLATION))
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+    # -- WAIT_FOR_EOF state ------------------------------------------------ #
+
+    def _update_wait_for_eof(self, event, pdu):
+        if event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E11_RECEIVED_FILEDATA:
+            self._issue_filesegment_received_indication(
+                pdu.segment_offset, len(pdu.file_data)
+            )
+            if self._is_file_transfer():
+                self._store_file_data(pdu)
+                self._update_received_file_size(pdu)
+
+        elif event.type == EventType.E12_RECEIVED_EOF_NO_ERROR:
+            self._issue_eof_received_indication()
+
+            if self._is_file_transfer():
+                if self._is_file_size_error(pdu.file_size):
+                    if not self._fault_file_size():
+                        self._close_tempfile()
+                        return
+                # Checksum verification is async (issue #21): remember the EOF's
+                # checksum, ask the shell to compute the temp-file checksum off
+                # the event thread, and finish in the E42 continuation.
+                self._expected_checksum = pdu.file_checksum
+                self._emit(
+                    RequestChecksum(
+                        checksum_type=self.transaction.checksum_type,
+                        from_temp_handle=True,
+                    )
+                )
+                return
+
+            if self.filestore_requests:
+                self._execute_filestore_requests()
+
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E42_CHECKSUM_READY:
+            self._finish_after_checksum(event.checksum)
+
+        elif event.type == EventType.E13_RECEIVED_EOF_CANCEL:
+            self.condition_code = pdu.condition_code
+            if pdu.fault_location is not None:
+                self.status_report = {"fault_location": pdu.fault_location}
+            self._issue_transaction_finished_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E27_INACTIVITY_TIMEOUT:
+            self._restart_inactivity_timer()
+            self._fault_inactivity()
+
+        elif event.type == EventType.E33_RECEIVED_CANCEL_REQUEST:
+            self.condition_code = ConditionCode.CANCEL_REQUEST_RECEIVED
+            self._emit(InternalEvent(EventType.E3_NOTICE_OF_CANCELLATION))
+
+        elif event.type == EventType.E34_RECEIVED_REPORT_REQUEST:
+            self._issue_report_indication()
+
+    # -- output helper ----------------------------------------------------- #
+
+    def _emit(self, output):
+        self._out.append(output)
+
+    # -- queries / predicates ---------------------------------------------- #
+
+    def _is_file_transfer(self):
+        return bool(
+            self.transaction.source_filename
+            and len(self.transaction.source_filename) > 0
+        )
+
+    def _is_file_size_error(self, file_size):
+        return self.received_file_size > file_size
+
+    def _is_file_checksum_failure(self, expected, calculated):
+        # ``calculated`` is the temp-file checksum computed asynchronously by the
+        # shell (issue #21) and delivered on E42_CHECKSUM_READY; ``expected`` is
+        # the EOF-carried value.
+        return calculated != expected
+
+    def _finish_after_checksum(self, calculated_checksum):
+        """E42 continuation: verify checksum, finalize, and finish (issue #21)."""
+        if self._is_file_checksum_failure(self._expected_checksum, calculated_checksum):
+            if not self._fault_file_checksum():
+                self._close_tempfile()
+                return
+
+        self.delivery_code = DeliveryCode.DATA_COMPLETE
+        self._copy_tempfile_to_destfile()
+        self._close_tempfile()
+        self.file_status = FileStatus.RETAINED_SUCCESSFULLY
+
+        if self.filestore_requests:
+            self._execute_filestore_requests()
+
+        self._issue_transaction_finished_indication()
+        self._shutdown()
+
+    # -- timer effects ----------------------------------------------------- #
+
+    def _restart_inactivity_timer(self):
+        # Mirror Machine.restart_inactivity_timer: only while not suspended.
+        if not self.suspended:
+            self._emit(
+                StartTimer(
+                    kind=TimerKind.INACTIVITY,
+                    interval=self.config.transaction_inactivity_limit,
+                )
+            )
+
+    # -- fault handling ---------------------------------------------------- #
+
+    def _fault_inactivity(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.INACTIVITY_DETECTED)
+        )
+
+    def _fault_file_size(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.FILE_SIZE_ERROR)
+        )
+
+    def _fault_file_checksum(self):
+        return self._run_fault_handler(
+            self.config.get_fault_handler(ConditionCode.FILE_CHECKSUM_FAILURE)
+        )
+
+    def _run_fault_handler(self, fault_handler):
+        """Return True if execution should continue (IGNORE), False otherwise."""
+        if fault_handler == FaultHandlerAction.CANCEL:
+            self._emit(InternalEvent(EventType.E33_RECEIVED_CANCEL_REQUEST))
+            return False
+        elif fault_handler == FaultHandlerAction.SUSPEND:
+            self._emit(InternalEvent(EventType.E31_RECEIVED_SUSPEND_REQUEST))
+            return False
+        elif fault_handler == FaultHandlerAction.IGNORE:
+            return True
+        elif fault_handler == FaultHandlerAction.ABANDON:
+            self._emit(InternalEvent(EventType.E2_ABANDON_TRANSACTION))
+            return False
+        else:
+            raise ValueError
+
+    # -- file lifecycle effects -------------------------------------------- #
+
+    def _open_tempfile(self):
+        self._emit(OpenTemp())
+        self._temp_open = True
+
+    def _store_file_data(self, pdu):
+        self._emit(WriteSegment(offset=pdu.segment_offset, data=bytes(pdu.file_data)))
+        self.received_file_segments[pdu.segment_offset] = len(pdu.file_data)
+
+    def _copy_tempfile_to_destfile(self):
+        # Class-1 Metadata always arrives first, so the frozen transaction has
+        # the destination filename; carry it explicitly so the effect is
+        # self-describing (and matches the recorder's normalized Finalize).
+        self._emit(Finalize(destination_filename=self.transaction.destination_filename))
+
+    def _close_tempfile(self):
+        # Mirror Machine.close_tempfile: it does NOT clear the handle, so the
+        # subsequent shutdown() sees a live handle and closes it a second time.
+        self._emit(CloseFile())
+
+    def _update_received_file_size(self, pdu):
+        new_size = pdu.segment_offset + len(pdu.file_data)
+        if self.received_file_size < new_size:
+            self.received_file_size = new_size
+            self._progress = new_size
+
+    def _process_metadata_options(self, pdu):
+        self.filestore_requests = pdu.filestore_requests
+        self.messages_to_user = pdu.messages_to_user
+        for message in self.messages_to_user or []:
+            message.originating_transaction = self.transaction
+            self._emit(PostUserMessage(message=message))
+
+    def _execute_filestore_requests(self):
+        # Filestore-request execution is a shell effect (design D3/D10): the
+        # machine carries the request TLVs but never touches the filestore. ``put``
+        # permits filestore requests in ANY transmission mode, so a Class-1
+        # Metadata can carry them (issue #27); emit the equivalent command for the
+        # EffectExecutor to run, mirroring Receiver2._execute_filestore_requests.
+        # Both call sites are guarded by ``if self.filestore_requests``, so this is
+        # a no-op (no effect) when the transfer carries none — the existing golden
+        # fixtures, which never carry filestore requests, are unchanged.
+        self._emit(ExecuteFilestoreRequests(requests=self.filestore_requests))
+
+    def _shutdown(self):
+        # Mirror Receiver1.shutdown: first super().shutdown() (base Machine)
+        # closes the handle only if one was opened — on the happy EOF path
+        # close_tempfile already emitted a CloseFile without clearing the handle,
+        # so this emits a second CloseFile, matching the old machine (the
+        # differential oracle). Then inactivity_timer.shutdown() cancels the
+        # inactivity timer, which the recording timer emits as
+        # CancelTimer(INACTIVITY) — always, regardless of whether a file was
+        # open.
+        if self._temp_open:
+            self._emit(CloseFile())
+            self._temp_open = False
+        self._emit(CancelTimer(kind=TimerKind.INACTIVITY))
+        self.state = MachineState.COMPLETED
+
+    # -- indications ------------------------------------------------------- #
+
+    def _issue_metadata_received_indication(self, file_size):
+        self._emit(
+            indications.metadata_received(
+                self.transaction.id,
+                self.transaction.source_entity_id,
+                file_size,
+                self.transaction.source_filename,
+                self.transaction.destination_filename,
+                self.messages_to_user,
+            )
+        )
+
+    def _issue_filesegment_received_indication(self, offset, length):
+        self._emit(
+            indications.filesegment_received(self.transaction.id, offset, length)
+        )
+
+    def _issue_eof_received_indication(self):
+        self._emit(indications.eof_received(self.transaction.id))
+
+    def _issue_transaction_finished_indication(self):
+        self._emit(
+            indications.transaction_finished(
+                self.transaction.id,
+                self.condition_code,
+                self.file_status,
+                self.delivery_code,
+                self.filestore_responses,
+                self.status_report,
+            )
+        )
+
+    def _issue_report_indication(self):
+        self._emit(indications.report(self.transaction.id, self.status_report))
+
+    def _issue_abandoned_indication(self):
+        self._emit(
+            indications.abandoned(
+                self.transaction.id, self.condition_code, self._progress
+            )
+        )