BLACKCOFFEE

Overview

BlackCoffee es un Application Server de próxima generación construido con Insitu Framework. Desplegá múltiples aplicaciones con aislamiento lógico, hot reload, y gestión centralizada de bases de datos. La versión v2.12.0 incluye Scheduler Extension para tareas programadas (cron), Route Statistics para métricas en tiempo real, y aislamiento de procesos con child_process.fork().

System Requirements

Quick Start

1. Clonar el repositorio
2. Ejecutar first-start (crea certificados y directorios)
3. Iniciar el servidor
4. Acceder al admin console

// Clonar
$ git clone https://gitlab.com/bytedogssyndicate1/bc2

// First Start (crea certificados y directorios)
$ npm run first-start

// Iniciar
$ node server.js

// Output:
[BlackCoffee] Server initialized
[BlackCoffee] HTTPS on port 9791
[BlackCoffee] Admin: https://localhost:9791/admin
[BlackCoffee] ✓ Ready
                    

Installation

Prerequisites

• Node.js 22.0.0+
• npm
• Git

$ git clone https://gitlab.com/bytedogssyndicate1/bc2
$ cd bc2
$ npm run first-start
$ node server.js
                    

Server Access

Features

Architecture

Directory Structure

blackcoffee/
├── server.js                    # Entry point
├── manifests/                   # Manifiestos inmutables
│   └── {app-name}/{version}/
│       └── manifest.json
├── apps/                        # Código de aplicaciones
│   └── {app-name}/{version}/
│       ├── controllers/
│       ├── models/
│       ├── routes/
│       └── public/
├── core/                        # Core del framework
│   ├── blackcoffee-core/        # Core library
│   ├── appLoader.js
│   ├── IsolatedAppLoader.js     # Aislamiento de procesos
│   ├── hotReload.js
│   ├── databasePoolManager.js
│   ├── QueueManager.js
│   ├── PostgresAdapter.js
│   └── RedisAdapter.js
├── includes/                    # Middleware y utilidades
│   ├── scheduler-extension.js   # Tareas programadas
│   ├── route-stats.js           # Estadísticas de rutas
│   ├── loginRateLimiter.js
│   ├── adminAuth.js
│   └── sessions.js
├── config/
│   ├── server.json
│   ├── database.json
│   └── queues.json
└── certs/                       # Certificados SSL
                    

Process Isolation (v2.6.0)

BlackCoffee v2.6.0 introduce aislamiento real de procesos usando child_process.fork(). Cada aplicación aislada corre en un proceso separado con su propio espacio de memoria.

Enable Isolation

{
  "name": "mi-app",
  "version": "1-0-0",
  "blackcoffee": {
    "useVM": true
  }
}
                    

Benefits

• Isolated Memory - Cada app tiene su own heap
• No Shared Globals - No puede afectar global.dbPoolManager
• No Shared Module Cache - Cada app tiene su propio cache
• No Prototype Pollution - Prototype chain aislada
• Crash Isolation - Si una app crashea, las otras no se afectan

IPC Communication

El servidor principal y los workers se comunican mediante mensajes IPC:

┌─────────────────────────────────────────────────────────┐
│              BlackCoffee Server (Main Process)          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │  App 1      │  │  App 2      │  │  App 3      │    │
│  │  Worker     │  │  Worker     │  │  Worker     │    │
│  │  (PID:123)  │  │  (PID:124)  │  │  (PID:125)  │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │ IPC            │ IPC            │ IPC        │
│         └────────────────┴────────────────┘            │
└─────────────────────────────────────────────────────────┘
                    

Scheduler Extension (v2.12.0)

BlackCoffee v2.12.0 introduce el sistema de programación de tareas para jobs recurrentes. Construido sobre QueueManager, permite ejecutar tareas con cron expressions, intervalos o delays.

Features

• Cron Expressions - Programá con sintaxis cron (0 */15 * * * *)
• Interval Jobs - Ejecutá cada X tiempo (30s, 5m, 1h)
• Delay Jobs - Ejecución única después de un delay
• Persistent - Los jobs se guardan en BD, sobreviven a reinicios
• Task Management Dashboard - Gestioná tareas desde /tasks

Example Usage

const scheduler = require('./includes/scheduler-extension');

// Inicializar
await scheduler.init({
  queue: 'otrack-tasks',
  pool: 'otrack-db',
  concurrency: 2
});

// Programar con cron (cada 15 minutos)
scheduler.schedule('0 */15 * * * *', 'detect-abandoned-carts', {}, {
  name: 'detect-abandoned-carts',
  timezone: 'America/Santiago'
});

// Programar con intervalo (cada hora)
scheduler.every('1h', 'cleanup-sessions', {}, {
  name: 'cleanup-expired-sessions'
});

// Programar con delay (ejecutar en 1 hora)
scheduler.delay(3600000, 'send-reminder', {
  userId: 123
});
                    

Scheduled Jobs Example (OTrack)

