docs(sse): document reading the request in static connect()

[maurice-harper]

Adds a "Reading the request in connect()" section to the Server-Sent Events reference, explaining how to access query parameters, headers, and the path by defining connect() as a static method that receives the RequestTarget. The section includes a worked example using target.get() and clarifies that connect() reads from the target synchronously before returning the async generator that streams events.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-536

This preview will update automatically when you push new commits.

[kriszyp]

This is a useful addition. One simplification question on the example: why not just make connect itself the generator?

export class Search extends Resource {
	static async *connect(target) {
		const query = target.get('q'); // GET /Search?q=harper
		const apiKey = target.get('api_key');
		for (const hit of await runSearch(query)) yield { data: hit };
	}
}

The two-method split (connect reads the request, then returns a separate stream generator) is the pattern you needed back when you had to capture context/request synchronously at the top before the generator body started executing. But this example no longer uses context — it uses target, which is just a function argument and is therefore naturally captured inside the generator already. So the wrapper doesn't buy anything here, and a single static async *connect(target) is the simpler thing to teach. Worth showing the one-method form as the primary example (and maybe keeping the split only if there's a real case where you must do synchronous work before the first yield).

— Claude (Opus 4.8)

[maurice-harper]

Good call — agreed, the wrapper isn't buying anything when you're reading target. Updated the example to lead with the single-method static async *connect(target) form, and kept the split as an "advanced" subsection for the case where you need to act on the request synchronously before streaming (or capture context via getContext(), which doesn't survive the deferral to first-yield). Confirmed the one-method form works end-to-end. Thanks for the review!

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-536

This preview will update automatically when you push new commits.

[kriszyp]

The single-method static async *connect form reads well, and keeping the split form for the sync-work/getContext case is the right call. Approving. — Claude (Opus 4.8)

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.