Referencia API de FoxServerCore

Introducción a FoxServerCore

FoxServerCore es el componente central del framework FoxServer que permite crear APIs RESTful utilizando Visual FoxPro. Proporciona todas las clases y utilidades necesarias para manejar solicitudes HTTP, procesar datos y generar respuestas en formato JSON.

El archivo principal FoxServerCore.prg contiene las siguientes clases principales:

• ApiController: Clase base para todos los controladores API
• FoxServerRequest: Encapsula la solicitud HTTP entrante
• FoxServerResponse: Encapsula la respuesta HTTP saliente
• FoxServerLogger: Proporciona capacidades de logging
• Clases auxiliares: Para manejo de datos y utilidades diversas

Clase ApiController

La clase ApiController es la base para todos los controladores de API en FoxServer. Hereda de la clase session de VFP y proporciona una amplia gama de métodos y propiedades para facilitar el desarrollo de APIs RESTful, incluyendo manejo de solicitudes, procesamiento de datos, conversión JSON, registro de eventos y utilidades diversas.

Propiedades principales

Inicialización y Configuración

PROCEDURE Initialize

* Se ejecuta automáticamente al crear una instancia del controlador
procedure Initialize
    set deleted on
    
    try
        this.ApiService = createobject("ApiServiceUtility")
    catch
    endtry
    
    try
        local lcMacro
        if empty(this.cPath)
            this.cPath = addbs(fullpath(curdir()))
        endif

        lcMacro = "set path to [" + this.cPath + "] additive"
        &lcMacro
        lcMacro = "set default to " + this.cPath
        &lcMacro
        this.LoadJsonFox()
    catch to loEx
        local lcError, lcFile
        lcError = textmerge("<>: Error in Initialize: <> line: <>")
        lcFile = this.cPath + "ApiControllerError.txt"
        strtofile(lcError + chr(13) + chr(10), lcFile, 1)
    endtry
endproc

FUNCTION GetGlobalResource(tcResourceName as string) AS Variant

* Obtener una conexión de base de datos global
    loConnection = this.GetGlobalResource("DatabaseConnection")
    IF !ISNULL(loConnection)
        * Usar la conexión...
    ENDIF

    * Obtener configuración global
    loConfig = this.GetGlobalResource("AppConfig")
    IF !ISNULL(loConfig)
        lcServerUrl = loConfig.ServerUrl
    ENDIF

PROCEDURE SetWorkingDirectory(tcWorkingDirectory as string)

