Interaction Pipeline Overview
The EdgeInteract interaction pipeline has five distinct stages. Each stage has defined inputs, outputs, and failure modes. Understanding the pipeline in full is essential for building reliable Human-in-the-Loop features.
The Five Pipeline Stages
Request Creation & Publish
Server constructs an InteractionRequest, validates it, runs pre-send hooks, and calls IInteractionPublisher.PublishAsync(). The interaction is registered in the pipeline state store with status: "pending".
Output: interactionId, interaction registered in state store
Failure: Hook rejection, validation error, rate limit exceeded → InteractionPublishException
EdgeStream Delivery
EdgeInteract publishes the serialized request to interactions.{targetUserId} via EdgeStream. The message fans out to all active WebSocket sessions for the targeted user. The timeout timer starts.
Output: Message delivered to 0..N client sessions, status: "delivered"
Failure: No active sessions → message is queued or dropped depending on configuration
UI Display
Client's InteractionSubscriber receives the message. InteractionContainer routes it to the correct component based on type. The component renders and waits for user input. Status: "displayed".
Output: Interaction visible in the user's browser/app
Failure: Unknown type → fallback renderer or error boundary
User Response
User takes action. Component calls respond(outcome, data). InteractionResponsePublisher publishes an InteractionResponse to interactions.callback.{interactionId}. Post-receive hooks run on the server.
Output: InteractionResponse on callback topic, status: "responded"
Failure: Response validation failure → hook rejects response, UI shows error
Acknowledgement
Server processes the response, runs post-receive hooks, and publishes InteractionAck to the user's session. The client receives the ack and dismisses the UI component. status: "acknowledged". The awaiting Task resolves.
Output: Cycle complete, workflow resumes with response data
Failure: Server processing error → error response to client
Timeout Path
If the timeout fires before Stage 4 completes:
Timeout Fires
The pipeline timer expires. EdgeInteract publishes InteractionTimeout to the callback topic with outcome: "timeout".
Client Dismissal
The client receives a timeout dismissal signal. The UI component is removed from the inbox. The interaction is marked as expired.
Pipeline Status Transitions
| Status | Meaning | Next Status |
|---|---|---|
pending | Request created, not yet delivered | delivered or failed |
delivered | Published to EdgeStream topic | displayed or timed_out |
displayed | Rendered in client UI | responded or timed_out |
responded | User submitted a response | acknowledged or failed |
acknowledged | Server processed, cycle complete | (terminal) |
timed_out | No response within timeoutMs | (terminal) |
failed | Error in hook, validation, or server processing | (terminal) |
Topic Map
| Topic | Direction | Content |
|---|---|---|
interactions.{userId} | Server → Client | InteractionRequest |
interactions.callback.{interactionId} | Client → Server | InteractionResponse |
interactions.ack.{interactionId} | Server → Client | InteractionAck |
interactions.dismiss.{userId} | Server → Client | Timeout/dismissal signal |