JERK Framework v2.4.1

¿Nuevo en JERK? Comienza tu proyecto rápidamente con nuestro Starter Kit

Nuestro Starter Kit en standard/server.js es la forma más rápida de comenzar con JERK. Viene con todas las funcionalidades del framework ya configuradas, permitiéndote concentrarte en desarrollar tu aplicación en lugar de configurar infraestructura.

Características del Starter Kit:

• Configuración lista para usar con todos los componentes principales
• Carga de rutas desde archivo JSON (routes.json)
• Sistema de controladores preconfigurado
• Middlewares esenciales ya integrados (autenticación, CORS, compresión, firewall, etc.)
• Sistema de logging y manejo de errores implementado
• NUEVO: Arquitectura completa MVC con modelos y soporte para bases de datos
• NUEVO: Compatible con qbuilderjs para consultas SQL seguras y eficientes

Cómo comenzar:

1. Edita el archivo routes.json para definir tus rutas y asociarlas a tus controladores

Ejemplo básico de routes.json:

[
  {
    "path": "/",
    "method": "GET",
    "controller": "HomeController",
    "handler": "index",
    "contentType": "text/html"
  },
  {
    "path": "/api/users",
    "method": "GET",
    "controller": "UserController",
    "handler": "getAllUsers",
    "contentType": "application/json"
  }
]

2. Crea tus controladores según las rutas definidas

Por ejemplo, para la ruta principal "/", crea un archivo HomeController.js:

class HomeController {
  index(req, res) {
    res.render('index.html', { data: 'Hola' });
  }
}

module.exports = new HomeController();

3. ¡Tu aplicación estará listo para usar!

El Starter Kit incluye controladores de ejemplo para que puedas ver cómo funciona el sistema.

Ejemplo de Rutas Estáticas

Desde la versión 2.1.8, JERK Framework soporta rutas estáticas para servir archivos desde directorios locales:

En routes.json:

[
  {
    "path": "/static",
    "method": "GET",
    "static": {
      "dir": "./public",
      "index": ["index.html", "index.htm"],
      "cacheControl": "public, max-age=3600"
    }
  },
  {
    "path": "/assets",
    "method": "GET",
    "static": {
      "dir": "./public",
      "index": [],
      "cacheControl": "public, max-age=86400"
    }
  }
]

Usando addRoute():

// Ruta estática para servir archivos desde ./public
server.addRoute({
  method: 'GET',
  path: '/static',
  static: {
    dir: './public',
    index: ['index.html'],
    cacheControl: 'public, max-age=3600'
  }
});

// Ruta estática para servir archivos JS, CSS e imágenes
server.addRoute('GET', '/assets', {
  static: {
    dir: './public/assets',
    index: [],
    cacheControl: 'public, max-age=86400'
  }
});

Visita nuestra página web: https://jerk.page.gd/ Repositorio oficial: https://gitlab.com/bytedogssyndicate1/jerk/

Características

• Arquitectura Modular: Componentes independientes para mayor flexibilidad
• Seguridad Avanzada: Firewall integrado (WAF) con detección de ataques
• Sistema de Hooks: Similar al sistema de WordPress para extensibility
• Autenticación Flexible: Soporte para JWT, API Keys, Basic Auth, OAuth2, OpenID Connect
• Almacenamiento de Tokens: Soporte para memoria, JSON, SQLite y MariaDB
• Enrutamiento Avanzado: Soporte para rutas parametrizadas, anidadas y estáticas
• Soporte para Frontend: Capacidad de servir contenido HTML y otros tipos de contenido
• Configuración de Content-Type: Especificación de headers Content-Type en routes.json
• Middlewares Integrados: CORS, rate limiting, compresión, firewall, etc.
• Gestión de Controladores: Carga dinámica de controladores desde archivos
• Carga de Rutas: Definición de rutas desde archivos JSON
• Sistema de Sesiones: Gestión completa de sesiones con soporte para autenticación
• Motor de Plantillas MVC: Sistema profesional de vistas con soporte para filtros, helpers y hooks
• Arquitectura de Modelos Completa (MVC): Capa de modelos para la lógica de negocio y acceso a datos
• Sistema de Adaptadores de Base de Datos: Soporte para múltiples motores de base de datos (MariaDB, MySQL, etc.)
• Compatible con qbuilderjs: Soporte para integrar el QueryBuilder externo qbuilderjs para construir consultas SQL complejas de manera segura y eficiente
• Servicio de Archivos Estáticos: Soporte para servir archivos desde directorios locales con configuración flexible
• Extensibilidad: Sistema de hooks y filters para personalización

