@zooid/server 0.0.1

package/src/routes/events.ts

@@ -0,0 +1,315 @@
+import { OpenAPIRoute } from 'chanfana';
+import { z } from 'zod';
+import type { Context } from 'hono';
+import type { Bindings, Variables } from '../types';
+import {
+  getChannel,
+  createEvent,
+  createEvents,
+  pollEvents,
+  cleanupExpiredEvents,
+  getWebhooksForChannel,
+} from '../db/queries';
+import { importPrivateKey, signPayload } from '../lib/signing';
+import { validateEvent } from '../lib/schema-validator';
+
+type Env = { Bindings: Bindings; Variables: Variables };
+
+export class PublishEvents extends OpenAPIRoute {
+  schema = {
+    summary: 'Publish event(s) to a channel',
+    tags: ['Events'],
+    security: [{ bearerAuth: [] }],
+    request: {
+      params: z.object({
+        channelId: z.string(),
+      }),
+      body: {
+        content: {
+          'application/json': {
+            schema: z.object({
+              type: z.string().optional(),
+              data: z.unknown().optional(),
+              events: z
+                .array(
+                  z.object({
+                    type: z.string().optional(),
+                    data: z.unknown(),
+                  }),
+                )
+                .optional(),
+            }),
+          },
+        },
+      },
+    },
+    responses: {
+      201: {
+        description: 'Event(s) published',
+        content: {
+          'application/json': {
+            schema: z.union([
+              z.object({
+                id: z.string(),
+                channel_id: z.string(),
+                type: z.string().nullable(),
+                data: z.string(),
+                publisher_id: z.string().nullable(),
+                created_at: z.string(),
+              }),
+              z.object({
+                events: z.array(
+                  z.object({
+                    id: z.string(),
+                    channel_id: z.string(),
+                    type: z.string().nullable(),
+                    data: z.string(),
+                    publisher_id: z.string().nullable(),
+                    created_at: z.string(),
+                  }),
+                ),
+              }),
+            ]),
+          },
+        },
+      },
+      400: {
+        description: 'Validation error',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+      404: {
+        description: 'Channel not found',
+        content: {
+          'application/json': {
+            schema: z.object({ error: z.string() }),
+          },
+        },
+      },
+    },
+  };
+
+  async handle(c: Context<Env>) {
+    const data = await this.getValidatedData<typeof this.schema>();
+    const { channelId } = data.params;
+    const db = c.env.DB;
+
+    const channel = await getChannel(db, channelId);
+    if (!channel) {
+      return c.json({ error: 'Channel not found' }, 404);
+    }
+
+    const body = data.body;
+    const jwt = c.get('jwtPayload');
+    const publisherId = jwt.sub ?? null;
+
+    const strictSchema =
+      channel.strict && channel.schema
+        ? (JSON.parse(channel.schema) as Record<
+            string,
+            {
+              required?: string[];
+              properties?: Record<string, unknown>;
+            }
+          >)
+        : null;
+
+    // Batch publish
+    if ('events' in body && Array.isArray(body.events)) {
+      for (const evt of body.events) {
+        if (evt.data === undefined) {
+          return c.json(
+            { error: 'Each event must include a data field' },
+            400,
+          );
+        }
+      }
+
+      if (strictSchema) {
+        for (const evt of body.events) {
+          const result = validateEvent(strictSchema, evt.type, evt.data);
+          if (!result.valid) {
+            return c.json({ error: result.error }, 400);
+          }
+        }
+      }
+
+      const created = await createEvents(
+        db,
+        channelId,
+        publisherId,
+        body.events,
+      );
+
+      const fanOut = async () => {
+        try {
+          const doId = c.env.CHANNEL_DO.idFromName(channelId);
+          const stub = c.env.CHANNEL_DO.get(doId);
+          for (const event of created) {
+            await stub.broadcast(event as unknown as Record<string, unknown>);
+          }
+        } catch {
+          // CHANNEL_DO binding may not exist in tests
+        }
+        for (const event of created) {
+          await deliverToWebhooks(c.env, channelId, event);
+        }
+      };
+      try {
+        c.executionCtx.waitUntil(fanOut());
+      } catch {
+        await fanOut();
+      }
+
+      return c.json({ events: created }, 201);
+    }
+
+    // Single publish
+    if (!('data' in body) || body.data === undefined) {
+      return c.json({ error: 'Event must include a data field' }, 400);
+    }
+
+    if (strictSchema) {
+      const result = validateEvent(strictSchema, body.type, body.data);
+      if (!result.valid) {
+        return c.json({ error: result.error }, 400);
+      }
+    }
+
+    const event = await createEvent(db, {
+      channelId,
+      publisherId,
+      type: body.type ?? null,
+      data: body.data,
+    });
+
+    const afterPublish = async () => {
+      try {
+        const doId = c.env.CHANNEL_DO.idFromName(channelId);
+        const stub = c.env.CHANNEL_DO.get(doId);
+        await stub.broadcast(event as unknown as Record<string, unknown>);
+      } catch {
+        // CHANNEL_DO binding may not exist in tests
+      }
+      await deliverToWebhooks(c.env, channelId, event);
+    };
+    try {
+      c.executionCtx.waitUntil(afterPublish());
+    } catch {
+      // No execution context in tests
+    }
+
+    return c.json(event, 201);
+  }
+}
+
+export class PollEvents extends OpenAPIRoute {
+  schema = {
+    summary: 'Poll events from a channel',
+    tags: ['Events'],
+    request: {
+      params: z.object({
+        channelId: z.string(),
+      }),
+      query: z.object({
+        since: z.string().optional(),
+        cursor: z.string().optional(),
+        type: z.string().optional(),
+        limit: z.coerce.number().int().min(1).max(100).optional(),
+      }),
+    },
+    responses: {
+      200: {
+        description: 'Polled events',
+        content: {
+          'application/json': {
+            schema: z.object({
+              events: z.array(
+                z.object({
+                  id: z.string(),
+                  channel_id: z.string(),
+                  type: z.string().nullable(),
+                  data: z.string(),
+                  publisher_id: z.string().nullable(),
+                  created_at: z.string(),
+                }),
+              ),
+              cursor: z.string().nullable(),
+              has_more: z.boolean(),
+            }),
+          },
+        },
+      },
+    },
+  };
+
+  async handle(c: Context<Env>) {
+    const data = await this.getValidatedData<typeof this.schema>();
+    const { channelId } = data.params;
+    const db = c.env.DB;
+
+    await cleanupExpiredEvents(db, channelId);
+
+    const { since, cursor, type, limit } = data.query;
+
+    const result = await pollEvents(db, channelId, {
+      since,
+      cursor,
+      type,
+      limit,
+    });
+
+    if (c.get('channelIsPublic')) {
+      const maxAge = parseInt(c.env.ZOOID_POLL_INTERVAL ?? '2', 10);
+      c.header('Cache-Control', `public, s-maxage=${maxAge}`);
+    }
+
+    return c.json(result);
+  }
+}
+
+async function deliverToWebhooks(
+  env: Bindings,
+  channelId: string,
+  event: { id: string; type: string | null },
+) {
+  const webhooks = await getWebhooksForChannel(
+    env.DB,
+    channelId,
+    event.type ?? undefined,
+  );
+
+  if (webhooks.length === 0) return;
+
+  const signingKey = env.ZOOID_SIGNING_KEY
+    ? await importPrivateKey(env.ZOOID_SIGNING_KEY)
+    : null;
+
+  const body = JSON.stringify(event as unknown as Record<string, unknown>);
+  const timestamp = new Date().toISOString();
+
+  const signature = signingKey
+    ? await signPayload(signingKey, timestamp, body)
+    : null;
+
+  await Promise.allSettled(
+    webhooks.map((webhook) => {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'X-Zooid-Timestamp': timestamp,
+        'X-Zooid-Channel': channelId,
+        'X-Zooid-Event-Id': event.id,
+        'X-Zooid-Key-Id': env.ZOOID_SERVER_ID || 'zooid-local',
+      };
+
+      if (signature) {
+        headers['X-Zooid-Signature'] = signature;
+      }
+
+      return fetch(webhook.url, { method: 'POST', headers, body });
+    }),
+  );
+}

