sproutboat 0.7.0 → 0.9.0

package/src/types-gen.ts

@@ -0,0 +1,90 @@
+/**
+ * `sproutboat types` — the project's `env`, as TypeScript.
+ *
+ * In Workers `env` is a parameter, so an editor can infer it from a signature.
+ * Here it is a global, which means nothing is inferable at all: `env.SESSIONS`
+ * is an undeclared identifier until this file exists. That makes generated
+ * types worth more here than they are there, not less.
+ *
+ * The output declares `env` from `sproutboat.jsonc` and references the ambient
+ * types shipped in `types/sproutboat.d.ts`, so binding *shapes* version with
+ * the CLI and binding *names* version with the project.
+ *
+ * Names need no quoting: `parseConfig` already holds every binding and var to
+ * /^[A-Z][A-Z0-9_]*$/, so all of them are plain identifiers.
+ */
+import { resourceRefs, type SproutboatConfig } from "./config";
+
+/** The file the generator writes, relative to the project directory. */
+export const TYPES_FILE = "sproutboat-env.d.ts";
+
+const HEADER = `// Generated by \`sproutboat types\`. Do not edit.
+//
+// Regenerated whenever sproutboat.jsonc is newer than this file, so a binding
+// added to the config shows up in the editor without asking. Commit it: it is
+// part of the project's type surface, like a schema.
+`;
+
+type Entry = { name: string; type: string; note?: string };
+
+function entries(config: SproutboatConfig): Entry[] {
+  const out: Entry[] = [];
+
+  for (const [name, value] of Object.entries(config.vars ?? {})) {
+    out.push({ name, type: "string", note: `vars: ${JSON.stringify(value)}` });
+  }
+  for (const name of config.secrets ?? []) {
+    out.push({ name, type: "string", note: "secret, set with `sproutboat secrets set`" });
+  }
+  for (const { binding } of resourceRefs(config.kv_namespaces)) out.push({ name: binding, type: "KVNamespace" });
+  for (const { binding } of resourceRefs(config.d1_databases)) out.push({ name: binding, type: "D1Database" });
+  for (const { binding } of resourceRefs(config.r2_buckets)) out.push({ name: binding, type: "R2Bucket" });
+  for (const { binding } of resourceRefs(config.queues)) out.push({ name: binding, type: "Queue" });
+  for (const name of config.analytics_engine_datasets ?? []) {
+    out.push({ name, type: "AnalyticsEngineDataset" });
+  }
+  for (const [binding, className] of Object.entries(config.durable_objects ?? {})) {
+    out.push({ name: binding, type: "DurableObjectNamespace", note: `class ${className}` });
+  }
+  for (const service of config.services ?? []) {
+    out.push({ name: service.binding, type: "Fetcher", note: `service binding: ${service.service}` });
+  }
+  if (config.assets?.binding) {
+    out.push({ name: config.assets.binding, type: "Fetcher", note: `static assets: ${config.assets.directory}` });
+  }
+  return out;
+}
+
+/**
+ * The contents of `sproutboat-env.d.ts` for `config`.
+ *
+ * Pure, so the test can assert on the text and `dev` can compare it against
+ * what is already on disk without writing.
+ */
+export function generateTypes(config: SproutboatConfig): string {
+  const rows = entries(config);
+  const body = rows.length
+    ? rows
+        .map((entry) => `    ${entry.note ? `/** ${entry.note} */\n    ` : ""}${entry.name}: ${entry.type};`)
+        .join("\n")
+    : "    // No bindings declared in sproutboat.jsonc yet.";
+
+  return `${HEADER}
+/// <reference types="sproutboat/types" />
+
+declare global {
+  /**
+   * Bindings from sproutboat.jsonc, for project "${config.name}".
+   *
+   * A global, not a parameter: the handler signature is \`fetch(request)\`.
+   * Every call on these is synchronous, so \`await\` is allowed and does
+   * nothing.
+   */
+  const env: {
+${body}
+  };
+}
+
+export {};
+`;
+}

package/src/wrap.ts

@@ -13,6 +13,23 @@
  *  imported — callers do `readFile(preludePath, "utf8")`. */
 export const preludePath = new URL("./native-fetch-prelude.js", import.meta.url);
 
