Jak funguje Viewer

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é pozorujete, 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, identifikovaný tokenem v IMemoryCache.
• Middleware Doconut — přidáno pomocí UseDoconut(); odpovídá na každý požadavek, který widget prohlížeče vytvoří (pages, thumbnails, search, annotations, …), vždy ověřeno tokenem.

Viewer je bezstavový — záměrně

Viewer je uzavřený (sealed), 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 voláním CloseDocument(token).

Injektujte jej kdekoliv jej 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. Licenční brána. Odmítnutá nebo verze vypršené 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. Výjimkou je licence s kalendářním vypršením dočasná nebo předplatitelská: nevyhodí výjimku — degraduje na vodoznak.
2. Vytvoření relace. 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 novým GUID tokenem s klouzavým vypršením — DocOptions.TimeOut minut, výchozí 60. Každý požadavek na stránku resetuje časovač.
3. Registrace zabezpečení. Při UnsafeMode = false (výchozí) je token svázán s ASP.NET relací volajícího: do relace se zapíše marker secure-{token}, takže pouze relace prohlížeče, 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.

Tyto tři přetížení se liší pouze vstupem: cesta k souboru, cesta k souboru plus konfigurace pro 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 nejprve provádí validaci:

• Žádný token → middleware vrátí 404 (nebo banner verze, když je ShowDoconutInfo = true).
• Neznámý nebo vypršený token → chybový obrázek s textem Document session not found. Please re-open document.
• Chybějící middleware relace (při UnsafeMode = false) → HTTP 500 s textem Session middleware not configured. Call UseSession() before UseDoconut().
• Token otevřený jinou relací prohlížeče → chybový obrázek s textem You Are Not Authorized To View This Page.

Uzavření dokumentu

viewer.CloseDocument(token);

CloseDocument odstraní relaci z cache (což uvolní podkladový dokumentový engine a okamžitě uvolní jeho paměť), smaže marker secure-{token} a odvolá přístupové oprávnění. Volání je volitelné — klouzavé vypršení provede 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 relaci prohlížeče, ne na globální URL.
• Token vyprší po klouzavém časovém okně; viewer, který zůstane nečinný déle než DocOptions.TimeOut, potřebuje opětovné otevření.
• Viewer může být injektován a volně sdílen; relace nesou veškerý stav.