feat: auto-mark app as ready on first inbound HTTP request

[sohankshirsagar]

Summary

Removes the requirement for users to explicitly call TuskDrift.markAppAsReady() in their service code. The SDK now automatically marks the app as ready when the first inbound HTTP server request is received. Users can still call markAppAsReady() explicitly if they need precise control over the timing.

Changes

• Add auto-ready detection in HttpInstrumentation._getServerEmitPatchFn() — when the first request event is emitted on an HTTP server and the app hasn't been marked ready yet, markAppAsReady() is called automatically.

Design decisions

• Placement in _getServerEmitPatchFn rather than modeUtils.ts: The auto-mark is placed at the HTTP server emit('request') level — the earliest possible hook for inbound requests — rather than inside handleRecordMode/handleReplayMode. This ensures the app is marked ready before sampling decisions, so it fires regardless of whether the specific request is sampled. It also fires before mode-specific logic, so it works for both record and replay.
• Covers all HTTP-based frameworks: Express, Fastify, Next.js, and any other framework built on Node's http.Server all emit request events, so this single hook point covers them all (including Next.js, which skips HTTP instrumentation deeper in _createServerSpan but still passes through _getServerEmitPatchFn).
• No-op after first request: The isAppReady() guard ensures the check is a cheap boolean read on subsequent requests. If the user explicitly calls markAppAsReady() before any request arrives, the auto-mark path never fires.

[cubic-dev-ai]

No issues found across 2 files

[tusk-dev]

Generated 5 tests - 5 passed

 

Tip

New to Tusk Unit Tests? Learn more here.

Test Summary

• _getServerEmitPatchFn - 5 ✓

Results

Tusk's tests all pass and validate the core auto-ready feature comprehensively. The test suite confirms that _getServerEmitPatchFn correctly triggers markAppAsReady() on the first HTTP request in both RECORD and REPLAY modes, handles repeated requests idempotently without errors, and only fires on actual request events (not other server events like listening). Critically, the tests also verify backward compatibility—explicit calls to markAppAsReady() work as expected and aren't interfered with by the auto-mark logic. This covers the hot path: every inbound HTTP request now flows through this instrumentation point, so the auto-ready detection is guaranteed to fire early and consistently across all HTTP-based frameworks (Express, Fastify, Next.js, etc.) without requiring users to add boilerplate code.

View check history

Commit	Status	Output	Created (UTC)
bd1207a	Generated 5 tests - 5 passed	Tests	Mar 24, 2026 12:13AM

Was Tusk helpful? Give feedback by reacting with 👍 or 👎