lopata 0.0.1

package/runtime/bindings/rpc-stub.ts

@@ -0,0 +1,267 @@
+/**
+ * RPC stub utilities for wrapping RpcTarget instances and functions
+ * returned from DO/service binding RPC calls.
+ *
+ * On Cloudflare, when an RPC method returns an RpcTarget or function,
+ * CF wraps it in a stub proxy. This module provides equivalent local
+ * wrapping so code behaves consistently between dev and production.
+ */
+
+import { warnInvalidRpcArgs, warnInvalidRpcReturn } from "../rpc-validate";
+
+// Brand symbol shared across plugin.ts and vite-plugin/modules-plugin.ts
+export const RPC_TARGET_BRAND = Symbol.for("bunflare.RpcTarget");
+
+export function isRpcTarget(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (value as Record<symbol, unknown>)[RPC_TARGET_BRAND] === true
+  );
+}
+
+// Properties that should NOT be proxied as RPC (JS internals, Promise protocol, etc.)
+export const NON_RPC_PROPS = new Set<string | symbol>([
+  "then", "catch", "finally",  // Promise/thenable protocol
+  "toJSON", "valueOf", "toString",  // conversion
+  Symbol.toPrimitive, Symbol.toStringTag, Symbol.iterator, Symbol.asyncIterator,
+]);
+
+// Cache to avoid wrapping the same target twice (handles `return this`)
+const stubCache = new WeakMap<object, object>();
+
+/**
+ * Wrap an RpcTarget instance in a Proxy that mimics CF stub behavior:
+ * - Method calls: validate args → call → wrap return value
+ * - Property access: thenable pattern, wraps returned RpcTarget/function values
+ * - Filters `_`-prefixed properties (returns undefined)
+ * - Symbol.dispose → no-op
+ * - dup() → new stub wrapping same target
+ */
+export function createRpcStub(target: object): object {
+  const cached = stubCache.get(target);
+  if (cached) return cached;
+
+  const stub = new Proxy({} as Record<string, unknown>, {
+    get(_obj, prop: string | symbol) {
+      if (NON_RPC_PROPS.has(prop)) return undefined;
+
+      // Symbol.dispose — no-op for `using` keyword compatibility
+      if (prop === Symbol.dispose) {
+        return () => {};
+      }
+
+      if (typeof prop === "symbol") return undefined;
+
+      // Filter _-prefixed private members (CF hides these)
+      if (prop.startsWith("_")) return undefined;
+
+      // dup() — returns a new stub wrapping the same target
+      if (prop === "dup") {
+        return () => {
+          // Create a fresh stub (bypass cache)
+          const dup = createRpcStubUncached(target);
+          return dup;
+        };
+      }
+
+      const member = (target as Record<string, unknown>)[prop];
+
+      // If it's a function, return an rpcCallable with thenable for property access
+      if (typeof member === "function") {
+        const rpcCallable = (...args: unknown[]) => {
+          warnInvalidRpcArgs(args, prop);
+          const result = (member as Function).call(target, ...args);
+          return Promise.resolve(result).then((r) => wrapRpcReturnValue(r, prop));
+        };
+
+        // Thenable for `await stub.method` (returns the wrapped function itself)
+        rpcCallable.then = (
+          onFulfilled?: ((value: unknown) => unknown) | null,
+          onRejected?: ((reason: unknown) => unknown) | null,
+        ) => {
+          const wrapped = createRpcFunctionStub(member as Function, target);
+          return Promise.resolve(wrapped).then(onFulfilled, onRejected);
+        };
+
+        return rpcCallable;
+      }
+
+      // Non-function property: return thenable
+      const rpcCallable = (..._args: unknown[]) => {
+        return Promise.reject(new Error(`"${prop}" is not a method on the RPC target`));
+      };
+
+      rpcCallable.then = (
+        onFulfilled?: ((value: unknown) => unknown) | null,
+        onRejected?: ((reason: unknown) => unknown) | null,
+      ) => {
+        const wrapped = wrapRpcReturnValue(member, prop);
+        return Promise.resolve(wrapped).then(onFulfilled, onRejected);
+      };
+
+      return rpcCallable;
+    },
+  });
+
+  stubCache.set(target, stub);
+  return stub;
+}
+
+/** Create a stub without caching (used by dup()) */
+function createRpcStubUncached(target: object): object {
+  return new Proxy({} as Record<string, unknown>, {
+    get(_obj, prop: string | symbol) {
+      if (NON_RPC_PROPS.has(prop)) return undefined;
+      if (prop === Symbol.dispose) return () => {};
+      if (typeof prop === "symbol") return undefined;
+      if (typeof prop === "string" && prop.startsWith("_")) return undefined;
+      if (prop === "dup") return () => createRpcStubUncached(target);
+
+      const member = (target as Record<string, unknown>)[prop];
+
+      if (typeof member === "function") {
+        const rpcCallable = (...args: unknown[]) => {
+          warnInvalidRpcArgs(args, prop as string);
+          const result = (member as Function).call(target, ...args);
+          return Promise.resolve(result).then((r) => wrapRpcReturnValue(r, prop as string));
+        };
+        rpcCallable.then = (
+          onFulfilled?: ((value: unknown) => unknown) | null,
+          onRejected?: ((reason: unknown) => unknown) | null,
+        ) => {
+          const wrapped = createRpcFunctionStub(member as Function, target);
+          return Promise.resolve(wrapped).then(onFulfilled, onRejected);
+        };
+        return rpcCallable;
+      }
+
+      const rpcCallable = (..._args: unknown[]) => {
+        return Promise.reject(new Error(`"${prop}" is not a method on the RPC target`));
+      };
+      rpcCallable.then = (
+        onFulfilled?: ((value: unknown) => unknown) | null,
+        onRejected?: ((reason: unknown) => unknown) | null,
+      ) => {
+        const wrapped = wrapRpcReturnValue(member, prop as string);
+        return Promise.resolve(wrapped).then(onFulfilled, onRejected);
+      };
+      return rpcCallable;
+    },
+  });
+}
+
+/**
+ * Wrap a function in a callable stub with validation + Symbol.dispose + dup().
+ */
+export function createRpcFunctionStub(fn: Function, thisArg?: object): Function {
+  const stub = (...args: unknown[]) => {
+    warnInvalidRpcArgs(args, fn.name || "<anonymous>");
+    const result = fn.call(thisArg, ...args);
+    return Promise.resolve(result).then((r) => wrapRpcReturnValue(r, fn.name || "<anonymous>"));
+  };
+
+  Object.defineProperty(stub, Symbol.dispose, {
+    value: () => {},
+    writable: false,
+    configurable: true,
+  });
+
+  Object.defineProperty(stub, "dup", {
+    value: () => createRpcFunctionStub(fn, thisArg),
+    writable: false,
+    configurable: true,
+  });
+
+  return stub;
+}
+
+/**
+ * Wrap a Promise in an RpcPromise proxy that supports promise pipelining.
+ *
+ * `stub.getChild().childMethod()` works without intermediate await:
+ * - then/catch/finally → delegate to underlying promise
+ * - Any other property → returns a pipelined callable
+ */
+export function createRpcPromise(promise: Promise<unknown>): Promise<unknown> {
+  return new Proxy(promise, {
+    get(target, prop: string | symbol) {
+      // Promise protocol — delegate to the underlying promise
+      if (prop === "then" || prop === "catch" || prop === "finally") {
+        const method = target[prop as keyof Promise<unknown>] as Function;
+        return method.bind(target);
+      }
+
+      // Symbol.dispose — no-op
+      if (prop === Symbol.dispose) return () => {};
+
+      // dup() — new RpcPromise wrapping same promise
+      if (prop === "dup") return () => createRpcPromise(promise);
+
+      // NON_RPC_PROPS (excluding then/catch/finally already handled)
+      if (NON_RPC_PROPS.has(prop)) return undefined;
+
+      if (typeof prop === "symbol") return undefined;
+
+      // Filter _-prefixed
+      if (prop.startsWith("_")) return undefined;
+
+      // Promise pipelining: property access chains through the resolved value
+      const pipelined = (...args: unknown[]) => {
+        const chained = promise.then((resolved) => {
+          if (resolved === null || resolved === undefined) {
+            throw new Error(`Cannot access "${prop}" on ${String(resolved)}`);
+          }
+          const member = (resolved as Record<string, unknown>)[prop];
+          if (typeof member !== "function") {
+            throw new Error(`"${prop}" is not a method on the resolved value`);
+          }
+          return (member as Function).call(resolved, ...args);
+        }).then((r) => wrapRpcReturnValue(r, prop));
+        return createRpcPromise(chained);
+      };
+
+      // Make pipelined callable also thenable for property access
+      pipelined.then = (
+        onFulfilled?: ((value: unknown) => unknown) | null,
+        onRejected?: ((reason: unknown) => unknown) | null,
+      ) => {
+        const chained = promise.then((resolved) => {
+          if (resolved === null || resolved === undefined) {
+            return undefined;
+          }
+          const member = (resolved as Record<string, unknown>)[prop];
+          if (typeof member === "function") {
+            return createRpcFunctionStub(member as Function, resolved as object);
+          }
+          return wrapRpcReturnValue(member, prop);
+        });
+        return chained.then(onFulfilled, onRejected);
+      };
+
+      return pipelined;
+    },
+  }) as Promise<unknown>;
+}
+
+/**
+ * Inspect a return value and wrap it appropriately:
+ * - RpcTarget instance → createRpcStub()
+ * - Function → createRpcFunctionStub()
+ * - Otherwise → warn if invalid + pass through
+ */
+export function wrapRpcReturnValue(value: unknown, context: string): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (isRpcTarget(value)) {
+    return createRpcStub(value as object);
+  }
+
+  if (typeof value === "function") {
+    return createRpcFunctionStub(value as Function);
+  }
+
+  // Not an RpcTarget or function — validate and pass through
+  warnInvalidRpcReturn(value, context);
+  return value;
+}

