ArctonArcton
Routing

Route Precedence

Which route wins when several could match, how backtracking works, and why a method mismatch stops the search.

When more than one route could match a request, Arcton follows two rules: static beats dynamic beats wildcard, applied one segment at a time, with backtracking when a branch dead-ends.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/me', () => 'the current user')
app.get('/users/:id', ctx => `user ${ctx.params.id}`)
app.get('/users/*path', ctx => `anything else: ${ctx.params.path}`)

app.listen()
RequestWinsWhy
GET /users/me/users/mea static segment is tried first
GET /users/42/users/:idno static 42, so the dynamic slot takes it
GET /users/a/b/c/users/*pathmore segments than :id can hold

Registration order does not matter. Moving /users/me to the bottom of the file changes nothing — precedence is a property of the path, not of when you wrote it.

Matching walks the path

Arcton stores routes in a tree, one node per segment. At each node it tries the static child first, then the dynamic slot, then the wildcard slot.

For GET /users/42 against the routes above:

/users/42
  ├─ "users"  → static child exists          ✓ descend
  └─ "42"     → static child "me"?           ✗
               dynamic slot ":id"?           ✓ capture id="42", descend
               node has a GET handler        ✓ match

Backtracking

If a branch matches for a while and then dead-ends, Arcton backs out and tries the next slot at the point where it still had options, discarding whatever parameters that abandoned branch captured.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/a/:b/c', ctx => `deep: ${ctx.params.b}`)
app.get('/a/*rest', ctx => `rest: ${ctx.params.rest}`)

app.listen()
RequestResult
GET /a/x/cdeep: x — the dynamic branch reaches c and matches
GET /a/x/yrest: x/y — y is not c, so matching backs out to the wildcard

The b captured on the way into the abandoned branch is discarded, so the handler that finally runs never sees a parameter from a path that did not match.

Backtracking applies to paths, not to methods. Once matching reaches a node that has handlers, that node answers — with the handler for this method if it has one, and with 405 if it does not. Arcton does not keep looking for another path pattern that happens to support the method.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/me', () => 'the current user')
app.post('/users/:id', ctx => `updated ${ctx.params.id}`)

app.listen()
RequestResponse
GET /users/me200
POST /users/42200
POST /users/me405 with Allow: GET

POST /users/me reaches the /users/me node, which only answers GET, so it returns 405 — even though /users/:id would have accepted the POST.

The most specific path that matches is the one that answers. If a static path should accept the same methods as the dynamic route beside it, register those methods on the static path too.

Making the example above answer both:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/me', () => 'the current user')
app.post('/users/me', () => 'updated the current user')
app.post('/users/:id', ctx => `updated ${ctx.params.id}`)

app.listen()

No match at all

When no path in the tree matches, the response is 404 with a { code: 'NOT_FOUND', message: 'Not Found' } JSON body — see HTTP errors. Global middleware still runs on it, which is how logging and CORS headers reach those responses — see Global middleware.

Wildcards need something to capture

A wildcard matches one or more segments, never zero:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/files', () => 'the index')
app.get('/files/*path', ctx => `file: ${ctx.params.path}`)

app.listen()

Without that first route, GET /files would be a 404, because *path has nothing to capture.

On this page