package/src/routes/feed.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import { env } from 'cloudflare:test';
+import app from '../index';
+import { setupTestDb, cleanTestDb } from '../test-utils';
+import { createToken } from '../lib/jwt';
+
+interface FeedBody {
+  version: string;
+  title: string;
+  description: string;
+  items: Array<{
+    id: string;
+    title: string;
+    content_text: string;
+    tags: string[];
+    _zooid: { data: unknown };
+  }>;
+}
+
+const JWT_SECRET = 'test-jwt-secret';
+
+async function adminRequest(path: string, options: RequestInit = {}) {
+  const token = await createToken({ scope: 'admin' }, JWT_SECRET);
+  const headers = new Headers(options.headers);
+  headers.set('Authorization', `Bearer ${token}`);
+  headers.set('Content-Type', 'application/json');
+  return app.request(
+    path,
+    { ...options, headers },
+    { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+  );
+}
+
+async function publishRequest(
+  path: string,
+  options: RequestInit = {},
+  channel: string,
+) {
+  const token = await createToken(
+    { scope: 'publish', channel, sub: 'test-publisher' },
+    JWT_SECRET,
+  );
+  const headers = new Headers(options.headers);
+  headers.set('Authorization', `Bearer ${token}`);
+  headers.set('Content-Type', 'application/json');
+  return app.request(
+    path,
+    { ...options, headers },
+    { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+  );
+}
+
+describe('JSON Feed routes', () => {
+  beforeAll(async () => {
+    await setupTestDb();
+  });
+
+  beforeEach(async () => {
+    await cleanTestDb();
+    await adminRequest('/api/v1/channels', {
+      method: 'POST',
+      body: JSON.stringify({
+        id: 'feed-channel',
+        name: 'Feed Channel',
+        description: 'Test JSON feed',
+        is_public: true,
+      }),
+    });
+    await adminRequest('/api/v1/channels', {
+      method: 'POST',
+      body: JSON.stringify({
+        id: 'priv-feed',
+        name: 'Private Feed',
+        is_public: false,
+      }),
+    });
+  });
+
+  describe('GET /channels/:channelId/feed.json', () => {
+    it('returns valid JSON Feed with correct content type', async () => {
+      await publishRequest(
+        '/api/v1/channels/feed-channel/events',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            type: 'signal',
+            data: { market: 'test', shift: 0.05 },
+          }),
+        },
+        'feed-channel',
+      );
+
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+
+      expect(res.status).toBe(200);
+      expect(res.headers.get('Content-Type')).toBe('application/feed+json');
+
+      const body = await res.json() as FeedBody;
+      expect(body.version).toBe('https://jsonfeed.org/version/1.1');
+      expect(body.title).toBe('Feed Channel');
+      expect(body.description).toBe('Test JSON feed');
+      expect(body.items).toHaveLength(1);
+      expect(body.items[0].id).toBeDefined();
+      expect(body.items[0]._zooid).toBeDefined();
+      expect(body.items[0]._zooid.data).toEqual({ market: 'test', shift: 0.05 });
+    });
+
+    it('formats data as YAML by default', async () => {
+      await publishRequest(
+        '/api/v1/channels/feed-channel/events',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            type: 'signal',
+            data: { market: 'election', shift: 0.07 },
+          }),
+        },
+        'feed-channel',
+      );
+
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+
+      const body = await res.json() as FeedBody;
+      // YAML-style: key: value
+      expect(body.items[0].content_text).toContain('market: election');
+      expect(body.items[0].content_text).toContain('shift: 0.07');
+    });
+
+    it('formats data as JSON when format=json', async () => {
+      await publishRequest(
+        '/api/v1/channels/feed-channel/events',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            type: 'signal',
+            data: { market: 'election' },
+          }),
+        },
+        'feed-channel',
+      );
+
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json?format=json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+
+      const body = await res.json() as FeedBody;
+      expect(body.items[0].content_text).toContain('"market"');
+    });
+
+    it('includes event type and publisher in item title', async () => {
+      await publishRequest(
+        '/api/v1/channels/feed-channel/events',
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            type: 'odds_shift',
+            data: { v: 1 },
+          }),
+        },
+        'feed-channel',
+      );
+
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+
+      const body = await res.json() as FeedBody;
+      expect(body.items[0].title).toContain('[odds_shift]');
+      expect(body.items[0].title).toContain('test-publisher');
+      expect(body.items[0].tags).toEqual(['odds_shift']);
+    });
+
+    it('returns empty feed when no events', async () => {
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+
+      expect(res.status).toBe(200);
+      const body = await res.json() as FeedBody;
+      expect(body.version).toBe('https://jsonfeed.org/version/1.1');
+      expect(body.items).toEqual([]);
+    });
+
+    it('allows public channel without auth', async () => {
+      const res = await app.request(
+        '/api/v1/channels/feed-channel/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+      expect(res.status).toBe(200);
+    });
+
+    it('requires token query param for private channel', async () => {
+      const res = await app.request(
+        '/api/v1/channels/priv-feed/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+      expect(res.status).toBe(401);
+    });
+
+    it('accepts token via query param for private channel', async () => {
+      const token = await createToken(
+        { scope: 'subscribe', channel: 'priv-feed', sub: 'sub-1' },
+        JWT_SECRET,
+      );
+      const res = await app.request(
+        `/api/v1/channels/priv-feed/feed.json?token=${token}`,
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+      expect(res.status).toBe(200);
+    });
+
+    it('returns 404 for non-existent channel', async () => {
+      const res = await app.request(
+        '/api/v1/channels/nonexistent/feed.json',
+        {},
+        { ...env, ZOOID_JWT_SECRET: JWT_SECRET },
+      );
+      expect(res.status).toBe(404);
+    });
+  });
+});

