feat: file_save_disk, file_delete, file_serve, upload_parse, upload_handler, thumbnail_generate (issue 0014 fase 3)

functions/infra/file_serve.md

@@ -0,0 +1,41 @@
+---
+name: file_serve
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func FileServe(dir string, pathPrefix string, maxAge int) http.Handler"
+description: "Retorna un http.Handler que sirve archivos estaticos desde dir, stripeando pathPrefix del URL. Setea Cache-Control con max-age. Rechaza paths con \"..\"."
+tags: [http, file, serve, static, cache, security, infra]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, net/http, strings]
+params:
+  - name: dir
+    desc: "directorio raiz desde donde se sirven los archivos"
+  - name: pathPrefix
+    desc: "prefijo del URL a remover antes de buscar (ej: \"/files/\")"
+  - name: maxAge
+    desc: "segundos para el header Cache-Control max-age"
+output: "http.Handler listo para registrar en un mux. No retorna error directo; el handler responde 400 si detecta path traversal y delega al http.FileServer en otros casos"
+tested: true
+tests: ["sirve archivo existente con headers de cache", "responde 404 para archivo inexistente", "rechaza path con .. con 400"]
+test_file_path: "functions/infra/file_serve_test.go"
+file_path: "functions/infra/file_serve.go"
+---
+
+## Ejemplo
+
+```go
+mux := http.NewServeMux()
+mux.Handle("/files/", FileServe("./uploads", "/files/", 3600))
+http.ListenAndServe(":8080", mux)
+```
+
+## Notas
+
+Wrapper sobre `http.FileServer` con dos refuerzos: rechazo explicito de paths con `..` y header `Cache-Control` configurable. `http.FileServer` ya normaliza paths, pero la doble verificacion es barata y reduce la superficie de ataque. Para servir archivos generados dinamicamente o detras de auth, no usar esta funcion — usar handlers custom.