@epoch32/visage 0.0.0-stage → 0.0.0

package/src/api/handler.ts

@@ -0,0 +1,326 @@
+/**
+ * Visage Web Standard API Fetch Handler & Request Dispatcher
+ */
+import { validateWithSchema } from "../form/schema";
+import { ERROR_CODE_TO_STATUS, RPCError } from "../rpc/error";
+import { buildFileRouter } from "./file-router";
+import { executeMiddlewareChain } from "./middleware";
+import type { ApiProcedure, ApiRouterConfig, FileRouteModule, RouteMatch } from "./types";
+
+/**
+ * Handle CORS preflight & headers
+ */
+function handleCors(req: Request, config?: ApiRouterConfig["cors"]): Response | null {
+  if (!config) return null;
+
+  const origin = req.headers.get("Origin") || "*";
+  const isAllowed =
+    !config.origin ||
+    config.origin === "*" ||
+    (typeof config.origin === "function" && config.origin(origin)) ||
+    (Array.isArray(config.origin) && config.origin.includes(origin)) ||
+    config.origin === origin;
+
+  if (req.method === "OPTIONS") {
+    const headers = new Headers();
+    if (isAllowed) {
+      headers.set("Access-Control-Allow-Origin", origin);
+    }
+    headers.set(
+      "Access-Control-Allow-Methods",
+      (config.methods || ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]).join(", ")
+    );
+    headers.set(
+      "Access-Control-Allow-Headers",
+      (config.allowedHeaders || ["Content-Type", "Authorization", "x-visage-rpc"]).join(", ")
+    );
+    if (config.credentials) {
+      headers.set("Access-Control-Allow-Credentials", "true");
+    }
+    if (config.maxAge) {
+      headers.set("Access-Control-Max-Age", config.maxAge.toString());
+    }
+    return new Response(null, { status: 204, headers });
+  }
+
+  return null;
+}
+
+function applyCorsHeaders(res: Response, req: Request, config?: ApiRouterConfig["cors"]): Response {
+  if (!config) return res;
+  const origin = req.headers.get("Origin") || "*";
+  res.headers.set("Access-Control-Allow-Origin", origin);
+  if (config.credentials) {
+    res.headers.set("Access-Control-Allow-Credentials", "true");
+  }
+  return res;
+}
+
+/**
+ * Create a standard Web Fetch API handler from compiled route manifests
+ */
+export function createApiHandler(
+  routes: RouteMatch[],
+  config: ApiRouterConfig = {}
+): (req: Request) => Promise<Response> {
+  const prefix = config.prefix ? `/${config.prefix.replace(/^\/+|\/+$/g, "")}` : "";
+
+  return async (req: Request): Promise<Response> => {
+    // 1. CORS Preflight Check
+    const corsPreflight = handleCors(req, config.cors);
+    if (corsPreflight) return corsPreflight;
+
+    const url = new URL(req.url);
+    let pathname = url.pathname;
+
+    if (prefix && pathname.startsWith(prefix)) {
+      pathname = pathname.slice(prefix.length) || "/";
+    }
+
+    // 2. Route Matching
+    let matchedRoute: RouteMatch | null = null;
+    const pathParams: Record<string, string> = {};
+
+    for (const route of routes) {
+      const match = pathname.match(route.pattern);
+      if (match) {
+        matchedRoute = route;
+        route.paramNames.forEach((name, i) => {
+          pathParams[name] = decodeURIComponent(match[i + 1] || "");
+        });
+        break;
+      }
+    }
+
+    if (!matchedRoute) {
+      return applyCorsHeaders(
+        new Response(
+          JSON.stringify({
+            ok: false,
+            error: { code: "NOT_FOUND", message: `Route not found: ${pathname}` }
+          }),
+          { status: 404, headers: { "Content-Type": "application/json" } }
+        ),
+        req,
+        config.cors
+      );
+    }
+
+    try {
+      const method = req.method.toUpperCase();
+      let procedure: ApiProcedure | undefined = matchedRoute.procedures.default;
+
+      if (!procedure) {
+        if (method === "GET") {
+          procedure = matchedRoute.procedures.GET || matchedRoute.procedures.get;
+        } else if (method === "POST") {
+          procedure = matchedRoute.procedures.POST || matchedRoute.procedures.post;
+        } else if (method === "PUT") {
+          procedure = matchedRoute.procedures.PUT || matchedRoute.procedures.put;
+        } else if (method === "DELETE") {
+          procedure =
+            matchedRoute.procedures.DELETE ||
+            matchedRoute.procedures.del ||
+            matchedRoute.procedures.delete;
+        } else if (method === "PATCH") {
+          procedure = matchedRoute.procedures.PATCH || matchedRoute.procedures.patch;
+        }
+      }
+
+      // 3. Execute Middleware Chain (File-level + Procedure-level)
+      const mwFns = [
+        ...matchedRoute.middlewares.map((m) => m.fn),
+        ...(procedure?.middlewares || [])
+      ];
+
+      const { response: earlyResponse, ctx } = await executeMiddlewareChain(
+        mwFns,
+        req,
+        url,
+        pathParams
+      );
+
+      if (earlyResponse) {
+        return applyCorsHeaders(earlyResponse, req, config.cors);
+      }
+
+      // 4. Custom Raw Handler
+      if (matchedRoute.handler) {
+        const res = await matchedRoute.handler(req, ctx);
+        return applyCorsHeaders(res, req, config.cors);
+      }
+
+      if (!procedure) {
+        return applyCorsHeaders(
+          new Response(
+            JSON.stringify({
+              ok: false,
+              error: {
+                code: "METHOD_NOT_ALLOWED",
+                message: `Method ${method} not allowed on ${pathname}`
+              }
+            }),
+            { status: 405, headers: { "Content-Type": "application/json" } }
+          ),
+          req,
+          config.cors
+        );
+      }
+
+      // Parse Input
+      let rawInput: any = {};
+      if (method === "GET") {
+        const inputQuery = url.searchParams.get("input");
+        if (inputQuery) {
+          try {
+            rawInput = JSON.parse(inputQuery);
+          } catch {
+            rawInput = inputQuery;
+          }
+        } else {
+          // Flatten searchParams
+          const spObj: Record<string, string> = {};
+          url.searchParams.forEach((val, key) => {
+            spObj[key] = val;
+          });
+          if (Object.keys(spObj).length > 0) {
+            rawInput = spObj;
+          }
+        }
+      } else {
+        const contentType = req.headers.get("Content-Type") || "";
+        if (contentType.includes("application/json")) {
+          try {
+            rawInput = await req.json();
+          } catch {
+            rawInput = {};
+          }
+        }
+      }
+
+      // Merge Path Params into Input if object
+      if (typeof rawInput === "object" && rawInput !== null) {
+        rawInput = { ...pathParams, ...rawInput };
+      }
+
+      // Validate Input Schema
+      let validatedInput = rawInput;
+      if (procedure.options.input) {
+        const validation = await validateWithSchema(procedure.options.input, rawInput);
+        if (!validation.success) {
+          return applyCorsHeaders(
+            new Response(
+              JSON.stringify({
+                ok: false,
+                error: {
+                  code: "BAD_REQUEST",
+                  message: "Validation Error",
+                  issues: validation.issues
+                }
+              }),
+              { status: 400, headers: { "Content-Type": "application/json" } }
+            ),
+            req,
+            config.cors
+          );
+        }
+        validatedInput = validation.data;
+      }
+
+      // Run Procedure
+      if (procedure.type === "subscription") {
+        // SSE Real-time Streaming
+        const generator = procedure.options.resolve({
+          input: validatedInput,
+          ctx,
+          req,
+          params: pathParams
+        }) as AsyncGenerator<any, void, unknown>;
+
+        const stream = new ReadableStream({
+          async start(controller) {
+            const encoder = new TextEncoder();
+            try {
+              for await (const chunk of generator) {
+                const payload = `data: ${JSON.stringify(chunk)}\n\n`;
+                controller.enqueue(encoder.encode(payload));
+              }
+              controller.close();
+            } catch (err: any) {
+              controller.error(err);
+            }
+          }
+        });
+
+        const sseRes = new Response(stream, {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive"
+          }
+        });
+        return applyCorsHeaders(sseRes, req, config.cors);
+      }
+
+      const result = await procedure.options.resolve({
+        input: validatedInput,
+        ctx,
+        req,
+        params: pathParams
+      });
+
+      const successRes = new Response(JSON.stringify({ ok: true, data: result }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" }
+      });
+      return applyCorsHeaders(successRes, req, config.cors);
+    } catch (err: any) {
+      if (config.onError) {
+        const customRes = await config.onError(err, req);
+        return applyCorsHeaders(customRes, req, config.cors);
+      }
+
+      const statusCode =
+        err instanceof RPCError
+          ? err.statusCode
+          : ERROR_CODE_TO_STATUS[err?.code as keyof typeof ERROR_CODE_TO_STATUS] || 500;
+
+      const code = err instanceof RPCError ? err.code : "INTERNAL_SERVER_ERROR";
+      const message = err?.message || "Internal Server Error";
+
+      const errRes = new Response(JSON.stringify({ ok: false, error: { code, message } }), {
+        status: statusCode,
+        headers: { "Content-Type": "application/json" }
+      });
+      return applyCorsHeaders(errRes, req, config.cors);
+    }
+  };
+}
+
+/**
+ * High-level createApi factory for file-based API routers
+ */
+export function createApi(
+  files: Record<string, FileRouteModule | { default?: any; [key: string]: any }>,
+  sourceMapOrConfig?: Record<string, string> | ApiRouterConfig,
+  maybeConfig?: ApiRouterConfig
+) {
+  const sourceMap =
+    sourceMapOrConfig && !("prefix" in sourceMapOrConfig) && !("cors" in sourceMapOrConfig)
+      ? (sourceMapOrConfig as Record<string, string>)
+      : {};
+
+  const config =
+    maybeConfig ||
+    (sourceMapOrConfig && ("prefix" in sourceMapOrConfig || "cors" in sourceMapOrConfig)
+      ? (sourceMapOrConfig as ApiRouterConfig)
+      : {});
+
+  const routes = buildFileRouter(files, sourceMap);
+  const fetchHandler = createApiHandler(routes, config);
+
+  return {
+    routes,
+    fetch: fetchHandler
+  };
+}