* Configurar directorio de trabajo para el controlador
loController.SetWorkingDirectory("C:\MiAplicacion\api\")

PROCEDURE LoadJsonFox

procedure LoadJsonFox
    try
        if type('_screen.json') != 'O' or vartype(_screen.json) == 'X'
            local lcJsonApp
            lcJsonApp = this.cPath + "JSONFox.app"
            if file(lcJsonApp)
                do (lcJsonApp)
                _screen.json.lShowErrors = .f.
            else
                this.logerror("JSONfox.app not found: " + lcJsonApp)
            endif
        endif
    catch to loEx
        this.LogFromException(loEx)
    endtry
endproc

Ciclo de vida de los endpoints

FUNCTION BeforeEndpoint(req, res) AS BOOLEAN

* En una clase que hereda de ApiController
FUNCTION BeforeEndpoint(req, res) AS BOOLEAN
    * Verificar autenticación
    lcTabla = THIS.cPath + "usuarios.dbf"
    IF !FILE(lcTabla)
        res.status(500).json('{"error":"La tabla de usuarios no existe"}')
        RETURN .F.  && Detener procesamiento
    ENDIF
    
    * Registrar inicio de solicitud
    this.LogInfo("Procesando solicitud: " + req.method + " " + req.uri.AbsolutePath)
    
    RETURN .T.  && Continuar con el endpoint
ENDFUNC

PROCEDURE AfterEndpoint(req, res)

* En una clase que hereda de ApiController
PROCEDURE AfterEndpoint(req, res)
    * Registrar finalización de solicitud
    this.LogInfo("Solicitud completada: " + req.method + " " + req.uri.AbsolutePath + " - Status: " + TRANSFORM(res.statusCode))
    
    * Liberar recursos si es necesario
    IF USED("tmpData")
        USE IN tmpData
    ENDIF
ENDPROC

Manejo de Logging

PROCEDURE SetLogging(tbEnabled as Boolean)
PROCEDURE SetLogFile(tcLogFile as string)
PROCEDURE SetCorrelationId(tcCorrelationId as string)

* Configurar logging para un controlador
loController.SetLogging(.T.)
loController.SetLogFile("C:\logs\api_" + DTOS(DATE()) + ".log")
loController.SetCorrelationId(SYS(2015))

* En un endpoint
FUNCTION GetUsuario(req, res)
    this.LogInfo("Obteniendo usuario con ID: " + req.GetParam("id"))
    * Resto del código...
ENDFUNC

PROCEDURE LogInfo(tcMessage)
PROCEDURE LogError(tcMessage)
PROCEDURE LogFromException(toException)

* Registrar información
this.LogInfo("Procesando solicitud para el usuario: " + lcUserId)

* Registrar error
this.LogError("No se pudo conectar a la base de datos")

* Registrar excepción
TRY
    * Código que podría fallar
CATCH TO loEx
    this.LogFromException(loEx)
    res.status(500).json('{"error":"Error interno del servidor"}')
ENDTRY

Manejo de JSON

FUNCTION ToJson(toObj as object) AS memo

* Crear un objeto y convertirlo a JSON
loUsuario = this.NewObject("id,nombre,email,activo")
loUsuario.id = 1
loUsuario.nombre = "Juan Pérez"
loUsuario.email = "juan@example.com"
loUsuario.activo = .T.

* Convertir a JSON
lcJson = this.ToJson(loUsuario)
* Resultado: {"id":1,"nombre":"Juan Pérez","email":"juan@example.com","activo":true}

FUNCTION ParseJson(tcJsonStr as memo) AS object

* Procesar JSON recibido en una solicitud
lcJson = req.GetRawBody()
loData = this.ParseJson(lcJson)

IF !ISNULL(loData)
    ? loData.nombre  && "Juan Pérez"
    ? loData.email   && "juan@example.com"
    ? loData.activo  && .T.
ENDIF

FUNCTION NewObject(tcSchema as memo) AS object

* Crear un objeto para respuesta de API
loRespuesta = this.NewObject("status,data,message,timestamp")
loRespuesta.status = "success"
loRespuesta.data = loResultados
loRespuesta.message = "Operación completada correctamente"
loRespuesta.timestamp = DATETIME()

* Enviar como JSON
res.json(this.ToJson(loRespuesta))

FUNCTION NewObjectFromCursor(tcCursor as string, tnSession as integer) AS Object

* Crear un objeto plantilla basado en la estructura de una tabla
USE usuarios IN 0
loTemplate = this.NewObjectFromCursor("usuarios", THIS.DataSessionId)

* El objeto tendrá las propiedades: id, nombre, email, etc.
* Útil para validaciones o crear objetos de respuesta consistentes

Conversión de datos a JSON

PROCEDURE TableToJson(tcCursor as string, tbCurrentRow as logical) AS memo

* Consultar datos
SELECT id, nombre, email, fecha_registro FROM usuarios WHERE activo = .T. INTO CURSOR curUsuarios

* Convertir todos los registros a JSON (como array)
lcJsonArray = this.TableToJson("curUsuarios", .F.)
* Resultado: [{"id":1,"nombre":"Juan","email":"juan@example.com","fecha_registro":"2023-05-15"},...]

* Convertir solo el registro actual (como objeto)
SELECT curUsuarios
LOCATE FOR id = 5
lcJsonObject = this.TableToJson("curUsuarios", .T.)
* Resultado: {"id":5,"nombre":"Ana","email":"ana@example.com","fecha_registro":"2023-06-20"}

FUNCTION TableToJsonObject(tcCursor as string, tbCurrentRow as logical, tnSession as integer) AS Collection

* Obtener datos como colección de objetos
SELECT id, nombre, email FROM usuarios INTO CURSOR curUsuarios
loCollection = this.TableToJsonObject("curUsuarios", .F., THIS.DataSessionId)

* Manipular los objetos antes de serializar
FOR EACH loUsuario IN loCollection
    * Agregar propiedades calculadas
    ADDPROPERTY(loUsuario, "display_name", loUsuario.nombre + " (" + loUsuario.email + ")")
ENDFOR

* Serializar la colección modificada
lcJson = this.ToJson(loCollection)

FUNCTION MasterToJSON(tcMaster as string, tcDetail as string, tcExpr as string, tcDetailAttribute as string) AS memo

* Preparar cursores
SELECT id, nombre, fecha FROM facturas INTO CURSOR curFacturas
SELECT id, factura_id, producto, cantidad, precio FROM items INTO CURSOR curItems

* Convertir a JSON con estructura jerárquica
lcJson = this.MasterToJSON("curFacturas", "curItems", "curFacturas.id = curItems.factura_id", "items")

* Resultado:
* [
*   {
*     "id": 1,
*     "nombre": "Factura A-001",
*     "fecha": "2023-05-20",
*     "items": [
*       {"id": 101, "factura_id": 1, "producto": "Teclado", "cantidad": 2, "precio": 25.99},
*       {"id": 102, "factura_id": 1, "producto": "Mouse", "cantidad": 1, "precio": 15.50}
*     ]
*   },
*   ...
* ]

Utilidades de Texto y Formato

FUNCTION Format(tcSource as string, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10) AS string

* Formatear un mensaje con valores
lcMensaje = this.Format("Usuario {0} realizó {1} en {2}", lcNombre, lcAccion, TTOC(DATETIME()))
* Resultado: "Usuario Juan realizó login en 2023-05-20 15:30:45"

* Formatear una URL
lcUrl = this.Format("/api/usuarios/{0}/pedidos/{1}", lcUserId, lcPedidoId)
* Resultado: "/api/usuarios/123/pedidos/456"

FUNCTION Content(req as FoxServerRequest, tvSource as variant) AS memo

* El cliente puede solicitar diferentes formatos:
* GET /api/usuarios?format=json
* GET /api/usuarios?format=xml  
* GET /api/usuarios?format=csv
* O usar headers: Accept: application/xml

FUNCTION GetUsuarios(req, res) HELP "GET: usuarios"
    SELECT * FROM usuarios INTO CURSOR curUsuarios
    
    * Content() detecta automáticamente el formato y convierte
    lcContent = this.Content(req, "curUsuarios")
    res.status(200).send(lcContent)
ENDFUNC

FUNCTION TableToXml(tcCursor as string, tbCurrentRow as logical) AS memo
FUNCTION TableToCsv(tcCursor as string, tbCurrentRow as logical) AS memo

* Generar XML de datos
SELECT * FROM productos INTO CURSOR curProductos
lcXml = this.TableToXml("curProductos", .F.)

* Generar CSV para exportación
lcCsv = this.TableToCsv("curProductos", .F.)
res.header("Content-Disposition", "attachment; filename=productos.csv").send(lcCsv)

FUNCTION EscapeCharsToJSON(tcStream as string) AS string
FUNCTION EscapeCharsToHTML(tcStream as string) AS string

* Escapar caracteres para JSON
lcTexto = "Café con leche & más"
lcEscapado = this.EscapeCharsToJSON(lcTexto)
* Resultado: "Caf\u00e9 con leche \u0026 m\u00e1s"

* Escapar caracteres para HTML
lcTexto = "Sección de información"
lcEscapado = this.EscapeCharsToHTML(lcTexto)
* Resultado: "Sección de información"

Utilidades de Fecha y Tiempo

FUNCTION DTOUNX(tdFecha as datetime, tbUseMiliseconds as logical) AS number
FUNCTION UNXTOD(tnUnixTimestamp as number) AS datetime

* Convertir fecha VFP a timestamp UNIX
ldFecha = DATETIME()
lnTimestamp = this.DTOUNX(ldFecha, .F.)  && En segundos
lnTimestampMs = this.DTOUNX(ldFecha, .T.)  && En milisegundos

* Convertir timestamp UNIX a fecha VFP
ldFecha1 = this.UNXTOD(1621500000)  && Desde segundos
ldFecha2 = this.UNXTOD(1621500000000)  && Desde milisegundos

Utilidades de Codificación

FUNCTION Base64URLEncode(tcInput as string) AS string
FUNCTION Base64URLDecode(tcInput as string) AS string

* Codificar payload JWT
lcPayload = '{"sub":"123","name":"John Doe","role":"admin"}'
lcEncodedPayload = this.Base64URLEncode(lcPayload)
* Resultado: "eyJzdWIiOiIxMjMiLCJuYW1lIjoiSm9obiBEb2UiLCJyb2xlIjoiYWRtaW4ifQ"

* Decodificar token
lcDecodedPayload = this.Base64URLDecode(lcEncodedPayload)
* Resultado: '{"sub":"123","name":"John Doe","role":"admin"}'

FUNCTION NewGuid() AS string

* Generar un GUID para un nuevo recurso
lcId = this.NewGuid()
* Resultado: "a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6"

* Usar como correlación para logs
this.SetCorrelationId(this.NewGuid())

Gestión de Recursos

PROCEDURE CleanUp
PROCEDURE Release
PROCEDURE Dispose

procedure CleanUp
    try
        if type('this.Logger') == 'O' and vartype(this.Logger) == 'O'
            this.Logger = null
        endif
    catch
    endtry
endproc

procedure release
    this.CleanUp()
endproc

procedure Dispose
    this.CleanUp()
endproc

Ejemplos de Implementación

DEFINE CLASS UsuariosController AS ApiController
    * Implementación de métodos hooks
    FUNCTION BeforeEndpoint(req, res) AS BOOLEAN
        * Verificar si la tabla de usuarios existe
        LOCAL lcTabla
        lcTabla = THIS.cPath + "usuarios.dbf"
        IF !FILE(lcTabla)
            res.status(500).json('{"error":"La tabla de usuarios no existe"}')
            RETURN .F.  && Detener procesamiento
        ENDIF        
        
        * Registrar inicio de solicitud
        this.LogInfo(this.Format("Solicitud iniciada: {0} {1}", req.Method, req.Uri.AbsolutePath))
        RETURN .T.
    ENDFUNC
    
    PROCEDURE AfterEndpoint(req, res)
        * Registrar finalización
        this.LogInfo(this.Format("Solicitud completada: {0} {1} - Status: {2}", ;
            req.GetMethod(), req.Uri.AbsolutePath, TRANSFORM(res.GetStatusCode())))
                
        CLOSE DATABASES ALL
    ENDPROC

    * Endpoint para obtener lista de usuarios
    PROCEDURE GetUsuarios(req, res) HELP "GET: usuarios public"
        * Al usar "public" se indica que este endpoint es accesible sin autenticación
        LOCAL lcFiltro, lcOrden
        
        * Obtener parámetros de consulta
        lcFiltro = req.GetQuery("filtro", "")
        lcOrden = req.GetQuery("orden", "nombre")
        
        * Registrar información
        this.LogInfo(this.Format("Obteniendo usuarios con filtro: {0}, orden: {1}", lcFiltro, lcOrden))
        
        * Ejecutar consulta
        IF !EMPTY(lcFiltro)
            SELECT id, nombre, email, activo FROM usuarios ;
                WHERE UPPER(nombre) LIKE UPPER('%' + lcFiltro + '%') ;
                ORDER BY &lcOrden ;
                INTO CURSOR curUsuarios
        ELSE
            SELECT id, nombre, email, activo FROM usuarios ;
                ORDER BY &lcOrden ;
                INTO CURSOR curUsuarios
        ENDIF
                
        * Convertir a JSON y responder
        lcJson = this.TableToJson("curUsuarios", .F.)        
        res.status(200).json(lcJson)
    ENDPROC
    
    * Endpoint para obtener un usuario específico
    PROCEDURE GetUsuario(req, res) HELP "GET: usuarios/{id} public"
        * Al usar "public" se indica que este endpoint es accesible sin autenticación
        LOCAL lcId, lcJson
        
        * Obtener ID del usuario
        lcId = req.GetParam("id", "0")
        
        * Validar ID
        IF !ISDIGIT(lcId) OR VAL(lcId) <= 0
            res.status(400).json('{"error":"ID de usuario inválido"}')
            RETURN
        ENDIF
        
        * Buscar usuario
        SELECT id, nombre, email, telefono, direccion, activo ;
            FROM usuarios WHERE id = VAL(lcId) ;
            INTO CURSOR curUsuario
        
        * Verificar si existe
        IF RECCOUNT("curUsuario") = 0
            res.status(404).json('{"error":"Usuario no encontrado"}')
            RETURN
        ENDIF
        
        * Convertir a JSON y responder
        lcJson = this.TableToJson("curUsuario", .T.)
        res.status(200).json(lcJson)
    ENDPROC
    
    * Endpoint para crear un nuevo usuario
    PROCEDURE CreateUsuario(req, res) HELP "POST: usuarios public"
        * Al usar "public" se indica que este endpoint es accesible sin autenticación
        LOCAL loData, lcNombre, lcEmail, lcJson
        
        * Obtener datos del cuerpo de la solicitud
        loData = this.ParseJson(req.GetRawBody())
        
        * Validar datos requeridos
        IF ISNULL(loData) OR EMPTY(loData.nombre) OR EMPTY(loData.email)
            res.status(400).json('{"error":"Nombre y email son obligatorios"}')
            RETURN
        ENDIF
        
        * Verificar si el email ya existe
        SELECT COUNT(*) as total FROM usuarios WHERE email = loData.email INTO CURSOR curCheck
        IF curCheck.total > 0
            res.status(409).json('{"error":"El email ya está registrado"}')
            RETURN
        ENDIF
        
        * Insertar nuevo usuario
        lcNombre = loData.email
        lcEmail = loData.email
        
        INSERT INTO usuarios (nombre, email, activo, fecha_registro) ;
            VALUES (lcNombre, lcEmail, .T., DATETIME())
        
        * Obtener ID generado
        lnId = _tally
        
        * Crear objeto de respuesta
        loRespuesta = this.NewObject("id,mensaje")
        loRespuesta.id = lnId
        loRespuesta.mensaje = "Usuario creado correctamente"
        
        * Responder
        res.status(201).json(this.ToJson(loRespuesta))
    ENDPROC
ENDDEFINE

Consejos de uso

Objetos Request y Response

FoxServerRequest

El objeto FoxServerRequest encapsula la solicitud HTTP entrante y proporciona acceso a sus datos. Este objeto es pasado a cada manejador de ruta y contiene toda la información necesaria sobre la petición del cliente.

Métodos para acceder a datos de la solicitud

FUNCTION GetHeader(tcKey as string, tvDefault as variant) AS variant

* Obtener token de autorización
lcToken = req.GetHeader("Authorization", "")
IF !EMPTY(lcToken)
    * Procesar token...
ENDIF

* Verificar tipo de contenido
lcContentType = req.GetHeader("Content-Type", "")
IF "application/json" $ lcContentType
    * Procesar como JSON...
ENDIF

FUNCTION GetParam(tcProp as string, tvDefault as variant) AS variant
FUNCTION GetQuery(tcProp as string, tvDefault as variant) AS variant

* Para una ruta como /usuarios/:id
lcUserId = req.GetParam("id", "0")

* Para una URL como /productos?categoria=electronica&orden=precio
lcCategoria = req.GetQuery("categoria", "todas")
lcOrden = req.GetQuery("orden", "nombre")

FUNCTION GetQueryParams() AS FoxServerTupleDictionary

* Iterar sobre todos los parámetros de consulta
loParams = req.GetQueryParams()
FOR lnI = 1 TO loParams.Count
    lcKey = loParams.GetKey(lnI)
    lcValue = loParams.GetValue(lnI)
    THIS.LogInfo("Parámetro: {0} = {1}", lcKey, lcValue)
ENDFOR

FUNCTION HasJsonBody() AS Boolean

* Validar que hay datos JSON antes de procesarlos
IF req.HasJsonBody()
    lcNombre = req.json.nombre
    lcEmail = req.json.email
ELSE
    res.status(400).json('{"error":"Se requiere un cuerpo JSON válido"}')
    RETURN
ENDIF

FUNCTION GetFormField(tcKey as string, tvDefault as variant) AS variant
FUNCTION HasFormField(tcKey as string) AS Boolean

* Procesar un formulario de registro
IF req.HasFormField("email") AND req.HasFormField("password")
    lcEmail = req.GetFormField("email")
    lcPassword = req.GetFormField("password")
    lcNombre = req.GetFormField("nombre", "Usuario")
    
    * Registrar usuario...
ELSE
    * Campos requeridos faltantes...
ENDIF

* Métodos simplificados (recomendados)
FUNCTION File(tcKey as string) AS Object
FUNCTION Files(tcKey as string) AS Object

* Métodos tradicionales
FUNCTION GetFile(tcKey as string) AS Object
FUNCTION GetFiles(tcKey as string) AS Object

* Métodos originales
FUNCTION GetMultipartFile(tcKey as string, tvDefault as variant) AS variant
FUNCTION GetMultipartFiles(tcKey as string, tvDefault as variant) AS variant

* Obtener un solo archivo
loFile = req.File("avatar")
IF !ISNULL(loFile)
    lcDestino = req.cPath + "uploads\" + loFile.FileName
    loFile.SaveToFile(lcDestino)
    This.LogInfo("Archivo guardado en:{0} ", lcDestino)
ENDIF

* Obtener múltiples archivos
loFiles = req.Files("documentos")
IF !ISNULL(loFiles)
    FOR EACH loKey IN loFiles.Keys
        loFile = loFiles.GetValue(loKey)
        lcDestino = req.cPath + "uploads\" + loFile.FileName
        loFile.SaveToFile(lcDestino)
        this.LogInfo("Archivo guardado: {0}", loFile.FileName)
    ENDFOR
ENDIF

FUNCTION GetRawBody() AS string

* Acceder al cuerpo raw para procesamiento personalizado
lcBody = req.GetRawBody()
IF !EMPTY(lcBody)
    * Procesar el cuerpo según sea necesario
    IF req.ContentType == "application/xml"
        * Procesar XML...
    ENDIF
ENDIF

PROCEDURE SetAuthenticatedUser(tcId as string, tcName as string, tcRole as string) AS Void

PROCEDURE SetLogging(tbEnabled as Boolean)
PROCEDURE SetLogFile(tcLogFile as string)
PROCEDURE SetCorrelationId(tcCorrelationId as string)

FoxServerResponse

El objeto FoxServerResponse encapsula la respuesta HTTP saliente y proporciona métodos para configurarla. Este objeto permite establecer el código de estado, encabezados y el cuerpo de la respuesta, así como enviar diferentes tipos de contenido al cliente.

FUNCTION Status(tnStatusCode as integer) AS FoxServerResponse

* Respuesta exitosa
res.status(200).json('{"mensaje":"Operación completada"}')

* Recurso creado
res.status(201).json('{"id":123,"mensaje":"Recurso creado"}')

* Error de validación
res.status(400).json('{"error":"Datos inválidos"}')

* Recurso no encontrado
res.status(404).json('{"error":"El recurso solicitado no existe"}')

* Error interno
res.status(500).json('{"error":"Error interno del servidor"}')

FUNCTION Header(tcKey as string, tvValue as variant) AS FoxServerResponse

* Establecer encabezados personalizados
res.header("Content-Type", "application/json");
   .header("X-API-Version", "1.0");
   .header("Cache-Control", "no-cache");
   .json('{"data":"ejemplo"}')

FUNCTION Json(tcContent as memo) AS FoxServerResponse

* Respuesta JSON simple
res.status(200).json('{"status":"success","message":"Operación completada"}')

* Respuesta JSON con datos complejos
LOCAL loRes, loData
loData = THIS.NewObject("id,nombre,email")
loData.id = 123
loData.nombre = "Juan Pérez"
loData.email = "juanperez@gmail.com"

loRes = THIS.NewObject("status,data,message,timestamp")
loRes.status = "success"
loRes.data = loData
loRes.message = "Datos obtenidos correctamente"
loRes.timestamp = DATETIME()

res.status(200).json(THIS.toJson(loRes))

FUNCTION Send(tcContent as memo, tcDisposition as string) AS FoxServerResponse

* Enviar texto plano
res.status(200).send("Operación completada correctamente")

* Enviar HTML
lcHtml = '<!DOCTYPE html><html><body><h1>Hola Mundo</h1></body></html>'
res.status(200).send(lcHtml)

* Enviar XML
lcXml = 'ok'
res.status(200).send(lcXml)

* Enviar archivo (detecta automáticamente si es una ruta de archivo)
res.status(200).send("C:\archivos\documento.pdf", "attachment")

FUNCTION SendFile(tcFilePath as string, tcDisposition as string) AS FoxServerResponse

* Enviar un PDF para visualizar en el navegador
res.sendFile("C:\informes\reporte.pdf", "inline")

* Enviar un archivo Excel para descargar
res.sendFile("C:\datos\exportacion.xlsx", "attachment")

* Enviar una imagen
res.sendFile("C:\imagenes\foto.jpg", "inline")

* Enviar un archivo con estado personalizado
res.status(201).sendFile("C:\archivos\nuevo_documento.docx", "attachment")

FUNCTION Location(tvLocation as variant) AS FoxServerResponse

* Redirección temporal (302)
res.status(302).location("/login").send("")

* Redirección permanente (301)
res.status(301).location("https://nuevositio.com").send("")

* Redirección después de crear un recurso
res.status(303).location("/api/recursos/" + lcId).send("")

* Redirección con mensaje
res.status(302).location("/dashboard").send('{"message":"Redirigiendo al panel de control..."}')

FUNCTION HasHeader(tcHeader as string) AS Boolean
FUNCTION GetHeader() AS string

* Verificar si ya se ha establecido un encabezado
IF !res.hasHeader("Content-Type")
    res.header("Content-Type", "application/json")
ENDIF

* Iterar sobre todos los encabezados
res.nHeaderIndex = 1
DO WHILE res.HasNextHeader()
    lcHeader = res.GetHeader()
    ? lcHeader
ENDDO

Consejos de uso

Clase Auth

La clase Auth es un componente especializado que hereda de ApiController y proporciona funcionalidades para la autenticación de usuarios en FoxServer. Esta clase se encarga de validar las credenciales del usuario y comunicar el resultado al middleware de autenticación mediante encabezados HTTP específicos.

Estructura básica

define class Auth as ApiController olepublic
    function ValidateUser(req, res) help "POST: auth/login public"
        * implementa aquí el proceso de autenticación con tus datos.
        * implement here the authentication process with your data.
    endfunc
enddefine

Métodos principales

Flujo de autenticación

El proceso de autenticación en FoxServer sigue estos pasos:

1. El cliente envía una solicitud POST a /auth/login con las credenciales del usuario.
2. El método ValidateUser en FoxPro valida estas credenciales contra la base de datos.
3. Dependiendo del resultado, se establece el encabezado X-Auth-Status a true o false.
4. El middleware de autenticación en el servidor X# detecta este encabezado y, si es true, genera el token JWT.
5. El token JWT se incluye en la respuesta final enviada al cliente.

Encabezado X-Auth-Status

Este encabezado es crucial para el funcionamiento de la autenticación:

• X-Auth-Status: true - Indica que la autenticación fue exitosa y el middleware debe generar un token JWT.
• X-Auth-Status: false - Indica que la autenticación falló y no debe generarse un token.

Formato de respuesta requerido

Para que el middleware pueda generar correctamente el token JWT, la respuesta JSON debe incluir los siguientes campos obligatorios:

{
    "status": "ok",
    "data": {
        "id": "123",      // Obligatorio: ID del usuario
        "name": "usuario", // Obligatorio: Nombre del usuario
        "role": "admin"   // Obligatorio: Rol del usuario
    },
    "message": "autenticación exitosa"
}

Implementación recomendada

A continuación se muestra una implementación completa del método ValidateUser:

procedure ValidateUser(req, res) help "POST: /auth/login public"
    local loRes, loData
    loRes = this.newObject('status,data,message')
    loData = this.newObject('id,name,role')
    try
        select users
        if seek(req.json.userName + req.json.password, 'users', 'login')
            loData.id = users.id
            loData.name = req.json.userName
            loData.Role = 'server'
            
            loRes.status = 'ok'
            loRes.data = loData
            loRes.message = 'autenticación exitosa'
            res.AddHeader('X-Auth-Status', 'true')
            res.status(200).json(this.toJson(loRes))
        else
            loRes.status = 'error'
            loRes.data = null
            loRes.message = 'el usuario y/o la contraseña no son válidos'
            res.AddHeader('X-Auth-Status', 'false')
            res.status(404).json(this.toJson(loRes))
        endif
    catch to loEx
        local lcMsg
        lcMsg = "Error en ValidateUser: " + loEx.message
        this.Logger.logerror(lcMsg)
        loRes.status = 'error'
        loRes.data = null
        loRes.message = lcMsg
        res.addHeader('X-Auth-Status', 'false')
        res.status(500).json(this.toJson(loRes))            
    endtry
endproc

Respuesta del middleware

Si la autenticación es exitosa, el middleware de X# generará un token JWT y modificará la respuesta para incluirlo:

{
    "status": "ok",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiresIn": 3600
    },
    "message": "token generated successfully"
}

