Skip to content
xs

Built-in HTTP Server

xs serve includes an optional HTTP server that can expose your event stream over HTTP/HTTPS. This is distinct from the store supervisor API (which uses Unix domain sockets) and is meant for serving external web requests.

Starting the Server

Enable the HTTP server by passing the --http flag with a port:

Terminal window
xs serve ./store --http :5007

How it Works

  1. When a request arrives, the server creates an http.request event with metadata about the request
  2. You can respond by appending an http.response event referencing the request ID
  3. The server processes the response and sends it back to the client

Request Events

Incoming requests generate events with this structure:

{
  "topic": "http.request",
  "id": "03cp38qrua78v15fkmiaq6baz",
  "meta": {
    "method": "GET",
    "uri": "/",
    "headers": {
      "host": "localhost:5007"
    },
    "query": {}
  }
}

Response Format

To respond, append an event:

Terminal window
echo '<h1>Hello</h1>' | xs append ./store http.response \
  --meta '{
    "request_id": "03cp38qrua78v15fkmiaq6baz",
    "status": 200,
    "headers": {
      "Content-Type": "text/html"
    }
  }'

Response metadata fields:

  • request_id: ID of the request event (required)
  • status: HTTP status code (default: 200)
  • headers: Response headers
  • more: Enable streaming responses (default: false)

Streaming Responses

Use the more flag to keep connections open for streaming:

Terminal window
# Initial response with headers
echo 'data: event 1' | xs append ./store http.response \
  --meta '{
    "request_id": "03cp38qrua78v15fkmiaq6baz",
    "headers": {"Content-Type": "text/event-stream"},
    "more": true
  }'


# Stream additional data
echo 'data: event 2' | xs append ./store http.response \
  --meta '{
    "request_id": "03cp38qrua78v15fkmiaq6baz",
    "more": true
  }'


# Close the stream
xs append ./store http.response \
  --meta '{
    "request_id": "03cp38qrua78v15fkmiaq6baz",
    "more": false
  }'