pycfdp 0.2.2__py3-none-any.whl

cfdp/pure/machines/sender1.py

@@ -0,0 +1,400 @@
+"""Pure Class-1 (unacknowledged) sender machine (issue #14).
+
+A pure function of ``(state, event)`` returning an ordered ``list[Output]``. It
+obeys the machine contract:
+
+    Sender1(transaction, config, query_port)
+    update_state(event) -> list[Output]
+
+No ``kernel`` reference, no threads, no open file descriptors, no wall clock.
+The machine builds PDUs itself (pure) and returns them in :class:`SendPdu`; it
+reads file bytes, size, and transport readiness through the injected
+:class:`~cfdp.pure.query_port.QueryPort`, synchronously (design D3/D5). The EOF
+*checksum* is computed asynchronously (issue #21): the machine emits
+:class:`RequestChecksum` and sends the EOF in the ``E42_CHECKSUM_READY``
+continuation so a large-file checksum never blocks the dispatcher (design R1).
+File open/close is a returned effect (:class:`OpenSource` / :class:`CloseFile`);
+the shell owns the handle (design D10).
+
+Class 1 has no timers and no NAKs, so this machine emits no timer effects.
+
+Verified by differential trace testing against frozen golden fixtures captured
+from the pre-cutover implementation — see ``tests/test_pure_sender1.py``.
+"""
+
+from typing import Any
+
+from cfdp.constants import (
+    ConditionCode,
+    DeliveryCode,
+    Direction,
+    FileStatus,
+    MachineState,
+    TransmissionMode,
+)
+from cfdp.event import Event, EventType
+from cfdp.pdu import EofPdu, FiledataPdu, MetadataPdu
+
+from .. import indications
+from ..config import TransactionConfig
+from ..outputs import (
+    CloseFile,
+    InternalEvent,
+    OpenSource,
+    Output,
+    RequestChecksum,
+    SendPdu,
+)
+from ..query_port import QueryPort
+from ..transaction import Transaction
+
+
+class Sender1:
+    """Pure implementation of the Class 1 (unacknowledged transfer) sender."""
+
+    def __init__(
+        self,
+        transaction: Transaction,
+        config: TransactionConfig,
+        query_port: QueryPort,
+        *,
+        messages_to_user: list | None = None,
+        filestore_requests: list | None = None,
+    ) -> None:
+        self.transaction = transaction
+        self.config = config
+        self.query_port = query_port
+
+        # Request payload arrives with the creating put request, not on the
+        # frozen Transaction descriptor (design D3, "Data model"). Class-1
+        # F-series scenarios carry neither, so both default to None.
+        self.messages_to_user = messages_to_user
+        self.filestore_requests = filestore_requests
+
+        self.transmission_mode = TransmissionMode.UNACKNOWLEDGED
+        self.state = MachineState.SEND_METADATA
+
+        # Runtime state (plain data; formerly split across Machine + Transaction).
+        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.suspended = False
+        self.file_status = FileStatus.UNREPORTED
+        self.filestore_responses = None
+        self.status_report = None
+
+        # Send-side file position (formerly Transaction._file_pos / _file_size).
+        self._file_pos = 0
+        self._file_size = None
+        # Whether a source file handle is open (formerly transaction.file_handle
+        # truthiness). shutdown() closes the handle only if one was opened, so a
+        # metadata-only transfer emits no CloseFile.
+        self._source_open = False
+        # The Class-1 sender never advances progress (only the receive side does),
+        # so resumed/abandoned indications always report 0 — matching the old
+        # machine's Transaction.get_progress().
+        self._progress = 0
+        # Async-checksum cache (issue #21). ``None`` until the shell computes the
+        # whole-file checksum and injects E42_CHECKSUM_READY. Cached exactly like
+        # the old ``Transaction.get_file_checksum`` memoized it, so every EOF
+        # (first send, cancellation) reuses the one value. ``_pending_eof`` holds
+        # the "finish sending the EOF" continuation deferred until the value
+        # arrives; ``None`` means nothing is waiting.
+        self._checksum = None
+        self._pending_eof = 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-1.
+
+        Returns the ordered list of :class:`~cfdp.pure.outputs.Output` produced
+        by handling ``event``.
+        """
+        self._out: list[Output] = []
+
+        if self.state == MachineState.SEND_METADATA:
+            self._update_send_metadata(event)
+        elif self.state == MachineState.SEND_FILE:
+            self._update_send_file(event)
+
+        out, self._out = self._out, []
+        return out
+
+    # -- SEND_METADATA state ----------------------------------------------- #
+
+    def _update_send_metadata(self, event):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self._initialize()
+
+        elif event.type == EventType.E30_RECEIVED_PUT_REQUEST:
+            self._issue_transaction_indication()
+            self._send_metadata()
+            if self._is_file_transfer():
+                self.state = MachineState.SEND_FILE
+                self._emit(InternalEvent(EventType.E0_ENTERED_STATE))
+            else:
+                self._send_eof()
+                self._issue_eof_sent_indication()
+                self._issue_transaction_finished_indication()
+                self._shutdown()
+
+    # -- SEND_FILE state --------------------------------------------------- #
+
+    def _update_send_file(self, event):
+        if event.type == EventType.E0_ENTERED_STATE:
+            self._open_sourcefile()
+            self._emit(InternalEvent(EventType.E1_SEND_FILE_DATA))
+
+        elif event.type == EventType.E1_SEND_FILE_DATA:
+            if not self.suspended and not self.frozen:
+                if self._is_comm_layer_ready():
+                    self._send_file_data()
+                    if self._is_entire_file_sent():
+                        self._begin_eof(self._complete_after_eof)
+                        return  # stop here
+                self._emit(InternalEvent(EventType.E1_SEND_FILE_DATA))
+
+        elif event.type == EventType.E2_ABANDON_TRANSACTION:
+            self._issue_abandoned_indication()
+            self._shutdown()
+
+        elif event.type == EventType.E3_NOTICE_OF_CANCELLATION:
+            self._begin_eof(self._cancel_after_eof)
+
+        elif event.type == EventType.E42_CHECKSUM_READY:
+            self._checksum = event.checksum
+            self._resume_eof()
+
+        elif event.type == EventType.E4_NOTICE_OF_SUSPENSION:
+            if not self.suspended:
+                self._issue_suspended_indication()
+                self.suspended = True
+
+        elif event.type == EventType.E31_RECEIVED_SUSPEND_REQUEST:
+            self._emit(InternalEvent(EventType.E4_NOTICE_OF_SUSPENSION))
+
+        elif event.type == EventType.E32_RECEIVED_RESUME_REQUEST:
+            if self.suspended:
+                self._issue_resumed_indication()
+                self.suspended = False
+                if not self.frozen:
+                    self._emit(InternalEvent(EventType.E1_SEND_FILE_DATA))
+
+        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()
+
+        elif event.type == EventType.E40_RECEIVED_FREEZE:
+            self.frozen = True
+
+        elif event.type == EventType.E41_RECEIVED_THAW:
+            if self.frozen:
+                self.frozen = False
+                if not self.suspended:
+                    self._emit(InternalEvent(EventType.E1_SEND_FILE_DATA))
+
+    # -- output helper ----------------------------------------------------- #
+
+    def _emit(self, output):
+        self._out.append(output)
+
+    # -- queries (predicates over pure state / the query port) ------------- #
+
+    def _is_file_transfer(self):
+        return bool(
+            self.transaction.source_filename
+            and len(self.transaction.source_filename) > 0
+        )
+
+    def _is_comm_layer_ready(self):
+        return self.query_port.transport_ready()
+
+    def _is_entire_file_sent(self):
+        return self._file_pos >= self._file_size_bytes()
+
+    def _file_size_bytes(self):
+        if self._file_size is None:
+            if self.transaction.source_filename:
+                self._file_size = self.query_port.size(self.transaction.source_filename)
+            else:
+                self._file_size = 0
+        return self._file_size
+
+    # -- effects: file lifecycle ------------------------------------------- #
+
+    def _open_sourcefile(self):
+        # The old machine runs the filestore fault handler if the source file is
+        # missing; Class-1 F-series scenarios only ever send existing files, so
+        # the happy path is a single OpenSource. (Fault handling on a missing
+        # source is Class-2 territory / a later increment.)
+        self._emit(OpenSource())
+        self._source_open = True
+
+    def _shutdown(self):
+        # Mirror Machine.shutdown: close the handle only if one was opened.
+        if self._source_open:
+            self._emit(CloseFile())
+            self._source_open = False
+        self.state = MachineState.COMPLETED
+
+    # -- effects: PDU builders (pure) -------------------------------------- #
+
+    def _header_fields(self) -> dict[str, Any]:
+        """The identity fields shared by every PDU this machine sends.
+
+        Direction, transmission mode, and the three transaction-identity fields
+        are the same on every outbound PDU; naming them once keeps each PDU
+        builder to only its distinguishing fields (splat with ``**``).
+        """
+        return {
+            "direction": Direction.TOWARD_RECEIVER,
+            "transmission_mode": self.transmission_mode,
+            "source_entity_id": self.transaction.source_entity_id,
+            "transaction_seq_number": self.transaction.seq_number,
+            "destination_entity_id": self.transaction.destination_entity_id,
+        }
+
+    def _send_metadata(self):
+        pdu = MetadataPdu(
+            **self._header_fields(),
+            file_size=self._file_size_bytes(),
+            source_filename=self.transaction.source_filename,
+            destination_filename=self.transaction.destination_filename,
+            checksum_type=self.transaction.checksum_type,
+            filestore_requests=self.filestore_requests,
+            messages_to_user=self.messages_to_user,
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    def _send_file_data(self):
+        offset = self._file_pos
+        _, data = self.query_port.read_segment(
+            offset, self.config.maximum_file_segment_length
+        )
+        # Advance by the bytes actually read, not the requested segment length: a
+        # backend that returns a short read for a non-final segment must not let
+        # _file_pos overshoot the real data end (which _is_entire_file_sent()'s
+        # >= would read as "done" and send EOF on a truncated transfer). For the
+        # native filestore every non-final read is full-length, so the emitted
+        # segment offsets are unchanged.
+        self._file_pos += len(data)
+        pdu = FiledataPdu(
+            **self._header_fields(),
+            segment_offset=offset,
+            file_data=data,
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    # -- async-checksum-gated EOF (issue #21) ------------------------------ #
+
+    def _begin_eof(self, continuation):
+        """Send the EOF, then run ``continuation`` — deferring on the checksum.
+
+        For a file transfer the EOF carries the whole-file checksum. Rather than
+        computing it synchronously on the event thread (design R1), the machine
+        emits :class:`RequestChecksum` and parks ``continuation`` until the shell
+        injects ``E42_CHECKSUM_READY``. A metadata-only transfer needs no real
+        checksum (value 0), so it proceeds immediately.
+        """
+        if self._is_file_transfer() and self._checksum is None:
+            if self._pending_eof is not None:
+                # A checksum request is already outstanding and we are being
+                # asked to send another EOF — the only re-entry is an E3
+                # cancellation, which includes the checksum-failure fallback
+                # where the shell injects E33 (not E42) because the computation
+                # raised. Do NOT re-park waiting for a second E42 that may never
+                # arrive: a Sender1 has no inactivity timer, so a missing event
+                # would strand the machine forever (defeating the issue #24
+                # "exactly one terminating event" guarantee). Resolve now with
+                # the best-available checksum (0 if it was never computed); a
+                # later E42, if any, finds nothing parked and no-ops.
+                self._pending_eof = None
+                self._send_eof()
+                continuation()
+                return
+            # First EOF: emit exactly one RequestChecksum and park until
+            # E42_CHECKSUM_READY arrives (a second request would spawn a
+            # duplicate worker and a redundant E42 — issue #21 review).
+            self._pending_eof = continuation
+            self._emit(RequestChecksum(checksum_type=self.transaction.checksum_type))
+            return
+        self._send_eof()
+        continuation()
+
+    def _resume_eof(self):
+        continuation, self._pending_eof = self._pending_eof, None
+        if continuation is None:
+            return
+        self._send_eof()
+        continuation()
+
+    def _complete_after_eof(self):
+        self._issue_eof_sent_indication()
+        self._issue_transaction_finished_indication()
+        self._shutdown()
+
+    def _cancel_after_eof(self):
+        self._issue_transaction_finished_indication()
+        self._shutdown()
+
+    def _send_eof(self):
+        pdu = EofPdu(
+            **self._header_fields(),
+            condition_code=self.condition_code,
+            file_checksum=self._file_checksum(),
+            file_size=self._file_size_bytes(),
+        )
+        self._emit(SendPdu(pdu=pdu))
+
+    def _file_checksum(self):
+        # The value is computed asynchronously (RequestChecksum -> E42) and
+        # cached; a metadata-only transfer has no file and checksums to 0.
+        if self.transaction.source_filename:
+            return self._checksum if self._checksum is not None else 0
+        return 0
+
+    # -- effects: indications ---------------------------------------------- #
+
+    def _issue_transaction_indication(self):
+        self._emit(indications.transaction(self.transaction.id))
+
+    def _issue_eof_sent_indication(self):
+        self._emit(indications.eof_sent(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_suspended_indication(self):
+        self._emit(indications.suspended(self.transaction.id, self.condition_code))
+
+    def _issue_resumed_indication(self):
+        self._emit(indications.resumed(self.transaction.id, self._progress))
+
+    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
+            )
+        )