Laravel SQS Extended
Directrices de Soporte
- Soporte Impulsado por la Comunidad
- Errores y Priorización de Funciones
Licencia - Licencia MIT

Laravel SQS Extended

Introducción

Laravel SQS Extended es un controlador de colas de Laravel que fue diseñado para sortear los límites de tamaño de carga útil de AWS SQS. Este controlador de colas serializa automáticamente cargas útiles grandes a un disco (típicamente S3) y luego las deserializa en tiempo de ejecución. Este paquete se inspiró en https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-s3-messages.html.

Migración desde Simple SQS Extended Client

Elimina el paquete simplesoftwareio/simple-sqs-extended-client de tu proyecto.
Instala el paquete defectivecode/laravel-sqs-extended.

La configuración anterior es compatible con el nuevo paquete. El único cambio es el nombre del paquete.

Instalación

Primero, crea un bucket que contendrá todas tus cargas útiles grandes de SQS.

Te recomendamos encarecidamente que utilices un bucket privado al almacenar cargas útiles de SQS. Las cargas útiles pueden contener información sensible y no deben compartirse públicamente.

Ejecuta composer require defectivecode/laravel-sqs-extended para instalar el controlador de colas.
Luego, agrega la siguiente configuración de cola predeterminada a tu archivo queue.php.

Los usuarios de Laravel Vapor deben establecer el nombre de la conexión en sqs. La conexión sqs es buscada dentro de Vapor Core y esta biblioteca no funcionará como se espera si utilizas un nombre de conexión diferente.

/*
|--------------------------------------------------------------------------
| Configuración de la Cola SQS Disk
|--------------------------------------------------------------------------
|
| Aquí puedes configurar el controlador de colas SQS disk. Comparte todas las mismas
| opciones de configuración del controlador de colas SQS incorporado de Laravel. La única opción
| añadida es `disk_options` que se explica a continuación.
|
| always_store: Determina si todas las cargas útiles deben almacenarse en un disco sin importar el límite de tamaño de la cola.
| cleanup:      Determina si los archivos de carga útil deben ser eliminados del disco una vez que el trabajo ha sido procesado. Dejar los
|                 archivos puede ser útil para reproducir los trabajos de la cola más tarde por razones de depuración.
| disk:         El disco donde se guardarán las cargas útiles de SQS. Este disco debe configurarse en tu archivo de configuración filesystems.php de Laravel.
| max_size:     Opcional. Fija el umbral de descarga a un número fijo de bytes. Cuando se omite, el umbral se lee de
|                 la cola misma. Consulta "Umbral de tamaño de carga útil" a continuación.
| prefix        El prefijo (carpeta) para almacenar las cargas útiles. Esto es útil si compartes un disco con otras colas SQS.
|                 Usar un prefijo permite que el comando queue:clear destruya los archivos por separado de otras colas respaldadas por sqs-disk
|                 que comparten el mismo disco.
|
*/
'sqs' => [
    'driver' => 'sqs-disk',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'prefix' => env('SQS_PREFIX', 'https://sqs.us-east-1.amazonaws.com/your-account-id'),
    'queue' => env('SQS_QUEUE', 'default'),
    'suffix' => env('SQS_SUFFIX'),
    'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
    'after_commit' => false,
    'disk_options' => [
        'always_store' => false,
        'cleanup' => false,
        'disk' => env('SQS_DISK'),
        'prefix' => 'bucket-prefix',
    ],
],

Activa tus colas y disfruta sin preocuparte por el límite de carga útil de SQS 🥳

Umbral de tamaño de carga útil

AWS aumentó la carga útil máxima de SQS de 256 KiB a 1 MiB en agosto de 2025, pero MaximumMessageSize es un atributo por cola; las colas creadas antes de ese cambio mantienen el antiguo valor de 262144 bytes hasta que lo aumentes. En lugar de asumir cualquiera de los límites, este paquete lee el atributo de la cola y descarga solo lo que realmente no cabe.

El umbral se resuelve en el siguiente orden, y la primera coincidencia gana. Una carga útil se almacena en el disco cuando su longitud es mayor o igual al umbral resuelto.

