DEV Community

Cover image for Quién Le Avisa a Mi Aplicación Laravel que Subieron un Archivo a S3 (Cuando el Navegador Se Va Antes de Dar el Aviso)
Hermann D. Schimpf
Hermann D. Schimpf

Posted on Edited on Originally published at hds-solutions.net

Quién Le Avisa a Mi Aplicación Laravel que Subieron un Archivo a S3 (Cuando el Navegador Se Va Antes de Dar el Aviso)

English version here


Banner Image


Hasta ahora, en esta serie preparamos el terreno por separado. En el capítulo 3 hicimos que los ficheros viajen del navegador directo a S3 con URLs pre-firmadas; y en el capítulo 4 configuramos SQS y una Lambda para procesar los jobs en segundo plano. Pero quedó una pregunta flotando: si el fichero nunca pasa por nuestra aplicación:

¿Quién le avisa a Laravel que terminó de subirse un fichero para encolar ese job?

Les debo confesar algo: en mi app, hasta hoy, quien avisaba era el navegador. El flujo real tiene tres fases: Laravel crea la URL firmada de subida y se la manda al navegador; el navegador manda el fichero directo a S3; y cuando termina, el navegador mismo hace un request a la app avisando "ya subí" para que Laravel encole el job. Funciona... hasta que alguien cierra la pestaña entre la fase dos y la tres, y nos queda una foto subida y un registro esperando una confirmación que no va a llegar.

Estaba pidiéndole al navegador que me cuente qué pasa en mi propio bucket. Como preguntarle al cartero si llegó la carta que él mismo entregó.

En un servidor tradicional este problema no existe: la subida pasa por PHP ($request->file()->store()) y el dispatch() va en el mismo controlador. La aplicación era el peaje obligatorio de cada subida.

En este capítulo vamos a cerrar el círculo.


1. El Mapa del Tesoro Serverless

Revisitemos el mapa, esta vez para conectar dos piezas que ya conocemos:

AWS Serverless architecture

Hoy aparece un invitado nuevo en el diagrama: S3 Event Converter (Lambda), una función lambda que actúa de traductor entre lo que dice el bucket a lo que el worker de Laravel entiende.


2. S3 Event Notifications: Cuando el Bucket Tiene Algo que Contar

a) El portero del edificio

Amazon S3 es un servicio de almacenamiento, pero también sabe avisar cuando algo sucede en sus objetos 1. Piensen en el bucket como el portero del edificio: no sube a golpear puertas piso por piso, pero si le dejan instrucciones como "si llega un paquete para el 4B, avisa a este número" lo hace, sin que nuestra aplicación tenga que preguntar cada tanto si llegó algo.

La configuración vive en el bucket, y se define mediante dos cosas: qué eventos debe avisar, y a qué destino debe enviar los avisos. Los eventos que nos interesan son:

  • s3:ObjectCreated:*: Se creó un objeto nuevo. Utilizamos * para cubrir todas las operaciones: Put, Post, Copy y CompleteMultipartUpload (para subidas en partes).
  • s3:ObjectRemoved:*: Se eliminó un objeto. Nuevamente, * para capturar todas las operaciones: Delete y DeleteMarkerCreated.

Existen más eventos 2, que por el momento no son relevantes para nosotros.

¿Y los destinos posibles? SNS, SQS, Lambda o EventBridge 2. Para nuestro caso, utilizaremos el destino Lambda.

b) No Todo el Bucket Nos Interesa

No necesitamos que S3 nos avise de todo lo que ocurre en el bucket: podemos filtrar por el prefijo y/o sufijo del objeto 3. Por ejemplo, "avísame solo cuando se cree un objeto dentro de uploads/", y "solo si es un fichero .jpg":

rules:
    -   prefix: uploads/
    -   suffix: .jpg
Enter fullscreen mode Exit fullscreen mode

Tres detalles que hay que tener presentes:

  • Sin wildcards: No podemos utilizar *, solo texto literal.
  • Espacios y caracteres especiales: un espacio se debe reemplazar por +, y el resto de caracteres especiales debe ser URL-encoded (fotos del evento @ 2026/ → fotos+del+evento+%40+2026/).
  • Sin filtros solapados: para el mismo tipo de evento, un objeto no puede coincidir con dos reglas de notificación solapadas 3.

c) Lo que S3 Nos Cuenta

El contenido del evento que publica S3 es JSON parecido a esto (version 2.x, recortado) 4:

