Route Groups Design

[SeanTAllen]

Route groups let you express shared middleware and path prefixes once for a set of routes, rather than attaching them to each route individually. This reduces the chance of accidentally leaving a route unprotected.

The problem

Today, shared middleware requires manual repetition per route:

let auth_mw: Array[hobby.Middleware val] val =
  recover val [as hobby.Middleware val: AuthMiddleware] end

hobby.Application
  .>get("/api/users", UsersHandler where middleware = auth_mw)
  .>post("/api/users", CreateUserHandler where middleware = auth_mw)
  .>get("/api/posts", PostsHandler where middleware = auth_mw)
  .>get("/health", HealthHandler)

Miss one auth_mw and a route is unprotected. The path prefix /api is also repeated on every route.

Implementation strategy: flatten at registration time

All approaches below share the same implementation: group middleware is prepended to per-route middleware, and the group prefix is prepended to the path, when routes are registered. The router, the radix tree, _ChainRunner, and _Connection are completely unchanged. Route groups are purely a registration-time convenience — by the time serve() builds the router, every route is a flat _RouteDefinition like it is today.

This means the feature has zero runtime cost and zero risk to the routing/execution path.

Three API approaches considered

Approach A: Enter/Exit (stateful stack)

hobby.Application
  .>begin_group("/api", auth_mw)
    .>get("/users", UsersHandler)
    .>post("/users", CreateUserHandler)
  .>end_group()
  .>get("/health", HealthHandler)
  .serve(auth, config, out)

Application maintains a stack of (prefix, middleware). begin_group pushes, end_group pops. Each route method reads the current stack to resolve the full path and middleware chain.

Pros: No new types. Clean syntax. Natural with .> chaining.

Cons: Forgetting end_group() silently applies the group's middleware and prefix to all subsequent routes — exactly the "accidentally leaving a route unprotected" problem, but in reverse (over-protecting/mis-pathing routes). serve() can check for unclosed groups at runtime, but the indentation in the example above is cosmetic — Pony's .> doesn't enforce scoping, so nothing structurally prevents the mistake.

Approach B: Lambda/callback

hobby.Application
  .>group("/api", auth_mw, {(g) =>
    g
      .>get("/users", UsersHandler)
      .>post("/users", CreateUserHandler)
  })
  .>get("/health", HealthHandler)
  .serve(auth, config, out)

group creates a builder internally, passes it to the lambda, then extracts the accumulated routes. The lambda is val (no captures needed), so auto-recovery works on the iso Application — all arguments (String, Array[...] val, lambda val) are sendable.

Pros: Scoped — forgetting to close is impossible. Familiar pattern from other frameworks.

Cons: The builder type must be public (it appears in the lambda's parameter type, and users outside the package can't reference private types). Nesting means nested lambdas, which gets deeply indented. The lambda syntax is heavier than .> chaining.

Approach C: RouteGroup object (recommended)

hobby.Application
  .>group(
    RouteGroup("/api", auth_mw)
      .>get("/users", UsersHandler)
      .>post("/users", CreateUserHandler)
  )
  .>get("/health", HealthHandler)
  .serve(auth, config, out)

RouteGroup is class iso with the same get/post/etc. methods as Application. Route methods prepend the group's prefix and middleware at registration time. Application's group method takes RouteGroup iso, consumes it, and copies the flattened routes into its own _routes array.

Auto-recovery works the same way it does for Application: RouteGroup is iso, its route methods are fun ref with all-sendable arguments, so .> chaining works. Application's group method takes RouteGroup iso (sendable), so auto-recovery works on the iso Application too.

Nesting:

hobby.Application
  .>group(
    RouteGroup("/api", auth_mw)
      .>get("/users", UsersHandler)
      .>group(
        RouteGroup("/admin", admin_mw)
          .>get("/dashboard", DashboardHandler)
      )
  )
  .>get("/health", HealthHandler)
  .serve(auth, config, out)

