# La petición y la respuesta: @http_context Cuando el servidor FastCGI atiende una petición, deja toda su información en la variable global **`@http_context`**, un registro con dos miembros principales: `request` (lo que llegó) y `response` (lo que se va a responder). Su programa lee el primero y escribe el segundo. `@http_context` está disponible en el programa que atiende la petición y en todo lo que este incluya. Los programas que se ejecutan con `runscript` (por ejemplo, las vistas de CRUD-L) no lo heredan: reciben su propia variable de contexto. ## Ver el contexto completo La forma más rápida de saber qué recibe un programa es volcar el contexto como JSON. Guarde esto como `web/misitio.localhost/ctx/index.dkl`: ```dkl #include "dkli.dkh" #! program "volcado" { #include "functions.dkh" #include "serialize.dkh" @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(@http_context) } ``` Y pídalo con parámetros, una cookie y un cuerpo JSON: ```bash curl "http://misitio.localhost/ctx/?cliente=27&orden=fecha" \ -H "Cookie: tema=oscuro; idioma=es" \ -X POST -H "Content-Type: application/json" -d '{"nombre":"Ana"}' ``` Respuesta real de 2.0 detrás de nginx (formateada; se omitieron las variables de entorno del proceso, que también aparecen en `request/headers`): ```json { "request": { "headers": { "QUERY_STRING": "cliente=27&orden=fecha", "REQUEST_METHOD": "POST", "CONTENT_TYPE": "application/json", "CONTENT_LENGTH": "16", "SCRIPT_NAME": "/ctx/", "REQUEST_URI": "/ctx/?cliente=27&orden=fecha", "DOCUMENT_URI": "web/misitio.localhost/ctx/?cliente=27&orden=fecha", "DOCUMENT_ROOT": "web/misitio.localhost", "SERVER_PROTOCOL": "HTTP/1.1", "REQUEST_SCHEME": "http", "GATEWAY_INTERFACE": "CGI/1.1", "SERVER_SOFTWARE": "nginx/1.24.0", "REMOTE_ADDR": "127.0.0.1", "REMOTE_PORT": "40806", "SERVER_ADDR": "127.0.0.1", "SERVER_PORT": "80", "SERVER_NAME": "misitio.localhost", "REDIRECT_STATUS": "200", "HTTP_HOST": "misitio.localhost", "HTTP_USER_AGENT": "curl/8.5.0", "HTTP_ACCEPT": "*/*", "HTTP_COOKIE": "tema=oscuro; idioma=es", "HTTP_CONTENT_TYPE": "application/json", "HTTP_CONTENT_LENGTH": "16", "path_translated": "web/misitio.localhost/ctx/index.dkl" }, "cookies": { "tema": "oscuro", "idioma": "es" }, "get": { "cliente": "27", "orden": "fecha" }, "files": null, "POST_STRING": "{\"nombre\":\"Ana\"}" }, "response": { "headers": { "Content-Type": "application/json;charset=utf-8", "X-Powered-By": "Devkron" }, "output": "text", "text": "", "binary": null, "http_status": 200 }, "session": {} } ``` El miembro `session` lo agrega el `auth.dk` del sitio (el de la plantilla `blank` lo hace siempre); vea [La sesión](/es/devkron/2.0/marcos/autenticacion/sesion.md). Los nombres de los miembros **no distinguen mayúsculas y minúsculas**: `request/headers/REQUEST_METHOD` y `request/headers/request_method` son el mismo valor, igual que `request/post_string` y `request/POST_STRING`. ## request: lo que llegó | Miembro | Tipo | Contenido | |---|---|---| | `headers` | registro | Variables CGI que manda el servidor web (`REQUEST_METHOD`, `REQUEST_URI`, `QUERY_STRING`, `CONTENT_TYPE`, `REMOTE_ADDR`, `SERVER_NAME`, `HTTPS`...), los encabezados del navegador con prefijo `HTTP_` (`HTTP_HOST`, `HTTP_ACCEPT`, `HTTP_AUTHORIZATION`, `HTTP_COOKIE`, `HTTP_USER_AGENT`...), las variables de entorno del proceso del servidor y las que agrega el controlador (abajo) | | `cookies` | registro | Una llave por cookie recibida | | `get` | registro | Parámetros de la cadena de consulta (lo que va después de `?`), ya decodificados, más los parámetros que agrega `routes.map` | | `post` | registro | Campos de un formulario `application/x-www-form-urlencoded` (métodos POST, PUT y PATCH) o los campos de texto de un `multipart/form-data`. Si el cuerpo es de otro tipo, no existe | | `POST_STRING` | cadena | El cuerpo de la petición como texto, en POST, PUT y PATCH, salvo que sea `multipart/form-data` (con un formulario urlencoded trae el texto crudo, `nombre=Luis`). Es lo que se lee para un cuerpo JSON | | `files` | lista o nulo | Los archivos de un `multipart/form-data`; nulo si no hay | Valores que agrega el controlador `http.dkl` en `request/headers` antes de ejecutar su programa: | Llave | Contenido | |---|---| | `document_root` | Carpeta del sitio, relativa a la carpeta de trabajo del servidor (`web/misitio.localhost`) | | `path_translated` | Archivo que se está ejecutando (`web/misitio.localhost/ctx/index.dkl`) | | `document_uri` | La URI de la petición pegada a la carpeta del sitio | ### Leer parámetros Use `@@` (de `functions.dkh`) con el prefijo de tipo: `$` cadena, `#` número, `&` objeto. Si el miembro no existe, `@@` devuelve un valor vacío del tipo pedido en lugar de un error: ```dkl cliente = @@(@http_context, "#request/get/cliente") // 27 (número; 0 si no viene o no es número) orden = @@(@http_context, "$request/get/orden") // "fecha" pagina = field.dnum(@http_context, "request/get/pagina", 1) // 1 si no viene metodo = toupper(@@(@http_context, "$request/headers/REQUEST_METHOD")) ``` ### Leer un cuerpo JSON ```dkl ref datos = from.json(@@(@http_context, "$request/POST_STRING")) nombre = @@(datos, "$nombre") ``` Si el cuerpo no es JSON válido, `from.json` lanza un error: atrápelo con `exception` y responda un mensaje claro. Un patrón útil para servicios que aceptan los dos formatos es leer el formulario si vino y, si no, el JSON: ```dkl carga:: { ref post = ifnull(@@(@http_context, "&request/post"), record.create()) if list.count(list.create_from_fields(post)) < 1 { texto = trim(field.dstr(@http_context, "request/post_string", "{}")) if texto == "" { texto = "{}" } ref post = from.json(texto) } return post } ``` ### Archivos subidos Con un formulario `multipart/form-data`, `request/files` es una lista con un registro por archivo, y los campos de texto llegan en `request/post`. Este programa los muestra: ```dkl #include "dkli.dkh" #! program "subir" { #include "functions.dkh" #include "serialize.dkh" new r { @"campos*": @@(@http_context,"&request/post") } r<"archivos*">: @@(@http_context,"&request/files") @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(r) } ``` ```bash curl -F "referencia=F-001" -F "comprobante=@recibo.txt" http://misitio.localhost/subir.dkl ``` ```json { "campos": { "referencia": "F-001" }, "archivos": [ { "headers_string": "Content-Disposition:form-data\r\nContent-Type:text/plain", "filename": "recibo.txt", "temp_file": "/tmp/29a72af626ad4dabbb364127141d17d7.tmp", "size": 3, "field": "comprobante" } ] } ``` | Llave | Contenido | |---|---| | `field` | Nombre del campo del formulario | | `filename` | Nombre del archivo en el equipo del cliente | | `temp_file` | Ruta del temporal donde el servidor guardó el contenido | | `size` | Tamaño en bytes | | `headers_string` | Encabezados de esa parte del formulario | **El temporal se borra al terminar la petición.** Para conservar el archivo, cópielo con `file.copy(field.str(f,"temp_file"), destino)` durante la petición. Para subir archivos con privilegios y carpetas por usuario, use la [API FSO](/es/devkron/2.0/marcos/fso/) en lugar de programarlo. El tamaño máximo del cuerpo lo limitan `client_max_body_size` de nginx y `max_body_size` de `fastcgi.json` ([Servidor FastCGI](/es/devkron/2.0/instalacion/fastcgi.md)). ## response: lo que se va a responder | Miembro | Valor inicial | Uso | |---|---|---| | `headers` | `Content-Type: text/html;charset=utf-8`, `X-Powered-By: Devkron` | Encabezados de la respuesta. Agregue o sustituya los que necesite (`Content-Type`, `Location`, `Content-Disposition`, `Access-Control-Allow-Origin`...) | | `output` | `standard` | Origen del cuerpo: `standard` (la salida declarativa del programa), `text` (el miembro `text`) o `binary` (el miembro `binary`) | | `text` | `""` | Cuerpo de la respuesta cuando `output` es `text` | | `binary` | nulo | Arreglo de bytes de la respuesta cuando `output` es `binary` (asígnelo con `*`: `@http_context<"response/binary*">: file.rbytes(ruta)`) | | `http_status` | `200` | Código de estado HTTP. En 2.0 sí llega al navegador | | `cookies` | no existe | Registro con las cookies a enviar (`Set-Cookie`); lo crea `cookies.dkl` | Además el servidor agrega siempre `Cache-Control: no-cache`, `Date`, `Server: Devkron FastCGI` y `Content-Length`. ### El código de estado `response/http_status` fija el estado (404, 201, 500...). Con 200 no se envía `Status:` a nginx, de modo que una respuesta con `Location` se convierte en una redirección 302. Si el programa pone su propio encabezado `response/headers/status`, ese manda sobre `http_status`. Las formas de responder, con ejemplos ejecutados, están en [Responder HTML, XML, JSON, texto o archivos](/es/devkron/2.0/marcos/servidor-web/respuestas.md). ## Errores típicos | Síntoma | Causa y solución | |---|---| | `request/post` no existe aunque se envió un cuerpo | El cuerpo es JSON u otro tipo: léalo de `request/POST_STRING` | | `request/POST_STRING` vacío con un `GET` | Solo se llena con POST, PUT y PATCH | | El archivo subido "desaparece" | El temporal se borra al terminar la petición: cópielo antes | | Un valor de `get` con `=` llega cortado (`?x=a=b` da `x` = `a`) | Los valores se cortan en el segundo `=` (comportamiento conservado de 1.x): codifique el valor (`%3D`) | | `Variable global '@http_context' no definida` en una vista | Las vistas de CRUD-L y los programas lanzados con `runscript` reciben otro contexto (`@crud_context`); vea [Vistas](/es/devkron/2.0/marcos/crudl/vistas.md) |