Pro phiên bản

Webview — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này ghi lại bề mặt công khai NextPDF\Pro\Webview, mô hình yêu cầu/phản hồi byte-range, và các chế độ thất bại chính xác vượt ngoài trang giới thiệu công khai.

Khả dụng & cấp phép

Năng lực này được giao trong NextPDF Pro (nextpdf/pro) và kích hoạt bằng một phong bì giấy phép hạng Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Không có cờ giấy phép riêng theo từng tính năng; mã được giao cùng phiên bản Pro. ResponseFactoryInterface / StreamFactoryInterface PSR-17 và media type của body là các tham số constructor lúc chạy, không phải cơ chế kiểm soát cấp phép.

Bề mặt API công khai

composer require nextpdf/pro

Các kiểu công khai dưới NextPDF\Pro\Webview:

LinearizedDocument — một PDF đã linearized được xác thực, chuẩn bị sẵn để giao.
ByteRangeResponder — bộ responder HTTP byte-range theo RFC 9110.
ByteRange — một byte range bao gồm (inclusive) thỏa mãn được trên một biểu diễn.
FirstPageProber — chứng minh cấu trúc “trang đầu trước khi tải về đầy đủ”.

Các kiểu ngoại lệ dưới NextPDF\Pro\Webview\Exception:

WebviewException (interface đánh dấu), UnsupportedDocumentException, RangeNotSatisfiableException.

`LinearizedDocument`

Một lớp final readonly với một constructor private; hãy khởi tạo qua named constructor.

static fromBytes(string $bytes): self — phân tích các byte qua LinearizationView::fromPdf() ở phía-đọc của Core. Ném UnsupportedDocumentException khi tài liệu không được linearized, khi /L được khai báo không khớp độ dài byte thực, hoặc khi offset kết-thúc-trang-đầu /E không phải là một offset dương bên trong tệp.
length(): int — độ dài tài liệu tính bằng byte.
firstPagePrefixLength(): int — tiền tố dẫn đầu tối thiểu chứa trang đầu hoàn chỉnh: offset /E, được kẹp về độ dài tệp.
firstPageByteRange(): ByteRange — range bao gồm [0, /E - 1] vốn giao trang đầu. Ném RangeNotSatisfiableException chỉ khi tiền tố rỗng (phòng-thủ-theo-chiều-sâu; fromBytes() đã đảm bảo 0 < /E <= length).
slice(int $firstByte, int $lastByte): string — cắt lát theo lập trình nghiêm ngặt với các offset bao gồm; ném RangeNotSatisfiableException khi ngoài biên.
etag(): string — entity-tag SHA-256 mạnh, tất định cho các byte, được ghi nhớ một lần lúc khởi tạo.

Các thuộc tính readonly công khai: bytes (các byte PDF thô) và view (LinearizationView của Core).

`ByteRangeResponder`

Một lớp final readonly được hiện thực chỉ dựa trên PSR-7 / PSR-17.

__construct(ResponseFactoryInterface $responses, StreamFactoryInterface $streams, string $contentType = 'application/pdf') — ném InvalidArgumentException khi $contentType chứa ký tự điều khiển (nó được nội suy vào các header của phản hồi và của phần multipart; CR/LF và các byte điều khiển khác bị từ chối để ngăn header injection).
respond(LinearizedDocument $document, ServerRequestInterface $request): ResponseInterface — trả lời một yêu cầu range cho một tài liệu linearized, dùng chính ETag của tài liệu.
respondToBytes(string $bytes, ServerRequestInterface $request, ?string $etag = null): ResponseInterface — trả lời một yêu cầu range cho các byte tùy ý (một biểu diễn nên hỗ trợ range mà không cần được linearized). ETag được suy ra từ các byte khi null.
firstPageResponse(LinearizedDocument $document): ResponseInterface — dựng một 206 mang theo đúng byte range của trang đầu; dạng server-push của “trang đầu trước khi tải về đầy đủ”.

`ByteRange`

Một value object final readonly cho một byte range bao gồm (inclusive) thỏa mãn được duy nhất (RFC 9110 §14.1.2).

__construct(int $firstByte, int $lastByte, int $contentLength) — thực thi tính thỏa mãn 0 <= firstByte <= lastByte <= contentLength - 1; nếu không thì ném RangeNotSatisfiableException.
length(): int — khoảng bao gồm (lastByte - firstByte + 1), luôn >= 1.
contentRange(): string — giá trị trường Content-Range theo RFC 9110 §14.4 bytes first-last/length.

Các thuộc tính readonly công khai: firstByte, lastByte, contentLength.

`FirstPageProber`

Một lớp final readonly được dựng từ một LinearizedDocument.

prefixLength(): int — số byte dẫn đầu tối thiểu cần để kết xuất trang đầu.
prefixFraction(): float — phần của toàn bộ tệp (0.0–1.0) mà tiền tố đại diện; trả về 1.0 cho một tệp độ-dài-không.
hintStreamWithinPrefix(): bool — liệu đối tượng primary hint stream có nằm hoàn toàn bên trong tiền tố trang-đầu hay không (để riêng tiền tố cho phép một bên đọc định vị các đối tượng trang-1). Hint stream phải có độ dài dương.
isFirstPageSelfContained(): bool — chứng minh cấu trúc kết hợp: một tiền tố dương vừa khít trong tệp và chứa hoàn toàn hint stream.

Mô hình yêu cầu/phản hồi byte-range

ByteRangeResponder tuân theo RFC 9110 §14. Sau khi tính độ dài và một ETag SHA-256 mạnh, nó đọc các header Range và If-Range rồi quyết định:

Điều kiện	Status	Ghi chú
Không có `Range` áp dụng được, hoặc `If-Range` không khớp `ETag` mạnh hiện tại	`200 OK`	Toàn bộ body. Chỉ dạng entity-tag mạnh của `If-Range` được tôn trọng (RFC 9110 §13.1.5).
Đơn vị range không nhận diện được hoặc `Range` sai cú pháp	`200 OK`	Header bị bỏ qua (RFC 9110 §14.2).
Một range thỏa mãn	`206 Partial Content`	Mang theo `Content-Range`.
Nhiều range thỏa mãn	`206 Partial Content`	`multipart/byteranges` với một biên được suy ra.
Các byte range hợp lệ, không cái nào thỏa mãn	`416 Range Not Satisfiable`	Mang theo `Content-Range: bytes */length` (RFC 9110 §15.3.7).

Mọi phản hồi đều quảng bá Accept-Ranges: bytes và ETag mạnh. Các phản hồi 200 và 206 cũng đặt Content-Type và Content-Length.

Việc phân tích range chỉ chấp nhận đơn vị bytes=. Nó hỗ trợ first-last tường minh, first- mở-cuối (được kẹp về cuối), và hậu tố -N (N byte cuối; một hậu tố lớn ít nhất bằng biểu diễn sẽ chọn toàn bộ nó). Một - trống trơn (hoặc bất kỳ spec dị dạng nào khác) làm cho toàn bộ header Range sai cú pháp, nên header bị bỏ qua và biểu diễn 200 OK đầy đủ được trả về. Một hậu tố -0, hoặc bất kỳ spec nào có offset đầu nằm tại hoặc vượt quá cuối, là một spec không thỏa mãn được và bị loại bỏ; nếu không có spec nào trong header thỏa mãn được thì phản hồi là 416 Range Not Satisfiable. Các offset thập phân lớn được so sánh mà không dựa vào sự bão hòa do tràn-số-nguyên, nên một giá trị Range 30 chữ số được xử lý độc lập với nền tảng. Các range thỏa mãn chồng lấn được gộp trước khi bất kỳ body nào được dựng; các range thực sự riêng biệt (không chồng lấn) được giữ làm các phần multipart riêng.

Các chế độ thất bại & mô hình ngoại lệ

WebviewException là một interface đánh dấu mở rộng Throwable; hãy catch nó để xử lý toàn bộ subsystem một cách đồng nhất. Cả hai ngoại lệ cụ thể đều hiện thực nó.

UnsupportedDocumentException (mở rộng InvalidArgumentException) — được làm phát sinh bởi LinearizedDocument::fromBytes() khi các byte không phải là một tài liệu linearized dùng được. Các named constructor: notLinearized() (không có từ điển tham số /Linearized), lengthMismatch($declaredLength, $actualLength) (/L được khai báo không khớp độ dài thực — bị cắt cụt, bị thêm-vào qua một incremental update vượt quá /L, hoặc không phù hợp chuẩn), và malformedFirstPageOffset($firstPageEndOffset, $length) (offset /E không phải là một offset dương bên trong tệp).
RangeNotSatisfiableException (mở rộng OutOfRangeException) — lỗi cắt-lát-theo-lập-trình, được làm phát sinh bởi ByteRange::__construct() và LinearizedDocument::slice() / firstPageByteRange() khi một range bao gồm rơi ra ngoài tài liệu. Named constructor: outOfBounds($firstByte, $lastByte, $length).

Bộ responder HTTP không ném RangeNotSatisfiableException cho các header Range của client — một range HTTP không thỏa mãn được là một phản hồi 416 (RFC 9110 §15.3.7), không phải một ngoại lệ. Ngoại lệ đó được dành riêng cho việc cắt lát theo lập trình trực tiếp, nơi một yêu cầu ngoài-biên là một lỗi của bên gọi. ByteRangeResponder::__construct() ném một InvalidArgumentException thuần (không phải một WebviewException) khi contentType được cấu hình chứa ký tự điều khiển.

Tăng cứng chống từ chối dịch vụ

Responder giới hạn số lượng range đã gộp riêng biệt được tôn trọng cho mỗi yêu cầu (lớp khuếch-đại-range-multipart, Apache HTTPD CVE-2011-3192). Khi một yêu cầu xin nhiều range đã gộp hơn giới hạn, hoặc nhiều byte tổng hơn toàn bộ biểu diễn, Range bị bỏ qua và một 200 đầy đủ được trả về. Biên multipart được suy ra một cách tất định và được suy-ra-lại cho đến khi nó được đảm bảo không xuất hiện bên trong body, giữ đầu ra có thể tái lập trong khi loại trừ va chạm biên.

Tính phù hợp

Hành vi byte-range tuân theo RFC 9110 (HTTP Semantics): §14 (các yêu cầu range), §13.1.5 (If-Range), §14.4 (Content-Range), và §15.3.7 (416). Bố cục tài-liệu-linearized là mô hình Fast Web View của ISO 32000-2 Annex F. Module không khẳng định thêm định danh điều khoản bên ngoài nào ngoài hành vi đã được các test của nó kiểm chứng.

Trường hợp ngoại lệ & hành vi ở chế độ FIPS

respondToBytes() phục vụ các range trên các byte tùy ý khi không cần ngữ nghĩa trang-đầu.
Một bộ xác thực If-Range dạng HTTP-date được coi là không-khớp → 200 đầy đủ (client chỉ đơn giản fetch lại).
ETag là một hash SHA-256 được dùng thuần túy như một bộ xác thực cache mạnh; module này không thực hiện việc ký hay thao tác mã hóa nào khác và không định nghĩa hành vi đặc thù FIPS nào.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, tên tệp runbook, và các tiền tố ticket đều nằm ngoài phạm vi.