Plan to add external events plan by archandatta · Pull Request #217 · kernel/kernel-images

archandatta · 2026-04-14T15:42:20Z

Note

Low Risk
Low risk because this PR only adds a planning document and does not change runtime code or APIs.

Overview
Adds plans/external-events.md, a detailed plan proposing new endpoints POST /events/publish (ingest external events.Event into the active capture session with enforced source.kind) and GET /events/stream (SSE streaming with Last-Event-ID resume, keepalives, and multi-client readers).

The plan also outlines follow-up behavioral changes like clearing capture-session state on stop via a session_ended marker, adding CaptureSession.Active(), and documenting both endpoints in server/openapi.yaml.

^{Reviewed by Cursor Bugbot for commit 6a06e95. Bugbot is set up for automated code reviews on this repo. Configure here.}

firetiger-agent · 2026-04-14T15:44:15Z

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR title and empty body provide insufficient information to determine if kernel API endpoints or Temporal workflows are being modified; please add details about what files are changed.

To monitor this PR anyway, reply with @firetiger monitor this.

rgarcia · 2026-04-14T17:49:58Z

@@ -0,0 +1,155 @@
+# External Event Ingestion + SSE Streaming — Plan
+
+**Scope:** Two new HTTP endpoints layered on top of the merged CDP base: `POST /events/capture_session/publish` (external event ingestion) and `GET /events/capture_session/stream` (SSE live stream), both wired into the existing resource-style `CaptureSession`.


i don't think the url here should be nested under capture_session. in my mind the capture session is a singleton producer the API runs / users can configure that publishes to a shared event stream that others can publish into. it doesn't own this stream

so either POST /events or POST /events/publish and GET /events or GET /evenst/stream makes more sense to me

Wouldn't we want the /events/publish tied to a capture_session_id for traceability?

The endpoint changed to events/publish but made it so that the a capture session is required so it goes through the pipeline

rgarcia · 2026-04-14T17:53:56Z

+| POST | `/events/capture_session/publish` | `ApiService.PublishEvent` | `publishEvent` |
+| GET | `/events/capture_session/stream` | `ApiService.StreamCaptureSession` (SSE) | `streamCaptureSession` |
+
+The stream endpoint follows the same singleton pattern as the other `/events/capture_session` routes. Handlers reference `s.captureSession` directly; the endpoint returns 404 when no session is active.


i don't think the stream endpoint should be stateful or a singleton. Many API users should be able to call this and request events starting after some time or sequence number. It's not tied to capture session, in fact capture session might not even be running

Okay understood.

So then diving into the lifecycle of the stream:

Client Pipeline │ │ │ GET /events/stream?after_seq=N │ │───────────────────────────────────▶│ │ │ │ SSE connection opens │ │◀───────────────────────────────────│ │ │ │ event (seq=N+1) │ │◀───────────────────────────────────│ │ event (seq=N+2) │ │◀───────────────────────────────────│ │ ... │ │ │ ├──── Client disconnects ────────────┤ │ OR │ ├──── Server shuts down ─────────────┤ │ │ │ Connection closes │ │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │

if we did decouple the events/publish from the capture session, then would we leave the stream open?

since this is opt-in, we'd need to figure out the use cases to leave the stream connection open/closed

Once a capture session is active, multiple streams will be able to connect/disconnect either at the oldest record or a certain seq

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2bbe5a3. Configure here.}

Sayan-

overall semantics look good to me!

Sayan- · 2026-04-22T18:19:46Z

+
+Accepts a JSON `events.Event` body and publishes it into the currently active `CaptureSession`.
+
+**Publish requires an active capture session.** If no session is active the handler returns `400` — the caller must `POST /events/start` first. The session is a precondition for publishing, not an implicitly-created resource.


seems reasonable

Sayan- · 2026-04-22T18:20:27Z

+- `400` when `type` is empty.
+- `200` on successful publish.
+
+The handler unconditionally sets `source.kind = KindKernelAPI` **after** decoding, overwriting whatever the caller supplied. This is not a default — it is an enforcement. A caller that sends `"source": {"kind": "cdp"}` must not be able to forge CDP provenance; `source.kind` is documented as the fan-out key (§3.2) and its value for this endpoint is not negotiable.


hmm is kind an enum or known set of strings? for example could we simpler interpolate the provided kind with something like event_publish? would that be more or less confusing downstream?

Yeah kind is coming from the types set in event.go

type SourceKind string const ( KindCDP SourceKind = "cdp" KindKernelAPI SourceKind = "kernel_api" KindExtension SourceKind = "extension" KindLocalProcess SourceKind = "local_process" )

hmm. how would we ever get events of type KindExtension or KindLocalProcess?

Sayan- · 2026-04-22T18:22:30Z

+
+The handler does not take `monitorMu` — `CaptureSession.Publish` is serialised internally and guarantees monotonic seq delivery. This creates a narrow TOCTOU: a concurrent `StopCapture` can clear the session ID between the `Active()` check and the `Publish()` call, causing the event to be written to the ring buffer with an empty `captureSessionID` (after the `session_ended` marker). This is accepted; grabbing `monitorMu` on every publish would serialize all external events behind CDP monitor start/stop.
+
+### 2.3 `GET /events/stream`


seems reasonable!

feat: add external events plan

fc419d0

archandatta force-pushed the archand/plan/externel-events-stream branch from a19154d to fc419d0 Compare April 14, 2026 17:24

archandatta requested review from Sayan- and rgarcia April 14, 2026 17:25

rgarcia requested changes Apr 14, 2026

View reviewed changes

archandatta requested a review from rgarcia April 15, 2026 13:07

update plan

2bbe5a3

cursor Bot reviewed Apr 22, 2026

View reviewed changes

Comment thread plans/external-events.md Outdated

update active mutex

6a06e95

Sayan- approved these changes Apr 22, 2026

View reviewed changes

		@@ -0,0 +1,155 @@
		# External Event Ingestion + SSE Streaming — Plan

		Scope: Two new HTTP endpoints layered on top of the merged CDP base: `POST /events/capture_session/publish` (external event ingestion) and `GET /events/capture_session/stream` (SSE live stream), both wired into the existing resource-style `CaptureSession`.


		Accepts a JSON `events.Event` body and publishes it into the currently active `CaptureSession`.

		Publish requires an active capture session. If no session is active the handler returns `400` — the caller must `POST /events/start` first. The session is a precondition for publishing, not an implicitly-created resource.


		The handler does not take `monitorMu` — `CaptureSession.Publish` is serialised internally and guarantees monotonic seq delivery. This creates a narrow TOCTOU: a concurrent `StopCapture` can clear the session ID between the `Active()` check and the `Publish()` call, causing the event to be written to the ring buffer with an empty `captureSessionID` (after the `session_ended` marker). This is accepted; grabbing `monitorMu` on every publish would serialize all external events behind CDP monitor start/stop.

		### 2.3 `GET /events/stream`

Conversation

archandatta commented Apr 14, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

firetiger-agent Bot commented Apr 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

archandatta Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Sayan- left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

archandatta commented Apr 14, 2026 •

edited by cursor Bot

Loading

archandatta Apr 15, 2026 •

edited

Loading