Configuración de FoxServer

Versión: 2.0 Actualizado: Mayo 2025

Contenido

Estructura de Configuración
Configuración Básica del Servidor
Configuración CORS
Configuración de Controladores
Configuración de Middleware
Configuración SSL

El archivo JSON se genera automaticamente al crear un proyecto API o WEB con WinFx. No tienes que manipular nada del fichero a menos que sea estrictamente necesario, de lo contrario WinFx se encargará de actualizar el fichero tras cada compilación del proyecto.

Estructura de Configuración

FoxServer utiliza un archivo JSON para su configuración. Este archivo se genera automáticamente al compilar un proyecto de API o Web, y contiene toda la información necesaria para el funcionamiento del servidor.

El archivo de configuración se almacena en formato JSON y define todos los aspectos del servidor: controladores, rutas, middleware, seguridad y más.

Un ejemplo básico de archivo de configuración:

{
  "name": "masterdetail",
  "description": "proyecto api para demostrar el maestro detalle",
  "type": "api",
  "active": false,
  "host": "127.0.0.1",
  "port": 8080,
  "prefix": "",
  "issecure": false,
  "lang": "en",
  "namespace": "masterdetail",
  "dllpath": "F:\\A1\\testnewd\\masterdetail\\build\\Interop.masterdetail.dll",
  "publicdir": "",
  "priority": 999,
  "controllers": [
    /* Definición de controladores */
  ],
  "middleware": {
    /* Configuración de middleware */
  },
  "server": {
    /* Configuración del servidor */
  }
}

Configuración Básica del Servidor

Las propiedades principales de configuración del servidor son:

Propiedad	Descripción	Tipo
`name`	Nombre del proyecto/servidor	String
`description`	Descripción del proyecto	String
`type`	Tipo de proyecto (api o web)	String
`active`	Indica si el servidor está activo	Boolean
`host`	Dirección IP o hostname donde se ejecutará el servidor	String
`port`	Puerto en el que escuchará el servidor	Number
`prefix`	Prefijo para todas las rutas (ej: "/api")	String
`issecure`	Indica si se usa HTTPS	Boolean
`lang`	Idioma predeterminado	String
`namespace`	Espacio de nombres para la DLL	String
`dllpath`	Ruta a la DLL de interoperabilidad	String
`publicdir`	Directorio para archivos públicos (solo para proyectos web)	String
`priority`	Prioridad del servidor (para múltiples servidores)	Number

Ejemplo de configuración básica

{
  "name": "miapi",
  "description": "API para sistema de ventas",
  "type": "api",
  "active": true,
  "host": "0.0.0.0",
  "port": 8080,
  "prefix": "/api/v1",
  "issecure": false,
  "lang": "es",
  "namespace": "ventas",
  "dllpath": "C:\\proyectos\\ventas\\build\\Interop.ventas.dll",
  "publicdir": "",
  "priority": 1
}

Configuración CORS

Cross-Origin Resource Sharing (CORS) permite que tu API sea accesible desde dominios diferentes. FoxServer ofrece una configuración sencilla para CORS:

{
  "allowedorigins": "*",
  "allowedmethods": "GET,POST,PUT,PATCH,DELETE,OPTIONS,HEAD",
  "allowedheaders": "*"
}

Propiedad	Descripción
`allowedorigins`	Dominios permitidos para acceder a la API. Usa "*" para permitir cualquier origen o especifica dominios separados por comas.
`allowedmethods`	Métodos HTTP permitidos. Por defecto incluye todos los métodos comunes.
`allowedheaders`	Cabeceras permitidas en las solicitudes. Usa "*" para permitir cualquier cabecera.

Consejo: Para entornos de producción, es recomendable especificar exactamente los orígenes permitidos en lugar de usar el comodín "*".

Ejemplo de configuración CORS específica

{
  "allowedorigins": "https://miapp.com,https://admin.miapp.com",
  "allowedmethods": "GET,POST,PUT,DELETE",
  "allowedheaders": "Content-Type,Authorization,X-Requested-With"
}

Configuración de Controladores

Los controladores definen los endpoints de tu API. Cada controlador puede tener múltiples endpoints que se mapean a procedimientos en tu código VFP:

"controllers": [
  {
    "classname": "masterdetailBackendClass",
    "filename": "Main",
    "path": "main",
    "endpoints": [
      {
        "apiroute": "hello",
        "backendprocedure": "pHello",
        "httpmethod": "GET",
        "ispublic": true,
        "requiresauth": true
      },
      {
        "apiroute": "users/{id}",
        "backendprocedure": "pGetUser",
        "httpmethod": "GET",
        "ispublic": true,
        "requiresauth": true
      }
      // Más endpoints...
    ]
  }
  // Más controladores...
]

Propiedades de un Controlador

