lakebed 0.0.18 → 0.0.19

package/src/anonymous.js

@@ -30,6 +30,7 @@ export const DEFAULT_ANONYMOUS_LIMITS = {
 
 const expressionOps = new Set(["arg", "auth", "call", "row"]);
 const authFields = new Set(["displayName", "email", "emailVerified", "isAuthenticated", "isGuest", "picture", "provider", "userId"]);
+const endpointMethodPattern = /^[A-Z0-9!#$%&'*+.^_`|~-]+$/;
 const sourceModuleCache = new Map();
 
 export class AnonymousCompilerError extends Error {
@@ -487,6 +488,69 @@ function serializeSchema(schema) {
   return { diagnostics, schema: cleanSchema };
 }
 
+function isReservedEndpointPath(path) {
+  return (
+    path === "/" ||
+    path === "/index.html" ||
+    path === "/client.js" ||
+    path === "/auth/callback" ||
+    path.startsWith("/auth/") ||
+    path === "/__lakebed" ||
+    path.startsWith("/__lakebed/") ||
+    path === "/__span" ||
+    path.startsWith("/__span/")
+  );
+}
+
+function validateEndpointRoute({ method, path }, diagnosticPath, diagnostics) {
+  if (typeof method !== "string" || !endpointMethodPattern.test(method)) {
+    diagnostics.push(diagnostic(diagnosticPath, "Endpoint method must be a valid uppercase HTTP method."));
+  }
+
+  if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.includes("\\") || path.includes("?") || path.includes("#")) {
+    diagnostics.push(diagnostic(diagnosticPath, "Endpoint path must be an absolute app path like /webhooks/stripe."));
+    return;
+  }
+
+  if (isReservedEndpointPath(path)) {
+    diagnostics.push(diagnostic(diagnosticPath, `Endpoint path ${path} is reserved by Lakebed.`));
+  }
+}
+
+function serializeEndpoints(endpoints) {
+  const diagnostics = [];
+  const cleanEndpoints = {};
+  const seenRoutes = new Map();
+
+  for (const [name, endpoint] of Object.entries(endpoints ?? {})) {
+    const diagnosticPath = `server.index.endpoints.${name}`;
+    if (!endpoint || endpoint.kind !== "endpoint" || typeof endpoint.handler !== "function") {
+      diagnostics.push(diagnostic("server/index.ts", `Endpoint ${name} must be defined with endpoint({ method, path }, handler).`));
+      continue;
+    }
+
+    const method = String(endpoint.method ?? "").toUpperCase();
+    const path = String(endpoint.path ?? "");
+    validateEndpointRoute({ method, path }, diagnosticPath, diagnostics);
+
+    const routeKey = `${method} ${path}`;
+    const existing = seenRoutes.get(routeKey);
+    if (existing) {
+      diagnostics.push(diagnostic("server/index.ts", `Endpoint ${name} duplicates ${existing} at ${routeKey}.`));
+      continue;
+    }
+    seenRoutes.set(routeKey, name);
+
+    cleanEndpoints[name] = {
+      method,
+      op: "source",
+      path
+    };
+  }
+
+  return { diagnostics, endpoints: cleanEndpoints };
+}
+
 function compileQueryHandler({ handler, name, schema }) {
   const { ctx, recorder } = createTraceContext({ mode: "query", schema });
   try {
@@ -615,7 +679,12 @@ export async function createAnonymousArtifact({ app, clientOut, serverOut, sourc
   const sourceFiles = await readSourceFiles(sourceStore);
   const diagnostics = forbiddenSourceDiagnostics(sourceFiles, { allowAsync: Boolean(serverOut) });
   const { diagnostics: schemaDiagnostics, schema } = serializeSchema(app.schema);
+  const { diagnostics: endpointDiagnostics, endpoints } = serializeEndpoints(app.endpoints);
   diagnostics.push(...schemaDiagnostics);
+  diagnostics.push(...endpointDiagnostics);
+  if (!serverOut && Object.keys(endpoints).length > 0) {
+    diagnostics.push(diagnostic("server/index.ts", "Endpoints require the source runtime. Build with a bundled server module."));
+  }
 
   if (diagnostics.length > 0) {
     throw new AnonymousCompilerError(diagnostics);
@@ -631,6 +700,7 @@ export async function createAnonymousArtifact({ app, clientOut, serverOut, sourc
   const sourceSnapshotHash = sha256(stableStringify(sourceManifest));
   const server = serverBundle
     ? {
+        endpoints,
         helpers: {},
         imports: ["lakebed/server"],
         mutations: Object.fromEntries(Object.keys(app.mutations ?? {}).map((name) => [name, { op: "source" }])),
@@ -674,6 +744,7 @@ export async function createAnonymousArtifact({ app, clientOut, serverOut, sourc
       maxValueBytes: DEFAULT_ANONYMOUS_LIMITS.maxValueBytes
     },
     server: server ?? {
+      endpoints: {},
       helpers: {},
       imports: ["lakebed/server"],
       mutations: compiled.mutations,
@@ -707,7 +778,9 @@ export async function createClaimedArtifact({ app, clientOut, serverOut, sourceS
       entry.message !== "Async server handlers are not part of the anonymous IR yet. Use synchronous Lakebed database operations."
   );
   const { diagnostics: schemaDiagnostics, schema } = serializeSchema(app.schema);
+  const { diagnostics: endpointDiagnostics, endpoints } = serializeEndpoints(app.endpoints);
   diagnostics.push(...schemaDiagnostics);
+  diagnostics.push(...endpointDiagnostics);
   if (diagnostics.length > 0) {
     throw new AnonymousCompilerError(diagnostics);
   }
@@ -739,6 +812,7 @@ export async function createClaimedArtifact({ app, clientOut, serverOut, sourceS
       maxValueBytes: DEFAULT_ANONYMOUS_LIMITS.maxValueBytes
     },
     server: {
+      endpoints,
       helpers: {},
       imports: ["lakebed/server"],
       mutations: Object.fromEntries(Object.keys(app.mutations ?? {}).map((name) => [name, { op: "source" }])),
@@ -922,6 +996,30 @@ export function validateAnonymousArtifact(artifact, { allowClaimedSource = false
     }
   }
 
+  const seenEndpointRoutes = new Map();
+  for (const [name, endpoint] of Object.entries(artifact.server?.endpoints ?? {})) {
+    const path = `artifact.server.endpoints.${name}`;
+    if (!isPlainObject(endpoint) || endpoint.op !== "source") {
+      diagnostics.push(diagnostic(path, "Endpoint must be source-backed."));
+      continue;
+    }
+
+    validateEndpointRoute(endpoint, path, diagnostics);
+    const routeKey = `${endpoint.method} ${endpoint.path}`;
+    const existing = seenEndpointRoutes.get(routeKey);
+    if (existing) {
+      diagnostics.push(diagnostic(path, `Endpoint route duplicates ${existing}.`));
+    }
+    seenEndpointRoutes.set(routeKey, name);
+
+    if (artifact.server?.source === undefined) {
+      diagnostics.push(diagnostic(path, "Source endpoint requires artifact.server.source."));
+    }
+    if (!sourceDeployTargets.has(artifact.deployTarget)) {
+      diagnostics.push(diagnostic(path, "Source endpoint requires deployTarget anonymous-source or claimed-source."));
+    }
+  }
+
   if (artifact.server?.source !== undefined) {
     if (!sourceDeployTargets.has(artifact.deployTarget)) {
       diagnostics.push(diagnostic("artifact.server.source", "Server source bundles require deployTarget anonymous-source or claimed-source."));
@@ -1449,3 +1547,146 @@ export async function executeAnonymousMutation({ args = [], artifact, auth, depl
     return null;
   }, mutationTransactionOptions(limits));
 }
+
+function normalizeEndpointHeaders(headers = {}) {
+  if (!headers) {
+    return {};
+  }
+
+  if (typeof headers.entries === "function") {
+    return Object.fromEntries(Array.from(headers.entries()).map(([key, value]) => [String(key), String(value)]));
+  }
+
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers.map(([key, value]) => [String(key), String(value)]));
+  }
+
+  if (isPlainObject(headers)) {
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [String(key), String(value)]));
+  }
+
+  return {};
+}
+
+function endpointBodyToBase64(body) {
+  if (body === undefined || body === null) {
+    return "";
+  }
+  if (typeof body === "string") {
+    return Buffer.from(body, "utf8").toString("base64");
+  }
+  if (body instanceof ArrayBuffer) {
+    return Buffer.from(body).toString("base64");
+  }
+  if (ArrayBuffer.isView(body)) {
+    return Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString("base64");
+  }
+  return Buffer.from(JSON.stringify(body ?? null), "utf8").toString("base64");
+}
+
+function endpointStatus(status, fallback = 200) {
+  const parsed = Number(status);
+  return Number.isInteger(parsed) && parsed >= 100 && parsed <= 599 ? parsed : fallback;
+}
+
+async function normalizeEndpointResponse(result) {
+  if (result === undefined || result === null) {
+    return { bodyBase64: "", headers: {}, status: 204 };
+  }
+
+  if (typeof Response !== "undefined" && result instanceof Response) {
+    const body = Buffer.from(await result.arrayBuffer());
+    return {
+      bodyBase64: body.toString("base64"),
+      headers: normalizeEndpointHeaders(result.headers),
+      status: endpointStatus(result.status)
+    };
+  }
+
+  if (isPlainObject(result) && result.kind === "response") {
+    return {
+      bodyBase64: endpointBodyToBase64(result.body),
+      headers: normalizeEndpointHeaders(result.headers),
+      status: endpointStatus(result.status)
+    };
+  }
+
+  if (typeof result === "string") {
+    return {
+      bodyBase64: endpointBodyToBase64(result),
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+      status: 200
+    };
+  }
+
+  return {
+    bodyBase64: endpointBodyToBase64(result),
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+    status: 200
+  };
+}
+
+function createEndpointRequest(request) {
+  const url = new URL(request.url ?? request.path ?? "/", "http://lakebed.local");
+  const body = Buffer.from(request.bodyBase64 ?? "", "base64");
+  const headers = new Map(
+    Object.entries(normalizeEndpointHeaders(request.headers)).map(([key, value]) => [key.toLowerCase(), String(value)])
+  );
+
+  return {
+    headers: {
+      entries() {
+        return headers.entries();
+      },
+      get(name) {
+        return headers.get(String(name).toLowerCase()) ?? null;
+      },
+      has(name) {
+        return headers.has(String(name).toLowerCase());
+      }
+    },
+    method: String(request.method ?? "GET").toUpperCase(),
+    path: request.path ?? url.pathname,
+    query: new URLSearchParams(url.searchParams),
+    url: url.href,
+    async bytes() {
+      return new Uint8Array(body);
+    },
+    async json() {
+      return JSON.parse(body.toString("utf8"));
+    },
+    async text() {
+      return body.toString("utf8");
+    }
+  };
+}
+
+export async function executeAnonymousEndpoint({ artifact, auth, deployId, limits = DEFAULT_ANONYMOUS_LIMITS, name, request, sourceRuntime, state }) {
+  const endpoint = artifact.server?.endpoints?.[name];
+  if (!endpoint) {
+    throw new Error(`Unknown endpoint: ${name}`);
+  }
+
+  if (!artifact.server?.source) {
+    throw new Error(`Endpoint ${name} requires the source runtime.`);
+  }
+
+  if (sourceRuntime) {
+    return sourceRuntime.executeEndpoint({ artifact, auth, deployId, limits, name, request, state });
+  }
+
+  const sourceApp = await loadSourceApp(artifact);
+  const definition = sourceApp.endpoints?.[name];
+  const handler = definition?.handler ?? definition;
+  if (typeof handler !== "function") {
+    throw new Error(`Unknown endpoint: ${name}`);
+  }
+
+  return state.transaction(deployId, async (tx) => {
+    const source = await createSourceContext({ artifact, auth, deployId, state: tx });
+    const result = await handler(source.ctx, createEndpointRequest(request));
+    const response = await normalizeEndpointResponse(result);
+    await source.flush(tx);
+    return response;
+  }, mutationTransactionOptions(limits));
+}