package/src/api/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Visage File-Based API & Opinionated RPC Framework (visage/api)
+ */
+
+// Re-export standard schema validation & RPC errors
+export {
+  Schema,
+  type SchemaLike,
+  type StandardSchemaV1,
+  type ValidationIssue,
+  type ValidationResult,
+  v,
+  validateWithSchema
+} from "../form/schema";
+export {
+  ERROR_CODE_TO_STATUS,
+  RPCError,
+  STATUS_TO_ERROR_CODE
+} from "../rpc/error";
+export { createApiClient } from "./client";
+export {
+  buildFileRouter,
+  compileRoutePattern,
+  type FileRouteEntry,
+  normalizeFilePath
+} from "./file-router";
+export {
+  createApi,
+  createApiHandler
+} from "./handler";
+export { executeMiddlewareChain } from "./middleware";
+export {
+  globToRegExp,
+  matchesAnyPattern,
+  parsePragma,
+  shouldApplyMiddleware
+} from "./pragma";
+export {
+  defineMiddleware,
+  mutation,
+  ProcedureBuilder,
+  procedure,
+  query,
+  subscription
+} from "./procedure";
+export type {
+  ApiCallOptions,
+  ApiClient,
+  ApiClientHeadersRule,
+  ApiClientOptions,
+  ApiEndpointMethods,
+  ApiMethodCaller,
+  ApiProcedure,
+  ApiRouterConfig,
+  ApiSubscriptionCallbacks,
+  ApiSubscriptionCaller,
+  ApiSubscriptionHandle,
+  FileRouteModule,
+  HttpMethod,
+  InferApiInput,
+  InferApiOutput,
+  MiddlewareContext,
+  MiddlewareDefinition,
+  MiddlewareFn,
+  MiddlewarePragma,
+  NextFn,
+  ProcedureOptions,
+  ProcedureType,
+  RouteMatch,
+  RPCErrorCode
+} from "./types";

