Jak funguje prohlížeč

Doconut vykresluje dokumenty jako stránkované obrázky poskytované prostřednictvím middleware ASP.NET Core. Porozumění životnímu cyklu — otevření, token, požadavky na stránky, uzavření — vysvětluje téměř veškeré chování, které můžete pozorovat, včetně chybových zpráv.

Tři pohyblivé části

• Viewer — veřejná služba, kterou injektujete. Otevírá dokumenty a vrací tokeny relace.
• Relace dokumentu — objekt na straně serveru, který drží načtený dokument, klíčovaný tokenem v IMemoryCache.
• Middleware Doconut — přidáno pomocí UseDoconut(); odpovídá na každý požadavek, který widget prohlížeče provádí (pages, thumbnails, search, annotations, …), vždy ověřeno tokenem.

Viewer je bezstavový — záměrně

Viewer je uzavřený, neuchovává žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable. Relace žijí nezávisle ve správci relací a jsou vyčištěny vypršením platnosti cache nebo explicitním CloseDocument(token).

Injektujte to kdekoliv potřebujete:

app.MapPost("/api/open", async (string fileName, Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync($"files/{fileName}");
    return Results.Content(token, "text/plain");
});

Co se děje uvnitř OpenDocumentAsync

1. License gate. Odmítnutá nebo prošlá licence (na černé listině, poškozená nebo sestavení mimo aktualizační okno licence) okamžitě vyhodí LicenseException, s důvodem odmítnutí jako zprávou — otevření se nikdy tiše nepropadá pro neplatnou (na rozdíl od chybějící) licenci. Licence s kalendářním vypršením (dočasná nebo předplatitelská) je výjimkou: nevyhazuje výjimku — přechází na vodoznak.
2. Session creation. Továrna prohlížeče vybere správný prohlížeč formátu podle přípony souboru a načte dokument (viz Rendering Pipeline). Relace je uložena v IMemoryCache pod čerstvým GUID tokenem s posuvnou expirací — DocOptions.TimeOut minut, výchozí 60. Každý požadavek na stránku resetuje časovač.
3. Security registration. S UnsafeMode = false (výchozí) je token svázán se session ASP.NET volajícího: do session je zapsán marker secure-{token}, takže pouze prohlížečová session, která dokument otevřela, může požadovat jeho stránky.
4. Token je vrácen. Je to jediné pověření pro vše, co následuje.

Tři přetížení se liší pouze vstupem: cesta k souboru, cesta k souboru plus konfigurace pro každý formát (PdfConfig, WordConfig, …), nebo Stream plus FileInfo, jehož přípona určuje detekci formátu.

Jak widget získává stránky

Klientský widget volá middleware Doconut s tokenem v řetězci dotazu. To, co middleware provede, závisí na požadavku:

Každá z těchto cest je nejprve ověřena:

• No token → middleware vrátí 404 (nebo banner verze, když ShowDoconutInfo = true).
• Unknown or expired token → chybový obrázek s Document session not found. Please re-open document.
• Session middleware missing (s UnsafeMode = false) → HTTP 500 s Session middleware not configured. Call UseSession() before UseDoconut().
• Token opened by a different browser session → chybový obrázek s You Are Not Authorized To View This Page.

Uzavření dokumentu

viewer.CloseDocument(token);

CloseDocument odstraňuje relaci z cache (což uvolní podkladový dokumentový engine a okamžitě uvolní jeho paměť), maže marker secure-{token} a odvolává přístupové oprávnění. Volání je volitelné — posuvná expirace provádí stejný úklid automaticky — ale u velkých dokumentů je to zdvořilý způsob, jak uvolnit paměť, jakmile uživatel skončí.

Závěry

• Jeden otevřený dokument = jedna relace = jeden token. Tokeny jsou vázány na prohlížečovou relaci, ne na globální URL.
• Token vyprší v posuvném okně; prohlížeč ponechaný nečinný po DocOptions.TimeOut potřebuje opětovné otevření.
• Viewer může být injektováno a volně sdíleno; relace nesou celý stav.