Coverage for src/copytrading_engine/sources/application.py: 96%
43 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-16 16:55 +0000
1"""Forward saved source messages; confirm only after the publisher acknowledges."""
3import logging
4from collections.abc import Callable, Mapping, Sequence
5from contextlib import AbstractContextManager, nullcontext
6from dataclasses import dataclass
7from typing import Literal, Protocol
9from pydantic import JsonValue
11from copytrading_engine.shared.raw_message import RawMessage
12from copytrading_engine.sources.recovery import RecoveryStart, RejectedCapture
14log = logging.getLogger(__name__)
17@dataclass(frozen=True, slots=True)
18class Delivery:
19 key: str
20 payload: str
21 mode: Literal["live", "historical"]
23 def __post_init__(self) -> None:
24 if self.mode not in {"live", "historical"}: 24 ↛ 25line 24 didn't jump to line 25 because the condition on line 24 was never true
25 raise ValueError("Saved delivery has an unknown route")
28@dataclass(frozen=True, slots=True)
29class AttachmentReference:
30 """Ephemeral source-adapter metadata; the signed URL is never persisted."""
32 attachment_id: str
33 filename: str
34 content_type: str | None
35 declared_size: int
36 url: str
39AttachmentStatus = Literal[
40 "pending",
41 "available",
42 "missing",
43 "oversize",
44 "download_failed",
45 "origin_rejected",
46 "timed_out",
47 "count_exceeded",
48 "skipped_rejected",
49]
52@dataclass(frozen=True, slots=True)
53class SourceAttachmentEvidence:
54 """Source-owned metadata and private managed reference for one attachment."""
56 evidence_id: str
57 attachment_id: str
58 filename: str
59 content_type: str | None
60 declared_size: int
61 status: AttachmentStatus
62 byte_size: int | None = None
63 sha256: str | None = None
64 managed_path: str | None = None
65 omitted_count: int = 0
68class SourceCapture(Protocol):
69 """Save a validated message or retain the complete rejected input."""
71 async def add(
72 self,
73 event: RawMessage,
74 *,
75 source_event: JsonValue | None = None,
76 attachments: Sequence[AttachmentReference] = (),
77 ) -> None: ...
79 async def reject(
80 self,
81 event: dict[str, JsonValue],
82 reason: str,
83 *,
84 source_event: JsonValue | None = None,
85 attachments: Sequence[AttachmentReference] = (),
86 ) -> None: ...
89class RecoveryCapture(SourceCapture, Protocol):
90 async def recovery_start(self, channel_id: int, fallback_id: int) -> RecoveryStart: ...
92 async def capture_recovery_page(
93 self,
94 channel_id: int,
95 events: list[RawMessage],
96 rejected: list[RejectedCapture],
97 last_id: int,
98 *,
99 source_events: Mapping[str, JsonValue] | None = None,
100 attachments: Mapping[str, Sequence[AttachmentReference]] | None = None,
101 ) -> None: ...
104class SourceOutbox(Protocol):
105 async def claim_batch(self) -> Sequence[Delivery]:
106 """Return the unconfirmed batch, or durably assign the next ordered batch.
108 This writes delivery state. Rows include identity, payload, and fixed route;
109 their order must survive retries and process restart.
110 """
111 ...
113 async def confirm(self, key: str) -> None: ...
116class SourcePublisher(Protocol):
117 async def publish(self, delivery: Delivery) -> None:
118 """Return only after acknowledgement; retries retain the original identity."""
119 ...
122class ForwardBatch:
123 def __init__(
124 self,
125 outbox: SourceOutbox,
126 publisher: SourcePublisher,
127 *,
128 observe: Callable[[], AbstractContextManager[None]] = nullcontext,
129 ) -> None:
130 self.outbox, self.publisher = outbox, publisher
131 self.observe = observe
133 async def flush(self) -> int:
134 rows = await self.outbox.claim_batch()
135 if not rows:
136 # The loop polls about twice a second; an empty poll is not an operation to record.
137 return 0
138 with self.observe():
139 for delivery in rows:
140 # Failure or cancellation in either step retains the unconfirmed head.
141 # Replays can duplicate transport delivery, never invent a new identity.
142 await self.publisher.publish(delivery)
143 await self.outbox.confirm(delivery.key)
144 log.info("message_published id=%s mode=%s", delivery.key, delivery.mode)
145 return len(rows)