Protección de rutas

Cuando un proyecto FoxServer utiliza autenticación JWT, todos los endpoints requieren autenticación por defecto. Para indicar que una ruta debe ser accesible públicamente (sin token JWT), utilice la palabra clave public en el comentario de ayuda del método:

function ValidateUser(req, res) help "POST: auth/login public"
    * Esta función es accesible sin token JWT (pública)
    * ...
endfunc

function GetUserData(req, res) help "GET: users/:id"
    * Esta función requiere autenticación con token JWT (protegida por defecto)
    * ...
endfunc

Sistema de Logging

FoxServerCore incluye un potente sistema de logging a través de la clase FoxServerLogger, que permite registrar eventos, información, advertencias y errores durante la ejecución de la aplicación. Este sistema facilita la depuración y el seguimiento de la actividad del servidor.

Clase FoxServerLogger

La clase FoxServerLogger es el componente central del sistema de logging, proporcionando métodos para registrar diferentes tipos de mensajes y configurar el comportamiento del logger.

Propiedades principales

Configuración del Logger

PROCEDURE SetLogFile(tcLogFile as string)

PROCEDURE SetLogging(tbEnabled as Boolean)

PROCEDURE SetCorrelationId(tcCorrelationId as string)

PROCEDURE SetApiService(toApiService as ApiServiceUtility)

