Stream — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Pro\Stream alt sisteminin genel sözleşmelerini, sınıflarını, yöntemlerini ve başarısızlık modlarını, genel bakış sayfasının ötesinde belgeler. Aşağıdaki her tür, belgelenmiş Pro genel yüzeyinin bir parçasıdır.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve Pro katmanı bir lisans zarfı ile etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Özellik başına bir lisans bayrağı geçerli değildir; kod, Pro sürümüyle gelir. Çalışan sayısı, grup boyutu, yeniden deneme bütçesi ve depo arka ucu, birer çalışma zamanı parametresidir.

Mimari: dondurulmuş motor bağlantı yüzeyi

NextPDF\Pro\Stream\Engine\RenderEngineInterface, üretim hızı motoru ile belge-işi akış işlemcisi arasındaki sözleşmedir. Motor onu uygular (eşzamanlılığı, çalışan-havuzu yaşam döngüsünü, geri basıncı, sınırlı belleği sahiplenerek); akış işlemcisi onu tüketir (anahtarlı durumu, yineleme kaldırmayı, yeniden denemeyi, denetim noktasını ve tam-bir-kez işlemeyi sahiplenerek). Motor, baytları artı sha-256’yı döndürür, asla işlenmiş bir konumu değil — bu yan etki özgürlüğü, işlemcinin tam olarak bir kez hazırlamasına, işlemesine ve denetim noktasına almasına izin veren şeydir.

public function renderBatch(array $manifests, array $variablesByJobId = []): array; // list<EngineRenderResult>, input order
public function maxBatchSize(): int;   // int<1, max> backpressure hint
public function isAvailable(): bool;

$manifests, en fazla maxBatchSize() boyutunda bir list<RenderManifest>’tir; $variablesByJobId, iş kimliğini array<string, scalar> şablon değişkenlerine eşler. Bildirim başına bir başarısızlık, öğe başına bir Failed/Timeout sonucudur ve grubu asla durdurmaz.

Motorlar

NextPDF\Pro\Stream\Engine\InProcessRenderEngine

Senkron, tek süreçli taban çizgisi. Her bildirimi, Core SingleDocumentRenderer aracılığıyla oluşturmadan önce RenderManifestValidator üzerinden başarısızlığa kapanır biçimde doğrular (16 MiB satır içi yük üst sınırı, uygunluk/imza izin listeleri, sha-256 içerik karması biçimi, BCP-47 yerel ayar söz dizimi). Engelleyici bir doğrulama hatası, EngineRenderResult::failed(jobId, 'SPEC-MANIFEST-INVALID', ...)’a kısa devre yapar; bir oluşturma istisnası ise 'SPEC-RENDER-EXCEPTION' hâline gelir. Yapıcı: __construct(SingleDocumentRenderer $renderer, int $maxBatchSize = 64, ?RenderManifestValidator $validator = null) — maxBatchSize < 1 bir InvalidArgumentException oluşturur. isAvailable() her zaman true’dur.

NextPDF\Pro\Stream\Engine\ConcurrentRenderEngine

final readonly, __construct(RenderUnitExecutorInterface $executor). Her bildirimi dizinli bir RenderUnit içine sarar, onları yürütücü üzerinden çalıştırır ve çıktının sıralı bir oluşturmayla bayt-bayt aynı olması için tamamlanmaları dizine göre yeniden sıralar. [0, count) aralığı dışındaki bir tamamlanma dizini, RenderEngineException::unknownUnit() oluşturur; yinelenen bir dizin duplicateResult() oluşturur; eksik bir dizin missingResult() oluşturur. maxBatchSize() ve isAvailable(), yürütücüye devreder.

Yürütücüler

NextPDF\Pro\Stream\Engine\RenderUnitExecutorInterface

public function execute(array $units): iterable; // iterable<CompletedRenderUnit>, any order
public function maxBatchSize(): int;
public function isAvailable(): bool;

Uygulamalar, tamamlanmaları herhangi bir sırada üretebilir; ConcurrentRenderEngine, sırayı dizine göre geri yükler.

NextPDF\Pro\Stream\Engine\InlineRenderUnitExecutor

