Webview

Sekilas pandang

Webview mengirimkan PDF terlinearisasi (Fast Web View) melalui HTTP sehingga klien dapat mulai me-render halaman 1 dari sebuah prefiks awal yang kecil sementara sisa berkasnya masih dalam pengiriman. Ia membungkus byte mentah sebagai sebuah LinearizedDocument, menjawab permintaan Range dengan respons partial-content RFC 9110 melalui PSR-7 ByteRangeResponder, dan dapat membuktikan (melalui FirstPageProber) bahwa halaman pertama bersifat mandiri di dalam prefiks.

Ketersediaan & lisensi

Kapabilitas ini dikirim dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur yang terpisah. Responder dikabel ke factory PSR-17 milik Anda sendiri saat runtime — sebuah ResponseFactoryInterface dan sebuah StreamFactoryInterface — dan media type baku-nya adalah application/pdf sebagai argumen konstruktor, bukan sakelar lisensi.

Pemasangan

composer require nextpdf/pro

Kode berada di bawah namespace NextPDF\Pro\Webview.

Tinjauan konseptual

PDF terlinearisasi ditata sedemikian rupa sehingga halaman pertama dokumen — dictionary parameter linearisasi, primary hint stream, dan objek halaman 1 — berada di seksi awal yang berakhir pada offset /E. Webview mengubah tata letak itu menjadi pengiriman progresif.

LinearizedDocument::fromBytes() mem-parsing byte melalui LinearizationView sisi-baca milik Core (Pro tidak pernah mengimplementasikan ulang parsing linearisasi) dan menolak apa pun yang bukan dokumen terlinearisasi yang dapat digunakan: tidak terlinearisasi sama sekali, panjang /L yang dideklarasikan yang tidak cocok dengan panjang byte sebenarnya, atau offset akhir-halaman-pertama /E yang bukan offset positif di dalam berkas. Konstruksi karenanya bersifat total — begitu Anda memegang sebuah LinearizedDocument, setiap offset yang diekspos-nya dapat dipercaya.

ByteRangeResponder lalu menjawab sebuah permintaan HTTP. Ia diimplementasikan hanya terhadap PSR-7 / PSR-17, tanpa keterikatan framework. Ia selalu mengiklankan Accept-Ranges: bytes dan ETag SHA-256 yang kuat dan deterministik, mem-parsing header Range dari klien sesuai RFC 9110 §14, dan mengembalikan salah satu dari 200 OK penuh, 206 Partial Content satu range, respons 206 multipart/byteranges untuk beberapa range, atau 416 Range Not Satisfiable.

FirstPageProber adalah sisi pembuktian struktural: ia mengukur prefiks halaman-pertama, fraksi keseluruhan berkas yang diwakili prefiks tersebut, dan apakah primary hint stream sepenuhnya berada di dalamnya — properti yang memungkinkan pembaca menemukan objek halaman-1 dari prefiks saja.

Mengapa ia bekerja seperti ini

Webview tidak pernah mem-parsing ulang linearisasi sendiri. Ia meminjam LinearizationView sisi-baca milik Core, sehingga lapisan pengiriman mewarisi satu parser yang telah diaudit alih-alih salinan kedua yang menyimpang. Konstruksi sengaja dibuat total. LinearizedDocument::fromBytes() menolak tata letak yang cacat di awal, sehingga setiap offset yang dipercaya oleh respons Range telah divalidasi terlebih dahulu. Responder hanya berbicara PSR-7 dan PSR-17, sehingga kode yang sama menyajikan PDF terlinearisasi dari HTTP stack mana pun. Disiplin itulah yang membuat pengiriman range progresif aman untuk dipaparkan ke klien yang tidak tepercaya dalam volume besar.

Latar belakang desain: High-volume document generation.

Cara penyajian byte-range progresif bekerja

1. Bangun sebuah LinearizedDocument dari byte PDF hasil render. Input tidak valid memunculkan UnsupportedDocumentException di awal.
2. Serahkan dokumen dan PSR-7 ServerRequestInterface yang masuk ke ByteRangeResponder::respond(). Responder membaca Range (dan prakondisi If-Range opsional), dan menghasilkan PSR-7 ResponseInterface yang benar.
3. Klien meminta prefiks awal terlebih dahulu (atau Anda mendorongnya dengan firstPageResponse()), me-render halaman 1, lalu meminta range sisanya saat pengguna menggulir.

Model byte-range menggunakan offset inklusif sesuai RFC 9110 §14.1.2: sebuah ByteRange adalah firstByte–lastByte atas representasi contentLength, dan field Content-Range-nya adalah bytes first-last/length.

Kontrak perilaku

