Shared connection interface for network and disk syncs #370

Overview

This task (milestone M3) turns the empty Connection class into an abstract interface. NetworkSyncConnection implements it, and TransferClient depends only on it. The task also renames the server names that both connection types use to peer names, with deprecated aliases.

Background & Motivation

TransferClient depends on the network connection in two ways. It creates a NetworkSessionContext directly, and it reads server_info. A disk connection needs its own session context, so the connection must create it.

The word "server" does not fit a disk peer. The design uses "peer" in shared code. Hosts such as Kolibri still use server_info and the server_cert keyword, so these names stay as deprecated aliases.

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

User Story

As a Kolibri developer,
I want one connection interface for network and disk syncs,
So that sync code works with either connection type without changes.

Description & Expected Outcomes

Connection groups its members by caller: peer identity, sync session lifecycle, certificates, and the Peer protocol. The Peer protocol methods are declared here. #371 implements them for the network.

NetworkSyncConnection gets peer_info, connection_kind, and create_session_context(). The old server_info property still works and emits DeprecationWarning. create_sync_session accepts peer_cert. The old server_cert keyword still works and emits DeprecationWarning.

TransferClient builds its session context from create_session_context(), and it reads capabilities from the connection.

Deliverables & Contracts

The task delivers:

• Connection as an abstract base class with the members in spec §3.2.
• NetworkSyncConnection.peer_info, connection_kind = "network", and create_session_context().
• create_sync_session(client_cert, peer_cert=None, chunk_size=None, server_cert=None).
• A TransferClient that uses only Connection members.

Acceptance Criteria

• NetworkSyncConnection is a subclass of Connection.
• server_info emits DeprecationWarning and returns the same value as peer_info.
• create_sync_session with the server_cert keyword emits DeprecationWarning and behaves like peer_cert.
• create_sync_session with neither certificate raises ValueError.
• The TransferClient context holds a LocalSessionContext and the context from create_session_context().
• Morango code has no reads of server_info.
• The characterization suite passes without edits.

Technical Pointers & Architecture

• Target Components: morango/sync/syncsession.py:111 (Connection), :125-517 (NetworkSyncConnection), :609-626 (TransferClient.__init__).
• Related Patterns: The deprecated names follow the same pattern as the deprecated Network* operations in Keep old network operation names and allow connection-specific overrides #375.
• Data Model & Schema Considerations: None. The model fields server_fsic, server_certificate, and is_server keep their names.
• Resilience & Failure Modes: None.

Notes & Tradeoffs

• Dependencies: Blocked by: Typed value for the peer view of a transfer session #369 (Typed value for the peer view of a transfer session). Blocks: Network connection speaks the transport-neutral Peer protocol #371, Session contexts support network and disk peers #373, Start and close sync sessions with a disk connection #383.
• Testing Requirements: This is a refactor. The characterization suite from Tests that pin today's async network push and pull behavior #363 and Tests that pin today's legacy network sync behavior #364 must pass without edits. Tests in tests/testapp/tests/sync/test_context.py build mocks with server_info. Do not change them.
• Tradeoffs & Alternatives Considered: A split into two interfaces was rejected. The disk transfer methods need the archive and certificates of the connection, so a split spreads connection details across two objects.
• Compatibility & Migrations: Kolibri must move from server_info to peer_info, and from server_cert to peer_cert. The deprecated names stay until a later release.

Metadata

• Complexity: Medium
• 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.