Instalación

npm install jerkjs

Uso Básico

const { APIServer, Router, Logger } = require('jerkjs');

// Crear instancia del servidor
const server = new APIServer({
  port: 3000,
  host: 'localhost'
});

// Crear instancia del logger
const logger = new Logger({ level: 'info' });

// Definir rutas
server.addRoute('GET', '/', (req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ message: '¡Hola Mundo!' }));
});

// Iniciar el servidor
server.start();

Componentes Principales

APIServer

Servidor HTTP/HTTPS básico con soporte para rutas parametrizadas, middlewares y configuración avanzada.

Router

Sistema de enrutamiento avanzado con soporte para rutas anidadas y prefijos.

Authenticator

Middleware de autenticación con soporte para múltiples métodos (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect).

SecurityEnhancedServer

Servidor con funcionalidades de seguridad avanzada (WAF) integradas.

RouteLoader

Carga de rutas desde archivos JSON con soporte para autenticación, controladores y especificación de content-type.

TokenManager

Gestión de tokens JWT con diferentes tipos de almacenamiento (memoria, JSON, SQLite, MariaDB).

Firewall

Middleware de firewall con detección de patrones de ataque y listas blancas/negras.

Hooks System

Sistema de hooks y filters similar al de WordPress para extensibilidad.

SessionManager

Sistema completo de gestión de sesiones con soporte para autenticación basada en sesiones.

ViewEngine

Motor de plantillas profesional con soporte para filtros, helpers, condiciones, bucles y hooks.

ControllerBase

Controlador base que facilita el desarrollo de controladores MVC con soporte para vistas.

Seguridad

El framework incluye múltiples capas de seguridad:

• Web Application Firewall (WAF): Detección de SQL injection, XSS, path traversal, etc.
• Rate Limiting: Limitación de peticiones por IP o usuario
• Firewall: Bloqueo automático por intentos fallidos
• Listas Blancas/Negras: Control de acceso por IP
• Auditoría de Seguridad: Registro de eventos de seguridad
• Autenticación Robusta: Soporte para múltiples métodos de autenticación

Sistema de Hooks

El framework incluye un sistema de hooks y filters similar al de WordPress:

const { hooks } = require('jerkjs');

// Registrar una acción
hooks.addAction('firewall_request_blocked', (rule, clientIP, req, res) => {
  console.log(`Solicitud bloqueada: ${rule.name} para IP: ${clientIP}`);
});

// Registrar un filtro
hooks.addFilter('session_create_data', (userData, req) => {
  return {
    ...userData,
    ipAddress: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
    createdAt: new Date().toISOString()
  };
});

Motor de Plantillas MVC

El framework incluye un motor de plantillas profesional con soporte para:

• Variables: {{variable}}
• Condiciones: {{if variable}}contenido{{endif}}
• Bucles: {{foreach:array}}contenido{{endforeach}}
• Inclusiones: {{include:header}}
• Filtros: {{variable|upper}}
• Helpers personalizados

Gestión de Sesiones

El framework incluye un sistema completo de gestión de sesiones:

const { SessionManager } = require('jerkjs');

const sessionManager = new SessionManager({
  secret: 'your-session-secret',
  timeout: 3600000 // 1 hora
});

// Usar como middleware
server.use(sessionManager.middleware());

Ejemplos

El proyecto incluye varios ejemplos completos:

• v2_json_auth: Autenticación JWT con tokens almacenados en JSON
• v2_mariadb_auth: Autenticación JWT con tokens almacenados en MariaDB
• v2_sqlite_auth: Autenticación JWT con tokens almacenados en SQLite
• public: API pública de ejemplo con CORS y rate limiting
• frontend: Ejemplo de servidor que combina API y frontend con diferentes content-types
• hooks: Ejemplo avanzado de uso del sistema de hooks con logging y seguimiento de solicitudes

Para ver los ejemplos completos, visita los directorios v2examplle/ y examples/.

