@edge-base/server 0.1.1

package/src/lib/cloudflare-realtime.ts

@@ -0,0 +1,251 @@
+import type { Env } from '../types.js';
+
+const DEFAULT_CLOUDFLARE_REALTIME_BASE_URL = 'https://rtc.live.cloudflare.com/v1';
+
+export interface CloudflareRealtimeSessionDescription {
+  sdp: string;
+  type: 'offer' | 'answer';
+}
+
+export interface CloudflareRealtimeTrackObject {
+  location: 'local' | 'remote';
+  mid?: string;
+  sessionId?: string;
+  trackName?: string;
+  bidirectionalMediaStream?: boolean;
+  kind?: string;
+  simulcast?: {
+    preferredRid?: string;
+    priorityOrdering?: 'none' | 'asciibetical';
+    ridNotAvailable?: 'none' | 'asciibetical';
+  };
+}
+
+export interface CloudflareRealtimeNewSessionRequest {
+  sessionDescription?: CloudflareRealtimeSessionDescription;
+}
+
+export interface CloudflareRealtimeNewSessionResponse {
+  errorCode?: string;
+  errorDescription?: string;
+  sessionDescription?: CloudflareRealtimeSessionDescription;
+  sessionId: string;
+}
+
+export interface CloudflareRealtimeTracksRequest {
+  sessionDescription?: CloudflareRealtimeSessionDescription;
+  tracks: CloudflareRealtimeTrackObject[];
+  autoDiscover?: boolean;
+}
+
+export interface CloudflareRealtimeTracksResponse {
+  errorCode?: string;
+  errorDescription?: string;
+  requiresImmediateRenegotiation?: boolean;
+  sessionDescription?: CloudflareRealtimeSessionDescription;
+  tracks?: Array<CloudflareRealtimeTrackObject & {
+    errorCode?: string;
+    errorDescription?: string;
+  }>;
+}
+
+export interface CloudflareRealtimeRenegotiateRequest {
+  sessionDescription: CloudflareRealtimeSessionDescription;
+}
+
+export interface CloudflareRealtimeCloseTracksRequest {
+  sessionDescription?: CloudflareRealtimeSessionDescription;
+  tracks: Array<{ mid: string }>;
+  force?: boolean;
+}
+
+export interface CloudflareRealtimeIceServer {
+  urls: string[] | string;
+  username?: string;
+  credential?: string;
+}
+
+export interface CloudflareRealtimeIceServersResponse {
+  iceServers: CloudflareRealtimeIceServer[];
+}
+
+export interface CloudflareRealtimeEnv {
+  CF_REALTIME_APP_ID?: string;
+  CF_REALTIME_APP_SECRET?: string;
+  CF_REALTIME_BASE_URL?: string;
+  CF_REALTIME_TURN_KEY_ID?: string;
+  CF_REALTIME_TURN_API_TOKEN?: string;
+}
+
+function trimString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+async function parseRealtimeResponse<T>(response: Response): Promise<T> {
+  const data = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+  if (!response.ok) {
+    const message =
+      (typeof data.errorDescription === 'string' && data.errorDescription)
+      || (typeof data.message === 'string' && data.message)
+      || `Cloudflare Realtime request failed (${response.status})`;
+    throw new Error(message);
+  }
+  return data as T;
+}
+
+export function hasCloudflareRealtimeConfig(env: CloudflareRealtimeEnv): boolean {
+  return !!trimString(env.CF_REALTIME_APP_ID) && !!trimString(env.CF_REALTIME_APP_SECRET);
+}
+
+export function assertCloudflareRealtimeConfig(env: CloudflareRealtimeEnv): {
+  appId: string;
+  appSecret: string;
+  baseUrl: string;
+  turnKeyId?: string;
+  turnApiToken?: string;
+} {
+  const appId = trimString(env.CF_REALTIME_APP_ID);
+  const appSecret = trimString(env.CF_REALTIME_APP_SECRET);
+  if (!appId || !appSecret) {
+    throw new Error('Cloudflare Realtime is not configured. Set CF_REALTIME_APP_ID and CF_REALTIME_APP_SECRET.');
+  }
+
+  return {
+    appId,
+    appSecret,
+    baseUrl: trimString(env.CF_REALTIME_BASE_URL) ?? DEFAULT_CLOUDFLARE_REALTIME_BASE_URL,
+    turnKeyId: trimString(env.CF_REALTIME_TURN_KEY_ID),
+    turnApiToken: trimString(env.CF_REALTIME_TURN_API_TOKEN),
+  };
+}
+
+export class CloudflareRealtimeClient {
+  private readonly appId: string;
+  private readonly appSecret: string;
+  private readonly baseUrl: string;
+  private readonly turnKeyId?: string;
+  private readonly turnApiToken?: string;
+
+  constructor(env: CloudflareRealtimeEnv) {
+    const config = assertCloudflareRealtimeConfig(env);
+    this.appId = config.appId;
+    this.appSecret = config.appSecret;
+    this.baseUrl = config.baseUrl;
+    this.turnKeyId = config.turnKeyId;
+    this.turnApiToken = config.turnApiToken;
+  }
+
+  async createSession(
+    body: CloudflareRealtimeNewSessionRequest = {},
+    query?: { thirdparty?: boolean; correlationId?: string },
+  ): Promise<CloudflareRealtimeNewSessionResponse> {
+    const url = this.buildSessionUrl('/sessions/new', query);
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: this.buildAuthHeaders(),
+      body: JSON.stringify(body),
+    });
+    return parseRealtimeResponse<CloudflareRealtimeNewSessionResponse>(response);
+  }
+
+  async addTracks(
+    sessionId: string,
+    body: CloudflareRealtimeTracksRequest,
+  ): Promise<CloudflareRealtimeTracksResponse> {
+    const response = await fetch(
+      this.buildSessionUrl(`/sessions/${encodeURIComponent(sessionId)}/tracks/new`),
+      {
+        method: 'POST',
+        headers: this.buildAuthHeaders(),
+        body: JSON.stringify(body),
+      },
+    );
+    return parseRealtimeResponse<CloudflareRealtimeTracksResponse>(response);
+  }
+
+  async renegotiate(
+    sessionId: string,
+    body: CloudflareRealtimeRenegotiateRequest,
+  ): Promise<CloudflareRealtimeTracksResponse> {
+    const response = await fetch(
+      this.buildSessionUrl(`/sessions/${encodeURIComponent(sessionId)}/renegotiate`),
+      {
+        method: 'PUT',
+        headers: this.buildAuthHeaders(),
+        body: JSON.stringify(body),
+      },
+    );
+    return parseRealtimeResponse<CloudflareRealtimeTracksResponse>(response);
+  }
+
+  async closeTracks(
+    sessionId: string,
+    body: CloudflareRealtimeCloseTracksRequest,
+  ): Promise<CloudflareRealtimeTracksResponse> {
+    const response = await fetch(
+      this.buildSessionUrl(`/sessions/${encodeURIComponent(sessionId)}/tracks/close`),
+      {
+        method: 'PUT',
+        headers: this.buildAuthHeaders(),
+        body: JSON.stringify(body),
+      },
+    );
+    return parseRealtimeResponse<CloudflareRealtimeTracksResponse>(response);
+  }
+
+  async getSession(sessionId: string): Promise<{
+    tracks?: Array<CloudflareRealtimeTrackObject & { status?: string }>;
+  }> {
+    const response = await fetch(
+      this.buildSessionUrl(`/sessions/${encodeURIComponent(sessionId)}`),
+      {
+        method: 'GET',
+        headers: this.buildAuthHeaders(),
+      },
+    );
+    return parseRealtimeResponse<{ tracks?: Array<CloudflareRealtimeTrackObject & { status?: string }> }>(response);
+  }
+
+  async generateIceServers(ttl = 3600): Promise<CloudflareRealtimeIceServersResponse> {
+    if (!this.turnKeyId || !this.turnApiToken) {
+      throw new Error('Cloudflare TURN is not configured. Set CF_REALTIME_TURN_KEY_ID and CF_REALTIME_TURN_API_TOKEN.');
+    }
+
+    const response = await fetch(
+      `${this.baseUrl.replace(/\/$/, '')}/turn/keys/${encodeURIComponent(this.turnKeyId)}/credentials/generate-ice-servers`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.turnApiToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ ttl }),
+      },
+    );
+    return parseRealtimeResponse<CloudflareRealtimeIceServersResponse>(response);
+  }
+
+  private buildSessionUrl(pathname: string, query?: { thirdparty?: boolean; correlationId?: string }): string {
+    const url = new URL(
+      `${this.baseUrl.replace(/\/$/, '')}/apps/${encodeURIComponent(this.appId)}${pathname}`,
+    );
+    if (query?.thirdparty !== undefined) {
+      url.searchParams.set('thirdparty', String(query.thirdparty));
+    }
+    if (query?.correlationId) {
+      url.searchParams.set('correlationId', query.correlationId);
+    }
+    return url.toString();
+  }
+
+  private buildAuthHeaders(): HeadersInit {
+    return {
+      Authorization: `Bearer ${this.appSecret}`,
+      'Content-Type': 'application/json',
+    };
+  }
+}
+
+export function createCloudflareRealtimeClient(env: Env): CloudflareRealtimeClient {
+  return new CloudflareRealtimeClient(env);
+}

