Laravel SQS Extended

소개

Laravel SQS Extended는 AWS SQS 페이로드 크기 제한을 우회하기 위해 설계된 Laravel 큐 드라이버입니다. 이 큐 드라이버는 큰 페이로드를 자동으로 디스크(일반적으로 S3)에 직렬화한 다음 실행 시 비직렬화합니다. 이 패키지는 https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-s3-messages.html에서 영감을 받았습니다.

Simple SQS Extended 클라이언트에서의 마이그레이션

프로젝트에서 simplesoftwareio/simple-sqs-extended-client 패키지를 제거합니다.
defectivecode/laravel-sqs-extended 패키지를 설치합니다.

기존 구성은 새로운 패키지와 호환됩니다. 유일한 변경점은 패키지 이름입니다.

설치

먼저 모든 큰 SQS 페이로드를 저장할 버킷을 생성합니다.

SQS 페이로드를 저장할 때는 비공개 버킷을 사용할 것을 강력히 권장합니다. 페이로드는 민감한 정보를 포함할 수 있으며 절대 공개적으로 공유되어서는 안 됩니다.

큐 드라이버를 설치하려면 composer require defectivecode/laravel-sqs-extended를 실행합니다.
그런 다음, queue.php 파일에 다음 기본 큐 설정을 추가합니다.

Laravel Vapor 사용자들은 연결 이름을 sqs로 설정해야 합니다. sqs 연결은 Vapor Core 내에서 검색되며 다른 연결 이름을 사용하면 이 라이브러리가 예상대로 작동하지 않습니다.

/*
|--------------------------------------------------------------------------
| SQS 디스크 큐 구성
|--------------------------------------------------------------------------
|
| 여기에서 SQS 디스크 큐 드라이버를 구성할 수 있습니다. 이 드라이버는 내장된 Laravel SQS 큐 드라이버와 동일한 모든
| 구성 옵션을 공유합니다. 추가된 유일한 옵션은 아래에서 설명하는 `disk_options`입니다.
|
| always_store: 모든 페이로드가 큐의 크기 제한에 관계없이 디스크에 저장되어야 하는지를 결정합니다.
| cleanup:      작업이 처리된 후 페이로드 파일을 디스크에서 제거해야 하는지를 결정합니다. 파일을 남겨두는 것은
|                 나중에 디버깅 목적으로 큐 작업을 재생하는 데 유용할 수 있습니다.
| disk:         SQS 페이로드를 저장할 디스크입니다. 이 디스크는 Laravel의 filesystems.php 구성 파일에서 구성되어야 합니다.
| max_size:     선택 사항입니다. 오프로드 임계값을 고정된 바이트 수로 설정합니다. 생략할 경우 임계값은
|                 큐 자체에서 읽어옵니다. 아래의 "페이로드 크기 임계값"을 참조하십시오.
| prefix        페이로드를 저장할 접두사(폴더)입니다. 다른 SQS 큐와 디스크를 공유하는 경우 유용합니다.
|                 접두사를 사용하면 queue:clear 명령을 통해 동일한 디스크를 공유하는 다른 sqs-disk 백업 큐와 별도로
|                 파일을 삭제할 수 있습니다.
|
*/
'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',
    ],
],

큐를 시작하고 SQS의 페이로드 제한에 대한 걱정 없이 수익을 얻으세요 🥳

페이로드 크기 임계값

AWS는 2025년 8월에 최대 SQS 페이로드를 256 KiB에서 1 MiB로 높였지만, MaximumMessageSize는 큐별 속성입니다. 즉, 그 변경 전에 생성된 큐는 이전 262144 바이트 값을 유지하며, 이 값을 증가시키기 전까지는 그 한계를 가집니다. 이 패키지는 어느 제한을 가정하기보다는 큐에서 속성을 읽고 실제로 적합하지 않은 페이로드만 오프로드합니다.

임계값은 다음 순서로 해결되며, 첫 번째 일치 항목이 우선시됩니다. 페이로드의 길이가 해결된 임계값보다 크거나 같을 때 해당 페이로드는 디스크에 저장됩니다.

조건	임계값	큐 속성을 읽음
`always_store`가 `true`인 경우	모든 페이로드가 저장됨	아니오
`max_size`가 설정된 경우	구성된 값	아니오
큐가 `262144`를 보고하는 경우 (2025년 이전 기본값)	250000	예
큐가 `1048576`을 보고하는 경우 (최대치로 상승)	1036432	예
속성을 읽을 수 없는 경우	250000	한 번 시도됨

12144 바이트의 예약된 여유 공간은 메시지별 오버헤드를 커버하며, 큐가 262144 바이트 기본값에서 유지되도록 크기를 조정하여 이전 버전의 패키지가 사용하는 250000 바이트 임계값으로 해결됩니다. 큐의 한계를 높이지 않는 한 업그레이드는 행동을 변경하지 않습니다.