Documentación

Además de la documentación en el README, el proyecto incluye documentación adicional:

• Guía de inicio rápido: docs/guia_inicio_rapido_jerkjs.md - Una guía completa para empezar rápidamente con JERKJS, incluyendo formatos de archivos, estructura de controladores, motor de plantillas y sistema de hooks.

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o envía un pull request en GitLab.

Licencia

Apache 2.0

Arquitectura de Modelos (MVC)

JERK Framework v2.2.0 introduce una arquitectura completa de modelos que completa el patrón MVC. Los modelos permiten encapsular la lógica de negocio y el acceso a datos en componentes reutilizables.

Ejemplo de Modelo Simple con MariaDB

const { ModelBase, MariaDBAdapter } = require('jerkjs');

// Definir un modelo para usuarios
class UserModel extends ModelBase {
  constructor(options = {}) {
    super({
      ...options,
      tableName: options.tableName || 'users'
    });

    // Definir campos del modelo
    this.fields = {
      id: { type: 'integer', primaryKey: true, autoIncrement: true },
      username: { type: 'string', required: true },
      email: { type: 'string', required: true },
      password: { type: 'string', required: true },
      createdAt: { type: 'datetime', default: 'CURRENT_TIMESTAMP' }
    };
  }

  // Método personalizado para encontrar usuario por email
  async findByEmail(email) {
    return await this.findOne({ email });
  }

  // Método personalizado para crear usuario con validación
  async createUser(userData) {
    // Validar datos antes de crear
    const validation = this.validate('create', userData);
    if (!validation.isValid) {
      throw new Error(`Validación fallida: ${validation.errors.join(', ')}`);
    }

    return await this.create(userData);
  }
}

// Configurar el adaptador de MariaDB
const dbConfig = {
  host: 'localhost',
  user: 'tu_usuario',
  password: 'tu_contraseña',
  database: 'tu_base_de_datos'
};

const mariaDBAdapter = new MariaDBAdapter(dbConfig);

// Crear instancia del modelo con el adaptador
const userModel = new UserModel({
  adapter: mariaDBAdapter,
  tableName: 'users'
});

// Uso del modelo
async function ejemploUsoModelo() {
  try {
    // Crear un nuevo usuario
    const nuevoUsuario = await userModel.createUser({
      username: 'juan.perez',
      email: '[email protected]',
      password: 'contraseña_segura'
    });

    console.log('Usuario creado:', nuevoUsuario);

    // Buscar usuario por email
    const usuario = await userModel.findByEmail('[email protected]');
    console.log('Usuario encontrado:', usuario);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

Uso de Modelos en Controladores con loadModel

JERK Framework proporciona un helper loadModel en el ControllerBase para facilitar la carga y uso de modelos en los controladores:

const ControllerBase = require('jerkjs').ControllerBase;

class UserController extends ControllerBase {
  constructor() {
    super();

    // Cargar el modelo de usuario
    this.userModel = this.loadModel('UserModel', {
      // Opciones del modelo
    });
  }

  async getAllUsers(req, res) {
    try {
      // Usar el modelo para obtener usuarios
      const users = await this.userModel.find({});

      this.json(res, { success: true, data: users });
    } catch (error) {
      this.json(res, { success: false, error: error.message }, 500);
    }
  }

  async getUserById(req, res) {
    try {
      const userId = req.params.id;

      // Usar el modelo para encontrar un usuario específico
      const user = await this.userModel.findOne({ id: userId });

      if (!user) {
        this.json(res, { success: false, error: 'Usuario no encontrado' }, 404);
        return;
      }

      this.json(res, { success: true, data: user });
    } catch (error) {
      this.json(res, { success: false, error: error.message }, 500);
    }
  }

  async createUser(req, res) {
    try {
      // Usar el modelo para crear un nuevo usuario
      const newUser = await this.userModel.createUser(req.body);

      this.json(res, { success: true, data: newUser }, 201);
    } catch (error) {
      this.json(res, { success: false, error: error.message }, 400);
    }
  }
}

module.exports = new UserController();

Documentación del Framework

Para una descripción detallada de la arquitectura y componentes del framework, consulta el archivo JERK_FRAMEWORK_DOCUMENTATION.md.