Lỗi Accelerator

Phạm vi

Năm ngoại lệ này phơi bày các lỗi từ sidecar tăng-tốc-phần-cứng Spectrum (Prism) tùy chọn. Sidecar được tiếp cận qua HTTP thông qua NextPDF\Accelerator\SpectrumClient; các phản hồi lỗi mang một mã SPEC-* máy đọc được từ một phân loại chuẩn tắc, và ứng dụng khách ánh xạ mã đó vào một trong các kiểu ngoại lệ bên dưới.

Khác với hầu hết các ngoại lệ NextPDF, các ngoại lệ Accelerator không hiện thực getContext(). Chúng mở rộng RuntimeException của PHP và phơi bày trạng thái của chúng dưới dạng các thuộc tính công khai readonly, có kiểu. Hãy phân biệt các lĩnh vực lỗi bằng cách khớp tiền tố specCode (ví dụ str_starts_with($e->specCode, 'SPEC-AUTH-')), không bằng cách bắt các lớp con — phân cấp lớp con là nội bộ và có thể thay đổi trong các phiên bản minor.

SpectrumApiException

SpectrumApiException là kiểu cơ sở cho mọi phản hồi lỗi của sidecar. Nó được ném trực tiếp cho bất kỳ mã SPEC-* nào không có lớp con cụ thể hơn, và nó là kiểu bạn bắt để xử lý mọi lỗi sidecar cùng một lúc.

Khi nào nó được ném