RouteGroup also has a group method. When the outer group consumes the inner group, it prepends its own prefix and middleware to each inner route. So /admin/dashboard with [AdminMW] becomes /api/admin/dashboard with [AuthMW, AdminMW].

Pure prefix grouping (no middleware, just organization):

hobby.Application
  .>group(
    RouteGroup("/api")
      .>get("/users", UsersHandler)
      .>post("/users", CreateUserHandler)
  )

The middleware parameter defaults to None.

Pros: Uses the exact same .> chaining pattern users already know. Scoped by construction — no unclosed-group risk. Nesting is natural (same group method). Composable — groups could be defined in separate functions and passed in. No capability concerns.

Cons: Adds one new public type (RouteGroup). Duplicates the HTTP method registration methods across Application and RouteGroup (can be shared internally via a private trait with default method implementations).

Why Approach C

It leverages the same iso + auto-recovery + .> chaining mechanism that Application already uses, so it feels like a natural extension rather than a new concept. The scoping is structural (group boundaries are object lifetime) rather than stateful (push/pop stack) or syntactic (lambdas). The enter/exit approach (A) has a silent failure mode that directly contradicts the stated goal. The lambda approach (B) works but is less idiomatic — Pony's .> chaining is the established registration pattern, and the lambda breaks that pattern.

Application-level middleware

Route groups address per-group middleware, but there's a related need: middleware that applies to every route in the application (e.g., request logging). Without application-level middleware, you'd need to wrap everything in a root group:

hobby.Application
  .>group(
    RouteGroup("/", log_mw)
      .>get("/health", HealthHandler)
      .>group(
        RouteGroup("/api", auth_mw)
          .>get("/users", UsersHandler)
      )
  )
  .serve(auth, config, out)

This works but makes Application's own get/post/etc. methods effectively useless — every route must live inside the outer group to get the global middleware.

An application-level middleware method solves this:

hobby.Application
  .>middleware(log_mw)
  .>get("/health", HealthHandler)
  .>group(
    RouteGroup("/api", auth_mw)
      .>get("/users", UsersHandler)
      .>post("/users", CreateUserHandler)
  )
  .serve(auth, config, out)

Routes registered directly on Application and routes inside groups all get log_mw prepended. The implementation is the same flatten-at-registration-time approach — serve() prepends the application middleware to every route's middleware chain before building the router.

What changes

• New: RouteGroup class (class iso, public)
• New: Application.group(g: RouteGroup iso) method
• New: Application.middleware(mw: Array[Middleware val] val) method
• Unchanged: _Router, _RouterBuilder, _BuildNode, _TreeNode, _ChainRunner, _Connection, _Listener, Context, Handler, Middleware

[SeanTAllen]

Path joining needs a spec

The design says "the group prefix is prepended to the path" but doesn't define joining rules. Simple concatenation breaks:

• RouteGroup("/api") + "/users" → /api/users (fine)
• RouteGroup("/api/") + "/users" → /api//users (broken)
• RouteGroup("/") + "/health" → //health (broken)

That last one is particularly relevant — the workaround example before application-level middleware uses RouteGroup("/", log_mw), which would produce double-slash paths.

Recommend: strip trailing slash from prefix during join (unconditionally — "/" → "", "/api/" → "/api"). Since route paths always start with /, this gives correct results in all cases.

Application.middleware() accumulation semantics

Can it be called multiple times? The chaining pattern (.>middleware(a).>middleware(b)) makes multiple calls natural. The design should specify: does a second call replace or accumulate? I'd recommend accumulate (append), since that's consistent with the additive registration pattern everywhere else in the API. Then the middleware runs in the order it was registered.

"What changes" is incomplete

The summary lists Application.group() but not RouteGroup.group(), which is needed for nesting and is shown in the nesting example. Also missing: RouteGroup.route() (the arbitrary-method variant that Application already has).

[SeanTAllen]

This was implemented in #10