The architecture in context
The system we are building
An online system can receive the same logical event more than once. The router derives different keys for different event types: a fill uses an execution identity, while a lifecycle event prefers a sequence number. This is more meaningful than hashing a transport envelope whose timestamps or serialization may change between deliveries.
Who does what in the stack
- Typed Python events
- Separate message meaning from transport representation.
- OrderedDict cache
- Bounds local duplicate-tracking memory.
- Custom router
- Dispatches accepted events and records diagnostics.
The project adds typed routing, deduplication and diagnostic counters around the transport. These are useful inference-system patterns whenever events update memory or trigger an action. The code excerpt describes identities, not a recipe for placing orders.
Open up the implementation
Give deduplication a memory horizon
Fill identities, lifecycle sequences and order identities have different semantics, so they need different keys. Transport timestamps are often unsuitable because a retry may receive a new envelope timestamp. A local cache suppresses repeats only while the key remains retained and the process state survives.
The mathematical contract
A larger cache extends retention but cannot fix a key that merges distinct events. Restart, eviction and multi-process consumers are separate failure modes. Access checks do not turn an insertion-ordered dictionary into an access-refreshing LRU unless order is explicitly updated.
Implementation and resource card
- Capacity / budget
- Memory scales with retained keys. Bounded insertion-order state is not a persistent exactly-once guarantee.
- Execution evidence
- This revision inspects and explains the archived implementation. It does not rerun the original workload. No unrecorded convergence time, throughput or accelerator result is supplied.
- Current reproduction context
- Current workstation, supplied by the author: Apple M4, 128 GB unified RAM, 40 GPU cores and 16 CPU cores. This is context for prospective reproduction, not attribution of every archived run. Python and framework versions are not fully locked for these historical sources; declarations, when available, are identified separately.
From explanation to a reproducible check
Replay a logical duplicate with a new envelope, then a distinct event with the same order ID. Force eviction and restart. Verify both the intended suppression and its declared boundary.
Preserve input identities, configuration and failure records with the result. A successful numerical check only establishes the operation it exercises: it does not certify an entire dataset, model or deployed system. Reproduce the interface on a small deterministic input before optimizing throughput or increasing workload size.
A closer look at the implementation
The code that carries the idea
The actual order-event branch keys by order identity and type, despite a broader timestamp description in the docstring. Code behavior takes precedence over the comment. A missing lifecycle sequence falls back to a weaker composite identity, so collision behavior must be considered explicitly.
def _get_dedup_key(self, event: BaseEvent) -> str:
"""
Generate de-duplication key based on event type
Different event types need different de-dup strategies:
- FillEvent: order_id + exec_id (unique execution)
- LifecycleEvent: seq (if available) or order_id + type
- OrderEvent: order_id + type + timestamp
"""
if isinstance(event, FillEvent):
# Fill: order_id + exec_id (most specific)
return f"fill:{event.order_id}:{event.exec_id}"
elif isinstance(event, LifecycleEvent):
# Lifecycle: prefer seq, fallback to order_id + type
if event.seq:
return f"lifecycle:{event.seq}"
return f"lifecycle:{event.order_id}:{event.type}"
elif isinstance(event, OrderEvent):
# Order: order_id + type (may get multiple OrderCreated, but type differs)
return f"order:{event.order_id}:{event.type}"
elif isinstance(event, CancelEvent):
# Cancel: order_id (should only get one per order)
return f"cancel:{event.order_id}"
else:
# Fallback: type + timestamp
return f"event:{type(event).__name__}:{event.ts.timestamp()}"Verbatim archive excerpt from event_router.py. Context-dependent historical code, not a standalone runnable program. Comments retain their original wording; the article distinguishes implemented behavior from stale or overbroad comments.
The boundary that matters
The seen-event container is bounded and insertion-ordered; membership checks do not make it a full access-refreshing LRU. After eviction, an old duplicate can be accepted again. Process restart and multi-process coordination create additional boundaries that a local cache does not solve.
