@mastra/koa 1.4.16 → 1.5.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/koa
 
+## 1.5.0-alpha.0
+
+### Minor Changes
+
+- Improved the Koa adapter to make request routing more efficient as route counts grow. ([#16050](https://github.com/mastra-ai/mastra/pull/16050))
+
+  Requests now move through a leaner routing path with lower middleware overhead, which helps Koa-based Mastra servers stay faster and produce cleaner request traces without changing the public API.
+
+### Patch Changes
+
+- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c)]:
+  - @mastra/core@1.31.1-alpha.0
+  - @mastra/server@1.31.1-alpha.0
+
 ## 1.4.16
 
 ### Patch Changes

package/dist/index.cjs

@@ -308,6 +308,7 @@ function toWebRequest2(ctx) {
   });
 }
 var MastraServer = class extends serverAdapter.MastraServer {
+  activeRouteDispatchers = /* @__PURE__ */ new WeakMap();
   async init() {
     this.registerErrorMiddleware();
     await super.init();
@@ -325,11 +326,12 @@ var MastraServer = class extends serverAdapter.MastraServer {
    * should use `server.onError` or register their own middleware between this and the routes.
    */
   registerErrorMiddleware() {
-    this.app.use(async (ctx, next) => {
+    const server = this;
+    this.app.use(async function mastraErrorBoundary(ctx, next) {
       try {
         await next();
       } catch (err) {
-        if (await this.handleOnError(err, ctx)) {
+        if (await server.handleOnError(err, ctx)) {
           return;
         }
         const error = err instanceof Error ? err : new Error(String(err));
@@ -393,7 +395,8 @@ var MastraServer = class extends serverAdapter.MastraServer {
     }
   }
   createContextMiddleware() {
-    return async (ctx, next) => {
+    const server = this;
+    return async function mastraRequestContext(ctx, next) {
       let bodyRequestContext;
       let paramsRequestContext;
       if (ctx.method === "POST" || ctx.method === "PUT") {
@@ -423,14 +426,14 @@ var MastraServer = class extends serverAdapter.MastraServer {
         } catch {
         }
       }
-      const requestContext = this.mergeRequestContext({ paramsRequestContext, bodyRequestContext });
+      const requestContext = server.mergeRequestContext({ paramsRequestContext, bodyRequestContext });
       ctx.state.requestContext = requestContext;
-      ctx.state.mastra = this.mastra;
-      ctx.state.tools = this.tools || {};
-      if (this.taskStore) {
-        ctx.state.taskStore = this.taskStore;
+      ctx.state.mastra = server.mastra;
+      ctx.state.tools = server.tools || {};
+      if (server.taskStore) {
+        ctx.state.taskStore = server.taskStore;
       }
-      ctx.state.customRouteAuthConfig = this.customRouteAuthConfig;
+      ctx.state.customRouteAuthConfig = server.customRouteAuthConfig;
       const controller = new AbortController();
       ctx.req.on("close", () => {
         if (!ctx.res.writableEnded) {
@@ -441,6 +444,193 @@ var MastraServer = class extends serverAdapter.MastraServer {
       await next();
     };
   }
+  getRouteDispatcherGroup(app) {
+    const activeGroup = this.activeRouteDispatchers.get(app);
+    if (activeGroup && app.middleware.length === activeGroup.stackLengthAfterRegistration) {
+      return activeGroup;
+    }
+    const group = {
+      routes: [],
+      stackLengthAfterRegistration: 0
+    };
+    app.use(this.createRouteDispatcherMiddleware(group));
+    group.stackLengthAfterRegistration = app.middleware.length;
+    this.activeRouteDispatchers.set(app, group);
+    return group;
+  }
+  createRouteDispatcherMiddleware(group) {
+    const server = this;
+    return async function mastraRouteDispatcher(ctx, next) {
+      const matchedRoute = server.findRegisteredRoute(group.routes, ctx);
+      if (!matchedRoute) {
+        await next();
+        return;
+      }
+      await server.handleMatchedRoute(matchedRoute, ctx);
+    };
+  }
+  findRegisteredRoute(routes, ctx) {
+    const method = ctx.method.toUpperCase();
+    for (const registeredRoute of routes) {
+      if (registeredRoute.route.method.toUpperCase() !== "ALL" && method !== registeredRoute.route.method.toUpperCase()) {
+        continue;
+      }
+      const match = registeredRoute.pathRegex.exec(ctx.path);
+      if (!match) {
+        continue;
+      }
+      ctx.params = {};
+      registeredRoute.paramNames.forEach((name, index) => {
+        ctx.params[name] = match[index + 1];
+      });
+      return registeredRoute;
+    }
+    return void 0;
+  }
+  async handleMatchedRoute(registeredRoute, ctx) {
+    const { route, prefix } = registeredRoute;
+    const authError = await this.checkRouteAuth(route, {
+      path: String(ctx.path || "/"),
+      method: String(ctx.method || "GET"),
+      getHeader: (name) => ctx.headers[name.toLowerCase()],
+      getQuery: (name) => ctx.query[name],
+      requestContext: ctx.state.requestContext,
+      request: toWebRequest2(ctx),
+      buildAuthorizeContext: () => toWebRequest2(ctx)
+    });
+    if (authError) {
+      if (authError.headers) {
+        for (const [key, value] of Object.entries(authError.headers)) {
+          ctx.set(key, value);
+        }
+      }
+      if (authError.error) {
+        ctx.status = authError.status;
+        ctx.body = { error: authError.error };
+        return;
+      }
+    }
+    const params = await this.getParams(route, ctx);
+    if (params.bodyParseError) {
+      ctx.status = 400;
+      ctx.body = {
+        error: "Invalid request body",
+        issues: [{ field: "body", message: params.bodyParseError.message }]
+      };
+      return;
+    }
+    if (params.queryParams) {
+      try {
+        params.queryParams = await this.parseQueryParams(route, params.queryParams);
+      } catch (error) {
+        this.mastra.getLogger()?.error("Error parsing query params", {
+          error: error instanceof Error ? { message: error.message, stack: error.stack } : error
+        });
+        if (error instanceof ZodError) {
+          const resolved = this.resolveValidationError(route, error, "query");
+          ctx.status = resolved.status;
+          ctx.body = resolved.body;
+          return;
+        }
+        ctx.status = 400;
+        ctx.body = {
+          error: "Invalid query parameters",
+          issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
+        };
+        return;
+      }
+    }
+    if (params.body) {
+      try {
+        params.body = await this.parseBody(route, params.body);
+      } catch (error) {
+        this.mastra.getLogger()?.error("Error parsing body", {
+          error: error instanceof Error ? { message: error.message, stack: error.stack } : error
+        });
+        if (error instanceof ZodError) {
+          const resolved = this.resolveValidationError(route, error, "body");
+          ctx.status = resolved.status;
+          ctx.body = resolved.body;
+          return;
+        }
+        ctx.status = 400;
+        ctx.body = {
+          error: "Invalid request body",
+          issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
+        };
+        return;
+      }
+    }
+    if (params.urlParams) {
+      try {
+        params.urlParams = await this.parsePathParams(route, params.urlParams);
+      } catch (error) {
+        this.mastra.getLogger()?.error("Error parsing path params", {
+          error: error instanceof Error ? { message: error.message, stack: error.stack } : error
+        });
+        if (error instanceof ZodError) {
+          const resolved = this.resolveValidationError(route, error, "path");
+          ctx.status = resolved.status;
+          ctx.body = resolved.body;
+          return;
+        }
+        ctx.status = 400;
+        ctx.body = {
+          error: "Invalid path parameters",
+          issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
+        };
+        return;
+      }
+    }
+    const handlerParams = {
+      ...params.urlParams,
+      ...params.queryParams,
+      ...typeof params.body === "object" ? params.body : {},
+      requestContext: ctx.state.requestContext,
+      mastra: this.mastra,
+      tools: ctx.state.tools,
+      taskStore: ctx.state.taskStore,
+      abortSignal: ctx.state.abortSignal,
+      routePrefix: prefix
+    };
+    const authConfig = this.mastra.getServer()?.auth;
+    if (authConfig) {
+      const hasPermission = await loadHasPermission();
+      if (hasPermission) {
+        const userPermissions = ctx.state.requestContext.get("userPermissions");
+        const permissionError = this.checkRoutePermission(route, userPermissions, hasPermission);
+        if (permissionError) {
+          ctx.status = permissionError.status;
+          ctx.body = {
+            error: permissionError.error,
+            message: permissionError.message
+          };
+          return;
+        }
+      }
+    }
+    try {
+      const result = await route.handler(handlerParams);
+      await this.sendResponse(route, ctx, result, prefix);
+    } catch (error) {
+      this.mastra.getLogger()?.error("Error calling handler", {
+        error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
+        path: route.path,
+        method: route.method
+      });
+      if (error && typeof error === "object") {
+        if (!("status" in error)) {
+          if ("details" in error && error.details && typeof error.details === "object" && "status" in error.details) {
+            error.status = error.details.status;
+          }
+        }
+      }
+      if (await this.handleOnError(error, ctx)) {
+        return;
+      }
+      throw error;
+    }
+  }
   async stream(route, ctx, result) {
     ctx.respond = false;
     const streamFormat = route.streamFormat || "stream";
@@ -666,165 +856,14 @@ var MastraServer = class extends serverAdapter.MastraServer {
     const prefix = prefixParam ?? this.prefix ?? "";
     const fullPath = `${prefix}${route.path}`;
     const koaPath = fullPath;
-    const handler = async (ctx, next) => {
-      const pathRegex = this.pathToRegex(koaPath);
-      const match = pathRegex.exec(ctx.path);
-      if (!match) {
-        await next();
-        return;
-      }
-      if (route.method.toUpperCase() !== "ALL" && ctx.method.toUpperCase() !== route.method.toUpperCase()) {
-        await next();
-        return;
-      }
-      const paramNames = this.extractParamNames(koaPath);
-      ctx.params = {};
-      paramNames.forEach((name, index) => {
-        ctx.params[name] = match[index + 1];
-      });
-      const authError = await this.checkRouteAuth(route, {
-        path: String(ctx.path || "/"),
-        method: String(ctx.method || "GET"),
-        getHeader: (name) => ctx.headers[name.toLowerCase()],
-        getQuery: (name) => ctx.query[name],
-        requestContext: ctx.state.requestContext,
-        request: toWebRequest2(ctx),
-        buildAuthorizeContext: () => toWebRequest2(ctx)
-      });
-      if (authError) {
-        if (authError.headers) {
-          for (const [key, value] of Object.entries(authError.headers)) {
-            ctx.set(key, value);
-          }
-        }
-        if (authError.error) {
-          ctx.status = authError.status;
-          ctx.body = { error: authError.error };
-          return;
-        }
-      }
-      const params = await this.getParams(route, ctx);
-      if (params.bodyParseError) {
-        ctx.status = 400;
-        ctx.body = {
-          error: "Invalid request body",
-          issues: [{ field: "body", message: params.bodyParseError.message }]
-        };
-        return;
-      }
-      if (params.queryParams) {
-        try {
-          params.queryParams = await this.parseQueryParams(route, params.queryParams);
-        } catch (error) {
-          this.mastra.getLogger()?.error("Error parsing query params", {
-            error: error instanceof Error ? { message: error.message, stack: error.stack } : error
-          });
-          if (error instanceof ZodError) {
-            const resolved = this.resolveValidationError(route, error, "query");
-            ctx.status = resolved.status;
-            ctx.body = resolved.body;
-            return;
-          }
-          ctx.status = 400;
-          ctx.body = {
-            error: "Invalid query parameters",
-            issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
-          };
-          return;
-        }
-      }
-      if (params.body) {
-        try {
-          params.body = await this.parseBody(route, params.body);
-        } catch (error) {
-          this.mastra.getLogger()?.error("Error parsing body", {
-            error: error instanceof Error ? { message: error.message, stack: error.stack } : error
-          });
-          if (error instanceof ZodError) {
-            const resolved = this.resolveValidationError(route, error, "body");
-            ctx.status = resolved.status;
-            ctx.body = resolved.body;
-            return;
-          }
-          ctx.status = 400;
-          ctx.body = {
-            error: "Invalid request body",
-            issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
-          };
-          return;
-        }
-      }
-      if (params.urlParams) {
-        try {
-          params.urlParams = await this.parsePathParams(route, params.urlParams);
-        } catch (error) {
-          this.mastra.getLogger()?.error("Error parsing path params", {
-            error: error instanceof Error ? { message: error.message, stack: error.stack } : error
-          });
-          if (error instanceof ZodError) {
-            const resolved = this.resolveValidationError(route, error, "path");
-            ctx.status = resolved.status;
-            ctx.body = resolved.body;
-            return;
-          }
-          ctx.status = 400;
-          ctx.body = {
-            error: "Invalid path parameters",
-            issues: [{ field: "unknown", message: error instanceof Error ? error.message : "Unknown error" }]
-          };
-          return;
-        }
-      }
-      const handlerParams = {
-        ...params.urlParams,
-        ...params.queryParams,
-        ...typeof params.body === "object" ? params.body : {},
-        requestContext: ctx.state.requestContext,
-        mastra: this.mastra,
-        tools: ctx.state.tools,
-        taskStore: ctx.state.taskStore,
-        abortSignal: ctx.state.abortSignal,
-        routePrefix: prefix
-      };
-      const authConfig = this.mastra.getServer()?.auth;
-      if (authConfig) {
-        const hasPermission = await loadHasPermission();
-        if (hasPermission) {
-          const userPermissions = ctx.state.requestContext.get("userPermissions");
-          const permissionError = this.checkRoutePermission(route, userPermissions, hasPermission);
-          if (permissionError) {
-            ctx.status = permissionError.status;
-            ctx.body = {
-              error: permissionError.error,
-              message: permissionError.message
-            };
-            return;
-          }
-        }
-      }
-      try {
-        const result = await route.handler(handlerParams);
-        await this.sendResponse(route, ctx, result, prefix);
-      } catch (error) {
-        this.mastra.getLogger()?.error("Error calling handler", {
-          error: error instanceof Error ? { message: error.message, stack: error.stack } : error,
-          path: route.path,
-          method: route.method
-        });
-        if (error && typeof error === "object") {
-          if (!("status" in error)) {
-            if ("details" in error && error.details && typeof error.details === "object" && "status" in error.details) {
-              error.status = error.details.status;
-            }
-          }
-        }
-        if (await this.handleOnError(error, ctx)) {
-          return;
-        }
-        throw error;
-      }
-    };
-    app.use(handler);
+    const group = this.getRouteDispatcherGroup(app);
+    group.routes.push({
+      route,
+      prefix,
+      koaPath,
+      pathRegex: this.pathToRegex(koaPath),
+      paramNames: this.extractParamNames(koaPath)
+    });
   }
   /**
    * Convert Express-style path to regex for matching
@@ -845,10 +884,11 @@ var MastraServer = class extends serverAdapter.MastraServer {
   }
   async registerCustomApiRoutes() {
     if (!await this.buildCustomRouteHandler()) return;
-    this.app.use(async (ctx, next) => {
+    const server = this;
+    this.app.use(async function mastraCustomRouteDispatcher(ctx, next) {
       const path = String(ctx.path || "/");
       const method = String(ctx.method || "GET");
-      if (auth.isProtectedCustomRoute(path, method, this.customRouteAuthConfig)) {
+      if (auth.isProtectedCustomRoute(path, method, server.customRouteAuthConfig)) {
         const serverRoute = {
           method,
           path,
@@ -856,7 +896,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
           handler: async () => {
           }
         };
-        const authError = await this.checkRouteAuth(serverRoute, {
+        const authError = await server.checkRouteAuth(serverRoute, {
           path,
           method,
           getHeader: (name) => ctx.headers[name.toLowerCase()],
@@ -877,7 +917,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
             return;
           }
         }
-        const authConfig = this.mastra.getServer()?.auth;
+        const authConfig = server.mastra.getServer()?.auth;
         if (authConfig) {
           let hasPermission;
           try {
@@ -889,7 +929,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
           }
           if (hasPermission) {
             const userPermissions = ctx.state.requestContext.get("userPermissions");
-            const permissionError = this.checkRoutePermission(serverRoute, userPermissions, hasPermission);
+            const permissionError = server.checkRoutePermission(serverRoute, userPermissions, hasPermission);
             if (permissionError) {
               ctx.status = permissionError.status;
               ctx.body = {
@@ -901,7 +941,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
           }
         }
       }
-      const response = await this.handleCustomRouteRequest(
+      const response = await server.handleCustomRouteRequest(
         `${ctx.protocol}://${ctx.host}${ctx.originalUrl || ctx.url}`,
         ctx.method,
         ctx.headers,
@@ -910,7 +950,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
       );
       if (!response) return next();
       ctx.respond = false;
-      await this.writeCustomRouteResponse(response, ctx.res);
+      await server.writeCustomRouteResponse(response, ctx.res);
     });
   }
   registerContextMiddleware() {
@@ -922,8 +962,9 @@ var MastraServer = class extends serverAdapter.MastraServer {
     if (!this.httpLoggingConfig?.enabled) {
       return;
     }
-    this.app.use(async (ctx, next) => {
-      if (!this.shouldLogRequest(ctx.path)) {
+    const server = this;
+    this.app.use(async function mastraHttpLogger(ctx, next) {
+      if (!server.shouldLogRequest(ctx.path)) {
         return next();
       }
       const start = Date.now();
@@ -932,19 +973,19 @@ var MastraServer = class extends serverAdapter.MastraServer {
       await next();
       const duration2 = Date.now() - start;
       const status = ctx.status;
-      const level = this.httpLoggingConfig?.level || "info";
+      const level = server.httpLoggingConfig?.level || "info";
       const logData = {
         method,
         path,
         status,
         duration: `${duration2}ms`
       };
-      if (this.httpLoggingConfig?.includeQueryParams) {
+      if (server.httpLoggingConfig?.includeQueryParams) {
         logData.query = ctx.query;
       }
-      if (this.httpLoggingConfig?.includeHeaders) {
+      if (server.httpLoggingConfig?.includeHeaders) {
         const headers = { ...ctx.headers };
-        const redactHeaders = this.httpLoggingConfig.redactHeaders || [];
+        const redactHeaders = server.httpLoggingConfig.redactHeaders || [];
         redactHeaders.forEach((h) => {
           const key = h.toLowerCase();
           if (headers[key] !== void 0) {
@@ -953,7 +994,7 @@ var MastraServer = class extends serverAdapter.MastraServer {
         });
         logData.headers = headers;
       }
-      this.logger[level](`${method} ${path} ${status} ${duration2}ms`, logData);
+      server.logger[level](`${method} ${path} ${status} ${duration2}ms`, logData);
     });
   }
 };