ข้อผิดพลาด Accelerator

ขอบเขต

exception ทั้งห้าตัวนี้ปรากฏความล้มเหลวจาก Spectrum (Prism) hardware-accelerator sidecar แบบเสริม sidecar เข้าถึงผ่าน HTTP ผ่าน NextPDF\Accelerator\SpectrumClient การตอบกลับข้อผิดพลาดพกพารหัส SPEC-* ที่เครื่องอ่านได้จาก taxonomy ตามแบบ และ client map รหัสนั้นไปยังหนึ่ง ในชนิด exception ด้านล่าง

ไม่เหมือน exception ส่วนใหญ่ของ NextPDF exception ของ Accelerator ไม่ นำ getContext() ไปใช้ มันสืบทอดจาก RuntimeException ของ PHP และเปิดเผยสถานะเป็น พร็อพเพอร์ตี public แบบมีชนิด readonly แยกแยะโดเมนข้อผิดพลาดโดยจับคู่ prefix ของ specCode (ตัวอย่างเช่น str_starts_with($e->specCode, 'SPEC-AUTH-')) ไม่ใช่โดยการจับซับคลาส — ลำดับชั้นซับคลาสเป็นภายในและอาจเปลี่ยน ในเวอร์ชัน minor

SpectrumApiException

SpectrumApiException เป็นชนิดฐานสำหรับการตอบกลับข้อผิดพลาด sidecar ทุกตัว มัน ถูกยกโดยตรงสำหรับรหัส SPEC-* ใดๆ ที่ไม่มีซับคลาสที่เฉพาะเจาะจงกว่า และมัน เป็นชนิดที่คุณจับเพื่อจัดการข้อผิดพลาด sidecar ทั้งหมดในคราวเดียว

เมื่อใดที่ถูกโยน

• sidecar คืน body ข้อผิดพลาด SPEC-* แบบมีโครงสร้าง SpectrumResponseParser ถอดรหัส body และยกชนิดนี้สำหรับรหัสทั้งหมดยกเว้น SPEC-AUTH-* และ SPEC-OOM-* (ซึ่ง map ไปยังซับคลาสด้านล่าง) การ map ที่บันทึกไว้ไปยังชนิดฐาน นี้รวมถึง SPEC-INDEX-* (collection index), SPEC-KMS-* (key-management provider), SPEC-OCR-*, SPEC-MODEL-*, และ SPEC-BILLING-*
• SPEC-IO-001 — body การตอบกลับไม่ใช่ JSON ที่ถูกต้อง (httpStatus 502)
• SPEC-IO-002 — เวอร์ชัน API ของ sidecar ไม่เข้ากันกับ minApiVersion ที่ กำหนดค่าไว้
• SPEC-SEC-001 — payload เอกสารเกินงบประมาณขนาดที่กำหนดค่าไว้ (SpectrumSecurityPolicy::validatePayloadSize())
• SPEC-SEC-003 — path ของ workspace ล้มเหลวการตรวจ traversal (SpectrumSecurityPolicy::validateWorkspacePath())
• SPEC-SEC-004 — ตัวระบุ job ว่าง ยาวเกินไป หรือมีอักขระ นอก allowlist ของ opaque-ID (SpectrumSecurityPolicy::validateJobId())

คุณสมบัติ

Property	Type	Meaning
specCode	string	รหัสข้อผิดพลาด SPEC-* ที่เครื่องอ่านได้ (ตัวอย่างเช่น SPEC-INDEX-003)
httpStatus	int	สถานะ HTTP ที่ sidecar คืน ค่าเริ่มต้นเป็น 500 ใช้เป็นรหัส exception ด้วย
retryable	bool	operation อาจถูกลองใหม่อย่างปลอดภัยได้หรือไม่ ค่าเริ่มต้นเป็น false
traceId	?string	trace ID สำหรับเชื่อมโยงจาก header การตอบกลับ X-Trace-Id หรือ null

ข้อความถูกประกอบเป็น "[{specCode}] {message}" predicate helper สามตัว จัดประเภทโดเมนทั่วไป: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*), และ isOcrError() (SPEC-OCR-*)

การกู้คืน

1. อ่าน specCode เพื่อระบุโดเมนที่ล้มเหลว แยกกิ่งบน prefix ของมัน
2. ปฏิบัติตาม retryable: ลองใหม่เฉพาะเมื่อมันเป็น true และไม่เคยลองใหม่บนรหัส SPEC-SEC-* หรือ SPEC-IO-002 ซึ่งสื่อถึงข้อบกพร่องการกำหนดค่าหรือความเข้ากันได้
3. จับ traceId ในล็อกของคุณเพื่อเชื่อมโยงความล้มเหลวกับการวินิจฉัยฝั่ง sidecar ในรายงานข้อบกพร่อง

คลาสย่อยของ Spectrum

ชนิดต่อไปนี้เป็นซับคลาส final ของ SpectrumApiException จับ SpectrumApiException (หรือจับคู่บน specCode) แทนการจับเหล่านี้โดยตรง

SpectrumAuthenticationException

