@divizend/scratch-core 1.0.0

package/http-server/index.ts

@@ -0,0 +1,3 @@
+export * from "./HttpServer";
+export * from "./NativeHttpServer";
+

package/http-server/middlewares/01-cors.ts

@@ -0,0 +1,33 @@
+/**
+ * CORS Middleware
+ * Handles CORS preflight requests and sets CORS headers
+ */
+
+import { Middleware, MiddlewareContext } from "./types";
+
+export const corsMiddleware: Middleware = async (ctx, next) => {
+  const { req, res } = ctx;
+
+  // Handle CORS preflight
+  if (req.method === "OPTIONS") {
+    setCorsHeaders(res);
+    res.writeHead(200);
+    res.end();
+    return;
+  }
+
+  // Set CORS headers for all responses
+  setCorsHeaders(res);
+  await next();
+};
+
+function setCorsHeaders(res: any): void {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader(
+    "Access-Control-Allow-Methods",
+    "GET, POST, PUT, DELETE, OPTIONS"
+  );
+  res.setHeader("Access-Control-Allow-Headers", "*");
+  res.setHeader("Access-Control-Expose-Headers", "*");
+}
+

package/http-server/middlewares/02-static.ts

@@ -0,0 +1,67 @@
+/**
+ * Static File Middleware
+ * Serves static files from the configured root directory
+ */
+
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { Middleware, MiddlewareContext } from "./types";
+
+export interface StaticMiddlewareOptions {
+  rootPath: string | null;
+}
+
+export function createStaticMiddleware(
+  options: StaticMiddlewareOptions
+): Middleware {
+  return async (ctx, next) => {
+    const { req, res, context } = ctx;
+    const path = context.path || "";
+
+    if (!options.rootPath || !path.startsWith("/public/")) {
+      await next();
+      return;
+    }
+
+    try {
+      const filePath = join(options.rootPath, path.substring(8)); // Remove "/public/"
+      const stats = await stat(filePath);
+      if (!stats.isFile()) {
+        await next();
+        return;
+      }
+
+      const content = await readFile(filePath);
+      const ext = filePath.split(".").pop()?.toLowerCase();
+      const contentTypeMap: Record<string, string> = {
+        html: "text/html",
+        css: "text/css",
+        js: "application/javascript",
+        json: "application/json",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        svg: "image/svg+xml",
+      };
+      const contentType = contentTypeMap[ext || ""] || "application/octet-stream";
+
+      setNoCacheHeaders(res);
+      res.writeHead(200, { "Content-Type": contentType });
+      res.end(content);
+      // Don't call next() - we've handled the request
+    } catch (error) {
+      await next();
+    }
+  };
+}
+
+function setNoCacheHeaders(res: any): void {
+  res.setHeader(
+    "Cache-Control",
+    "no-store, no-cache, must-revalidate, max-age=0"
+  );
+  res.setHeader("Pragma", "no-cache");
+  res.setHeader("Expires", "0");
+}
+

package/http-server/middlewares/03-request-logger.ts

