arckode-framework 1.2.3 → 1.3.1

package/README.md

@@ -317,13 +317,63 @@ await mail.send({ to: 'user@example.com', subject: 'Bienvenido', html: '<p>Hola<
 ### Storage
 
 ```ts
-import { StorageService } from 'arckode-framework/storage'
-import { LocalAdapter } from 'arckode-framework/storage/local'
+import { StorageService } from 'arckode-framework/modules/storage'
+import { LocalStorageAdapter } from 'arckode-framework/modules/storage/local-adapter'
+
+// En composition-root.ts
+const storage = new StorageService(
+  new LocalStorageAdapter('./uploads', '/uploads')
+)
+
+// Subir un archivo
+const stored = await storage.upload(file, 'avatars')
+// stored.url  → '/uploads/avatars/1234567890-abc.jpg'
+// stored.path → 'avatars/1234567890-abc.jpg'
+```
+
+### File Uploads (multipart/form-data)
+
+El servidor detecta `Content-Type: multipart/form-data` automáticamente y parsea el body
+sin dependencias externas. Los archivos quedan en `req.files`, los campos de texto en `req.body`.
+
+```ts
+import type { UploadedFile } from 'arckode-framework'
+import { ValidationError } from 'arckode-framework'
 
-const storage = new StorageService(new LocalAdapter({ path: './uploads' }))
-const url = await storage.save('avatars/user.png', fileBuffer)
+router.post('/avatar', [auth.authenticate()], async (req) => {
+  const file = req.files?.['avatar']
+  if (!file) throw new ValidationError('Se requiere un archivo')
+
+  const stored = await storageService.upload(file, 'avatars')
+  return { status: 200, body: { url: stored.url } }
+})
 ```
 
+**Desde el cliente:**
+
+```ts
+const form = new FormData()
+form.append('avatar', blob, 'photo.jpg')
+await fetch('/avatar', { method: 'POST', body: form })
+```
+
+**Estructura de `UploadedFile`:**
+
+```ts
+interface UploadedFile {
+  fieldName: string     // nombre del campo en el form
+  originalName: string  // nombre del archivo enviado
+  buffer: Buffer        // contenido binario
+  mimeType: string      // 'image/jpeg', 'application/pdf', etc.
+  size: number          // bytes
+}
+```
+
+> Combiná con `bodyLimit()` para limitar el tamaño máximo:
+> ```ts
+> router.post('/avatar', [bodyLimit(5 * 1024 * 1024)], handler)  // 5MB máx
+> ```
+
 ---
 
 ## Middlewares

package/kernel/framework.ts

@@ -1065,6 +1065,14 @@ export class OrmTransactor implements Transactor {
 // 6. ROUTER + HTTP — Enrutamiento con middlewares y error handler
 // ═══════════════════════════════════════════════════════════════
 
+export interface UploadedFile {
+  fieldName: string
+  originalName: string
+  buffer: Buffer
+  mimeType: string
+  size: number
+}
+
 export interface HttpRequest {
   id: string
   method: string
@@ -1073,6 +1081,7 @@ export interface HttpRequest {
   query: Record<string, string>
   headers: Record<string, string>
   body: unknown
+  files?: Record<string, UploadedFile>
   user?: { id: string; role: string }
 }
 
@@ -1318,6 +1327,17 @@ function buildEnvelope(status: number, body: unknown): string {
   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
@@ -1341,7 +1361,7 @@ export class NodeServer implements ServerAdapter {
 
         await requestStorage.run({ requestId, startTime: Date.now() }, async () => {
           try {
-            const body = await this.readBody(nodeReq, this.maxBodyBytes)
+            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> = {}
@@ -1355,6 +1375,7 @@ export class NodeServer implements ServerAdapter {
               query,
               headers: nodeReq.headers as Record<string, string>,
               body,
+              ...(files ? { files } : {}),
             }
 
             const res = await handler(req)
@@ -1441,7 +1462,10 @@ export class NodeServer implements ServerAdapter {
     return typeof addr === 'object' && addr ? addr.port : this.port
   }
 
-  private readBody(req: IncomingMessage, maxBytes = 10 * 1024 * 1024): Promise<unknown> {
+  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
@@ -1457,14 +1481,90 @@ export class NodeServer implements ServerAdapter {
       })
 
       req.on('end', () => {
-        const raw = Buffer.concat(chunks).toString()
-        if (!raw) return resolve(null)
-        try { resolve(JSON.parse(raw)) } catch { resolve(raw) }
+        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) {
+      // Skip \r\n after boundary line, or detect closing --
+      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 }
+  }
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -2038,4 +2138,7 @@ export default {
 
   // Response envelope
   // ApiResponse interface is exported as named export above
+
+  // File uploads (multipart/form-data)
+  // UploadedFile interface is exported as named export above
 }

package/modules/storage/index.ts

@@ -1,13 +1,8 @@
 // modules/storage/index.ts — Módulo de almacenamiento
 // Sube y sirve archivos via adapter (local disk, S3, etc.)
 
-export interface FileUpload {
-  fieldName: string
-  originalName: string
-  buffer: Buffer
-  mimeType: string
-  size: number
-}
+import type { UploadedFile as FileUpload } from '../../kernel/framework'
+export type { UploadedFile as FileUpload } from '../../kernel/framework'
 
 export interface StoredFile {
   url: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-framework",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "AI-first TypeScript/Bun framework. Modular, SOLID, zero magic. The AI reads the composition root and knows everything.",
   "type": "module",
   "main": "./kernel/framework.ts",
@@ -17,6 +17,7 @@
     "./adapters/mysql": "./adapters/mysql.ts",
     "./modules/mail": "./modules/mail/index.ts",
     "./modules/storage": "./modules/storage/index.ts",
+    "./modules/storage/local-adapter": "./modules/storage/local-adapter.ts",
     "./modules/queue": "./modules/queue/index.ts",
     "./testing": "./kernel/testing.ts"
   },