# http.dkh: cliente HTTP, petición recibida y respuesta `http.dkh` reúne en un encabezado las tres caras de HTTP en Devkron 2.0: - **`http.*`**: cliente para llamar a otros servicios (JSON, formularios, texto, archivos, peticiones en paralelo). Complementa a `webcl.dkh` (`http.get`, `http.post`, `http.request`…), que sigue igual; puede incluir los dos. - **`httpreq.*`**: lectura de la **petición recibida** (parámetros, encabezados, cuerpo JSON, archivos, autenticación). - **`httpres.*`**: armado de la **respuesta** (código, encabezados, JSON, descargas, cookies, CORS). `httpreq.*` y `httpres.*` son DKL sobre `@http_context`. Solo el cliente usa `Devkron.Ext.Http.dll`. Todo viene con la distribución. Incluya antes `functions.dkh` y `serialize.dkh`. ## Cuándo usarla - Servicios JSON detrás de nginx con el servidor FastCGI de Devkron. - Consumir API de terceros (pagos, timbrado, mensajería) que hablan JSON o formularios. - Validar quién llama a su servicio con `Authorization: Bearer` o `Basic`. `httpreq.*` y `httpres.*` solo tienen sentido dentro del servidor FastCGI, donde existe `@http_context`. El cliente `http.*` funciona también en consola. ```dkl #include "http.dkh" ``` ## Cliente: http.* | Función | Devuelve | Descripción | |---|---|---| | `http.get_json(url, encabezados)` | registro | GET y convierte la respuesta JSON en registro | | `http.post_json(url, encabezados, objeto)` | registro | POST con el objeto en JSON (`Content-Type: application/json`) | | `http.call(metodo, url, encabezados, objeto)` | registro | `PUT`, `PATCH`, `DELETE` u otro método con JSON; `objeto` en `@null` = sin cuerpo | | `http.post_form(url, encabezados, campos)` | registro | POST con los campos del registro como `application/x-www-form-urlencoded`; respuesta JSON | | `http.text(metodo, url, encabezados, cuerpo)` | cadena | Cualquier método; devuelve el texto de la respuesta. `cuerpo`: cadena, registro/lista (se envía como JSON) o `@null` | | `http.post_multipart(url, encabezados, archivos, campos)` | cadena | Envía archivos (`{campo: ruta}`) y campos (`{nombre: valor}`) como `multipart/form-data` | | `http.parallel(peticiones, n)` | número | Ejecuta varias peticiones, máximo `n` a la vez; devuelve cuántas respondieron 2xx | | `http.status()` | número | Código HTTP de la última llamada **de este hilo** | | `http.bearer(token)` | registro | Encabezados `{Authorization: "Bearer …"}` | | `http.basic(usuario, contrasena)` | registro | Encabezados `{Authorization: "Basic …"}` (UTF-8, base64) | - `encabezados` es un registro `{nombre: valor}` o `@null`. Los de `http.bearer` y `http.basic` son registros normales: puede agregarles más campos. - El encabezado especial `__timeout` fija el tiempo máximo en milisegundos (100 000 por omisión); no se envía. - **Un código de error HTTP (404, 500) no lanza error**: revise `http.status()`. Sí lanzan error la falta de conexión, el tiempo agotado y, en las funciones que devuelven registro, una respuesta que no es JSON. Una respuesta vacía da un registro vacío. - En `http.parallel`, `peticiones` es una lista de registros `{url, method, headers, payload}`. Cada registro recibe `status`, `response` (cuerpo como texto), `success` (1 si fue 2xx) y `error` (mensaje si no hubo respuesta). ### Ejemplo: cliente contra una API El ejemplo usa un servidor de prueba local (`/eco` devuelve lo recibido, `/status/N` responde con el código N, `/lento` tarda 2 segundos): ```dkl #include "dkli.dkh" #! program "cliente" { #include "functions.dkh" #include "serialize.dkh" #include "http.dkh" base = "http://127.0.0.1:19580" ref h = http.bearer("mi_token_de_ejemplo") h<"X-Prueba">: "uno" new pedido { @"cliente": "C-001" @"total": 1500.75 } ref r = http.post_json(base + "/eco", h, pedido) do print(str(http.status()) + " " + field.str(r, "method") + " " + field.str(r, "ctype") + " " + field.str(r, "body")) ref r2 = http.call("DELETE", base + "/eco?id=7", h, @null) do print(str(http.status()) + " " + field.str(r2, "method") + " " + field.str(r2, "query")) new campos { @"grant_type": "client_credentials" @"client_secret": "s3cr3t" } ref t = http.post_form(base + "/token", @null, campos) do print("form: " + to.json(t)) // Un 404 o un 500 no lanzan error: revise http.status() ref e = http.get_json(base + "/status/404", @null) do print("status: " + str(http.status()) + " " + to.json(e)) do print("texto: " + http.text("GET", base + "/texto", @null, @null)) new archivos { @"xml": "factura.xml" } new mas { @"rfc": "XAXX010101000" } do print("multipart: " + http.post_multipart(base + "/upload", http.basic("mi_usuario", "MiClave#2026"), archivos, mas)) ref pet = list.create() for i=1; i<=5 { new p { @"url": base + "/status/" + ifstr(i == 3, "500", "200") @"method": "GET" } do list.add(pet, p) } ok = http.parallel(pet, 3) do print("parallel: " + str(ok) + " de " + str(list.count(pet)) + " con 2xx; la 3a: " + str(field.num(list.obj(pet, 2), "status")) + " success=" + str(field.num(list.obj(pet, 2), "success"))) new lento { @"__timeout": 500 } x = http.get_json(base + "/lento", lento) exception { do print(last_error()) } } ``` Salida: ``` 200 POST application/json; charset=utf-8 {"cliente":"C-001","total":1500.75} 200 DELETE id=7 form: {"access_token":"cc-1","expires_in":3600,"scope":""} status: 404 {"code":404} texto: hola ñ multipart: rfc=XAXX010101000;xml=archivo:factura.xml:7 parallel: 4 de 5 con 2xx; la 3a: 500 success=0 {1} Error en 'http.get_json. (http.get_json: se agotó el tiempo de espera (500 ms) con http://127.0.0.1:19580/lentoException has been thrown by the target of an invocation.) [cliente.dkl][Ln= 56] ``` ### Errores del cliente | Mensaje | Causa | |---|---| | `http.get_json: no se pudo conectar con … (Connection refused)` | El servidor no responde, error de DNS o de certificado | | `http.get_json: se agotó el tiempo de espera (N ms) con …` | Pasó `__timeout` | | `http.get_json: la respuesta (HTTP 200) no es JSON: …` | La respuesta no es JSON (use `http.text`) | | `http.post_multipart: no existe el archivo '…' (campo '…')` | Ruta de archivo equivocada | | `http.parallel: las peticiones deben ser una lista de registros` / `… falta 'url' en una petición` | Lista mal armada | | `http.get_json: no se indicó la URL` / `… los encabezados debe ser un registro` | Argumentos inválidos | El prefijo cambia según la función (`http.post_json:`, `http.call:`…). ### El cliente no reintenta Todo el proceso usa un solo cliente: las conexiones se reutilizan y es seguro entre hilos. **No reintenta por su cuenta.** Contra un servidor que cierra las conexiones sin avisar (HTTP/1.0, algunos equipos intermedios), una petición puede fallar con `The response ended prematurely`. Si la operación se puede repetir sin efectos (un GET, una consulta), reintente usted en DKL. No reintente a ciegas un POST que crea algo, como un pedido o un cobro. ## Petición recibida: httpreq.* Nunca fallan porque falte una sección: devuelven vacío. | Función | Devuelve | Descripción | |---|---|---| | `httpreq.get()` / `httpreq.post()` / `httpreq.headers()` / `httpreq.cookies()` | registro | Esa sección de la petición (vacía si no viene) | | `httpreq.files()` | lista | Archivos subidos: `[{filename, temp_file, size, field}]` | | `httpreq.arg(nombre)` / `httpreq.darg(nombre, predeterminado)` | cadena | Valor de POST o, si no viene, de GET; `""` o el predeterminado | | `httpreq.num(nombre)` / `httpreq.dnum(nombre, predeterminado)` | número | Igual, como número; `0` o el predeterminado si no viene o no es número | | `httpreq.has(nombre)` | lógico | Si viene en POST o GET | | `httpreq.header(nombre)` | cadena | Encabezado escrito en cualquier forma: `host`, `User-Agent` o `HTTP_HOST` | | `httpreq.cookie(nombre)` | cadena | Valor de la cookie; `""` si no viene | | `httpreq.body()` | cadena | Cuerpo crudo | | `httpreq.json()` | registro | Cuerpo JSON como registro; vacío si no hay cuerpo | | `httpreq.method()` / `httpreq.is_post()` | cadena / lógico | `GET`, `POST`… en mayúsculas | | `httpreq.host()` / `httpreq.uri()` / `httpreq.url()` | cadena | Host; ruta y consulta; URL completa con esquema | | `httpreq.is_https()` | lógico | Por `HTTPS`, `REQUEST_SCHEME` o `X-Forwarded-Proto` (nginx) | | `httpreq.ip()` | cadena | Primera IP de `X-Forwarded-For`; si no viene, `REMOTE_ADDR` | | `httpreq.user_agent()` | cadena | Navegador o programa cliente | | `httpreq.auth_scheme()` | cadena | `Basic`, `Bearer` (u otro, tal como viene) o `""` | | `httpreq.bearer()` | cadena | Token de `Authorization: Bearer …`; `""` si no hay | | `httpreq.basic()` | registro o nulo | `{user, password}` de `Authorization: Basic …`; nulo si no viene | | `httpreq.file(campo)` | registro o nulo | Archivo subido en ese campo | | `httpreq.save_file(campo, ruta)` | — | Copia el archivo subido a `ruta`; error si no vino | El archivo temporal de una subida se borra al terminar la petición. Si lo necesita, guárdelo antes con `httpreq.save_file`. ## Respuesta: httpres.* | Función | Descripción | |---|---| | `httpres.status(codigo)` | Código HTTP de la respuesta | | `httpres.header(nombre, valor)` / `httpres.content_type(tipo)` | Encabezado de respuesta | | `httpres.redirect(url)` | `Location` y código 302 | | `httpres.text(texto)` | Responde con texto | | `httpres.json(objeto)` | Responde con el objeto en JSON (`application/json;charset=utf-8`) | | `httpres.ok(datos)` | `{"success":true,"data":…}` **con HTTP 200** (un formato de respuesta común en API JSON). `datos`: registro, lista o cadena; un número, como `str(n)` o dentro de un registro | | `httpres.fail(mensaje)` | `{"success":false,"message":"…"}` **con HTTP 200** | | `httpres.binary(bytes, tipo, nombre_descarga)` | Descarga de un arreglo de bytes; nombre `""` = se muestra en el navegador | | `httpres.file(ruta, tipo, nombre_descarga)` | Descarga de un archivo del disco; error si no existe | | `httpres.cors(origen)` | `Access-Control-Allow-Origin`, `-Methods` y `-Headers` | | `httpres.no_cache()` | `Cache-Control`, `Pragma` y `Expires` para que no se guarde la respuesta | | `httpres.require_basic(realm)` | 401 con `WWW-Authenticate: Basic` y devuelve `@true`; fuera de HTTPS (salvo `localhost`, `*.localhost` y `127.0.0.1`) responde 403 y devuelve `@false` | | `httpres.cookie(nombre, valor, dias)` | Cookie con `Path=/` y `Max-Age` (`0` días = de sesión); sustituye a `cookie.set` de `dkl-web` | | `httpres.cookie_raw(nombre, valor_con_atributos)` | Cookie con atributos escritos a mano (`v;Path=/;HttpOnly;Secure`); sustituye a `cookie.setw` | | `httpres.del_cookie(nombre)` | Borra una cookie (`Max-Age=0`) | **`httpres.ok` y `httpres.fail` fijan el código 200.** Si quiere responder 401, 400 o 500 con ese formato, llame a `httpres.status` **después**. ## Ejemplo: un servicio JSON `clientes.dkl`, el controlador de un servidor FastCGI: lista o da de alta clientes, con token Bearer y CORS. Para que el ejemplo no dependa de una base, los clientes se guardan en el caché del proceso ([threads.dkh](/es/devkron/2.0/bibliotecas/estandar/threads.md)); en un sistema real serían `dbr.*` contra MySQL. ```dkl #include "dkli.dkh" #! program "api clientes" { #include "functions.dkh" #include "serialize.dkh" #include "threads.dkh" #include "http.dkh" do httpres.cors("https://app.ejemplo.com") if httpreq.method() == "OPTIONS" { return } if httpreq.bearer() != "MiTokenDeEjemplo-2026" { do httpres.fail("Token inválido") // ok y fail fijan HTTP 200: el código distinto se pone después do httpres.status(401) return } // Para el ejemplo los clientes viven en el caché del proceso; en un sistema real, dbr.* contra MySQL llave = "api.ejemplo.com/clientes" ref clientes = cache.dget(llave, @null) if isnull(clientes) { ref clientes = list.create() } if httpreq.is_post() { ref c = httpreq.json() if field.dstr(c, "nombre", "") == "" { do httpres.fail("Falta el nombre") do httpres.status(400) return } c<"id">: list.count(clientes) + 1 do list.add(clientes, c) do cache.set(llave, clientes, 0) do httpres.ok(c) do httpres.status(201) return } limite = httpreq.dnum("limite", 50) ref salida = list.create() for i=0; i