Skip to content
v0.3

Overview

Register HTTP routes with inline handlers, controller classes, and prefixed route groups on host.http.

AI generated, pending review Updated 10 days ago · Flare 0.3

Routing is how inbound HTTP requests reach your code. On Flare, everything registers on host.http (or inside a route group via host.http.group). At host.build(), Flare compiles path matchers, merges methods per path into pipelines, and validates registrations.

Read these pages in order when wiring HTTP for the first time:

  1. Inline route handlers: host.http.get and friends, HttpRouteOptions, named inject maps.
  2. Controller classes: ControllerBase, decorators, static contract.
  3. Route groups and versioning: shared prefixes, per-version middleware and CORS.
  4. Routing behavior: matching, 404/405, HEAD, OPTIONS, wildcards, URL decoding.
  5. Custom 404 responses: catch-all wildcard routes.

Registration surface

Section titled “Registration surface”
APIPurpose
.get / .post / .put / .patch / .delete / .head / .optionsInline route handlers
.controller(prefix, Cls)Class-based controllers
.group(prefix, fn)Prefixed route groups; callback must return g.register()
.before / .after / .finallyInline middleware hooks
.use(Cls)Global MiddlewareBase class
.error(fn | Cls)Central HTTP error mapping
.cors(config)Arc-wide CORS policy
.onStart(fn) / .onStop(fn)Arc lifecycle hooks

There is no host.http.route or host.http.all helper. Register each HTTP method explicitly, or use multiple decorators on one controller class.

Two handler shapes

Section titled “Two handler shapes”

Flare supports inline functions and controller classes. Inline handlers read typed input from scope.input when the route options carry descriptor fields or a contract entry. Controllers use httpContract on the class and this.ctx.extract(entry) in methods.

Route groups

Section titled “Route groups”

host.http.group("/v1", (g) => { … return g.register(); }) applies a shared prefix to every route and controller registered inside the callback. The group builder exposes the same route, controller, middleware, and error registration methods as host.http (including .cors), plus g.isolated(), g.exclude([Cls]), and g.replace(from, to). Lifecycle hooks (onStart/onStop) and group itself exist only on host.http.

Groups do not nest. Use one group with a combined prefix (for example /api/v1) or register separate top-level groups.

Request path (overview)

Section titled “Request path (overview)”

At runtime the adapter builds a FlareHttpContext and calls host.http.fetch(ctx). Malformed inbound pathnames return 400 before routing. No match yields 404 with plain text Not Found. A path match with a disallowed method yields 405 and an Allow header.

Early exits (404, 405, 400, pre-build 503, and Node shutdown 503) skip middleware and host.http.error() handlers. Matcher tie-breaks, synthesized OPTIONS responses, and HEAD fallback are documented on Routing behavior.

Precedence is a property of the matcher, not of where a route sits in your file. A router that scans its table top to bottom makes the first matching pattern win, so moving a route can quietly change which handler serves a path, and two overlapping routes resolve to whichever was registered first with nothing said about it. Flare sorts by specificity instead (literals outrank parameters, which outrank wildcards), so a more specific route wins wherever you registered it, and registration order only settles a true tie. When two equal-specificity routes can match the same path, registration order settles that tie the same way on every request, but which route wins is invisible at the call site, so build() raises a ROUTE_PRIORITY_AMBIGUITY warning naming both routes and the winner rather than letting it surface in production.

Section titled “Related”