Skip to content

Commit d7ecbb6

Browse files
committed
feat(core): delivery lane engine — per-room ordered execution off the room lock (RMK-93)
The engine half of the RFC delivery-lanes amendment (roomkit-specs e0aabcc): DeliveryPlan / DeliveryCascade / RoomDeliveryLane / RoomLaneRegistry in core/lanes.py, and EventRouter.broadcast() split into plan() (pure, runs under the room lock) and execute_plan() (the per-target work, no lock required). broadcast() remains plan+execute for inline callers. The executor runs per room and per process on a fresh contextvars context (an inherited _held_rooms would fake lock reentrancy), executes only its own plans in index order gated by the delivered_index CAS under the __delivery__:{room_id} claim, backs off on cursor holes, and force-skips a hole after gap_timeout with a delivery_skipped framework event — never past a locally-held index. Cascades resolve the caller's wait only when the full reentry chain has completed, and short-circuit inside the lane or under the room lock to stay deadlock-free. Nothing uses the engine yet — the pipeline surgery is the next commit. 21 new unit tests; full suite 6632 green.
1 parent d38c0b8 commit d7ecbb6

3 files changed

Lines changed: 1209 additions & 30 deletions

File tree

‎src/roomkit/core/event_router.py‎

Lines changed: 75 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
from roomkit.channels.base import Channel
1212
from roomkit.core.circuit_breaker import CircuitBreaker
13+
from roomkit.core.lanes import DeliveryPlan
1314
from roomkit.core.rate_limiter import TokenBucketRateLimiter
1415
from roomkit.core.retry import retry_with_backoff
1516
from roomkit.core.transcoder import DefaultContentTranscoder
@@ -146,28 +147,67 @@ def get_channel(self, channel_id: str) -> Channel | None:
146147
"""Look up a channel by ID."""
147148
return self._channels.get(channel_id)
148149