{
    "Records": [
        {
            "eventSource": "aws:s3",
            "awsRegion": "us-east-1",
            "eventTime": "2026-11-06T14:32:11.000Z",
            "eventName": "ObjectCreated:Put",
            "s3": {
                "bucket": { "name": "mi-app-storage" },
                "object": {
                    "key": "inbox/ProcessImage/9f8d7c6b-2aab-4c12-a11a-00f4c3d2e1f0.jpg",
                    "size": 20481234,
                    "eTag": "b21b84d653bb07b05b1e6b33684dc11b",
                    "sequencer": "0C0F6F405D6ED209E1"
                }
            }
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

Todo lo que necesitamos está ahí: el nombre del bucket (s3.bucket.name), la ruta del fichero (s3.object.key), su tamaño en bytes y un sequencer para ordenar eventos sobre la misma key.

Importante: el nombre del fichero en s3.object.key viene URL-encoded, siguiendo las mismas reglas del prefijo y sufijo. Si alguien sube foto yo & ella.jpg, el key contendrá foto+yo+%26+ella.jpg.

d) Qué nos Garantiza S3 (Y Qué No)

S3 nos avisa, pero hay tres condiciones que nuestro código debe contemplar 1 5:

  • Al menos una vez (at-least-once): S3 garantiza que el aviso llega, pero en raros casos puede llegar dos veces.
  • Rápido, casi siempre: típicamente segundos, pero puede llegar a tardar un minuto o más.
  • Sin orden garantizado: dos eventos pueden llegar desordenados respecto a cuando ocurrieron.

S3 puede repetir el mensaje; nuestro job no debería repetir el desastre. Y como vimos en el capítulo anterior, eso significa que nuestro procesamiento tiene que ser idempotente.

¿Y cuánto cuesta el aviso? S3 no cobra por emitir estas notificaciones; el destino que las recibe sí puede generar cargos.


3. S3 Ya Avisó. ¿Y Ahora Qué?

Primero, un dato que hace posible todo lo que sigue: con bref/laravel-bridge, el handler de una función Lambda puede ser directamente una clase PHP, y Bref la resuelve desde el contenedor de Laravel 6. Si revisamos el HandlerResolver que hace el truco (simplificado) 7:

private function laravel(): Application
{
    // require bootstrap/app.php
    $application = require LaravelPathFinder::app();

    // Laravel listo y arrancado
    $kernel = $application->make(Kernel::class);
    $kernel->bootstrap(); 

    return $application;
}
Enter fullscreen mode Exit fullscreen mode

Inicializa Laravel completo y luego llama a $this->laravel()->get($id) con el nombre de nuestra clase. El resultado: dentro de nuestra clase funciona todo; Storage, Log, dispatch(), y hasta la inyección de dependencias. Es Laravel de verdad, no una versión recortada.

Una decisión de diseño antes de seguir, porque simplifica todo lo que viene: los uploads no caen en cualquier rincón del bucket, sino en un directorio de entrada que llamaremos inbox/, organizado por tipo de tarea:

inbox/ProcessImage/{media_uuid}.jpg    → foto a procesar
inbox/ImportData/{list_uuid}.csv       → planilla a importar
inbox/GeneratePreview/{doc_uuid}.pdf   → documento a convertir
Enter fullscreen mode Exit fullscreen mode

El primer segmento después de inbox/ define quién debe procesar (el nombre del Job), y el segundo segmento qué se debe procesar (el nombre del fichero). Los resultados se escriben siempre fuera del directorio inbox/ (para evitar loops infinitos).

inbox/ es la bandeja de entrada del portero del edificio, recibe los originales hasta que un job se hace cargo de ellos.

a) Opción A: una Lambda extends S3Handler que procesa directo

La forma más directa: escribir una clase que extienda el S3Handler de Bref 6 y hacer el trabajo ahí mismo. Leer el fichero subido, procesarlo, y listo:

namespace App\Lambda;

use Bref\Context\Context;
use Bref\Event\S3\S3Event;
use Bref\Event\S3\S3Handler;
use Illuminate\Support\Facades\Storage;
use Intervention\Image\Format;
use Intervention\Image\Laravel\Facades\Image;

final class GenerateThumbnail extends S3Handler
{
    public function handleS3(S3Event $event, Context $context): void
    {
        foreach ($event->getRecords() as $record) {
            // obtenemos el nombre original del fichero,
            // urldecode() porque la key esta URL-encoded
            $key = urldecode($record->getObject()->getKey());

            // procesamos la imagen ...
            $image = Image::decodeStream(Storage::readStream($key));
            Storage::put(
                str_replace('inbox/', 'media/thumbnails/', $key),
                $image->coverDown(600, 600)->encodeUsingFormat(Format::WEBP, quality: 75),
            );

            // y eliminamos el original que ya hizo su trabajo,
            // para mantener limpia la bandeja de entrada
            Storage::delete($key);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Teniendo nuestra clase GenerateThumbnail, la asignamos en serverless.yml como la función que se ejecutará escuchando el evento s3:ObjectCreated:* del bucket que ya creamos con el construct storage de Lift 8:

functions:
    laravel:
        handler: Bref\LaravelBridge\Http\OctaneHandler
        runtime: php-85
        # ...

+   thumbnails:
+       handler: App\Lambda\GenerateThumbnail
+       runtime: php-85
+       layers:
+           - ${bref-extra:gd-php-85}
+       timeout: 60
+       events:
+           - s3:
+               bucket: ${construct:storage.bucketName}
+               existing: true
+               event: s3:ObjectCreated:*
+               rules:
+                   -   prefix: inbox/

constructs:
    storage:
        type: storage
        allowAcl: true
        cors: ${construct:website.url}
+       lifecycleRules:
+           -   prefix: inbox/
+               expirationInDays: 7   # limpieza de huérfanos (sección 5.d)
Enter fullscreen mode Exit fullscreen mode

Dos detalles de oro que hemos agregado en serverless.yml:

  • functions.thumbnails.events.s3.existing: true: sin esta bandera, Serverless Framework intentaría crear un bucket nuevo con ese nombre y fallaría, porque ese bucket ya existe. Habilitando la bandera, apunta al bucket existente que ya creó Lift.

Eso sí: agrega una Lambda custom resource y un rol IAM extra al stack para configurar la notificación, y solo permite un bucket existente por función 9.

  • functions.thumbnails.events.s3.rules.prefix: inbox/: solo ejecutamos la función cuando cae algo nuevo en la bandeja de entrada. Y como recomendamos anteriormente, los resultados se escriben fuera de este directorio.

Las ventajas:

  • Una misma función recibe el evento y procesa el fichero,
  • Latencia mínima entre el upload y el procesamiento,
  • y un código que cualquiera entiende.

Para tareas triviales como validar un fichero, registrar un log, moverlo de prefijo, funciona de maravilla.

Los contras honestos, y son unos cuantos:

  • Reintentos menos flexibles: S3 invoca a Lambda asíncronamente 10. Si la función devuelve un error, Lambda realiza por defecto hasta 2 reintentos adicionales (con esperas de 1 y 2 minutos) y, si sigue fallando, se descarta el evento 11. No hay #[Tries(3)], #[Backoff], failed(), failed_jobs, ni queue:retry. Salvo que configuren un destino onFailure 12, pero estaríamos agregando complejidad innecesaria (con la opción B se simplifica esto).
  • Concurrencia con otro mecanismo: podemos limitar esta Lambda con reservedConcurrency 13, pero no contamos con el control de consumo por cola de SQS. Si llegan más eventos de los que puede procesar, quedan pendientes en la cola asíncrona interna de Lambda, sujetos a su política de reintentos y caducidad 11.
  • Multiplicación de funciones: cada "tipo de tarea" es una función adicional. Si quieren procesar imágenes y CSV, ya son dos funciones, dos custom resources y dos suscripciones al mismo bucket (y recuerden: no podemos tener de prefijos solapados).
  • Duplicar el tuning: layers adicionales (GD para imágenes, etc.), memorySize, timeout... el mismo trabajo que ya hicimos para el worker en el capítulo anterior, otra vez, por cada función.
  • Fuera del ecosistema de jobs: no podremos utilizar Queue::fake() en los tests, nada de queue:failed o serverless jobs:failed para acceder al listado de jobs fallidos. El procesamiento no es un Job de Laravel: es una clase aparte con su propio ciclo de vida.

La Opción A es como pedirle al portero que además de avisar, revele las fotos, las recorte y las enmarque: puede hacerlo, pero ya le cambiamos bastante la descripción del puesto.

b) Opción B: el S3 Event Converter; traducir el evento y delegar

La segunda opción es la que me convenció: una Lambda delgada que no procesa nada. Solo recibe el evento de S3, averigua qué fichero es, y despacha el Job de Laravel que ya existe. Un traductor entre dos idiomas: del JSON de S3 al payload de Laravel Queue.

namespace App\Lambda;

use Bref\Context\Context;
use Bref\Event\S3\S3Event;
use Bref\Event\S3\S3Handler;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;

final class S3EventConverter extends S3Handler
{
    public const INBOX_KEY = '#^inbox/(?<job>[A-Za-z]+)/(?<file>[^/]+)$#';

    public function handleS3(S3Event $event, Context $context): void
    {
        foreach ($event->getRecords() as $record) {
            // nombre original del fichero (URL-decoded)
            $key = urldecode($record->getObject()->getKey());

            // realizamos unas validaciones básicas:
            // 1. el fichero debe estar en la bandeja de entrada ^/inbox,
            // 2. debe contener el nombre de un Job (?<job>[A-Za-z]+),
            // 3. debe contener el nombre del fichero (?<file>[^/]+)$
            if (! preg_match(self::INBOX_KEY, $key, $m)) {
                Log::debug('S3 event ignored', ['key' => $key]);
                continue;
            }

            $jobClass = "App\\Jobs\\{$m['job']}";

            // y por último, validamos que el Job sea encolable
            if (! is_a($jobClass, ShouldQueue::class, true)) {
                Log::warning('Unknown job for S3 inbox key', ['key' => $key, 'job' => $jobClass]);
                continue;
            }

            // finalmente, despachamos el Job a la cola SQS
            $jobClass::dispatch($key);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Tres decisiones encerradas en esas ~23 líneas:

  1. El directorio es el job: la convención inbox/{JobName}/{fichero} mapea el primer segmento de la key a una clase en App\Jobs:
    • Llega inbox/ProcessImage/abc.jpg → despacha App\Jobs\ProcessImage,
    • Llega inbox/ImportGuests/xyz.csv → despacha App\Jobs\ImportGuests,
    • ¿Necesitan agregar un nuevo tipo de proceso mañana? Solo deben crear el job: el converter no se toca.
  2. Validación contra ShouldQueue: is_a(..., ShouldQueue::class) resuelve la clase y verifica que implemente la interfaz de jobs encolables. Si alguien o algo sube un fichero a inbox/Whatever/x.bin, el converter lo ignora con un log de warning en vez de explotar.
  3. Despachamos la key completa: cada job recibe $key y se las arregla solo. Contrato uniforme para todos los jobs de la bandeja: "un constructor, una key".

El converter es un traductor con un único trabajo: escuchar ObjectCreated y responder dispatch().

Y la configuración en serverless.yml es mucho más simple respecto a la Opción A, escuchamos un único prefijo, y ejecutamos una única lambda:

functions:
    laravel:
        handler: Bref\LaravelBridge\Http\OctaneHandler
        runtime: php-85
        # ...

+   s3-event-converter:
+       handler: App\Lambda\S3EventConverter
+       runtime: php-85
+       memorySize: 256
+       timeout: 10
+       events:
+           - s3:
+               bucket: ${construct:storage.bucketName}
+               existing: true
+               event: s3:ObjectCreated:*
+               rules:
+                   -   prefix: inbox/
Enter fullscreen mode Exit fullscreen mode

El converter, que solo lee un JSON de S3 y ejecuta un SendMessage a SQS, funciona sobrado con 256 MB de memoria (medido en mi aplicación). Si quieren afinar al milímetro, con aws-lambda-power-tuning pueden encontrar el punto dulce entre duración y precio 14. Como es un salto en segundo plano, un cold-start no le quita el sueño a nadie.

Todo lo que no tuvimos que configurar:

  • Nada de permisos IAM: Lift ya da permiso sqs:SendMessage a todas las funciones del stack por el construct jobs 15, y acceso de lectura/escritura al bucket por el construct storage 16.
  • Nada de variables de cola: QUEUE_CONNECTION y SQS_QUEUE ya están definidos en provider.environment desde el capítulo anterior.
  • Sin layers adicionales: el layer GD vive solo en la función jobs (el queue:work del capítulo anterior). El converter es un SendMessage glorificado.
  • Sin lógica nueva: ProcessImage es el mismo job de siempre, #[Tries(3)], #[Backoff(30)], Intervention Image, etc.; solo cambia quién lo despacha.

¿Por qué es mejor que la Opción A?

Aprovecha toda la configuración del capítulo 4:

  • los reintentos los maneja Laravel con #[Tries] y #[Backoff],
  • los jobs agotados van a failed_jobs en DynamoDB con TTL,
  • las invocaciones que mueren a mitad de camino terminan en la DLQ con retención de 14 días y alerta por email,
  • batchSize y maxConcurrency frenan las avalanchas,
  • el job es testeable con Queue::fake() y corre en local con QUEUE_CONNECTION=sync.

Y tiene un beneficio arquitectónico sutil: El converter no escribe en S3, así que no genera nuevos eventos por sí mismo. Para evitar el loop en el flujo completo, los jobs también deben escribir fuera de inbox/.

¿Y qué hay de las desventajas?

Pues sí, las hay:

  • Latencia por un salto más: S3 → converter → SQS → worker, en vez de S3 → Lambda. Agregamos latencia de conversión, encolado y espera.
  • Es async igual que la opción A: si en el converter todo falla, el evento se descarta.
  • Más puntos que observar: una subida puede llegar a S3 y fallar antes de entrar a SQS. Necesitamos distinguir un fallo del converter de un fallo del job.
  • El despacho también puede duplicarse: si SendMessage tiene éxito, pero la invocación falla después, un reintento puede encolar el mismo trabajo otra vez. La idempotencia sigue siendo necesaria.
  • El converter necesita su propia política de fallos y observabilidad: Si el converter falló antes de encolar el Job, no existe ningún Job de Laravel que se pueda recuperar con queue:retry.

Comparando ambas opciones:

A: S3 → S3Handler directo B: S3 → Converter → SQS → worker
Piezas nuevas N lambdas, 1 por tipo de tarea (en esta implementación) 1 lambda única, se rutea todo al SQS existente
Reintentos Hasta 2 reintentos adicionales por defecto ante errores de función #[Tries] + #[Backoff] + reenvíos de Bref
Si falla, ¿dónde termina? Se descarta (o onFailure si se configura) Worker: failed_jobs / DLQ. Converter: destino de fallos propio, si se configura
Freno de concurrencia reservedConcurrency, sin el control de consumo de SQS maxConcurrency + reservedConcurrency
Riesgo de loop infinito Bajo si escribe fuera de inbox/ Nulo (el converter no escribe en S3), siempre que el job no escriba en inbox/
¿Agregar un tipo de upload? Nueva función + filtro Solo crear el Job; el converter no se toca
Tests / local Invocar la clase a mano Queue::fake(), QUEUE_CONNECTION=sync
Latencia extra Cero Conversión, encolado y espera en SQS
¿Cuándo elegirla? Procesamiento directo cuando no necesitamos reutilizar la cola de Laravel Cuando queremos reutilizar los jobs y el sistema de colas de Laravel

c) ¿Y por qué no apuntar S3 directo a la cola existente?

Ya que tenemos una cola que funciona perfecto, la pregunta obvia es: "¿y si S3 notifica directo a la cola jobs que creó Lift?" Al fin y al cabo, SQS es un destino válido de las notificaciones 2. Dos variantes, dos respuestas cortas: no funciona en ninguna.

Variante 1: S3 → función worker (destino Lambda). El QueueHandler de Bref no escucha eventos S3: extiende SqsHandler y cada mensaje pasa por SqsRecord, que valida el origen en el constructor 17:

public function __construct(mixed $record)
{
    if (! is_array($record) || ! isset($record['eventSource']) || $record['eventSource'] !== 'aws:sqs') {
        throw new InvalidArgumentException;
    }
    $this->record = $record;
}
Enter fullscreen mode Exit fullscreen mode

Un evento de S3 trae eventSource: "aws:s3", se lanza un InvalidArgumentException en el primer record. La Lambda se muere en el "hola".

Variante 2: S3 → cola jobs (destino SQS). Acá es más interesante, porque técnicamente podría funcionar... si el body del mensaje fuera el payload de Laravel. Pero S3 envía su propio JSON (el de la sección 2.c.) y Laravel espera un payload con campos como displayName, job, data y uuid, generado al despachar el job 18. Job::fire() arranca así 19:

public function fire()
{
    $payload = $this->payload();

    [$class, $method] = JobName::parse($payload['job']);
    // ...
}
Enter fullscreen mode Exit fullscreen mode

$payload['job'] no existe en el JSON de S3: el mensaje no tiene la estructura necesaria para ejecutar un job de Laravel. No podemos asumir que seguirá el ciclo normal de reintentos y terminará en failed_jobs; estamos entregándole al worker un formato que no entiende.

El contador attempts es otra pieza: cuando un job válido se libera para reintentarlo, Bref incrementa ese campo y reenvía el payload a SQS 20. Ese mecanismo no convierte una notificación de S3 en un job de Laravel.

Bonus: S3 exige una queue policy que autorice a s3.amazonaws.com a hacer SendMessage 2, que Lift no agrega; y al habilitar la notificación, S3 publica un evento s3:TestEvent con un formato distinto 4 que también rompería al worker.

Es meter la carta en el buzón correcto, pero escrita en otro idioma: el cartero la entrega, el destinatario no la entiende y la tira.

Por eso agregamos el converter: adapta el evento de S3 al formato que espera nuestro worker, sin modificar cómo procesa los jobs.


4. El Viaje Completo de una Foto

Pongamos todo junto. Así quedaría el recorrido completo de una foto con este diseño, de principio a fin, y cómo cambia respecto al "aviso del navegador":

Journey

a) Laravel crea la firma, el navegador sube a S3

El controlador crea el registro para la foto y devuelve la URL pre-firmada 21. El fichero se sube directamente a S3 en inbox/{JobName}/{file}. El directorio dice qué job lo va a procesar:

// MediaController::prepareFileUpload()
$media = Media::create([
    'status'   => MediaStatus::Uploading,
    'filename' => $filename = sprintf('%s.%s', Str::uuid()->toString(), $fileInfo['extension']),
    /* ... */
]);

$signedUrl = Storage::temporaryUploadUrl(
    path: "inbox/ProcessImage/{$filename}",
    expiration: now()->addMinutes(15),
    options: ['Content-Type' => $fileInfo['mime_type']],
);
Enter fullscreen mode Exit fullscreen mode

Detalle de seguridad: la URL pre-firmada solo permite subir a esa key exacta. El nombre del directorio y fichero lo elegimos nosotros, no el cliente; nadie puede hacer PUT a inbox/DeleteDatabase/x si no firmamos esa key.

El navegador sube el fichero directo a S3:

xhr.open('PUT', uploadData.upload_url);
xhr.send(file);
Enter fullscreen mode Exit fullscreen mode

b) S3 Confirma la Llegada

Cuando la subida desde el navegador finaliza, S3 emite el evento ObjectCreated:Put (o CompleteMultipartUpload si el frontend utiliza multipart), el filtro prefix: inbox/ lo deja pasar, y la notificación invoca a la lambda s3-event-converter asíncronamente.

c) El converter traduce y despacha

La Lambda lee la key (inbox/ProcessImage/9f8d7c6b-...jpg), extrae ProcessImage del directorio, verifica que sea un job encolable y despacha App\Jobs\ProcessImage::dispatch($key) a la cola.

La responsabilidad del converter termina al despachar el job a SQS. El procesamiento queda en el worker.

d) El worker hace el trabajo pesado

SQS invoca al Queue Worker del capítulo 4, el Worker de Laravel ejecuta ProcessImage. El job lee la imagen original desde inbox/, genera la versión 2048px y el thumbnail 600px, almacena las versiones generadas fuera de la bandeja de entrada (media/), actualiza el status a processing → completed, y termina vaciando la bandeja de entrada:

Simplificación del job para facilitar la lectura.

final class ProcessImage implements ShouldQueue, ShouldBeUnique {
    use Queueable;

    private readonly string $filename;

    private Media $media;

    public function __construct(
        public readonly string $key,
    ) {
        preg_match(S3EventConverter::INBOX_KEY, $key, $matches);
        $this->filename = $matches['file'];
    }

    public function uniqueId() {
        return $this->getMedia()->uuid;
    }

    public function handle(): void {
        // ..., verificamos si ya se procesó la imagen,
        // validamos que exista el fichero original, ...
        if (! Storage::exists($media_path = "inbox/ProcessImage/{$this->filename}")) {
            throw new Exception("El fichero original no existe");
        }

        // ... Procesar, escribir a media/, ...
        $image = Image::decodeStream(Storage::readStream($media_path));
        Storage::put("media/{$this->getMedia()->uuid}.webp", $image->encodeUsingFormat(Format::WEBP, quality: 85));

        // ..., actualiza el estado del registro Media, ...
        $this->getMedia()->update([ 'status' => MediaStatus::Completed ]);

        // ..., limpieza: la imagen original ya no es requerida
        Storage::delete($this->key);
    }

    private function getMedia(): Media {
        return $this->media ??= Media::ofFilename($this->filename)->query()->first();
    }
}
Enter fullscreen mode Exit fullscreen mode

Limpiar recién al final importa: si el job falla y Laravel lo reintenta, el original sigue ahí esperándolo.

e) Los Eventos que No Disparan al Converter