@@ -0,0 +1,159 @@
+/**
+ * Request Logger Middleware
+ * Logs incoming requests and responses with structured logging
+ */
+
+import { randomUUID } from "node:crypto";
+import { Middleware, MiddlewareContext } from "./types";
+
+// Keep per-request metadata without leaking memory
+const meta = new WeakMap<any, { id: string; start: number }>();
+
+// Minimal structured logger - automatically adds timestamp unless explicitly provided
+const log = (record: Record<string, unknown>) => {
+  if (!record.ts) {
+    record.ts = new Date().toISOString();
+  }
+  console.log(JSON.stringify(record));
+};
+
+// Best-effort client IP from common proxy/CDN headers
+const getClientIP = (req: any): string | undefined => {
+  const headers = req.headers || {};
+  const getHeader = (name: string) => {
+    const value = headers[name] || headers[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value;
+  };
+
+  const xForwardedFor = getHeader("x-forwarded-for");
+  if (xForwardedFor) {
+    return xForwardedFor.split(",")[0]?.trim();
+  }
+
+  return (
+    getHeader("x-real-ip") ||
+    getHeader("x-client-ip") ||
+    getHeader("cf-connecting-ip") ||
+    getHeader("fastly-client-ip") ||
+    getHeader("x-cluster-client-ip") ||
+    getHeader("x-forwarded") ||
+    getHeader("forwarded-for") ||
+    getHeader("forwarded") ||
+    getHeader("appengine-user-ip") ||
+    getHeader("true-client-ip") ||
+    getHeader("cf-pseudo-ipv4") ||
+    undefined
+  );
+};
+
+export const requestLoggerMiddleware: Middleware = async (ctx, next) => {
+  const { req, res, context, metadata } = ctx;
+
+  // Accept incoming request ID or generate one
+  const reqId =
+    req.headers?.["x-request-id"] ||
+    req.headers?.["X-Request-Id"] ||
+    "" ||
+    randomUUID();
+
+  // Set response header
+  res.setHeader("x-request-id", reqId);
+
+  // Stash timing data for this request
+  const start = performance.now();
+  metadata.requestId = reqId;
+  metadata.startTime = start;
+  meta.set(req, { id: reqId, start });
+
+  // Parse URL for logging - use query from context if available (already filtered)
+  const url = req.url || "/";
+  const urlObj = new URL(url, `http://${req.headers?.host || "localhost"}`);
+  const query: Record<string, string> =
+    context.query || Object.fromEntries(urlObj.searchParams);
+
+  // Base request log
+  log({
+    level: "info",
+    event: "request",
+    req_id: reqId,
+    method: req.method || "GET",
+    path: urlObj.pathname,
+    query: Object.keys(query).length > 0 ? query : undefined,
+    ip: getClientIP(req),
+    ua: req.headers?.["user-agent"] || undefined,
+    referer: req.headers?.referer || req.headers?.referrer || undefined,
+    req_len: Number(req.headers?.["content-length"] || "") || undefined,
+    content_type: req.headers?.["content-type"] || undefined,
+  });
+
+  log({
+    level: "info",
+    event: "after_request_log",
+    req_id: reqId,
+    path: urlObj.pathname,
+    query_keys: Object.keys(query),
+  });
+
+  // Track response status and length
+  let statusCode = 200;
+  let responseLength: number | undefined = undefined;
+
+  // Intercept writeHead to capture status
+  const originalWriteHead = res.writeHead.bind(res);
+  res.writeHead = function (status: number, headers?: any) {
+    statusCode = status;
+    if (headers && headers["content-length"]) {
+      responseLength = Number(headers["content-length"]) || undefined;
+    }
+    return originalWriteHead(status, headers);
+  };
+
+  // Intercept setHeader to capture content-length
+  const originalSetHeader = res.setHeader.bind(res);
+  res.setHeader = function (name: string, value: string | number) {
+    if (name.toLowerCase() === "content-length") {
+      responseLength = Number(value) || undefined;
+    }
+    return originalSetHeader(name, value);
+  };
+
+  try {
+    await next();
+
+    // Log response after next() completes
+    const m = meta.get(req);
+    const duration = m ? Math.round(performance.now() - m.start) : undefined;
+
+    log({
+      level: "info",
+      event: "response",
+      req_id: reqId,
+      status: statusCode,
+      duration_ms: duration,
+      res_len: responseLength,
+    });
+
+    meta.delete(req);
+  } catch (error) {
+    // Log error
+    const m = meta.get(req);
+    const reqIdForError = m?.id || reqId;
+    const urlObjForError = new URL(
+      req.url || "/",
+      `http://${req.headers?.host || "localhost"}`
+    );
+
+    log({
+      level: "error",
+      event: "error",
+      req_id: reqIdForError,
+      method: req.method || "GET",
+      path: urlObjForError.pathname,
+      status: statusCode,
+      message: error instanceof Error ? error.message : String(error),
+    });
+
+    meta.delete(req);
+    throw error;
+  }
+};

package/http-server/middlewares/04-body-parser.ts

@@ -0,0 +1,54 @@
+/**
+ * Body Parser Middleware
+ * Parses request body for POST/PUT/PATCH requests
+ */
+
+import { Middleware, MiddlewareContext } from "./types";
+
+async function readBody(req: any): Promise<any> {
+  return new Promise((resolve, reject) => {
+    // If body is already parsed (from fetch handler), use it
+    if ((req as any).body !== undefined) {
+      resolve((req as any).body);
+      return;
+    }
+
+    let body = "";
+    req.on("data", (chunk: any) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        const contentType = req.headers?.["content-type"] || "";
+        if (contentType.includes("application/json")) {
+          resolve(body ? JSON.parse(body) : {});
+        } else {
+          resolve(body || {});
+        }
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+export const bodyParserMiddleware: Middleware = async (ctx, next) => {
+  const { req, context } = ctx;
+  const method = req.method || "GET";
+
+  // Read body once if needed (for POST/PUT/PATCH)
+  if (["POST", "PUT", "PATCH"].includes(method)) {
+    try {
+      const requestBody = await readBody(req);
+      // Store body in request object for later use
+      (req as any).body = requestBody;
+      context.requestBody = requestBody;
+    } catch {
+      // Ignore body reading errors
+    }
+  }
+
+  await next();
+};
+

package/http-server/middlewares/05-no-cache.ts

@@ -0,0 +1,23 @@
+/**
+ * No-Cache Middleware
+ * Sets no-cache headers for all responses
+ */
+
+import { Middleware, MiddlewareContext } from "./types";
+
+export const noCacheMiddleware: Middleware = async (ctx, next) => {
+  const { res } = ctx;
+
+  setNoCacheHeaders(res);
+  await next();
+};
+
+function setNoCacheHeaders(res: any): void {
+  res.setHeader(
+    "Cache-Control",
+    "no-store, no-cache, must-revalidate, max-age=0"
+  );
+  res.setHeader("Pragma", "no-cache");
+  res.setHeader("Expires", "0");
+}
+

package/http-server/middlewares/06-response-handler.ts

@@ -0,0 +1,39 @@
+/**
+ * Response Handler Middleware
+ * Handles converting handler responses to HTTP responses
+ */
+
+import { Middleware, MiddlewareContext } from "./types";
+
+export const responseHandlerMiddleware: Middleware = async (ctx, next) => {
+  const { req, res, context } = ctx;
+
+  // This middleware runs after routing, so if we get here,
+  // the route handler should have already set the response
+  // But we can add response formatting here if needed
+  await next();
+};
+
+/**
+ * Converts a handler result to an HTTP response
+ */
+export function handleHandlerResult(result: any, res: any): void {
+  if (result instanceof Response) {
+    // Copy Response to Node response
+    res.writeHead(result.status, Object.fromEntries(result.headers));
+    result.text().then((body) => res.end(body));
+    return;
+  }
+  if (typeof result === "string") {
+    res.writeHead(200, { "Content-Type": "text/plain" });
+    res.end(result);
+    return;
+  }
+  if (result === null || result === undefined) {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ success: true }));
+    return;
+  }
+  res.writeHead(200, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(result));
+}

package/http-server/middlewares/handler-wrapper.ts

@@ -0,0 +1,250 @@
+/**
+ * Handler Wrapper Utilities
+ * Wraps handlers with auth and validation logic
+ */
+
+import {
+  Universe,
+  ScratchContext,
+  ScratchBlock,
+  ScratchEndpointDefinition,
+  JsonSchema,
+  JsonSchemaValidator,
+  UniverseModule,
+} from "../../core/index";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+// Type alias for schema property values
+type SchemaProperty = NonNullable<ScratchBlock["schema"]>[string];
+
+export interface HandlerWrapperOptions {
+  universe: Universe;
+  endpoint: ScratchEndpointDefinition;
+  noAuth?: boolean;
+  requiredModules?: UniverseModule[];
+}
+
+/**
+ * Wraps a handler with authentication and validation
+ */
+export async function wrapHandlerWithAuthAndValidation(
+  options: HandlerWrapperOptions
+): Promise<
+  (
+    context: ScratchContext,
+    query?: Record<string, string>,
+    requestBody?: any,
+    authHeader?: string
+  ) => Promise<any>
+> {
+  const { universe, endpoint, noAuth = false, requiredModules = [] } = options;
+
+  // Get the block definition to extract schema
+  const blockDef = await endpoint.block({});
+  const schema = blockDef.schema;
+
+  // Create the wrapped handler
+  return async (
+    context: ScratchContext,
+    query: Record<string, string> = {},
+    requestBody: any = undefined,
+    authHeader: string | undefined = undefined
+  ) => {
+    // Auth check
+    if (!noAuth) {
+      if (!universe.auth.isConfigured()) {
+        throw new Error("JWT authentication not configured");
+      }
+
+      if (!authHeader || !authHeader.startsWith("Bearer ")) {
+        throw new Error("Missing or invalid authorization header");
+      }
+
+      const token = authHeader.substring(7);
+      try {
+        const payload = await universe.auth.validateJwtToken(token);
+        if (!payload) {
+          throw new Error("Invalid or expired token");
+        }
+      } catch {
+        throw new Error("Invalid or expired token");
+      }
+    }
+
+    // Extract user email from auth header if present
+    let userEmail: string | undefined;
+    try {
+      if (authHeader?.startsWith("Bearer ")) {
+        const payload = await universe.auth.validateJwtToken(
+          authHeader.substring(7)
+        );
+        if (payload) userEmail = (payload as any)?.email;
+      }
+    } catch {}
+
+    // Update context with user email, authHeader, and ensure universe is set
+    const enrichedContext: ScratchContext = {
+      ...context,
+      userEmail,
+      universe: universe,
+      authHeader: authHeader, // Store authHeader for nested calls
+    };
+
+    // Module validation
+    if (requiredModules.length > 0) {
+      const missingModules = requiredModules.filter(
+        (module) => !universe.hasModule(module)
+      );
+      if (missingModules.length > 0) {
+        throw new Error(
+          `Required modules not available: ${missingModules.join(", ")}`
+        );
+      }
+    }
+
+    // Schema validation
+    if (schema) {
+      const validator =
+        universe?.jsonSchemaValidator || new JsonSchemaValidator();
+      const fullSchema = constructJsonSchema(schema);
+      const isGet = blockDef.blockType === "reporter";
+
+      // For GET requests, query params go directly into inputs
+      // For POST requests, request body goes into inputs
+      let data: any = isGet
+        ? Object.fromEntries(
+            Object.keys(schema).map((key) => [key, query[key] || undefined])
+          )
+        : requestBody || {};
+
+      // Handle JSON type properties
+      if (schema) {
+        for (const [key, propSchema] of Object.entries(schema)) {
+          const typedPropSchema = propSchema as SchemaProperty;
+          if (
+            typedPropSchema.type === "json" &&
+            data[key] !== undefined &&
+            data[key] !== null &&
+            data[key] !== ""
+          ) {
+            try {
+              // If data[key] is already an object, use it directly
+              let parsed = data[key];
+              if (typeof data[key] === "string") {
+                parsed = JSON.parse(data[key]);
+              }
+              if (typedPropSchema.schema) {
+                const wrappedSchema: JsonSchema = {
+                  type: "object",
+                  properties: { value: typedPropSchema.schema },
+                  required: ["value"],
+                };
+                const result = validator.validate(wrappedSchema, {
+                  value: parsed,
+                });
+                if (!result.valid) {
+                  throw new Error(
+                    `Validation failed for ${key}: ${JSON.stringify(
+                      result.errors
+                    )}`
+                  );
+                }
+                data[key] = result.data?.value ?? parsed;
+              } else {
+                data[key] = parsed;
+              }
+            } catch (parseError) {
+              throw new Error(
+                `Invalid JSON for ${key}: ${
+                  parseError instanceof Error
+                    ? parseError.message
+                    : "Unknown error"
+                }`
+              );
+            }
+          }
+        }
+      }
+
+      // Validate the data
+      const dataForValidation: any = { ...data };
+      if (schema) {
+        for (const [key, propSchema] of Object.entries(schema)) {
+          const typedPropSchema = propSchema as SchemaProperty;
+          if (
+            typedPropSchema.type === "json" &&
+            dataForValidation[key] !== undefined
+          )
+            delete dataForValidation[key];
+        }
+      }
+
+      const result = validator.validate(fullSchema, dataForValidation);
+      if (!result.valid) {
+        throw new Error(`Validation failed: ${JSON.stringify(result.errors)}`);
+      }
+
+      const finalData = { ...result.data };
+      if (schema) {
+        for (const [key, propSchema] of Object.entries(schema)) {
+          const typedPropSchema = propSchema as SchemaProperty;
+          if (typedPropSchema.type === "json" && data[key] !== undefined)
+            finalData[key] = data[key];
+        }
+      }
+
+      enrichedContext.inputs = finalData;
+    } else {
+      // For endpoints without schema, set empty inputs
+      enrichedContext.inputs = {};
+    }
+
+    // Call the original handler
+    return await endpoint.handler(enrichedContext);
+  };
+}
+
+function constructJsonSchema(schema?: ScratchBlock["schema"]): JsonSchema {
+  if (!schema)
+    return {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    };
+  const properties: any = {};
+  const required: string[] = [];
+  for (const [key, propSchema] of Object.entries(schema)) {
+    // Type assertion: schema is defined as Record<string, {...}>, so propSchema is the value type
+    const typedPropSchema = propSchema as SchemaProperty;
+    if (typedPropSchema.type === "json") {
+      if (!typedPropSchema.schema)
+        throw new Error(
+          `Property ${key} has type "json" but no schema provided`
+        );
+      properties[key] = {
+        type: "string",
+        description: typedPropSchema.description,
+        _jsonSchema: typedPropSchema.schema,
+      };
+    } else {
+      // Copy schema but exclude non-JSON-Schema fields
+      const {
+        default: _,
+        description: __,
+        ...jsonSchemaProps
+      } = typedPropSchema;
+      properties[key] = jsonSchemaProps;
+      // Only add to required if there's no default or default is a placeholder
+      if (!typedPropSchema.default || typedPropSchema.default === `[${key}]`) {
+        required.push(key);
+      }
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    required,
+    additionalProperties: false,
+  };
+}

package/http-server/middlewares/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Middleware exports
+ */
+
+export * from "./types";
+export * from "./01-cors";
+export * from "./02-static";
+export * from "./03-request-logger";
+export * from "./04-body-parser";
+export * from "./05-no-cache";
+export * from "./06-response-handler";
+export * from "./handler-wrapper";
+
+import { Middleware } from "./types";
+import { corsMiddleware } from "./01-cors";
+import { createStaticMiddleware } from "./02-static";
+import { requestLoggerMiddleware } from "./03-request-logger";
+import { bodyParserMiddleware } from "./04-body-parser";
+import { noCacheMiddleware } from "./05-no-cache";
+
+/**
+ * Creates the middleware chain for NativeHttpServer
+ * @param staticRootPath - Root path for static files (or null)
+ * @returns Array of middlewares in execution order
+ */
+export function createMiddlewareChain(
+  staticRootPath: string | null
+): Middleware[] {
+  return [
+    corsMiddleware,
+    createStaticMiddleware({ rootPath: staticRootPath }),
+    requestLoggerMiddleware,
+    bodyParserMiddleware,
+    noCacheMiddleware,
+  ];
+}
+

package/http-server/middlewares/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Middleware types for NativeHttpServer
+ */
+
+import { IncomingMessage, ServerResponse } from "node:http";
+import { ScratchContext } from "../../index";
+
+export interface MiddlewareContext {
+  req: IncomingMessage | any;
+  res: ServerResponse | any;
+  context: ScratchContext & { [key: string]: any };
+  metadata: {
+    requestId?: string;
+    startTime?: number;
+    [key: string]: any;
+  };
+}
+
+export type Middleware = (
+  ctx: MiddlewareContext,
+  next: () => Promise<void>
+) => Promise<void> | void;
+
+export interface MiddlewareResult {
+  handled: boolean;
+}
+