Almacenamiento y Media

Tabla de Contenidos

1. Arquitectura General
2. Buckets de Almacenamiento
3. URLs Pre-firmadas (Presigned URLs)
4. Tipos de Archivo Permitidos
5. Limites de Tamano por Plan
6. Proveedores de Almacenamiento
7. URLs de CDN

Arquitectura General

El sistema de almacenamiento de Nvito utiliza el protocolo S3 como capa de abstraccion, permitiendo cambiar entre proveedores (MinIO en desarrollo, Cloudflare R2 en produccion) sin modificar el codigo de la aplicacion.

Componentes Principales

S3 Client

El servicio inicializa un S3Client del AWS SDK v3 con configuracion adaptativa:

this.s3Client = new S3Client({
  region: 'auto',
  endpoint: endpoint || `https://${accountId}.r2.cloudflarestorage.com`,
  credentials: { accessKeyId, secretAccessKey },
  forcePathStyle: isMinIO,  // MinIO requiere path-style, R2 usa virtual-hosted
});

Buckets de Almacenamiento

El sistema organiza los archivos en 4 buckets separados por proposito:

Estructura de Archivos en nvito-uploads

nvito-uploads/
└── org_{organizationId}/
    └── events/
        └── {eventId}/
            ├── media/
            │   ├── {timestamp}_{filename}.jpg     # Fotos
            │   ├── {timestamp}_{filename}.mp4     # Videos
            │   └── {timestamp}_{filename}.mp3     # Audio
            └── invitations/
                └── {invitationId}/
                    ├── versions/
                    │   └── v{N}/
                    │       ├── index.html         # HTML compilado
                    │       ├── styles.css          # CSS compilado
                    │       └── script.js           # JS compilado (opcional)
                    └── live/
                        ├── index.html             # Version publicada
                        ├── styles.css
                        └── script.js

Estructura de Archivos en nvito-templates

nvito-templates/
└── templates/
    └── {templateId}/
        ├── template.html              # HTML del template base
        └── assets/
            └── {timestamp}_{file}     # Imagenes preview, fondos, etc.

URLs Pre-firmadas (Presigned URLs)

Para subir archivos, el frontend no envia el archivo al API. En su lugar, solicita una URL pre-firmada y sube directamente al almacenamiento, reduciendo la carga en el servidor.

Generacion de Key

El key se construye con la siguiente estructura para evitar colisiones:

org_{organizationId}/events/{eventId}/media/{timestamp}_{sanitizedFilename}

El filename se sanitiza eliminando caracteres especiales: filename.replace(/[^a-zA-Z0-9._-]/g, '_').

Expiracion

Las URLs pre-firmadas expiran despues de 3600 segundos (1 hora) por defecto. El frontend recibe la fecha de expiracion en expiresAt.

Validacion Post-Upload

Despues de que el frontend sube el archivo, el API descarga el archivo del bucket y valida:

1. Magic bytes: Verifica que el contenido real coincide con el MIME type declarado
2. Ejecutables: Rechaza archivos ejecutables detectados por analisis de bytes
3. Accion en fallo: Si la validacion falla, el archivo se elimina automaticamente del bucket

Tipos de Archivo Permitidos

MIME Types Aceptados

Archivos de Invitacion (generados por el sistema)

Ademas de los archivos subidos por usuarios, el sistema genera y almacena:

Limites de Tamano por Plan

Los limites de tamano de archivo varian segun el plan contratado por la organizacion:

Variables de Entorno para Limites

MAX_FILE_SIZE_FREE=5242880          # 5 MB
MAX_FILE_SIZE_ESSENTIAL=26214400    # 25 MB
MAX_FILE_SIZE_PLUS=52428800         # 50 MB
MAX_FILE_SIZE_VIP=104857600         # 100 MB

Estos valores son configurables por variable de entorno, permitiendo ajustarlos sin recompilar.

Proveedores de Almacenamiento

MinIO (Desarrollo Local)

MinIO es un servidor de almacenamiento de objetos compatible con S3, ideal para desarrollo local:

Deteccion automatica: Si la variable R2_ENDPOINT esta configurada (apuntando a MinIO), el servicio activa forcePathStyle: true automaticamente, ya que MinIO requiere path-style en lugar de virtual-hosted.

Cloudflare R2 (Produccion)

Cloudflare R2 es el proveedor de almacenamiento para ambientes remotos:

Tabla Comparativa

URLs de CDN

Construccion de URLs Publicas

El servicio construye URLs publicas de forma diferente segun el proveedor:

MinIO (local):

http://localhost:9000/{bucket}/{key}
Ejemplo: http://localhost:9000/nvito-uploads/org_abc123/events/evt1/media/1707123456_foto.jpg

Cloudflare R2 (produccion):

https://cdn.nvito.mx/{key}
Ejemplo: https://cdn.nvito.mx/org_abc123/events/evt1/media/1707123456_foto.jpg

Diferencia Clave

En MinIO, el nombre del bucket se incluye en la URL publica (/{bucket}/{key}). En R2, el bucket no aparece en la URL porque se configura a nivel de dominio personalizado (/{key}).

Cache-Control

Los archivos subidos por usuarios se sirven con cache agresivo:

Cache-Control: public, max-age=31536000    # 1 ano (media de usuario)
Cache-Control: public, max-age=3600        # 1 hora (HTML de invitacion)

URLs Privadas

Para archivos en el bucket nvito-private, se generan URLs firmadas de lectura con expiracion configurable:

async getPrivateUrl(key: string, expiresIn: number = 3600): Promise<string>

Estas URLs son temporales y permiten descargar el archivo sin exponer credenciales.

Operaciones del StorageService

Resumen de Metodos

Variables de Entorno

Referencias

• StorageService: src/modules/storage/storage.service.ts
• Storage Config: src/config/storage.config.ts
• File Validation: src/common/utils/file-validation.util.ts