Acá es donde el diseño del prefijo inbox/ paga doble. Las escrituras del job se realizan en media/, fuera del prefijo, así que no generan invocaciones del converter, evitando loops infinitos.

Evitamos las invocaciones causadas por las versiones generadas. Por cada subida esperamos una invocación del converter, aunque los duplicados y reintentos siguen siendo posibles.

El Storage::delete() final emite un ObjectRemoved, pero solo escuchamos ObjectCreated.

f) ¿Y qué pasa con el PATCH del navegador?

El endpoint de status sigue existiendo, pero deja de ser el disparador del procesamiento: queda para registrar el evento failed si el navegador no pudo subir la foto.

El navegador pasó de ser el testigo principal a ser la notificación de cortesía.


5. Lo que No Te Cuentan los Tutoriales (Cuidados y Riesgos)

a) El loop infinito: el bucket que se llama a sí mismo

AWS lo advierte en la documentación oficial, con negrita y todo 1 10: si el destino de la notificación escribe en el mismo bucket que la dispara, pueden crear un loop infinito. upload → procesa → escribe thumbnail → dispara el mismo evento → ∞. El diseño inbox/ lo corta de raíz: solo los uploads aterrizan ahí, los resultados viven en otros directorios, y el delete final genera un ObjectRemoved que nadie escucha.

