# File System Operations (FSO) API
Implementa los servicios de un Resources Directory (según el RAAM de Induxsoft) a través de una API pública (web services) y
privada (biblioteca de funciones).
## Enrutamiento público
La extensión .fso está dirigida hacia los programas de la API FSO que exponen servicios, revise el ```ext.map``` de la BWL.
## Servicios Web
### Listar carpetas y/o archivos
End point: uri/lst.fso
Método HTTP: GET
Devuelve un objeto JSON con información del contenido de la URI desde la que se invocó o bien,
la que se haya especificado en los parámetros de la URL (GET) si están admitidos.
#### Parámetros GET admitidos (todos son opcionales):
* filter. Una cadena de filtro para los archivos, p.e. *.txt
* deep. Numérico que indica la profundidad de búsqueda en sub-carpetas, predeterminado 999
* search. Una cadena que será buscada en el contenido de archivos
* mode. Numérico: 0 (predeterminado) - Devuelve archivos y carpetas, 1-Solo carpetas, 2- Solo archivos y 3-Solo resultados de búsqueda en archivos
* base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base.
* uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl
Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio lst.fso.
#### Privilegios requeridos
Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes:
* dkl_fso_list
* read + plus
* write
* admin
Ejemplos:
```
https://misitioweb.tld/lst.fso
https://misitioweb.tld/lst.fso?filter=*.txt
https://misitioweb.tld/lst.fso?search=guanabanas&filter=*.txt&mode=3
```
### Obtener metadatos de una carpeta o archivo
Devuelve un objeto JSON con los metadatos de un archivo o carpeta
End point: uri/get.fso
Método HTTP: GET
#### Parámetros GET admitidos (todos son opcionales):
* base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base.
* uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl
Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio get.fso.
#### Privilegios requeridos
Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes:
* dkl_fso_getprops
* read + plus
* write
* admin
Ejemplo:
```
https://misitioweb.tld/documento.docx/get.fso
```
### Establecer metadatos de una o varias carpetas o archivos
End point: uri/set.fso
Método HTTP: POST o PUT
Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales):
* base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base.
* uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl
Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio set.fso.
Cuerpo de la solicitud (payload):
```
Content-Type: application/json;charset=utf-8
{
"uri1":{
"properties":{"clave":"valor",...}
"privileges":{
"write":[{"user":"admin",...},...]
}
},
"uri2":{...},
...
"uriN":{...}
}
```
Las claves "uri1",..."uriN" del cuerpo de la solicitud y que indican los recursos a actualizar, son relativas a la uri de la URL a menos que inicien con el caracter ```/```. Para indicar que el recurso a afectar es la URL desde la que se invoca el servicio, use como clave ```.```.
Ejemplos:
Asumiendo la URL de solicitud como: ```https://misitioweb.tld/carpeta_ejemplo/set.fso```
Las uri de los recursos a afectar indicadas:
```
{
".":{ -- Afecta a la carpeta 'carpeta_ejemplo' -- },
"subcarpeta/archivo.txt":{ -- Afecta al archivo '/carpeta_ejemplo/subcarpeta/archivo.txt' -- }
"notas.txt":{ -- Afecta al archivo '/carpeta_ejemplo/notas.txt' -- }
"/otra_carpeta/texto.txt":{ -- Afecta al archivo '/otra_carpeta/texto.txt' -- }
}
```
Respuesta de ejemplo:
```
Content-Type: application/json;charset=utf-8
{
"success":true,
"data":
{
"uri1":{"props_done":true, "privs_done":true },
...
}
}
```
#### Privilegios requeridos
Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes:
* dkl_fso_setprops
* write
* admin
### Subir uno o varios archivos
Este servicio permite subir archivos codificados como ```multipart/form-data``` en la ubicación (URI) de carpeta indicada.
Si los archivos ya existen, serán sobre-escritos (si el usuario que invoca el servicio tiene los privilegios suficientes).
End point: uri/upl.fso
Método HTTP: POST o PUT
Content-Type: multipart/form-data
Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales):
* base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base.
* uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl
Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio upl.fso.
Fragmento HTML de ejemplo:
``` html
Ejemplo: Subir archivo
```
Ejemplo de respuesta (JSON) tras enviar dos archivos:
```
Content-Type: application/json;charset=utf-8
{
"success":true,
"data":
{
"nombre_archivo1":{"done":true},
"nombre_archivo2":{"done":false,"message":"No autorizado"},
...
}
}
```
#### Privilegios requeridos
Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes:
* dkl_fso_upload
* write
* admin
Adicionalmente, para permitir subir archivos de extensiones consideradas de riesgo configuradas en la variable ```@dklfso_danger_files_ext``` de fso.config.dk, se requiere alguno de los siguientes:
* dkl_fso_danger
* write + plus
* admin
### Acciones sobre el sistema de archivos
Este servicio permite las siguientes acciones directamente sobre el sistema de archivos:
* Crear una carpeta
* Eliminar una carpeta y todo su contenido
* Copiar un archivo
* Mover un archivivo
* Renombrar un archivo
* Eliminar un archivo
End point: uri/do.fso
Método HTTP: POST o PUT
Se admiten los siguientes parámetros en la URL de solicitud (todos son opcionales):
* base_path. Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base.
* uri. Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
De manera predeterminada, los parámetros en la URL base_path y host son excluyentes entre sí y son ignorados a menos que establezca ```@dklfso_multisites=@true``` en fso.config.dkl
Si se omite el parámetro uri, se asume que la URI es la que corresponde a la invocación del servicio do.fso.
Las claves "uri1",..."uriN" del cuerpo de la solicitud y que indican los recursos a actualizar, son relativas a la uri de la URL a menos que inicien con el caracter ```/```. Para indicar que el recurso a afectar es la URL desde la que se invoca el servicio, use como clave ```.```.
Cuerpo de la solicitud (payload):
```
Content-Type: application/json;charset=utf-8
{
"uri1":{ "action":"delete" },
"uri2":{ "action":"mkdir" },
"uri3":{ "action":"copy", "to":"uri_destino"},
"uri4":{ "action":"move", "to":"uri_destino"},
"uri5":{ "action":"rename", "as":"nuevo_nombre"}
...
"uriN":{...}
}
```
Ejemplo de respuesta (JSON):
```
Content-Type: application/json;charset=utf-8
{
"success":true,
"data":
{
"uri1":{"done":true},
"uri2":{"done":false,"message":"No autorizado"},
...
}
}
```
#### Privilegios requeridos
Se requiere que el usuario esté autenticado y cuente con alguno de los siguientes:
* dkl_fso_mkdir - Para crear carpetas
* dkl_fso_copy - Para copiar archivos
* dkl_fso_move - Para mover archivos
* dkl_fso_delete - Para eliminar archivos y carpetas
* dkl_fso_rename - Para renombrar archivos
* dkl_fso_overwrite - Para sobrescribir archivos en el destino al copiar o mover
* write (crear carpetas, copiar, mover, eliminar, sobrescribir y renombrar)
* write + plus (Igual que write, pero incluyendo extensiones de archivos con extensiones de riesgo)
* admin (Igual que write + plus)
Adicionalmente, para permitir escribir o renombrar archivos con extensiones consideradas de riesgo configuradas en la variable ```@dklfso_danger_files_ext``` de fso.config.dk, se requiere alguno de los siguientes:
* dkl_fso_danger
* write + plus
* admin
## Funciones disponibles en fso.dk
fso.dk requiere que previamente se incluya el archivo de configuraciones fso.config.dk y depende de functions.dkh, serialize.dkh y webauth.dkl
Ejemplo:
```
#include "dkli.dkh"
#!
program "ejemplo"
{
#include "functions.dkh"
#include "serialize.dkh"
#include "webauth.dkl"
#include "_protected/fso/fso.config.dk"
#include "_protected/fso/fso.dk"
//..su código
}
```
fso.dk contiene las siguientes funciones de interés para el programador del back-end:
### dklfso.isprotected::uri
Devuelve ```@true``` si la cadena uri indicada es una subcarpeta o archivo en una subcarpeta del carpeta protegida del sitio Web.
### dklfso.createObjectInfo::base_path,uri
Devuelve una referencia a una estructura de datos con toda la información de metadatos de un archivo o carpeta en el sistema local, o bien @null si no se encuentra el recurso.
* base_path - Es una cadena que representa la ruta de base del sitio Web en el sistema local
* uri - Es una cadena que representa la ruta relativa a base_path del recurso (archivo o carpeta) en el sistema local
### dklfso.list::¶ms
Devuelve un objeto con toda la información de carpetas y archivos, es la misma respuesta que el servicio lst.fso invocado desde el propio backend.
```params``` es una referencia a una estructura que puede tener los siguientes parámetros:
* base_path. (Requerido) Una cadena con la ruta del sistema local (en el servidor) usada como base para la uri
* uri. (Requerido) Una cadena que representa un URI concatenado sobre la ruta de base (base_path) para la obtención de resultados
* host. Una cadena con el nombre de un host en el servidor para tomar su ubicación de archivos como base, si se indica este parámetro no se ignorará base_path por lo que este último puede excluirse.
* filter. (Opcional) Una cadena de filtro para los archivos, p.e. *.txt
* deep. (Opcional) Numérico que indica la profundidad de búsqueda en sub-carpetas, predeterminado 999
* search. (Opcional) Una cadena que será buscada en el contenido de archivos
* mode. (Opcional) Numérico: 0 (predeterminado) - Devuelve archivos y carpetas, 1-Solo carpetas, 2- Solo archivos y 3-Solo resultados de búsqueda en archivos
## Metadatos
Los metadatos asociados a una carpeta o archivo son propiedades extendidas (clave/valor) o el manifiesto de privilegios.
### Propiedades extendidas
Se almacenan en archivos en formato JSON con extensión ```._m_``` a menos que indique lo contrario en fso.config.dk
Las propiedades extendidas de una carpeta se encuentran en el archivo ```._m_``` (archivo sin nombre, solo extensión) dentro de la misma.
Para las propiedades extendidas de los archivos, se emplean archivos con el mismo nombre y extensión, más la extensión ```._m_```, p.e. para un archivo denominado ```notas.docx```, existirá un archivo de propiedades extendidas llamado ```notas.docx._m_```
Si no existe el archivo ```._m_``` de propiedades extendidas, las únicas propiedades del archivo o carpeta son las que corresponden al sistema de archivos: nombre (incluyendo extensión), fecha y hora de creación, fecha y hora de último acceso y fecha y hora de última escritura (todas las fechas y horas en formato UTC)
### Manifiesto de privilegios
Se almacenan en archivos en formato JSON con extensión ```._p_``` a menos que indique lo contrario en fso.config.dk
El manifiesto de privilegios de una carpeta se encuentran en el archivo ```._p_``` (archivo sin nombre, solo extensión) dentro de la misma.
Para el manifiesto de privilegios de los archivos, se emplean archivos con el mismo nombre y extensión, más la extensión ```._p_```, p.e. para un archivo denominado ```notas.docx```, existirá un archivo de manifiesto de privilegios llamado ```notas.docx._p_```
Si no existe un archivo de manifiesto de privilegios para un archivo o carpeta, aplica la herencia ascendente, es decir, se heredan los privilegios del manifiesto de la carpeta padre y si no existe, entonces la del padre del padre, etc.
### Importante
Ni los archivos de propiedades extendidas ni los archivos de manifiesto de privilegios se generan o existen de forma predeterminada, deberá crearlos manualmente o a través del servicio set.fso
## Privilegios de operaciones específicas
FSO API asume que existen los privilegios básicos de BWL: read, write, plus y admin
Adicionalmente, define privilegios para operaciones específicas y sus equivalencias (mapa de resolución de privilegios) con respecto a los privilegios básicos en fso.config.dk, lea el código fuente para comprender mejor o realizar personalizaciones.