arckode-framework 1.0.0

package/kernel/middlewares.ts

@@ -0,0 +1,179 @@
+// kernel/middlewares.ts — Middlewares comunes
+// Cada middleware es una función pura: (req, next) => Response
+// Se registran en el Router: router.use(mw) o router.get('/', h, [mw1, mw2])
+
+import { gzip } from 'node:zlib'
+import { promisify } from 'node:util'
+import type { MiddlewareHandler, HttpRequest, HttpResponse } from './framework'
+import { AuthError, RateLimitError } from './framework'
+
+const gzipAsync = promisify(gzip)
+
+// ─── CORS ──────────────────────────────────────────────
+export function cors(options: {
+  origins?: string[]
+  methods?: string[]
+  headers?: string[]
+  credentials?: boolean
+} = {}): MiddlewareHandler {
+  const origins = options.origins ?? ['*']
+  const methods = options.methods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+  const headers = options.headers ?? ['Content-Type', 'Authorization']
+  const credentials = options.credentials ?? true
+
+  return async (req, next): Promise<HttpResponse> => {
+    if (req.method === 'OPTIONS') {
+      return {
+        status: 204,
+        body: null,
+        headers: {
+          'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origins.join(', '),
+          'Access-Control-Allow-Methods': methods.join(', '),
+          'Access-Control-Allow-Headers': headers.join(', '),
+          'Access-Control-Allow-Credentials': String(credentials),
+          'Access-Control-Max-Age': '86400',
+        },
+      }
+    }
+
+    const res = await next()
+    const corsHeaders: Record<string, string> = {
+      ...res.headers,
+      'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origins.join(', '),
+    }
+    if (credentials) corsHeaders['Access-Control-Allow-Credentials'] = 'true'
+    return { ...res, headers: corsHeaders }
+  }
+}
+
+// ─── Rate Limiting (en memoria) ────────────────────────
+export interface RateLimitMiddleware extends MiddlewareHandler {
+  reset(key: string): void
+}
+
+export function rateLimit(opts: {
+  windowMs?: number
+  max?: number
+  /**
+   * Función para derivar la clave de rate limit.
+   * Por defecto: IP del cliente.
+   * Para rate limit por usuario: `(req) => req.user?.id ?? req.headers['x-forwarded-for'] ?? 'anon'`
+   */
+  keyBy?: (req: HttpRequest) => string
+} = {}): RateLimitMiddleware {
+  const windowMs = opts.windowMs ?? 60000
+  const max = opts.max ?? 100
+  const keyBy = opts.keyBy ?? ((req) => (req.headers['x-forwarded-for'] ?? req.headers['host'] ?? 'unknown') as string)
+  const hits = new Map<string, { count: number; resetAt: number }>()
+
+  const mw = async (req: HttpRequest, next: () => Promise<HttpResponse>): Promise<HttpResponse> => {
+    const key = keyBy(req)
+    const now = Date.now()
+    const record = hits.get(key)
+
+    if (!record || now > record.resetAt) {
+      hits.set(key, { count: 1, resetAt: now + windowMs })
+      return next()
+    }
+
+    if (record.count >= max) {
+      throw new RateLimitError(`Too many requests. Max ${max} per ${windowMs / 1000}s`)
+    }
+
+    record.count++
+    return next()
+  }
+
+  const rlMw = mw as RateLimitMiddleware
+  rlMw.reset = (key: string) => { hits.delete(key) }
+  return rlMw
+}
+
+// ─── Request Logger ────────────────────────────────────
+export function requestLogger(logger: { info: (msg: string, meta?: any) => void }): MiddlewareHandler {
+  return async (req, next) => {
+    const start = Date.now()
+    logger.info(`${req.method} ${req.path}`, { requestId: req.id })
+
+    try {
+      const res = await next()
+      const duration = Date.now() - start
+      logger.info(`${req.method} ${req.path} ${res.status} ${duration}ms`, {
+        requestId: req.id,
+        status: res.status,
+        duration,
+      })
+      return res
+    } catch (error) {
+      const duration = Date.now() - start
+      logger.info(`${req.method} ${req.path} ERROR ${duration}ms`, {
+        requestId: req.id,
+        duration,
+        error: String(error),
+      })
+      throw error
+    }
+  }
+}
+
+// ─── Body Size Limit ───────────────────────────────────
+export function bodyLimit(maxBytes: number = 1024 * 1024): MiddlewareHandler {
+  return async (req, next) => {
+    const bodyStr = JSON.stringify(req.body ?? '')
+    if (bodyStr.length > maxBytes) {
+      return { status: 413, body: { error: `Request body too large. Max ${maxBytes} bytes` } }
+    }
+    return next()
+  }
+}
+
+// ─── Timeout ───────────────────────────────────────────
+export function timeout(ms: number = 5000): MiddlewareHandler {
+  return async (req, next) => {
+    const result = await Promise.race([
+      next(),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`Request timed out after ${ms}ms`)), ms)
+      ),
+    ])
+    return result
+  }
+}
+
+// ─── Require Auth (wrapper alrededor de auth.authenticate) ──
+export function requireAuth(authenticate: (...roles: string[]) => MiddlewareHandler, ...roles: string[]): MiddlewareHandler {
+  return authenticate(...roles)
+}
+
+// ─── Compression (gzip) ────────────────────────────────
+// Comprime la respuesta JSON si el cliente acepta gzip.
+// Solo aplica a respuestas JSON (no a SSE/streams).
+export function compression(opts: { threshold?: number } = {}): MiddlewareHandler {
+  const threshold = opts.threshold ?? 1024 // solo comprimir si supera 1KB
+
+  return async (req, next) => {
+    const res = await next()
+
+    // No comprimir streams SSE ni responses sin body
+    if (res.stream || res.body === null || res.body === undefined) return res
+
+    const acceptEncoding = req.headers['accept-encoding'] ?? ''
+    if (!acceptEncoding.includes('gzip')) return res
+
+    const bodyStr = JSON.stringify(res.body)
+    if (bodyStr.length < threshold) return res
+
+    const compressed = await gzipAsync(bodyStr)
+
+    return {
+      ...res,
+      body: compressed,
+      headers: {
+        ...res.headers,
+        'Content-Encoding': 'gzip',
+        'Content-Type': 'application/json',
+        'Content-Length': String(compressed.length),
+      },
+    }
+  }
+}