Dicho eso, el loop sigue siendo posible si no respetamos la convención. Para evitarlo, combinamos prevención en el diseño y una última red de seguridad:

  1. Filtrar en código: el converter valida la key antes de despachar, no permite pasar nada que no sea inbox/{Job}/{fichero}.
  2. Prefijo de entrada dedicado: inbox/ solo recibe uploads; ningún job debe escribir ahí. Si algún día un job necesita dejar una salida procesada, va a media/ o a otro directorio que corresponda, nunca a la bandeja.
  3. La red de seguridad de AWS: Lambda tiene recursive loop detection y viene activada por defecto: si detecta una cadena S3 → Lambda → S3 que se repite ~16 veces, corta la invocación y les avisa por email y en el Health Dashboard 22.

Ojo: la detección de recursividad es el airbag, no el cinturón. El corte llega tras aproximadamente 16 invocaciones de una misma cadena de solicitudes, no antes de que se genere consumo. Solo cubre loops entre Lambda, S3, SQS, SNS y los buses de eventos personalizados de EventBridge (con AWS SDK for PHP ≥ 3.232.0) 22. Un loop que pase por DynamoDB, por ejemplo, queda fuera de esta protección.

b) La key viene URL-encoded

Vuelve el detalle del key: mi foto.jpg llega como mi+foto.jpg 4. Y Bref no lo decodifica. BucketObject::getKey() devuelve el nombre tal y como figura en el JSON 23. Si hacen Storage::get('mi+foto.jpg') van a obtener un glorioso 404 que terminará en failed_jobs tres intentos después. urldecode() siempre, como primer paso del handler.

