ts: MeshJob Stream subscription — subscribeEvents (TypeScript)

[dhyansraj]

Summary

• Adds Stream subscription mode for MeshJob (TypeScript vertical of MeshJob: event injection into running jobs — recv_event + send_event + Stream subscription + trace propagation #1032 follow-up): mesh.jobs.subscribeEvents(jobId, { types, after, longPollSecs }) -> AsyncGenerator<JobEvent>.
• Mirrors the Python vertical (MeshJob: Stream subscription — subscribe_events (Python) #1047). Counterpart to the point-to-point recvEvent/postEvent surface shipped in ts: MeshJob event injection parity — recvEvent/sendEvent/postEvent #1043. Multiple subscribers can observe the same job's events independently via per-call cursors.
• Three layers: napi-rs binding JsJobProxy::list_events returning ListEventsResult { events, next_after } (napi-rs v3 doesn't auto-serialize bare tuples), TS SDK subscribeEvents async generator reusing the existing _getOrCreateProxy LRU cache, integration test tc27 in uc22_meshjob_ts extending the long-task fixtures with run_until_done (producer) and commission_subscribe_observer (consumer).
• Side benefit: scrubs a stray null byte from jobs.ts:187 (${registryUrl}\x00${jobId} → ${registryUrl} ${jobId}) inherited from an earlier PR that made git classify the file as binary in diffs. This also explains the Bin -> Bin line in the file stat — git diff -a shows the actual textual diff.

Review Notes

Independent review caught 4 substantive WARNINGs (all addressed in the amended commit):

1. bigint → number cursor truncation: TSDoc accepted bigint for i64-sourced cursors, but Number(after) silently truncated values above 2^53. Now guarded with an explicit RangeError when after > BigInt(Number.MAX_SAFE_INTEGER).
2. Missing "no seq key" malformed-payload test: Python sibling had this test; TS now has parity (rejects event without seq key).
3. Subscriber drain comment misleading: .catch(() => {}) only suppresses the unhandled rejection — it does NOT cancel the underlying long-poll (JS has no cancellation primitive without AbortController plumbed through napi). Comment rewritten to be honest. Plumbing AbortController through napi is a known limitation left out of scope.
4. LRU-reuse test asserted caching only: now strengthened to assert both iters observe seq=1 independently — the actual headline contract.

Other findings (3 INFOs) skipped as cosmetic or already-intentional patterns.

Closes #1048

Sibling Java vertical of subscription mode will follow as a separate PR, mirroring the #1043 → #1045 cadence.

Test plan

• TS unit tests pass (jobs.spec.ts: 23 tests, +7 new in this PR — 6 from initial implementation + 1 from review fix)
• napi binding rebuild + src-tests 12/12 pass
• uc22_meshjob_ts integration suite: 24/24 pass (23 baseline + 1 new tc27 in 54.4s)
• parse_timeout_secs guard reused at napi boundary (NaN/Inf/negative reject)
• LRU JobProxy cache reused from ts: MeshJob event injection parity — recvEvent/sendEvent/postEvent #1043 (no duplicate cache)
• Server-side types filter forwarded all the way to the registry (no client-side post-filter)
• nextAfter watermark advances cursor on empty pages (parity with Python MeshJob: Stream subscription — subscribe_events (Python) #1047)
• Bool-seq and missing-seq rejection (parity with Python RuntimeError shape)

Summary by CodeRabbit

Release Notes

• New Features

  • Added subscribeEvents() function to the jobs namespace for real-time event subscription with optional event type filtering and long-polling support
  • Events support cursor-based pagination for reliable delivery across subscription sessions

• Tests

  • Added comprehensive integration tests validating concurrent event subscription alongside event consumption patterns

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements TypeScript stream subscription mode for MeshJob: a non-destructive async iterator that allows clients to observe a job's event stream independently from the consumer. It adds an N-API binding, exposes subscribeEvents on mesh.jobs, validates iterator behavior with comprehensive unit tests, and verifies end-to-end observer patterns with concurrent producer/consumer integration.

Changes

Stream subscription mode for job events

Layer / File(s)	Summary
N-API binding for event list fetching src/runtime/core/src/jobs_napi.rs	JsJobProxy::list_events validates timeout, calls underlying proxy, converts returned JobEvent objects to JSON, and returns both events array and registry-provided next_after watermark. New ListEventsResult struct wraps the response.
TypeScript SDK public API and namespace wiring src/runtime/typescript/src/index.ts	Imports subscribeEvents from ./jobs.js, adds it to mesh.jobs namespace, and re-exports both the function and SubscribeEventsOptions type for public consumption.
TypeScript unit tests for async iterator behavior src/runtime/typescript/src/__tests__/jobs.spec.ts	Mocks N-API listEvents, tests async iterator yielding on non-empty pages, cursor advancement via nextAfter on empty pages, malformed event rejection (boolean seq, missing seq), null longPollSecs forwarding, "job not found" translation to JobNotFoundError, and per-iterator cursor isolation with JobProxy cache reuse.
Integration test tools for concurrent producer/observer pattern tests/integration/suites/uc22_meshjob_ts/fixtures/long-task-provider-ts/src/index.ts, tests/integration/suites/uc22_meshjob_ts/fixtures/long-task-consumer-ts/src/index.ts	Provider adds run_until_done tool consuming work events via recvEvent until final: true. Consumer adds commission_subscribe_observer tool that concurrently subscribes via subscribeEvents and posts three work events to complete both producer and observer flows.
Integration test case for observer pattern validation tests/integration/suites/uc22_meshjob_ts/tc27_subscribe_events_streams_observer_pattern_ts/test.yaml	tc27 validates observer pattern: provisions services, invokes commission_subscribe_observer, asserts subscriber completes without timeout with observed_count=3, confirms producer processes all 3 events in order (seq=1,2,3), and validates final: true payload round-trips through both consumption paths.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• dhyansraj/mcp-mesh#1048: This PR directly implements the TypeScript vertical of MeshJob stream subscription mode (subscribeEvents async iterator) described in the linked issue.

Possibly related PRs

• dhyansraj/mcp-mesh#1047: Both PRs introduce the Rust JobProxy::list_events mechanism for non-destructive event streaming — main PR via N-API JsJobProxy::list_events, while the retrieved PR adds the underlying Rust JobProxy::list_events used by all language SDKs.
• dhyansraj/mcp-mesh#1043: Main PR's new JsJobProxy::list_events builds on the same N-API job-event JSON serialization and timeout validation helpers added in PR #1043.
• dhyansraj/mcp-mesh#885: The main PR extends the same N-API JsJobProxy (in src/runtime/core/src/jobs_napi.rs) by adding a new list_events method for subscribeEvents, building on the earlier MeshJob TypeScript runtime/N-API JobProxy bindings from the retrieved PR.

Poem

🐰 A rabbit hops through event streams,
Non-destructive reads fulfill the dreams,
Observers watch, producers play,
Async iterators light the way!
TypeScript flies with cursor's grace, ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'ts: MeshJob Stream subscription — subscribeEvents (TypeScript)' clearly and concisely describes the main change: adding TypeScript Stream subscription support via subscribeEvents for MeshJob.
Linked Issues check	✅ Passed	The implementation fulfills all coding requirements from #1048: napi-rs binding with JsJobProxy::list_events returning ListEventsResult, TS async generator subscribeEvents with proper cursor management, integration test tc27 with producer/consumer patterns, and all specified acceptance criteria.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to #1048 objectives: napi binding, TS SDK async generator, integration test fixtures, and test suite for subscribeEvents. No unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/1048-meshjob-subscribe-events-typescript

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/integration/suites/uc22_meshjob_ts/tc27_subscribe_events_streams_observer_pattern_ts/test.yaml (1)

118-130: ⚡ Quick win

Strengthen posted sequence assertions to target posted_seqs directly.

Lines 125-130 currently match "seq" anywhere in the response, so they can pass even if posted_seqs is wrong. Assert the posted_seqs array content instead.

Proposed assertion update

-  - expr: "${captured.commission_response} contains '\\\"seq\\\":1'"
-    message: "first posted event must have seq=1"
-  - expr: "${captured.commission_response} contains '\\\"seq\\\":2'"
-    message: "second posted event must have seq=2"
-  - expr: "${captured.commission_response} contains '\\\"seq\\\":3'"
-    message: "third posted event must have seq=3"
+  - expr: "${captured.commission_response} contains '\\\"posted_seqs\\\":[1,2,3]'"
+    message: "posted_seqs must preserve ordered values [1,2,3] for a fresh job"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@tests/integration/suites/uc22_meshjob_ts/tc27_subscribe_events_streams_observer_pattern_ts/test.yaml`
around lines 118 - 130, The current assertions check for '"seq":N' anywhere,
which can match unrelated fields; update the assertions that reference
captured.commission_response to explicitly assert the posted_seqs array and its
entries (e.g., that captured.commission_response contains the "posted_seqs" key
and that its array contains 1,2,3 in order or at least contains those values
tied to that key). Modify the three seq checks to target posted_seqs (and keep
the existing message strings) so they validate posted_seqs contains seq=1, seq=2
and seq=3 rather than any stray "seq" occurrences.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In
`@tests/integration/suites/uc22_meshjob_ts/tc27_subscribe_events_streams_observer_pattern_ts/test.yaml`:
- Around line 118-130: The current assertions check for '"seq":N' anywhere,
which can match unrelated fields; update the assertions that reference
captured.commission_response to explicitly assert the posted_seqs array and its
entries (e.g., that captured.commission_response contains the "posted_seqs" key
and that its array contains 1,2,3 in order or at least contains those values
tied to that key). Modify the three seq checks to target posted_seqs (and keep
the existing message strings) so they validate posted_seqs contains seq=1, seq=2
and seq=3 rather than any stray "seq" occurrences.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3369d217-111e-4a41-9582-ab8c370cb51c

📥 Commits

Reviewing files that changed from the base of the PR and between 888d2cb and 4fa4b69.

⛔ Files ignored due to path filters (1)

• src/runtime/core/typescript/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (7)

• src/runtime/core/src/jobs_napi.rs
• src/runtime/typescript/src/__tests__/jobs.spec.ts
• src/runtime/typescript/src/index.ts
• src/runtime/typescript/src/jobs.ts
• tests/integration/suites/uc22_meshjob_ts/fixtures/long-task-consumer-ts/src/index.ts
• tests/integration/suites/uc22_meshjob_ts/fixtures/long-task-provider-ts/src/index.ts
• tests/integration/suites/uc22_meshjob_ts/tc27_subscribe_events_streams_observer_pattern_ts/test.yaml