Support global RxRouter filters for unmatched routes (e.g., CORS preflight) (#4172)

## Summary

- Fix: When using
`RxRouter.filter(corsFilter).andThen(RxRouter.of[Controller])`, OPTIONS
preflight requests returned 404 because the route matcher groups routes
by HTTP method — unmatched methods fell through to 404 before global
filters could run.
- Track accumulated filter chains from non-leaf filter nodes as a
`fallbackFilter` in `RoutingTable`. When route matching fails, apply the
fallback filter so global filters like CORS can intercept unmatched
requests.
- Add integration test verifying OPTIONS preflight and CORS headers work
with controller-based routing.

## Test plan

- [x] New `CorsControllerTest` verifies OPTIONS preflight returns CORS
headers with controller-based routing
- [x] New test verifies CORS headers are added to normal POST responses
- [x] Existing `CorsFilterTest` (leaf endpoint pattern) still passes —
no regression

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: xerial

airframe-http-netty/src/test/scala/wvlet/airframe/http/netty/CorsControllerTest.scala

@@ -0,0 +1,70 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package wvlet.airframe.http.netty
+
+import wvlet.airframe.http.*
+import wvlet.airframe.http.client.SyncClient
+import wvlet.airframe.http.filter.Cors
+import wvlet.airspec.AirSpec
+
+object CorsControllerTest extends AirSpec {
+  @RPC
+  class MyApi {
+    def hello(msg: String): String = s"Hello ${msg}!"
+  }
+
+  private val corsRouter = RxRouter
+    .filter(Cors.newFilter(Cors.unsafePermissivePolicy))
+    .andThen(RxRouter.of[MyApi])
+}
+
+/**
+  * Test that CORS filter works with controller-based routing via RxRouter.filter(...). Previously, OPTIONS preflight
+  * requests would return 404 because the route matcher rejects unmatched HTTP methods before filters run.
+  */
+class CorsControllerTest extends AirSpec {
+  import CorsControllerTest.*
+
+  initDesign { d =>
+    Netty.server.withRouter(corsRouter).designWithSyncClient
+  }
+
+  test("handle OPTIONS preflight for controller routes") { (client: SyncClient) =>
+    val resp = client.send(
+      Http
+        .request(HttpMethod.OPTIONS, "/wvlet.airframe.http.netty.CorsControllerTest.MyApi/hello")
+        .withHeader("Origin", "https://example.com")
+        .withHeader("Access-Control-Request-Method", "POST")
+        .withHeader("Access-Control-Request-Headers", "Content-Type")
+    )
+    resp.statusCode shouldBe 200
+    resp.header.get("access-control-allow-origin") shouldBe Some("https://example.com")
+    resp.header.get("access-control-allow-methods") shouldBe Some("POST")
+    resp.header.get("access-control-allow-headers") shouldBe Some("Content-Type")
+    resp.header.get("access-control-allow-credentials") shouldBe Some("true")
+  }
+
+  test("add CORS headers to normal responses") { (client: SyncClient) =>
+    val resp = client.send(
+      Http
+        .POST("/wvlet.airframe.http.netty.CorsControllerTest.MyApi/hello")
+        .withJson("""{"msg":"World"}""")
+        .withHeader("Origin", "https://example.com")
+    )
+    resp.statusCode shouldBe 200
+    resp.contentString shouldBe "Hello World!"
+    resp.header.get("access-control-allow-origin") shouldBe Some("https://example.com")
+    resp.header.get("access-control-allow-credentials") shouldBe Some("true")
+  }
+}

airframe-http/.jvm/src/main/scala/wvlet/airframe/http/router/HttpRequestDispatcher.scala

@@ -18,6 +18,7 @@ import wvlet.airframe.codec.MessageCodecFactory
 import wvlet.airframe.http.*
 import wvlet.log.LogSupport
 
+import scala.annotation.tailrec
 import scala.concurrent.ExecutionContext
 import scala.language.higherKinds
 
@@ -30,7 +31,10 @@ object HttpRequestDispatcher extends LogSupport {
 
   case class RoutingTable[Req, Resp, F[_]](
       routeToFilterMappings: Map[Route, RouteFilter[Req, Resp, F]],
-      leafFilter: Option[HttpFilter[Req, Resp, F]]
+      leafFilter: Option[HttpFilter[Req, Resp, F]],
+      // Global filter chain extracted from the root of the Router tree.
+      // Applied before route matching so filters like CORS can intercept all requests.
+      globalFilter: Option[HttpFilter[Req, Resp, F]] = None
   ) {
     def findFilter(route: Route): RouteFilter[Req, Resp, F] = {
       routeToFilterMappings(route)
@@ -49,7 +53,8 @@ object HttpRequestDispatcher extends LogSupport {
     // Generate a table for Route -> matching HttpFilter
     val routingTable = buildRoutingTable(backend, session, router, backend.defaultFilter, controllerProvider)
 
-    backend.newFilter { (request: Req, context: HttpContext[Req, Resp, F]) =>
+    // Route dispatcher: matches requests to routes and applies route-specific filters
+    val routeDispatcher = backend.newFilter { (request: Req, context: HttpContext[Req, Resp, F]) =>
       router.findRoute(request) match {
         case Some(routeMatch) =>
           // Find a filter for the matched route
@@ -76,6 +81,11 @@ object HttpRequestDispatcher extends LogSupport {
           }
       }
     }
+
+    // Wrap with global filter so it runs before route matching.
+    // This allows filters like CORS to intercept requests (e.g., OPTIONS preflight)
+    // regardless of whether a route matches.
+    routingTable.globalFilter.map(_.andThen(routeDispatcher)).getOrElse(routeDispatcher)
   }
 
   /**
@@ -88,29 +98,56 @@ object HttpRequestDispatcher extends LogSupport {
       baseFilter: HttpFilter[Req, Resp, F],
       controllerProvider: ControllerProvider
   ): RoutingTable[Req, Resp, F] = {
+
+    def adaptFilter(router: Router): Option[HttpFilter[Req, Resp, F]] =
+      router.filterInstance
+        .orElse {
+          router.filterSurface.flatMap(fs => controllerProvider.findController(session, fs))
+        }
+        .map {
+          case rxFilter: RxHttpFilter =>
+            backend.rxFilterAdapter(rxFilter)
+          case legacyFilter: HttpFilter[Req, Resp, F] @unchecked =>
+            backend.filterAdapter(legacyFilter)
+          case other =>
+            throw RPCStatus.UNIMPLEMENTED_U8.newException(s"Invalid filter type: ${other}")
+        }
+
+    // Extract global filters from the root's linear single-child path.
+    // These filters wrap the entire dispatch so they run before route matching.
+    val (globalFilter, routeRoot) = {
+      @tailrec
+      def walk(
+          r: Router,
+          acc: Option[HttpFilter[Req, Resp, F]]
+      ): (Option[HttpFilter[Req, Resp, F]], Router) = {
+        val localFilter = adaptFilter(r)
+        val newAcc = (acc, localFilter) match {
+          case (Some(a), Some(lf)) => Some(a.andThen(lf))
+          case (None, Some(lf))    => Some(lf)
+          case (a, None)           => a
+        }
+
+        if (r.localRoutes.isEmpty && r.children.size == 1) {
+          // Single child with no routes — continue walking
+          walk(r.children.head, newAcc)
+        } else if (localFilter.isDefined) {
+          // Filter with routes or branching — extract filter, return node without it
+          (newAcc, r.copy(filterInstance = None, filterSurface = None))
+        } else {
+          (acc, r)
+        }
+      }
+      walk(rootRouter, None)
+    }
+
     val leafFilters = Seq.newBuilder[HttpFilter[Req, Resp, F]]
 
     def buildMappingsFromRouteToFilter(
         router: Router,
         parentFilter: HttpFilter[Req, Resp, F]
     ): Map[Route, RouteFilter[Req, Resp, F]] = {
-      val localFilterOpt: Option[HttpFilter[Req, Resp, F]] =
-        // Use a given filter instance or one created from the DI session
-        router.filterInstance
-          .orElse {
-            router.filterSurface
-              .map(fs => controllerProvider.findController(session, fs))
-              .filter(_.isDefined)
-              .map(_.get)
-          }
-          .map {
-            case rxFilter: RxHttpFilter =>
-              backend.rxFilterAdapter(rxFilter)
-            case legacyFilter: HttpFilter[Req, Resp, F] @unchecked =>
-              backend.filterAdapter(legacyFilter)
-            case other =>
-              throw RPCStatus.UNIMPLEMENTED_U8.newException(s"Invalid filter type: ${other}") //
-          }
+      val localFilterOpt = adaptFilter(router)
 
       val currentFilter: HttpFilter[Req, Resp, F] =
         localFilterOpt
@@ -139,14 +176,14 @@ object HttpRequestDispatcher extends LogSupport {
       m.result()
     }
 
-    val mappings = buildMappingsFromRouteToFilter(rootRouter, baseFilter)
+    val mappings = buildMappingsFromRouteToFilter(routeRoot, baseFilter)
 
     val lf = leafFilters.result()
     if (lf.size > 1) {
       warn(s"Multiple leaf filters are found in the router. Using the first one: ${lf.head}")
     }
 
-    RoutingTable(mappings, lf.headOption)
+    RoutingTable(mappings, lf.headOption, globalFilter)
   }
 
 }

docs/airframe-http.md

@@ -390,6 +390,53 @@ val router = RxRouter
 Using local variables inside filters will not work because the request processing will happen when Future[X] is evaluated, so we must use thead-local parmeter holder, which will be prepared for each request call.
 
 
+### CORS Filter
+
+airframe-http provides a built-in CORS filter for handling [Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). To use it, add the CORS filter to your router with `RxRouter.filter(...)`:
+
+```scala
+import wvlet.airframe.http.*
+import wvlet.airframe.http.filter.Cors
+import wvlet.airframe.http.netty.Netty
+
+@RPC
+class MyApi {
+  def hello(msg: String): String = s"Hello ${msg}!"
+}
+
+// Define a CORS policy
+val corsPolicy = Cors.Policy(
+  allowsOrigin = {
+    case origin if origin.endsWith(".mydomain.com") => Some(origin)
+    case _ => None
+  },
+  allowsMethods = _ => Some(Seq("GET", "POST")),
+  allowsHeaders = headers => Some(headers),
+  supportsCredentials = true
+)
+
+// Add the CORS filter to the router
+val router = RxRouter
+  .filter(Cors.newFilter(corsPolicy))
+  .andThen(RxRouter.of[MyApi])
+
+Netty.server
+  .withRouter(router)
+  .start { server =>
+    // Server handles CORS preflight (OPTIONS) and adds CORS headers to all responses
+  }
+```
+
+The CORS filter placed at the router level intercepts `OPTIONS` preflight requests before route matching, so it works correctly with `@RPC` and `@Endpoint` controller routes. For non-OPTIONS requests, it adds the appropriate CORS headers to responses.
+
+For development or testing, you can use the permissive policy that allows all origins (do not use in production):
+```scala
+val router = RxRouter
+  .filter(Cors.newFilter(Cors.unsafePermissivePolicy))
+  .andThen(RxRouter.of[MyApi])
+```
+
+
 ## Access Logs
 
 airframe-http stores HTTP access logs at `log/http-server.json` by default in JSON format. When the log file becomes large, it will be compressed with gz and rotated automatically.