final readonly, __construct(RenderEngineInterface $inner). Her birimi iç motor aracılığıyla sırayla oluşturur — bir paralel yürütücünün bayt-bayt eşleştirmesi gereken deterministik doğruluk referansı. Zaman, süreç, iş parçacığı veya rastgelelik yok.

NextPDF\Pro\Stream\Engine\ProcessPoolRenderUnitExecutor

final readonly. Bir grubu, paralel olarak oluşturan en fazla maxWorkers php çalışan alt sürecine (her biri bir parça) dağıtır; çıktı, satır içi taban çizgisiyle bayt-bayt aynıdır. Yapıcı:

__construct(
    int $maxWorkers = 4,
    int $maxBatchSize = 64,
    ?string $phpBinary = null,
    ?string $workerScript = null,
    ?string $autoload = null,
    ?int $timeoutSeconds = 300, // null disables the wall-clock watchdog
)

Sağlamlık sözleşmesi:

• Kilitlenmesiz, Windows için güvenli. Birim yükleri ve sonuçları, borular üzerinden değil, geçici dosyalar üzerinden seyahat eder; ebeveyn proc_get_status()’u yoklar ve bir boruyu yalnızca bir çalışan çıktıktan sonra EOF’a kadar boşaltır; böylece bir çalışan ebeveyni sıkıştıramaz.
• Sınırlı bekleme. timeoutSeconds, tüm paralel oluşturmayı sınırlar; süre dolduğunda hâlâ çalışan her çalışan sonlandırılır ve bir RenderEngineException oluşturulur.
• Kaynak hijyeni. Bir finally, boruları kapatır, sağ kalan çalışanlar üzerinde sınırlı bir sonlandır-ve-topla girişimi yapar (kibar sonlandırma → zorla öldürme → toplama; sınırlı erteleme süresi içinde durduğu gözlemlenmeyen bir alt süreç, süresiz bir engellemeyi göze almak yerine terk edilir) ve tüm yollarda her geçici dosyanın bağlantısını kaldırır.
• Güvenilir ilişkilendirme. Her çalışan, tam olarak kendisine atanan dizin kümesini döndürmelidir (eksik, yinelenen veya yabancı dizin yok); oluşturulan her sonucun baytları yeniden karma değerine sokulur ve çalışanın bildirdiği sha-256 ile eşleştirilir ve rendered/failed dışındaki herhangi bir durum sert biçimde başarısız olur. Bildirim başına bir oluşturma başarısızlığı, birim başına bir Failed sonucudur; yalnızca altyapısal bir arıza (sıfır olmayan çıkış, okunamaz/bozuk çıktı, zaman aşımı) yürütücüyü sert biçimde başarısız kılar.

isAvailable(), hem otomatik yükleme dosyasının hem de çalışan betiğinin var olmasını gerektirir. Pozitif olmayan bir sınır veya negatif bir zaman aşımı, bir InvalidArgumentException oluşturur.

Oluşturma birimleri ve sonuçları

NextPDF\Pro\Stream\Engine\RenderUnit

final readonly — int<0, max> $index, RenderManifest $manifest, array<string, scalar> $variables. İlişkilendirme, iş kimliğine göre değil, index’e göre yapılır (iş kimliklerinin bir grup içinde benzersiz olduğu garanti edilmez).

NextPDF\Pro\Stream\Engine\CompletedRenderUnit

final readonly — int $index (güvenilmez, motor tarafından doğrulanır), EngineRenderResult $result.

NextPDF\Pro\Stream\Engine\EngineRenderResult

final readonly. Alanlar: jobId, EngineRenderStatus $status, ?string $bytes, ?string $sha256, int $pageCount, ?string $errorCode, ?string $errorMessage, array<non-empty-string, float> $timings. Fabrikalar: rendered(jobId, bytes, sha256, pageCount, timings = []), failed(jobId, errorCode, errorMessage), timedOut(jobId, errorMessage) (kod SPEC-ENGINE-TIMEOUT). isRendered(), durumu bildirir. Oluşturulmuş bir sonuç, baytları ve bir özeti taşır, asla işlenmiş bir konumu değil.

