# Enrutamiento Sin configuración, cada URL corresponde a un archivo del sitio: `/ventas/reporte.dkl` ejecuta `web//ventas/reporte.dkl`. El controlador `fastcgi/routing.dkl` permite cambiar esa correspondencia por sitio con cuatro archivos opcionales en la **carpeta protegida** (`_protected/`): | Archivo | Decide por | Para | |---|---|---| | `ext.map` | La extensión de la URL (y el método) | Que todas las URL `.api` o `.fso` las atienda un programa | | `routes.map` | El patrón de la URL, con parámetros | URL limpias tipo REST: `/clientes/27/reportes/ventas` | | `paths.map` | El patrón de la URL, con comodín | Carpetas virtuales: servir archivos que están fuera del sitio | | `routing.dk` | Código DKL | Lo que no se resuelve con los mapas | Se evalúan en ese orden y cada uno puede corregir lo que decidió el anterior. Si un archivo no existe, simplemente no se aplica. Todos los ejemplos de esta página se probaron con Devkron 2.0 detrás de nginx. ## Reglas comunes a los tres mapas - Son archivos de texto con **una regla por línea**: `[métodos:] patrón > destino`. - Las líneas que empiezan con `#` son comentarios. - **Métodos**: opcional; uno o varios separados por comas (`get`, `post, put`). `*`, `any` o no poner nada significa todos. - **Destino**: ruta relativa a la carpeta del sitio (`/_protected/servicios/eco.dkl` o `tienda/entry-point.dkl`), o **absoluta** si empieza con `$` (`$/etc/devkron/servicios/eco.dkl`). Un `$` seguido de una ruta relativa (`$fso/fso.*.dkl`) es relativa a la carpeta de trabajo del servidor, es decir, a la instalación de Devkron: así apuntan los sitios a los marcos de `/opt/devkron/fso/`. - Las comparaciones no distinguen mayúsculas y minúsculas (lo controla `@http_casesensitive` en `http.dkl`). - **Gana la primera regla que coincide**, en el orden del archivo. ## ext.map: por extensión ```text # _protected/ext.map .fso > $fso/fso.*.dkl post : .api > /_protected/servicios/*.dkl ``` El `*` del destino se sustituye por el **nombre del archivo pedido sin extensión**, sin importar la carpeta de la URL: | Petición | Programa que se ejecuta | |---|---| | `POST /eco.api` | `web//_protected/servicios/eco.dkl` | | `POST /cualquier/ruta/eco.api?x=1` | el mismo, con `request/get/x` = `1` | | `GET /eco.api` | ninguno: la regla es solo para POST, y como no existe `eco.api` responde 404 | | `GET /documentos/lst.fso` | `/opt/devkron/fso/fso.lst.dkl` (servicio de la [API FSO](/es/devkron/2.0/marcos/fso/)) | Ejemplos de especificación de métodos: ```text post, put : .api > servicios/servicio_api.dkl get : .api > servicios/servicio_api.dkl *: .api > servicios/servicio_api.dkl any: .api > servicios/servicio_api.dkl .api > servicios/servicio_api.dkl ``` Las tres últimas son equivalentes (todos los métodos). ## routes.map: por patrón de URL con parámetros Cada segmento del patrón es texto fijo o un **parámetro** entre llaves. Los valores de los parámetros se agregan a `request/get`, como si hubieran llegado en la cadena de consulta, para que su programa los lea igual en ambos casos: ```text # _protected/routes.map get : /api/clientes/{#id_cliente}/reportes/{id_reporte?} > /_protected/servicios/eco.dkl post,put : /api/clientes/{id_cliente} > /_protected/servicios/eco.dkl /tienda/{_entities_type}/{_entity_id?} > tienda/entry-point.dkl ``` | Marca | Significado | |---|---| | `{nombre}` | Parámetro obligatorio; acepta cualquier valor del segmento | | `{#nombre}` | Parámetro numérico: la regla solo coincide si el segmento es un número, y el valor llega como número | | `{nombre?}` | Parámetro opcional; solo tiene sentido en el **último** segmento | Con el programa `eco.dkl` que responde el método y `request/get`, estas son las respuestas reales: ```text GET /api/clientes/7/reportes/ventas → {"metodo":"GET","get":{"id_cliente":7,"id_reporte":"ventas"}, ...} PUT /api/clientes/A-27 → {"metodo":"PUT","get":{"id_cliente":"a-27"}, ...} GET /api/clientes/abc/reportes/x → 404 (abc no es número) DELETE /api/clientes/27 → 404 (ninguna regla admite DELETE) ``` Observe que `A-27` llegó como `a-27`: **el valor de los parámetros llega en minúsculas** cuando el enrutamiento no distingue mayúsculas (el valor predeterminado). Si su programa necesita el valor tal cual (códigos, folios, tokens), páselo en la cadena de consulta o active `@http_casesensitive=@true` en `http.dkl` (afecta a todos los sitios del servidor y hace que los patrones distingan mayúsculas). Si la URL trae en la cadena de consulta un parámetro con el mismo nombre que uno del patrón, el del patrón lo **sobrescribe**. Para separarlos, `http.dkl` define `@prefix_uri_params` (vacío de forma predeterminada): con `@prefix_uri_params="_r_"` el parámetro del patrón llega como `request/get/_r_id_cliente`. El ejemplo de `eco.dkl` es este: ```dkl #include "dkli.dkh" #! program "eco" { #include "functions.dkh" #include "serialize.dkh" new r { } r<"metodo">: @@(@http_context,"$request/headers/REQUEST_METHOD") r<"get*">: @@(@http_context,"&request/get") r<"programa">: @@(@http_context,"$request/headers/path_translated") @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(r) } ``` ## paths.map: carpetas virtuales Un **recurso virtual** es una URL que no corresponde a un archivo dentro del sitio. Con `paths.map` se publica una carpeta que está en otra parte (compartida entre sitios, en otro disco) sin copiarla: ```text # _protected/paths.map get : /manuales/* > $/srv/compartidos/manuales/* get : /documentos-oficiales/acta-asamblea.pdf > $/srv/actas/act01.pdf ``` El `*` final del patrón toma el resto de la URL y lo pega en el `*` del destino: | URL pedida | Archivo entregado | |---|---| | `/manuales/manual.txt` | `/srv/compartidos/manuales/manual.txt` | | `/manuales/2026/guia.pdf` | `/srv/compartidos/manuales/2026/guia.pdf` | | `/documentos-oficiales/acta-asamblea.pdf` | `/srv/actas/act01.pdf` | Si el destino es un `.dkl`, se ejecuta; si no, se entrega como archivo estático con el tipo que corresponda a su extensión. ## routing.dk: enrutamiento con código Cuando los mapas no bastan, escriba `_protected/routing.dk`. Se ejecuta después de los tres mapas y recibe la variable global **`@http_request`** (no `@http_context`) con lo que se decidió hasta ese momento; lo que usted cambie en ella es lo que se usa después: | Miembro de `@http_request` | Contenido | |---|---| | `host` | Nombre del host de la petición | | `uri` | URI de la petición unida a la carpeta del sitio | | `base_path` | Carpeta del sitio (`web/misitio.localhost`) | | `document_path` | Archivo que se va a entregar o ejecutar. Cámbielo para decidir qué responde el servidor | | `http_context` | El contexto de la petición hasta ese momento | Ejemplo: atender `/salud` (la URL que consultan los monitores) con un programa del sitio: ```dkl #include "dkli.dkh" #! module "routing.dk" { #include "functions.dkh" uri_solicitada = @@(@http_request, "$http_context/request/headers/REQUEST_URI") if findstr(uri_solicitada, "/salud") == 0 { @http_request<"document_path">: path.concat(@@(@http_request,"base_path"), "resp/texto.dkl") } } ``` ```text GET /salud → 200, "Hola mundo (enviado como texto plano)" ``` Mantenga `routing.dk` rápido: se ejecuta en **todas** las peticiones del sitio, incluidas las de archivos estáticos. ## La carpeta protegida `_protected/` (nombre configurable con `@http_protected_dir` en `http.dkl`) guarda la configuración del sitio: `ext.map`, `routes.map`, `paths.map`, `routing.dk`, `auth.dk`, `render.dk`, los proveedores de identidad en `idp/` y los programas que solo deben ejecutarse por una regla de enrutamiento. En la distribución, el controlador **no restringe** el acceso directo a esa carpeta (`@http_restrict_protected_dir=@false` en `fastcgi/http.dkl`): con ese valor, `GET /_protected/routes.map` entrega el contenido del mapa. Para que cualquier URL que empiece con `/_protected/` responda "Acceso prohibido", cambie el valor en la copia de `http.dkl` de su servidor: ```dkl @http_restrict_protected_dir=@true // @true - Restringir acceso a la carpeta protegida ``` Comprobado en 2.0: con `@true`, `GET /_protected/ext.map` y `GET /_protected/auth.dk` responden 500 con el mensaje `Acceso prohibido`, y las reglas de `routes.map` y `ext.map` que apuntan a programas de `_protected/` siguen funcionando, porque la restricción revisa la URL pedida, no el archivo que se ejecuta. ## Errores típicos | Síntoma | Causa y solución | |---|---| | La regla no se aplica | Una regla anterior coincidió primero, o el método no está en la lista. Ordene de lo más específico a lo más general | | 404 con una regla correcta de `ext.map` | El método de la petición no está en la regla (`post : .api` no atiende GET) | | El parámetro llega en minúsculas | El enrutamiento no distingue mayúsculas: lea el valor de la cadena de consulta o active `@http_casesensitive` | | El parámetro de la URL "pisa" uno de la consulta | Use `@prefix_uri_params` | | `Variable global '@http_request' no definida` | Se pidió `routing.dk` o `auth.dk` directamente por su URL; solo el controlador debe ejecutarlos. Restrinja la carpeta protegida | | Un `.fso` responde 404 | Falta la regla `.fso > $fso/fso.*.dkl` en `ext.map` o el destino no apunta a la carpeta `fso/` de la instalación |