c) At-least-once + los reintentos de Lambda

Dos fuentes de duplicados: S3 puede publicar el mismo evento dos veces (raro, pero documentado) 1, y Lambda puede invocar al converter más de una vez con el mismo evento 11. Consecuencia: ProcessImage puede despacharse dos veces para la misma foto. La receta que yo utilicé es ShouldBeUnique usando el uuid del Media como uniqueId() 24 y validar si el fichero destino existe al iniciar el job.

d) Los huérfanos de la bandeja (y el Roomba de S3)

El Storage::delete($key) al finalizar el job deja inbox/ limpio; pero solo ocurre en el camino feliz.

Pero, ¿y si el job agota sus 3 intentos y termina en failed_jobs?

En ese caso, el fichero original se queda en la bandeja (que es justo lo que queremos). Sirve para reintentar con queue:retry, salvo que nunca se reintente y inbox/ se convierta en un depósito de basura facturado por GB-mes.

Para eso están las reglas lifecycleRules que agregamos al construct storage en la sección 3: S3 aplica una regla de expiración a los originales de inbox/ a partir de los 7 días 8. Si el bucket tiene versionado habilitado, la expiración crea un delete marker y la versión anterior queda sujeta a su propia política de limpieza; no se eliminan todas las versiones del fichero en ese momento 25. El mismo Roomba que limpia nuestra tabla caché de DynamoDB del capítulo 3, pero en versión bucket.

