athena_rs 2.9.1

# CDC WebSocket


The CDC (Change Data Capture) WebSocket server streams events to clients. Connect with the `X-Athena-Client` header and optionally send **travel** messages to replay buffered events.

## Connecting


- **URL:** `ws://host:port/ws` when the server is plain HTTP. Use `wss://` only when the server is behind TLS (e.g. a reverse proxy). Using `wss://` against a non-TLS server produces an SSL `WRONG_VERSION_NUMBER` error.
- **Header:** Send `X-Athena-Client: <client_name>` on the WebSocket upgrade request. The server returns **400 Bad Request** with a JSON body if this header is missing. The value is your logical client name (e.g. the same as for the REST API).

### Example (Node with `ws`)


```js
const WebSocket = require("ws");
const ws = new WebSocket("ws://localhost:4053/ws", {
  headers: { "X-Athena-Client": "athena_logging" },
});
ws.on("message", (data) => console.log(data.toString()));
```

---

## Messages you send (client → server)


Send **JSON text frames** only.

### Travel (replay)


Request a replay of buffered events for a channel (optionally filtered by sequence or time).

```json
{
  "type": "travel",
  "organization_id": "athena_logging",
  "since_seq": 0,
  "since_ts_ms": 1700000000000,
  "limit": 1000
}
```

| Field             | Required | Description                                                               |
| ----------------- | -------- | ------------------------------------------------------------------------- |
| `type`            | Yes      | Must be `"travel"`.                                                       |
| `organization_id` | No       | Channel to replay. Omit to replay **all** channels you are subscribed to. |
| `since_seq`       | No       | Only events with `seq` **greater than** this value.                       |
| `since_ts_ms`     | No       | Only events with `ts_ms` **≥** this (milliseconds since Unix epoch).      |
| `limit`           | No       | Max events to return (default 10 000, max 50 000).                        |

**Examples:**

- Replay last 100 events for the current client:  
  `{"type":"travel","limit":100}`
- Replay for a specific channel after a sequence number:  
  `{"type":"travel","organization_id":"athena_logging","since_seq":42,"limit":500}`

You do not need to send any message if you only want **live** events; the server pushes those automatically after the initial subscription confirmation.

---

## Messages you receive (server → client)


All messages are **JSON text frames**.

| When                       | Shape                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Right after connect        | `{"status":"subscribed","client_id":"...","message":"Subscribed via X-Athena-Client header"}`                                                         |
| Live or replayed CDC event | `{"organization_id":"...","data":{"seq":1,"ts_ms":...,"payload":{...}}}`                                                                              |
| After a **travel** request | One event object per replayed record, then an ack: `{"status":"travel_complete","organization_id":...,"since_seq":...,"since_ts_ms":...,"limit":...}` |

---

## Summary


- **Connect:** `ws://host:port/ws` with header `X-Athena-Client: <client_name>`.
- **Send (optional):** `{"type":"travel", ...}` when you want replay/catch-up.
- **Receive:** subscription confirmation, then `organization_id` + `data` event objects; after travel, a `travel_complete` ack.