Receive pushed data into an archive through the Peer protocol

[bjester]

Overview

A disk connection receives a push through the Peer protocol and stores the data in the archive, as a morango server does. This issue is part of milestone M6 (disk connection).

Background & Motivation

The shared Peer* operations from #374 drive a peer only through the Peer protocol. The network connection answers the protocol with HTTP calls to a server. The disk connection must answer the same protocol, with the archive in the role of the server.

The parity rule requires that the archive holds the same state as a server that receives the same push. For this reason, the disk connection calls the same receiver functions that the server uses. It does not use separate write logic.

Design: spec. Plan: implementation plan, Task 23.

User Story

As a Kolibri developer,
I want a push over a disk connection to complete all transfer stages,
So that the exported archive holds the same records and counters as a server.

Description & Expected Outcomes

The disk connection implements the six Peer protocol methods. It rejects a pull, because Phase 1 supports export only.

When a transfer session is created, the disk connection applies the same scope checks as the server. The filter must be in the write scope of the client certificate and the read scope of the archive certificate. The connection records the filter in the manifest.

When an update asks for a later stage, the disk connection runs each stage step in order up to that stage. It stops at the first step that does not complete. The steps compute the archive FSIC, accept record chunks, and dequeue the records into the archive store.

The disk connection returns every result as a PeerTransferSession. All writes to the archive happen inside a transaction on the archive alias.

Deliverables & Contracts

The feature delivers these capabilities:

• create_transfer_session, get_transfer_session, update_transfer_session, close_transfer_session, push_record_chunk and pull_record_chunk on DiskSyncConnection, as spec §3.6 describes.
• An update to a later stage runs every skipped stage step in order.
• A push through the shared Peer* operations writes Store, RecordMaxCounter and DatabaseMaxCounter rows in the archive.

Acceptance Criteria

• create_transfer_session for a pull raises MorangoError.
• A filter outside the certificate scopes raises MorangoError.
• create_transfer_session sets the manifest filter.
• update_transfer_session(ts, transfer_stage="queuing") from initializing runs serializing and queuing, and returns stage queuing with status completed.
• push_record_chunk sets the stage to transferring and increases records_transferred by the chunk length.
• An update to dequeuing writes Store, RecordMaxCounter and DatabaseMaxCounter rows in the archive and increments the archive instance counter.
• Two calls to close_transfer_session do not raise.
• pull_record_chunk raises MorangoError.
• All archive writes pass inside assert_no_default_db_queries().

Technical Pointers & Architecture

• Target Components / Context: morango/sync/syncsession.py (DiskSyncConnection).
• Related Patterns: TransferSessionViewSet (morango/api/viewsets.py:319) and BufferViewSet (morango/api/viewsets.py:452) are the server behavior to mirror. The scope checks are at morango/api/viewsets.py:348-354.
• Data Model & Schema Considerations: No schema change.
• Resilience & Failure Modes: The disk connection runs synchronously. Each stage step either completes or raises. Errors must not be suppressed.

Notes & Tradeoffs

• Dependencies: Blocked by: Receiver helpers work against a chosen database #367 (receiver helpers take db), Network connection speaks the transport-neutral Peer protocol #371 (Peer protocol and PeerTransferSession), Start and close sync sessions with a disk connection #383 (disk connection lifecycle). Blocks: Prove that disk and network peers obey the same Peer protocol #385, Prove that an exported archive matches a network server #386.
• Kolibri companion changes: See spec §3.9. Kolibri routers must allow morango migrations on aliases that start with morango_archive_. Kolibri settings overrides must list the Peer* operations.
• Tradeoffs & Alternatives Considered: The spec rejects a run of the server middleware against the archive. Server operations read the HTTP request, and host operations also run in that path. The contract suite in Prove that disk and network peers obey the same Peer protocol #385 guards against drift from server behavior.
• Follow-up: A separate issue will split update_transfer_session into a field update and a stage advance (command-query separation).

Metadata

• Complexity: High
• Target Branch: release-v0.9.x

AI Usage

Drafted with Claude (Claude Code) from the approved design spec and implementation plan. The author reviewed the requirements, and the code references were checked against the release-v0.9.x codebase.