e) events.s3.existing: true tiene sus detalles

  • Solo un bucket existente por función; pero sí podemos declarar varios eventos de ese mismo bucket para la función, siempre que sus filtros sean compatibles.
  • Si CloudFormation no actualiza los triggers en deploys subsiguientes, se puede agregar forceDeploy: true para forzar la actualización 9.
  • La notificación tarda ~5 minutos en activarse tras el deploy; si prueban "subí un fichero y no pasó nada", esperen un rato antes de culpar al código 26.

f) Multipart uploads: el Put que no es Put

Si el frontend sube ficheros grandes implementando multipart, el evento no es ObjectCreated:Put sino ObjectCreated:CompleteMultipartUpload 2. Por eso optamos por escuchar s3:ObjectCreated:* en serverless.yml: con el wildcard se cubren todas las formas de crear un objeto.

g) Filtros que no se pueden pisar

Si en el futuro agregan una segunda función escuchando el mismo bucket con el mismo evento, los filtros prefix/suffix no pueden solaparse: si definen dos funciones con prefix: inbox/ y ObjectCreated:* el deploy será rechazado por S3 3. Otra razón por la cual optamos consolidar todo el ruteo en el converter.

h) Probar en local sin AWS

El converter es una clase PHP común, así que testearlo es fácil. Un JSON de ejemplo (recortado del evento real) en un test con Queue::fake(), instanciando el handler, invocando handleS3() con el S3Event armado a mano y validar que el job se envió a la cola con Queue::assertPushed(ProcessImage::class).