+/**
+ * #15 — the two transports the prelude can be built with.
+ *
+ * Both define `__sbCall(reqJson) -> replyJson` and nothing else; every binding
+ * shim above that line is identical, which is what lets one conformance suite
+ * hold both honest. `broker` talks to the per-deployment broker over loopback
+ * (deployed, dev, phase-0 standalone); `embedded` compiles SQLite into the
+ * sprout and needs no second process at all.
+ */
+export type Transport = "broker" | "embedded";
+export const transportPath = (transport: Transport): URL =>
+  new URL(transport === "embedded" ? "./transport-embedded.js" : "./transport-broker.js", import.meta.url);
+
+/** Where the prelude expects its transport spliced in. */
+export const TRANSPORT_MARKER =
+  "// TRANSPORT: wrap.ts splices one of transport-broker.js / transport-embedded.js here.";
+
 // The server honours $PORT at runtime (patches/porffor-render.patch); this baked
 // value is only a fallback for a directly-run binary.
 const DEFAULT_PORT = 8080;
@@ -44,6 +61,9 @@ export type Bindings = {
   queues: string[];
   analytics: string[];
   do: Array<{ binding: string; className: string }>;
+  /** #48 — worker-to-worker: binding name -> the project it calls. The hostname
+   *  it resolves to is a runtime input, not part of the artifact. */
+  services: Array<{ binding: string; service: string }>;
   crons: string[];
   /** Static-asset binding name for `env.<NAME>.fetch(request)`; `""` when assets are edge-only. */
   assets: string;
@@ -58,6 +78,7 @@ export const EMPTY_BINDINGS: Bindings = {
   queues: [],
   analytics: [],
   do: [],
+  services: [],
   crons: [],
   assets: "",
 };
@@ -72,6 +93,7 @@ function hasBindings(b: Bindings): boolean {
     b.queues.length > 0 ||
     b.analytics.length > 0 ||
     b.do.length > 0 ||
+    b.services.length > 0 ||
     b.assets !== ""
   );
 }
