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()| Request | Gana | Por qué |
|---|---|---|
GET /users/me | /users/me | primero se prueba un segmento static |
GET /users/42 | /users/:id | no hay static 42, así que se lo lleva el slot dynamic |
GET /users/a/b/c | /users/*path | má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 ✓ matchBacktracking
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()| Request | Resultado |
|---|---|
GET /a/x/c | deep: x — la rama dynamic llega hasta c y matchea |
GET /a/x/y | rest: 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()| Request | Respuesta |
|---|---|
GET /users/me | 200 |
POST /users/42 | 200 |
POST /users/me | 405 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.