ถูกยกสำหรับรหัส SPEC-AUTH-* ที่บ่งชี้ความล้มเหลวการผูก license token หรือ deployment SpectrumResponseParser ยกมันทุกครั้งที่รหัสการตอบกลับ ขึ้นต้นด้วย SPEC-AUTH-

สาเหตุที่บันทึกไว้รวมถึง SPEC-AUTH-001 (ลายเซ็น Ed25519 ของ license ที่ไม่ถูกต้อง), SPEC-AUTH-002 (license หมดอายุและอยู่นอกช่วงผ่อนผัน), SPEC-AUTH-003 (deployment slot ไม่ตรงกัน), SPEC-AUTH-004 (JWT Bearer token ที่ไม่ถูกต้อง), SPEC-AUTH-006 (license ถูกลดทอน ช่วงผ่อนผันหมด) และ SPEC-AUTH-007 (คุณสมบัติ ไม่รวมอยู่ใน license ที่ซื้อ)

มันพกพาพร็อพเพอร์ตีเดียวกับชนิดฐาน แต่ constructor pin retryable เป็น false และตั้งค่าเริ่มต้น httpStatus เป็น 403

Recovery ข้อผิดพลาดเหล่านี้ไม่เคยลองใหม่ได้โดยไม่มีการแทรกแซงของผู้ปฏิบัติงาน ต่ออายุหรือแก้ license รีเฟรช Bearer token หรือจัดแนว deployment slot แล้วรันการเรียกใหม่

SpectrumResourceException

ถูกยกสำหรับรหัส SPEC-OOM-* เมื่อหน่วยความจำ GPU หรือ CPU หมด SpectrumResponseParser ยกมันสำหรับ prefix SPEC-OOM- ใดๆ และการตั้งค่า DegradePolicy::FailFast ยกมันแทนการ downgrade อย่างเงียบๆ ไปยัง hardware tier ที่ต่ำกว่า

constructor pin retryable เป็น true และตั้งค่าเริ่มต้น httpStatus เป็น 503

Recovery exception นี้ลองใหม่ได้ คิว job และลองใหม่หลังจาก job อื่น เสร็จและปลดทรัพยากร หรือผ่อน DegradePolicy เป็น AllowWithLog / WarnAndProceed หาก tier ที่ downgrade ยอมรับได้สำหรับ workload

SpectrumProtocolException

ถูกยกเมื่อการตอบกลับ sidecar แยกวิเคราะห์เป็น JSON แต่ไม่ตรงกับรูปทรง protocol ที่คาดหวัง มันใช้ specCode SPEC-IO-003 และ httpStatus 502 เสมอ โดย retryable ถูก pin เป็น false

นี่แตกต่างจาก SPEC-IO-001 (JSON ที่ไม่ถูกต้อง): ที่นี่ JSON มีรูปแบบดี แต่ผิดเชิงโครงสร้าง ซึ่งโดยทั่วไปบ่งชี้ proxy หรือ gateway ที่เขียน body ใหม่ เวอร์ชัน sidecar ที่ไม่เข้ากัน หรือการตอบกลับที่เสียหาย

Recovery ลองใหม่ไม่ได้ — รูปทรงการตอบกลับเป็น deterministic สำหรับ sidecar เวอร์ชันหนึ่ง ตรวจสอบเวอร์ชัน sidecar เทียบกับ minApiVersion ของ client ตรวจสอบ proxy หรือ gateway ตัวกลางใดๆ แล้ว re-deploy sidecar ที่เข้ากันได้

SpectrumNotAvailableException

SpectrumNotAvailableException สืบทอดจาก RuntimeException โดยตรงและ ไม่ใช่ ส่วนหนึ่งของลำดับชั้น SpectrumApiException มันสื่อว่า sidecar เข้าถึงไม่ได้หรือล้มเหลว health check ก่อนที่ body ข้อผิดพลาด SPEC-* ใดๆ จะ ถูกคืน

เมื่อใดที่ถูกโยน

• circuit breaker เปิด หรือความพยายามลองใหม่ทั้งหมดหมดลง (SpectrumClient)
• ข้อผิดพลาดการขนส่ง HTTP เกิดขึ้นขณะติดต่อ sidecar ClientExceptionInterface PSR-18 พื้นฐานถูกเชื่อมโยงเป็น exception ก่อนหน้า
• stream แบบ server-sent-events ถูกร้องขอขณะ sidecar รายงานตัวเอง ว่าไม่พร้อมใช้งาน (SseStreamClient)

คุณสมบัติ

ชนิดนี้ไม่พกพาข้อมูลเมตา SPEC-* ข้อความถูกประกอบเป็น "Spectrum sidecar unavailable: {reason}" พร้อม integer code แบบทางเลือกและ throwable previous ที่เชื่อมโยงกัน

การกู้คืน

จับสิ่งนี้เมื่อ Spectrum เป็นแบบเสริมและ fall back ไปยังการประมวลผลแบบ PHP-native (graceful degradation) เมื่อ Spectrum จำเป็น ให้ยืนยันว่า sidecar ทำงานและ เข้าถึงได้ แล้วรันการเรียกใหม่

ดูเพิ่มเติม

• Error reference index
• Encryption and permissions
• Knowledge base index