• Sidecar trả về một thân lỗi SPEC-* có cấu trúc. SpectrumResponseParser giải mã thân và ném kiểu này cho mọi mã trừ SPEC-AUTH-* và SPEC-OOM-* (vốn ánh xạ tới các lớp con bên dưới). Các ánh xạ đã lập tài liệu tới kiểu cơ sở này bao gồm SPEC-INDEX-* (collection index), SPEC-KMS-* (nhà cung cấp quản-lý-khóa), SPEC-OCR-*, SPEC-MODEL-*, và SPEC-BILLING-*.
• SPEC-IO-001 — thân phản hồi không phải JSON hợp lệ (httpStatus 502).
• SPEC-IO-002 — phiên bản API của sidecar không tương thích với minApiVersion được cấu hình.
• SPEC-SEC-001 — một payload tài liệu vượt quá ngân sách kích thước được cấu hình (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — một đường dẫn workspace thất bại ở bước kiểm tra traversal (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — một định danh job rỗng, quá dài, hoặc chứa các ký tự ngoài allowlist opaque-ID (SpectrumSecurityPolicy::validateJobId()).

Thuộc tính

Thuộc tính	Kiểu	Ý nghĩa
specCode	string	Mã lỗi SPEC-* máy đọc được (ví dụ SPEC-INDEX-003).
httpStatus	int	Trạng thái HTTP mà sidecar trả về; mặc định là 500. Cũng được dùng làm mã ngoại lệ.
retryable	bool	Liệu thao tác có thể được thử lại an toàn hay không. Mặc định là false.
traceId	?string	Trace ID tương quan từ header phản hồi X-Trace-Id, hoặc null.

Thông báo được tạo thành "[{specCode}] {message}". Ba predicate helper phân loại các lĩnh vực phổ biến: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*), và isOcrError() (SPEC-OCR-*).

Khôi phục

1. Đọc specCode để xác định lĩnh vực thất bại; rẽ nhánh theo tiền tố của nó.
2. Tôn trọng retryable: chỉ thử lại khi nó là true, và không bao giờ trên một mã SPEC-SEC-* hoặc SPEC-IO-002, vốn báo hiệu các khiếm khuyết cấu hình hoặc tương thích.
3. Ghi lại traceId trong nhật ký của bạn để tương quan lỗi với chẩn đoán phía-sidecar trong một báo cáo lỗi.

Các lớp con Spectrum

Các kiểu sau là các lớp con final của SpectrumApiException. Hãy bắt SpectrumApiException (hoặc khớp trên specCode) thay vì các lớp này trực tiếp.

SpectrumAuthenticationException

Được ném cho các mã SPEC-AUTH-*, cho biết một lỗi ràng buộc license, token, hoặc deployment. SpectrumResponseParser nêu nó ra bất cứ khi nào mã phản hồi bắt đầu bằng SPEC-AUTH-.

Các nguyên nhân đã lập tài liệu bao gồm SPEC-AUTH-001 (chữ ký Ed25519 license không hợp lệ), SPEC-AUTH-002 (license hết hạn và ngoài thời gian ân hạn), SPEC-AUTH-003 (sai khớp deployment slot), SPEC-AUTH-004 (JWT Bearer token không hợp lệ), SPEC-AUTH-006 (license suy giảm, ân hạn đã hết), và SPEC-AUTH-007 (tính năng không có trong license đã mua).

Nó mang cùng các thuộc tính như kiểu cơ sở, nhưng constructor ghim retryable thành false và mặc định httpStatus thành 403.

Khôi phục. Các lỗi này không bao giờ thử lại được nếu không có sự can thiệp của người vận hành. Gia hạn hoặc sửa license, làm mới Bearer token, hoặc căn chỉnh deployment slot, rồi chạy lại lệnh gọi.

SpectrumResourceException

Được ném cho các mã SPEC-OOM-* khi bộ nhớ GPU hoặc CPU bị cạn kiệt. SpectrumResponseParser nêu nó ra cho bất kỳ tiền tố SPEC-OOM- nào, và thiết lập DegradePolicy::FailFast nêu nó ra thay vì âm thầm hạ cấp xuống một tier phần cứng thấp hơn.

Constructor ghim retryable thành true và mặc định httpStatus thành 503.

Khôi phục. Ngoại lệ này thử lại được. Xếp hàng job và thử lại sau khi các job khác hoàn tất và giải phóng tài nguyên, hoặc nới DegradePolicy về AllowWithLog / WarnAndProceed nếu một tier bị hạ cấp là chấp nhận được cho workload.

SpectrumProtocolException

Được ném khi một phản hồi sidecar phân tích được dưới dạng JSON nhưng không khớp với hình dạng giao thức mong đợi. Nó luôn dùng specCode SPEC-IO-003 và httpStatus 502, với retryable được ghim thành false.

Cái này khác với SPEC-IO-001 (JSON không hợp lệ): ở đây JSON hợp khuôn nhưng sai về cấu trúc, điều thường cho thấy một proxy hoặc gateway đang viết lại thân, một phiên bản sidecar không tương thích, hoặc một phản hồi bị hỏng.

Khôi phục. Không thử lại được — hình dạng phản hồi là tất định với một phiên bản sidecar cho trước. Kiểm tra phiên bản sidecar đối với minApiVersion của ứng dụng khách, kiểm tra bất kỳ proxy hoặc gateway trung gian nào, rồi triển khai lại một sidecar tương thích.

SpectrumNotAvailableException

SpectrumNotAvailableException mở rộng trực tiếp RuntimeException và không thuộc phân cấp SpectrumApiException. Nó báo hiệu rằng sidecar không thể tiếp cận hoặc thất bại ở một health check, trước khi bất kỳ thân lỗi SPEC-* nào có thể được trả về.

Khi nào nó được ném

• Circuit breaker đang mở, hoặc tất cả các lần thử lại đã cạn kiệt (SpectrumClient).
• Một lỗi truyền tải HTTP xảy ra trong khi liên lạc với sidecar; PSR-18 ClientExceptionInterface nền được móc xích làm ngoại lệ trước.
• Một stream server-sent-events được yêu cầu trong khi sidecar tự báo cáo là không có sẵn (SseStreamClient).

Thuộc tính

Kiểu này không mang siêu dữ liệu SPEC-*. Thông báo được tạo thành "Spectrum sidecar unavailable: {reason}", với một code số nguyên tùy chọn và một throwable previous được móc xích.

Khôi phục

Bắt cái này khi Spectrum là tùy chọn và dự phòng về xử lý PHP-bản-địa (suy giảm nhẹ nhàng). Khi Spectrum là bắt buộc, xác nhận sidecar đang chạy và có thể tiếp cận, rồi chạy lại lệnh gọi.

Xem thêm

• Chỉ mục tài liệu tham khảo lỗi
• Mã hóa và quyền
• Chỉ mục cơ sở tri thức