📖 11주차 02강: 비동기 큐(Queues) 작업 처리와 라라벨 호라이즌(Horizon) 모니터링

<?php

namespace App\Jobs;

use App\Models\Book;
use App\Models\User;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;
use Throwable;

class ProcessBookWatermarkJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    /**
     * 작업 최대 재시도 횟수
     */
    public int $tries = 3;

    /**
     * 작업 최대 허용 실행 시간(초) - 초과 시 실패 처리
     */
    public int $timeout = 120;

    /**
     * 재시도 간격(초) - 지수 백오프 적용 (1회차 5초, 2회차 15초, 3회차 45초)
     */
    public array $backoff = [5, 15, 45];

    /**
     * 새 Job 인스턴스 생성
     */
    public function __construct(
        public User $user,
        public Book $book,
        public string $orderNumber
    ) {
        // 'watermark' 전용 우선순위 큐 지정
        $this->onQueue('watermark');
    }

    /**
     * 백그라운드 워커에 의해 실행되는 작업 본문
     */
    public function handle(): void
    {
        Log::info("[큐 작업 시작] 사용자 '{$this->user->name}'을 위한 '{$this->book->title}' 전자책 워터마크 작업 시작");

        // 1. 원본 PDF 경로 확인
        $sourcePdf = "ebooks/originals/{$this->book->id}.pdf";
        if (!Storage::disk('local')->exists($sourcePdf)) {
            throw new \Exception("도서 ID {$this->book->id}의 원본 PDF 파일을 찾을 수 없습니다.");
        }

        // 2. 가상의 무거운 워터마크 프로세싱 시뮬레이션
        // (실제 실무에서는 setasign/fpdi 라이브러리 등을 사용하여 PDF 각 페이지 하단에 텍스트를 인쇄함)
        sleep(3); // 3초 소요되는 CPU 작업

        $watermarkText = "구매자: {$this->user->name} ({$this->user->email}) | 주문번호: {$this->orderNumber}";
        $outputPdfPath = "ebooks/watermarked/{$this->user->id}_{$this->book->id}.pdf";

        Storage::disk('local')->put($outputPdfPath, "WATERMARKED CONTENT FOR: {$watermarkText}");

        Log::info("[큐 작업 완료] 도서 '{$this->book->title}' 워터마크 PDF 생성 완료: {$outputPdfPath}");
    }

    /**
     * 모든 재시도($tries)가 실패했을 때 호출되는 최종 실패 콜백
     */
    public function failed(?Throwable $exception): void
    {
        Log::critical("[큐 작업 최종 실패] 전자책 워터마크 생성 실패! 긴급 점검 필요", [
            'user_id' => $this->user->id,
            'book_id' => $this->book->id,
            'error' => $exception?->getMessage(),
        ]);

        // 관리자에게 알림 또는 고객 주문 상태를 '워터마크 생성 실패'로 갱신
    }
}

// 즉시 큐로 디스패치
ProcessBookWatermarkJob::dispatch($user, $book, $order->order_number);

// 10초 뒤에 실행되도록 지연(Delay) 디스패치
ProcessBookWatermarkJob::dispatch($user, $book, $order->order_number)
    ->delay(now()->addSeconds(10));

// 여러 작업 순차 체이닝 (PDF 워터마크 완료 후 -> DRM 암호화 -> 다운로드 링크 발송)
use Illuminate\Support\Facades\Bus;

Bus::chain([
    new ProcessBookWatermarkJob($user, $book, $order->order_number),
    new EncryptDrmEbookJob($user, $book),
    new SendEbookDownloadLinkJob($user, $book),
])->dispatch();

'environments' => [
    'local' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['high', 'watermark', 'default'],
            'balance' => 'auto', // 큐 작업량에 따라 워커 수 동적 조절
            'minProcesses' => 1,
            'maxProcesses' => 5,
            'tries' => 3,
        ],
    ],
],

use Illuminate\Contracts\Queue\ShouldBeUnique;

class ProcessBookWatermarkJob implements ShouldQueue, ShouldBeUnique
{
    // 60초 동안 동일 도서 및 사용자에 대한 중복 큐 진입 방지
    public int $uniqueFor = 60;

    public function uniqueId(): string
    {
        return $this->user->id . '-' . $this->book->id;
    }
}