Condición	Umbral	Lee el atributo de la cola
`always_store` es `true`	Cada carga útil se almacena	No
`max_size` está configurado	El valor configurado	No
La cola informa `262144` (el valor predeterminado anterior a 2025)	250000	Sí
La cola informa `1048576` (aumentada al máximo)	1036432	Sí
No se puede leer el atributo	250000	Intentado una vez

El margen reservado de 12144 bytes cubre el overhead por mensaje y se dimensiona para que una cola que se deja en el valor predeterminado de 262144 bytes se resuelva al umbral de 250000 bytes utilizado por versiones anteriores de este paquete. La actualización no cambia el comportamiento hasta que aumentes el límite de la cola.

Permisos

Leer el atributo requiere sqs:GetQueueAttributes. El resultado se almacena en caché en memoria por cola, por lo que esto cuesta una llamada por cola durante la vida del proceso en lugar de una llamada por trabajo.

Si no se puede leer el atributo —una política IAM restringida, o un emulador de SQS que no lo implementa— el controlador retrocede al umbral de 250000 bytes y continúa despachando. Configura max_size para omitir completamente la búsqueda si prefieres no conceder el permiso.

Aumentar el límite de una cola

aws sqs set-queue-attributes \
    --queue-url https://sqs.us-east-1.amazonaws.com/your-account-id/your-queue \
    --attributes MaximumMessageSize=1048576

Ten en cuenta que SQS mide el uso en bloques de 64 KB, por lo que un solo mensaje de 1 MiB se factura como 16 solicitudes. Almacenar cargas útiles grandes en un disco es a menudo el camino más económico.

Directrices de Soporte

¡Gracias por elegir nuestro paquete de código abierto! Tómate un momento para revisar estas directrices de soporte. Te ayudarán a sacar el máximo provecho de nuestro proyecto.

Soporte Impulsado por la Comunidad

Nuestro proyecto de código abierto es impulsado por nuestra increíble comunidad. Si tienes preguntas o necesitas asistencia, StackOverflow y otros recursos en línea son tus mejores opciones.

Errores y Priorización de Funciones

La realidad de gestionar un proyecto de código abierto significa que no podemos abordar cada error reportado o solicitud de función de inmediato. Priorizamos los problemas en el siguiente orden:

1. Errores que Afectan Nuestros Productos de Pago

Los errores que impactan nuestros productos de pago siempre serán nuestra máxima prioridad. En algunos casos, solo abordaremos los errores que nos afectan directamente.

2. Solicitudes de Extracción de la Comunidad

Si has identificado un error y tienes una solución, por favor envía una solicitud de extracción. Después de los problemas que afectan a nuestros productos, damos la siguiente mayor prioridad a estas soluciones impulsadas por la comunidad. Una vez revisada y aprobada, integraremos tu solución y daremos crédito a tu contribución.

3. Apoyo Financiero

Para problemas fuera de las categorías mencionadas, puedes optar por financiar su resolución. Cada problema abierto está vinculado a un formulario de pedido donde puedes contribuir financieramente. Priorizamos estos problemas según la cantidad de financiamiento proporcionada.

Contribuciones de la Comunidad

El código abierto prospera cuando su comunidad está activa. Incluso si no estás solucionando errores, considera contribuir a través de mejoras de código, actualizaciones de documentación, tutoriales o asistiendo a otros en los canales de la comunidad. Animamos encarecidamente a todos, como comunidad, a ayudar a apoyar el trabajo de código abierto.

Para reiterar, DefectiveCode priorizará los errores en función de cómo impactan a nuestros productos de pago, las solicitudes de extracción de la comunidad y el apoyo financiero recibido para los problemas.

Licencia - Licencia MIT

Por la presente se otorga permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricciones, incluyendo sin limitación los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y a permitir a las personas a las que se les proporciona el Software hacerlo, sujeto a las siguientes condiciones:

La mención de copyright anterior y esta nota de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITÁNDOSE A LAS GARANTÍAS DE COMERCIALIZABILIDAD, ADECUACIÓN PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO O OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, QUE SURJA DE, O EN CONEXIÓN CON EL SOFTWARE O EL USO O OTRAS NEGOCIACIONES EN EL SOFTWARE.

🔗Laravel SQS Extended

🔗Introducción

🔗Migración desde Simple SQS Extended Client

🔗Instalación

🔗Umbral de tamaño de carga útil