package/src/lib/control-db.ts

@@ -0,0 +1,36 @@
+import type { AuthDb } from './auth-db-adapter.js';
+import { D1AuthDb } from './auth-db-adapter.js';
+
+export type ControlDb = AuthDb;
+
+export const CONTROL_D1_SCHEMA = `
+CREATE TABLE IF NOT EXISTS _meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+
+let controlSchemaInitialized = false;
+
+export async function ensureControlSchema(db: ControlDb): Promise<void> {
+  if (controlSchemaInitialized) return;
+
+  const statements = CONTROL_D1_SCHEMA.split(/;\s*\n/)
+    .map((statement) => statement.trim())
+    .filter((statement) => statement.length > 0);
+
+  await db.batch(statements.map((sql) => ({ sql })));
+  controlSchemaInitialized = true;
+}
+
+export function resetControlSchemaInit(): void {
+  controlSchemaInitialized = false;
+}
+
+export function resolveControlDb(env: Record<string, unknown>): ControlDb {
+  const d1 = env.CONTROL_DB as D1Database | undefined;
+  if (!d1) {
+    throw new Error('CONTROL_DB D1 binding is not available in the environment.');
+  }
+  return new D1AuthDb(d1);
+}

package/src/lib/cron.ts

@@ -0,0 +1,163 @@
+/**
+ * Cron expression parser and next-fire-time calculator.
+ *
+ * Supports standard 5-field cron: minute hour dayOfMonth month dayOfWeek
+ * Examples:
+ *   '0 9 * * *'     - every day at 09:00
+ *   '* /5 * * * *'  - every 5 minutes
+ *   '30 2 * * 1'    - every Monday at 02:30
+ *   '0 0 1 * *'     - first day of every month at midnight
+ */
+
+// ─── Types ───
+
+export interface CronSchedule {
+  minutes: Set<number>;
+  hours: Set<number>;
+  daysOfMonth: Set<number>;
+  months: Set<number>;
+  daysOfWeek: Set<number>;
+}
+
+export interface ParsedScheduleFunction {
+  name: string;
+  cron: string;
+  schedule: CronSchedule;
+  lastRunAt?: number;
+}
+
+// ─── Parser ───
+
+/**
+ * Parse a cron field into a Set of matching values.
+ * Supports: *, N, N-M, N/step, star/step, N-M/step, lists (comma-separated).
+ */
+export function parseCronField(field: string, min: number, max: number): Set<number> {
+  const values = new Set<number>();
+
+  for (const part of field.split(',')) {
+    const trimmed = part.trim();
+
+    if (trimmed === '*') {
+      for (let i = min; i <= max; i++) values.add(i);
+      continue;
+    }
+
+    // */step
+    const stepMatch = trimmed.match(/^(\*|(\d+)-(\d+))\/(\d+)$/);
+    if (stepMatch) {
+      const step = parseInt(stepMatch[4], 10);
+      if (step <= 0) throw new Error(`Invalid cron step: ${step}`);
+      let start = min;
+      let end = max;
+      if (stepMatch[2] !== undefined && stepMatch[3] !== undefined) {
+        start = parseInt(stepMatch[2], 10);
+        end = parseInt(stepMatch[3], 10);
+      }
+      for (let i = start; i <= end; i += step) values.add(i);
+      continue;
+    }
+
+    // N-M range
+    const rangeMatch = trimmed.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+      const start = parseInt(rangeMatch[1], 10);
+      const end = parseInt(rangeMatch[2], 10);
+      for (let i = start; i <= end; i++) values.add(i);
+      continue;
+    }
+
+    // Single value
+    const num = parseInt(trimmed, 10);
+    if (isNaN(num) || num < min || num > max) {
+      throw new Error(`Invalid cron value '${trimmed}' (${min}-${max})`);
+    }
+    values.add(num);
+  }
+
+  return values;
+}
+
+/**
+ * Parse a 5-field cron expression.
+ */
+export function parseCron(expression: string): CronSchedule {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`Invalid cron expression: expected 5 fields, got ${fields.length}`);
+  }
+
+  return {
+    minutes: parseCronField(fields[0], 0, 59),
+    hours: parseCronField(fields[1], 0, 23),
+    daysOfMonth: parseCronField(fields[2], 1, 31),
+    months: parseCronField(fields[3], 1, 12),
+    daysOfWeek: parseCronField(fields[4], 0, 6), // 0=Sunday
+  };
+}
+
+/**
+ * Check if a Date matches a cron schedule.
+ */
+export function matchesCron(date: Date, schedule: CronSchedule): boolean {
+  return (
+    schedule.minutes.has(date.getUTCMinutes()) &&
+    schedule.hours.has(date.getUTCHours()) &&
+    schedule.daysOfMonth.has(date.getUTCDate()) &&
+    schedule.months.has(date.getUTCMonth() + 1) &&
+    schedule.daysOfWeek.has(date.getUTCDay())
+  );
+}
+
+// ─── Next Fire Time ───
+
+/**
+ * Calculate the next fire time from a given date for a cron schedule.
+ * Scans forward minute-by-minute up to 366 days.
+ * Returns timestamp in milliseconds.
+ */
+export function getNextFireTime(schedule: CronSchedule, from: Date): number {
+  // Start from the next minute
+  const next = new Date(from.getTime());
+  next.setUTCSeconds(0, 0);
+  next.setUTCMinutes(next.getUTCMinutes() + 1);
+
+  const maxIterations = 366 * 24 * 60; // 1 year of minutes
+
+  for (let i = 0; i < maxIterations; i++) {
+    if (matchesCron(next, schedule)) {
+      return next.getTime();
+    }
+    next.setUTCMinutes(next.getUTCMinutes() + 1);
+  }
+
+  throw new Error('Could not find next fire time within 366 days');
+}
+
+// ─── Alarm Multiplexer ───
+
+/**
+ * Given multiple schedule functions, find the earliest next fire time.
+ * Returns the timestamp and the list of functions that fire at that time.
+ */
+export function getNextAlarm(
+  schedules: ParsedScheduleFunction[],
+  from: Date,
+): { time: number; functions: string[] } | null {
+  if (schedules.length === 0) return null;
+
+  let earliestTime = Infinity;
+  let functions: string[] = [];
+
+  for (const sched of schedules) {
+    const nextTime = getNextFireTime(sched.schedule, from);
+    if (nextTime < earliestTime) {
+      earliestTime = nextTime;
+      functions = [sched.name];
+    } else if (nextTime === earliestTime) {
+      functions.push(sched.name);
+    }
+  }
+
+  return earliestTime === Infinity ? null : { time: earliestTime, functions };
+}