package/kernel/static.ts

@@ -0,0 +1,76 @@
+// kernel/static.ts — Servidor de archivos estáticos
+// Para modo monolito: sirve el frontend compilado desde el mismo servidor
+// SOLID: responsabilidad ÚNICA de servir archivos estáticos
+
+import { readFile, access } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+import type { Router, MiddlewareHandler } from './framework'
+
+export interface StaticOptions {
+  prefix?: string
+  fallback?: string
+  cacheControl?: string
+}
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.ts': 'application/javascript',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.webp': 'image/webp',
+  '.pdf': 'application/pdf',
+}
+
+export function serveStatic(
+  router: Router,
+  basePath: string,
+  options: StaticOptions = {},
+): void {
+  const { prefix = '', fallback, cacheControl = 'public, max-age=3600' } = options
+
+  // GET /* → intenta servir archivo estático
+  router.get(`${prefix}/:path(*)`, async (req) => {
+    const filePath = join(basePath, req.params['path'] || 'index.html')
+
+    try {
+      await access(filePath)
+      const content = await readFile(filePath)
+      const ext = extname(filePath).toLowerCase()
+      const mime = MIME_TYPES[ext] ?? 'application/octet-stream'
+
+      return {
+        status: 200,
+        body: content,
+        headers: {
+          'Content-Type': mime,
+          'Cache-Control': cacheControl,
+        } satisfies Record<string, string>,
+      }
+    } catch {
+      // Si no existe y hay fallback, servir el fallback (para SPA routing)
+      if (fallback) {
+        const fallbackPath = join(basePath, fallback)
+        try {
+          const content = await readFile(fallbackPath)
+          return {
+            status: 200,
+            body: content,
+            headers: { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache' } satisfies Record<string, string>,
+          }
+        } catch {
+          return { status: 404, body: { error: 'File not found' } }
+        }
+      }
+      return { status: 404, body: { error: 'File not found' } }
+    }
+  })
+}

package/kernel/testing.ts

@@ -0,0 +1,237 @@
+// kernel/testing.ts — Utilidades de testing para módulos Arckode
+// Uso: import { createTestClient, createRecordingOrm } from 'arckode-framework/testing'
+//
+// Diseño: sin dependencias externas, compatible con bun:test, Jest y Vitest.
+
+import { request as httpRequest } from 'node:http'
+import type { HttpRequest, HttpResponse, MiddlewareHandler } from './framework'
+import { Router, ORM, Logger, NodeServer } from './framework'
+import type { DbAdapter } from './framework'
+
+// ═══════════════════════════════════════════════════════════════
+// TEST CLIENT — hace requests a un Router sin levantar HTTP
+// ═══════════════════════════════════════════════════════════════
+
+export interface TestRequestOptions {
+  headers?: Record<string, string>
+  body?: unknown
+  query?: Record<string, string>
+  user?: { id: string; role: string }
+}
+
+export interface TestClient {
+  get(path: string, opts?: TestRequestOptions): Promise<HttpResponse>
+  post(path: string, opts?: TestRequestOptions): Promise<HttpResponse>
+  put(path: string, opts?: TestRequestOptions): Promise<HttpResponse>
+  patch(path: string, opts?: TestRequestOptions): Promise<HttpResponse>
+  delete(path: string, opts?: TestRequestOptions): Promise<HttpResponse>
+}
+
+/**
+ * Crea un cliente de test que dispara requests directamente al Router.
+ * No levanta ningún servidor HTTP.
+ *
+ * @example
+ * const client = createTestClient(router)
+ * const res = await client.get('/productos')
+ * expect(res.status).toBe(200)
+ */
+export function createTestClient(router: Router): TestClient {
+  const request = (method: string) => async (path: string, opts: TestRequestOptions = {}): Promise<HttpResponse> => {
+    return router.resolve(method, path, {
+      query: opts.query ?? {},
+      headers: opts.headers ?? {},
+      body: opts.body ?? null,
+      user: opts.user,
+    })
+  }
+
+  return {
+    get: request('GET'),
+    post: request('POST'),
+    put: request('PUT'),
+    patch: request('PATCH'),
+    delete: request('DELETE'),
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// RECORDING ORM — captura SQL sin tocar ninguna BD real
+// ═══════════════════════════════════════════════════════════════
+
+export interface RecordedCall {
+  sql: string
+  params: unknown[]
+  type: 'query' | 'run'
+}
+
+export interface RecordingDb extends DbAdapter {
+  calls: RecordedCall[]
+  lastSql(): string
+  lastParams(): unknown[]
+  reset(): void
+}
+
+/**
+ * Adapter de BD que registra las llamadas SQL en vez de ejecutarlas.
+ * Ideal para verificar qué SQL genera el ORM sin depender de SQLite/PostgreSQL.
+ *
+ * @example
+ * const db = createRecordingDb({ queryData: [{ id: '1', nombre: 'Laptop' }] })
+ * const orm = new ORM(db)
+ * await orm.findMany('Producto', { activo: true })
+ * expect(db.lastSql()).toContain('WHERE activo = ?')
+ */
+export function createRecordingDb(opts: {
+  countValue?: number
+  queryData?: unknown[]
+} = {}): RecordingDb {
+  const calls: RecordedCall[] = []
+
+  const db: RecordingDb = {
+    calls,
+    lastSql: () => calls.at(-1)?.sql ?? '',
+    lastParams: () => calls.at(-1)?.params ?? [],
+    reset: () => calls.splice(0, calls.length),
+
+    async query(sql: string, params: unknown[] = []) {
+      calls.push({ sql, params, type: 'query' })
+      if (sql.includes('COUNT(*)')) return [{ n: opts.countValue ?? 0 }]
+      return opts.queryData ?? []
+    },
+
+    async run(sql: string, params: unknown[] = []) {
+      calls.push({ sql, params, type: 'run' })
+      return { changes: 1, lastId: crypto.randomUUID() }
+    },
+
+    async close() {},
+  }
+
+  return db
+}
+
+// ═══════════════════════════════════════════════════════════════
+// AUTH MOCK — simula tokens sin necesitar JWT real
+// ═══════════════════════════════════════════════════════════════
+
+export interface MockAuthOptions {
+  user?: { id: string; role: string }
+}
+
+/**
+ * Middleware que simula autenticación en tests.
+ * Inyecta `req.user` directamente sin verificar JWT.
+ *
+ * @example
+ * router.get('/perfil', handler, [mockAuth({ user: { id: '1', role: 'admin' } })])
+ * const res = await client.get('/perfil')
+ */
+export function mockAuth(opts: MockAuthOptions = {}): MiddlewareHandler {
+  const user = opts.user ?? { id: 'test-user-id', role: 'user' }
+  return async (req, next) => {
+    req.user = user
+    return next()
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LOGGER SILENCIOSO — para que los tests no llenen la consola
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Logger que no imprime nada. Úsalo en tests para silenciar output.
+ *
+ * @example
+ * const logger = silentLogger()
+ * const service = new MiService(orm, logger)
+ */
+export function silentLogger(): Logger {
+  return new Logger('test', 'error')
+}
+
+// ═══════════════════════════════════════════════════════════════
+// INTEGRATION CLIENT — levanta HTTP real, prueba la pila completa
+// ═══════════════════════════════════════════════════════════════
+
+export interface IntegrationClient {
+  get(path: string, opts?: { headers?: Record<string, string>; query?: Record<string, string> }): Promise<{ status: number; body: unknown; headers: Record<string, string> }>
+  post(path: string, body?: unknown, opts?: { headers?: Record<string, string> }): Promise<{ status: number; body: unknown; headers: Record<string, string> }>
+  put(path: string, body?: unknown, opts?: { headers?: Record<string, string> }): Promise<{ status: number; body: unknown; headers: Record<string, string> }>
+  patch(path: string, body?: unknown, opts?: { headers?: Record<string, string> }): Promise<{ status: number; body: unknown; headers: Record<string, string> }>
+  delete(path: string, opts?: { headers?: Record<string, string> }): Promise<{ status: number; body: unknown; headers: Record<string, string> }>
+  stop(): Promise<void>
+}
+
+/**
+ * Levanta un servidor HTTP real en un puerto aleatorio y retorna un cliente HTTP.
+ * Prueba la pila completa: parsing del body, headers reales, middlewares, SSE, bodyLimit.
+ * Llama a `stop()` en el afterAll/teardown de tu suite.
+ *
+ * @example
+ * const app = await createIntegrationClient(router)
+ * const res = await app.post('/productos', { nombre: 'Laptop', precio: 999 })
+ * expect(res.status).toBe(201)
+ * await app.stop()
+ */
+export async function createIntegrationClient(router: Router): Promise<IntegrationClient> {
+  const logger = silentLogger()
+  // Puerto 0 = SO asigna uno libre automáticamente
+  const server = new NodeServer(0, logger)
+  await server.start((req) => router.resolve(req.method, req.path, req))
+  const actualPort = server.getPort()
+
+  const makeRequest = (
+    method: string,
+    path: string,
+    body?: unknown,
+    extraHeaders?: Record<string, string>,
+    query?: Record<string, string>,
+  ): Promise<{ status: number; body: unknown; headers: Record<string, string> }> => {
+    return new Promise((resolve, reject) => {
+      const qs = query && Object.keys(query).length > 0
+        ? '?' + new URLSearchParams(query).toString()
+        : ''
+
+      const bodyStr = body !== undefined ? JSON.stringify(body) : undefined
+
+      const req = httpRequest({
+        hostname: '127.0.0.1',
+        port: actualPort,
+        path: path + qs,
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(bodyStr ? { 'Content-Length': String(Buffer.byteLength(bodyStr)) } : {}),
+          ...extraHeaders,
+        },
+      }, (res) => {
+        const chunks: Buffer[] = []
+        res.on('data', (c: Buffer) => chunks.push(c))
+        res.on('end', () => {
+          const raw = Buffer.concat(chunks).toString()
+          let parsed: unknown = raw
+          try { parsed = JSON.parse(raw) } catch { /* texto plano */ }
+          resolve({
+            status: res.statusCode ?? 0,
+            body: parsed,
+            headers: res.headers as Record<string, string>,
+          })
+        })
+      })
+
+      req.on('error', reject)
+      if (bodyStr) req.write(bodyStr)
+      req.end()
+    })
+  }
+
+  return {
+    get: (path, opts) => makeRequest('GET', path, undefined, opts?.headers, opts?.query),
+    post: (path, body, opts) => makeRequest('POST', path, body, opts?.headers),
+    put: (path, body, opts) => makeRequest('PUT', path, body, opts?.headers),
+    patch: (path, body, opts) => makeRequest('PATCH', path, body, opts?.headers),
+    delete: (path, opts) => makeRequest('DELETE', path, undefined, opts?.headers),
+    stop: () => server.stop(),
+  }
+}

package/modules/events/index.ts

@@ -0,0 +1,99 @@
+// modules/events/index.ts — Bus de eventos (pub-sub) formal
+// Para comunicación entre módulos sin acoplamiento directo
+// Complementa los sockets: sockets son 1:1, events es 1:N
+
+export interface EventMessage {
+  name: string
+  data: unknown
+  source: string      // módulo que emitió
+  timestamp: string
+  id: string
+}
+
+export type EventHandler = (event: EventMessage) => Promise<void>
+
+export interface EventBusAdapter {
+  publish(name: string, data: unknown, source: string): Promise<void>
+  subscribe(name: string, handler: EventHandler): void
+  unsubscribe(name: string, handler: EventHandler): void
+}
+
+export class EventBus {
+  private handlers = new Map<string, Set<EventHandler>>()
+  private history: EventMessage[] = []
+  private maxHistory = 100
+
+  constructor(private adapter?: EventBusAdapter) {}
+
+  async emit(name: string, data: unknown, source: string = 'system'): Promise<void> {
+    const event: EventMessage = {
+      id: crypto.randomUUID(),
+      name,
+      data,
+      source,
+      timestamp: new Date().toISOString(),
+    }
+
+    // Guardar historial (para debug y recovery)
+    this.history.push(event)
+    if (this.history.length > this.maxHistory) this.history.shift()
+
+    // Handler locales
+    const localHandlers = this.handlers.get(name)
+    if (localHandlers) {
+      await Promise.allSettled([...localHandlers].map(h => h(event).catch(e => {
+        console.error(`[EventBus] Error en handler para "${name}":`, e)
+      })))
+    }
+
+    // Adapter externo (Redis, etc.)
+    if (this.adapter) {
+      await this.adapter.publish(name, data, source)
+    }
+  }
+
+  on(name: string, handler: EventHandler): void {
+    if (!this.handlers.has(name)) this.handlers.set(name, new Set())
+    this.handlers.get(name)!.add(handler)
+  }
+
+  off(name: string, handler: EventHandler): void {
+    this.handlers.get(name)?.delete(handler)
+  }
+
+  once(name: string, handler: EventHandler): void {
+    const wrapper: EventHandler = async (event) => {
+      await handler(event)
+      this.off(name, wrapper)
+    }
+    this.on(name, wrapper)
+  }
+
+  getHistory(name?: string): EventMessage[] {
+    if (name) return this.history.filter(e => e.name === name)
+    return [...this.history]
+  }
+
+  clearHistory(): void {
+    this.history = []
+  }
+
+  get listeners(): Record<string, number> {
+    const result: Record<string, number> = {}
+    for (const [name, handlers] of this.handlers) {
+      result[name] = handlers.size
+    }
+    return result
+  }
+}
+
+// ─── Uso en composition root ───────────────────────────
+// const events = new EventBus()
+//
+// // Módulo A emite
+// await events.emit('pedido.creado', { id: '123' }, 'pedidos')
+//
+// // Módulo B escucha
+// events.on('pedido.creado', async (event) => {
+//   await descontarStock(event.data)
+// })

package/modules/mail/index.ts

@@ -0,0 +1,51 @@
+// modules/mail/index.ts — Mail module
+// Sends emails via adapter (SMTP, SendGrid, etc.). The module is adapter-agnostic.
+
+export interface MailAddress { name?: string; address: string }
+export interface MailAttachment { filename: string; content: Buffer | string; contentType?: string }
+
+export interface MailMessage {
+  to: MailAddress | MailAddress[]
+  subject: string
+  text?: string
+  html?: string
+  from?: MailAddress
+  cc?: MailAddress | MailAddress[]
+  bcc?: MailAddress | MailAddress[]
+  attachments?: MailAttachment[]
+}
+
+export interface MailAdapter {
+  send(message: MailMessage): Promise<void>
+}
+
+export class MailService {
+  constructor(
+    private adapter: MailAdapter,
+    private defaultFrom: MailAddress = { address: 'noreply@arckode.app' },
+  ) {}
+
+  async send(message: MailMessage): Promise<void> {
+    const msg: MailMessage = {
+      ...message,
+      from: message.from ?? this.defaultFrom,
+    }
+    await this.adapter.send(msg)
+  }
+
+  async sendWelcome(email: string, name: string): Promise<void> {
+    await this.send({
+      to: { address: email, name },
+      subject: 'Welcome',
+      html: `<h1>Welcome, ${name}!</h1><p>Thanks for signing up.</p>`,
+    })
+  }
+
+  async sendPasswordReset(email: string, token: string): Promise<void> {
+    await this.send({
+      to: { address: email },
+      subject: 'Password reset',
+      html: `<p>Use this token to reset your password: <b>${token}</b></p>`,
+    })
+  }
+}

package/modules/mail/smtp-adapter.ts

@@ -0,0 +1,42 @@
+// modules/mail/smtp-adapter.ts — Adapter SMTP para MailService
+// npm: nodemailer
+
+import nodemailer from 'nodemailer'
+import type { MailAdapter, MailMessage } from './index'
+
+export interface SmtpConfig {
+  host: string
+  port: number
+  user: string
+  pass: string
+  secure?: boolean
+}
+
+export class SmtpAdapter implements MailAdapter {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SmtpConfig) {
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure ?? config.port === 465,
+      auth: { user: config.user, pass: config.pass },
+    })
+  }
+
+  async send(message: MailMessage): Promise<void> {
+    const to = Array.isArray(message.to) ? message.to.map(a => a.address).join(', ') : message.to.address
+    await this.transporter.sendMail({
+      from: message.from ? `"${message.from.name}" <${message.from.address}>` : undefined,
+      to,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      attachments: message.attachments?.map(a => ({
+        filename: a.filename,
+        content: a.content,
+        contentType: a.contentType,
+      })),
+    })
+  }
+}