📘 Flash — Librería para crear servidores HTTP aislados en Node.js

Flash es una librería escrita en TypeScript que permite crear servidores HTTP aislados, cada uno con su propio contexto, rutas, middlewares y configuración. Está diseñada para escenarios multi‑tenant, entornos de pruebas, simulación de microservicios y sistemas donde múltiples servidores deben convivir dentro del mismo proceso sin interferir entre sí.

🚀 Instalación

npm install @tuusuario/flash

🎯 Objetivo de Flash

Flash permite:

• Crear múltiples servidores HTTP independientes dentro del mismo proceso.
• Asignar a cada servidor un tenant, nombre y metadatos propios.
• Aislar rutas, middlewares y contexto por servidor.
• Generar configuración para proxies como Nginx o Traefik.
• Extender funcionalidad mediante plugins (logging, rate‑limit, métricas).
• Integrarse con namespaces de red o contenedores externos.

Flash NO intenta reemplazar Express o Fastify; su propósito es aislar servidores, no crear un framework web completo.

🧩 Conceptos clave

Servidor aislado

Cada instancia de FlashServer es un servidor HTTP independiente:

• Tiene su propio router.
• Tiene su propio contexto (tenantId, nombre, metadatos).
• Tiene su propio pipeline de middlewares.
• Escucha en un puerto distinto.

Contexto

Cada petición recibe un objeto context con información del servidor:

req.context.name
req.context.tenantId
req.context.metadata

Plugins

Flash incluye plugins listos para usar:

• Logging
• Rate limiting
• Métricas

Y permite crear plugins personalizados fácilmente.

Integración con red

Flash puede generar configuraciones para:

• Nginx
• Traefik

Esto permite mapear cada servidor interno a un dominio o IP externa.

📦 Uso básico

Crear un servidor Flash

import { Flash } from "@tuusuario/flash";

async function main() {
  const app = Flash.createServer({
    name: "api",
    tenantId: "tenant-001"
  });

  app.get("/", (req, res) => {
    res.end(`Hola desde ${req.context.name}`);
  });

  const port = await app.listen();
  console.log(`Servidor escuchando en el puerto ${port}`);
}

main();

🧭 Middlewares

Flash soporta middlewares estilo Express:

app.use((req, res, next) => {
  console.log("Petición recibida:", req.url);
  next();
});

Plugins incluidos

Logging

app.use(Flash.plugins.logging());

Rate limit

app.use(Flash.plugins.rateLimit({
  max: 100,
  windowMs: 60_000
}));

Métricas

app.use(Flash.plugins.metrics());

🛣️ Rutas

Flash soporta los métodos HTTP más comunes:

app.get("/hola", (req, res) => res.end("Hola"));
app.post("/data", (req, res) => res.end("POST recibido"));
app.put("/item", (req, res) => res.end("PUT recibido"));
app.delete("/item", (req, res) => res.end("DELETE recibido"));

🧪 Multi‑tenant: varios servidores en un solo proceso

import { Flash } from "@tuusuario/flash";

async function main() {
  for (let i = 0; i < 3; i++) {
    const app = Flash.createServer({
      name: `server-${i}`,
      tenantId: `T${i}`
    });

    app.get("/", (req, res) => {
      res.end(`Hola desde ${req.context.name}`);
    });

    const port = await app.listen();
    console.log(`Servidor ${i} en puerto ${port}`);
  }
}

main();

🌐 Integración con Nginx

Flash puede generar automáticamente la configuración:

import { Flash } from "@tuusuario/flash";

const registry = new Flash.net.BindingRegistry();

registry.add({
  server: app,
  externalHost: "api.example.com"
});

const nginxConfig = Flash.net.generateNginxConfig(registry);
console.log(nginxConfig);

Ejemplo generado:

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
    }
}

🧱 Arquitectura interna

Flash está organizado en módulos:

• core/ → servidor, router, aislamiento, contexto
• plugins/ → extensiones oficiales
• net/ → integración con red y proxies
• utils/ → tipos, errores, utilidades

Esto permite extender Flash sin romper su núcleo.

🛠️ Crear un plugin personalizado

function customPlugin() {
  return (req, res, next) => {
    req.context.metadata.timestamp = Date.now();
    next();
  };
}

app.use(customPlugin());

📚 API de Flash

Flash.createServer(options)

Crea un servidor aislado.

options:

• name: string
• tenantId?: string
• port?: number
• metadata?: Record<string, unknown>

Métodos del servidor

• get(path, handler)
• post(path, handler)
• put(path, handler)
• delete(path, handler)
• use(middleware)
• listen(): Promise<number>
• close(): Promise<void>
• getPort()
• getName()
• getTenantId()

🧪 Ejemplo completo

import { Flash } from "@tuusuario/flash";

async function main() {
  const app = Flash.createServer({
    name: "api",
    tenantId: "A"
  });

  app.use(Flash.plugins.logging());
  app.use(Flash.plugins.rateLimit({ max: 10, windowMs: 5000 }));

  app.get("/", (req, res) => {
    res.end(`Hola desde ${req.context.name}`);
  });

  const port = await app.listen();
  console.log(`Servidor listo en puerto ${port}`);
}

main();