Route Statistics (v2.10.0)

BlackCoffee v2.10.0 introduce estadísticas de rendimiento en tiempo real por ruta. Monitoreá el performance de tus endpoints con métricas detalladas.

API Endpoints

Metrics Captured

• count - Total de requests por ruta
• rps - Requests por segundo (ventana deslizante de 1 min)
• avgMs - Tiempo promedio de respuesta en milisegundos
• totalMs - Tiempo total acumulado
• lastAccess - Timestamp del último acceso
• createdAt - Cuando se registró la ruta por primera vez

Example Response

{
  "success": true,
  "data": [
    {
      "method": "POST",
      "path": "/api/admin/auth/login",
      "count": 50,
      "rps": 5,
      "avgMs": 15,
      "totalMs": 750,
      "lastAccess": "2026-02-23T16:00:00.000Z",
      "createdAt": "2026-02-23T15:00:00.000Z"
    }
  ],
  "timestamp": "2026-02-23T16:00:01.000Z"
}
                    

Authentication & Sessions

BlackCoffee soporta dos sistemas de autenticación independientes:

System 1: Session Manager del Core

Usado por el dashboard administrativo (/admin). Almacena sesiones en memoria.

• Cookie: blackcoffee_admin_session
• Default User: admin / bl4ckc0ff33
• ⚠️ IMPORTANTE: Cambiar contraseña inmediatamente

System 2: Database Sessions + JWT (Recomendado para Apps)

Usado por otrack y woo-analytics. Sesiones persistentes en base de datos.

• Persistence: Sobrevive a reinicios del servidor
• Auditing: Tracking completo de actividad
• JWT Support: Para APIs y mobile apps
• Invalidation: Revocación controlada de sesiones

Database Structure

-- Tabla de usuarios
CREATE TABLE users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(50) UNIQUE NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  role VARCHAR(20) DEFAULT 'user',
  active TINYINT(1) DEFAULT 1,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  last_login DATETIME NULL
);

-- Tabla de tokens JWT
CREATE TABLE jwt_tokens (
  id INT AUTO_INCREMENT PRIMARY KEY,
  user_id INT NOT NULL,
  token VARCHAR(255) NOT NULL,
  token_hash VARCHAR(64) NOT NULL,
  expires_at DATETIME NOT NULL,
  issued_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  revoked TINYINT(1) DEFAULT 0,
  ip_address VARCHAR(45),
  user_agent TEXT,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

-- Tabla de sesiones
CREATE TABLE sessions (
  id VARCHAR(64) PRIMARY KEY,
  user_id INT NOT NULL,
  token VARCHAR(128) UNIQUE NOT NULL,
  data TEXT,
  expires_at DATETIME NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);
                    

Change Password

// CLI
$ node cli/admin-users.js reset-password admin NuevaPassword123!

// API
POST /api/admin/auth/change-password
{
  "currentPassword": "bl4ckc0ff33",
  "newPassword": "MiNuevaPassword123!"
}
                    

Docker Deployment

BlackCoffee incluye una imagen Docker minimalista (~257MB) optimizada para producción.

Quick Start

// Build image
$ docker build -f docker/Dockerfile -t blackcoffee:latest .

// Run container
$ docker run -d --name blackcoffee-server \
  -p 9791:9791 -p 9999:9999 \
  --restart unless-stopped \
  blackcoffee:latest

// Docker Compose
$ cd docker
$ docker compose up -d
                    

Access

⚠️ Security Warning: Admin Console (Port 9999)

Environment Variables

API Reference

Admin API

Database API

Queues API

Stats API (v2.10.0)

Scheduler API (v2.12.0)

CLI Commands

Application

Database

Queues

Server

Admin Users

Database Pools

Supported Databases

• SQLite - File-based, development
• MariaDB - Production MySQL-compatible
• MySQL - Open-source RDBMS
• PostgreSQL - Production, complex data
• Memory - In-memory caching
• Redis - Key-value store, high-performance

{
  "pools": {
    "default": {
      "type": "sqlite",
      "filename": "data/app.sqlite"
    },
    "production": {
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "user": "blackcoffee_app",
      "password": "secret",
      "database": "myapp_prod"
    },
    "cache": {
      "type": "redis",
      "host": "localhost",
      "port": 6379
    }
  }
}
                    

Isolated Helpers (v2.7.0)

Las aplicaciones aisladas (useVM: true) pueden acceder a Database Pools y Queues vía IPC:

// Database Helper
const pools = await global.blackcoffee.db.listPools();
const users = await global.blackcoffee.db.query(
  'default',
  'SELECT * FROM users WHERE active = ?',
  [1]
);

// Queue Helper
const queues = await global.blackcoffee.queue.listQueues();
const jobId = await global.blackcoffee.queue.enqueue(
  'email-queue',
  'send-email',
  { to: 'user@example.com' }
);
                    

Roadmap

Progreso: 100% (8/8 fases completas)

Features by Version