@robodev-ai/runtime 0.1.0

package/src/handler-timeout.ts

@@ -0,0 +1,26 @@
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const MAX_TIMEOUT_MS = 30_000;
+
+export class HandlerTimeoutError extends Error {
+  constructor() {
+    super("handler_timeout");
+    this.name = "HandlerTimeoutError";
+  }
+}
+
+export function clampTimeoutMs(value?: number): number {
+  if (value == null || !Number.isFinite(value)) return DEFAULT_TIMEOUT_MS;
+  return Math.min(MAX_TIMEOUT_MS, Math.max(1, Math.floor(value)));
+}
+
+export async function withHandlerTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new HandlerTimeoutError()), timeoutMs);
+  });
+  try {
+    return await Promise.race([run(), timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/ids.ts

@@ -0,0 +1,10 @@
+import { customAlphabet } from "nanoid";
+
+const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+const nano = customAlphabet(alphabet, 12);
+
+export function id(prefix: string): string {
+  // Project ids appear in hostnames; Let's Encrypt rejects underscores.
+  const sep = prefix === "prj" ? "-" : "_";
+  return `${prefix}${sep}${nano()}`;
+}

package/src/index.ts

@@ -0,0 +1,195 @@
+/**
+ * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
+ * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
+ * loading, schema push, route matching, OpenAPI, handler invocation, and Robodev Auth.
+ */
+
+export {
+  BINARY_EXTENSIONS,
+  DEPLOY_BODY_LIMIT_BYTES,
+  DeployValidationError,
+  LEGACY_DATABASE_FILE,
+  MAX_FILE_BYTES,
+  MAX_FILE_COUNT,
+  MAX_PATH_DEPTH,
+  MAX_PATH_LENGTH,
+  MAX_STATIC_FILE_BYTES,
+  MAX_TREE_BYTES,
+  MAX_WORKSPACE_FILE_COUNT,
+  PUBLIC_BINARY_EXTENSIONS,
+  ROBODEV_DATABASE_FILE,
+  ROBODEV_PACKAGE_JSON,
+  ROBODEV_PREFIX,
+  apiCompilePaths,
+  backendRootFromFiles,
+  classifyDeployPath,
+  databaseFilePath,
+  deployFileStoredBytes,
+  detectFrontendKind,
+  formatLimitMb,
+  isAllowedDeployPath,
+  isAllowedWorkspacePath,
+  isApiPath,
+  isBackendTestPath,
+  isConfigPath,
+  isDeniedPath,
+  isDeniedWorkspacePath,
+  isHookPath,
+  isJobPath,
+  isPublicBinaryPath,
+  isPublicPath,
+  isRootStaticPath,
+  isServedStaticPath,
+  isSocketPath,
+  isSrcPath,
+  isUnsafeDeployPath,
+  mapPackagesBePath,
+  mapWorkspaceToDeployFiles,
+  mixedBackendLayoutError,
+  normalizeDeployPath,
+  reactEntryPath,
+  stripRobodevPrefix,
+  validateDeployFiles,
+  webServePath,
+  workspaceHasFrontend,
+  workspaceHasPublishableFrontend,
+  workspaceHasTinyFrontend,
+  type DeployFile,
+  type DeployFileError,
+  type FileClass,
+  type FrontendKind,
+} from "./deploy-files.js";
+
+export {
+  fileToRoute,
+  fileToSocketRoute,
+  isAuthHookFile,
+  jobNameFromFile,
+  matchPathParams,
+  matchProjectRoute,
+  matchSocketRoute,
+  openApiDocumentedPath,
+  openApiPath,
+  pathParamNames,
+  socketNameFromFile,
+  type FileRoute,
+  type RouteCandidate,
+} from "./path-match.js";
+
+export { buildOpenApi, scalarHtml, swaggerHtml, type RuntimeRoute } from "./openapi.js";
+
+export { applyPlan, buildPlan, type SchemaOp, type SchemaPlan } from "./schema-sync.js";
+
+export { encodeHandlerResult, type EncodedHandlerResult } from "./handler-response.js";
+
+export {
+  DEFAULT_TIMEOUT_MS,
+  HandlerTimeoutError,
+  MAX_TIMEOUT_MS,
+  clampTimeoutMs,
+  withHandlerTimeout,
+} from "./handler-timeout.js";
+
+export {
+  MAX_MULTIPART_FILE_BYTES,
+  mediaType,
+  parseMultipart,
+  parseUrlEncoded,
+} from "./multipart.js";
+
+export { hashPassword, verifyPassword } from "./password.js";
+
+export { id } from "./ids.js";
+
+export {
+  ApiBuildError,
+  HOST_SDK,
+  apiBundleExternals,
+  compileApiTree,
+  isEsbuildFailure,
+  isNodeBuiltin,
+  mapEsbuildErrors,
+  writeDeploySources,
+  type CompileApiOptions,
+  type CompileIssue,
+} from "./compile.js";
+
+export {
+  loadModules,
+  type LoadedModules,
+  type RuntimeAuthHook,
+  type RuntimeJob,
+  type RuntimeSocket,
+} from "./load-modules.js";
+
+export {
+  isReservedAuthPath,
+  isReservedProjectPath,
+  isReservedRobodevPath,
+  isReservedStoragePath,
+} from "./reserved-paths.js";
+
+export {
+  runRoute,
+  type MappedError,
+  type RouteClients,
+  type RouteOutcome,
+  type RunRouteInput,
+} from "./invoke.js";
+
+export {
+  PROJECT_ACCESS_TTL,
+  PROJECT_ACCESS_TYP,
+  bearerToken,
+  projectSecret,
+  signProjectUserToken,
+  verifyProjectUserToken,
+} from "./project-jwt.js";
+
+export {
+  NONCE_TTL_MS,
+  REFRESH_TTL_MS,
+  consumeNonce,
+  createNonce,
+  ensureAuthSchema,
+  hashToken,
+  insertPasswordUser,
+  issueProjectTokenPair,
+  loadRefreshSession,
+  loadUserByEmail,
+  loadUserById,
+  passwordMatches,
+  randomSecret,
+  revokeRefresh,
+  rotateRefresh,
+  toAuthUser,
+  updateUserPassword,
+  updateUserProfile,
+  type AuthQueryable,
+  type AuthRow,
+  type NonceType,
+} from "./auth-core.js";
+
+export {
+  GENERIC_STATUS_MESSAGE,
+  emailField,
+  forgotCallbackBody,
+  forgotRequestBody,
+  googleStartQuery,
+  loginBody,
+  magicConsumeQuery,
+  magicGenerateQuery,
+  meUpdateBody,
+  refreshBody,
+  registerBody,
+  statusOk,
+} from "./auth-schemas.js";
+
+export {
+  handleLocalAuth,
+  isLocalAuthPath,
+  resolveLocalUser,
+  type LocalAuthOptions,
+  type LocalAuthRequest,
+  type LocalAuthResult,
+} from "./local-auth.js";

package/src/invoke.ts

@@ -0,0 +1,225 @@
+import type {
+  AgentClient,
+  ApiHandlerContext,
+  AuthUser,
+  EmailClient,
+  JobsClient,
+  LlmClient,
+  PushClient,
+  RobodevDb,
+  SocketsClient,
+  StorageClient,
+  UploadedFile,
+} from "@robodev-ai/sdk";
+import { encodeHandlerResult, type EncodedHandlerResult } from "./handler-response.js";
+import { clampTimeoutMs, HandlerTimeoutError, withHandlerTimeout } from "./handler-timeout.js";
+import {
+  MAX_MULTIPART_FILE_BYTES,
+  mediaType,
+  parseMultipart,
+  parseUrlEncoded,
+} from "./multipart.js";
+import type { RuntimeRoute } from "./openapi.js";
+import { matchProjectRoute } from "./path-match.js";
+
+/** Everything a handler context needs that the host, not the runtime, provides. */
+export type RouteClients = {
+  email: EmailClient;
+  llm: LlmClient;
+  agent: AgentClient;
+  storage: StorageClient;
+  push: PushClient;
+  jobs: JobsClient;
+  sockets: SocketsClient;
+  env: Record<string, string>;
+};
+
+export type RouteOutcome =
+  | { kind: "ok"; encoded: EncodedHandlerResult }
+  | { kind: "error"; status: number; body: Record<string, unknown> };
+
+export type MappedError = { status: number; body: Record<string, unknown> };
+
+export type RunRouteInput = {
+  db: RobodevDb;
+  routes: readonly RuntimeRoute[];
+  method: string;
+  pathname: string;
+  query: unknown;
+  body: unknown;
+  rawBody?: Buffer;
+  headers: Record<string, string | string[] | undefined>;
+  authorization?: string;
+  /** Per-file multipart ceiling. Defaults to the runtime's own limit. */
+  maxUploadBytes?: number;
+  /** Resolves the Robodev Auth user for `auth: "required" | "optional"`. */
+  resolveUser: (authorization?: string) => Promise<AuthUser | null>;
+  /** Built after auth passes, right before the handler runs. */
+  clients: () => Promise<RouteClients> | RouteClients;
+  /** True when the request carries a valid schedule signature. */
+  verifySchedule?: (headers: Record<string, string | string[] | undefined>) => boolean;
+  scheduleId?: string;
+  /** Lets the host translate its own error types before the generic 500. */
+  mapError?: (error: unknown) => MappedError | null;
+};
+
+function invalid(status: number, body: Record<string, unknown>): RouteOutcome {
+  return { kind: "error", status, body };
+}
+
+/**
+ * Matches one request against the loaded file routes, validates it, runs the handler
+ * under the shared timeout, and encodes the result. Hosted project hosts and
+ * `robodev dev` share this so validation and response shapes cannot drift.
+ */
+export async function runRoute(input: RunRouteInput): Promise<RouteOutcome> {
+  const matched = matchProjectRoute(input.pathname, input.method, input.routes as RuntimeRoute[]);
+  if (!matched) {
+    return invalid(404, {
+      error: "route_not_found",
+      message: `${input.method} ${input.pathname} is not deployed`,
+    });
+  }
+
+  const { route, params } = matched;
+  const contentType = mediaType(
+    typeof input.headers["content-type"] === "string" ? input.headers["content-type"] : undefined,
+  );
+  let query: unknown = input.query ?? {};
+  let body: unknown = input.body;
+  let files: UploadedFile[] | undefined;
+  const rawBody = input.rawBody;
+
+  if (route.def.query) {
+    const parsed = route.def.query.safeParse(input.query ?? {});
+    if (!parsed.success) {
+      return invalid(400, { error: "invalid_query", details: parsed.error.flatten() });
+    }
+    query = parsed.data;
+  }
+
+  if (route.def.multipart) {
+    if (!rawBody) {
+      return invalid(400, { error: "invalid_body", message: "missing multipart body" });
+    }
+    const parsed = await parseMultipart(
+      rawBody,
+      typeof input.headers["content-type"] === "string"
+        ? input.headers["content-type"]
+        : "multipart/form-data",
+      input.maxUploadBytes ?? MAX_MULTIPART_FILE_BYTES,
+    );
+    files = parsed.files;
+    body = parsed.fields;
+    if (route.def.body) {
+      const parsedBody = route.def.body.safeParse(body);
+      if (!parsedBody.success) {
+        return invalid(400, { error: "invalid_body", details: parsedBody.error.flatten() });
+      }
+      body = parsedBody.data;
+    }
+  } else if (route.def.rawBody) {
+    if (contentType === "application/json") {
+      try {
+        body = rawBody && rawBody.length ? JSON.parse(rawBody.toString("utf8")) : {};
+      } catch {
+        return invalid(400, { error: "invalid_body", message: "invalid JSON" });
+      }
+    } else if (contentType === "application/x-www-form-urlencoded") {
+      body = rawBody ? parseUrlEncoded(rawBody) : {};
+    } else if (contentType === "application/octet-stream") {
+      body = undefined;
+    }
+    if (route.def.body && contentType !== "application/octet-stream") {
+      const parsed = route.def.body.safeParse(body);
+      if (!parsed.success) {
+        return invalid(400, { error: "invalid_body", details: parsed.error.flatten() });
+      }
+      body = parsed.data;
+    }
+  } else if (route.def.body && input.method !== "get") {
+    const parsed = route.def.body.safeParse(input.body);
+    if (!parsed.success) {
+      return invalid(400, { error: "invalid_body", details: parsed.error.flatten() });
+    }
+    body = parsed.data;
+  }
+
+  const scheduleValid = input.verifySchedule ? input.verifySchedule(input.headers) : false;
+  const schedule = scheduleValid
+    ? { id: input.scheduleId ?? "schedule" }
+    : input.scheduleId
+      ? { id: input.scheduleId }
+      : null;
+
+  let user: AuthUser | null = null;
+  const auth = route.def.auth ?? false;
+  if (auth === "schedule") {
+    if (!scheduleValid) {
+      return invalid(401, {
+        error: "unauthorized",
+        message: "missing or invalid schedule signature",
+      });
+    }
+  } else if (typeof auth === "function") {
+    try {
+      user = await auth({ headers: input.headers });
+    } catch {
+      user = null;
+    }
+    if (!user) {
+      return invalid(401, {
+        error: "unauthorized",
+        message: "auth verifier rejected the request",
+      });
+    }
+  } else if (auth === "required" || auth === "optional") {
+    user = await input.resolveUser(input.authorization);
+    if (auth === "required" && !user) {
+      return invalid(401, {
+        error: "unauthorized",
+        message: "missing or invalid access token",
+      });
+    }
+  }
+
+  try {
+    const clients = await input.clients();
+    const context: ApiHandlerContext<never, never> = {
+      db: input.db,
+      email: clients.email,
+      llm: clients.llm,
+      agent: clients.agent,
+      storage: clients.storage,
+      env: clients.env,
+      params,
+      query: query as never,
+      body: body as never,
+      headers: input.headers,
+      user,
+      ...(rawBody ? { rawBody } : {}),
+      ...(files ? { files } : {}),
+      push: clients.push,
+      jobs: clients.jobs,
+      sockets: clients.sockets,
+      schedule,
+    };
+    const result = await withHandlerTimeout(
+      () => Promise.resolve(route.def.handler(context)),
+      clampTimeoutMs(route.def.timeoutMs),
+    );
+    return { kind: "ok", encoded: encodeHandlerResult(result) };
+  } catch (error) {
+    if (error instanceof HandlerTimeoutError) {
+      return invalid(504, { error: "handler_timeout" });
+    }
+    const mapped = input.mapError?.(error);
+    if (mapped) {
+      return invalid(mapped.status, mapped.body);
+    }
+    return invalid(500, {
+      error: "handler_failed",
+      message: error instanceof Error ? error.message : "Handler failed",
+    });
+  }
+}

package/src/load-modules.ts

@@ -0,0 +1,164 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  HTTP_METHODS,
+  isApiDefinition,
+  isAuthHookDefinition,
+  isDatabaseDef,
+  isJobDefinition,
+  isSocketDefinition,
+  type AuthHookDefinition,
+  type DatabaseDef,
+  type JobDefinition,
+  type SocketDefinition,
+} from "@robodev-ai/sdk";
+import { databaseFilePath, type DeployFile } from "./deploy-files.js";
+import type { RuntimeRoute } from "./openapi.js";
+import {
+  fileToRoute,
+  fileToSocketRoute,
+  isAuthHookFile,
+  jobNameFromFile,
+  socketNameFromFile,
+} from "./path-match.js";
+import { isReservedProjectPath } from "./reserved-paths.js";
+
+export type RuntimeJob = {
+  name: string;
+  file: string;
+  def: JobDefinition;
+};
+
+export type RuntimeSocket = {
+  name: string;
+  path: string;
+  file: string;
+  paramNames: string[];
+  def: SocketDefinition;
+};
+
+export type RuntimeAuthHook = {
+  file: string;
+  def: AuthHookDefinition;
+};
+
+export type LoadedModules = {
+  database: DatabaseDef;
+  routes: RuntimeRoute[];
+  jobs: RuntimeJob[];
+  sockets: RuntimeSocket[];
+  authHook?: RuntimeAuthHook;
+};
+
+async function importFresh(absPath: string): Promise<Record<string, unknown>> {
+  const url = `${pathToFileURL(absPath).href}?t=${Date.now()}`;
+  return (await import(url)) as Record<string, unknown>;
+}
+
+function compiledPath(distDir: string, sourcePath: string): string {
+  return join(distDir, sourcePath.replace(/\.ts$/, ".js"));
+}
+
+/**
+ * Imports the compiled bundle and turns it into routes, jobs, sockets, and the auth hook.
+ * `distDir` is the output of `compileApiTree`.
+ */
+export async function loadModules(
+  distDir: string,
+  files: readonly DeployFile[],
+): Promise<LoadedModules> {
+  const dbPath = databaseFilePath(files);
+  if (!dbPath) {
+    throw new Error("deployment must include database.ts");
+  }
+
+  const dbMod = await importFresh(compiledPath(distDir, dbPath));
+  const database = dbMod.default;
+  if (!isDatabaseDef(database)) {
+    throw new Error("database.ts must default-export defineDatabase(...)");
+  }
+
+  const routes: RuntimeRoute[] = [];
+  for (const file of files) {
+    const mapped = fileToRoute(file.path);
+    if (!mapped || isReservedProjectPath(mapped.path)) continue;
+    const mod = await importFresh(compiledPath(distDir, file.path));
+    for (const method of HTTP_METHODS) {
+      const exported = mod[method];
+      if (isApiDefinition(exported)) {
+        if (exported.rawBody && exported.multipart) {
+          throw Object.assign(
+            new Error(`rawBody and multipart cannot both be set in ${file.path}`),
+            { statusCode: 400, code: "invalid_api_definition", path: file.path },
+          );
+        }
+        routes.push({
+          method,
+          path: mapped.path,
+          file: file.path,
+          def: exported,
+          paramNames: mapped.paramNames,
+        });
+      }
+    }
+  }
+
+  const jobs: RuntimeJob[] = [];
+  const seenJobs = new Set<string>();
+  for (const file of files) {
+    const name = jobNameFromFile(file.path);
+    if (!name) continue;
+    if (seenJobs.has(name)) {
+      throw Object.assign(new Error(`Duplicate job name: ${name}`), {
+        statusCode: 400,
+        code: "duplicate_job",
+        path: file.path,
+      });
+    }
+    const mod = await importFresh(compiledPath(distDir, file.path));
+    if (!isJobDefinition(mod.default)) continue;
+    seenJobs.add(name);
+    jobs.push({ name, file: file.path, def: mod.default });
+  }
+
+  const sockets: RuntimeSocket[] = [];
+  const seenSockets = new Set<string>();
+  for (const file of files) {
+    const name = socketNameFromFile(file.path);
+    const mapped = fileToSocketRoute(file.path);
+    if (!name || !mapped) continue;
+    if (seenSockets.has(name)) {
+      throw Object.assign(new Error(`Duplicate socket name: ${name}`), {
+        statusCode: 400,
+        code: "duplicate_socket",
+        path: file.path,
+      });
+    }
+    const mod = await importFresh(compiledPath(distDir, file.path));
+    if (!isSocketDefinition(mod.default)) continue;
+    seenSockets.add(name);
+    sockets.push({
+      name,
+      path: mapped.path,
+      file: file.path,
+      paramNames: mapped.paramNames,
+      def: mod.default,
+    });
+  }
+
+  let authHook: RuntimeAuthHook | undefined;
+  const authHookFile = files.find((file) => isAuthHookFile(file.path));
+  if (authHookFile) {
+    const mod = await importFresh(compiledPath(distDir, authHookFile.path));
+    if (!isAuthHookDefinition(mod.default)) {
+      throw Object.assign(new Error("hooks/auth.ts must default-export defineAuthHook(...)"), {
+        statusCode: 400,
+        code: "invalid_auth_hook",
+        path: authHookFile.path,
+      });
+    }
+    authHook = { file: authHookFile.path, def: mod.default };
+  }
+
+  return { database, routes, jobs, sockets, authHook };
+}