package/src/api/middleware.ts

@@ -0,0 +1,54 @@
+/**
+ * Visage Middleware Execution Engine & Context Propagation
+ */
+import type { MiddlewareFn, NextFn } from "./types";
+
+/**
+ * Execute a chain of middlewares, accumulating context and returning either an early Response or merged Context
+ */
+export async function executeMiddlewareChain(
+  middlewares: MiddlewareFn[],
+  req: Request,
+  url: URL,
+  params: Record<string, string>,
+  initialCtx: Record<string, any> = {}
+): Promise<{ response?: Response; ctx: Record<string, any> }> {
+  let currentCtx = { ...initialCtx };
+  let earlyResponse: Response | undefined;
+
+  let index = 0;
+
+  const runner = async (): Promise<void> => {
+    if (index >= middlewares.length) {
+      return;
+    }
+
+    const currentMw = middlewares[index++]!;
+    const next: NextFn = async (enriched) => {
+      if (enriched && typeof enriched === "object") {
+        currentCtx = { ...currentCtx, ...enriched };
+      }
+      await runner();
+      return currentCtx;
+    };
+
+    const result = await currentMw({
+      req,
+      ctx: currentCtx,
+      url,
+      params,
+      next
+    });
+
+    if (result instanceof Response) {
+      earlyResponse = result;
+    }
+  };
+
+  await runner();
+
+  return {
+    response: earlyResponse,
+    ctx: currentCtx
+  };
+}

