shokupan 0.0.1 → 0.1.0

package/dist/index.js

@@ -1,17 +1,15 @@
 import { trace, SpanKind, SpanStatusCode, context } from "@opentelemetry/api";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { Eta } from "eta";
 import { stat, readdir } from "fs/promises";
 import { resolve, join, basename } from "path";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OAuth2Client, Okta, Auth0, Apple, MicrosoftEntraId, Google, GitHub, generateState, generateCodeVerifier } from "arctic";
 import * as jose from "jose";
+import { OpenAPIAnalyzer } from "./openapi-analyzer-cjdGeQ5a.js";
 import { randomUUID, createHmac } from "crypto";
 import { EventEmitter } from "events";
+import { plainToInstance } from "class-transformer";
+import { validateOrReject } from "class-validator";
 class ShokupanResponse {
   _headers = new Headers();
   _status = 200;
@@ -67,8 +65,10 @@ class ShokupanResponse {
   }
 }
 class ShokupanContext {
-  constructor(request, state) {
+  constructor(request, server, state, app) {
     this.request = request;
+    this.server = server;
+    this.app = app;
     this.url = new URL(request.url);
     this.state = state || {};
     this.response = new ShokupanResponse();
@@ -101,12 +101,55 @@ class ShokupanContext {
   get query() {
     return Object.fromEntries(this.url.searchParams);
   }
+  /**
+   * Client IP address
+   */
+  get ip() {
+    return this.server?.requestIP(this.request);
+  }
+  /**
+   * Request hostname (e.g. "localhost")
+   */
+  get hostname() {
+    return this.url.hostname;
+  }
+  /**
+   * Request host (e.g. "localhost:3000")
+   */
+  get host() {
+    return this.url.host;
+  }
+  /**
+   * Request protocol (e.g. "http:", "https:")
+   */
+  get protocol() {
+    return this.url.protocol;
+  }
+  /**
+   * Whether request is secure (https)
+   */
+  get secure() {
+    return this.url.protocol === "https:";
+  }
+  /**
+   * Request origin (e.g. "http://localhost:3000")
+   */
+  get origin() {
+    return this.url.origin;
+  }
   /**
    * Request headers
    */
   get headers() {
     return this.request.headers;
   }
+  /**
+   * Get a request header
+   * @param name Header name
+   */
+  get(name) {
+    return this.request.headers.get(name);
+  }
   /**
    * Base response object
    */
@@ -115,6 +158,8 @@ class ShokupanContext {
   }
   /**
    * Helper to set a header on the response
+   * @param key Header key
+   * @param value Header value
    */
   set(key, value) {
     this.response.set(key, value);
@@ -226,6 +271,23 @@ class ShokupanContext {
     const status = responseOptions?.status ?? this.response.status;
     return new Response(Bun.file(path, fileOptions), { status, headers });
   }
+  /**
+   * JSX Rendering Function
+   */
+  renderer;
+  /**
+   * Render a JSX element
+   * @param element JSX Element
+   * @param status HTTP Status
+   * @param headers HTTP Headers
+   */
+  async jsx(element, args, status, headers) {
+    if (!this.renderer) {
+      throw new Error("No JSX renderer configured");
+    }
+    const html = await this.renderer(element, args);
+    return this.html(html, status, headers);
+  }
 }
 const $isApplication = /* @__PURE__ */ Symbol.for("Shokupan.app");
 const $appRoot = /* @__PURE__ */ Symbol.for("Shokupan.app-root");
@@ -240,6 +302,8 @@ const $childRouters = /* @__PURE__ */ Symbol.for("Shokupan.child-routers");
 const $childControllers = /* @__PURE__ */ Symbol.for("Shokupan.child-controllers");
 const $mountPath = /* @__PURE__ */ Symbol.for("Shokupan.mount-path");
 const $dispatch = /* @__PURE__ */ Symbol.for("Shokupan.dispatch");
+const $routes = /* @__PURE__ */ Symbol.for("Shokupan.routes");
+const $routeSpec = /* @__PURE__ */ Symbol.for("Shokupan.routeSpec");
 const HTTPMethods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "ALL"];
 var RouteParamType = /* @__PURE__ */ ((RouteParamType2) => {
   RouteParamType2["BODY"] = "BODY";
@@ -292,6 +356,14 @@ const Query = createParamDecorator(RouteParamType.QUERY);
 const Headers$1 = createParamDecorator(RouteParamType.HEADER);
 const Req = createParamDecorator(RouteParamType.REQUEST);
 const Ctx = createParamDecorator(RouteParamType.CONTEXT);
+function Spec(spec) {
+  return (target, propertyKey, descriptor) => {
+    if (!target[$routeSpec]) {
+      target[$routeSpec] = /* @__PURE__ */ new Map();
+    }
+    target[$routeSpec].set(propertyKey, spec);
+  };
+}
 function createMethodDecorator(method) {
   return (path = "/") => {
     return (target, propertyKey, descriptor) => {
@@ -346,20 +418,6 @@ function Inject(token) {
     });
   };
 }
-const provider = new NodeTracerProvider({
-  resource: resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: "basic-service"
-  }),
-  spanProcessors: [
-    new SimpleSpanProcessor(
-      new OTLPTraceExporter({
-        url: "http://localhost:4318/v1/traces"
-        // Default OTLP port
-      })
-    )
-  ]
-});
-provider.register();
 const tracer = trace.getTracer("shokupan.middleware");
 function traceMiddleware(fn, name) {
   const middlewareName = fn.name || "anonymous middleware";
@@ -449,7 +507,6 @@ class ShokupanRequestBase {
   }
 }
 const ShokupanRequest = ShokupanRequestBase;
-const asyncContext = new AsyncLocalStorage();
 function isObject(item) {
   return item && typeof item === "object" && !Array.isArray(item);
 }
@@ -463,7 +520,17 @@ function deepMerge(target, ...sources) {
         deepMerge(target[key], source[key]);
       } else if (Array.isArray(source[key])) {
         if (!target[key]) Object.assign(target, { [key]: [] });
-        target[key] = target[key].concat(source[key]);
+        if (key === "tags") {
+          target[key] = source[key];
+          continue;
+        }
+        const mergedArray = target[key].concat(source[key]);
+        const isPrimitive = (item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean";
+        if (mergedArray.every(isPrimitive)) {
+          target[key] = Array.from(new Set(mergedArray));
+        } else {
+          target[key] = mergedArray;
+        }
       } else {
         Object.assign(target, { [key]: source[key] });
       }
@@ -471,12 +538,583 @@ function deepMerge(target, ...sources) {
   }
   return deepMerge(target, ...sources);
 }
+function analyzeHandler(handler) {
+  const handlerSource = handler.toString();
+  const inferredSpec = {};
+  if (handlerSource.includes("ctx.body") || handlerSource.includes("await ctx.req.json()")) {
+    inferredSpec.requestBody = {
+      content: { "application/json": { schema: { type: "object" } } }
+    };
+  }
+  const queryParams = /* @__PURE__ */ new Map();
+  const queryIntMatch = handlerSource.match(/parseInt\(ctx\.query\.(\w+)\)/g);
+  if (queryIntMatch) {
+    queryIntMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName) queryParams.set(paramName, { type: "integer", format: "int32" });
+    });
+  }
+  const queryFloatMatch = handlerSource.match(/parseFloat\(ctx\.query\.(\w+)\)/g);
+  if (queryFloatMatch) {
+    queryFloatMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName) queryParams.set(paramName, { type: "number", format: "float" });
+    });
+  }
+  const queryNumberMatch = handlerSource.match(/Number\(ctx\.query\.(\w+)\)/g);
+  if (queryNumberMatch) {
+    queryNumberMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "number" });
+      }
+    });
+  }
+  const queryBoolMatch = handlerSource.match(/(?:Boolean\(ctx\.query\.(\w+)\)|!+ctx\.query\.(\w+))/g);
+  if (queryBoolMatch) {
+    queryBoolMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.query\.(\w+)/)?.[1];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "boolean" });
+      }
+    });
+  }
+  const queryMatch = handlerSource.match(/ctx\.query\.(\w+)/g);
+  if (queryMatch) {
+    queryMatch.forEach((match) => {
+      const paramName = match.split(".")[2];
+      if (paramName && !queryParams.has(paramName)) {
+        queryParams.set(paramName, { type: "string" });
+      }
+    });
+  }
+  if (queryParams.size > 0) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    queryParams.forEach((schema, paramName) => {
+      inferredSpec.parameters.push({
+        name: paramName,
+        in: "query",
+        schema: { type: schema.type, ...schema.format ? { format: schema.format } : {} }
+      });
+    });
+  }
+  const pathParams = /* @__PURE__ */ new Map();
+  const paramIntMatch = handlerSource.match(/parseInt\(ctx\.params\.(\w+)\)/g);
+  if (paramIntMatch) {
+    paramIntMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.params\.(\w+)/)?.[1];
+      if (paramName) pathParams.set(paramName, { type: "integer", format: "int32" });
+    });
+  }
+  const paramFloatMatch = handlerSource.match(/parseFloat\(ctx\.params\.(\w+)\)/g);
+  if (paramFloatMatch) {
+    paramFloatMatch.forEach((match) => {
+      const paramName = match.match(/ctx\.params\.(\w+)/)?.[1];
+      if (paramName) pathParams.set(paramName, { type: "number", format: "float" });
+    });
+  }
+  if (pathParams.size > 0) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    pathParams.forEach((schema, paramName) => {
+      inferredSpec.parameters.push({
+        name: paramName,
+        in: "path",
+        required: true,
+        schema: { type: schema.type, ...schema.format ? { format: schema.format } : {} }
+      });
+    });
+  }
+  const headerMatch = handlerSource.match(/ctx\.get\(['"](\w+)['"]\)/g);
+  if (headerMatch) {
+    if (!inferredSpec.parameters) inferredSpec.parameters = [];
+    headerMatch.forEach((match) => {
+      const headerName = match.match(/['"](\w+)['"]/)?.[1];
+      if (headerName) {
+        inferredSpec.parameters.push({
+          name: headerName,
+          in: "header",
+          schema: { type: "string" }
+        });
+      }
+    });
+  }
+  const responses = {};
+  if (handlerSource.includes("ctx.json(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "application/json": { schema: { type: "object" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.html(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "text/html": { schema: { type: "string" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.text(")) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "text/plain": { schema: { type: "string" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.file(")) {
+    responses["200"] = {
+      description: "File download",
+      content: {
+        "application/octet-stream": { schema: { type: "string", format: "binary" } }
+      }
+    };
+  }
+  if (handlerSource.includes("ctx.redirect(")) {
+    responses["302"] = {
+      description: "Redirect"
+    };
+  }
+  if (!responses["200"] && /return\s+\{/.test(handlerSource)) {
+    responses["200"] = {
+      description: "Successful response",
+      content: {
+        "application/json": { schema: { type: "object" } }
+      }
+    };
+  }
+  const errorStatusMatch = handlerSource.match(/ctx\.(?:json|text|html)\([^)]+,\s*(\d{3,})\)/g);
+  if (errorStatusMatch) {
+    errorStatusMatch.forEach((match) => {
+      const statusCode = match.match(/,\s*(\d{3,})\)/)?.[1];
+      if (statusCode && statusCode !== "200") {
+        responses[statusCode] = {
+          description: `Error response (${statusCode})`
+        };
+      }
+    });
+  }
+  if (Object.keys(responses).length > 0) {
+    inferredSpec.responses = responses;
+  }
+  return { inferredSpec };
+}
+async function generateOpenApi(rootRouter, options = {}) {
+  const paths = {};
+  const tagGroups = /* @__PURE__ */ new Map();
+  const defaultTagGroup = options.defaultTagGroup || "General";
+  const defaultTagName = options.defaultTag || "Application";
+  let astRoutes = [];
+  try {
+    const { OpenAPIAnalyzer: OpenAPIAnalyzer2 } = await import("./openapi-analyzer-cjdGeQ5a.js");
+    const analyzer = new OpenAPIAnalyzer2(process.cwd());
+    const { applications } = await analyzer.analyze();
+    const appMap = /* @__PURE__ */ new Map();
+    applications.forEach((app) => {
+      appMap.set(app.name, app);
+      if (app.name !== app.className) {
+        appMap.set(app.className, app);
+      }
+    });
+    const getExpandedRoutes = (app, prefix = "", seen = /* @__PURE__ */ new Set()) => {
+      if (seen.has(app.name)) return [];
+      const newSeen = new Set(seen);
+      newSeen.add(app.name);
+      const expanded = [];
+      for (const route of app.routes) {
+        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+        const cleanPath = route.path.startsWith("/") ? route.path : "/" + route.path;
+        let joined = cleanPrefix + cleanPath;
+        if (joined.length > 1 && joined.endsWith("/")) {
+          joined = joined.slice(0, -1);
+        }
+        expanded.push({
+          ...route,
+          path: joined || "/"
+        });
+      }
+      if (app.mounted) {
+        for (const mount of app.mounted) {
+          const targetApp = appMap.get(mount.target);
+          if (targetApp) {
+            const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+            const mountPrefix = mount.prefix.startsWith("/") ? mount.prefix : "/" + mount.prefix;
+            expanded.push(...getExpandedRoutes(targetApp, cleanPrefix + mountPrefix, newSeen));
+          }
+        }
+      }
+      return expanded;
+    };
+    applications.forEach((app) => {
+      astRoutes.push(...getExpandedRoutes(app));
+    });
+    const dedupedRoutes = /* @__PURE__ */ new Map();
+    for (const route of astRoutes) {
+      const key = `${route.method.toUpperCase()}:${route.path}`;
+      let score = 0;
+      if (route.responseSchema) score += 10;
+      if (route.handlerSource) score += 5;
+      if (!dedupedRoutes.has(key) || score > dedupedRoutes.get(key).score) {
+        dedupedRoutes.set(key, { route, score });
+      }
+    }
+    astRoutes = Array.from(dedupedRoutes.values()).map((v) => v.route);
+  } catch (e) {
+    console.warn("OpenAPI AST analysis failed or skipped:", e);
+  }
+  const collect = (router, prefix = "", currentGroup = defaultTagGroup, defaultTag = defaultTagName) => {
+    let group = currentGroup;
+    let tag = defaultTag;
+    if (router.config?.group) group = router.config.group;
+    if (router.config?.name) {
+      tag = router.config.name;
+    } else {
+      const mountPath = router[$mountPath];
+      if (mountPath && mountPath !== "/") {
+        const segments = mountPath.split("/").filter(Boolean);
+        if (segments.length > 0) {
+          const lastSegment = segments[segments.length - 1];
+          tag = lastSegment.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        }
+      }
+    }
+    if (!tagGroups.has(group)) tagGroups.set(group, /* @__PURE__ */ new Set());
+    const routes = router[$routes] || [];
+    for (const route of routes) {
+      const routeGroup = route.group || group;
+      const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+      const cleanSubPath = route.path.startsWith("/") ? route.path : "/" + route.path;
+      let fullPath = cleanPrefix + cleanSubPath || "/";
+      fullPath = fullPath.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
+      if (fullPath.length > 1 && fullPath.endsWith("/")) {
+        fullPath = fullPath.slice(0, -1);
+      }
+      if (!paths[fullPath]) paths[fullPath] = {};
+      const operation = {
+        responses: { "200": { description: "Successful response" } },
+        tags: [tag]
+      };
+      if (route.guards) {
+        for (const guard of route.guards) {
+          if (guard.spec) {
+            if (guard.spec.security) {
+              const existing = operation.security || [];
+              for (const req of guard.spec.security) {
+                const reqStr = JSON.stringify(req);
+                if (!existing.some((e) => JSON.stringify(e) === reqStr)) {
+                  existing.push(req);
+                }
+              }
+              operation.security = existing;
+            }
+            if (guard.spec.responses) {
+              operation.responses = { ...operation.responses, ...guard.spec.responses };
+            }
+          }
+        }
+      }
+      let astMatch = astRoutes.find(
+        (r) => r.method.toUpperCase() === route.method.toUpperCase() && r.path === fullPath
+      );
+      if (!astMatch) {
+        let runtimeSource = route.handler.toString();
+        if (route.handler.originalHandler) {
+          runtimeSource = route.handler.originalHandler.toString();
+        }
+        const runtimeHandlerSrc = runtimeSource.replace(/\s+/g, " ");
+        const sameMethodRoutes = astRoutes.filter((r) => r.method.toUpperCase() === route.method.toUpperCase());
+        astMatch = sameMethodRoutes.find((r) => {
+          const astHandlerSrc = (r.handlerSource || r.handlerName || "").replace(/\s+/g, " ");
+          if (!astHandlerSrc || astHandlerSrc.length < 20) return false;
+          const match = runtimeHandlerSrc.includes(astHandlerSrc) || astHandlerSrc.includes(runtimeHandlerSrc) || r.handlerSource && runtimeHandlerSrc.includes(r.handlerSource.substring(0, 50));
+          return match;
+        });
+      }
+      const potentialMatches = astRoutes.filter(
+        (r) => r.method.toUpperCase() === route.method.toUpperCase() && r.path === fullPath
+      );
+      if (potentialMatches.length > 1) {
+        const runtimeHandlerSrc = route.handler.toString().replace(/\s+/g, " ");
+        const preciseMatch = potentialMatches.find((r) => {
+          const astHandlerSrc = (r.handlerSource || r.handlerName || "").replace(/\s+/g, " ");
+          const match = runtimeHandlerSrc.includes(astHandlerSrc) || astHandlerSrc.includes(runtimeHandlerSrc) || r.handlerSource && runtimeHandlerSrc.includes(r.handlerSource.substring(0, 50));
+          return match;
+        });
+        if (preciseMatch) {
+          astMatch = preciseMatch;
+        }
+      }
+      if (astMatch) {
+        if (astMatch.summary) operation.summary = astMatch.summary;
+        if (astMatch.description) operation.description = astMatch.description;
+        if (astMatch.tags) operation.tags = astMatch.tags;
+        if (astMatch.operationId) operation.operationId = astMatch.operationId;
+        if (astMatch.requestTypes?.body) {
+          operation.requestBody = {
+            content: {
+              "application/json": { schema: astMatch.requestTypes.body }
+            }
+          };
+        }
+        if (astMatch.responseSchema) {
+          operation.responses["200"] = {
+            description: "Successful response",
+            content: {
+              "application/json": { schema: astMatch.responseSchema }
+            }
+          };
+        } else if (astMatch.responseType) {
+          const contentType = astMatch.responseType === "string" ? "text/plain" : "application/json";
+          operation.responses["200"] = {
+            description: "Successful response",
+            content: {
+              [contentType]: { schema: { type: astMatch.responseType } }
+            }
+          };
+        }
+        const params = [];
+        if (astMatch.requestTypes?.query) {
+          for (const [name, _type] of Object.entries(astMatch.requestTypes.query)) {
+            params.push({ name, in: "query", schema: { type: "string" } });
+          }
+        }
+        if (params.length > 0) {
+          operation.parameters = params;
+        }
+      }
+      if (route.keys.length > 0) {
+        const pathParams = route.keys.map((key) => ({
+          name: key,
+          in: "path",
+          required: true,
+          schema: { type: "string" }
+        }));
+        const existingParams = operation.parameters || [];
+        const mergedParams = [...existingParams];
+        pathParams.forEach((p) => {
+          const idx = mergedParams.findIndex((ep) => ep.in === "path" && ep.name === p.name);
+          if (idx >= 0) {
+            mergedParams[idx] = deepMerge(mergedParams[idx], p);
+          } else {
+            mergedParams.push(p);
+          }
+        });
+        operation.parameters = mergedParams;
+      }
+      const { inferredSpec } = analyzeHandler(route.handler);
+      if (inferredSpec) {
+        if (inferredSpec.parameters) {
+          const existingParams = operation.parameters || [];
+          const mergedParams = [...existingParams];
+          for (const p of inferredSpec.parameters) {
+            const idx = mergedParams.findIndex((ep) => ep.name === p.name && ep.in === p.in);
+            if (idx >= 0) {
+              mergedParams[idx] = deepMerge(mergedParams[idx], p);
+            } else {
+              mergedParams.push(p);
+            }
+          }
+          operation.parameters = mergedParams;
+          delete inferredSpec.parameters;
+        }
+        deepMerge(operation, inferredSpec);
+      }
+      if (route.handlerSpec) {
+        const spec = route.handlerSpec;
+        if (spec.summary) operation.summary = spec.summary;
+        if (spec.description) operation.description = spec.description;
+        if (spec.operationId) operation.operationId = spec.operationId;
+        if (spec.tags) operation.tags = spec.tags;
+        if (spec.security) operation.security = spec.security;
+        if (spec.responses) {
+          operation.responses = { ...operation.responses, ...spec.responses };
+        }
+      }
+      if (!operation.tags || operation.tags.length === 0) operation.tags = [tag];
+      if (operation.tags) {
+        operation.tags = Array.from(new Set(operation.tags));
+        for (const t of operation.tags) {
+          if (!tagGroups.has(routeGroup)) tagGroups.set(routeGroup, /* @__PURE__ */ new Set());
+          tagGroups.get(routeGroup)?.add(t);
+        }
+      }
+      const methodLower = route.method.toLowerCase();
+      if (methodLower === "all") {
+        ["get", "post", "put", "delete", "patch"].forEach((m) => {
+          if (!paths[fullPath][m]) paths[fullPath][m] = { ...operation };
+        });
+      } else {
+        paths[fullPath][methodLower] = operation;
+      }
+    }
+    for (const controller of router[$childControllers]) {
+      const controllerName = controller.constructor.name || "UnknownController";
+      tagGroups.get(group)?.add(controllerName);
+    }
+    for (const child of router[$childRouters]) {
+      const mountPath = child[$mountPath];
+      const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+      const cleanMount = mountPath.startsWith("/") ? mountPath : "/" + mountPath;
+      const nextPrefix = cleanPrefix + cleanMount || "/";
+      collect(child, nextPrefix, group, tag);
+    }
+  };
+  collect(rootRouter);
+  const xTagGroups = [];
+  for (const [name, tags] of tagGroups) {
+    xTagGroups.push({ name, tags: Array.from(tags).sort() });
+  }
+  return {
+    openapi: "3.1.0",
+    info: { title: "Shokupan API", version: "1.0.0", ...options.info },
+    paths,
+    components: options.components,
+    servers: options.servers,
+    tags: options.tags,
+    externalDocs: options.externalDocs,
+    "x-tagGroups": xTagGroups
+  };
+}
 const eta$1 = new Eta();
+function serveStatic(ctx, config, prefix) {
+  const rootPath = resolve(config.root || ".");
+  const normalizedPrefix = prefix.endsWith("/") && prefix !== "/" ? prefix.slice(0, -1) : prefix;
+  return async () => {
+    let relative = ctx.path.slice(normalizedPrefix.length);
+    if (!relative.startsWith("/") && relative.length > 0) relative = "/" + relative;
+    if (relative.length === 0) relative = "/";
+    relative = decodeURIComponent(relative);
+    const requestPath = join(rootPath, relative);
+    if (!requestPath.startsWith(rootPath)) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    if (requestPath.includes("\0")) {
+      return ctx.json({ error: "Forbidden" }, 403);
+    }
+    if (config.hooks?.onRequest) {
+      const res = await config.hooks.onRequest(ctx);
+      if (res) return res;
+    }
+    if (config.exclude) {
+      for (const pattern of config.exclude) {
+        if (pattern instanceof RegExp) {
+          if (pattern.test(relative)) return ctx.json({ error: "Forbidden" }, 403);
+        } else if (typeof pattern === "string") {
+          if (relative.includes(pattern)) return ctx.json({ error: "Forbidden" }, 403);
+        }
+      }
+    }
+    if (basename(requestPath).startsWith(".")) {
+      const behavior = config.dotfiles || "ignore";
+      if (behavior === "deny") return ctx.json({ error: "Forbidden" }, 403);
+      if (behavior === "ignore") return ctx.json({ error: "Not Found" }, 404);
+    }
+    let finalPath = requestPath;
+    let stats;
+    try {
+      stats = await stat(requestPath);
+    } catch (e) {
+      if (config.extensions) {
+        for (const ext of config.extensions) {
+          const p = requestPath + (ext.startsWith(".") ? ext : "." + ext);
+          try {
+            const s = await stat(p);
+            if (s.isFile()) {
+              finalPath = p;
+              stats = s;
+              break;
+            }
+          } catch {
+          }
+        }
+      }
+      if (!stats) return ctx.json({ error: "Not Found" }, 404);
+    }
+    if (stats.isDirectory()) {
+      if (!ctx.path.endsWith("/")) {
+        const query = ctx.url.search;
+        return ctx.redirect(ctx.path + "/" + query, 302);
+      }
+      let indexes = [];
+      if (config.index === void 0) {
+        indexes = ["index.html", "index.htm"];
+      } else if (Array.isArray(config.index)) {
+        indexes = config.index;
+      } else if (config.index) {
+        indexes = [config.index];
+      }
+      let foundIndex = false;
+      for (const idx of indexes) {
+        const idxPath = join(finalPath, idx);
+        try {
+          const idxStats = await stat(idxPath);
+          if (idxStats.isFile()) {
+            finalPath = idxPath;
+            foundIndex = true;
+            break;
+          }
+        } catch {
+        }
+      }
+      if (!foundIndex) {
+        if (config.listDirectory) {
+          try {
+            const files = await readdir(requestPath);
+            const listing = eta$1.renderString(`
+                                <!DOCTYPE html>
+                                <html>
+                                <head>
+                                    <title>Index of <%= it.relative %></title>
+                                    <style>
+                                        body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+                                        ul { list-style: none; padding: 0; }
+                                        li { padding: 0.5rem 0; border-bottom: 1px solid #eee; }
+                                        a { text-decoration: none; color: #0066cc; }
+                                        a:hover { text-decoration: underline; }
+                                        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
+                                    </style>
+                                </head>
+                                <body>
+                                <h1>Index of <%= it.relative %></h1>
+                                <ul>
+                                    <% if (it.relative !== '/') { %>
+                                        <li><a href="../">../</a></li>
+                                    <% } %>
+                                    <% it.files.forEach(function(f) { %>
+                                        <li><a href="<%= f %>"><%= f %></a></li>
+                                    <% }) %>
+                                </ul>
+                                </body>
+                                </html>
+                            `, { relative, files, join });
+            return new Response(listing, { headers: { "Content-Type": "text/html" } });
+          } catch (e) {
+            return ctx.json({ error: "Internal Server Error" }, 500);
+          }
+        } else {
+          return ctx.json({ error: "Forbidden" }, 403);
+        }
+      }
+    }
+    const file = Bun.file(finalPath);
+    let response = new Response(file);
+    if (config.hooks?.onResponse) {
+      const hooked = await config.hooks.onResponse(ctx, response);
+      if (hooked) response = hooked;
+    }
+    return response;
+  };
+}
+const asyncContext = new AsyncLocalStorage();
 const RouterRegistry = /* @__PURE__ */ new Map();
 const ShokupanApplicationTree = {};
 class ShokupanRouter {
   constructor(config) {
     this.config = config;
+    if (config?.requestTimeout) {
+      this.requestTimeout = config.requestTimeout;
+    }
   }
   // Internal marker to identify Router vs. Application
   [$isApplication] = false;
@@ -484,6 +1122,7 @@ class ShokupanRouter {
   [$isRouter] = true;
   [$appRoot];
   [$mountPath] = "/";
+  // Public via Symbol for OpenAPI generator
   [$parent] = null;
   [$childRouters] = [];
   [$childControllers] = [];
@@ -493,7 +1132,8 @@ class ShokupanRouter {
   get root() {
     return this[$appRoot];
   }
-  routes = [];
+  [$routes] = [];
+  // Public via Symbol for OpenAPI generator
   currentGuards = [];
   isRouterInstance(target) {
     return typeof target === "object" && target !== null && $isRouter in target;
@@ -509,6 +1149,12 @@ class ShokupanRouter {
    * - postCreate(ctx) -> POST /prefix/create
    */
   mount(prefix, controller) {
+    const isRouter = this.isRouterInstance(controller);
+    const isFunction = typeof controller === "function";
+    const controllersOnly = this.config?.controllersOnly ?? this.rootConfig?.controllersOnly ?? false;
+    if (controllersOnly && !isFunction && !isRouter) {
+      throw new Error(`[Shokupan] strict controller check failed: ${controller.constructor.name || typeof controller} is not a class constructor.`);
+    }
     if (this.isRouterInstance(controller)) {
       if (controller[$isMounted]) {
         throw new Error("Router is already mounted");
@@ -535,6 +1181,15 @@ class ShokupanRouter {
           prefix = p1 + p2;
           if (!prefix) prefix = "/";
         }
+      } else {
+        const ctor = instance.constructor;
+        const controllerPath = ctor[$controllerPath];
+        if (controllerPath) {
+          const p1 = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+          const p2 = controllerPath.startsWith("/") ? controllerPath : "/" + controllerPath;
+          prefix = p1 + p2;
+          if (!prefix) prefix = "/";
+        }
       }
       instance[$mountPath] = prefix;
       this[$childControllers].push(instance);
@@ -652,8 +1307,14 @@ class ShokupanRouter {
               return composed(ctx, () => wrappedHandler(ctx));
             };
           }
+          finalHandler.originalHandler = originalHandler;
+          if (finalHandler !== wrappedHandler) {
+            wrappedHandler.originalHandler = originalHandler;
+          }
           const tagName = instance.constructor.name;
-          const spec = { tags: [tagName] };
+          const decoratedSpecs = instance[$routeSpec] || proto && proto[$routeSpec];
+          const userSpec = decoratedSpecs && decoratedSpecs.get(name);
+          const spec = { tags: [tagName], ...userSpec };
           this.add({ method, path: normalizedPath, handler: finalHandler, spec });
         }
       }
@@ -668,7 +1329,7 @@ class ShokupanRouter {
    * Returns all routes attached to this router and its descendants.
    */
   getRoutes() {
-    const routes = this.routes.map((r) => ({
+    const routes = this[$routes].map((r) => ({
       method: r.method,
       path: r.path,
       handler: r.handler
@@ -769,6 +1430,30 @@ class ShokupanRouter {
       data: result
     };
   }
+  applyHooks(match) {
+    if (!this.config?.hooks) return match;
+    const hooks = this.config.hooks;
+    const originalHandler = match.handler;
+    match.handler = async (ctx) => {
+      if (hooks.onRequestStart) await hooks.onRequestStart(ctx);
+      try {
+        const result = await originalHandler(ctx);
+        if (hooks.onRequestEnd) await hooks.onRequestEnd(ctx);
+        return result;
+      } catch (err) {
+        if (hooks.onError) {
+          try {
+            await hooks.onError(err, ctx);
+          } catch (e) {
+            console.error("Error in router onError hook:", e);
+          }
+        }
+        throw err;
+      }
+    };
+    match.handler.originalHandler = originalHandler.originalHandler || originalHandler;
+    return match;
+  }
   /**
    * Find a route matching the given method and path.
    * @param method HTTP method
@@ -776,7 +1461,7 @@ class ShokupanRouter {
    * @returns Route handler and parameters if found, otherwise null
    */
   find(method, path) {
-    for (const route of this.routes) {
+    for (const route of this[$routes]) {
       if (route.method !== "ALL" && route.method !== method) continue;
       const match = route.regex.exec(path);
       if (match) {
@@ -784,7 +1469,7 @@ class ShokupanRouter {
         route.keys.forEach((key, index) => {
           params[key] = match[index + 1];
         });
-        return { handler: route.handler, params };
+        return this.applyHooks({ handler: route.handler, params });
       }
     }
     for (const child of this[$childRouters]) {
@@ -792,13 +1477,13 @@ class ShokupanRouter {
       if (path === prefix || path.startsWith(prefix + "/")) {
         const subPath = path.slice(prefix.length) || "/";
         const match = child.find(method, subPath);
-        if (match) return match;
+        if (match) return this.applyHooks(match);
       }
       if (prefix.endsWith("/")) {
         if (path.startsWith(prefix)) {
           const subPath = path.slice(prefix.length) || "/";
           const match = child.find(method, subPath);
-          if (match) return match;
+          if (match) return this.applyHooks(match);
         }
       }
     }
@@ -816,6 +1501,7 @@ class ShokupanRouter {
     };
   }
   // --- Functional Routing ---
+  requestTimeout;
   /**
    * Adds a route to the router.
    * 
@@ -823,12 +1509,25 @@ class ShokupanRouter {
    * @param path - URL path
    * @param spec - OpenAPI specification for the route
    * @param handler - Route handler function
+   * @param requestTimeout - Timeout for this route in milliseconds
    */
-  add({ method, path, spec, handler, regex: customRegex, group }) {
+  add({ method, path, spec, handler, regex: customRegex, group, requestTimeout, renderer }) {
     const { regex, keys } = customRegex ? { regex: customRegex, keys: [] } : this.parsePath(path);
     let wrappedHandler = handler;
     const routeGuards = [...this.currentGuards];
+    const effectiveTimeout = requestTimeout ?? this.requestTimeout ?? this.rootConfig?.requestTimeout;
+    if (effectiveTimeout !== void 0 && effectiveTimeout > 0) {
+      const originalHandler = wrappedHandler;
+      wrappedHandler = async (ctx) => {
+        if (ctx.server) {
+          ctx.server.timeout(ctx.req, effectiveTimeout / 1e3);
+        }
+        return originalHandler(ctx);
+      };
+      wrappedHandler.originalHandler = originalHandler.originalHandler || originalHandler;
+    }
     if (routeGuards.length > 0) {
+      const innerHandler = wrappedHandler;
       wrappedHandler = async (ctx) => {
         for (const guard of routeGuards) {
           let guardPassed = false;
@@ -853,10 +1552,18 @@ class ShokupanRouter {
             return ctx.json({ error: "Forbidden" }, 403);
           }
         }
-        return handler(ctx);
+        return innerHandler(ctx);
+      };
+    }
+    const effectiveRenderer = renderer ?? this.config?.renderer ?? this.rootConfig?.renderer;
+    if (effectiveRenderer) {
+      const innerHandler = wrappedHandler;
+      wrappedHandler = async (ctx) => {
+        ctx.renderer = effectiveRenderer;
+        return innerHandler(ctx);
       };
     }
-    this.routes.push({
+    this[$routes].push({
       method,
       path,
       regex,
@@ -864,7 +1571,9 @@ class ShokupanRouter {
       handler: wrappedHandler,
       handlerSpec: spec,
       group,
-      guards: routeGuards.length > 0 ? routeGuards : void 0
+      guards: routeGuards.length > 0 ? routeGuards : void 0,
+      requestTimeout: effectiveTimeout
+      // Save for inspection? Or just relying on closure
     });
     return this;
   }
@@ -909,133 +1618,12 @@ class ShokupanRouter {
    */
   static(uriPath, options) {
     const config = typeof options === "string" ? { root: options } : options;
-    const rootPath = resolve(config.root || ".");
     const prefix = uriPath.startsWith("/") ? uriPath : "/" + uriPath;
     const normalizedPrefix = prefix.endsWith("/") && prefix !== "/" ? prefix.slice(0, -1) : prefix;
-    const handler = async (ctx) => {
-      let relative = ctx.path.slice(normalizedPrefix.length);
-      if (!relative.startsWith("/") && relative.length > 0) relative = "/" + relative;
-      if (relative.length === 0) relative = "/";
-      relative = decodeURIComponent(relative);
-      const requestPath = join(rootPath, relative);
-      if (!requestPath.startsWith(rootPath)) {
-        return ctx.json({ error: "Forbidden" }, 403);
-      }
-      if (requestPath.includes("\0")) {
-        return ctx.json({ error: "Forbidden" }, 403);
-      }
-      if (config.hooks?.onRequest) {
-        const res = await config.hooks.onRequest(ctx);
-        if (res) return res;
-      }
-      if (config.exclude) {
-        for (const pattern2 of config.exclude) {
-          if (pattern2 instanceof RegExp) {
-            if (pattern2.test(relative)) return ctx.json({ error: "Forbidden" }, 403);
-          } else if (typeof pattern2 === "string") {
-            if (relative.includes(pattern2)) return ctx.json({ error: "Forbidden" }, 403);
-          }
-        }
-      }
-      if (basename(requestPath).startsWith(".")) {
-        const behavior = config.dotfiles || "ignore";
-        if (behavior === "deny") return ctx.json({ error: "Forbidden" }, 403);
-        if (behavior === "ignore") return ctx.json({ error: "Not Found" }, 404);
-      }
-      let finalPath = requestPath;
-      let stats;
-      try {
-        stats = await stat(requestPath);
-      } catch (e) {
-        if (config.extensions) {
-          for (const ext of config.extensions) {
-            const p = requestPath + (ext.startsWith(".") ? ext : "." + ext);
-            try {
-              const s = await stat(p);
-              if (s.isFile()) {
-                finalPath = p;
-                stats = s;
-                break;
-              }
-            } catch {
-            }
-          }
-        }
-        if (!stats) return ctx.json({ error: "Not Found" }, 404);
-      }
-      if (stats.isDirectory()) {
-        if (!ctx.path.endsWith("/")) {
-          const query = ctx.url.search;
-          return ctx.redirect(ctx.path + "/" + query, 302);
-        }
-        let indexes = [];
-        if (config.index === void 0) {
-          indexes = ["index.html", "index.htm"];
-        } else if (Array.isArray(config.index)) {
-          indexes = config.index;
-        } else if (config.index) {
-          indexes = [config.index];
-        }
-        let foundIndex = false;
-        for (const idx of indexes) {
-          const idxPath = join(finalPath, idx);
-          try {
-            const idxStats = await stat(idxPath);
-            if (idxStats.isFile()) {
-              finalPath = idxPath;
-              foundIndex = true;
-              break;
-            }
-          } catch {
-          }
-        }
-        if (!foundIndex) {
-          if (config.listDirectory) {
-            try {
-              const files = await readdir(requestPath);
-              const listing = eta$1.renderString(`
-                                <!DOCTYPE html>
-                                <html>
-                                <head>
-                                    <title>Index of <%= it.relative %></title>
-                                    <style>
-                                        body { font-family: system-ui, -apple-system, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
-                                        ul { list-style: none; padding: 0; }
-                                        li { padding: 0.5rem 0; border-bottom: 1px solid #eee; }
-                                        a { text-decoration: none; color: #0066cc; }
-                                        a:hover { text-decoration: underline; }
-                                        h1 { font-size: 1.5rem; margin-bottom: 1rem; }
-                                    </style>
-                                </head>
-                                <body>
-                                <h1>Index of <%= it.relative %></h1>
-                                <ul>
-                                    <% if (it.relative !== '/') { %>
-                                        <li><a href="../">../</a></li>
-                                    <% } %>
-                                    <% it.files.forEach(function(f) { %>
-                                        <li><a href="<%= f %>"><%= f %></a></li>
-                                    <% }) %>
-                                </ul>
-                                </body>
-                                </html>
-                            `, { relative, files, join });
-              return new Response(listing, { headers: { "Content-Type": "text/html" } });
-            } catch (e) {
-              return ctx.json({ error: "Internal Server Error" }, 500);
-            }
-          } else {
-            return ctx.json({ error: "Forbidden" }, 403);
-          }
-        }
-      }
-      const file = Bun.file(finalPath);
-      let response = new Response(file);
-      if (config.hooks?.onResponse) {
-        const hooked = await config.hooks.onResponse(ctx, response);
-        if (hooked) response = hooked;
-      }
-      return response;
+    serveStatic(null, config, prefix);
+    const routeHandler = async (ctx) => {
+      const runner = serveStatic(ctx, config, prefix);
+      return runner();
     };
     let groupName = "Static";
     const segments = normalizedPrefix.split("/").filter(Boolean);
@@ -1054,8 +1642,8 @@ class ShokupanRouter {
     const pattern = `^${normalizedPrefix}(/.*)?$`;
     const regex = new RegExp(pattern);
     const displayPath = normalizedPrefix === "/" ? "/*" : normalizedPrefix + "/*";
-    this.add({ method: "GET", path: displayPath, handler, spec, regex });
-    this.add({ method: "HEAD", path: displayPath, handler, spec, regex });
+    this.add({ method: "GET", path: displayPath, handler: routeHandler, spec, regex });
+    this.add({ method: "HEAD", path: displayPath, handler: routeHandler, spec, regex });
     return this;
   }
   /**
@@ -1090,137 +1678,23 @@ class ShokupanRouter {
   }
   /**
    * Generates an OpenAPI 3.1 Document by recursing through the router and its descendants.
+   * Now includes runtime analysis of handler functions to infer request/response types.
    */
   generateApiSpec(options = {}) {
-    const paths = {};
-    const tagGroups = /* @__PURE__ */ new Map();
-    const defaultTagGroup = options.defaultTagGroup || "General";
-    const defaultTagName = options.defaultTag || "Application";
-    const collect = (router, prefix = "", currentGroup = defaultTagGroup, defaultTag = defaultTagName) => {
-      let group = currentGroup;
-      let tag = defaultTag;
-      if (router.config?.group) {
-        group = router.config.group;
-      }
-      if (router.config?.name) {
-        tag = router.config.name;
-      } else {
-        const mountPath = router[$mountPath];
-        if (mountPath && mountPath !== "/") {
-          const segments = mountPath.split("/").filter(Boolean);
-          if (segments.length > 0) {
-            const lastSegment = segments[segments.length - 1];
-            const humanized = lastSegment.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-            tag = humanized;
-          }
-        }
-      }
-      if (!tagGroups.has(group)) {
-        tagGroups.set(group, /* @__PURE__ */ new Set());
-      }
-      for (const route of router.routes) {
-        const routeGroup = route.group || group;
-        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        const cleanSubPath = route.path.startsWith("/") ? route.path : "/" + route.path;
-        let fullPath = cleanPrefix + cleanSubPath || "/";
-        fullPath = fullPath.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
-        if (!paths[fullPath]) {
-          paths[fullPath] = {};
-        }
-        const operation = {
-          responses: {
-            200: { description: "OK" }
-          }
-        };
-        if (route.keys.length > 0) {
-          operation.parameters = route.keys.map((key) => ({
-            name: key,
-            in: "path",
-            required: true,
-            schema: { type: "string" }
-          }));
-        }
-        if (route.guards) {
-          for (const guard of route.guards) {
-            if (guard.spec) {
-              deepMerge(operation, guard.spec);
-            }
-          }
-        }
-        if (route.handlerSpec) {
-          deepMerge(operation, route.handlerSpec);
-        }
-        if (!operation.tags || operation.tags.length === 0) {
-          operation.tags = [tag];
-        }
-        if (operation.tags) {
-          operation.tags = Array.from(new Set(operation.tags));
-          for (const t of operation.tags) {
-            if (!tagGroups.has(routeGroup)) {
-              tagGroups.set(routeGroup, /* @__PURE__ */ new Set());
-            }
-            tagGroups.get(routeGroup)?.add(t);
-          }
-        }
-        const methodLower = route.method.toLowerCase();
-        if (methodLower === "all") {
-          ["get", "post", "put", "delete", "patch"].forEach((m) => {
-            if (!paths[fullPath][m]) {
-              paths[fullPath][m] = { ...operation };
-            }
-          });
-        } else {
-          paths[fullPath][methodLower] = operation;
-        }
-      }
-      for (const controller of router[$childControllers]) {
-        const mountPath = controller[$mountPath] || "";
-        prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        mountPath.startsWith("/") ? mountPath : "/" + mountPath;
-        const controllerName = controller.constructor.name || "UnknownController";
-        tagGroups.get(group)?.add(controllerName);
-      }
-      for (const child of router[$childRouters]) {
-        const mountPath = child[$mountPath];
-        const cleanPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-        const cleanMount = mountPath.startsWith("/") ? mountPath : "/" + mountPath;
-        const nextPrefix = cleanPrefix + cleanMount || "/";
-        collect(child, nextPrefix, group, tag);
-      }
-    };
-    collect(this);
-    const xTagGroups = [];
-    for (const [name, tags] of tagGroups) {
-      xTagGroups.push({
-        name,
-        tags: Array.from(tags).sort()
-      });
-    }
-    return {
-      openapi: "3.1.0",
-      info: {
-        title: "Shokupan API",
-        version: "1.0.0",
-        ...options.info
-      },
-      paths,
-      components: options.components,
-      servers: options.servers,
-      tags: options.tags,
-      externalDocs: options.externalDocs,
-      "x-tagGroups": xTagGroups
-    };
+    return generateOpenApi(this, options);
   }
 }
 const defaults = {
   port: 3e3,
   hostname: "localhost",
   development: process.env.NODE_ENV !== "production",
-  enableAsyncLocalStorage: false
+  enableAsyncLocalStorage: false,
+  reusePort: false
 };
 trace.getTracer("shokupan.application");
 class Shokupan extends ShokupanRouter {
   applicationConfig = {};
+  openApiSpec;
   middleware = [];
   get logger() {
     return this.applicationConfig.logger;
@@ -1238,24 +1712,41 @@ class Shokupan extends ShokupanRouter {
     this.middleware.push(middleware);
     return this;
   }
+  startupHooks = [];
+  /**
+   * Registers a callback to be executed before the server starts listening.
+   */
+  onStart(callback) {
+    this.startupHooks.push(callback);
+    return this;
+  }
   /**
    * Starts the application server.
    * 
    * @param port - The port to listen on. If not specified, the port from the configuration is used. If that is not specified, port 3000 is used.
    * @returns The server instance.
    */
-  listen(port) {
+  async listen(port) {
     const finalPort = port ?? this.applicationConfig.port ?? 3e3;
     if (finalPort < 0 || finalPort > 65535) {
       throw new Error("Invalid port number");
     }
+    for (const hook of this.startupHooks) {
+      await hook();
+    }
+    if (this.applicationConfig.enableOpenApiGen) {
+      this.openApiSpec = await generateOpenApi(this);
+    }
     if (port === 0 && process.platform === "linux") ;
-    const server = Bun.serve({
+    const serveOptions = {
       port: finalPort,
       hostname: this.applicationConfig.hostname,
       development: this.applicationConfig.development,
-      fetch: this.fetch.bind(this)
-    });
+      fetch: this.fetch.bind(this),
+      reusePort: this.applicationConfig.reusePort,
+      idleTimeout: this.applicationConfig.readTimeout ? this.applicationConfig.readTimeout / 1e3 : void 0
+    };
+    const server = this.applicationConfig.serverFactory ? await this.applicationConfig.serverFactory(serveOptions) : Bun.serve(serveOptions);
     console.log(`Shokupan server listening on http://${server.hostname}:${server.port}`);
     return server;
   }
@@ -1306,9 +1797,10 @@ class Shokupan extends ShokupanRouter {
    * This logic contains the middleware chain and router dispatch.
    * 
    * @param req - The request to handle.
+   * @param server - The server instance.
    * @returns The response to send.
    */
-  async fetch(req) {
+  async fetch(req, server) {
     const tracer2 = trace.getTracer("shokupan.application");
     const store = asyncContext.getStore();
     const attrs = {
@@ -1325,10 +1817,13 @@ class Shokupan extends ShokupanRouter {
       ctxMap.set("request", req);
       const runCallback = () => {
         const request = req;
+        const ctx2 = new ShokupanContext(request, server, void 0, this);
         const handle = async () => {
-          const ctx2 = new ShokupanContext(request);
-          const fn = compose(this.middleware);
           try {
+            if (this.applicationConfig.hooks?.onRequestStart) {
+              await this.applicationConfig.hooks.onRequestStart(ctx2);
+            }
+            const fn = compose(this.middleware);
             const result = await fn(ctx2, async () => {
               const match = this.find(req.method, ctx2.path);
               if (match) {
@@ -1337,17 +1832,24 @@ class Shokupan extends ShokupanRouter {
               }
               return null;
             });
+            let response;
             if (result instanceof Response) {
-              return result;
-            }
-            if (result === null || result === void 0) {
+              response = result;
+            } else if (result === null || result === void 0) {
               span.setAttribute("http.status_code", 404);
-              return ctx2.text("Not Found", 404);
+              response = ctx2.text("Not Found", 404);
+            } else if (typeof result === "object") {
+              response = ctx2.json(result);
+            } else {
+              response = ctx2.text(String(result));
+            }
+            if (this.applicationConfig.hooks?.onRequestEnd) {
+              await this.applicationConfig.hooks.onRequestEnd(ctx2);
             }
-            if (typeof result === "object") {
-              return ctx2.json(result);
+            if (this.applicationConfig.hooks?.onResponseStart) {
+              await this.applicationConfig.hooks.onResponseStart(ctx2, response);
             }
-            return ctx2.text(String(result));
+            return response;
           } catch (err) {
             console.error(err);
             span.recordException(err);
@@ -1355,10 +1857,46 @@ class Shokupan extends ShokupanRouter {
             const status = err.status || err.statusCode || 500;
             const body = { error: err.message || "Internal Server Error" };
             if (err.errors) body.errors = err.errors;
+            if (this.applicationConfig.hooks?.onError) {
+              try {
+                await this.applicationConfig.hooks.onError(err, ctx2);
+              } catch (hookErr) {
+                console.error("Error in onError hook:", hookErr);
+              }
+            }
             return ctx2.json(body, status);
           }
         };
-        return handle().finally(() => span.end());
+        let executionPromise = handle();
+        const timeoutMs = this.applicationConfig.requestTimeout;
+        if (timeoutMs && timeoutMs > 0 && this.applicationConfig.hooks?.onRequestTimeout) {
+          let timeoutId;
+          const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(async () => {
+              try {
+                if (this.applicationConfig.hooks?.onRequestTimeout) {
+                  await this.applicationConfig.hooks.onRequestTimeout(ctx2);
+                }
+              } catch (e) {
+                console.error("Error in onRequestTimeout hook:", e);
+              }
+              reject(new Error("Request Timeout"));
+            }, timeoutMs);
+          });
+          executionPromise = Promise.race([executionPromise, timeoutPromise]).finally(() => clearTimeout(timeoutId));
+        }
+        return executionPromise.catch((err) => {
+          if (err.message === "Request Timeout") {
+            return ctx2.text("Request Timeout", 408);
+          }
+          console.error("Unexpected error in request execution:", err);
+          return ctx2.text("Internal Server Error", 500);
+        }).then(async (res) => {
+          if (this.applicationConfig.hooks?.onResponseEnd) {
+            await this.applicationConfig.hooks.onResponseEnd(ctx2, res);
+          }
+          return res;
+        }).finally(() => span.end());
       };
       if (this.applicationConfig.enableAsyncLocalStorage) {
         return asyncContext.run(ctxMap, runCallback);
@@ -1416,8 +1954,8 @@ class AuthPlugin extends ShokupanRouter {
   init() {
     for (const [providerName, providerConfig] of Object.entries(this.authConfig.providers)) {
       if (!providerConfig) continue;
-      const provider2 = this.getProviderInstance(providerName, providerConfig);
-      if (!provider2) {
+      const provider = this.getProviderInstance(providerName, providerConfig);
+      if (!provider) {
         continue;
       }
       this.get(`/auth/${providerName}/login`, async (ctx) => {
@@ -1425,15 +1963,15 @@ class AuthPlugin extends ShokupanRouter {
         const codeVerifier = providerName === "google" || providerName === "microsoft" || providerName === "auth0" || providerName === "okta" ? generateCodeVerifier() : void 0;
         const scopes = providerConfig.scopes || [];
         let url;
-        if (provider2 instanceof GitHub) {
-          url = await provider2.createAuthorizationURL(state, scopes);
-        } else if (provider2 instanceof Google || provider2 instanceof MicrosoftEntraId || provider2 instanceof Auth0 || provider2 instanceof Okta) {
-          url = await provider2.createAuthorizationURL(state, codeVerifier, scopes);
-        } else if (provider2 instanceof Apple) {
-          url = await provider2.createAuthorizationURL(state, scopes);
-        } else if (provider2 instanceof OAuth2Client) {
+        if (provider instanceof GitHub) {
+          url = await provider.createAuthorizationURL(state, scopes);
+        } else if (provider instanceof Google || provider instanceof MicrosoftEntraId || provider instanceof Auth0 || provider instanceof Okta) {
+          url = await provider.createAuthorizationURL(state, codeVerifier, scopes);
+        } else if (provider instanceof Apple) {
+          url = await provider.createAuthorizationURL(state, scopes);
+        } else if (provider instanceof OAuth2Client) {
           if (!providerConfig.authUrl) return ctx.text("Config error: authUrl required for oauth2", 500);
-          url = await provider2.createAuthorizationURL(providerConfig.authUrl, state, scopes);
+          url = await provider.createAuthorizationURL(providerConfig.authUrl, state, scopes);
         } else {
           return ctx.text("Provider config error", 500);
         }
@@ -1456,19 +1994,19 @@ class AuthPlugin extends ShokupanRouter {
         try {
           let tokens;
           let idToken;
-          if (provider2 instanceof GitHub) {
-            tokens = await provider2.validateAuthorizationCode(code);
-          } else if (provider2 instanceof Google || provider2 instanceof MicrosoftEntraId) {
+          if (provider instanceof GitHub) {
+            tokens = await provider.validateAuthorizationCode(code);
+          } else if (provider instanceof Google || provider instanceof MicrosoftEntraId) {
             if (!storedVerifier) return ctx.text("Missing verifier", 400);
-            tokens = await provider2.validateAuthorizationCode(code, storedVerifier);
-          } else if (provider2 instanceof Auth0 || provider2 instanceof Okta) {
-            tokens = await provider2.validateAuthorizationCode(code, storedVerifier || "");
-          } else if (provider2 instanceof Apple) {
-            tokens = await provider2.validateAuthorizationCode(code);
+            tokens = await provider.validateAuthorizationCode(code, storedVerifier);
+          } else if (provider instanceof Auth0 || provider instanceof Okta) {
+            tokens = await provider.validateAuthorizationCode(code, storedVerifier || "");
+          } else if (provider instanceof Apple) {
+            tokens = await provider.validateAuthorizationCode(code);
             idToken = tokens.idToken;
-          } else if (provider2 instanceof OAuth2Client) {
+          } else if (provider instanceof OAuth2Client) {
             if (!providerConfig.tokenUrl) return ctx.text("Config error: tokenUrl required for oauth2", 500);
-            tokens = await provider2.validateAuthorizationCode(providerConfig.tokenUrl, code, null);
+            tokens = await provider.validateAuthorizationCode(providerConfig.tokenUrl, code, null);
           }
           const accessToken = tokens.accessToken || tokens.access_token;
           const user = await this.fetchUser(providerName, accessToken, providerConfig, idToken);
@@ -1485,9 +2023,9 @@ class AuthPlugin extends ShokupanRouter {
       });
     }
   }
-  async fetchUser(provider2, token, config, idToken) {
-    let user = { id: "unknown", provider: provider2 };
-    if (provider2 === "github") {
+  async fetchUser(provider, token, config, idToken) {
+    let user = { id: "unknown", provider };
+    if (provider === "github") {
       const res = await fetch("https://api.github.com/user", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1497,10 +2035,10 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name || data.login,
         email: data.email,
         picture: data.avatar_url,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "google") {
+    } else if (provider === "google") {
       const res = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1510,10 +2048,10 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name,
         email: data.email,
         picture: data.picture,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "microsoft") {
+    } else if (provider === "microsoft") {
       const res = await fetch("https://graph.microsoft.com/v1.0/me", {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1522,12 +2060,12 @@ class AuthPlugin extends ShokupanRouter {
         id: data.id,
         name: data.displayName,
         email: data.mail || data.userPrincipalName,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "auth0" || provider2 === "okta") {
+    } else if (provider === "auth0" || provider === "okta") {
       const domain = config.domain.startsWith("http") ? config.domain : `https://${config.domain}`;
-      const endpoint = provider2 === "auth0" ? `${domain}/userinfo` : `${domain}/oauth2/v1/userinfo`;
+      const endpoint = provider === "auth0" ? `${domain}/userinfo` : `${domain}/oauth2/v1/userinfo`;
       const res = await fetch(endpoint, {
         headers: { Authorization: `Bearer ${token}` }
       });
@@ -1537,20 +2075,20 @@ class AuthPlugin extends ShokupanRouter {
         name: data.name,
         email: data.email,
         picture: data.picture,
-        provider: provider2,
+        provider,
         raw: data
       };
-    } else if (provider2 === "apple") {
+    } else if (provider === "apple") {
       if (idToken) {
         const payload = jose.decodeJwt(idToken);
         user = {
           id: payload.sub,
           email: payload["email"],
-          provider: provider2,
+          provider,
           raw: payload
         };
       }
-    } else if (provider2 === "oauth2") {
+    } else if (provider === "oauth2") {
       if (config.userInfoUrl) {
         const res = await fetch(config.userInfoUrl, {
           headers: { Authorization: `Bearer ${token}` }
@@ -1561,7 +2099,7 @@ class AuthPlugin extends ShokupanRouter {
           name: data.name,
           email: data.email,
           picture: data.picture,
-          provider: provider2,
+          provider,
           raw: data
         };
       }
@@ -1702,6 +2240,66 @@ function Cors(options = {}) {
     return response;
   };
 }
+function useExpress(expressMiddleware) {
+  return async (ctx, next) => {
+    return new Promise((resolve2, reject) => {
+      const reqStore = {
+        method: ctx.method,
+        url: ctx.url.pathname + ctx.url.search,
+        path: ctx.url.pathname,
+        query: ctx.query,
+        headers: ctx.headers,
+        get: (name) => ctx.headers.get(name)
+      };
+      const req = new Proxy(ctx.request, {
+        get(target, prop) {
+          if (prop in reqStore) return reqStore[prop];
+          const val = target[prop];
+          if (typeof val === "function") return val.bind(target);
+          return val;
+        },
+        set(target, prop, value) {
+          reqStore[prop] = value;
+          ctx.state[prop] = value;
+          return true;
+        }
+      });
+      const res = {
+        locals: {},
+        statusCode: 200,
+        setHeader: (name, value) => {
+          ctx.response.headers.set(name, value);
+        },
+        set: (name, value) => {
+          ctx.response.headers.set(name, value);
+        },
+        end: (chunk) => {
+          resolve2(new Response(chunk, { status: res.statusCode }));
+        },
+        status: (code) => {
+          res.statusCode = code;
+          return res;
+        },
+        send: (body) => {
+          let content = body;
+          if (typeof body === "object") content = JSON.stringify(body);
+          resolve2(new Response(content, { status: res.statusCode }));
+        },
+        json: (body) => {
+          resolve2(Response.json(body, { status: res.statusCode }));
+        }
+      };
+      try {
+        expressMiddleware(req, res, (err) => {
+          if (err) return reject(err);
+          resolve2(next());
+        });
+      } catch (err) {
+        reject(err);
+      }
+    });
+  };
+}
 function RateLimit(options = {}) {
   const windowMs = options.windowMs || 60 * 1e3;
   const max = options.max || 5;
@@ -1792,10 +2390,43 @@ class ScalarPlugin extends ShokupanRouter {
     this.get("/scalar.js", (ctx) => {
       return ctx.file(__dirname + "/../../node_modules/@scalar/api-reference/dist/browser/standalone.js");
     });
-    this.get("/openapi.json", (ctx) => {
-      return (this.root || this).generateApiSpec();
+    this.get("/openapi.json", async (ctx) => {
+      let spec;
+      if (this.root.openApiSpec) {
+        try {
+          spec = structuredClone(this.root.openApiSpec);
+        } catch (e) {
+          spec = Object.assign({}, this.root.openApiSpec);
+        }
+      } else {
+        spec = await (this.root || this).generateApiSpec();
+      }
+      if (this.pluginOptions.baseDocument) {
+        deepMerge(spec, this.pluginOptions.baseDocument);
+      }
+      return ctx.json(spec);
     });
   }
+  // New lifecycle method to be called by router.mount
+  onMount(parent) {
+    if (parent.onStart) {
+      parent.onStart(async () => {
+        if (this.pluginOptions.enableStaticAnalysis) {
+          try {
+            const entrypoint = process.argv[1];
+            console.log(`[ScalarPlugin] Running eager static analysis on entrypoint: ${entrypoint}`);
+            const analyzer = new OpenAPIAnalyzer(process.cwd(), entrypoint);
+            let staticSpec = await analyzer.analyze();
+            if (!this.pluginOptions.baseDocument) this.pluginOptions.baseDocument = {};
+            deepMerge(this.pluginOptions.baseDocument, staticSpec);
+            console.log("[ScalarPlugin] Static analysis completed successfully.");
+          } catch (err) {
+            console.error("[ScalarPlugin] Failed to run static analysis:", err);
+          }
+        }
+      });
+    }
+  }
 }
 function SecurityHeaders(options = {}) {
   return async (ctx, next) => {
@@ -2155,6 +2786,30 @@ async function validateValibotWrapper(wrapper, data) {
   }
   return result.output;
 }
+function isClass(schema) {
+  try {
+    if (typeof schema === "function" && /^\s*class\s+/.test(schema.toString())) {
+      return true;
+    }
+    return typeof schema === "function" && schema.prototype && schema.name;
+  } catch {
+    return false;
+  }
+}
+async function validateClassValidator(schema, data) {
+  const object = plainToInstance(schema, data);
+  try {
+    await validateOrReject(object);
+    return object;
+  } catch (errors) {
+    const formattedErrors = Array.isArray(errors) ? errors.map((err) => ({
+      property: err.property,
+      constraints: err.constraints,
+      children: err.children
+    })) : errors;
+    throw new ValidationError(formattedErrors);
+  }
+}
 const safelyGetBody = async (ctx) => {
   const req = ctx.req;
   if (req._bodyParsed) {
@@ -2186,21 +2841,38 @@ const safelyGetBody = async (ctx) => {
 };
 function validate(config) {
   return async (ctx, next) => {
+    const dataToValidate = {};
+    if (config.params) dataToValidate.params = ctx.params;
+    let queryObj;
+    if (config.query) {
+      const url = new URL(ctx.req.url);
+      queryObj = Object.fromEntries(url.searchParams.entries());
+      dataToValidate.query = queryObj;
+    }
+    if (config.headers) dataToValidate.headers = Object.fromEntries(ctx.req.headers.entries());
+    let body;
+    if (config.body) {
+      body = await safelyGetBody(ctx);
+      dataToValidate.body = body;
+    }
+    if (ctx.app?.applicationConfig.hooks?.beforeValidate) {
+      await ctx.app.applicationConfig.hooks.beforeValidate(ctx, dataToValidate);
+    }
     if (config.params) {
       ctx.params = await runValidation(config.params, ctx.params);
     }
-    if (config.query) {
-      const url = new URL(ctx.req.url);
-      const queryObj = Object.fromEntries(url.searchParams.entries());
-      await runValidation(config.query, queryObj);
+    let validQuery;
+    if (config.query && queryObj) {
+      validQuery = await runValidation(config.query, queryObj);
     }
     if (config.headers) {
       const headersObj = Object.fromEntries(ctx.req.headers.entries());
       await runValidation(config.headers, headersObj);
     }
+    let validBody;
     if (config.body) {
-      const body = await safelyGetBody(ctx);
-      const validBody = await runValidation(config.body, body);
+      const b = body ?? await safelyGetBody(ctx);
+      validBody = await runValidation(config.body, b);
       const req = ctx.req;
       req._bodyValue = validBody;
       Object.defineProperty(req, "json", {
@@ -2209,6 +2881,13 @@ function validate(config) {
       });
       ctx.body = validBody;
     }
+    if (ctx.app?.applicationConfig.hooks?.afterValidate) {
+      const validatedData = { ...dataToValidate };
+      if (config.params) validatedData.params = ctx.params;
+      if (config.query) validatedData.query = validQuery;
+      if (config.body) validatedData.body = validBody;
+      await ctx.app.applicationConfig.hooks.afterValidate(ctx, validatedData);
+    }
     return next();
   };
 }
@@ -2225,6 +2904,18 @@ async function runValidation(schema, data) {
   if (isValibotWrapper(schema)) {
     return validateValibotWrapper(schema, data);
   }
+  if (isClass(schema)) {
+    return validateClassValidator(schema, data);
+  }
+  if (isTypeBox(schema)) {
+    return validateTypeBox(schema, data);
+  }
+  if (isAjv(schema)) {
+    return validateAjv(schema, data);
+  }
+  if (isValibotWrapper(schema)) {
+    return validateValibotWrapper(schema, data);
+  }
   if (typeof schema === "function") {
     return schema(data);
   }
@@ -2244,6 +2935,8 @@ export {
   $parent,
   $routeArgs,
   $routeMethods,
+  $routeSpec,
+  $routes,
   All,
   AuthPlugin,
   Body,
@@ -2279,9 +2972,11 @@ export {
   ShokupanRequest,
   ShokupanResponse,
   ShokupanRouter,
+  Spec,
   Use,
   ValidationError,
   compose,
+  useExpress,
   valibot,
   validate
 };