149-
async def broadcast(
150+
def plan(
150151
self,
151152
event: RoomEvent,
152153
source_binding: ChannelBinding,
153154
context: RoomContext,
154155
*,
155156
exclude_delivery: set[str] | None = None,
156-
) -> BroadcastResult:
157-
"""Broadcast an event to all eligible channels in the room.
157+
) -> DeliveryPlan:
158+
"""Resolve an event's delivery set (RFC §10.1 step 12).
159+
160+
Pure — no I/O, no awaits — so it runs under the room lock: the target
161+
set is consistent with the committed timeline. Execution
162+
(:meth:`execute_plan`) does not require the lock.
163+
164+
A source that cannot write (RFC §7.5 — guards reentry events and
165+
direct broadcast callers; inbound events from non-writable sources
166+
are blocked before broadcast) yields an empty delivery set.
167+
"""
168+
if not source_binding.can_write:
169+
logger.debug(
170+
"Source %s cannot write (access=%s, muted=%s) — not broadcasting",
171+
source_binding.channel_id,
172+
source_binding.access,
173+
source_binding.muted,
174+
extra={"room_id": event.room_id, "channel_id": source_binding.channel_id},
175+
)
176+
targets: list[ChannelBinding] = []
177+
else:
178+
# Stamp visibility from source binding
179+
if event.visibility == Visibility.ALL and source_binding.visibility != Visibility.ALL:
180+
event = event.model_copy(update={"visibility": source_binding.visibility})
181+
# Target bindings include muted channels — they can still read.
182+
targets = self._filter_targets(event, source_binding, context.bindings)
183+
return DeliveryPlan(
184+
event=event,
185+
source_binding=source_binding,
186+
context=context,
187+
targets=targets,
188+
exclude_delivery=exclude_delivery,
189+
)
190+
191+
async def execute_plan(self, plan: DeliveryPlan) -> BroadcastResult:
192+
"""Execute a plan's delivery set (RFC §10.1 step 14).
158193
159194
RFC §3.8: For each target channel:
160195
- on_event(): all channels react (intelligence generates, observers analyze)
161196
- deliver(): only transport channels push to external recipients
162197
163-
Args:
164-
exclude_delivery: Channel IDs to skip delivery for (already
165-
received content via streaming).
198+
Runs without the room lock; per-room ordering is the caller's
199+
contract (the delivery lane, or an inline caller running to
200+
completion).
166201
"""
167202
from roomkit.telemetry.base import Attr, SpanKind
168203
from roomkit.telemetry.context import get_current_span, reset_span, set_current_span
169204
from roomkit.telemetry.noop import NoopTelemetryProvider
170205

206+
event = plan.event
207+
source_binding = plan.source_binding
208+
context = plan.context
209+
exclude_delivery = plan.exclude_delivery
210+
171211
telemetry = self._telemetry or NoopTelemetryProvider()
172212
session_id = (event.metadata or {}).get("voice_session_id")
173213
span_id = telemetry.start_span(
@@ -176,38 +216,20 @@ async def broadcast(
176216
parent_id=get_current_span(),
177217
room_id=event.room_id,
178218
session_id=session_id,
179-
attributes={Attr.CHANNEL_ID: source_binding.channel_id},
219+
attributes={Attr.CHANNEL_ID: source_binding.channel_id if source_binding else ""},
180220
)
181221
# Propagate backend-specific context for robust parent linking
182222
broadcast_token = set_current_span(
183223
span_id, telemetry_ctx=telemetry.get_span_context(span_id)
184224
)
185225

186226
result = BroadcastResult()
227+
targets = plan.targets
187228

188-
# Check source can write (RFC §7.5). Inbound events from non-writable
189-
# sources are already blocked before broadcast in the inbound pipeline;
190-
# this guards reentry events and any direct broadcast callers.
191-
if not source_binding.can_write:
192-
logger.debug(
193-
"Source %s cannot write (access=%s, muted=%s) — not broadcasting",
194-
source_binding.channel_id,
195-
source_binding.access,
196-
source_binding.muted,
197-
extra={"room_id": event.room_id, "channel_id": source_binding.channel_id},
198-
)
199-
reset_span(broadcast_token)
200-
telemetry.end_span(span_id, attributes={"target_count": 0})
201-
return result
202-
203-
# Stamp visibility from source binding
204-
if event.visibility == Visibility.ALL and source_binding.visibility != Visibility.ALL:
205-
event = event.model_copy(update={"visibility": source_binding.visibility})
206-
207-
# Determine target bindings (includes muted channels — they can still read)
208-
targets = self._filter_targets(event, source_binding, context.bindings)
209-
210-
if not targets:
229+
# An injected plan (bare on_event/deliver, no transcode, no reentry)
230+
# is executed by the framework host, never here; a plan with no
231+
# source binding has nothing to transcode from either way.
232+
if not targets or source_binding is None:
211233
reset_span(broadcast_token)
212234
telemetry.end_span(span_id, attributes={"target_count": 0})
213235
return result
@@ -467,6 +489,29 @@ async def _process_target(binding: ChannelBinding) -> None:
467489

468490
return result
469491

492+
async def broadcast(
493+
self,
494+
event: RoomEvent,
495+
source_binding: ChannelBinding,
496+
context: RoomContext,
497+
*,
498+
exclude_delivery: set[str] | None = None,
499+
) -> BroadcastResult:
500+
"""Plan and execute in one call — the inline path.
501+
502+
Running to completion where the caller stands trivially satisfies
503+
per-room order (RFC §10.2). The inbound pipeline instead calls
504+
:meth:`plan` under the room lock and hands execution to the room's
505+
delivery lane.
506+
507+
Args:
508+
exclude_delivery: Channel IDs to skip delivery for (already
509+
received content via streaming).
510+
"""
511+
return await self.execute_plan(
512+
self.plan(event, source_binding, context, exclude_delivery=exclude_delivery)
513+
)
514+
470515
def _filter_targets(
471516
self,
472517
event: RoomEvent,

0 commit comments

Comments
 (0)