• LinearizedDocument::fromBytes() bersifat total: dokumen yang tidak terlinearisasi, ketidakcocokan /L, atau offset /E yang non-positif / di luar berkas masing-masing memunculkan UnsupportedDocumentException alih-alih menghasilkan dokumen yang tidak aman.
• ETag adalah entity-tag SHA-256 kuat atas byte yang persis, di-memoise sekali saat konstruksi. Input render yang identik menghasilkan byte yang identik dan karenanya ETag yang identik, sehingga cache dan If-Range berperilaku terprediksi.
• Permintaan tanpa Range yang berlaku mengembalikan 200 OK dengan body penuh. Sebuah If-Range yang tidak cocok dengan ETag kuat saat ini menyebabkan Range diabaikan dan sebuah 200 penuh dikembalikan (RFC 9110 §13.1.5). Hanya bentuk entity-tag kuat dari If-Range yang dihormati; If-Range berformat HTTP-date diperlakukan sebagai non-match.
• Unit range yang tak dikenali atau Range yang cacat secara sintaks diabaikan dan sebuah 200 penuh dikembalikan (RFC 9110 §14.2).
• Satu range yang dapat dipenuhi mengembalikan 206 Partial Content dengan Content-Range; beberapa range yang dapat dipenuhi mengembalikan 206 multipart/byteranges. Byte range yang valid tanpa satu pun yang dapat dipenuhi mengembalikan 416 dengan Content-Range: bytes */length (RFC 9110 §15.3.7).
• firstPageResponse() memancarkan sebuah 206 yang membawa persis byte range halaman pertama [0, /E - 1] — bentuk server-push dari “halaman pertama sebelum pengunduhan penuh”.

Contoh kode — Mulai cepat

Berikut ini mencerminkan API publik yang terdokumentasi. Repositori tidak mengirimkan contoh yang dapat dijalankan untuk modul ini.

use NextPDF\Pro\Webview\LinearizedDocument;
use NextPDF\Pro\Webview\ByteRangeResponder;

$document  = LinearizedDocument::fromBytes($pdfBytes);
$responder = new ByteRangeResponder($responseFactory, $streamFactory);

$response = $responder->respond($document, $request);

Contoh kode — Push halaman-pertama dan probing

use NextPDF\Pro\Webview\LinearizedDocument;
use NextPDF\Pro\Webview\ByteRangeResponder;
use NextPDF\Pro\Webview\FirstPageProber;
use NextPDF\Pro\Webview\Exception\UnsupportedDocumentException;

try {
    $document = LinearizedDocument::fromBytes($pdfBytes);
} catch (UnsupportedDocumentException $e) {
    // Not a usable linearized document — fall back to plain full delivery.
    // ...
    return;
}

$prober = new FirstPageProber($document);
if ($prober->isFirstPageSelfContained()) {
    // Push exactly the first page's bytes for an instant render.
    $response = (new ByteRangeResponder($responseFactory, $streamFactory))
        ->firstPageResponse($document);
}

Kasus tepi & jebakan

• Webview membutuhkan PDF yang benar-benar terlinearisasi. Jika dokumen hasil render tidak terlinearisasi, aktifkan linearisasi saat render, atau sajikan dengan pengiriman penuh biasa — respondToBytes() masih dapat menyajikan range atas byte arbitrer (non-terlinearisasi) ketika Anda hanya membutuhkan dukungan range, bukan semantik halaman-pertama.
• Incremental update penting: dokumen yang telah ditambahi melampaui /L yang dideklarasikan ditolak sebagai ketidakcocokan panjang, karena offset byte-range tidak lagi dapat dipercaya.
• Responder membatasi jumlah range berbeda yang dihormatinya per permintaan. Permintaan yang meminta lebih banyak range gabungan daripada batas, atau lebih banyak total byte daripada keseluruhan representasi, akan diabaikan Range-nya dan disajikan 200 penuh.

Kinerja

Prefiks halaman-pertama adalah offset akhir-halaman-pertama /E yang dijepit ke panjang berkas, sehingga FirstPageProber::prefixFraction() melaporkan seberapa kecil pengambilan awal relatif terhadap keseluruhan berkas — untuk dokumen banyak-halaman inilah inti dari Fast Web View. Pembangunan respons memotong string byte di memori; biayanya proporsional terhadap byte yang dipilih. ETag dihitung sekali per dokumen. Ukur dengan dokumen yang representatif.

Catatan keamanan

Perlakukan input sebagai tidak tepercaya. LinearizedDocument::fromBytes() memvalidasi invarian linearisasi sebelum offset apa pun digunakan. Responder menolak contentType yang mengandung karakter kontrol untuk mencegah header injection, menurunkan boundary multipart yang dijamin tidak muncul di dalam body, serta menggabungkan range yang tumpang-tindih dan membatasi jumlah serta total ukurannya untuk bertahan terhadap kelas denial-of-service range-amplification multipart (Apache HTTPD CVE-2011-3192). Modul ini tidak mencatat isi dokumen.

Kesesuaian

Pengiriman byte-range mengikuti RFC 9110 (HTTP Semantics) — §14 untuk permintaan range, §13.1.5 untuk If-Range, dan §15.3.7 untuk 416. Model dokumen-terlinearisasi adalah tata letak Fast Web View yang dijelaskan oleh ISO 32000-2 Annex F. Modul tidak menyatakan pengenal klausa eksternal lebih lanjut di luar perilaku yang diverifikasi oleh pengujiannya.

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Webview. Enterprise menambahkan fitur kepatuhan dan pengarsipan tingkat lebih tinggi yang didokumentasikan secara terpisah; fitur tersebut tidak diperlukan untuk menyajikan PDF terlinearisasi melalui byte range.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Webview — Deep Reference
• Writer
• Output Pipeline
• Optimizer