# Programas y sitios en Devkron Edge Esta página explica cómo se escribe un conector para `dkle`: la forma de un programa, cómo llegan las peticiones, cómo se responde y cómo se usan la configuración, la caché, las llamadas salientes y la bitácora. El lenguaje es el de Devkron 2.0: si no lo conoce, empiece por la [Referencia del lenguaje](/es/devkron/2.0/lenguaje/). ## La forma de un programa ```dkl #include "dkli.dkh" #! program "mi conector" { #include "edge.dkh" // su código do httpres.json(resultado) } ``` - `dkli.dkh` (las sentencias del lenguaje) y `edge.dkh` (la biblioteca Edge) vienen **integrados** en `dkle`: no hay archivos que copiar. Las líneas `#include` se escriben igual, para que el mismo programa corra también en Devkron 2.0 y porque `dkle check` avisa si falta `edge.dkh`. - Puede incluir sus propios encabezados `.dkh` (funciones comunes de sus conectores), siempre que estén **dentro de la carpeta del sitio**: `#include "lib/shopify.dkh"`. Un `#include` fuera del sitio, o de las bibliotecas de Devkron 2.0 (`functions.dkh`, `http.dkh`, `dbr.dkh`…), da error: en Edge todo eso ya está en `edge.dkh` o no existe. - `print` no escribe en la respuesta: en `dkle` va a la **bitácora** (nivel `print`), útil para depurar. La respuesta se arma con `httpres.*`. ## Rutas Cada carpeta `web//` es un sitio y se elige por el encabezado `Host` de la petición (en minúsculas y sin el puerto). Dentro del sitio: - **URL directa:** un `.dkl` responde por su ruta: `web//pedidos/nuevo.dkl` atiende `/pedidos/nuevo.dkl`. Una carpeta responde con su `index.dkl` o `default.dkl`. - **`_protected/routes.map`:** rutas limpias y con parámetros, con el mismo formato de Devkron 2.0. Cada línea es `MÉTODOS:patrón > programa`; `*` acepta cualquier método y `#` inicia un comentario: ``` POST:/webhooks/shopify/{tienda} > webhooks/shopify.dkl GET:/tiendas/{tienda}/pedidos/{#id} > pedidos/consultar.dkl GET,POST:/tareas/{nombre?} > tareas/ejecutar.dkl ``` `{nombre}` es un segmento, `{#nombre}` un segmento numérico (si no es número, la ruta no coincide) y `{nombre?}` uno opcional, solo al final (si falta, llega vacío). Los parámetros llegan junto con los de la consulta y se leen con `httpreq.arg`: ```dkl tienda = httpreq.arg("tienda") id = httpreq.arg("id") ``` - `_protected/ext.map` y `_protected/paths.map` funcionan como en Devkron 2.0. `_protected/routing.dk` no se admite. - `dkle` **no entrega archivos estáticos** (`.html`, `.js`, imágenes) ni nada de `_protected/`: una ruta que no resuelve a un `.dkl` responde 404. ## La petición Los datos de la petición están en `@http_context`, con la misma forma que en Devkron 2.0, y se leen con `httpreq.*` (referencia en [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md)): | Para | Use | |---|---| | Un parámetro de la consulta, del formulario o de la ruta | `httpreq.arg("id")`, `httpreq.darg("id", "pred")`, `httpreq.num("n")` | | El cuerpo como texto o como JSON | `httpreq.body()`, `ref p = httpreq.json()` | | El cuerpo binario, en base64 | `httpreq.body_b64()` (solo en `dkle`) | | Un encabezado o una cookie | `httpreq.header("X-Firma")`, `httpreq.cookie("sesion")` | | Método, host, ruta, IP | `httpreq.method()`, `httpreq.host()`, `httpreq.path()`, `httpreq.ip()` | | Credenciales | `httpreq.bearer()`, `httpreq.basic()` | `httpreq.path()` es la ruta pedida sin la consulta y **sin decodificar** (`/a%20b?q=1` da `/a%20b`), para poder compararla con la que firmó un tercero. `httpreq.ip()` es la IP real del cliente: los encabezados `X-Forwarded-*` solo se aceptan de los `trusted_proxies` declarados en `dkle.json`. A diferencia de Devkron 2.0, `@http_context` **no** trae las variables de entorno del proceso entre los encabezados: las variables se leen con `env.get` y solo las que el sitio tiene autorizadas. ## La respuesta | Para | Use | |---|---| | Responder JSON o texto | `httpres.json(registro)`, `httpres.text("ok")` | | Código de estado | `httpres.status(201)` | | Encabezados | `httpres.header("Cache-Control", "no-store")`, `httpres.content_type("text/csv")` | | Redirigir | `httpres.redirect(url)` | | CORS, sin caché | `httpres.cors("*")`, `httpres.no_cache()` | | Cookies | `httpres.cookie(…)`, `httpres.del_cookie(nombre)` | | Un archivo generado en memoria | `httpres.binary_b64(b64, "application/pdf", "factura.pdf")` | Cada respuesta lleva `X-Request-Id`: el mismo identificador de la línea de bitácora de la petición. Si la petición ya trae `X-Request-Id`, se conserva. ## Errores Un error no manejado responde **500** en JSON, con el identificador de la petición; el mensaje completo queda en la bitácora: ```json {"error":"error interno","id":"9c72800030ac16cb4af9900b","status":500} ``` Para responder otra cosa, maneje el error con `exception`, como en Devkron 2.0. Tenga presente que una respuesta 4xx o 5xx de otro sistema **no** es un error: se revisa con `http.status()`. Sí son errores la falta de conexión, el tiempo agotado, un destino no permitido o una respuesta que no es JSON: ```dkl ref r = http.get_json(config.get("erp_url") + "/clientes/" + id, @null) if http.status() != 200 { do log.warn("ERP respondió " + str(http.status())) do httpres.status(502) new e {$$ "error": "el ERP no está disponible" $$} do httpres.json(e) return 0 } do httpres.json(r) exception { do log.error("ERP sin conexión: " + last_error()) do httpres.status(502) new e {$$ "error": "el ERP no está disponible" $$} do httpres.json(e) } ``` Con `"debug": true` en la configuración del sitio, el detalle del error viaja también en la respuesta (`"detalle"`). Para respuestas 404 y 500 propias, use `errors` (ver [Configuración](/es/devkron/2.0/dkle/configuracion.md)). Un error de sintaxis también es un 500 al pedir la página; `dkle check` lo encuentra antes de publicar. ## Bitácora `dkle` escribe una línea JSON por evento en la salida estándar. Con `systemd` queda en `journalctl`; en contenedores, en el registro del contenedor: ```json {"t":"2026-11-01T15:54:09Z","sitio":"conector.localhost","nivel":"info","msg":"evento evt_1001 procesado"} {"t":"2026-11-01T15:54:09.075Z","sitio":"conector.localhost","nivel":"info","msg":"petición","id":"8a154700f689dc077103c705","metodo":"POST","ruta":"/webhooks/proveedor","estado":200,"ms":21.252} ``` Desde el programa, `log.info(msg)`, `log.warn(msg)`, `log.error(msg)`, `log.write(nivel, msg)` y `log.json(registro)`, este último con el registro como JSON en `msg`. Las peticiones se registran solas (desactívelo con `"log": {"requests": false}` en `dkle.json`); un 4xx sale con nivel `warn` y un 5xx con `error`. ## Configuración y secretos ```dkl url = config.get("erp_url") zona = config.dget("zona", "America/Mexico_City") clave = env.get("ERP_CLAVE") ``` `config.get` lee la sección `app` de `_config/.dkle.json`; `env.get`, solo las variables de entorno que esa configuración autoriza en `env`. Las dos se recargan en caliente y cada sitio ve solo lo suyo. Detalle en [Configuración](/es/devkron/2.0/dkle/configuracion.md). ## Caché y candados Cada sitio tiene su propia memoria con caducidad (`cache.*`) y sus propios candados (`threads.lock`): dos sitios pueden usar la misma llave sin pisarse. La memoria es **volátil**: se pierde al reiniciar `dkle`. ```dkl // El catálogo de sucursales cambia poco: se pide al ERP solo si no está en la caché (10 minutos) if not(cache.has("sucursales")) { ref s = http.get_json(config.get("erp_url") + "/sucursales", @null) do cache.set("sucursales", s, 600) } ref sucursales = cache.obj("sucursales") ``` Los tokens de OAuth no necesitan esto: `oauth.client_credentials` ya reutiliza el token mientras no caduque. Para leer, modificar y escribir sin que dos peticiones se encimen, use las operaciones atómicas o un candado: | Caso | Use | |---|---| | Procesar un webhook una sola vez aunque el proveedor lo reenvíe | `cache.set_nx("evento:" + id, "1", 86400)` devuelve `@false` si ya existía | | Un contador o un consecutivo | `cache.incr("folio", 1, 0)` | | Un tramo de código que no debe correr dos veces a la vez | `threads.lock("sincronizar", 5000)` … `threads.unlock("sincronizar")` | Un candado que el programa no libera se libera solo al terminar la ejecución, con un aviso en la bitácora. Referencia en [Funciones nuevas](/es/devkron/2.0/dkle/funciones-nuevas.md) y en [threads.dkh](/es/devkron/2.0/bibliotecas/estandar/threads.md). ## Llamadas a otros sistemas El cliente HTTP es el de [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md) de Devkron 2.0: `http.get_json`, `http.post_json`, `http.call`, `http.post_form`, `http.text` y `http.parallel`, con `http.status()` para el código de la última respuesta. Además: - `http.response_headers()` devuelve los encabezados de la última respuesta (por ejemplo `Retry-After`). - `http.forward_headers("X-Request-Id, Authorization")` toma esos encabezados de la petición recibida, listos para reenviarlos. - Solo se puede llamar a los destinos que permite `outbound`, y cada respuesta recibida tiene el tope `max_response_kb`. - **No hay reintentos automáticos**: si el destino responde 429 o 503, el conector decide si espera (`threads.sleep`) y reintenta. ```dkl // Reenviar el pedido al ERP con el mismo identificador de petición token = oauth.client_credentials(config.get("token_url"), config.get("cliente"), env.get("ERP_CLAVE"), "") ref enc = http.forward_headers("X-Request-Id") enc<"Authorization">:"Bearer " + token ref r = http.post_json(config.get("erp_url") + "/pedidos", enc, pedido) if http.status() == 429 { do log.warn("ERP saturado, reintentar en " + field.dstr(http.response_headers(), "Retry-After", "?") + " s") } ``` ## Tareas periódicas `dkle` no tiene programador interno: el del sistema operativo llama por HTTP a una ruta del sitio, así la tarea comparte la caché, los tokens y la configuración del conector. Marque la ruta como local para que nadie más la pueda llamar: ```json { "local_only": ["/tareas/*"] } ``` ``` # crontab: cada 15 minutos */15 * * * * curl -fsS -X POST -H "Host: conectores.ejemplo.com" http://127.0.0.1:8080/tareas/sincronizar >/dev/null ``` Si una tarea puede durar más que el intervalo, protéjala con `cache.set_nx` o `threads.lock` para que no corran dos a la vez. ## Concurrencia Un mismo `.dkl` atiende muchas peticiones a la vez. Cada petición tiene su propio contexto: variables, globales `@`, objetos, `@http_context`, errores y `http.status()`. Entre peticiones solo se comparte lo que se pone en `cache.*`. El número de peticiones simultáneas de cada sitio lo limita `max_concurrent`. ## Cambios en caliente Al cambiar un `.dkl`, un `.dkh` incluido, un archivo de rutas o la configuración del sitio, la siguiente petición usa la versión nueva; las que están en curso terminan con la anterior. `dkle` espera a que el archivo deje de cambiar antes de cargarlo, así que copiar un archivo grande no produce una carga a medias. Para publicar varios archivos a la vez sin estados intermedios, haga que `web/` sea un enlace simbólico a la carpeta de la versión y cámbielo de un golpe al publicar: ``` cp -r conector-v2 /opt/dkle/versiones/conector-v2 ln -sfn /opt/dkle/versiones/conector-v2 /opt/dkle/web/conectores.ejemplo.com.nuevo mv -T /opt/dkle/web/conectores.ejemplo.com.nuevo /opt/dkle/web/conectores.ejemplo.com ``` Para volver atrás, se apunta el enlace a la versión anterior de la misma forma.