NextPDF\Pro\Stream\Engine\EngineRenderStatus

Dize destekli enum: Rendered, Failed, Timeout. isRetryable(), yalnızca Timeout için true’dur; böylece çağıran, bir zaman aşımını hatayı yeniden incelemeden uçucu olarak sınıflandırır.

İşleme

NextPDF\Pro\Stream\Commit\OutputCommitterInterface

public function commit(
    string $jobId,
    OutputObjectKey $target,
    string $bytes,
    string $sha256,
    bool $overwrite = false,
): CommitReceipt;

Tam-bir-kez yayımlama: atomik, idempotent (bayt-bayt aynı yeniden işleme hiçbir yazma gerçekleştirmez ve idempotentReuse = true ile bir CommitReceipt döndürür — orijinali değil, yeni bir makbuz; committedAt’i geçerli saattir), sessiz ezme yok ve bütünlük denetiminden geçirilmiş (işleyici, özeti yeniden hesaplar). Başarısızlık modları: CommitIntegrityException (bildirilen sha-256 baytlarla eşleşmez), OutputCommitConflictException (dolu bir anahtarda overwrite = false ile ayrışan baytlar), UnsupportedTargetException (desteklenmeyen hedef şeması).

NextPDF\Pro\Stream\Commit\LocalFilesystemCommitter

final readonly, OutputCommitterInterface, DurableCapability uygular. __construct(string $rootDirectory, ?AtomicFileWriter $writer = null, ?ClockInterface $clock = null). Yalnızca file şemasına hizmet eder; her hedefi yapılandırılmış tek bir kök altında çözer ve atomik bir yazıcı (O_EXCL geçici → fsync → aynı birimde yeniden adlandırma) aracılığıyla yazar. Tüm kritik bölüm (ebeveyn-dizin oluşturma dâhil), çıktı anahtar uzayının dışında tutulan kök başına bir kilit dosyası üzerinde özel bir flock altında çalışır ve kilit açılamaz veya alınamazsa işleme başarısızlığa kapanır. Sembolik bağlantılı nihai bileşenleri ve iki nokta içeren herhangi bir anahtarı (NTFS alternatif veri akışı vektörü) reddeder. Aynı anahtara çapraz ana makine eşzamanlı tam-bir-kez, dayanıklı Enterprise işleyicisini gerektirir. Sistem geçici dizinini olan veya içeren bir kök, bir InvalidArgumentException oluşturur.

NextPDF\Pro\Stream\Commit\CommitReceipt

final readonly — jobId, OutputObjectKey $target, sha256, int<0, max> $bytesWritten, bool $idempotentReuse, DateTimeImmutable $committedAt. toArray() / fromArray() tam olarak gidiş-dönüş yapılabilir (hedef, kayıplı bir URI değil, yapılandırılmıştır); fromArray() katıdır ve eksik veya bozuk alanlarda bir InvalidArgumentException oluşturur.

Denetim noktası

NextPDF\Pro\Stream\Checkpoint\CheckpointStoreInterface

load(string $runId): ?RunCheckpoint ve save(RunCheckpoint $checkpoint): void (dayanıklı ve atomik — bir okuyucu, yarı yazılmış bir denetim noktasını asla görmez).

NextPDF\Pro\Stream\Checkpoint\RunCheckpoint

final readonly — runId, int<0, max> $committedOffset, array $keyedState, DateTimeImmutable $updatedAt; SCHEMA_VERSION = '1.0'. Fabrikalar start(runId, at) ve advancedTo(committedOffset, keyedState, at). toArray()/toJson()/fromArray()/fromJson() onu serileştirir; fromArray(), boş olmayan bir çalıştırma kimliği ve geçerli bir updated_at gerektirir, uyumsuz (1.x olmayan) bir schema_version’ı reddeder ve her derinlikte JSON serileştirilemez değerleri düşürerek anahtarlı durumu normalleştirir; böylece kurtarılan durum her zaman yeniden serileştirilebilir. Kurtarmada işlemci, committedOffset’in ötesine hızlı ileri sarar ve anahtarlı durumu geri yükler; son engelden sonra değiştirilen durum, bir hata değil, ileriye doğru yeniden hesaplanır, çünkü dayanıklı tam-bir-kez, işleyicinin özet yineleme kaldırmasından gelir.

