shokupan 0.3.0 → 0.4.5

package/README.md

@@ -1,44 +1,45 @@
 # Shokupan 🍞
 
-> A low-lift modern web framework for Bun
+> A delightful, type-safe web framework for Bun
 
-Shokupan is a high-performance, feature-rich web framework built specifically for Bun. It combines the familiarity of Express.js with modern NestJS-style architecture (Dependency Injection, Controllers) and seamless compatibility with the vast ecosystem of Express plugins — all while maintaining exceptional performance and built-in OpenAPI support.
+**Built for Developer Experience**
+Shokupan is designed to make building APIs delightful again. With zero-config defaults, instant startup times, and full type safety out of the box, you can focus on building your product, not configuring your framework.
 
 ### Note: Shokupan is still in alpha and is not guaranteed to be stable. Please use with caution. We will be adding more features and APIs in the future. Please file an issue if you find any bugs or have suggestions for improvement.
 
 ## ✨ Features
 
-- 🚀 **Built for Bun** - Native [Bun](https://bun.sh/) performance with optimized routing
-- 🎯 **TypeScript First** - Full type safety with decorators and generics
-- 📝 **Auto OpenAPI** - Generate [OpenAPI](https://www.openapis.org/) specs automatically from routes
-- 🔌 **Rich Plugin System** - CORS, Sessions, Auth, Validation, Rate Limiting, and more
-- 🌐 **Flexible Routing** - Express-style routes or decorator-based controllers
-- 🔀 **Express Compatible** - Works with [Express](https://expressjs.com/) middleware patterns
-- 📊 **Built-in Telemetry** - [OpenTelemetry](https://opentelemetry.io/) instrumentation out of the box
-- 🔐 **OAuth2 Support** - GitHub, Google, Microsoft, Apple, Auth0, Okta
-- ✅ **Multi-validator Support** - Zod, Ajv, TypeBox, Valibot
-- 📚 **OpenAPI Docs** - Beautiful OpenAPI documentation with [Scalar](https://scalar.dev/)
-- ⏩ **Short shift** - Very simple migration from [Express](https://expressjs.com/) or [NestJS](https://nestjs.com/) to Shokupan
+- 🎯 **TypeScript First** - End-to-end type safety with decorators and generics. No manual types needed.
+- 🛠️ **Zero Config** - Works effectively out of the box. No complex setup or boilerplate.
+- 🚀 **Built for Bun** - Native [Bun](https://bun.sh/) performance with instant startup.
+- 🔍 **Debug Dashboard** - Visual inspector for your routes, middleware, and request flow.
+- 📝 **Auto OpenAPI** - Generate [OpenAPI](https://www.openapis.org/) specs automatically from routes.
+- 🔌 **Rich Plugin System** - CORS, Sessions, Auth, Validation, Rate Limiting, and more.
+- 🌐 **Flexible Routing** - Express-style routes or decorator-based controllers.
+- 🔀 **Express Compatible** - Works with [Express](https://expressjs.com/) middleware patterns.
+- 📊 **Built-in Telemetry** - [OpenTelemetry](https://opentelemetry.io/) instrumentation out of the box.
+- 🔐 **OAuth2 Support** - GitHub, Google, Microsoft, Apple, Auth0, Okta.
+- ✅ **Multi-validator Support** - Zod, Ajv, TypeBox, Valibot.
+- 📚 **OpenAPI Docs** - Beautiful OpenAPI documentation with [Scalar](https://scalar.dev/).
+- ⏩ **Short shift** - Very simple migration from [Express](https://expressjs.com/) or [NestJS](https://nestjs.com/) to Shokupan.
 
-## 📦 Installation
+![Shokupan Debug Dashboard](docs/src/assets/debug_dashboard_overview.png)
 
-```bash
-bun add shokupan
-```
 
 ## 🚀 Quick Start
 
+> Bun and TypeScript are recommended for Shokupan, though it also supports Node.js and standard JavaScript.
+
 ```typescript
 import { Shokupan } from 'shokupan';
+const app = new Shokupan();
 
-const app = new Shokupan({
-    port: 3000,
-    development: true
-});
+app.get('/', (ctx) => ({ message: 'Hello, World!' }));
+app.get('/hello', (ctx) => "world");
 
-app.get('/', (ctx) => {
-    return { message: 'Hello, World!' };
-});
+app.mount('/scalar', new ScalarPlugin({
+    enableStaticAnalysis: true
+}));
 
 app.listen();
 ```
@@ -829,6 +830,119 @@ app.mount('/docs', new ScalarPlugin({
 
 The Scalar plugin automatically generates OpenAPI documentation from your routes and controllers!
 
+### Proxy
+
+Create a reverse proxy to forward requests to another server:
+
+```typescript
+import { Proxy } from 'shokupan';
+
+app.use('/api/v1', Proxy({
+    target: 'https://api.example.com',
+    changeOrigin: true,
+    pathRewrite: (path) => path.replace('/api/v1', ''),
+    headers: {
+        'X-Custom-Header': 'Proxy'
+    }
+}));
+
+// Proxy WebSockets
+app.use('/socket', Proxy({
+    target: 'ws://ws.example.com',
+    ws: true
+}));
+```
+
+### OpenAPI Validator
+
+Validate incoming requests against your generated OpenAPI specification:
+
+```typescript
+import { enableOpenApiValidation } from 'shokupan';
+
+const app = new Shokupan({ enableOpenApiGen: true });
+
+// Enable validation middleware
+// This validates Body, Query, Params, and Headers against your OpenAPI definitions
+enableOpenApiValidation(app);
+
+app.post('/users', {
+    parameters: [
+        { name: 'apiKey', in: 'header', required: true, schema: { type: 'string' } }
+    ],
+    requestBody: {
+        content: {
+            'application/json': {
+                schema: {
+                    type: 'object',
+                    required: ['name'],
+                    properties: {
+                        name: { type: 'string', minLength: 3 }
+                    }
+                }
+            }
+        }
+    }
+}, (ctx) => {
+    return { success: true };
+});
+
+// Invalid requests will throw a ValidationError (400 Bad Request)
+```
+
+### Idempotency
+
+Ensure that multiple identical requests do not result in different outcomes (e.g., duplicate payments). This middleware caches the response of the first request and returns it for subsequent requests with the same idempotency key.
+
+```typescript
+import { Idempotency } from 'shokupan';
+
+app.post('/payments', 
+    Idempotency({
+        header: 'Idempotency-Key', // default
+        ttl: 24 * 60 * 60 * 1000   // default 24h
+    }),
+    async (ctx) => {
+        // Process payment...
+        return { status: 'charged' };
+    }
+);
+```
+
+### Failed Request Recorder
+
+Automatically record failed requests (500s) for debugging and replay purposes.
+
+```typescript
+import { FailedRequestRecorder } from 'shokupan';
+
+app.use(FailedRequestRecorder({
+    maxCapacity: 1000,
+    ttl: 86400000 // 1 day
+}));
+```
+
+This works great when combined with the Debug Dashboard.
+
+### Debug Dashboard
+
+A visual dashboard to inspect your application, view metrics, analyze the middleware graph, and replay failed requests.
+
+```typescript
+import { DebugDashboard } from 'shokupan/plugins/debugview';
+
+// Mount the dashboard
+app.mount('/debug', new DebugDashboard({
+    retentionMs: 2 * 60 * 60 * 1000, // Keep 2 hours of logs
+    getRequestHeaders: () => ({
+        'Authorization': 'Bearer ...' // Headers to using when replaying requests and accessing data APIs
+    })
+}));
+
+// Available at http://localhost:3000/debug
+```
+
+
 ## 🚀 Advanced Features
 
 ### Dependency Injection
@@ -999,8 +1113,40 @@ provider.addSpanProcessor(
 provider.register();
 ```
 
+### Server Factory (Node.js & Deno)
+
+Run Shokupan on Node.js or Deno using the server adapter:
+
+```typescript
+import { Shokupan, createHttpServer } from 'shokupan';
+
+const app = new Shokupan({
+    // Use Node.js http module
+    serverFactory: createHttpServer()
+});
+
+app.get('/', () => ({ message: 'Running on Node!' }));
+
+app.listen(3000);
+```
+
+### Automatic Backpressure
+
+Protect your server from overload by shedding load when CPU usage is high:
+
+```typescript
+const app = new Shokupan({
+    // Monitor CPU and reject requests when usage > 80%
+    autoBackpressureFeedback: true,
+    autoBackpressureLevel: 80 
+});
+```
+
+When the threshold is reached, the server will return `429 Too Many Requests`.
+
 ## 📦 Migration Guides
 
+
 ### From Express
 
 Shokupan is designed to feel familiar to Express developers. Here's how to migrate:
@@ -1397,6 +1543,10 @@ app.use(useExpress(compression()));
 ## 🧪 Testing
 
 Shokupan applications are easy to test using Bun's built-in test runner.
+It can directly pass requests to the application or a router without requiring the 
+server to fully start, bind to a port or listen for connections. This makes mocking 
+the server unnecessary and allows for faster and more reliable testing. Additionally
+you can directly test authenticated endpoints without the need for a session or cookie.
 
 ```typescript
 import { describe, it, expect } from 'bun:test';
@@ -1427,13 +1577,13 @@ Since Shokupan is built on Bun, deployment is straightforward.
 ### Using Bun
 
 ```bash
-bun run src/index.ts
+bun run src/main.ts
 ```
 
 ### Docker
 
 ```dockerfile
-FROM oven/bun:1
+FROM oven/bun:1-alpine
 
 WORKDIR /app
 
@@ -1442,7 +1592,7 @@ RUN bun install --production
 
 EXPOSE 3000
 
-CMD ["bun", "run", "src/index.ts"]
+CMD ["bun", "run", "src/main.ts"]
 ```
 
 ## 🛠️ CLI Tools
@@ -1530,6 +1680,14 @@ const app = new Shokupan(config?: ShokupanConfig);
 - `hostname?: string` - Hostname (default: "localhost")
 - `development?: boolean` - Development mode (default: auto-detect)
 - `enableAsyncLocalStorage?: boolean` - Enable async context tracking
+- `enableTracing?: boolean` - Enable OpenTelemetry tracing
+- `enableOpenApiGen?: boolean` - Enable OpenAPI spec generation (default: true)
+- `controllersOnly?: boolean` - If true, only allows controllers, disabling app.get/post/etc (default: false)
+- `requestTimeout?: number` - Global request timeout (ms)
+- `readTimeout?: number` - Request body read timeout (ms)
+- `serverFactory?: ServerFactory` - Custom server factory (for Node.js/Deno support)
+- `autoBackpressureFeedback?: boolean` - Enable automatic load shedding based on CPU usage
+- `autoBackpressureLevel?: number` - CPU usage % threshold for backpressure (default: 60)
 - `logger?: Logger` - Custom logger instance
 
 **Methods:**
@@ -1551,7 +1709,13 @@ const app = new Shokupan(config?: ShokupanConfig);
 
 ### ShokupanRouter Class
 
-Router for grouping routes.
+Router for grouping operations, applying middleware, and mounting controllers. Additionally
+they are effective for creating sub-applications that are independently tested. Routers can 
+have OpenAPI spec applied to all endpoints of the router. Additionally they can be mounted
+onto the main application or other routers.
+
+When a router is mounted to an app, if you are using the DebugView plugin you will be able to
+see it under the Registry tab and the Graph tab.
 
 ```typescript
 const router = new ShokupanRouter(config?: ShokupanRouteConfig);
@@ -1592,6 +1756,13 @@ Request context object.
 - `state: Record<string, any>` - Shared state object
 - `session: any` - Session data (with session plugin)
 - `response: ShokupanResponse` - Response builder
+- `ip: string` - Client IP address
+- `hostname: string` - Hostname (e.g. "localhost")
+- `host: string` - Host (e.g. "localhost:3000")
+- `protocol: string` - Protocol (http/https)
+- `secure: boolean` - Whether the request is secure over HTTPS
+- `origin: string` - Origin URL
+- `signal: AbortSignal` - Request abort signal (for standard fetch requests)
 
 **Methods:**
 - `set(name: string, value: string): ShokupanContext` - Set a response header
@@ -1602,6 +1773,7 @@ Request context object.
 - `json(data: any, status?: number): ShokupanContext` - Return JSON response
 - `text(data: string, status?: number): ShokupanContext` - Return text response
 - `html(data: string, status?: number): ShokupanContext` - Return HTML response
+- `jsx(element: any): ShokupanContext` - Render a JSX element
 - `redirect(url: string, status?: number): ShokupanContext` - Redirect response
 - `file(path: string, fileOptions?: BlobPropertyBag, responseOptions?: ResponseInit): Response` - Return file response
 
@@ -1639,7 +1811,6 @@ Container.clear();
 - 🚧 **Framework Plugins** - Drop-in adapters for [Express](https://expressjs.com/), [Koa](https://koajs.com/), and [Elysia](https://elysiajs.com/)
 - 🚧 **Enhanced WebSockets** - Event support and HTTP simulation
 - 🚧 **Benchmarks** - Comprehensive performance comparisons
-- 🚧 **Scaling** - Automatic clustering support
 - 🚧 **RPC Support** - [tRPC](https://trpc.io/) and [gRPC](https://grpc.io/) integration
 - 🚧 **Binary Formats** - [Protobuf](https://protobuf.dev/) and [MessagePack](https://msgpack.org/) support
 - 🚧 **Reliability** - Circuit breaker pattern for resilience
@@ -1652,7 +1823,7 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
+4. Publish the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
 ## 📝 License
@@ -1664,7 +1835,8 @@ MIT License - see the [LICENSE](LICENSE) file for details.
 - Inspired by [Express](https://expressjs.com/), [Koa](https://koajs.com/), [NestJS](https://nestjs.com/), and [Elysia](https://elysiajs.com/)
 - Built for the amazing [Bun](https://bun.sh/) runtime
 - Powered by [Arctic](https://github.com/pilcrowonpaper/arctic) for OAuth2 support
+- Tests and Benchmarks created with Antigravity
 
 ---
 
-**Made with 🍞 by the Shokupan team**
+**Made with ❤️ by the Shokupan team**

package/dist/context.d.ts

@@ -9,6 +9,8 @@ export interface HandlerStackItem {
     file: string;
     line: number;
     stateChanges?: Record<string, any>;
+    startTime?: number;
+    duration?: number;
 }
 export interface DebugCollector {
     trackStep(id: string | undefined, type: string, duration: number, status: 'success' | 'error', error?: any): void;
@@ -51,7 +53,7 @@ export declare class ShokupanContext<State extends Record<string, any> = Record<
     /**
      * Client IP address
      */
-    get ip(): Bun.SocketAddress;
+    get ip(): any;
     /**
      * Request hostname (e.g. "localhost")
      */

package/dist/index.cjs

@@ -1397,6 +1397,7 @@ const ready = db.connect(engine, { namespace: "vendor", database: "shokupan" }).
         DEFINE TABLE OVERWRITE users SCHEMALESS COMMENT "Created by Shokupan";
         DEFINE TABLE OVERWRITE idempotency_keys SCHEMALESS COMMENT "Created by Shokupan";
         DEFINE TABLE OVERWRITE middleware_tracking SCHEMALESS COMMENT "Created by Shokupan";
+        DEFINE TABLE OVERWRITE requests SCHEMALESS COMMENT "Created by Shokupan";
     `);
 });
 const datastore = {
@@ -1506,17 +1507,28 @@ class ShokupanRouter {
   currentGuards = [];
   // Registry Accessor
   getComponentRegistry() {
-    const routes = this[$routes].map((r) => ({
-      type: "route",
-      path: r.path,
-      method: r.method,
-      metadata: r.metadata,
-      handlerName: r.handler.name,
-      tags: r.handlerSpec?.tags,
-      order: r.order,
-      _fn: r.handler
-      // Expose handler for debugging instrumentation
-    }));
+    const controllerRoutesMap = /* @__PURE__ */ new Map();
+    const localRoutes = [];
+    for (const r of this[$routes]) {
+      const entry = {
+        type: "route",
+        path: r.path,
+        method: r.method,
+        metadata: r.metadata,
+        handlerName: r.handler.name,
+        tags: r.handlerSpec?.tags,
+        order: r.order,
+        _fn: r.handler
+      };
+      if (r.controller) {
+        if (!controllerRoutesMap.has(r.controller)) {
+          controllerRoutesMap.set(r.controller, []);
+        }
+        controllerRoutesMap.get(r.controller).push(entry);
+      } else {
+        localRoutes.push(entry);
+      }
+    }
     const mw = this.middleware;
     const middleware = mw ? mw.map((m) => ({
       name: m.name || "middleware",
@@ -1532,18 +1544,19 @@ class ShokupanRouter {
       children: r.getComponentRegistry()
     }));
     const controllers = this[$childControllers].map((c) => {
+      const routes = controllerRoutesMap.get(c) || [];
       return {
         type: "controller",
         path: c[$mountPath] || "/",
         name: c.constructor.name,
-        metadata: c.metadata
-        // Check if we can store this
+        metadata: c.metadata,
+        children: { routes }
       };
     });
     return {
       metadata: this.metadata,
       middleware,
-      routes,
+      routes: localRoutes,
       routers,
       controllers
     };
@@ -1633,7 +1646,7 @@ class ShokupanRouter {
       const decoratedArgs = instance[$routeArgs] || proto && proto[$routeArgs];
       const methodMiddlewareMap = instance[$middleware] || proto && proto[$middleware];
       let routesAttached = 0;
-      for (const name of methods) {
+      for (const name of Array.from(methods)) {
         if (name === "constructor") continue;
         if (["arguments", "caller", "callee"].includes(name)) continue;
         const originalHandler = instance[name];
@@ -1767,7 +1780,7 @@ class ShokupanRouter {
           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 });
+          this.add({ method, path: normalizedPath, handler: finalHandler, spec, controller: instance });
         }
       }
       if (routesAttached === 0) {
@@ -1988,8 +2001,23 @@ class ShokupanRouter {
    * @param handler - Route handler function
    * @param requestTimeout - Timeout for this route in milliseconds
    */
-  add({ method, path: path2, spec, handler, regex: customRegex, group, requestTimeout, renderer }) {
+  add({ method, path: path2, spec, handler, regex: customRegex, group, requestTimeout, renderer, controller }) {
     const { regex, keys } = customRegex ? { regex: customRegex, keys: [] } : this.parsePath(path2);
+    if (this.currentGuards.length > 0) {
+      spec = spec || {};
+      for (const guard of this.currentGuards) {
+        if (guard.spec) {
+          if (guard.spec.responses) {
+            spec.responses = spec.responses || {};
+            Object.assign(spec.responses, guard.spec.responses);
+          }
+          if (guard.spec.security) {
+            spec.security = spec.security || [];
+            spec.security.push(...guard.spec.security);
+          }
+        }
+      }
+    }
     let wrappedHandler = handler;
     const routeGuards = [...this.currentGuards];
     const effectiveTimeout = requestTimeout ?? this.requestTimeout ?? this.rootConfig?.requestTimeout;
@@ -2115,7 +2143,8 @@ class ShokupanRouter {
       metadata: {
         file,
         line
-      }
+      },
+      controller
     });
     this.trie.insert(method, path2, bakedHandler);
     return this;
@@ -2349,12 +2378,21 @@ class Shokupan extends ShokupanRouter {
       const c = ctx;
       if (c.handlerStack && c.app?.applicationConfig.enableMiddlewareTracking) {
         const metadata = middleware.metadata || {};
-        c.handlerStack.push({
+        const start = performance.now();
+        const item = {
           name: metadata.pluginName ? `${metadata.pluginName} (${metadata.name})` : metadata.name || middleware.name || "middleware",
           file: metadata.file || file,
           line: metadata.line || line,
-          isBuiltin: metadata.isBuiltin
-        });
+          isBuiltin: metadata.isBuiltin,
+          startTime: start,
+          duration: -1
+        };
+        c.handlerStack.push(item);
+        try {
+          return await middleware(ctx, next);
+        } finally {
+          item.duration = performance.now() - start;
+        }
       }
       return middleware(ctx, next);
     };
@@ -2895,14 +2933,14 @@ function Compression(options = {}) {
       if (ctx._rawBody !== void 0) {
         if (typeof ctx._rawBody === "string") {
           const encoded = new TextEncoder().encode(ctx._rawBody);
-          body = encoded.buffer;
+          body = encoded;
           bodySize = encoded.byteLength;
         } else if (ctx._rawBody instanceof Uint8Array) {
-          body = ctx._rawBody.buffer;
+          body = ctx._rawBody;
           bodySize = ctx._rawBody.byteLength;
         } else {
           body = ctx._rawBody;
-          bodySize = ctx._rawBody.byteLength;
+          bodySize = body.byteLength;
         }
       } else {
         body = await response.arrayBuffer();
@@ -2912,7 +2950,7 @@ function Compression(options = {}) {
         return new Response(body, {
           status: response.status,
           statusText: response.statusText,
-          headers: response.headers
+          headers: new Headers(response.headers)
         });
       }
       let compressed;
@@ -3435,7 +3473,8 @@ function enableOpenApiValidation(app) {
 }
 const eta = new eta$2.Eta();
 class ScalarPlugin extends ShokupanRouter {
-  constructor(pluginOptions) {
+  constructor(pluginOptions = {}) {
+    pluginOptions.config ??= {};
     super();
     this.pluginOptions = pluginOptions;
     this.init();