@@ -142,6 +164,9 @@ export function wrapNativeFetchHandler(
   bindings: Bindings = EMPTY_BINDINGS,
   port: number = DEFAULT_PORT,
   compatibilityDate: string = BASELINE_COMPATIBILITY_DATE,
+  appName: string = "app",
+  /** #15 — assets baked into the module for a binary that has no files beside it. */
+  assets?: { manifest: unknown; files: Record<string, string> },
 ): string {
   const neutralised = neutraliseExports(source);
   if (neutralised === null || !/\bfetch\s*\(/.test(source)) {
@@ -151,16 +176,26 @@ export function wrapNativeFetchHandler(
   const env = `const env = ${JSON.stringify(vars)};\nglobalThis.env = env;\n`;
   // Baked, not a binding: the date belongs to the artifact, and a handler must
   // not be able to change the semantics it was compiled against at runtime.
-  const compat = `globalThis.__sbCompat = ${JSON.stringify(compatibilityDate)};\n`;
+  const compat =
+    `globalThis.__sbCompat = ${JSON.stringify(compatibilityDate)};\n` +
+    // #15 — the embedded transport derives its default data directory from this.
+    `globalThis.__sbAppName = ${JSON.stringify(appName)};\n` +
+    // #15 — and enforces the outbound allowlist itself, with no broker to do it.
+    `globalThis.__sbOutbound = ${JSON.stringify(bindings.outbound)};\n` +
+    (assets ? `globalThis.__sbAssets = ${JSON.stringify(assets)};\n` : "");
   const wire = hasBindings(bindings) ? `__sbInstallBindings(env, ${JSON.stringify(bindings)});\n` : "";
   const registerDO = bindings.do.length
     ? `__sbRegisterDO({ ${bindings.do.map((d) => `${d.className}: ${d.className}`).join(", ")} });\n`
     : "";
+  // Cron / queue / alarm timers, for a transport that has no broker to deliver
+  // them. The broker transport defines this as a no-op, so the emitted module
+  // is the same either way.
+  const triggers = hasBindings(bindings) ? `__sbStartLocalTriggers(__sbHandlers, ${JSON.stringify(bindings)});\n` : "";
 
   return (
     `${prelude}\n${compat}${env}${wire}` +
     `${neutralised}\n` +
-    `${registerDO}` +
+    `${registerDO}${triggers}` +
     `export default {\n  port: ${port},\n  fetch(request) { return __sbEntry(__sbHandlers, request); }\n};\n`
   );
 }
@@ -200,6 +235,14 @@ export function readBindingsFromEnv(): Bindings {
   const parsed: VarsJson = JSON.parse(raw);
   if (!isVarsObject(parsed)) throw new Error("SPROUTBOAT_BINDINGS_JSON must be a JSON object");
   const strings = (v: VarsJson): string[] => (Array.isArray(v) ? v.filter(isVarsString) : []);
+  const services: Array<{ binding: string; service: string }> = [];
+  if (Array.isArray(parsed.services)) {
+    for (const entry of parsed.services) {
+      if (isVarsObject(entry) && isVarsString(entry.binding) && isVarsString(entry.service)) {
+        services.push({ binding: entry.binding, service: entry.service });
+      }
+    }
+  }
   const dos: Array<{ binding: string; className: string }> = [];
   if (Array.isArray(parsed.do)) {
     for (const entry of parsed.do) {
@@ -217,6 +260,7 @@ export function readBindingsFromEnv(): Bindings {
     queues: strings(parsed.queues),
     analytics: strings(parsed.analytics),
     do: dos,
+    services,
     crons: strings(parsed.crons),
     assets: isVarsString(parsed.assets) ? parsed.assets : "",
   };

package/types/sproutboat.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Ambient types for a Sproutboat handler.
+ *
+ * Shipped with the CLI rather than as a separate package, so the types always
+ * describe the runtime that the installed CLI compiles. `sproutboat types`
+ * generates a project's `sproutboat-env.d.ts`, which references this file and
+ * declares `env` with that project's bindings.
+ *
+ * Two things differ from Cloudflare Workers and are the reason these exist:
+ * `env` is a global rather than a parameter, so nothing is inferable from a
+ * signature, and every binding call is synchronous.
+ */
+
+declare global {
+  // ---------------------------------------------------------------- KV
+
+  interface KVNamespace {
+    /** The stored string, or `null`. Synchronous: no `await`. */
+    get(key: string): string | null;
+    put(key: string, value: string): void;
+    delete(key: string): void;
+    /** Keys under `prefix` (all keys when omitted). */
+    list(prefix?: string): string[];
+  }
+
+  // ---------------------------------------------------------------- D1
+
+  interface D1Meta {
+    /** `INSERT` only. The autoincrement id of the row just written. */
+    last_row_id: number;
+    changes: number;
+  }
+
+  interface D1Result<T = Record<string, unknown>> {
+    results: T[];
+    success: boolean;
+    meta: D1Meta;
+  }
+
+  interface D1PreparedStatement {
+    /** Positional `?` parameters, in order. */
+    bind(...values: Array<string | number | boolean | null>): D1PreparedStatement;
+    all<T = Record<string, unknown>>(): D1Result<T>;
+    run(): D1Result;
+    /** The first row, or one column of it when named. `null` if there are none. */
+    first<T = Record<string, unknown>>(): T | null;
+    first<T = unknown>(column: string): T | null;
+  }
+
+  interface D1Database {
+    prepare(sql: string): D1PreparedStatement;
+    batch(statements: D1PreparedStatement[]): D1Result[];
+    /** Runs a whole script. Use this for multi-statement DDL. */
+    exec(sql: string): void;
+  }
+
+  // ---------------------------------------------------------------- R2
+
+  interface R2Object {
+    key: string;
+    size: number;
+    etag: string;
+    uploaded: string;
+    customMetadata?: Record<string, string>;
+    /**
+     * The object as a string. An object is held whole in memory on the way in
+     * and on the way out, so keep them small.
+     */
+    body: string;
+  }
+
+  type R2ObjectHead = Omit<R2Object, "body">;
+
+  interface R2Objects {
+    objects: R2ObjectHead[];
+    truncated: boolean;
+    cursor?: string;
+  }
+
+  interface R2PutOptions {
+    customMetadata?: Record<string, string>;
+  }
+
+  interface R2ListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+  }
+
+  interface R2Bucket {
+    put(key: string, value: string, options?: R2PutOptions): void;
+    get(key: string): R2Object | null;
+    /** Metadata without the body. */
+    head(key: string): R2ObjectHead | null;
+    delete(key: string): void;
+    list(options?: R2ListOptions): R2Objects;
+  }
+
+  // ------------------------------------------------------------ Queues
+
+  interface QueueSendOptions {
+    delaySeconds?: number;
+  }
+
+  interface Queue<Body = unknown> {
+    /** Returns immediately. The batch reaches `queue()` out of band. */
+    send(body: Body, options?: QueueSendOptions): void;
+    sendBatch(messages: Array<{ body: Body }>): void;
+  }
+
+  interface QueueMessage<Body = unknown> {
+    id: string;
+    timestamp: number;
+    body: Body;
+    /** Mark as handled. Without this the message is redelivered. */
+    ack(): void;
+    /** Hand it back for another attempt. */
+    retry(): void;
+  }
+
+  interface MessageBatch<Body = unknown> {
+    queue: string;
+    messages: Array<QueueMessage<Body>>;
+  }
+
+  // --------------------------------------------------- Durable Objects
+
+  interface DurableObjectId {
+    toString(): string;
+    name?: string;
+  }
+
+  interface DurableObjectStub {
+    fetch(request: Request): Response;
+  }
+
+  interface DurableObjectNamespace {
+    idFromName(name: string): DurableObjectId;
+    idFromString(hex: string): DurableObjectId;
+    newUniqueId(): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStub;
+  }
+
+  interface DurableObjectStorage {
+    get<T = unknown>(key: string): T | undefined;
+    put<T>(key: string, value: T): void;
+    delete(key: string): void;
+    deleteAll(): void;
+    /** Stored values under `prefix`, keyed by storage key. */
+    list<T = unknown>(options?: { prefix?: string; limit?: number }): Map<string, T>;
+    /**
+     * At most one alarm is pending per object; a later `setAlarm` replaces it.
+     * The handler is the class's `alarm()` method.
+     */
+    setAlarm(scheduledTime: number): void;
+    getAlarm(): number | null;
+    deleteAlarm(): void;
+  }
+
+  interface DurableObjectState {
+    id: DurableObjectId;
+    /** Synchronous, like every other binding. */
+    storage: DurableObjectStorage;
+  }
+
+  // -------------------------------------------------- Analytics Engine
+
+  interface AnalyticsEngineDataPoint {
+    blobs?: string[];
+    doubles?: number[];
+    indexes?: string[];
+  }
+
+  interface AnalyticsEngineDataset {
+    writeDataPoint(event: AnalyticsEngineDataPoint): void;
+    query<T = unknown>(options?: { limit?: number }): { count: number; rows: T[] };
+  }
+
+  // ------------------------------------ Fetchers: services and assets
+
+  /** A service binding, and the shape of the static-asset binding. */
+  interface Fetcher {
+    fetch(request: Request): Response;
+  }
+
+  // --------------------------------------------------------- Handlers
+
+  interface ScheduledEvent {
+    /** The expression that fired, as written in `triggers.crons`. */
+    cron: string;
+    scheduledTime: number;
+  }
+
+  /**
+   * The default export.
+   *
+   * `fetch` takes only a request: `env` is a global, and there is no `ctx`, so
+   * there is no `ctx.waitUntil`. Use a queue for work that outlives a response.
+   */
+  interface SproutboatHandler<QueueBody = unknown> {
+    fetch(request: Request): Response | Promise<Response>;
+    scheduled?(event: ScheduledEvent): void | Promise<void>;
+    queue?(batch: MessageBatch<QueueBody>): void | Promise<void>;
+  }
+
+  /**
+   * What a Durable Object class implements. Declare it above the default
+   * export and name it in `durable_objects`.
+   */
+  interface DurableObject {
+    fetch(request: Request): Response | Promise<Response>;
+    /** Runs after `storage.setAlarm`, with no request in flight. */
+    alarm?(): void | Promise<void>;
+  }
+}
+
+export {};