package/src/api/pragma.ts

@@ -0,0 +1,155 @@
+/**
+ * Visage API Pragma Parser & Path Pattern Matcher
+ * Parses `// @visage-middleware` pragmas at the top of middleware files.
+ */
+import type { MiddlewarePragma } from "./types";
+
+const PRAGMA_REGEX =
+  /(?:\/\/\s*@visage-middleware\s+([^\r\n]+))|(?:\/\*\s*@visage-middleware\s+([\s\S]*?)\*\/)/i;
+
+/**
+ * Parse top-level `// @visage-middleware` pragma from file source code
+ */
+export function parsePragma(sourceCode: string): MiddlewarePragma {
+  if (!sourceCode || typeof sourceCode !== "string") {
+    return { cascade: true, match: ["*"], exclude: [], priority: 0 };
+  }
+
+  const match = sourceCode.match(PRAGMA_REGEX);
+  if (!match) {
+    return { cascade: true, match: ["*"], exclude: [], priority: 0 };
+  }
+
+  const rawDirective = (match[1] || match[2] || "").trim();
+  const pragma: MiddlewarePragma = {
+    cascade: true,
+    match: ["*"],
+    exclude: [],
+    priority: 0
+  };
+
+  // Parse comma-separated or key-value options: cascade: true, match: ["..."], exclude: ["..."]
+  const pairs = rawDirective.split(/,(?![^[]*\])/);
+  for (const pair of pairs) {
+    const colonIdx = pair.indexOf(":");
+    if (colonIdx === -1) continue;
+
+    const key = pair.slice(0, colonIdx).trim().toLowerCase();
+    const valStr = pair.slice(colonIdx + 1).trim();
+
+    if (key === "cascade") {
+      pragma.cascade = valStr === "true" || valStr === "1";
+    } else if (key === "priority") {
+      const num = Number.parseInt(valStr, 10);
+      if (!Number.isNaN(num)) pragma.priority = num;
+    } else if (key === "match" || key === "exclude") {
+      let items: string[] = [];
+      if (valStr.startsWith("[") && valStr.endsWith("]")) {
+        try {
+          items = JSON.parse(valStr.replace(/'/g, '"'));
+        } catch {
+          items = valStr
+            .slice(1, -1)
+            .split(",")
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+            .filter(Boolean);
+        }
+      } else {
+        items = [valStr.replace(/^['"]|['"]$/g, "")];
+      }
+
+      if (key === "match") pragma.match = items;
+      if (key === "exclude") pragma.exclude = items;
+    }
+  }
+
+  return pragma;
+}
+
+/**
+ * Convert a glob-like pattern (e.g. `admin/*`, `users/**`, `stats`) into a RegExp
+ */
+export function globToRegExp(pattern: string): RegExp {
+  const normalized = pattern.trim().replace(/^\/+|\/+$/g, "");
+  if (normalized === "*" || normalized === "**" || normalized === "") {
+    return /^.*$/;
+  }
+
+  const escaped = normalized
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "___DOUBLE_STAR___")
+    .replace(/\*/g, "[^/]+")
+    .replace(/___DOUBLE_STAR___/g, ".*");
+
+  return new RegExp(`^(?:/)?${escaped}(?:/)?$`);
+}
+
+/**
+ * Test whether a normalized route path matches any glob pattern in a list
+ */
+export function matchesAnyPattern(routePath: string, patterns: string[]): boolean {
+  if (!patterns || patterns.length === 0) return false;
+  const cleanPath = routePath.replace(/^\/+|\/+$/g, "");
+
+  for (const pat of patterns) {
+    const cleanPat = pat.replace(/^\/+|\/+$/g, "");
+    if (cleanPat === "*" || cleanPat === "**") return true;
+    if (cleanPat === cleanPath) return true;
+    if (globToRegExp(cleanPat).test(cleanPath)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Evaluate if a middleware definition should apply to a specific route
+ */
+export function shouldApplyMiddleware(
+  pragma: MiddlewarePragma,
+  routePath: string,
+  routeDir: string,
+  middlewareDir: string
+): boolean {
+  const normRouteDir = routeDir.replace(/^\/+|\/+$/g, "");
+  const normMwDir = middlewareDir.replace(/^\/+|\/+$/g, "");
+
+  // 1. Ancestor check: routeDir must be equal to or a subfolder of middlewareDir
+  const isDirectDir = normRouteDir === normMwDir;
+  const isSubDir =
+    normMwDir === "" ? normRouteDir !== "" : normRouteDir.startsWith(`${normMwDir}/`);
+
+  if (!isDirectDir && !isSubDir) {
+    return false;
+  }
+
+  // 2. Cascading check: if route is in a subfolder and cascade is false, do not apply
+  const isCascade = pragma.cascade ?? true;
+  if (isSubDir && !isCascade) {
+    return false;
+  }
+
+  // 3. Relative route path within the middleware's domain
+  let relativePath = routePath.replace(/^\/+|\/+$/g, "");
+  if (normMwDir && relativePath.startsWith(normMwDir)) {
+    relativePath = relativePath.slice(normMwDir.length).replace(/^\/+/, "");
+  }
+
+  // 4. Exclude rule takes immediate precedence
+  if (pragma.exclude && pragma.exclude.length > 0) {
+    if (
+      matchesAnyPattern(routePath, pragma.exclude) ||
+      matchesAnyPattern(relativePath, pragma.exclude)
+    ) {
+      return false;
+    }
+  }
+
+  // 5. Match rule
+  if (!pragma.match || pragma.match.length === 0 || pragma.match.includes("*")) {
+    return true;
+  }
+
+  return (
+    matchesAnyPattern(routePath, pragma.match) || matchesAnyPattern(relativePath, pragma.match)
+  );
+}