@zooid/server 0.0.1

package/src/db/queries.ts

@@ -0,0 +1,450 @@
+
+import type {
+  Channel,
+  ChannelListItem,
+  Publisher,
+  ZooidEvent,
+  Webhook,
+  PollResult,
+  ServerIdentity,
+} from '../types';
+import { generateUlid } from '../lib/ulid';
+
+export async function createChannel(
+  db: D1Database,
+  channel: {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    is_public?: boolean;
+    schema?: Record<string, unknown>;
+    strict?: boolean;
+  },
+): Promise<Channel> {
+  const isPublic = channel.is_public === false ? 0 : 1;
+  const strict = channel.strict ? 1 : 0;
+  const schema = channel.schema ? JSON.stringify(channel.schema) : null;
+  const tags = channel.tags ? JSON.stringify(channel.tags) : null;
+
+  await db
+    .prepare(
+      `INSERT INTO channels (id, name, description, tags, is_public, schema, strict) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .bind(channel.id, channel.name, channel.description ?? null, tags, isPublic, schema, strict)
+    .run();
+
+  const row = await db
+    .prepare(`SELECT * FROM channels WHERE id = ?`)
+    .bind(channel.id)
+    .first<Channel>();
+
+  return row!;
+}
+
+export async function getChannel(
+  db: D1Database,
+  id: string,
+): Promise<Channel | null> {
+  return db.prepare(`SELECT * FROM channels WHERE id = ?`).bind(id).first<Channel>();
+}
+
+export async function listChannels(
+  db: D1Database,
+): Promise<ChannelListItem[]> {
+  const rows = await db
+    .prepare(
+      `SELECT
+        c.id,
+        c.name,
+        c.description,
+        c.tags,
+        c.is_public,
+        c.schema,
+        c.strict,
+        COALESCE(e.event_count, 0) as event_count,
+        e.last_event_at
+      FROM channels c
+      LEFT JOIN (
+        SELECT
+          channel_id,
+          COUNT(*) as event_count,
+          MAX(created_at) as last_event_at
+        FROM events
+        GROUP BY channel_id
+      ) e ON c.id = e.channel_id
+      ORDER BY c.created_at DESC`,
+    )
+    .all<{
+      id: string;
+      name: string;
+      description: string | null;
+      tags: string | null;
+      is_public: number;
+      schema: string | null;
+      strict: number;
+      event_count: number;
+      last_event_at: string | null;
+    }>();
+
+  const channels: ChannelListItem[] = [];
+
+  for (const row of rows.results) {
+    const publishers = await db
+      .prepare(`SELECT name FROM publishers WHERE channel_id = ?`)
+      .bind(row.id)
+      .all<{ name: string }>();
+
+    channels.push({
+      id: row.id,
+      name: row.name,
+      description: row.description,
+      tags: row.tags ? JSON.parse(row.tags) : [],
+      is_public: row.is_public === 1,
+      schema: row.schema ? JSON.parse(row.schema) : null,
+      strict: row.strict === 1,
+      event_count: row.event_count,
+      last_event_at: row.last_event_at,
+      publishers: publishers.results.map((p) => p.name),
+    });
+  }
+
+  return channels;
+}
+
+export async function createPublisher(
+  db: D1Database,
+  channelId: string,
+  name: string,
+): Promise<Publisher> {
+  const id = generateUlid();
+
+  await db
+    .prepare(
+      `INSERT INTO publishers (id, channel_id, name) VALUES (?, ?, ?)`,
+    )
+    .bind(id, channelId, name)
+    .run();
+
+  const row = await db
+    .prepare(`SELECT * FROM publishers WHERE id = ?`)
+    .bind(id)
+    .first<Publisher>();
+
+  return row!;
+}
+
+// --- Event queries ---
+
+const MAX_PAYLOAD_BYTES = 64 * 1024;
+const MAX_BATCH_SIZE = 100;
+const DEFAULT_POLL_LIMIT = 50;
+const DEFAULT_WEBHOOK_TTL_SECONDS = 3 * 24 * 60 * 60; // 3 days
+const MAX_WEBHOOK_TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days
+
+export async function createEvent(
+  db: D1Database,
+  event: {
+    channelId: string;
+    publisherId?: string | null;
+    type?: string | null;
+    data: unknown;
+  },
+): Promise<ZooidEvent> {
+  const dataStr = JSON.stringify(event.data);
+  if (new TextEncoder().encode(dataStr).length > MAX_PAYLOAD_BYTES) {
+    throw new Error('Event payload exceeds 64KB limit');
+  }
+
+  const id = generateUlid();
+
+  await db
+    .prepare(
+      `INSERT INTO events (id, channel_id, publisher_id, type, data) VALUES (?, ?, ?, ?, ?)`,
+    )
+    .bind(
+      id,
+      event.channelId,
+      event.publisherId ?? null,
+      event.type ?? null,
+      dataStr,
+    )
+    .run();
+
+  const row = await db
+    .prepare(`SELECT * FROM events WHERE id = ?`)
+    .bind(id)
+    .first<ZooidEvent>();
+
+  return row!;
+}
+
+export async function createEvents(
+  db: D1Database,
+  channelId: string,
+  publisherId: string | null,
+  events: Array<{ type?: string | null; data: unknown }>,
+): Promise<ZooidEvent[]> {
+  if (events.length > MAX_BATCH_SIZE) {
+    throw new Error(`Batch size exceeds maximum of ${MAX_BATCH_SIZE}`);
+  }
+
+  const ids: string[] = [];
+
+  for (const event of events) {
+    const dataStr = JSON.stringify(event.data);
+    if (new TextEncoder().encode(dataStr).length > MAX_PAYLOAD_BYTES) {
+      throw new Error('Event payload exceeds 64KB limit');
+    }
+
+    const id = generateUlid();
+    ids.push(id);
+
+    await db
+      .prepare(
+        `INSERT INTO events (id, channel_id, publisher_id, type, data) VALUES (?, ?, ?, ?, ?)`,
+      )
+      .bind(id, channelId, publisherId, event.type ?? null, dataStr)
+      .run();
+  }
+
+  const results: ZooidEvent[] = [];
+  for (const id of ids) {
+    const row = await db
+      .prepare(`SELECT * FROM events WHERE id = ?`)
+      .bind(id)
+      .first<ZooidEvent>();
+    results.push(row!);
+  }
+
+  return results;
+}
+
+export async function pollEvents(
+  db: D1Database,
+  channelId: string,
+  options: {
+    since?: string;
+    cursor?: string;
+    limit?: number;
+    type?: string;
+  },
+): Promise<PollResult> {
+  const limit = options.limit ?? DEFAULT_POLL_LIMIT;
+  const conditions: string[] = ['channel_id = ?'];
+  const bindings: unknown[] = [channelId];
+
+  if (options.since) {
+    conditions.push('created_at > ?');
+    bindings.push(options.since);
+  }
+
+  if (options.cursor) {
+    conditions.push('id > ?');
+    bindings.push(options.cursor);
+  }
+
+  if (options.type) {
+    conditions.push('type = ?');
+    bindings.push(options.type);
+  }
+
+  const sql = `SELECT * FROM events WHERE ${conditions.join(' AND ')} ORDER BY id ASC LIMIT ?`;
+  bindings.push(limit + 1);
+
+  const stmt = db.prepare(sql);
+  const result = await stmt.bind(...bindings).all<ZooidEvent>();
+  const rows = result.results;
+
+  const hasMore = rows.length > limit;
+  const events = hasMore ? rows.slice(0, limit) : rows;
+  const cursor = events.length > 0 ? events[events.length - 1].id : null;
+
+  return {
+    events,
+    cursor: hasMore ? cursor : null,
+    has_more: hasMore,
+  };
+}
+
+export async function cleanupExpiredEvents(
+  db: D1Database,
+  channelId: string,
+): Promise<number> {
+  const result = await db
+    .prepare(
+      `DELETE FROM events WHERE channel_id = ? AND created_at < datetime('now', '-7 days')`,
+    )
+    .bind(channelId)
+    .run();
+
+  return result.meta.changes ?? 0;
+}
+
+// --- Webhook queries ---
+
+export async function createWebhook(
+  db: D1Database,
+  webhook: {
+    channelId: string;
+    url: string;
+    eventTypes?: string[];
+    ttlSeconds?: number;
+  },
+): Promise<Webhook> {
+  const ttl = Math.min(
+    webhook.ttlSeconds ?? DEFAULT_WEBHOOK_TTL_SECONDS,
+    MAX_WEBHOOK_TTL_SECONDS,
+  );
+  const expiresAt = new Date(Date.now() + ttl * 1000).toISOString();
+  const eventTypes = webhook.eventTypes
+    ? JSON.stringify(webhook.eventTypes)
+    : null;
+  const id = generateUlid();
+
+  await db
+    .prepare(
+      `INSERT INTO webhooks (id, channel_id, url, event_types, expires_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(channel_id, url) DO UPDATE SET
+         expires_at = excluded.expires_at,
+         event_types = excluded.event_types`,
+    )
+    .bind(id, webhook.channelId, webhook.url, eventTypes, expiresAt)
+    .run();
+
+  // Fetch back — could be the new row or the updated existing one
+  const row = await db
+    .prepare(
+      `SELECT * FROM webhooks WHERE channel_id = ? AND url = ?`,
+    )
+    .bind(webhook.channelId, webhook.url)
+    .first<Webhook>();
+
+  return row!;
+}
+
+export async function deleteWebhook(
+  db: D1Database,
+  webhookId: string,
+  channelId: string,
+): Promise<boolean> {
+  const result = await db
+    .prepare(`DELETE FROM webhooks WHERE id = ? AND channel_id = ?`)
+    .bind(webhookId, channelId)
+    .run();
+
+  return (result.meta.changes ?? 0) > 0;
+}
+
+export async function getWebhooksForChannel(
+  db: D1Database,
+  channelId: string,
+  eventType?: string,
+): Promise<Webhook[]> {
+  if (eventType) {
+    // Return webhooks that match the event type OR have no filter (null = all events)
+    const result = await db
+      .prepare(
+        `SELECT * FROM webhooks
+         WHERE channel_id = ? AND expires_at > datetime('now')
+         AND (event_types IS NULL OR event_types LIKE ?)`,
+      )
+      .bind(channelId, `%"${eventType}"%`)
+      .all<Webhook>();
+    return result.results;
+  }
+
+  const result = await db
+    .prepare(
+      `SELECT * FROM webhooks WHERE channel_id = ? AND expires_at > datetime('now')`,
+    )
+    .bind(channelId)
+    .all<Webhook>();
+  return result.results;
+}
+
+// --- Server meta queries ---
+
+interface ServerMetaRow {
+  id: number;
+  name: string;
+  description: string | null;
+  tags: string | null;
+  owner: string | null;
+  company: string | null;
+  email: string | null;
+  updated_at: string;
+}
+
+function rowToServerMeta(row: ServerMetaRow): ServerIdentity {
+  return {
+    name: row.name,
+    description: row.description,
+    tags: row.tags ? JSON.parse(row.tags) : [],
+    owner: row.owner,
+    company: row.company,
+    email: row.email,
+    updated_at: row.updated_at,
+  };
+}
+
+export async function getServerMeta(
+  db: D1Database,
+): Promise<ServerIdentity | null> {
+  const row = await db
+    .prepare(`SELECT * FROM server_meta WHERE id = 1`)
+    .first<ServerMetaRow>();
+
+  return row ? rowToServerMeta(row) : null;
+}
+
+export async function upsertServerMeta(
+  db: D1Database,
+  meta: {
+    name?: string;
+    description?: string | null;
+    tags?: string[];
+    owner?: string | null;
+    company?: string | null;
+    email?: string | null;
+  },
+): Promise<ServerIdentity> {
+  const tags = meta.tags ? JSON.stringify(meta.tags) : null;
+
+  await db
+    .prepare(
+      `INSERT INTO server_meta (id, name, description, tags, owner, company, email, updated_at)
+       VALUES (1, ?, ?, ?, ?, ?, ?, datetime('now'))
+       ON CONFLICT(id) DO UPDATE SET
+         name = COALESCE(?, server_meta.name),
+         description = ?,
+         tags = ?,
+         owner = ?,
+         company = ?,
+         email = ?,
+         updated_at = datetime('now')`,
+    )
+    .bind(
+      meta.name ?? 'Zooid',
+      meta.description ?? null,
+      tags,
+      meta.owner ?? null,
+      meta.company ?? null,
+      meta.email ?? null,
+      // ON CONFLICT values
+      meta.name ?? null,
+      meta.description ?? null,
+      tags,
+      meta.owner ?? null,
+      meta.company ?? null,
+      meta.email ?? null,
+    )
+    .run();
+
+  const row = await db
+    .prepare(`SELECT * FROM server_meta WHERE id = 1`)
+    .first<ServerMetaRow>();
+
+  return rowToServerMeta(row!);
+}

package/src/db/schema.sql

@@ -0,0 +1,56 @@
+CREATE TABLE IF NOT EXISTS channels (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  description TEXT,
+  tags TEXT,
+  is_public INTEGER NOT NULL DEFAULT 1,
+  schema TEXT,
+  strict INTEGER NOT NULL DEFAULT 0,
+  max_subscribers INTEGER DEFAULT 100,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS events (
+  id TEXT PRIMARY KEY,
+  channel_id TEXT NOT NULL,
+  publisher_id TEXT,
+  type TEXT,
+  data TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (channel_id) REFERENCES channels(id)
+);
+
+CREATE TABLE IF NOT EXISTS webhooks (
+  id TEXT PRIMARY KEY,
+  channel_id TEXT NOT NULL,
+  url TEXT NOT NULL,
+  event_types TEXT,
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (channel_id) REFERENCES channels(id)
+);
+
+CREATE TABLE IF NOT EXISTS publishers (
+  id TEXT PRIMARY KEY,
+  channel_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (channel_id) REFERENCES channels(id)
+);
+
+CREATE TABLE IF NOT EXISTS server_meta (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  name TEXT NOT NULL DEFAULT 'Zooid',
+  description TEXT,
+  tags TEXT,
+  owner TEXT,
+  company TEXT,
+  email TEXT,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_channel_created ON events(channel_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_events_channel_type ON events(channel_id, type);
+CREATE INDEX IF NOT EXISTS idx_webhooks_channel ON webhooks(channel_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_webhooks_channel_url ON webhooks(channel_id, url);
+CREATE INDEX IF NOT EXISTS idx_publishers_channel ON publishers(channel_id);

package/src/do/channel.ts

@@ -0,0 +1,69 @@
+import { DurableObject } from 'cloudflare:workers';
+import type { Bindings } from '../types';
+
+const TAG_ALL = 'type:*';
+const TAG_PREFIX = 'type:';
+
+export class ChannelDO extends DurableObject<Bindings> {
+  async fetch(request: Request): Promise<Response> {
+    const upgradeHeader = request.headers.get('Upgrade');
+    if (upgradeHeader !== 'websocket') {
+      return new Response('Expected WebSocket upgrade', { status: 426 });
+    }
+
+    const url = new URL(request.url);
+    const typesParam = url.searchParams.get('types');
+
+    const tags: string[] = [];
+    if (typesParam) {
+      for (const t of typesParam.split(',')) {
+        const trimmed = t.trim();
+        if (trimmed) tags.push(TAG_PREFIX + trimmed);
+      }
+    }
+    // No types specified → receive all events
+    if (tags.length === 0) tags.push(TAG_ALL);
+
+    const pair = new WebSocketPair();
+    this.ctx.acceptWebSocket(pair[1], tags);
+
+    return new Response(null, { status: 101, webSocket: pair[0] });
+  }
+
+  async broadcast(event: Record<string, unknown>): Promise<void> {
+    const message = JSON.stringify(event);
+    const eventType = typeof event.type === 'string' ? event.type : null;
+
+    // Collect sockets that should receive this event
+    const targets = new Set<WebSocket>();
+
+    // Unfiltered sockets always receive
+    for (const ws of this.ctx.getWebSockets(TAG_ALL)) {
+      targets.add(ws);
+    }
+
+    // If the event has a type, also include sockets subscribed to that type
+    if (eventType) {
+      for (const ws of this.ctx.getWebSockets(TAG_PREFIX + eventType)) {
+        targets.add(ws);
+      }
+    }
+
+    for (const ws of targets) {
+      try {
+        ws.send(message);
+      } catch {
+        // Client disconnected — close silently
+        try {
+          ws.close(1011, 'Broadcast failed');
+        } catch {
+          // Already closed
+        }
+      }
+    }
+  }
+
+  webSocketMessage() {}
+  webSocketClose() {}
+  webSocketError() {}
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+import { Hono } from 'hono';
+import { fromHono } from 'chanfana';
+import type { Bindings, Variables } from './types';
+import { wellKnown } from './routes/well-known';
+import { requireAuth, requireScope, requireSubscribeIfPrivate } from './middleware/auth';
+import { ListChannels, CreateChannel, AddPublisher } from './routes/channels';
+import { PublishEvents, PollEvents } from './routes/events';
+import { RegisterWebhook, DeleteWebhook } from './routes/webhooks';
+import { GetServerMeta, UpdateServerMeta } from './routes/server-meta';
+import { DirectoryClaim } from './routes/directory';
+import { ws } from './routes/ws';
+import { rss } from './routes/rss';
+import { feed } from './routes/feed';
+import { opml } from './routes/opml';
+
+type Env = { Bindings: Bindings; Variables: Variables };
+
+const app = new Hono<Env>();
+
+// Well-known stays at root
+app.route('', wellKnown);
+
+// All API routes under /api
+const api = new Hono<Env>();
+const openapi = fromHono(api, {
+  docs_url: '/docs',
+  redoc_url: null,
+  openapi_url: '/openapi.json',
+  schema: {
+    info: {
+      title: 'Zooid',
+      version: '0.1.0',
+      description: 'Pub/sub for AI agents',
+    },
+    security: [{ bearerAuth: [] }],
+  },
+});
+openapi.registry.registerComponent('securitySchemes', 'bearerAuth', {
+  type: 'http',
+  scheme: 'bearer',
+  bearerFormat: 'JWT',
+});
+
+// Server meta routes
+openapi.get('/server', GetServerMeta);
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.put('/server', requireAuth(), requireScope('admin'), UpdateServerMeta);
+
+// Channel routes
+openapi.get('/channels', ListChannels);
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.post('/channels', requireAuth(), requireScope('admin'), CreateChannel);
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.post('/channels/:channelId/publishers', requireAuth(), requireScope('admin'), AddPublisher);
+
+// Event routes
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.post('/channels/:channelId/events', requireAuth(), requireScope('publish', { channelParam: 'channelId' }), PublishEvents);
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.get('/channels/:channelId/events', requireSubscribeIfPrivate('channelId'), PollEvents);
+
+// Directory claim route
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.post('/directory/claim', requireAuth(), requireScope('admin'), DirectoryClaim);
+
+// Webhook routes
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.post('/channels/:channelId/webhooks', requireSubscribeIfPrivate('channelId'), RegisterWebhook);
+// prettier-ignore
+// @ts-expect-error chanfana types don't include middleware overloads
+openapi.delete('/channels/:channelId/webhooks/:webhookId', requireAuth(), requireScope('admin'), DeleteWebhook);
+
+// Plain Hono routes (streaming/XML — not suited for OpenAPI)
+api.route('', ws);
+api.route('', rss);
+api.route('', feed);
+api.route('', opml);
+
+api.get('/', (c) => c.json({ ok: true }));
+app.route('/api/v1', api);
+
+export { ChannelDO } from './do/channel';
+export default app;