Métodos de Logging

PROCEDURE LogInfo(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

* Registrar mensaje simple
loLogger.LogInfo("Iniciando procesamiento de datos")

* Registrar mensaje con formato
loLogger.LogInfo("Cliente ID: {0} procesado con {1} registros", lcClienteId, lnRegistros)

PROCEDURE LogWarning(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

* Advertir sobre datos incompletos
loLogger.LogWarning("Usuario ID {0} no tiene email configurado", lcUserId)

* Advertir sobre recursos bajos
loLogger.LogWarning("Memoria disponible baja: {0} bytes", lnMemoryAvailable)

PROCEDURE LogError(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

* Registrar error de conexión
loLogger.LogError("No se pudo conectar a la base de datos: {0}", lcServer)

* Registrar error con múltiples parámetros
loLogger.LogError("Error al procesar el archivo: {0}. Código: {1}, Tipo: {2}", lcFileName, lnErrorCode, lcErrorType)

PROCEDURE LogFromException(toEx as exception)

* Capturar y registrar una excepción
TRY
    * Código que puede generar error
    USE (lcDatabase) SHARED
    * Más operaciones...
CATCH TO loException
    loLogger.LogFromException(loException)
    * Manejar el error...
ENDTRY

PROCEDURE Log(tnType as integer, tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

Formato de mensajes con múltiples parámetros

La clase FoxServerLogger ahora soporta el formato de mensajes con múltiples parámetros, similar a las funciones printf en otros lenguajes. Esto se logra a través del servicio ApiServiceUtility que proporciona la función format.

* Mensaje con formato y múltiples parámetros
loLogger.LogInfo("Usuario {0} realizó {1} operaciones en {2}", lcUserName, lnOperations, lcModule)

Formato de los mensajes de log

Los mensajes de log se escriben en el archivo con el siguiente formato:

FECHA_HORA | TIPO_LOG | [CORRELATION_ID] | MENSAJE

Ejemplo:

31/05/2025 11:45:23 | INFO    | [a1b2c3d4-e5f6-g7h8] | Iniciando procesamiento de solicitud GET /api/usuarios
31/05/2025 11:45:24 | WARNING | [a1b2c3d4-e5f6-g7h8] | Parámetro 'filtro' no especificado, usando valores predeterminados
31/05/2025 11:45:25 | ERROR   | [a1b2c3d4-e5f6-g7h8] | Error 1526 at line 45: File 'datos.dbf' does not exist in program PROCESAR

Integración con ApiController

La clase ApiController integra automáticamente el sistema de logging, proporcionando métodos para acceder al logger desde los controladores:

* En un controlador que hereda de ApiController
FUNCTION GetUsuarios(req, res) HELP "GET: /api/usuarios"
    this.LogInfo("Obteniendo lista de usuarios")
    
    TRY
        * Código para obtener usuarios...
    CATCH TO loEx
        this.LogFromException(loEx)
        res.status(500).json('{"error":"Error interno del servidor"}')
    ENDTRY
    
    this.LogInfo("Se encontraron {0} usuarios", lnUsuarios)
    res.status(200).json(lcJson)
ENDFUNC

Buenas prácticas de logging

Manejo de Datos Multipart

FoxServerCore proporciona un sistema robusto para manejar datos multipart/form-data, permitiendo procesar formularios con archivos adjuntos y campos de texto. Este sistema se compone de dos clases principales: FoxServerMultipartData y FoxServerMultipartFile.

FoxServerMultipartData

La clase FoxServerMultipartData extiende FoxServerTupleDictionary y proporciona métodos para gestionar colecciones de archivos enviados en formularios multipart.

PROCEDURE AddFile(tcFieldName as string, tcFileName as string, tcContentType as string, tvContent as Variant) as Void

* Agregar un archivo a la colección
loMultipartData = CREATEOBJECT("FoxServerMultipartData")
loMultipartData.AddFile("avatar", "profile.jpg", "image/jpeg", lcFileContent)

* Agregar múltiples archivos con el mismo nombre de campo
loMultipartData.AddFile("documentos", "contrato.pdf", "application/pdf", lcPdfContent)
loMultipartData.AddFile("documentos", "anexo.docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", lcDocxContent)

FUNCTION GetFiles(tcKey as string) as Variant

* Obtener todos los archivos de un campo y procesarlos
loFiles = loMultipartData.GetFiles("documentos")

IF !ISNULL(loFiles)
    * Iterar a través de todos los archivos
    FOR EACH loKey IN loFiles.Keys
        loFile = loFiles.GetValue(loKey)
        THIS.LogInfo("Procesando archivo: {0} Tamaño: {1}", loFile.FileName, loFile.GetSize())
        * Hacer algo con cada archivo...
    ENDFOR
ENDIF

FUNCTION GetFile(tcKey as string) as Variant

* Obtener un único archivo y procesarlo
loFile = loMultipartData.GetFile("avatar")

IF !ISNULL(loFile)
    * Verificar si es una imagen
    IF loFile.IsImage()
        * Guardar la imagen en un directorio
        lcPath = "C:\uploads\avatars\" + SYS(2015) + "." + loFile.GetBestExtension()
        IF loFile.SaveToFile(lcPath)
            THIS.LogInfo("Imagen guardada en: {0}", lcPath)
        ELSE
            THIS.LogError("Error al guardar la imagen")
        ENDIF
    ENDIF
ENDIF

FoxServerMultipartFile

La clase FoxServerMultipartFile representa un archivo individual enviado en un formulario multipart y proporciona métodos para manipular y validar el archivo.

Propiedades

Métodos de configuración

PROCEDURE SetFieldName(tcFieldName as string) as Void
PROCEDURE SetFileName(tcFileName as string) as Void
PROCEDURE SetContentType(tcContentType as string) as Void
PROCEDURE SetContent(tvContent as Variant) as Void

Métodos de extensión de archivo

FUNCTION GetFileExtension() as string

* Obtener extensión basada en el tipo MIME
lcExt = loFile.GetFileExtension()
? lcExt && "pdf" para un archivo con ContentType = "application/pdf"

FUNCTION GetOriginalExtension() as string

* Obtener extensión del nombre original
lcExt = loFile.GetOriginalExtension()
? lcExt && "pdf" para un archivo con FileName = "documento.pdf"

FUNCTION GetBestExtension() as string

* Obtener la mejor extensión para guardar el archivo
lcExt = loFile.GetBestExtension()
lcPath = "C:\uploads\" + SYS(2015) + "." + lcExt

Métodos de manejo de archivos

FUNCTION SaveToFile(tcTargetPath as string) as Boolean

* Guardar archivo con nombre único
lcPath = "C:\uploads\" + SYS(2015)
IF loFile.SaveToFile(lcPath)
    THIS.Logger("Archivo guardado como: {0}", lcPath + "." + loFile.GetBestExtension())
ELSE
    THIS.Logger("Error al guardar el archivo")
ENDIF

* Guardar con ruta y nombre específicos
IF loFile.SaveToFile("C:\uploads\documentos\informe_final.pdf")
    ? "Archivo guardado correctamente"
ENDIF

FUNCTION GetSize() as integer

* Verificar tamaño antes de procesar
lnSize = loFile.GetSize()
THIS.Logger("Tamaño del archivo: {0} bytes", lnSize)

* Verificar si excede un límite
IF lnSize > 5000000 && 5MB
    THIS.LogError("El archivo es demasiado grande")
ENDIF

FUNCTION IsEmpty() as Boolean

* Verificar si el archivo tiene contenido
IF loFile.IsEmpty()
    THIS.LogError("El archivo está vacío")
ELSE
    THIS.LogInfo("El archivo contiene {0} bytes.", loFile.GetSize())
ENDIF

Métodos de validación de tipo

FUNCTION IsContentType(tcPattern as string) as Boolean

* Verificar tipo específico
IF loFile.IsContentType("application/pdf")
    THIS.LogInfo("Es un archivo PDF")
ENDIF

* Verificar tipo de imagen específico
IF loFile.IsContentType("image/jpeg")
    THIS.LogInfo("Es una imagen JPEG")
ENDIF

FUNCTION IsImage() as Boolean

* Verificar si es una imagen
IF loFile.IsImage()
    THIS.LogInfo("Es una imagen de tipo: {0}", loFile.ContentType)
    
    * Procesar solo imágenes
    lcImagePath = "C:\uploads\images\" + SYS(2015) + "." + loFile.GetBestExtension()
    loFile.SaveToFile(lcImagePath)
ELSE
    ? "No es una imagen"
ENDIF

FUNCTION IsPDF() as Boolean

* Verificar si es un PDF
IF loFile.IsPDF()
    THIS.LogInfo("Es un archivo PDF")
    
    * Procesar solo PDFs
    lcPdfPath = "C:\uploads\documents\" + SYS(2015) + ".pdf"
    loFile.SaveToFile(lcPdfPath)
ELSE
    THIS.LogInfo("No es un archivo PDF")
ENDIF

FUNCTION IsAllowedType(tcAllowedTypes as string) as Boolean

* Verificar si es un tipo permitido
IF loFile.IsAllowedType("pdf,docx,xlsx")
    THIS.LogInfo("Tipo de archivo permitido")
ELSE
    THIS.LogInfo("Tipo de archivo no permitido. Solo se aceptan PDF, DOCX y XLSX")
ENDIF

* Verificar tipos de imagen permitidos
IF loFile.IsImage() AND loFile.IsAllowedType("jpg,png,gif")
    THIS.LogInfo("Formato de imagen permitido")
ELSE
    THIS.LogInfo("Solo se permiten imágenes JPG, PNG y GIF")
ENDIF

Integración con ApiController

El sistema de manejo multipart se integra perfectamente con ApiController para procesar formularios con archivos:

DEFINE CLASS UploadController AS ApiController
    
    * Endpoint para subir archivos
    FUNCTION Upload(req, res) HELP "POST: /api/upload"
        LOCAL loFiles, loFile, lcUploadPath, lcSavedPath, loResponse
        
        * Verificar si hay archivos
        IF !req.HasFiles()
            res.status(400).json('{"error":"No se encontraron archivos"}')
            RETURN
        ENDIF                     
        
        * Configurar directorio de carga
        lcUploadPath = ADDBS(this.GetConfig("upload_path", "C:\uploads"))
        
        * Verificar y crear directorio si no existe
        IF !DIRECTORY(lcUploadPath)
            MD (lcUploadPath)
        ENDIF
        
        * Procesar archivo de avatar (uno solo)
        loFile = req.GetFile("avatar")
        IF !ISNULL(loFile)
            * Validar que sea una imagen
            IF !loFile.IsImage()
                res.status(400).json('{"error":"El avatar debe ser una imagen"}')
                RETURN
            ENDIF
            
            * Validar tamaño máximo (1MB)
            IF loFile.GetSize() > 1048576
                res.status(400).json('{"error":"El avatar no debe superar 1MB"}')
                RETURN
            ENDIF
            
            * Guardar con nombre único
            lcSavedPath = ADDBS(lcUploadPath) + "avatar_" + req.GetParam("user_id") + "." + loFile.GetBestExtension()
            IF !loFile.SaveToFile(lcSavedPath)
                res.status(500).json('{"error":"Error al guardar el avatar"}')
                RETURN
            ENDIF
            
            this.LogInfo("Avatar guardado: {0}", lcSavedPath)
        ENDIF
        
        * Procesar múltiples documentos
        loDocumentos = req.GetFiles("documentos")
        IF !ISNULL(loDocumentos)
            LOCAL laRutas[1], lnCount, loDocumento
            
            lnCount = 0
            DIMENSION laRutas[1]
            
            * Crear directorio específico para documentos
            lcDocPath = ADDBS(lcUploadPath) + "docs_" + SYS(2015)
            MD (lcDocPath)
            
            * Procesar cada documento
            FOR EACH loKey IN loDocumentos.Keys
                loDocumento = loDocumentos.GetValue(loKey)
                
                * Validar tipo permitido
                IF !loDocumento.IsAllowedType("pdf,docx,xlsx")
                    this.LogWarning("Tipo de documento no permitido: {0}", loDocumento.FileName)
                    LOOP
                ENDIF
                
                * Guardar documento
                lcDocFile = ADDBS(lcDocPath) + loDocumento.FileName
                IF loDocumento.SaveToFile(lcDocFile)
                    lnCount = lnCount + 1
                    DIMENSION laRutas[lnCount]
                    laRutas[lnCount] = lcDocFile                    
                    this.LogInfo("Documento guardado: {0}", lcDocFile)
                ENDIF
            ENDFOR
            
            * Crear respuesta
            loResponse = this.NewObject("success,message,avatar,documentos")
            loResponse.success = .T.
            loResponse.message = "Archivos procesados correctamente"
            loResponse.avatar = lcSavedPath
            loResponse.documentos = laRutas

            res.status(200).json(this.ToJson(loResponse))
        ENDIF

        res.status(200).json('{"success":true,"message":"Avatar procesado correctamente"}')
    ENDFUNC
    
ENDDEFINE

Buenas prácticas

Colecciones y Diccionarios

FoxServerCore proporciona un sistema flexible para manejar colecciones de pares clave-valor a través de las clases FoxServerTuple y FoxServerTupleDictionary. Estas clases forman la base de muchas estructuras de datos utilizadas en el framework.

FoxServerTuple

La clase FoxServerTuple representa un par clave-valor simple, donde la clave es una cadena y el valor puede ser de cualquier tipo. Esta estructura básica se utiliza como componente fundamental para construir colecciones más complejas.

Propiedades

PROCEDURE init(tcKey as string, tvValue as Variant)

PROCEDURE SetKey(tcKey as string) as Void
FUNCTION GetKey() as string

PROCEDURE SetValue(tvValue as Variant) as Void
FUNCTION GetValue() as Variant

FUNCTION ToString() as string

FoxServerTupleDictionary

La clase FoxServerTupleDictionary extiende la clase nativa Collection de VFP para proporcionar funcionalidad de diccionario (mapa clave-valor). Permite almacenar y recuperar valores utilizando claves de cadena, manteniendo un acceso eficiente.

Propiedades

FUNCTION Exists(tcKey as string) as Boolean

PROCEDURE AddPair(tcKey as string, tvValue as Variant)

FUNCTION AddEntry(toEntry as FoxServerTuple) as Void

FUNCTION GetIndex(tcKey as string) as integer

FUNCTION Get(tvIndexOrKey as Variant) as Variant

FUNCTION GetValue(tvIndexOrKey as Variant, tvDefault as Variant) as Variant

PROCEDURE CleanUp() as Void
PROCEDURE Release() as Void
PROCEDURE Dispose() as Void

Utilidades de Servicio API

La clase ApiServiceUtility proporciona un conjunto de herramientas y funciones auxiliares comúnmente utilizadas en el desarrollo de APIs y servicios web. Estas utilidades facilitan tareas como la determinación de tipos MIME, validación de formatos, generación de identificadores únicos, manipulación de JSON y más.

ApiServiceUtility

Esta clase contiene métodos que pueden ser utilizados en cualquier parte de la aplicación para realizar operaciones comunes.

Propiedades principales

Métodos de configuración

PROCEDURE SetPath(tcPath as String)

PROCEDURE SetLogger(toLogger as FoxServerLogger)

Utilidades básicas

FUNCTION GetMimeType(tcExtension as string) as string

* Obtener tipos MIME para diferentes extensiones
? loUtils.GetMimeType("pdf")    && "application/pdf"
? loUtils.GetMimeType("jpg")    && "image/jpeg"
? loUtils.GetMimeType("docx")   && "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
? loUtils.GetMimeType("json")   && "application/json"

FUNCTION IsValidEmail(tcEmail as string) as Boolean

* Validar direcciones de correo electrónico
? loUtils.IsValidEmail("usuario@dominio.com")      && .T.
? loUtils.IsValidEmail("nombre.apellido@empresa.co.uk")  && .T.
? loUtils.IsValidEmail("usuario@dominio")          && .F.

FUNCTION GenerateUUID() as string

* Generar identificadores únicos
lcUUID = loUtils.GenerateUUID()
? lcUUID && Por ejemplo: "550e8400-e29b-41d4-a716-446655440000"

FUNCTION GenerateUUIDManual() as string

Utilidades de formato y texto

FUNCTION format(tcSource, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11) as string

* Formatear una cadena con valores
lcNombre = "Juan"
lnEdad = 30
lcCiudad = "Madrid"

lcMensaje = loUtils.format("Hola, mi nombre es {0}, tengo {1} años y vivo en {2}.", lcNombre, lnEdad, lcCiudad)
? lcMensaje && "Hola, mi nombre es Juan, tengo 30 años y vivo en Madrid."

FUNCTION EscapeCharsToJSON(tcStream) as string

* Escapar caracteres especiales para JSON
lcTexto = "José Martínez & Cía."
lcEscapado = loUtils.EscapeCharsToJSON(lcTexto)
? lcEscapado && "Jos\u00e9 Mart\u00ednez \u0026 C\u00eda."

FUNCTION EscapeCharsToHTML(tcStream) as string

* Convertir caracteres a entidades HTML
lcTexto = "José María"
lcHtml = loUtils.EscapeCharsToHTML(lcTexto)
? lcHtml && "José María"

Utilidades de fecha y hora

FUNCTION DTOUNX(tdFecha as datetime, tbUseMiliseconds as logical) as number

* Convertir fecha a timestamp UNIX
ldFecha = {^2025-06-01 12:30:00}

* En segundos
lnUnixSecs = loUtils.DTOUNX(ldFecha, .F.)
? lnUnixSecs && 1748905800

* En milisegundos
lnUnixMs = loUtils.DTOUNX(ldFecha, .T.)
? lnUnixMs && 1748905800000

FUNCTION UNXTOD(tnUnixTimestamp as number) as datetime

* Convertir timestamp UNIX a fecha
* Timestamp en segundos
ldFecha1 = loUtils.UNXTOD(1748905800)
? ldFecha1 && 01/06/2025 12:30:00

* Timestamp en milisegundos
ldFecha2 = loUtils.UNXTOD(1748905800000)
? ldFecha2 && 01/06/2025 12:30:00

Utilidades de codificación

FUNCTION Base64URLEncode(tcInput as string) as string

* Codificar en Base64URL
lcTexto = "Esto es un texto de prueba"
lcCodificado = loUtils.Base64URLEncode(lcTexto)
? lcCodificado && "RXN0byBlcyB1biB0ZXh0byBkZSBwcnVlYmE"

FUNCTION Base64URLDecode(tcInput as string) as string

* Decodificar desde Base64URL
lcCodificado = "RXN0byBlcyB1biB0ZXh0byBkZSBwcnVlYmE"
lcDecodificado = loUtils.Base64URLDecode(lcCodificado)
? lcDecodificado && "Esto es un texto de prueba"

Utilidades JSON

PROCEDURE LoadJsonFox()

FUNCTION ParseJson(tcJsonStr as memo) as object

* Analizar una cadena JSON
lcJson = '{"nombre":"Juan","edad":30,"ciudad":"Madrid"}'
loObj = loUtils.ParseJson(lcJson)

? loObj.nombre && "Juan"
? loObj.edad && 30
? loObj.ciudad && "Madrid"

FUNCTION TableToJson(tcCursor as string, tbCurrentRow as logical, tnSessionId as integer) as memo

* Crear un cursor de ejemplo
CREATE CURSOR clientes (id i, nombre c(30), email c(50))
INSERT INTO clientes VALUES (1, 'Juan Pérez', 'juan@ejemplo.com')
INSERT INTO clientes VALUES (2, 'María López', 'maria@ejemplo.com')

* Convertir todo el cursor a JSON
lcJson = loUtils.TableToJson('clientes', .F., THIS.DataSessionId)
? lcJson 
&& [{"id":1,"nombre":"Juan Pérez","email":"juan@ejemplo.com"},
&&  {"id":2,"nombre":"María López","email":"maria@ejemplo.com"}]

* Convertir solo el registro actual
GO 2
lcJsonRow = loUtils.TableToJson('clientes', .T., THIS.DataSessionId)
? lcJsonRow 
&& {"id":2,"nombre":"María López","email":"maria@ejemplo.com"}

FUNCTION MasterToJSON(tcMaster as string, tcDetail as string, tcExpr as string, tcDetailAttribute as string, tnSessionID as integer) as memo

* Crear cursores maestro-detalle
CREATE CURSOR facturas (id i, fecha d, cliente c(30))
CREATE CURSOR items (factura_id i, producto c(30), cantidad i, precio n(10,2))

* Insertar datos de ejemplo
INSERT INTO facturas VALUES (1, DATE(), 'Cliente A')
INSERT INTO facturas VALUES (2, DATE(), 'Cliente B')

INSERT INTO items VALUES (1, 'Producto 1', 2, 100.00)
INSERT INTO items VALUES (1, 'Producto 2', 1, 50.00)
INSERT INTO items VALUES (2, 'Producto 3', 3, 75.00)

* Convertir a JSON con relación maestro-detalle
lcJson = loUtils.MasterToJSON('facturas', 'items', 'facturas.id = items.factura_id', 'items', _VFP.DataSessionId)

* El resultado será un JSON con cada factura y sus items relacionados

Métodos de logging

PROCEDURE LogInfo(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

PROCEDURE LogError(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

PROCEDURE LogWarning(tcMessage, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11)

PROCEDURE LogFromException(toException as exception)

Tabla de tipos MIME soportados

Gestión del Ciclo de Vida de la Aplicación

La clase ApplicationLifecycle proporciona un mecanismo para gestionar recursos globales y eventos del ciclo de vida de la aplicación FoxServer. Esta clase hereda de ApiController y permite centralizar la inicialización y limpieza de recursos compartidos.

ApplicationLifecycle

Esta clase actúa como un contenedor para recursos globales y maneja los eventos de inicio y parada de la aplicación. Utiliza una colección interna (oResources) para almacenar y gestionar todos los recursos globales de forma centralizada.

PROCEDURE Init()

PROCEDURE Init()
    THIS.oResources = CREATEOBJECT("Collection")
ENDPROC

PROCEDURE OnApplicationStarting()

DEFINE CLASS MyAppLifecycle AS ApplicationLifecycle OLEPUBLIC
    PROCEDURE OnApplicationStarting()
        * Inicializar conexión de base de datos global
        LOCAL loConnection
        loConnection = CREATEOBJECT("ADODB.Connection")
        loConnection.Open("Provider=SQLOLEDB;Server=localhost;Database=MyApp;Trusted_Connection=yes")
        
        * Almacenar como recurso global
        THIS.SetResource("DatabaseConnection", loConnection)
        
        * Cargar configuración global
        LOCAL loConfig
        loConfig = THIS.LoadConfiguration()
        THIS.SetResource("AppConfig", loConfig)
        
        * Inicializar cache global
        LOCAL loCache
        loCache = CREATEOBJECT("ApplicationCache")
        THIS.SetResource("Cache", loCache)
        
        THIS.LogInfo("Aplicación iniciada correctamente")
    ENDPROC
    
ENDDEFINE

PROCEDURE OnApplicationStopping()

PROCEDURE OnApplicationStopping()
    * Cerrar conexión de base de datos
    LOCAL loConnection
    loConnection = THIS.GetResource("DatabaseConnection")
    IF !ISNULL(loConnection)
        loConnection.Close()
        THIS.LogInfo("Conexión de base de datos cerrada")
    ENDIF
    
    * Limpiar cache
    LOCAL loCache
    loCache = THIS.GetResource("Cache")
    IF !ISNULL(loCache) AND PEMSTATUS(loCache, "Clear", 5)
        loCache.Clear()
        THIS.LogInfo("Cache limpiado")
    ENDIF
    
    THIS.LogInfo("Aplicación detenida correctamente")
ENDPROC

PROTECTED PROCEDURE SetResource(tcResourceName as string, toReference as variant)

* En OnApplicationStarting()
LOCAL loConnection
loConnection = CREATEOBJECT("ADODB.Connection")
loConnection.Open("connection_string")
THIS.SetResource("DatabaseConnection", loConnection)

* Actualizar recurso existente
LOCAL loNewConfig
loNewConfig = THIS.LoadUpdatedConfiguration()
THIS.SetResource("AppConfig", loNewConfig)  && Reemplaza el anterior

* Almacenar diferentes tipos de recursos
THIS.SetResource("ServerStartTime", DATETIME())
THIS.SetResource("MaxConnections", 100)
THIS.SetResource("DebugMode", .T.)

FUNCTION GetResource(tcResourceName as string) AS Variant

* Obtener recursos de diferentes tipos
LOCAL loConnection, loConfig, lnMaxConn, llDebug
loConnection = THIS.GetResource("DatabaseConnection")
loConfig = THIS.GetResource("AppConfig")
lnMaxConn = THIS.GetResource("MaxConnections")
llDebug = THIS.GetResource("DebugMode")

* Siempre validar antes de usar
IF !ISNULL(loConnection)
    * Usar la conexión...
ELSE
    THIS.LogError("Conexión de base de datos no disponible")
ENDIF

* Obtener con valores por defecto
LOCAL lcServerUrl
lcServerUrl = IIF(ISNULL(THIS.GetResource("ServerUrl")), "localhost", THIS.GetResource("ServerUrl"))

PROTECTED FUNCTION IsValidResourceCollection() AS Boolean

FUNCTION GetResource(tcResourceName)
    IF !THIS.IsValidResourceCollection()
        RETURN NULL
    ENDIF
    
    LOCAL i
    i = THIS.oResources.GetKey(tcResourceName)
    IF i > 0
        RETURN THIS.oResources.Item(i)
    ENDIF
    RETURN NULL
ENDFUNC

FUNCTION GetResourceNames() AS String

* Listar todos los recursos disponibles
LOCAL lcResourceList
lcResourceList = THIS.GetResourceNames()
THIS.LogInfo("Recursos disponibles: {0}", lcResourceList)

* Resultado ejemplo: "DatabaseConnection, AppConfig, Cache, ServerStartTime"

* Usar para validaciones de estado
IF EMPTY(lcResourceList)
    THIS.LogWarning("No hay recursos globales inicializados")
ENDIF

PROCEDURE CleanUp()

PROCEDURE CleanUp()
    DODEFAULT()  && Llama al CleanUp del ApiController padre
    
    TRY
        IF THIS.IsValidResourceCollection()
            * Limpiar recursos individuales si tienen método CleanUp
            LOCAL i, loResource
            FOR i = 1 TO THIS.oResources.Count
                loResource = THIS.oResources.Item(i)
                IF VARTYPE(loResource) == 'O' AND !ISNULL(loResource)
                    IF PEMSTATUS(loResource, "CleanUp", 5)
                        loResource.CleanUp()
                    ENDIF
                ENDIF
            ENDFOR
            
            * Limpiar toda la colección
            THIS.oResources.Remove(-1)
            THIS.oResources = NULL
        ENDIF
    CATCH TO loEx
        * No propagar errores en cleanup
    ENDTRY
ENDPROC

Integración con ApiController

Los controladores API pueden acceder a los recursos globales a través del método GetGlobalResource que está disponible en todos los controladores que hereden de ApiController:

DEFINE CLASS UsuariosController AS ApiController

    FUNCTION GetUsuarios(req, res) HELP "GET: usuarios"
        * Obtener conexión global de base de datos
        LOCAL loConnection
        loConnection = THIS.GetGlobalResource("DatabaseConnection")
        
        IF ISNULL(loConnection)
            res.Status(500).Json('{"error":"Base de datos no disponible"}')
            RETURN
        ENDIF
        
        * Obtener configuración global
        LOCAL loConfig
        loConfig = THIS.GetGlobalResource("AppConfig")
        LOCAL lnPageSize
        lnPageSize = IIF(ISNULL(loConfig), 10, loConfig.DefaultPageSize)
        
        * Usar la conexión para consultar datos
        LOCAL lcSql, loRecordset
        lcSql = "SELECT TOP " + ALLTRIM(STR(lnPageSize)) + " * FROM usuarios"
        loRecordset = loConnection.Execute(lcSql)
        
        * Procesar resultados...
        LOCAL lcJsonData
        lcJsonData = THIS.RecordsetToJson(loRecordset)
        res.Status(200).Json(lcJsonData)
    ENDFUNC
    
    FUNCTION CreateUsuario(req, res) HELP "POST: usuarios"
        * Validar que hay datos JSON
        IF !req.HasJsonBody()
            res.Status(400).Json('{"error":"Se requiere un cuerpo JSON válido"}')
            RETURN
        ENDIF
        
        * Obtener recursos globales
        LOCAL loConnection, loCache
        loConnection = THIS.GetGlobalResource("DatabaseConnection")
        loCache = THIS.GetGlobalResource("Cache")
        
        IF ISNULL(loConnection)
            res.Status(500).Json('{"error":"Servicio no disponible"}')
            RETURN
        ENDIF
        
        * Crear usuario...
        LOCAL lcSql
        lcSql = "INSERT INTO usuarios (nombre, email) VALUES (?, ?)"
        loConnection.Execute(lcSql, req.json.nombre, req.json.email)
        
        * Invalidar cache si existe
        IF !ISNULL(loCache) AND PEMSTATUS(loCache, "InvalidatePattern", 5)
            loCache.InvalidatePattern("usuarios*")
        ENDIF
        
        res.Status(201).Json('{"message":"Usuario creado correctamente"}')
    ENDFUNC
    
ENDDEFINE

DEFINE CLASS MyAppLifecycle AS ApplicationLifecycle OLEPUBLIC
    PROCEDURE OnApplicationStarting()
        THIS.LogInfo("Iniciando aplicación...")
        
        TRY
            * 1. Inicializar conexión de base de datos
            THIS.InitializeDatabase()
            
            * 2. Cargar configuración
            THIS.LoadApplicationConfig()
            
            * 3. Inicializar cache
            THIS.InitializeCache()
            
            * 4. Configurar servicios externos
            THIS.InitializeExternalServices()
            
            THIS.LogInfo("Aplicación iniciada correctamente. Recursos: {0}", THIS.GetResourceNames())
            
        CATCH TO loEx
            THIS.LogError("Error al iniciar aplicación: {0}", loEx.Message)
            THROW loEx
        ENDTRY
    ENDPROC
    
    PROCEDURE OnApplicationStopping()
        THIS.LogInfo("Deteniendo aplicación...")
        
        * Cerrar conexiones de base de datos
        LOCAL loConnection
        loConnection = THIS.GetResource("DatabaseConnection")
        IF !ISNULL(loConnection)
            loConnection.Close()
            THIS.LogInfo("Conexión de base de datos cerrada")
        ENDIF
        
        * Limpiar cache
        LOCAL loCache
        loCache = THIS.GetResource("Cache")
        IF !ISNULL(loCache) AND PEMSTATUS(loCache, "SaveToDisk", 5)
            loCache.SaveToDisk()
            THIS.LogInfo("Cache guardado en disco")
        ENDIF
        
        THIS.LogInfo("Aplicación detenida correctamente")
    ENDPROC
    
    PROTECTED PROCEDURE InitializeDatabase()
        LOCAL loConnection
        loConnection = CREATEOBJECT("ADODB.Connection")
        loConnection.Open("Provider=SQLOLEDB;Server=localhost;Database=MyApp;Trusted_Connection=yes")
        THIS.SetResource("DatabaseConnection", loConnection)
        THIS.LogInfo("Conexión de base de datos inicializada")
    ENDPROC
    
    PROTECTED PROCEDURE LoadApplicationConfig()
        LOCAL loConfig
        loConfig = CREATEOBJECT("Empty")
        ADDPROPERTY(loConfig, "DefaultPageSize", 20)
        ADDPROPERTY(loConfig, "MaxUploadSize", 10485760)  && 10MB
        ADDPROPERTY(loConfig, "EnableCache", .T.)
        THIS.SetResource("AppConfig", loConfig)
        THIS.LogInfo("Configuración de aplicación cargada")
    ENDPROC
    
    PROTECTED PROCEDURE InitializeCache()
        LOCAL loCache
        loCache = CREATEOBJECT("ApplicationCache")  && Clase personalizada
        THIS.SetResource("Cache", loCache)
        THIS.LogInfo("Cache de aplicación inicializado")
    ENDPROC
    
    PROTECTED PROCEDURE InitializeExternalServices()
        * Configurar servicios externos, APIs, etc.
        LOCAL loEmailService
        loEmailService = CREATEOBJECT("EmailService")
        loEmailService.Configure("smtp.gmail.com", 587)
        THIS.SetResource("EmailService", loEmailService)
        THIS.LogInfo("Servicios externos configurados")
    ENDPROC
    
ENDDEFINE