Propiedad	Descripción
`classname`	Nombre de la clase VFP que implementa el controlador
`filename`	Nombre del archivo (sin extensión)
`path`	Ruta relativa donde se encuentra el archivo
`endpoints`	Array de endpoints definidos para este controlador

Propiedades de un Endpoint

Propiedad	Descripción
`apiroute`	Ruta URL para acceder al endpoint (puede incluir parámetros como {id})
`backendprocedure`	Nombre del procedimiento VFP que se ejecutará
`httpmethod`	Método HTTP (GET, POST, PUT, DELETE, etc.)
`ispublic`	Indica si el endpoint es público
`requiresauth`	Indica si requiere autenticación
`parameters`	Parámetros esperados (opcional)
`description`	Descripción corta del endpoint
`documentation`	Documentación detallada

Ejemplo de un controlador completo

{
  "classname": "VentasControllerClass",
  "filename": "Ventas",
  "path": "ventas",
  "endpoints": [
    {
      "apiroute": "ventas",
      "backendprocedure": "GetDocumentos",
      "httpmethod": "GET",
      "ispublic": true,
      "requiresauth": true,
      "description": "Obtiene lista de documentos de venta",
      "documentation": "Este endpoint devuelve todos los documentos de venta filtrados por fecha"
    },
    {
      "apiroute": "ventas/{id}",
      "backendprocedure": "GetDocumento",
      "httpmethod": "GET",
      "ispublic": true,
      "requiresauth": true,
      "description": "Obtiene un documento específico"
    },
    {
      "apiroute": "ventas/{id}/pdf",
      "backendprocedure": "GenerarPDF",
      "httpmethod": "GET",
      "ispublic": true,
      "requiresauth": true,
      "description": "Genera PDF de una factura"
    }
  ]
}

Configuración de Middleware

El middleware permite procesar las solicitudes antes o después de que lleguen a los controladores. FoxServer incluye varios tipos de middleware configurables:

"middleware": {
  "auth": {
    "enabled": false,
    "loginendpoint": "auth/login",
    "secret": "",
    "timing": "pre",
    "tokenexpirationseconds": 7200,
    "type": "jwt"
  },
  "hooks": true,
  "logging": {
    "enabled": true,
    "fileprefix": "masterdetail",
    "format": "Detailed",
    "options": {
      "debug": true,
      "errors": true,
      "performance": true,
      "requests": true,
      "responses": true
    },
    "path": "f:\\a1\\testnewd\\masterdetail\\logs\\",
    "timing": "pre"
  },
  "webhooks": {
    "enabled": false,
    "global": {
      "backoff": [5, 15, 30],
      "logging": {
        "enabled": true,
        "path": "logs/webhooks/",
        "retentiondays": 30
      },
      "queue": {
        "batchsize": 10,
        "path": "queue/webhooks",
        "workers": 2
      },
      "retries": 3,
      "timeout": 30
    },
    "webhookendpoints": null
  }
}

Middleware de Autenticación

Propiedad	Descripción
`enabled`	Activa o desactiva la autenticación
`loginendpoint`	Ruta para el endpoint de login
`secret`	Clave secreta para firmar tokens JWT
`timing`	Momento de ejecución (pre o post)
`tokenexpirationseconds`	Tiempo de expiración del token en segundos
`type`	Tipo de autenticación (jwt)

Middleware de Logging

Propiedad	Descripción
`enabled`	Activa o desactiva el logging
`fileprefix`	Prefijo para los archivos de log
`format`	Formato de log (Simple, Detailed)
`options`	Opciones específicas de logging
`path`	Ruta donde se guardarán los logs
`timing`	Momento de ejecución (pre o post)

Middleware de Webhooks

Los webhooks permiten notificar a sistemas externos cuando ocurren eventos en tu API:

Propiedad	Descripción
`enabled`	Activa o desactiva los webhooks
`global`	Configuración global para todos los webhooks
`webhookendpoints`	Lista de endpoints de webhook

Ejemplo de configuración de autenticación

"auth": {
  "enabled": true,
  "loginendpoint": "auth/login",
  "secret": "mi_clave_secreta_muy_segura",
  "timing": "pre",
  "tokenexpirationseconds": 3600,
  "type": "jwt"
}

Configuración SSL

Para habilitar HTTPS en tu servidor, configura las siguientes propiedades:

{
  "issecure": true,
  "certificatename": "mi_certificado.pfx",
  "certificatepassword": "contraseña_del_certificado"
}

Propiedad	Descripción
`issecure`	Activa el modo HTTPS
`certificatename`	Nombre del archivo de certificado (.pfx o .p12)
`certificatepassword`	Contraseña del certificado

¡Importante! Nunca almacenes contraseñas de certificados en archivos de configuración que se suban a repositorios. Considera usar variables de entorno o configuración externa para información sensible.