La clase ProcessImage de verdad corre en local con QUEUE_CONNECTION=sync, como siempre.

i) sequencer: el número que ordena el caos

S3 no garantiza orden, pero los eventos Put y Delete traen un sequencer hexadecimal creciente por key 4. Si algún día importa que "la última versión gana" (ej.: re-upload del mismo fichero), guarden el último sequencer procesado y descarten los menores. En mi caso no lo necesito, pero es gratis saberlo.

j) La limpieza del SDK

S3 ya estaba en la lista de removeUnusedServices del capítulo 2, así que no hay nada que agregar. Pero si su SDK está recortado, revisen que S3 y Sqs estén vivos antes de culpar al código.


6. ¿Cuánto Cuesta Conectar las Piezas?

Actualicemos la cuenta, como lo hacemos en cada capítulo.

  • S3 Event Notifications: 100% gratis. Ni publicar, ni filtrar, ni el s3:TestEvent tiene costo 27.
  • El converter: una invocación por evento; y gracias al prefijo inbox/, una invocación por upload (excluyendo duplicados y reintentos). Para un estimado de 100.000 uploads/mes:
    • 100.000 invocaciones a 256 MB ~100 ms
    • 100k requests ($0.02) + 2.500 GB-s ($0.04) ≈ $0.06/mes ($0.00 dentro del free tier) 28
  • SQS: estimamos ~$0.12 por las operaciones de los 100.000 mensajes y $0.25 por el polling, manteniendo el escenario del capítulo anterior: $0.37 en total 29.
  • El worker: el mismo costo que calculamos en el capítulo 4 (~$0.44/100k jobs en total) 28. El trabajo pesado no cambió.
