Real-time events

​

Subscribe

curl -N 'http://localhost:3333/api/kiwi/events' \
  -H 'Authorization: Bearer kiwi_sk_...'

event: write
data: {"op":"write","path":"concepts/auth.md","actor":"agent:docs-writer","etag":"5d41402abc4b2a76"}

event: delete
data: {"op":"delete","path":"drafts/old.md","actor":"alice"}

event: bulk
data: {"op":"bulk","paths":["notes/a.md","notes/b.md"],"actor":"agent:importer"}

:keep-alive

event: comment.add
data: {"op":"comment.add","path":"concepts/auth.md","actor":"bob"}

const events = new EventSource("/api/kiwi/events");

events.addEventListener("write", (e) => {
  const { path, etag, actor } = JSON.parse(e.data);
  console.log(`${actor} wrote ${path} (${etag})`);
});

events.addEventListener("delete", (e) => {
  console.log("deleted", JSON.parse(e.data).path);
});

import json, requests

with requests.get("http://localhost:3333/api/kiwi/events",
                  headers={"Authorization": "Bearer kiwi_sk_..."}, stream=True) as r:
    event = None
    for line in r.iter_lines(decode_unicode=True):
        if line.startswith("event: "):
            event = line[7:]
        elif line.startswith("data: "):
            print(event, json.loads(line[6:]))

​

Event types

​

When events fire

​

Client guidance

• Reconnect. The stream stays open until either side closes it. Reconnect with backoff when it drops. Browsers’ EventSource does this for you.
• Resync after a gap. Events have no IDs, and KiwiFS ignores Last-Event-ID. After reconnecting, catch up with GET /api/kiwi/changes or by re-reading the files you care about.
• Keep up. Each subscriber has a small buffer. A client that reads too slowly misses events instead of slowing the server.
• Authenticate like any other /api/kiwi route. The browser EventSource API cannot send an Authorization header, so when auth is on, browser clients need a same-origin proxy that adds it.
• Limits. A space accepts up to 256 concurrent subscribers. Beyond that, the endpoint returns 503.
• Spaces. Each space has its own stream. Subscribe to /api/kiwi/{space}/events, or send X-Kiwi-Space. See Multi-space.

​

Related