package/src/routes/feed.ts

@@ -0,0 +1,101 @@
+import { Hono } from 'hono';
+import { stringify } from 'yaml';
+import type { Bindings, Variables, ZooidEvent } from '../types';
+import { getChannel } from '../db/queries';
+import { pollEvents, cleanupExpiredEvents } from '../db/queries';
+import { verifyToken } from '../lib/jwt';
+
+type Env = { Bindings: Bindings; Variables: Variables };
+
+export const feed = new Hono<Env>();
+
+feed.get('/channels/:channelId/feed.json', async (c) => {
+  const channelId = c.req.param('channelId');
+  const db = c.env.DB;
+
+  const channel = await getChannel(db, channelId);
+  if (!channel) {
+    return c.json({ error: 'Channel not found' }, 404);
+  }
+
+  // Auth: public channels need no auth, private channels use ?token= query param
+  if (channel.is_public !== 1) {
+    const tokenStr = c.req.query('token');
+    if (!tokenStr) {
+      return c.json(
+        { error: 'Subscribe token required for private channel' },
+        401,
+      );
+    }
+
+    try {
+      const payload = await verifyToken(tokenStr, c.env.ZOOID_JWT_SECRET);
+      if (payload.scope !== 'admin' && payload.scope !== 'subscribe') {
+        return c.json({ error: 'Insufficient permissions' }, 403);
+      }
+      if (payload.scope === 'subscribe' && payload.channel !== channelId) {
+        return c.json({ error: 'Token not valid for this channel' }, 403);
+      }
+    } catch {
+      return c.json({ error: 'Invalid or expired token' }, 401);
+    }
+  }
+
+  await cleanupExpiredEvents(db, channelId);
+
+  const result = await pollEvents(db, channelId, { limit: 50 });
+  const format = c.req.query('format') || 'yaml';
+
+  const items = result.events.map((event) => formatItem(event, channelId, format));
+
+  const jsonFeed = {
+    version: 'https://jsonfeed.org/version/1.1',
+    title: channel.name,
+    description: channel.description || '',
+    items,
+  };
+
+  return c.json(jsonFeed, 200, {
+    'Content-Type': 'application/feed+json',
+  });
+});
+
+function formatItem(
+  event: ZooidEvent,
+  channelId: string,
+  format: string,
+): Record<string, unknown> {
+  const type = event.type || null;
+  const publisher = event.publisher_id || 'unknown';
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(event.data);
+  } catch {
+    data = {};
+  }
+
+  const contentText =
+    format === 'json' ? JSON.stringify(data, null, 2) : stringify(data).trim();
+
+  const titleLabel = type || 'event';
+
+  const item: Record<string, unknown> = {
+    id: event.id,
+    title: `[${titleLabel}] ${publisher}`,
+    content_text: contentText,
+    date_published: new Date(event.created_at).toISOString(),
+    _zooid: {
+      channel_id: channelId,
+      publisher_id: event.publisher_id || null,
+      type: type,
+      data,
+    },
+  };
+
+  if (type) {
+    item.tags = [type];
+  }
+
+  return item;
+}