# Biblioteca fso.dk y configuración Las capacidades de FSO también se usan desde código, con `fso/fso.dk`. Necesita `functions.dkh`, `serialize.dkh` y `webauth.dkl`, y que antes se haya incluido `fso/fso.config.dk`. Al incluirse, deja asignadas las funciones predeterminadas de autorización y de búsqueda ([Puntos de extensión](#puntos-de-extensión)). ```dkl #include "dkli.dkh" #! program "ejemplo" { #include "functions.dkh" #include "serialize.dkh" #include "webauth.dkl" #include "fso/fso.config.dk" #include "fso/fso.dk" // ... su código } ``` La autorización usa `@http_context/session/user`; en un programa web lo arma `auth.dk`. En consola no hay petición: simule el contexto como en el ejemplo de abajo. ## Funciones ### dklfso.list::¶ms Devuelve las carpetas y archivos con la misma estructura que `data` de `lst.fso` (modos 0, 1 y 2): un registro con `folders` y `files`. Devuelve nulo si el usuario no puede listar la URI. | Campo de `params` | Descripción | |---|---| | `base_path` | **Requerido.** Carpeta del servidor que sirve de base | | `uri` | **Requerido.** URI del recurso, relativa a `base_path` | | `filter` | Filtro de nombres (`*.txt`; `*.*` para todos) | | `deep` | Niveles de subcarpetas | | `mode` | `0` carpetas y archivos · `1` solo carpetas · `2` solo archivos · `3` solo los que contienen `search` | | `search` | Texto a buscar en el contenido | - Ponga siempre `filter`, `deep` y `mode`: los predeterminados de `lst.fso` (`*.*`, `999`, `0`) los aplica el servicio, no la función. - La función **modifica** `params` al recorrer; use un registro nuevo en cada llamada. - Con `mode=3`, los archivos encontrados quedan en `params/found` (lista de registros). - Con `base_path` vacío lanza `Invalid base_path`. ### dklfso.createObjectInfo::base_path, uri Registro con los metadatos de un archivo o carpeta (`type`, `name`, `path`, `fullpath`, `length`, `creation`, `lastaccess`, `lastwrite`, `properties`, `privileges`, `priv_inherited`), o nulo si no existe. ### dklfso.auth::&fi, op `@true` si el usuario actual puede hacer la operación `op` (un `@op_id_*`) sobre el recurso `fi` (obtenido con `createObjectInfo`). Usa la función de autorización configurada. ### dklfso.authOp::op, &privs Aplica el [mapa de resolución de privilegios](/es/devkron/2.0/marcos/fso/privilegios.md#privilegios-por-operación): `@true` si la lista de privilegios `privs` permite `op`. Está en `fso.config.dk`. ### dklfso.getPrivs::&ruta_fisica, es_carpeta Busca el manifiesto aplicable (propio o heredado) a una ruta del disco. Devuelve un registro con `privileges` y `priv_inherited`, o nulo si no hay. ### dklfso.isprotected::uri `@true` si `uri` es la carpeta protegida (`@dklfso_protected_dir`) o algo dentro de ella, **solo** si `@dklfso_protected_dir_restricted` es `@true`; si no, siempre `@false`. No distingue mayúsculas en `uri`; escriba `@dklfso_protected_dir` en minúsculas. ### dklfso.parseRequest:: Registro con `base_path` y `uri` para la petición en curso, con las reglas de los [servicios](/es/devkron/2.0/marcos/fso/#el-recurso-sobre-el-que-se-opera). ## Ejemplo ```dkl #include "dkli.dkh" #! program "fso-backend" { #include "functions.dkh" #include "serialize.dkh" // En consola no hay solicitud HTTP: se simula un usuario con sesión ref @http_context = from.json('{"request":{"headers":{}},"session":{"user":{"uid":"web"}}}') #include "webauth.dkl" #include "fso/fso.config.dk" #include "fso/fso.dk" base = "web/misitio.localhost" new p { @"base_path": base @"uri": "/documentos" @"filter": "*.txt" @"deep": 0 @"mode": 2 } ref r = dklfso.list(p) ref archivos = @@(r,"&files") for i=0; i<@count(archivos) { do print(@@(@item(archivos,i),"fullpath") + " " + @@(@item(archivos,i),"$length") + " bytes") } new q { @"base_path": base @"uri": "/documentos" @"filter": "*.txt" @"deep": 999 @"mode": 3 @"search": "Segunda" } do dklfso.list(q) do print("encontrados: " + str(@count(@@(q,"&found")))) ref fi = dklfso.createObjectInfo(base, "/documentos/notas.txt") do print("autor: " + @@(fi,"$properties/autor")) do print("¿puede borrar?: " + str(dklfso.auth(fi, @op_id_dkl_fso_delete))) // Regla propia: nadie borra .txt, el resto lo decide el manifiesto mi.autorizar::&fi, op { if op == @op_id_dkl_fso_delete && file.extension(@@(fi,"name")) == ".txt" { return @false } return dklfso.defaultAuthObject(fi, op) } point @dklfso.funcAuthObject to mi.autorizar do print("¿puede borrar con la regla propia?: " + str(dklfso.auth(fi, @op_id_dkl_fso_delete))) do print("¿puede listar?: " + str(dklfso.auth(fi, @op_id_dkl_fso_list))) ref pr = dklfso.getPrivs(path.concat(base,"/documentos/notas.txt"), @false) do print("manifiesto a " + @@(pr,"$priv_inherited") + " niveles: " + to.json(@@(pr,"&privileges"))) } ``` Ejecutado desde la carpeta de la instalación (`./dkl /ruta/fso-backend.dkl -hide-log`), salida real: ```text /documentos/nuevo.txt 18 bytes /documentos/dup.txt 3 bytes /documentos/notas.txt 29 bytes encontrados: 1 autor: ana ¿puede borrar?: 1 ¿puede borrar con la regla propia?: 0 ¿puede listar?: 1 manifiesto a 2 niveles: {"admin":[{"user":"web"}],"dkl_fso_list":[{"user":"+"}],"dkl_fso_getprops":[{"user":"+"}]} ``` En un programa web, la base del sitio es `@@(@http_context,"$request/headers/document_root")` y el usuario lo pone `auth.dk`. ## Puntos de extensión La autorización y la búsqueda de texto se delegan en dos punteros, que puede reemplazar con `point` **después** de incluir `fso.dk`: | Puntero | Firma | Predeterminada | Decide | |---|---|---|---| | `@dklfso.funcAuthObject` | `f(&objeto, op)` → booleano | `dklfso.defaultAuthObject` | Si el usuario puede hacer `op` sobre `objeto`. La predeterminada evalúa el manifiesto y niega si no hay | | `@dklfso.funcSearchInFile` | `f(texto, archivo)` → booleano | `dklfso.defaultSearchInFile` | Si el archivo contiene el texto (la predeterminada lo busca tal cual en el contenido) | El ejemplo de arriba muestra una regla propia que delega lo demás en la estándar. Si la usa en los servicios web, póngala en un programa que todos incluyan (o modifique `fso.config.dk` de su instalación), porque cada servicio `.fso` incluye `fso.dk` por su cuenta. ## Configuración: fso.config.dk | Variable | Predeterminado | Descripción | |---|---|---| | `@dklfso_websites_path` | `"web"` | Carpeta de los sitios cuando se usa el parámetro `host` | | `@dklfso_multisites` | `@false` | `@true` habilita `base_path` y `host`, para llegar a otros sitios del servidor | | `@dklfso_metadata_ext` | `"._m_"` | Extensión de las propiedades extendidas | | `@dklfso_privs_ext` | `"._p_"` | Extensión de los manifiestos | | `@dklfso_danger_files_ext` | `".dkl,.dkh"` | Extensiones de riesgo; operar con ellas requiere `dkl_fso_danger` | | `@dklfso_id_process_file` | `"*"` | Marcador que, agregado al nombre del campo en `upl.fso`, pide procesar el archivo (`.zip*`, `.jsnwm*`) | | `@dklfso_protected_dir` | `"_protected"` | Carpeta protegida | | `@dklfso_protected_dir_restricted` | `@false` | `@true` oculta la carpeta protegida de `lst.fso` y `get.fso` | | `@dklfso_textfile_maxsize_r4search` | `262144` | Tamaño máximo (bytes) de los archivos donde se busca texto | | `@dklfso_privs_revdeep` | `50` | Niveles hacia arriba donde se busca un manifiesto heredado | | `@privid_admin`, `@privid_write`, `@privid_read`, `@privid_plus` | `"admin"`, `"write"`, `"read"`, `"plus"` | Nombres de los privilegios básicos | | `@op_id_dkl_fso_*` | `"dkl_fso_*"` | Nombres de los privilegios de operación | Considere `.dk` en `@dklfso_danger_files_ext` si sus usuarios pueden escribir en carpetas del sitio: el controlador estándar también ejecuta archivos `.dk` pedidos por URL ([Servidor web](/es/devkron/2.0/marcos/servidor-web/)). ## Mensajes de error | Mensaje | Significado | |---|---| | `Resource not found` | La URI de la llave no existe (y no se envió `text` en `set.fso`) | | `No autorizado` / `No está autorizado` | Falta el privilegio sobre el recurso | | `No está autorizado, extensión restringida` / `No autorizado, extensión peligrosa` | Extensión de `@dklfso_danger_files_ext` sin `dkl_fso_danger` | | `No está autorizado para subir archivos en esta ubicación` | Falta `dkl_fso_upload` sobre la carpeta de destino | | `No está autorizado para crear la estructura de directorios` | Hay que crear la carpeta de destino y no se pudo autorizar (hoy ocurre siempre; ver [upl.fso](/es/devkron/2.0/marcos/fso/servicios.md#comportamiento)) | | `No se pudo crear la estructura de directorios` | Falló la creación en disco | | `No existe el folder indicado y no hay manifiesto de privilegios disponible` | La carpeta de destino no existe y no hay manifiesto en su ruta | | `El destino no es un directorio` | En `upl.fso`, la URI es un archivo | | `No se han enviado archivos` | `upl.fso` sin archivos | | `Not implemented` | `copy`, `move` o `rename` sobre una carpeta | | `Command invalid` | `action` no válida | | `Action invalid` | `mkdir` sobre algo que no es carpeta | | `Invalid base_path` | `dklfso.list` con `base_path` vacío |