npm package: @pato404/flash
Description: Librería para crear servidores HTTP aislados en Node.js
Author: Tu Nombre
Latest version: 0.1.1

# 📘 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

```bash
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:

```ts
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

```ts
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:

```ts
app.use((req, res, next) => {
  console.log("Petición recibida:", req.url);
  next();
});
```

### Plugins incluidos

#### Logging

```ts
app.use(Flash.plugins.logging());
```

#### Rate limit

```ts
app.use(Flash.plugins.rateLimit({
  max: 100,
  windowMs: 60_000
}));
```

#### Métricas

```ts
app.use(Flash.plugins.metrics());
```

---

## 🛣️ Rutas

Flash soporta los métodos HTTP más comunes:

```ts
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

```ts
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:

```ts
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

```ts
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

```ts
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();
```