package/runtime/bindings/scheduled.ts

@@ -0,0 +1,172 @@
+import { ExecutionContext } from "../execution-context";
+import { startSpan, persistError } from "../tracing/span";
+
+export interface ScheduledController {
+  readonly scheduledTime: number;
+  readonly cron: string;
+  readonly type: "scheduled";
+  noRetry(): void;
+}
+
+interface CronField {
+  type: "any" | "values";
+  values: number[];
+}
+
+interface ParsedCron {
+  expression: string;
+  minute: CronField;
+  hour: CronField;
+  dayOfMonth: CronField;
+  month: CronField;
+  dayOfWeek: CronField;
+}
+
+const DAY_NAMES: Record<string, number> = {
+  SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6,
+};
+
+const MONTH_NAMES: Record<string, number> = {
+  JAN: 1, FEB: 2, MAR: 3, APR: 4, MAY: 5, JUN: 6,
+  JUL: 7, AUG: 8, SEP: 9, OCT: 10, NOV: 11, DEC: 12,
+};
+
+const SPECIAL_CRONS: Record<string, string> = {
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *",
+  "@weekly": "0 0 * * 0",
+  "@monthly": "0 0 1 * *",
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+};
+
+function resolveToken(token: string, names: Record<string, number> | null): number {
+  if (names) {
+    const upper = token.toUpperCase();
+    if (upper in names) return names[upper]!;
+  }
+  return parseInt(token, 10);
+}
+
+function parseField(field: string, min: number, max: number, names: Record<string, number> | null = null): CronField {
+  if (field === "*") {
+    return { type: "any", values: [] };
+  }
+
+  const values: number[] = [];
+
+  for (const part of field.split(",")) {
+    const stepMatch = part.match(/^(\*|([a-zA-Z0-9]+)-([a-zA-Z0-9]+))\/(\d+)$/);
+    if (stepMatch) {
+      const step = parseInt(stepMatch[4]!, 10);
+      const start = stepMatch[1] === "*" ? min : resolveToken(stepMatch[2]!, names);
+      const end = stepMatch[1] === "*" ? max : resolveToken(stepMatch[3]!, names);
+      for (let i = start; i <= end; i += step) {
+        values.push(i);
+      }
+      continue;
+    }
+
+    const rangeMatch = part.match(/^([a-zA-Z0-9]+)-([a-zA-Z0-9]+)$/);
+    if (rangeMatch) {
+      const start = resolveToken(rangeMatch[1]!, names);
+      const end = resolveToken(rangeMatch[2]!, names);
+      for (let i = start; i <= end; i++) {
+        values.push(i);
+      }
+      continue;
+    }
+
+    values.push(resolveToken(part, names));
+  }
+
+  return { type: "values", values };
+}
+
+export function parseCron(expression: string): ParsedCron {
+  const trimmed = expression.trim();
+
+  // Handle special cron strings
+  const special = SPECIAL_CRONS[trimmed.toLowerCase()];
+  if (special) {
+    const parsed = parseCron(special);
+    parsed.expression = trimmed;
+    return parsed;
+  }
+
+  const parts = trimmed.split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression: "${expression}" (expected 5 fields)`);
+  }
+
+  return {
+    expression: trimmed,
+    minute: parseField(parts[0]!, 0, 59),
+    hour: parseField(parts[1]!, 0, 23),
+    dayOfMonth: parseField(parts[2]!, 1, 31),
+    month: parseField(parts[3]!, 1, 12, MONTH_NAMES),
+    dayOfWeek: parseField(parts[4]!, 0, 6, DAY_NAMES),
+  };
+}
+
+function fieldMatches(field: CronField, value: number): boolean {
+  if (field.type === "any") return true;
+  return field.values.includes(value);
+}
+
+export function cronMatchesDate(cron: ParsedCron, date: Date): boolean {
+  return (
+    fieldMatches(cron.minute, date.getMinutes()) &&
+    fieldMatches(cron.hour, date.getHours()) &&
+    fieldMatches(cron.dayOfMonth, date.getDate()) &&
+    fieldMatches(cron.month, date.getMonth() + 1) &&
+    fieldMatches(cron.dayOfWeek, date.getDay())
+  );
+}
+
+export function createScheduledController(cron: string, scheduledTime: number): ScheduledController {
+  return {
+    scheduledTime,
+    cron,
+    type: "scheduled",
+    noRetry() {},
+  };
+}
+
+type ScheduledHandler = (controller: ScheduledController, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+
+export function startCronScheduler(
+  crons: string[],
+  handler: ScheduledHandler,
+  env: Record<string, unknown>,
+  workerName?: string,
+): NodeJS.Timer {
+  const parsed = crons.map(parseCron);
+
+  // Check every 60 seconds, aligned to the start of each minute
+  const interval = setInterval(() => {
+    const now = new Date();
+    for (const cron of parsed) {
+      if (cronMatchesDate(cron, now)) {
+        const controller = createScheduledController(cron.expression, now.getTime());
+        const ctx = new ExecutionContext();
+        console.log(`[bunflare] Cron triggered: ${cron.expression}`);
+        startSpan({
+          name: "scheduled",
+          kind: "server",
+          attributes: { cron: cron.expression },
+          workerName,
+        }, async () => {
+          await handler(controller, env, ctx);
+          await ctx._awaitAll();
+        }).catch((err) => {
+          console.error(`[bunflare] Scheduled handler error (${cron.expression}):`, err);
+          persistError(err, "scheduled", workerName);
+        });
+      }
+    }
+  }, 60_000);
+
+  return interval;
+}

package/runtime/bindings/service-binding.ts

@@ -0,0 +1,217 @@
+/**
+ * Service Binding — worker-to-worker communication via HTTP fetch and RPC.
+ *
+ * The binding is a Proxy that supports:
+ * - `.fetch(request | url, init?)` — calls the target worker's fetch() handler
+ * - `.myMethod(args)` — RPC call to the target's entrypoint class method (always returns Promise)
+ * - `.myProperty` — RPC property access (returns thenable/Promise)
+ * - `.connect()` — stub for TCP socket (throws — not supported in dev)
+ */
+
+import { ExecutionContext } from "../execution-context";
+import { getActiveContext, runWithContext } from "../tracing/context";
+import { warnInvalidRpcArgs } from "../rpc-validate";
+import { NON_RPC_PROPS, wrapRpcReturnValue, createRpcFunctionStub } from "./rpc-stub";
+
+type WorkerModule = Record<string, unknown>;
+
+export interface ServiceBindingLimits {
+  /** Max subrequests per top-level request (CF default: 1000 for workers, 32 for service bindings) */
+  maxSubrequests?: number;
+  /** Max payload size in bytes for RPC arguments (CF default: 32 MiB) */
+  maxRpcPayloadSize?: number;
+}
+
+const SERVICE_BINDING_DEFAULTS: Required<ServiceBindingLimits> = {
+  maxSubrequests: 1000,
+  maxRpcPayloadSize: 32 * 1024 * 1024,
+};
+
+// Internal properties that should be forwarded to the ServiceBinding instance
+const INTERNAL_PROPS = new Set(["_wire", "isWired", "_subrequestCount"]);
+
+export class ServiceBinding {
+  private _resolver: (() => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) | null = null;
+  private _entrypoint: string | undefined;
+  private _serviceName: string;
+  private _limits: Required<ServiceBindingLimits>;
+  _subrequestCount: number = 0;
+
+  constructor(serviceName: string, entrypoint?: string, limits?: ServiceBindingLimits) {
+    this._serviceName = serviceName;
+    this._entrypoint = entrypoint;
+    this._limits = { ...SERVICE_BINDING_DEFAULTS, ...limits };
+  }
+
+  _wire(resolverOrModule: (() => { workerModule: Record<string, unknown>; env: Record<string, unknown> }) | Record<string, unknown>, env?: Record<string, unknown>): void {
+    if (typeof resolverOrModule === "function" && env === undefined) {
+      // New API: resolver function
+      this._resolver = resolverOrModule as () => { workerModule: Record<string, unknown>; env: Record<string, unknown> };
+    } else {
+      // Legacy API: _wire(workerModule, env)
+      const workerModule = resolverOrModule as Record<string, unknown>;
+      const capturedEnv = env!;
+      this._resolver = () => ({ workerModule, env: capturedEnv });
+    }
+  }
+
+  get isWired(): boolean {
+    return this._resolver !== null;
+  }
+
+  private _resolve(): { workerModule: Record<string, unknown>; env: Record<string, unknown> } {
+    if (!this._resolver) {
+      throw new Error(`Service binding "${this._serviceName}" is not wired — target worker not loaded`);
+    }
+    return this._resolver();
+  }
+
+  private _checkSubrequestLimit(): void {
+    this._subrequestCount++;
+    if (this._subrequestCount > this._limits.maxSubrequests) {
+      throw new Error(
+        `Service binding "${this._serviceName}": subrequest limit exceeded (max ${this._limits.maxSubrequests})`
+      );
+    }
+  }
+
+  private _getTarget(ctx?: ExecutionContext): Record<string, unknown> {
+    const { workerModule, env } = this._resolve();
+    if (this._entrypoint) {
+      const cls = workerModule[this._entrypoint] as (new (...args: unknown[]) => Record<string, unknown>) | undefined;
+      if (!cls) {
+        throw new Error(`Entrypoint "${this._entrypoint}" not exported from worker module`);
+      }
+      return new cls(ctx ?? new ExecutionContext(), env);
+    }
+    // Default export: could be class-based or object-based
+    const def = workerModule.default;
+    if (typeof def === "function" && def.prototype && typeof def.prototype.fetch === "function") {
+      return new (def as new (ctx: ExecutionContext, env: unknown) => Record<string, unknown>)(ctx ?? new ExecutionContext(), env);
+    }
+    return def as Record<string, unknown>;
+  }
+
+  async fetch(input: Request | string | URL, init?: RequestInit): Promise<Response> {
+    this._checkSubrequestLimit();
+    const execCtx = new ExecutionContext();
+    const target = this._getTarget(execCtx);
+    if (!target?.fetch || typeof target.fetch !== "function") {
+      throw new Error(`Service binding "${this._serviceName}" target has no fetch() handler`);
+    }
+    const url = input instanceof URL ? input.toString() : input;
+    const request = typeof url === "string" ? new Request(url, init) : url;
+    // Class-based entrypoints receive (request) — env/ctx via constructor
+    // Object-based entrypoints receive (request, env, ctx)
+    const { workerModule, env } = this._resolve();
+    const def = workerModule.default;
+    const isClass = (this._entrypoint || (typeof def === "function" && def.prototype?.fetch));
+
+    // Propagate trace context to target worker so child spans link correctly
+    const parentCtx = getActiveContext();
+    const doCall = async () => {
+      const response = isClass
+        ? await (target.fetch as (r: Request) => Promise<Response>)(request)
+        : await (target.fetch as (r: Request, e: unknown, c: ExecutionContext) => Promise<Response>)(request, env, execCtx);
+      execCtx._awaitAll().catch(() => {});
+      return response;
+    };
+
+    if (parentCtx) {
+      return runWithContext(parentCtx, doCall);
+    }
+    return doCall();
+  }
+
+  connect(_address: string | { hostname: string; port: number }): never {
+    throw new Error(
+      `Service binding "${this._serviceName}": connect() (TCP sockets) is not supported in local dev mode`
+    );
+  }
+
+  toProxy(): Record<string, unknown> {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
+    return new Proxy({} as Record<string, unknown>, {
+      get(_obj, prop: string | symbol) {
+        if (typeof prop === "symbol") {
+          if (NON_RPC_PROPS.has(prop)) return undefined;
+          return undefined;
+        }
+
+        if (prop === "fetch") {
+          return self.fetch.bind(self);
+        }
+        if (prop === "connect") {
+          return self.connect.bind(self);
+        }
+        if (INTERNAL_PROPS.has(prop)) {
+          const val = (self as unknown as Record<string, unknown>)[prop];
+          if (typeof val === "function") return val.bind(self);
+          return val;
+        }
+        // Non-RPC props should not trigger proxy behavior
+        if (NON_RPC_PROPS.has(prop)) {
+          return undefined;
+        }
+
+        // RPC: return a callable that also acts as a thenable for property access
+        // If called as a function → RPC method call (always returns Promise)
+        // If awaited → RPC property read (returns Promise of the property value)
+        const rpcCallable = (...args: unknown[]) => {
+          self._checkSubrequestLimit();
+          warnInvalidRpcArgs(args, prop);
+          const target = self._getTarget();
+          const member = target[prop];
+          if (typeof member !== "function") {
+            throw new Error(`Service binding "${self._serviceName}": "${prop}" is not a method on the target`);
+          }
+          // Propagate trace context so child spans link correctly
+          const parentCtx = getActiveContext();
+          const doCall = () => (member as (...a: unknown[]) => unknown).call(target, ...args);
+          const result = parentCtx
+            ? runWithContext(parentCtx, doCall)
+            : doCall();
+          // CF always wraps in Promise for async consistency
+          return Promise.resolve(result).then((r) => wrapRpcReturnValue(r, prop));
+        };
+
+        // Make it thenable for property access: `await binding.prop`
+        rpcCallable.then = (
+          onFulfilled?: ((value: unknown) => unknown) | null,
+          onRejected?: ((reason: unknown) => unknown) | null,
+        ) => {
+          self._checkSubrequestLimit();
+          const promise = new Promise<unknown>((resolve, reject) => {
+            try {
+              const target = self._getTarget();
+              const member = target[prop];
+              if (typeof member === "function") {
+                resolve(createRpcFunctionStub(member as Function, target));
+              } else {
+                resolve(wrapRpcReturnValue(member, prop));
+              }
+            } catch (e) {
+              reject(e);
+            }
+          });
+          return promise.then(onFulfilled, onRejected);
+        };
+
+        return rpcCallable;
+      },
+    });
+  }
+}
+
+/**
+ * Create a service binding proxy.
+ */
+export function createServiceBinding(
+  serviceName: string,
+  entrypoint?: string,
+  limits?: ServiceBindingLimits,
+): Record<string, unknown> {
+  const binding = new ServiceBinding(serviceName, entrypoint, limits);
+  return binding.toProxy();
+}