권한

속성을 읽으려면 sqs:GetQueueAttributes 권한이 필요합니다. 결과는 각 큐당 메모리에 캐싱되므로, 프로세스의 수명 동안 큐당 하나의 호출만 필요하며 각 작업에 대해 하나의 호출이 필요하지 않습니다.

속성을 읽을 수 없는 경우 — 협소한 IAM 정책 또는 이를 구현하지 않는 SQS 에뮬레이터 — 드라이버는 250000 바이트 임계값으로 기본값으로 돌아가고 발송을 계속합니다. 권한을 부여하고 싶지 않으면 max_size를 설정하여 조회를 건너뛸 수 있습니다.

큐의 한계 높이기

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

SQS는 사용량을 64 KB 청크로 측정하므로 단일 1 MiB 메시지는 16개의 요청으로 청구됩니다. 큰 페이로드를 디스크에 저장하는 것은 종종 더 저렴한 경로입니다.

지원 지침

우리의 오픈 소스 패키지를 선택해 주셔서 감사합니다! 이 지원 지침을 확인하는데 잠시 시간을 할애해 주세요. 이 지침은 우리 프로젝트를 최대한 활용하는 데 도움이 될 것입니다.

커뮤니티 주도 지원

우리의 오픈 소스 프로젝트는 훌륭한 커뮤니티에 의해 구동됩니다. 질문이 있거나 도움이 필요하다면 StackOverflow와 다른 온라인 리소스가 최선의 선택입니다.

버그 및 기능 우선순위

오픈 소스 프로젝트를 관리하는 현실은 모든 보고된 버그나 기능 요청을 즉시 처리할 수 없다는 것입니다. 우리는 문제를 다음과 같은 순서로 우선 처리합니다:

1. 유료 제품에 영향을 주는 버그

우리의 유료 제품에 영향을 미치는 버그는 항상 최우선 순위입니다. 경우에 따라 우리에게 직접적인 영향을 미치는 버그만 처리할 수도 있습니다.

2. 커뮤니티 풀 리퀘스트

버그를 발견하고 해결책이 있다면, 풀 리퀘스트를 제출해 주세요. 우리 제품에 영향을 미치는 문제 다음으로, 이러한 커뮤니티 주도 수정을 우선적으로 처리합니다. 리뷰하고 승인된 후, 귀하의 해결책을 병합하고 기여를 인정할 것입니다.

3. 재정적 지원

언급된 범주 외의 문제에 대해서는 해결을 위한 자금을 기부할 수 있습니다. 각 열려 있는 문제는 재정적으로 기여할 수 있는 주문 양식에 연결되어 있습니다. 제공된 자금 금액에 따라 이러한 문제를 우선 처리합니다.

커뮤니티 기여

오픈 소스는 커뮤니티가 활발할 때 성장합니다. 버그를 수정하지 않더라도 코드 개선, 문서 업데이트, 튜토리얼, 또는 커뮤니티 채널에서 다른 사람들을 도와주는 방식으로 기여하는 것을 고려해 보세요. 우리는 모두가 커뮤니티로서 오픈 소스 작업을 지원하는 것을 강력히 권장합니다.

다시 말해, DefectiveCode는 유료 제품에 영향을 미치는 정도, 커뮤니티 풀 리퀘스트 및 문제에 대한 재정적 지원을 기반으로 버그를 우선 처리할 것입니다.

라이선스 - MIT 라이선스

본 소프트웨어 및 관련 문서 파일(이하 "소프트웨어")의 사본을 얻은 모든 개인에게 무료로 사용 권한이 부여되며, 소프트웨어를 제한 없이 사용할 수 있습니다. 여기에는 소프트웨어를 사용, 복사, 수정, 병합, 게시, 배포, 서브 라이센스 및/또는 판매하는 권리가 포함되며, 소프트웨어가 제공된 사람에게 그러한 권한을 허용하는 것이 포함됩니다. 단, 다음 조건을 준수해야 합니다:

소프트웨어는 "있는 그대로" 제공되며, 명시적이거나 암시적인 어떤 종류의 보증도 없이 제공됩니다. 여기에는 상업성, 특정 목적에 대한 적합성 및 비침해성에 대한 보증이 포함되지만 이에 국한되지 않습니다. 어떤 경우에도 저자나 저작권자는 계약, 불법행위 또는 기타 방식으로 소프트웨어 또는 소프트웨어의 사용이나 기타 거래와 관련하여 발생하는 어떤 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다.

🔗Laravel SQS Extended

🔗소개

🔗Simple SQS Extended 클라이언트에서의 마이그레이션

🔗설치

🔗페이로드 크기 임계값

권한