NextPDF\Pro\Stream\Checkpoint\FilesystemCheckpointStore

final readonly, CheckpointStoreInterface, DurableCapability uygular. Çalıştırma başına bir JSON dosyası, atomik olarak yazılır. Çalıştırma kimlikleri [A-Za-z0-9._-]+ ile eşleşmeli ve hiçbir .. içermemelidir; var olmayan bir dizin, bir InvalidArgumentException oluşturur.

Idempotency yineleme kaldırma

NextPDF\Pro\Stream\Dedup\IdempotencyStoreInterface

isCommitted(IdempotencyKey $key): bool, markCommitted(IdempotencyKey $key, CommitReceipt $receipt): void, receiptFor(IdempotencyKey $key): ?CommitReceipt. Bir yeniden yürütmeyi oluşturmadan önce kısa devre yapan hızlı yol; işleyicinin özet karşılaştırması dayanıklı güvence olarak kalır; böylece kaybedilen bir kayıt en kötü durumda, işleyicinin yineleme kaldırdığı bir yeniden oluşturmayı boşa harcar.

• InMemoryIdempotencyStore — tek çalıştırma / test kapsamı (çökmede kaybolur).
• FilesystemIdempotencyStore — DurableCapability; işlenmiş anahtar başına bir atomik JSON dosyası (serileştirilmiş makbuz), anahtar değerinin bir karması ile adlandırılmış. İşaretler idempotenttir; eşzamanlı bir yeniden işaretleme, tek bir dosyada zararsızca yarışır. Var olmayan bir dizin, bir InvalidArgumentException oluşturur.

Yeniden deneme ve ölü-mektuplar

NextPDF\Pro\Stream\Retry\RetryPolicy

final readonly — positive-int $maxAttempts, positive-int $baseDelayMs, positive-int $maxDelayMs. maxAttempts >= 1 ve 1 <= baseDelayMs <= maxDelayMs <= 7 days değişmezleriyle __construct(int $maxAttempts = 3, int $baseDelayMs = 100, int $maxDelayMs = 30000) (aksi hâlde InvalidArgumentException). Fabrikalar default() ve none() (tek deneme). shouldRetry(int $attempt): bool. delayMsForAttempt(int $attempt): int<0, max>, maxDelayMs’de sınırlanmış deterministik üstel geri çekilme baseDelayMs * 2^(attempt-1)’dir (yerleşik titreşim yok; çağrı yerinde uygulayın).

NextPDF\Pro\Stream\Retry\DeadLetterStoreInterface

add(DeadLetterRecord $record): void, all(): list<DeadLetterRecord>, count(): int<0, max>.

NextPDF\Pro\Stream\Retry\DeadLetterRecord

final readonly — jobId, idempotencyKeyValue, positive-int $attempts, lastErrorCode, lastErrorMessage, DateTimeImmutable $failedAt, isteğe bağlı ?string $runId, isteğe bağlı int<1, max> $sourceOffset. dedupKey(), her ikisi de bilindiğinde runId:sourceOffset’tir, aksi hâlde idempotency anahtar değeridir. fromArray(), failed_at’i kesin olarak ATOM olarak ayrıştırır (göreceli veya ATOM olmayan ifadeleri reddederek); böylece serileştirme/serileştirmeyi geri alma simetrik kalır.

• InMemoryDeadLetterStore — tek çalıştırma / test kapsamı.
• FilesystemDeadLetterStore — DurableCapability; kayıt başına bir atomik JSON dosyası, yineleme kaldırma anahtarının bir SHA-256 karması ile adlandırılmış (….dlq.json); böylece aynı öğeyi sürdürmede yeniden ekleme idempotenttir. all(), kayıtları deterministik (sıralı) düzende okur ve bozuk bir kaydı bir istisna oluşturarak yüzeye çıkarır; count(), bir geçerlilik denetimi değil, ucuz bir dosya sayımıdır.

