feat: stubs s3_upload, s3_download, s3_presign_url (issue 0014 fase 4)

2026-04-18 17:17:19 +02:00
parent 4b420fb24b
commit 0bd91f04b8
6 changed files with 317 additions and 0 deletions
@@ -0,0 +1,80 @@
+---
+name: s3_presign_url
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func S3PresignURL(cfg S3Config, key string, expiry time.Duration) (string, error)"
+description: "STUB. Genera una URL presignada para download (GET) del objeto key en un bucket S3-compatible, valida durante expiry. Util para descargas directas sin pasar por el servidor. Requiere github.com/aws/aws-sdk-go-v2."
+tags: [s3, presign, url, storage, cloud, stub, infra]
+uses_functions: []
+uses_types: [S3Config_go_infra]
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [fmt, time]
+params:
+  - name: cfg
+    desc: "S3Config con endpoint, bucket, credenciales y region"
+  - name: key
+    desc: "key del objeto en el bucket (ej: \"images/foto.png\")"
+  - name: expiry
+    desc: "duracion de validez de la URL (ej: time.Hour)"
+output: "URL presignada como string. Empty + error si falla la generacion. STUB actual retorna siempre error \"not implemented\""
+tested: false
+tests: []
+test_file_path: ""
+file_path: "functions/infra/s3_presign_url.go"
+---
+
+## Estado
+
+**Stub**. Para activar la implementacion real:
+
+1. Añadir las mismas dependencias que `s3_upload`.
+2. Reemplazar el cuerpo del stub por:
+   ```go
+   func S3PresignURL(cfg S3Config, key string, expiry time.Duration) (string, error) {
+       ctx := context.Background()
+       awsCfg, err := awscfg.LoadDefaultConfig(ctx,
+           awscfg.WithRegion(cfg.Region),
+           awscfg.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
+               cfg.AccessKey, cfg.SecretKey, "")),
+       )
+       if err != nil {
+           return "", fmt.Errorf("s3_presign_url: aws config: %w", err)
+       }
+       client := s3.NewFromConfig(awsCfg, func(o *s3.Options) {
+           o.UsePathStyle = true
+           if cfg.Endpoint != "" {
+               scheme := "http"
+               if cfg.UseSSL {
+                   scheme = "https"
+               }
+               o.BaseEndpoint = aws.String(fmt.Sprintf("%s://%s", scheme, cfg.Endpoint))
+           }
+       })
+       psClient := s3.NewPresignClient(client)
+       req, err := psClient.PresignGetObject(ctx, &s3.GetObjectInput{
+           Bucket: aws.String(cfg.Bucket),
+           Key:    aws.String(key),
+       }, s3.WithPresignExpires(expiry))
+       if err != nil {
+           return "", fmt.Errorf("s3_presign_url: presign: %w", err)
+       }
+       return req.URL, nil
+   }
+   ```
+
+## Ejemplo (con implementacion real)
+
+```go
+url, err := S3PresignURL(cfg, "images/foto.png", time.Hour)
+// url es valida 1 hora; el cliente puede descargar sin credenciales
+fmt.Println(url)
+```
+
+## Notas
+
+Para uploads directos (PUT/POST presigned), se usaria `psClient.PresignPutObject` analogamente. Las URLs presignadas heredan los permisos de las credenciales que las generaron — no incrementan privilegios.