Viewer je bezstavový — podle návrhu

Viewer ne uchovává žádná data dokumentu specifická pro požadavek. Je to uzavřená třída, nikdy neimplementuje IDisposable a každý dokument, který otevřete, žije v samostatné relaci, kterou spravuje cache frameworku. Díky tomu můžete injektovat jedinou instanci Viewer kdekoliv ve své aplikaci ASP.NET Core a bezpečně ji volat z mnoha souběžných požadavků.

---

Důsledky bezstavové služby

• Žádné skryté zdroje – služba sama nikdy nealokuje velké buffery, které by vyžadovaly explicitní úklid.
• Bezpečné pro vlákna ve výchozím nastavení – protože není uloženo žádné stavové informace specifické pro požadavek, může být stejná instance Viewer použita více vlákny bez zamykání.
• Škálovatelné nasazení – horizontální škálování funguje ihned; nepotřebujete sticky session ani afinitu serveru, jen token relace, který drží klient.

Veškeré informace specifické pro dokument (stránky, anotace, vyhledávací index) jsou uchovávány v relaci vytvořené pomocí OpenDocumentAsync. Relace je uložena v IMemoryCache (nebo v libovolném IDistributedCache, který nakonfigurujete) a automaticky vyprší po období nečinnosti (výchozí 60 minut). Až budete hotovi, můžete zavolat CloseDocument pro předčasné uvolnění položky v cache.

---

Registrace bezstavového Vieweru

Protože Viewer nemá žádný měnitelný stav, zaregistrujte jej jednou během spouštění:

builder.Services.AddDoconut();               // registruje Viewer a požadovaný middleware
builder.Services.AddSession();               // vyžadováno pro zabezpečení tokenu
builder.Services.AddDistributedMemoryCache(); // jednoduchá cache pro demo

Volání AddDoconut také propojí middleware, který poskytuje statické zdroje vieweru. Po nastavení služeb můžete požadovat Viewer v jakémkoli podpisu koncového bodu.

---

Minimální otevřený dokumentový koncový bod (příklad pro net‑8)

Následující kód je přesný úryvek z oficiální dokumentace a funguje ihned v projektu .NET 8 minimal‑API:

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

Co kód dělá

1. Přijímá název souboru – klient říká serveru, který soubor pod wwwroot/files má otevřít.
2. Volá OpenDocumentAsync – bezstavový Viewer vytvoří novou relaci, uloží ji do cache a vrátí neprůhledný token.
3. Vrací token jako prostý text – klient obdrží pouze token; server v této odpovědi nikdy neodesílá bajty dokumentu.

Protože Viewer neobsahuje žádná data dokumentu, koncový bod nepotřebuje bloky using, volání Dispose ani továrny na požadavek. Token je jediným pověřením, které klient kdykoli pošle zpět widgetu vieweru (objViewer.View(token) na front‑endu).

---

Použití tokenu na straně klienta

Po vrácení tokenu front‑end widget zavolá objViewer.View(token). Widget pak zahrne stejný token ke každému následnému požadavku na obrázky stránek, vyhledávání nebo akce anotací. Server ověří token vůči relaci, která původně otevřela dokument. Pokud je token předložen z jiné relace prohlížeče, viewer vrátí chybu autorizace, což je zamýšlené bezpečnostní chování.

---

Ukončení relace předčasně (volitelné)

Pokud váš pracovní postup ví, že dokument už nebude nikdy znovu přístupný, můžete uvolnit položku v cache vyvoláním CloseDocument na Viewer. Tím se relace odstraní z cache a zabrání se tomu, aby časovač posuvného vypršení udržoval relaci naživu.

---

Shrnutí bezstavového toku

Krok	Co se děje	Kde se stav nachází
Injektujte Viewer	Jedna instance Viewer je vytvořena při spuštění.	V DI kontejneru (singleton).
OpenDocumentAsync	Licence ověřena → relace vytvořena → token vrácen.	Relace uložena v IMemoryCache (nebo distribuovaná cache).
Klient vykresluje	Widget posílá token s každým požadavkem.	Token je jediná data dokumentu, která klient drží.
Vypršení relace / CloseDocument	Položka v cache odstraněna po vypršení časového limitu nebo explicitním uzavření.	Žádné zbylé zdroje ve službě Viewer.

Protože samotná služba nikdy neukládá data dokumentu, můžete bezpečně škálovat svůj webový farm, nahrazovat uzly nebo restartovat aplikaci bez ztráty jakéhokoli uživatelsky viditelného stavu — pouze token se stane neplatným, což přiměje klienta znovu otevřít dokument.

---

Nasazení bezstavového Vieweru ve vaší aplikaci

1. Přidejte AddDoconut, AddSession a poskytovatele cache do Program.cs.
2. Vložte úryvek otevřeného koncového bodu do své konfigurace minimal‑API.
3. Předávejte vrácený token do objViewer.View(token) na front‑endu.

Nyní máte plně bezstavové, produkčně připravené API pro otevírání dokumentů, které využívá design Viewer od Doconut.