Anahtarlı durum

NextPDF\Pro\Stream\State\KeyedStateStoreInterface

has, get, put, remove, clear, ayrıca denetim noktası sınırı için snapshot(): array ve restore(array $snapshot): void. Değerler JSON serileştirilebilir olmalıdır. Varsayılan oluştur-ve-işle iş yükü için hiçbir anahtarlı durum kullanılmaz; toplama/pencereleme uzantıları için vardır. InMemoryKeyedStateStore, tek çalıştırma uygulamasıdır; kurtarmada onu kaybetmek varsayılan iş yükü için anlamsal bir işlemsizliktir, çünkü tam-bir-kez, işleyicinin özet yineleme kaldırmasından gelir.

NextPDF\Pro\Stream\State\KeySelector

final readonly, __construct(string $tenantField = 'tenant_id', string $documentField = 'document_id'). keyFor(RenderManifest $manifest): non-empty-string, bölüm anahtarını bildirim meta verisinden rawurlencode(tenant):rawurlencode(document) olarak türetir (kodlama, ("a:b","c")’nin ("a","b:c") ile çakışmasını durdurur), her iki alan da yoksa iş kimliğine geri döner — böylece her bildirim, kararlı, boş olmayan bir anahtara çözülür.

Dayanıklılık işaretçisi ve istisnalar

NextPDF\Pro\Stream\DurableCapability, durumu bir süreç yeniden başlatmasından sağ çıkan herhangi bir depo/işleyici için bir işaretçi arabirimidir. Çökmeye dayanıklı bir çalıştırma, her iş birlikçinin onu uygulamasını gerektirir; böylece bellek-içi bir deponun koruyamayacağı tam-bir-kez’i vaat etmek yerine hızlıca başarısız olur.

Tüm alt sistem istisnaları, NextPDF\Pro\Stream\Exception\StreamException’ı (Throwable’ı genişletir) uygular; böylece bir çağıran tek tip olarak catch (StreamException) yapabilir:

• RenderEngineException (RuntimeException) — yürütücü grup sözleşmesini ihlal etti (bilinmeyen, yinelenen veya eksik birim; çalışan arızası; zaman aşımı).
• CommitIntegrityException (RuntimeException) — bildirilen sha-256, yükle eşleşmez; spec kodu SPEC-COMMIT-422.
• OutputCommitConflictException (RuntimeException) — üzerine yazma devre dışıyken dolu bir anahtarda ayrışan baytlar; spec kodu SPEC-COMMIT-409 (specCode() aracılığıyla açığa çıkarılır).
• UnsupportedTargetException (InvalidArgumentException) — bir işleyicinin hizmet edemeyeceği hedef şeması.

Uygunluk

Motor, bildirimleri Core bildirim modeline karşı doğrular ve deterministik baytlar artı sha-256 özetleri üretir; işleyici, atomik, bütünlük denetiminden geçirilmiş, tam-bir-kez yazmaları zorunlu kılar. Modül, sha-256 içerik özetlerinin ötesinde hiçbir kriptografik işlem gerçekleştirmez ve hiçbir FIPS’e özgü davranış tanımlamaz.

Uç durumlar ve dikkat edilecekler

• renderBatch(), bildirim başına bir başarısızlıkta asla durmaz; her EngineRenderResult’ı inceleyin.
• ProcessPoolRenderUnitExecutor, kesin olarak dizine göre ilişkilendirir ve çalışan baytlarını yeniden karma değerine sokar; bozuk bir çalışan, çıktıyı bozmak yerine sert biçimde başarısız olur.
• LocalFilesystemCommitter, tek ana makinelidir; çapraz ana makine tam-bir-kez, dayanıklı Enterprise işleyicisini gerektirir.
• Çökmeye dayanıklı çalıştırmalar, bellek-içi türevleri değil, baştan sona DurableCapability (dosya sistemi) depolarını kullanmalıdır.

Yayımlama sınırı

Bu sayfa, yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dâhilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalışma kitabı dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Stream
• Writer — Deep Reference
• Output Pipeline — Deep Reference