feat(standard-server): send initial comment in event stream to flush response headers immediately (#1204)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
  * Configurable initial event comment (enable/disable + custom text).
* **Bug Fixes**
* Streaming/SSE responses now emit an initial keep‑alive heartbeat line
before event data.
* **Documentation**
* Added HTTP Event Iterator configuration docs; removed several
client/OpenAPI/RPC keep‑alive sections.
* **Tests**
* Expanded tests covering initial-comment and keep‑alive sequencing,
timing, and stream consumption.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/adapters/http.md

@@ -247,3 +247,52 @@ The `link` can be any supported oRPC link, such as [RPCLink](/docs/client/rpc-li
 ::: info
 This only shows how to configure the http link. For full client examples, see [Client-Side Clients](/docs/client/client-side).
 :::
+
+## Event Iterator Options
+
+HTTP adapters provide reliability features for streaming [Event Iterators](/docs/event-iterator):
+
+```ts
+const handler = new RPCHandler(router, {
+  eventIteratorInitialCommentEnabled: true,
+  eventIteratorInitialComment: 'start',
+  eventIteratorKeepAliveEnabled: true,
+  eventIteratorKeepAliveInterval: 5000,
+  eventIteratorKeepAliveComment: '',
+})
+
+const link = new OpenAPILink({
+  eventIteratorInitialCommentEnabled: true,
+  eventIteratorInitialComment: 'start',
+  eventIteratorKeepAliveEnabled: true,
+  eventIteratorKeepAliveInterval: 5000,
+  eventIteratorKeepAliveComment: '',
+})
+```
+
+::: info
+These options are available for HTTP-based handlers and links only.
+:::
+
+::: warning
+Link options apply when streaming from **client to server**, not server to client (as with handlers). In most cases, you don't need to configure these on the link.
+:::
+
+### Initial Comment
+
+Sends an initial comment immediately when the stream starts to flush response headers early. This allows the receiving side to establish the connection without waiting for the first event.
+
+| Option                               | Default | Description                    |
+| ------------------------------------ | ------- | ------------------------------ |
+| `eventIteratorInitialCommentEnabled` | `true`  | Enable/disable initial comment |
+| `eventIteratorInitialComment`        | `''`    | Custom comment content         |
+
+### Keep-Alive Comments
+
+Sends periodic comments during inactivity to prevent connection timeouts.
+
+| Option                           | Default | Description                        |
+| -------------------------------- | ------- | ---------------------------------- |
+| `eventIteratorKeepAliveEnabled`  | `true`  | Enable/disable keep-alive comments |
+| `eventIteratorKeepAliveInterval` | `5000`  | Interval in milliseconds           |
+| `eventIteratorKeepAliveComment`  | `''`    | Custom comment content             |

apps/content/docs/client/rpc-link.md

@@ -153,28 +153,6 @@ const link = new RPCLink({
 
 Unlike traditional SSE, the [Event Iterator](/docs/event-iterator) does not automatically retry on error. To enable automatic retries, refer to the [Client Retry Plugin](/docs/plugins/client-retry).
 
-## Event Iterator Keep Alive
-
-:::warning
-These options for sending [Event Iterator](/docs/event-iterator) from **client to the server**, not from **the server to client** as used in [RPCHandler Event Iterator Keep Alive](/docs/rpc-handler#event-iterator-keep-alive) or [OpenAPIHandler Event Iterator Keep Alive](/docs/openapi/openapi-handler#event-iterator-keep-alive).
-
-**In 99% of cases, you don't need to configure these options.**
-:::
-
-To keep [Event Iterator](/docs/event-iterator) connections alive, `RPCLink` periodically sends a ping comment to the server. You can configure this behavior using the following options:
-
-- `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
-- `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
-- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping messages.
-
-```ts
-const link = new RPCLink({
-  eventIteratorKeepAliveEnabled: true,
-  eventIteratorKeepAliveInterval: 5000, // 5 seconds
-  eventIteratorKeepAliveComment: '',
-})
-```
-
 ## Lifecycle
 
 ```mermaid

apps/content/docs/openapi/client/openapi-link.md

@@ -154,28 +154,6 @@ const link = new OpenAPILink({
 
 Unlike traditional SSE, the [Event Iterator](/docs/event-iterator) does not automatically retry on error. To enable automatic retries, refer to the [Client Retry Plugin](/docs/plugins/client-retry).
 
-## Event Iterator Keep Alive
-
-:::warning
-These options for sending [Event Iterator](/docs/event-iterator) from **client to the server**, not from **the server to client** as used in [RPCHandler Event Iterator Keep Alive](/docs/rpc-handler#event-iterator-keep-alive) or [OpenAPIHandler Event Iterator Keep Alive](/docs/openapi/openapi-handler#event-iterator-keep-alive).
-
-**In 99% of cases, you don't need to configure these options.**
-:::
-
-To keep [Event Iterator](/docs/event-iterator) connections alive, `OpenAPILink` periodically sends a ping comment to the server. You can configure this behavior using the following options:
-
-- `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
-- `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
-- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping messages.
-
-```ts
-const link = new OpenAPILink({
-  eventIteratorKeepAliveEnabled: true,
-  eventIteratorKeepAliveInterval: 5000, // 5 seconds
-  eventIteratorKeepAliveComment: '',
-})
-```
-
 ## Lifecycle
 
 The `OpenAPILink` follows the same lifecycle as the [RPCLink Lifecycle](/docs/client/rpc-link#lifecycle), ensuring consistent behavior across different link types.

apps/content/docs/openapi/openapi-handler.md

@@ -102,22 +102,6 @@ const handler = new OpenAPIHandler(router, {
 })
 ```
 
-## Event Iterator Keep Alive
-
-To keep [Event Iterator](/docs/event-iterator) connections alive, `OpenAPIHandler` periodically sends a ping comment to the client. You can configure this behavior using the following options:
-
-- `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
-- `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
-- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping comments.
-
-```ts
-const handler = new OpenAPIHandler(router, {
-  eventIteratorKeepAliveEnabled: true,
-  eventIteratorKeepAliveInterval: 5000, // 5 seconds
-  eventIteratorKeepAliveComment: '',
-})
-```
-
 ## Lifecycle
 
 The `OpenAPIHandler` follows the same lifecycle as the [RPCHandler Lifecycle](/docs/rpc-handler#lifecycle), ensuring consistent behavior across different handler types.

apps/content/docs/rpc-handler.md

@@ -83,22 +83,6 @@ const handler = new RPCHandler(router, {
 })
 ```
 
-## Event Iterator Keep Alive
-
-To keep [Event Iterator](/docs/event-iterator) connections alive, `RPCHandler` periodically sends a ping comment to the client. You can configure this behavior using the following options:
-
-- `eventIteratorKeepAliveEnabled` (default: `true`) – Enables or disables pings.
-- `eventIteratorKeepAliveInterval` (default: `5000`) – Time between pings (in milliseconds).
-- `eventIteratorKeepAliveComment` (default: `''`) – Custom content for ping comments.
-
-```ts
-const handler = new RPCHandler(router, {
-  eventIteratorKeepAliveEnabled: true,
-  eventIteratorKeepAliveInterval: 5000, // 5 seconds
-  eventIteratorKeepAliveComment: '',
-})
-```
-
 ## Default Plugins
 
 `RPCHandler` automatically enables **essential plugins** for security reasons.

packages/standard-server-aws-lambda/src/response.test.ts

@@ -130,6 +130,7 @@ describe('sendStandardResponse', () => {
     })
 
     expect(chunks).toEqual([
+      Buffer.from(': \n\n'),
       Buffer.from('event: message\ndata: "foo"\n\n'),
       Buffer.from('event: message\ndata: "bar"\n\n'),
     ])
@@ -175,6 +176,7 @@ describe('sendStandardResponse', () => {
       await new Promise(r => setTimeout(r, 110))
 
       expect(chunks).toEqual([
+        Buffer.from(': \n\n'),
         Buffer.from('event: message\ndata: 1\n\n'),
         Buffer.from('event: message\ndata: 2\n\n'),
       ])
@@ -229,6 +231,7 @@ describe('sendStandardResponse', () => {
       await new Promise(r => setTimeout(r, 110))
 
       expect(chunks).toEqual([
+        Buffer.from(': \n\n'),
         Buffer.from('event: message\ndata: 1\n\n'),
         Buffer.from('event: message\ndata: 2\n\n'),
       ])

packages/standard-server-fastify/src/response.test.ts

@@ -179,7 +179,7 @@ describe('sendStandardResponse', () => {
       'x-custom-header': 'custom-value',
     })
 
-    expect(res.text).toEqual('event: message\ndata: "foo"\n\nevent: message\ndata: "bar"\n\nevent: done\ndata: "baz"\n\n')
+    expect(res.text).toEqual(': \n\nevent: message\ndata: "foo"\n\nevent: message\ndata: "bar"\n\nevent: done\ndata: "baz"\n\n')
   })
 
   describe('edge case', () => {

packages/standard-server-fetch/src/body.test.ts

@@ -296,6 +296,7 @@ describe('toFetchBody', () => {
 
     const reader = (body as ReadableStream).pipeThrough(new TextDecoderStream()).getReader()
 
+    expect(await reader.read()).toEqual({ done: false, value: ': \n\n' })
     expect(await reader.read()).toEqual({ done: false, value: 'event: message\ndata: 123\n\n' })
     expect(await reader.read()).toEqual({ done: false, value: 'event: done\ndata: 456\n\n' })
   })