jerkjs 2.0.0

package/examples/v2.1_openapi_demo/app.js

@@ -0,0 +1,296 @@
+/**
+ * Ejemplo de API con funcionalidades OpenAPI (v2.1.0)
+ * Demostrando la generación automática de documentación OpenAPI
+ */
+
+const {
+  APIServer,
+  Authenticator,
+  Logger,
+  OpenApiGenerator
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8096,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  // Crear instancia del autenticador
+  const authenticator = new Authenticator({ logger });
+
+  // Registrar estrategia de autenticación JWT
+  authenticator.use('jwt-openapi', authenticator.jwtStrategy('super-secret-key-for-openapi-example'));
+
+  try {
+    // Crear instancia del generador de OpenAPI
+    const openApiGenerator = new OpenApiGenerator({
+      title: 'API de Ejemplo con OpenAPI',
+      description: 'API que demuestra la funcionalidad OpenAPI del Framework API SDK',
+      version: '2.1.0',
+      servers: [
+        { url: 'http://localhost:8096', description: 'Servidor de desarrollo' }
+      ]
+    });
+
+    // Definir esquemas para la documentación
+    openApiGenerator.addSchema('User', {
+      type: 'object',
+      properties: {
+        id: { type: 'integer', example: 1 },
+        name: { type: 'string', example: 'John Doe' },
+        email: { type: 'string', example: 'john@example.com' },
+        role: { type: 'string', example: 'user' }
+      },
+      required: ['id', 'name', 'email']
+    });
+
+    openApiGenerator.addSchema('Product', {
+      type: 'object',
+      properties: {
+        id: { type: 'integer', example: 1 },
+        name: { type: 'string', example: 'Laptop' },
+        price: { type: 'number', example: 999.99 },
+        category: { type: 'string', example: 'Electronics' }
+      },
+      required: ['id', 'name', 'price']
+    });
+
+    openApiGenerator.addSchema('LoginRequest', {
+      type: 'object',
+      properties: {
+        username: { type: 'string', example: 'admin' },
+        password: { type: 'string', example: 'password' }
+      },
+      required: ['username', 'password']
+    });
+
+    openApiGenerator.addSchema('LoginResponse', {
+      type: 'object',
+      properties: {
+        message: { type: 'string', example: 'Inicio de sesión exitoso' },
+        token: { type: 'string', example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' },
+        user: { $ref: '#/components/schemas/User' }
+      }
+    });
+
+    // Agregar rutas a la documentación OpenAPI
+    openApiGenerator.addRoute({
+      path: '/',
+      method: 'GET',
+      config: {
+        summary: 'Página de inicio',
+        description: 'Devuelve información básica sobre la API y sus funcionalidades OpenAPI',
+        responses: {
+          '200': {
+            description: 'Información de la API',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    message: { type: 'string' },
+                    features: { type: 'array', items: { type: 'string' } },
+                    timestamp: { type: 'string', format: 'date-time' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/login',
+      method: 'POST',
+      config: {
+        summary: 'Iniciar sesión',
+        description: 'Autenticación de usuario y obtención de token JWT',
+        requestBody: {
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/LoginRequest' }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Inicio de sesión exitoso',
+            content: {
+              'application/json': {
+                schema: { $ref: '#/components/schemas/LoginResponse' }
+              }
+            }
+          },
+          '401': {
+            description: 'Credenciales inválidas'
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/users',
+      method: 'GET',
+      config: {
+        summary: 'Obtener usuarios',
+        description: 'Lista de usuarios registrados (requiere autenticación JWT)',
+        security: [{ bearerAuth: [] }],
+        responses: {
+          '200': {
+            description: 'Lista de usuarios',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/User' }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    openApiGenerator.addRoute({
+      path: '/products',
+      method: 'GET',
+      config: {
+        summary: 'Obtener productos',
+        description: 'Lista de productos disponibles (requiere autenticación JWT)',
+        security: [{ bearerAuth: [] }],
+        responses: {
+          '200': {
+            description: 'Lista de productos',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: { $ref: '#/components/schemas/Product' }
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    // Agregar esquema de seguridad
+    openApiGenerator.addSecurityScheme('bearerAuth', {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      description: 'Autenticación por token JWT'
+    });
+
+    // Agregar rutas de documentación al servidor
+    openApiGenerator.addDocumentationRoute(server);
+
+    // Ruta pública
+    server.addRoute('GET', '/', (req, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'API con funcionalidades OpenAPI (v2.1.0)',
+        features: [
+          'Generación automática de documentación OpenAPI 3.0',
+          'Interfaz Swagger UI interactiva',
+          'Esquemas de datos definidos',
+          'Documentación de seguridad',
+          'Especificación de endpoints, parámetros y respuestas'
+        ],
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    // Ruta de login
+    server.addRoute('POST', '/login', (req, res) => {
+      let body = req.body;
+      
+      // Si body es string, intentar parsear como JSON
+      if (typeof body === 'string') {
+        try {
+          body = JSON.parse(body);
+        } catch (parseError) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Formato de solicitud inválido' }));
+          return;
+        }
+      }
+      
+      const { username, password } = body;
+
+      // Simulación de autenticación
+      if (username === 'admin' && password === 'password') {
+        // Generar token JWT
+        const jwt = require('jsonwebtoken');
+        const token = jwt.sign(
+          { userId: 1, username: username, role: 'admin' },
+          'super-secret-key-for-openapi-example',
+          { expiresIn: '1h' }
+        );
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          message: 'Inicio de sesión exitoso',
+          token: token,
+          user: { userId: 1, username: username, role: 'admin' }
+        }));
+      } else {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Credenciales inválidas' }));
+      }
+    });
+
+    // Ruta protegida - Usuarios
+    server.addRoute('GET', '/users', (req, res) => {
+      authenticator.authenticate('jwt-openapi')(req, res, () => {
+        if (req.user) {
+          const users = [
+            { id: 1, name: 'John Doe', email: 'john@example.com', role: 'admin' },
+            { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'user' },
+            { id: 3, name: 'Robert Johnson', email: 'robert@example.com', role: 'user' }
+          ];
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(users));
+        }
+      });
+    });
+
+    // Ruta protegida - Productos
+    server.addRoute('GET', '/products', (req, res) => {
+      authenticator.authenticate('jwt-openapi')(req, res, () => {
+        if (req.user) {
+          const products = [
+            { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
+            { id: 2, name: 'Mouse', price: 29.99, category: 'Electronics' },
+            { id: 3, name: 'Keyboard', price: 79.99, category: 'Electronics' }
+          ];
+
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(products));
+        }
+      });
+    });
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor OpenAPI iniciado en http://localhost:8096');
+    logger.info('Documentación OpenAPI disponible en http://localhost:8096/docs');
+    logger.info('Especificación OpenAPI disponible en http://localhost:8096/openapi.json');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2.1_openapi_demo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "api-sdk-openapi-demo",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con funcionalidades OpenAPI usando el Framework API SDK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "openapi",
+    "swagger",
+    "documentation",
+    "framework"
+  ],
+  "author": "API SDK Framework",
+  "license": "MIT",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}

package/examples/v2_cors/README.md

@@ -0,0 +1,82 @@
+# Ejemplo API con Funcionalidad CORS
+
+Este ejemplo demuestra cómo usar la funcionalidad CORS (Cross-Origin Resource Sharing) del Framework API SDK.
+
+## Características
+
+- Configuración de CORS con múltiples orígenes permitidos
+- Configuración de métodos HTTP permitidos
+- Configuración de encabezados permitidos y expuestos
+- Soporte para credenciales
+- Manejo de solicitudes preflight (OPTIONS)
+- Ejemplos de endpoints para probar diferentes aspectos de CORS
+
+## Configuración de CORS
+
+El ejemplo configura CORS con las siguientes opciones:
+
+- **Orígenes permitidos**: `['http://localhost:3000', 'http://localhost:8080', 'https://miapp.com']`
+- **Métodos permitidos**: `['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']`
+- **Encabezados permitidos**: `['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'X-Api-Key']`
+- **Encabezados expuestos**: `['X-Total-Count', 'X-Request-ID']`
+- **Credenciales**: `true` (permite el uso de cookies y encabezados de autenticación)
+- **Max Age**: `86400` (24 horas para caché de preflight)
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8094`
+
+## Endpoints
+
+- `GET /` - Página de inicio
+- `GET /public` - Endpoint público con CORS habilitado
+- `POST /data` - Endpoint para recibir datos con CORS
+- `GET /test-cors` - Endpoint para probar diferentes encabezados CORS
+
+## Pruebas de CORS
+
+Puedes probar la funcionalidad CORS desde una aplicación web alojada en uno de los orígenes permitidos:
+
+### Ejemplo de solicitud GET:
+```javascript
+fetch('http://localhost:8094/public')
+  .then(response => response.json())
+  .then(data => console.log(data));
+```
+
+### Ejemplo de solicitud POST con encabezados personalizados:
+```javascript
+fetch('http://localhost:8094/data', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Api-Key': 'tu-api-key'
+  },
+  body: JSON.stringify({ dato: 'ejemplo' })
+})
+.then(response => response.json())
+.then(data => console.log(data));
+```
+
+### Solicitudes complejas que disparan preflight:
+Las solicitudes con encabezados personalizados o ciertos tipos de contenido dispararán una solicitud OPTIONS preflight, que será manejada automáticamente por el middleware CORS.
+
+## Estructura del proyecto
+
+```
+examples/v2_cors/
+├── app.js              # Punto de entrada de la aplicación
+└── README.md
+```
+
+## Notas
+
+- El middleware CORS maneja automáticamente las solicitudes preflight (OPTIONS)
+- Los encabezados expuestos son accesibles desde el código JavaScript del cliente
+- Las credenciales permiten el uso de cookies y encabezados de autenticación
+- El encabezado `Access-Control-Max-Age` permite cachear la respuesta preflight

package/examples/v2_cors/app.js

@@ -0,0 +1,108 @@
+const {
+  APIServer,
+  Cors,
+  Logger
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8094,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Crear instancia del middleware CORS
+    const cors = new Cors({
+      origin: ['http://localhost:3000', 'http://localhost:8080', 'https://miapp.com'],
+      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowedHeaders: [
+        'Content-Type', 
+        'Authorization', 
+        'X-Requested-With',
+        'Accept', 
+        'X-Api-Key'
+      ],
+      exposedHeaders: [
+        'X-Total-Count',
+        'X-Request-ID'
+      ],
+      credentials: true,
+      maxAge: 86400 // 24 horas
+    });
+
+    // Aplicar el middleware CORS al servidor
+    server.use(cors.middleware());
+
+    // Agregar algunas rutas de ejemplo
+    server.addRoute('GET', '/', (req, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'API con CORS configurado',
+        endpoints: {
+          'GET /public': 'Endpoint público con CORS',
+          'POST /data': 'Endpoint para recibir datos con CORS',
+          'GET /test-cors': 'Endpoint para probar diferentes encabezados CORS'
+        }
+      }));
+    });
+
+    server.addRoute('GET', '/public', (req, res) => {
+      // Establecer encabezados personalizados que serán expuestos al cliente
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      res.setHeader('X-Total-Count', '100');
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Este es un endpoint público con CORS habilitado',
+        timestamp: new Date().toISOString(),
+        origin: req.headers.origin || 'no origin'
+      }));
+    });
+
+    server.addRoute('POST', '/data', (req, res) => {
+      // Establecer encabezados personalizados
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Datos recibidos exitosamente',
+        receivedData: req.body,
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    server.addRoute('GET', '/test-cors', (req, res) => {
+      // Endpoint para probar diferentes aspectos de CORS
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      res.setHeader('X-Custom-Header', 'custom-value'); // Este encabezado no está en exposedHeaders
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Prueba de CORS completada',
+        headers: req.headers,
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    // Manejar solicitudes OPTIONS para todos los endpoints (preflight)
+    // No es necesario agregar una ruta específica para '*' ya que el middleware CORS lo maneja
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor iniciado en http://localhost:8094');
+    logger.info('CORS configurado para orígenes: http://localhost:3000, http://localhost:8080, https://miapp.com');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2_cors/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "api-sdk-cors-example",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con funcionalidad CORS usando el Framework API SDK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "cors",
+    "cross-origin",
+    "security",
+    "framework"
+  ],
+  "author": "API SDK Framework",
+  "license": "MIT",
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}

package/examples/v2_json_auth/README.md

@@ -0,0 +1,83 @@
+# Ejemplo API con Autenticación JSON
+
+Este ejemplo demuestra cómo crear una API con autenticación basada en tokens estáticos almacenados en un archivo JSON utilizando el Framework API SDK.
+
+## Características
+
+- Autenticación JWT con tokens gestionados a través de almacenamiento JSON
+- Rutas protegidas y públicas
+- Sistema de login para obtener tokens
+- Controladores organizados por funcionalidad
+- Tokens almacenados en un archivo JSON local
+
+## Configuración
+
+1. Asegúrate de tener instaladas las dependencias del framework API SDK
+2. El archivo de tokens `tokens.json` se creará automáticamente al iniciar la aplicación
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8091`
+
+## Endpoints
+
+- `GET /` - Página de inicio (público)
+- `POST /login` - Iniciar sesión y obtener token (público)
+- `GET /protected` - Contenido protegido (requiere token)
+- `GET /profile` - Perfil de usuario (requiere token)
+- `GET /tokens` - Ver tokens almacenados (requiere token)
+
+## Ejemplo de uso
+
+1. Iniciar sesión:
+   ```bash
+   curl -X POST http://localhost:8091/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "password"}'
+   ```
+
+2. Acceder a contenido protegido:
+   ```bash
+   curl -X GET http://localhost:8091/protected \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+3. Ver perfil de usuario:
+   ```bash
+   curl -X GET http://localhost:8091/profile \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+4. Ver tokens almacenados:
+   ```bash
+   curl -X GET http://localhost:8091/tokens \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+## Estructura del proyecto
+
+```
+examples/v2_json_auth/
+├── app.js              # Punto de entrada de la aplicación
+├── routes.json         # Definición de rutas
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   ├── authController.js
+│   ├── protectedController.js
+│   ├── userController.js
+│   └── tokenController.js
+├── tokens.json         # Archivo de almacenamiento de tokens (generado automáticamente)
+└── README.md
+```
+
+## Seguridad
+
+- Los tokens se gestionan a través del sistema de TokenManager del framework
+- Los tokens expiran después de 1 hora
+- Las rutas protegidas requieren un token válido en el header Authorization
+- El archivo de tokens se almacena localmente en formato JSON

package/examples/v2_json_auth/app.js

@@ -0,0 +1,72 @@
+const {
+  APIServer,
+  Authenticator,
+  RouteLoader,
+  Logger,
+  TokenManager
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8091,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Crear instancia del TokenManager con almacenamiento en JSON
+    const tokenManager = new TokenManager({
+      storage: 'json',
+      tokenFile: './tokens.json'
+    });
+
+    // Crear instancia del autenticador
+    const authenticator = new Authenticator({ logger });
+
+    // Registrar estrategia de autenticación JWT que utiliza el TokenManager con almacenamiento JSON
+    authenticator.use('jwt-json', async (req, options = {}) => {
+      const authHeader = req.headers.authorization;
+      const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+      if (!token) {
+        return false;
+      }
+
+      // Validar el token usando el TokenManager
+      const secret = 'super-secret-key-for-json-example';
+      const decoded = tokenManager.validateToken(token, secret);
+      
+      if (decoded) {
+        // Verificar si el token está almacenado en el archivo JSON (opcional, dependiendo del enfoque)
+        // En este caso, simplemente verificamos que el token sea válido
+        req.user = decoded;
+        return true;
+      }
+
+      return false;
+    });
+
+    // Agregar el autenticador al servidor para que pueda ser usado por el RouteLoader
+    server.authenticator = authenticator;
+
+    // Cargar rutas desde archivo JSON
+    const routeLoader = new RouteLoader();
+    await routeLoader.loadRoutes(server, './routes.json');
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor iniciado en http://localhost:8091');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };