arckode-framework 1.3.1 → 1.4.0

package/kernel/http/router.ts

@@ -0,0 +1,131 @@
+import { ErrorContract } from '../errors'
+import type { Logger } from '../logger'
+import type { HttpRequest, HttpResponse, MiddlewareHandler, RouteHandler } from './types'
+
+interface RouteEntry {
+  method: string
+  pattern: RegExp
+  paramNames: string[]
+  handler: RouteHandler
+  middlewares: MiddlewareHandler[]
+}
+
+export class Router {
+  private routes: RouteEntry[] = []
+  private globalMiddlewares: MiddlewareHandler[] = []
+  private logger?: Logger
+
+  setLogger(logger: Logger): void { this.logger = logger }
+
+  use(middleware: MiddlewareHandler): void {
+    this.globalMiddlewares.push(middleware)
+  }
+
+  private add(method: string, path: string, handler: RouteHandler, middlewares: MiddlewareHandler[] = []): void {
+    const paramNames: string[] = []
+    const parts = path.split('/').filter(Boolean)
+    const regexParts = parts.map(part => {
+      if (part.startsWith(':')) {
+        const rawName = part.slice(1)
+        if (rawName.endsWith('(*)')) {
+          paramNames.push(rawName.slice(0, -3))
+          return '(.*)'
+        }
+        paramNames.push(rawName)
+        return '([^/]+)'
+      }
+      return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    })
+
+    this.routes.push({
+      method,
+      pattern: new RegExp(`^/${regexParts.join('/')}/?$`),
+      paramNames,
+      handler,
+      middlewares,
+    })
+  }
+
+  private resolveRouteArgs(
+    handlerOrMw: RouteHandler | MiddlewareHandler[],
+    handlerOrUndefined?: RouteHandler | MiddlewareHandler[],
+  ): { handler: RouteHandler; mw: MiddlewareHandler[] } {
+    if (Array.isArray(handlerOrMw)) {
+      return { handler: handlerOrUndefined as RouteHandler, mw: handlerOrMw }
+    }
+    return { handler: handlerOrMw, mw: (handlerOrUndefined as MiddlewareHandler[] | undefined) ?? [] }
+  }
+
+  get(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('GET', path, handler, mw) }
+  post(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('POST', path, handler, mw) }
+  put(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('PUT', path, handler, mw) }
+  patch(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('PATCH', path, handler, mw) }
+  delete(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('DELETE', path, handler, mw) }
+  options(path: string, handlerOrMw: RouteHandler | MiddlewareHandler[], h?: RouteHandler | MiddlewareHandler[]): void { const { handler, mw } = this.resolveRouteArgs(handlerOrMw, h); this.add('OPTIONS', path, handler, mw) }
+
+  async resolve(method: string, path: string, extras?: Partial<HttpRequest>): Promise<HttpResponse> {
+    const reqId = crypto.randomUUID().slice(0, 8)
+
+    const buildRequest = (route: RouteEntry, match: RegExpMatchArray): HttpRequest => {
+      const params: Record<string, string> = {}
+      route.paramNames.forEach((name, i) => { params[name] = decodeURIComponent(match[i + 1] ?? '') })
+      return {
+        id: reqId,
+        method,
+        path,
+        params,
+        query: extras?.query ?? {},
+        headers: extras?.headers ?? {},
+        body: extras?.body ?? null,
+        user: extras?.user,
+      }
+    }
+
+    const runAll = async (req: HttpRequest, routeMiddlewares: MiddlewareHandler[], routeHandler: RouteHandler): Promise<HttpResponse> => {
+      const allMiddlewares = [...this.globalMiddlewares, ...routeMiddlewares]
+      let index = 0
+      const next = async (): Promise<HttpResponse> => {
+        if (index < allMiddlewares.length) {
+          const mw = allMiddlewares[index++]!
+          return mw(req, next)
+        }
+        return routeHandler(req)
+      }
+      try {
+        return await next()
+      } catch (error) {
+        if (error instanceof ErrorContract) {
+          return { status: error.httpStatus, body: error.toJSON() }
+        }
+        if (this.logger) {
+          const stack = error instanceof Error ? error.stack : String(error)
+          this.logger.error(`Unhandled error in ${method} ${path}`, { stack, requestId: reqId })
+        }
+        return { status: 500, body: { error: 'Error interno del servidor', code: 'INTERNAL_ERROR' } }
+      }
+    }
+
+    if (method === 'OPTIONS') {
+      let anyMatch: { route: RouteEntry; match: RegExpMatchArray } | null = null
+      for (const route of this.routes) {
+        const m = path.match(route.pattern)
+        if (m) { anyMatch = { route, match: m }; break }
+      }
+      if (anyMatch) {
+        const req = buildRequest(anyMatch.route, anyMatch.match)
+        return runAll(req, [], () => Promise.resolve({ status: 204, body: null }))
+      }
+    }
+
+    for (const route of this.routes) {
+      if (route.method !== method) continue
+      const match = path.match(route.pattern)
+      if (!match) continue
+
+      const req = buildRequest(route, match)
+      return runAll(req, route.middlewares, route.handler)
+    }
+
+    return { status: 404, body: { error: 'Route not found', code: 'NOT_FOUND' } }
+  }
+}

package/kernel/http/server.ts

@@ -0,0 +1,303 @@
+import { createServer as createNodeServer, IncomingMessage, ServerResponse } from 'node:http'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { PayloadTooLargeError } from '../errors'
+import type { Logger } from '../logger'
+import type { ApiResponse, HttpRequest, HttpResponse, UploadedFile } from './types'
+
+export const requestStorage = new AsyncLocalStorage<{ requestId: string; startTime: number }>()
+
+export function getRequestId(): string | undefined {
+  return requestStorage.getStore()?.requestId
+}
+
+export function getRequestElapsed(): number | undefined {
+  const store = requestStorage.getStore()
+  return store ? Date.now() - store.startTime : undefined
+}
+
+export interface ServerAdapter {
+  start(handler: (req: HttpRequest) => Promise<HttpResponse>): Promise<void>
+  stop(): Promise<void>
+}
+
+function buildEnvelope(status: number, body: unknown): string {
+  if (status >= 400) {
+    const b = (body ?? {}) as Record<string, unknown>
+    return JSON.stringify({
+      success: false,
+      data: null,
+      meta: null,
+      error: {
+        code:    (b.code    ?? 'ERROR') as string,
+        message: (b.error   ?? 'Error') as string,
+        details: b.details ?? null,
+      },
+    } satisfies ApiResponse)
+  }
+
+  if (body === null || body === undefined) {
+    return JSON.stringify({ success: true, data: null, meta: null, error: null } satisfies ApiResponse)
+  }
+
+  const b = body as Record<string, unknown>
+
+  if (Array.isArray(b.data) && (b.pagination !== undefined || b.total !== undefined)) {
+    const pagination = b.pagination ?? { total: b.total, limit: b.limit, offset: b.offset, pages: b.pages }
+    return JSON.stringify({
+      success: true,
+      data: b.data,
+      meta: { pagination },
+      error: null,
+    } satisfies ApiResponse)
+  }
+
+  return JSON.stringify({ success: true, data: body, meta: null, error: null } satisfies ApiResponse)
+}
+
+function indexOfBuffer(haystack: Buffer, needle: Buffer, offset = 0): number {
+  const limit = haystack.length - needle.length
+  outer: for (let i = offset; i <= limit; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer
+    }
+    return i
+  }
+  return -1
+}
+
+export class NodeServer implements ServerAdapter {
+  private server?: ReturnType<typeof createNodeServer>
+  private maxBodyBytes: number
+  private drainTimeoutMs: number
+  private activeRequests = 0
+
+  constructor(
+    private port: number,
+    private logger: Logger,
+    opts: { maxBodyBytes?: number; drainTimeoutMs?: number } = {},
+  ) {
+    this.maxBodyBytes = opts.maxBodyBytes ?? 10 * 1024 * 1024
+    this.drainTimeoutMs = opts.drainTimeoutMs ?? 30_000
+  }
+
+  async start(handler: (req: HttpRequest) => Promise<HttpResponse>): Promise<void> {
+    return new Promise((resolve) => {
+      this.server = createNodeServer(async (nodeReq: IncomingMessage, nodeRes: ServerResponse) => {
+        this.activeRequests++
+        const requestId = crypto.randomUUID().slice(0, 8)
+
+        await requestStorage.run({ requestId, startTime: Date.now() }, async () => {
+          try {
+            const { body, files } = await this.readBody(nodeReq, this.maxBodyBytes)
+
+            const url = new URL(nodeReq.url ?? '/', `http://${nodeReq.headers.host ?? 'localhost'}`)
+            const query: Record<string, string> = {}
+            url.searchParams.forEach((value, key) => { query[key] = value })
+
+            const req: HttpRequest = {
+              id: requestId,
+              method: nodeReq.method ?? 'GET',
+              path: url.pathname,
+              params: {},
+              query,
+              headers: nodeReq.headers as Record<string, string>,
+              body,
+              remoteAddress: nodeReq.socket?.remoteAddress,
+              ...(files ? { files } : {}),
+            }
+
+            const res = await handler(req)
+
+            if (res.stream) {
+              nodeRes.writeHead(res.status, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+                'X-Request-Id': req.id,
+                ...res.headers,
+              })
+              try {
+                for await (const chunk of res.stream) {
+                  nodeRes.write(`data: ${chunk}\n\n`)
+                }
+              } finally {
+                nodeRes.end()
+              }
+              return
+            }
+
+            // RFC 7231 §6.3.5 — 204 No Content: no body
+            if (res.status === 204) {
+              nodeRes.writeHead(204, { 'X-Request-Id': req.id, ...res.headers })
+              nodeRes.end()
+              return
+            }
+
+            const isBuffer = Buffer.isBuffer(res.body)
+            const responseBody = isBuffer ? res.body : buildEnvelope(res.status, res.body)
+            nodeRes.writeHead(res.status, {
+              'Content-Type': 'application/json',
+              'X-Request-Id': req.id,
+              ...res.headers,
+            })
+            nodeRes.end(responseBody)
+          } catch (error) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const httpStatus = (error as any)?.httpStatus as number | undefined
+            if (httpStatus) {
+              const msg = httpStatus < 500
+                ? (error as Error).message
+                : 'Error interno'
+              if (httpStatus >= 500) {
+                this.logger.error('Server error', { error: String(error), httpStatus })
+              }
+              nodeRes.writeHead(httpStatus, { 'Content-Type': 'application/json' })
+              nodeRes.end(buildEnvelope(httpStatus, { error: msg, code: 'REQUEST_ERROR' }))
+              return
+            }
+
+            const stack = error instanceof Error ? error.stack : String(error)
+            this.logger.error('Error no manejado en HTTP', { error: String(error), stack })
+            nodeRes.writeHead(500, { 'Content-Type': 'application/json' })
+            nodeRes.end(buildEnvelope(500, { error: 'Error interno', code: 'INTERNAL_ERROR' }))
+          } finally {
+            this.activeRequests--
+          }
+        })
+      })
+
+      this.server.listen(this.port, () => {
+        this.logger.info(`Servidor HTTP escuchando en :${this.port}`)
+        resolve()
+      })
+    })
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      let resolved = false
+      const done = () => { if (!resolved) { resolved = true; resolve() } }
+
+      this.server?.close(done)
+
+      const deadline = Date.now() + this.drainTimeoutMs
+      const poll = setInterval(() => {
+        if (this.activeRequests === 0 || Date.now() >= deadline) {
+          clearInterval(poll)
+          if (this.activeRequests > 0) {
+            this.logger.warn(`Graceful shutdown: ${this.activeRequests} request(s) sin terminar, forzando cierre`)
+          }
+          done()
+        }
+      }, 50)
+    })
+  }
+
+  getPort(): number {
+    const addr = this.server?.address()
+    return typeof addr === 'object' && addr ? addr.port : this.port
+  }
+
+  private readBody(
+    req: IncomingMessage,
+    maxBytes = 10 * 1024 * 1024,
+  ): Promise<{ body: unknown; files?: Record<string, UploadedFile> }> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = []
+      let total = 0
+
+      req.on('data', (chunk: Buffer) => {
+        total += chunk.length
+        if (total > maxBytes) {
+          req.destroy()
+          reject(new PayloadTooLargeError())
+          return
+        }
+        chunks.push(chunk)
+      })
+
+      req.on('end', () => {
+        const rawBuffer = Buffer.concat(chunks)
+        if (!rawBuffer.length) return resolve({ body: null })
+
+        const contentType = (req.headers['content-type'] ?? '').toLowerCase()
+        const boundaryMatch = contentType.match(/multipart\/form-data;\s*boundary=(.+)/)
+
+        if (boundaryMatch) {
+          const boundary = (boundaryMatch[1] ?? '').trim()
+          const { fields, files } = this.parseMultipart(rawBuffer, boundary)
+          return resolve({ body: fields, files })
+        }
+
+        const raw = rawBuffer.toString()
+        try { resolve({ body: JSON.parse(raw) }) } catch { resolve({ body: raw }) }
+      })
+
+      req.on('error', reject)
+    })
+  }
+
+  private parseMultipart(
+    buffer: Buffer,
+    boundary: string,
+  ): { fields: Record<string, string>; files: Record<string, UploadedFile> } {
+    const fields: Record<string, string> = {}
+    const files: Record<string, UploadedFile> = {}
+
+    const firstDelim = Buffer.from(`--${boundary}`)
+    const innerDelim = Buffer.from(`\r\n--${boundary}`)
+    const doubleCRLF = Buffer.from('\r\n\r\n')
+
+    let pos = indexOfBuffer(buffer, firstDelim, 0)
+    if (pos === -1) return { fields, files }
+    pos += firstDelim.length
+
+    while (pos < buffer.length) {
+      if (buffer[pos] === 0x2d && buffer[pos + 1] === 0x2d) break
+      if (buffer[pos] === 0x0d && buffer[pos + 1] === 0x0a) pos += 2
+      else break
+
+      const headerEnd = indexOfBuffer(buffer, doubleCRLF, pos)
+      if (headerEnd === -1) break
+
+      const headerStr = buffer.subarray(pos, headerEnd).toString()
+      pos = headerEnd + 4
+
+      const nextBound = indexOfBuffer(buffer, innerDelim, pos)
+      if (nextBound === -1) break
+
+      const partBody = buffer.subarray(pos, nextBound)
+      pos = nextBound + innerDelim.length
+
+      const headers: Record<string, string> = {}
+      for (const line of headerStr.split('\r\n')) {
+        const colon = line.indexOf(':')
+        if (colon === -1) continue
+        headers[line.slice(0, colon).toLowerCase().trim()] = line.slice(colon + 1).trim()
+      }
+
+      const disp = headers['content-disposition'] ?? ''
+      const nameMatch = /name="([^"]*)"/.exec(disp)
+      const fileMatch = /filename="([^"]*)"/.exec(disp)
+      if (!nameMatch) continue
+
+      const fieldName = nameMatch[1] ?? ''
+
+      if (fileMatch) {
+        files[fieldName] = {
+          fieldName,
+          originalName: fileMatch[1] ?? '',
+          buffer: partBody,
+          mimeType: headers['content-type'] ?? 'application/octet-stream',
+          size: partBody.length,
+        }
+      } else {
+        fields[fieldName] = partBody.toString()
+      }
+
+      if (buffer[pos] === 0x2d && buffer[pos + 1] === 0x2d) break
+    }
+
+    return { fields, files }
+  }
+}

package/kernel/http/types.ts

@@ -0,0 +1,56 @@
+export interface UploadedFile {
+  fieldName: string
+  originalName: string
+  buffer: Buffer
+  mimeType: string
+  size: number
+}
+
+export interface HttpRequest {
+  id: string
+  method: string
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  headers: Record<string, string>
+  body: unknown
+  files?: Record<string, UploadedFile>
+  user?: { id: string; role: string }
+  /** IP real del cliente extraída del socket TCP. No spoofeable. */
+  remoteAddress?: string
+}
+
+export interface HttpResponse {
+  status: number
+  body?: unknown
+  headers?: Record<string, string>
+  /** SSE / streaming: async generator que emite chunks de texto plano */
+  stream?: AsyncGenerator<string>
+}
+
+/** Helper: crea una respuesta SSE a partir de un async generator. */
+export function sseResponse(
+  generator: AsyncGenerator<string>,
+  headers?: Record<string, string>,
+): HttpResponse {
+  return {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+      ...headers,
+    },
+    stream: generator,
+  }
+}
+
+export type RouteHandler = (req: HttpRequest) => HttpResponse | Promise<HttpResponse>
+export type MiddlewareHandler = (req: HttpRequest, next: () => Promise<HttpResponse>) => Promise<HttpResponse>
+
+export interface ApiResponse<T = unknown> {
+  success: boolean
+  data: T | null
+  meta: { pagination?: unknown } | null
+  error: { code: string; message: string; details?: unknown } | null
+}

package/kernel/index.ts

@@ -0,0 +1,25 @@
+// Arckode Framework — Kernel index
+// Re-exporta todos los módulos del kernel. Backward compat: cualquier
+// import de 'arckode-framework' sigue funcionando sin cambios.
+
+export * from './errors'
+export * from './logger'
+export * from './config'
+export * from './container'
+export * from './cache'
+export * from './validator'
+export * from './auth'
+export * from './seeds'
+
+export * from './db/types'
+export * from './db/orm'
+export * from './db/orm-repository'
+export * from './db/transactor'
+
+export * from './http/types'
+export * from './http/router'
+export * from './http/server'
+
+export * from './modules/types'
+export * from './modules/create-module'
+export * from './modules/system'

package/kernel/logger.ts

@@ -0,0 +1,50 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+export interface LoggerTransport {
+  write(entry: { timestamp: string; level: LogLevel; source: string; message: string; meta?: Record<string, unknown> }): void
+}
+
+export class Logger {
+  constructor(
+    public readonly source: string = 'app',
+    private level: LogLevel = 'info',
+    private transports: LoggerTransport[] = [new ConsoleTransport()],
+  ) {}
+
+  child(name: string): Logger {
+    return new Logger(`${this.source}.${name}`, this.level, this.transports)
+  }
+
+  debug(message: string, meta?: Record<string, unknown>): void { this.emit('debug', message, meta) }
+  info(message: string, meta?: Record<string, unknown>): void  { this.emit('info', message, meta) }
+  warn(message: string, meta?: Record<string, unknown>): void  { this.emit('warn', message, meta) }
+  error(message: string, meta?: Record<string, unknown>): void { this.emit('error', message, meta) }
+
+  private emit(level: LogLevel, message: string, meta?: Record<string, unknown>): void {
+    const weight = { debug: 0, info: 1, warn: 2, error: 3 }
+    if (weight[level] < weight[this.level]) return
+
+    const entry: Record<string, unknown> = {
+      timestamp: new Date().toISOString(),
+      level,
+      source: this.source,
+      message,
+    }
+
+    if (meta && Object.keys(meta).length > 0) {
+      entry.meta = { ...meta }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const t of this.transports) t.write(entry as any)
+  }
+}
+
+export class ConsoleTransport implements LoggerTransport {
+  write(entry: { level: LogLevel; message: string; source: string } & Record<string, unknown>): void {
+    const line = JSON.stringify(entry)
+    if (entry.level === 'error') console.error(line)
+    else if (entry.level === 'warn') console.warn(line)
+    else console.log(line)
+  }
+}

package/kernel/middlewares.ts

@@ -14,33 +14,42 @@ export function cors(options: {
   origins?: string[]
   methods?: string[]
   headers?: string[]
+  /**
+   * Por defecto false. Si true, envía Access-Control-Allow-Credentials: true.
+   * Requiere origins específicos (no '*') — los browsers rechazan la combinación.
+   */
   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
+  const credentials = options.credentials ?? false
 
   return async (req, next): Promise<HttpResponse> => {
+    const requestOrigin = req.headers['origin'] as string | undefined
+
+    // Access-Control-Allow-Origin must be a single value — never a comma-separated list.
+    // When multiple origins are allowed, echo back only the matching request origin.
+    const allowedOrigin = origins.includes('*')
+      ? '*'
+      : requestOrigin && origins.includes(requestOrigin)
+        ? requestOrigin
+        : undefined
+
     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 h: Record<string, string> = {
+        'Access-Control-Allow-Methods': methods.join(', '),
+        'Access-Control-Allow-Headers': headers.join(', '),
+        'Access-Control-Allow-Credentials': String(credentials),
+        'Access-Control-Max-Age': '86400',
       }
+      if (allowedOrigin) h['Access-Control-Allow-Origin'] = allowedOrigin
+      return { status: 204, body: null, headers: h }
     }
 
     const res = await next()
-    const corsHeaders: Record<string, string> = {
-      ...res.headers,
-      'Access-Control-Allow-Origin': origins.includes('*') ? '*' : origins.join(', '),
-    }
+    const corsHeaders: Record<string, string> = { ...res.headers }
+    if (allowedOrigin) corsHeaders['Access-Control-Allow-Origin'] = allowedOrigin
     if (credentials) corsHeaders['Access-Control-Allow-Credentials'] = 'true'
     return { ...res, headers: corsHeaders }
   }
@@ -56,14 +65,17 @@ export function rateLimit(opts: {
   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'`
+   * Por defecto: IP real del socket TCP (no spoofeable).
+   * Si el servidor está detrás de un proxy confiable (nginx/Cloudflare), usar:
+   *   `(req) => req.headers['x-forwarded-for']?.split(',')[0]?.trim() ?? req.remoteAddress ?? 'unknown'`
+   * ADVERTENCIA: x-forwarded-for es spoofeable si no validás el proxy.
+   * Para rate limit por usuario autenticado: `(req) => req.user?.id ?? req.remoteAddress ?? '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 keyBy = opts.keyBy ?? ((req) => req.remoteAddress ?? 'unknown')
   const hits = new Map<string, { count: number; resetAt: number }>()
 
   const mw = async (req: HttpRequest, next: () => Promise<HttpResponse>): Promise<HttpResponse> => {
@@ -117,11 +129,16 @@ export function requestLogger(logger: { info: (msg: string, meta?: any) => void
 }
 
 // ─── Body Size Limit ───────────────────────────────────
+// Nota: el límite de bytes en la wire va en NodeServer({ maxBodyBytes }).
+// Este middleware aplica un límite adicional a nivel de aplicación sobre el
+// body ya parseado — útil para JSON muy anidado que expande mucho en memoria.
 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` } }
+    if (req.body !== null && req.body !== undefined) {
+      const size = Buffer.byteLength(JSON.stringify(req.body), 'utf-8')
+      if (size > maxBytes) {
+        return { status: 413, body: { error: `Request body too large. Max ${maxBytes} bytes` } }
+      }
     }
     return next()
   }

package/kernel/modules/create-module.ts

@@ -0,0 +1,5 @@
+import type { ModuleDefinition } from './types'
+
+export function createModule<T>(def: ModuleDefinition<T>): ModuleDefinition<T> {
+  return def
+}