~100k uploads/mes Free tier Tarifa plena
S3 Event Notifications (~100k avisos) $0.00 $0.00
Converter (~100k invocaciones, 256MB, 100 ms) $0.00 ~$0.06
SQS (300k requests /mensaje + 630k de polling) $0.00 ~$0.37
Worker (100k invocaciones, 512MB, 500 ms) $0.00 ~$0.44
Total mensual $0.00 ~$0.87

S3 no cobra por dar el aviso. La cuenta empieza cuando ponemos a trabajar al resto.


7. ¿Qué Sigue?

Hoy conectamos los cables del capítulo 3 "el fichero viaja del navegador a S3 sin tocar Lambda", y el worker del capítulo 4 "el trabajo pesado con todos sus reintentos, su DLQ y sus alarmas" mediante la lambda que actúa de traductor.

Hasta acá, Laravel despierta porque alguien hace un request o porque llega un evento. Pero hay tareas que no esperan un evento: las reservas deben vencer, se deben enviar recordatorios o limpiar datos a una hora determinada. Y para todos estos casos: ¿Quién despierta a nuestra aplicación Laravel para hacerlas si ya no tenemos un servidor con cron? En el próximo capítulo veremos cómo ejecutar el scheduler con EventBridge y Artisan, sin mantener un servidor pendiente del reloj.


Una pregunta para ustedes: ¿Cómo se entera hoy su aplicación de que terminó una subida: se lo cuenta el navegador o lo avisa el almacenamiento? Los leo en los comentarios.


  1. https://docs.aws.amazon.com/AmazonS3/latest/userguide/EventNotifications.html ↩

  2. https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html ↩

  3. https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-filtering.html ↩

  4. https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-content-structure.html ↩

  5. https://aws.amazon.com/blogs/storage/manage-event-ordering-and-duplicate-events-with-amazon-s3-event-notifications/ ↩

  6. https://bref.sh/docs/use-cases/s3 ↩

  7. https://github.com/brefphp/laravel-bridge/blob/a62196d5cb3efe95861fc6b78f7e5606bd2ad09d/src/HandlerResolver.php#L68-L94 ↩

  8. https://github.com/getlift/lift/blob/45ec61c6fb36e2a220326e62e4e543e5b11fbdbc/docs/storage.md ↩

  9. https://www.serverless.com/framework/docs/providers/aws/events/s3#using-existing-buckets ↩

  10. https://docs.aws.amazon.com/lambda/latest/dg/with-s3.html ↩

  11. https://docs.aws.amazon.com/lambda/latest/dg/invocation-async-error-handling.html ↩

  12. https://www.serverless.com/framework/docs/providers/aws/guide/functions#asynchronous-invocation ↩

  13. https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html ↩

  14. https://github.com/alexcasalboni/aws-lambda-power-tuning ↩

  15. https://github.com/getlift/lift/blob/45ec61c6fb36e2a220326e62e4e543e5b11fbdbc/docs/queue.md#permissions ↩

  16. https://github.com/getlift/lift/blob/45ec61c6fb36e2a220326e62e4e543e5b11fbdbc/docs/storage.md#permissions ↩

  17. https://github.com/brefphp/bref/blob/3b1dbda5680930187bd44b7c863429e570b35692/src/Event/Sqs/SqsRecord.php#L16-L17 ↩

  18. https://github.com/laravel/framework/blob/c42f9abd4a3d2f9a3cd6be109255ddce8092ceb8/src/Illuminate/Queue/Queue.php#L176-L215 ↩

  19. https://github.com/laravel/framework/blob/c42f9abd4a3d2f9a3cd6be109255ddce8092ceb8/src/Illuminate/Queue/Jobs/Job.php#L96-L103 ↩

  20. https://github.com/brefphp/laravel-bridge/blob/a62196d5cb3efe95861fc6b78f7e5606bd2ad09d/src/Queue/SqsJob.php#L13-L45 ↩

  21. https://laravel.com/framework/docs/13.x/filesystem#temporary-upload-urls ↩

  22. https://docs.aws.amazon.com/lambda/latest/dg/invocation-recursion.html ↩

  23. https://github.com/brefphp/bref/blob/3b1dbda5680930187bd44b7c863429e570b35692/src/Event/S3/BucketObject.php#L24-L27 ↩

  24. https://laravel.com/framework/docs/13.x/queues#unique-jobs ↩

  25. https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-considerations.html ↩

  26. https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-enable-disable-notification-intro.html ↩

  27. https://aws.amazon.com/s3/faqs/ ↩

  28. https://aws.amazon.com/lambda/pricing/ ↩

  29. https://aws.amazon.com/sqs/pricing/ ↩

Top comments (0)