Stream environment events

Streams state-change events for a VM as Server-Sent Events. Replaces polling GET /v1/environments/{vmId} for state transitions. The control-server should use this stream during provisioning instead of a 2s polling loop.

Event semantics

• The first event is always a snapshot of the current state, emitted immediately on connect. Clients do not need to GET first.
• Subsequent events fire on every state transition (provisioning → running → draining → destroying → destroyed / failed).
• The stream closes cleanly after a terminal event (destroyed or failed).
• The stream closes cleanly on client disconnect.
• A keepalive comment line (: keepalive\n\n) is emitted every 15s so proxies don’t idle-out the connection.

Wire format — standard SSE. Each event is two lines plus a blank-line terminator:

id: <128-bit hex>
data: {"event":"state","vm_id":"...","state":"running","url":"...","updated_at":"..."}

Replication caveat — this is a single-process pub/sub. Subscribers connected to a different orchestrator replica than the publishing replica will not see events. The orchestrator runs as a single process today, so this is acceptable; cross-replica fanout would require a Redis or NATS backplane.

curl -X GET "http://localhost:8080/v1/environments/string/events" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/environments/string/events", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "http://localhost:8080/v1/environments/string/events",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

{
  "id": "string",
  "event": "state",
  "vm_id": "string",
  "state": "provisioning",
  "url": "string",
  "error": "string",
  "updated_at": "2024-01-01T00:00:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "not_found",
    "message": "string",
    "details": {}
  }
}