ArctonArcton
Enrutamiento

Route Precedence

Qué ruta gana cuando varias podrían matchear, cómo funciona el backtracking, y por qué un método que no coincide corta la búsqueda.

Cuando más de una ruta podría matchear un request, Arcton sigue dos reglas: static gana a dynamic gana a wildcard, aplicadas un segmento a la vez, con backtracking cuando una rama llega a un callejón sin salida.

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()
RequestGanaPor qué
GET /users/me/users/meprimero se prueba un segmento static
GET /users/42/users/:idno hay static 42, así que se lo lleva el slot dynamic
GET /users/a/b/c/users/*pathmás segmentos de los que :id puede contener

El orden de registro no importa. Mover /users/me al final del archivo no cambia nada — la precedencia es una propiedad del path, no de cuándo lo escribiste.

El matching recorre el path

Arcton guarda las rutas en un árbol, un nodo por segmento. En cada nodo prueba primero el hijo static, después el slot dynamic, después el slot wildcard.

Para GET /users/42 contra las rutas de arriba:

/users/42
  ├─ "users"  → existe un hijo static         ✓ desciende
  └─ "42"     → ¿hijo static "me"?            ✗
               ¿slot dynamic ":id"?           ✓ captura id="42", desciende
               el nodo tiene un handler GET   ✓ match

Backtracking

Si una rama matchea por un tiempo y después llega a un callejón sin salida, Arcton retrocede y prueba el siguiente slot en el punto donde todavía tenía opciones, descartando los parámetros que esa rama abandonada haya capturado.

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()
RequestResultado
GET /a/x/cdeep: x — la rama dynamic llega hasta c y matchea
GET /a/x/yrest: x/y — y no es c, así que el matching retrocede hacia el wildcard

La b capturada al entrar en la rama abandonada se descarta, así que el handler que finalmente corre nunca ve un parámetro de un path que no matcheó.

Un método que no coincide termina la búsqueda

El backtracking aplica a paths, no a métodos. Una vez que el matching llega a un nodo que tiene handlers, ese nodo responde — con el handler para este método si lo tiene, y con 405 si no lo tiene. Arcton no sigue buscando otro patrón de path que resulte soportar el método.

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()
RequestRespuesta
GET /users/me200
POST /users/42200
POST /users/me405 con Allow: GET

POST /users/me llega al nodo /users/me, que solo responde GET, así que retorna 405 — aunque /users/:id hubiera aceptado el POST.

El path más específico que matchea es el que responde. Si un path static debería aceptar los mismos métodos que la ruta dynamic de al lado, registra esos métodos también en el path static.

Haciendo que el ejemplo de arriba responda a ambos:

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()

Ningún match

Cuando ningún path del árbol matchea, la respuesta es 404 con un body JSON { code: 'NOT_FOUND', message: 'Not Found' } — ver HTTP errors. El middleware global igual corre sobre ella, que es como los headers de logging y CORS llegan a esas respuestas — ver Global middleware.

Los wildcards necesitan algo que capturar

Un wildcard matchea uno o más segmentos, nunca cero:

import { Arcton } from '@arcton/core'

const app = Arcton()

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

app.listen()

Sin esa primera ruta, GET /files sería un 404, porque *path no tiene nada que capturar.

En esta página