---
id: "INT-005"
title: "Integracion Storage Providers"
type: "Integration"
status: "Implemented"
priority: "P1"
provider: "S3/R2/MinIO"
category: "Storage"
multi_tenant: true
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# INT-005: Storage Integration

## Metadata
| Campo | Valor |
|-------|-------|
| Codigo | INT-005 |
| Proveedor | AWS S3, Cloudflare R2, MinIO |
| Tipo | Storage |
| Estado | Implementado |
| Multi-tenant | Si |
| Fecha integracion | 2026-01-10 |

---

**Documentacion completa:** Ver [SAAS-011-storage.md](../01-modulos/SAAS-011-storage.md)

## Resumen

Integracion multi-proveedor para almacenamiento de archivos.

## Proveedores Soportados

- AWS S3
- Cloudflare R2
- MinIO (self-hosted)

## Caracteristicas

- Upload directo con URLs pre-firmadas
- Cuotas de almacenamiento por plan
- Tipos MIME permitidos configurables
- Metadata de archivos en base de datos

## Configuracion

```env
# AWS S3
STORAGE_PROVIDER=s3
AWS_S3_BUCKET=my-bucket
AWS_S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# Cloudflare R2
STORAGE_PROVIDER=r2
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET=my-bucket

# MinIO
STORAGE_PROVIDER=minio
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...
MINIO_BUCKET=my-bucket
```

## Rate Limits
| Limite | Valor | Accion si excede |
|--------|-------|------------------|
| Requests/seg | 3500 (S3 PUT), 5500 (S3 GET) | Retry con backoff exponencial |
| Tamanio archivo | Segun plan del tenant | Rechazar upload |

## Manejo de Errores
| Codigo | Descripcion | Accion |
|--------|-------------|--------|
| 400 | Bad Request | Log + no retry |
| 401 | Unauthorized | Renovar credenciales |
| 403 | Forbidden | Verificar permisos bucket |
| 429 | Rate Limited | Backoff exponencial |
| 500 | Server Error | Retry con backoff |

## Fallbacks

### Estrategia Storage Fallback

| Escenario | Estrategia |
|-----------|------------|
| S3 no disponible | Fallback automatico a R2 |
| R2 no disponible | Fallback a MinIO local |
| Todos fallan | Encolar upload para retry posterior |
| Cuota excedida | Rechazar con mensaje claro al usuario |

### Multi-region

- **Primary:** us-east-1 (S3)
- **Failover:** eu-west-1 (R2 o S3 EU)
- **Replicacion:** Asincrona cada 5 minutos para archivos criticos

### Configuracion Failover

```typescript
const storageProviders = [
  { name: 's3', priority: 1, region: 'us-east-1' },
  { name: 'r2', priority: 2 },
  { name: 'minio', priority: 3, endpoint: 'localhost:9000' }
];
```

### Circuit Breaker

- Umbral apertura: 3 fallos consecutivos
- Timeout semi-abierto: 30 segundos
- Fallback: Siguiente provider en prioridad

## Multi-tenant
- Credenciales: Por tenant (cada tenant puede tener su propio bucket/proveedor)
- Configuracion: Por tenant via tenant_config
- Aislamiento: Prefijo tenant_id en todas las operaciones (path: /{tenant_id}/...)

## Testing
### Sandbox/Test Mode
- MinIO local para desarrollo
- Buckets de prueba separados de produccion
- Fixtures disponibles para testing unitario

## Monitoreo
| Metrica | Descripcion | Alerta |
|---------|-------------|--------|
| Latencia | Tiempo de respuesta | >2s |
| Errores | Tasa de errores | >1% |
| Disponibilidad | Uptime del servicio | <99.9% |

## Referencias

- Modulo relacionado: SAAS-011-storage.md

---

**Ultima actualizacion:** 2026-01-10
**Version:** 1.0.0