Як працює переглядач

Життєвий цикл запиту документа

Doconut відображає документи у вигляді розбитих на сторінки зображень, які подаються через middleware ASP.NET Core. Розуміння життєвого циклу — відкриття, токен, запити сторінок, закриття — пояснює майже всю поведінку, яку ви спостерігатимете, включаючи повідомлення про помилки.

Три взаємодіючі частини

  • Viewer — публічний сервіс, який ви інжектуєте. Він відкриває документи та повертає токени сесії.
  • Сесія документа — об’єкт на боці сервера, що зберігає завантажений документ, індексований токеном у IMemoryCache.
  • Middleware Doconut — додається UseDoconut(); відповідає на кожен запит, який робить віджет браузера (pages, thumbnails, search, annotations, …), завжди автентифікований токеном.

Viewer є безстанним — за задумом

Viewer є sealed, не містить стану документа для кожного запиту і навмисно не реалізує IDisposable. Сесії існують незалежно в менеджері сесій і очищуються вичерпанням кешу або явним CloseDocument(token).

Інжектуйте його там, де потрібно:

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

Що відбувається всередині OpenDocumentAsync

  1. License gate. Відхилена або застаріла ліцензія (чорний список, підроблена або збірка поза вікном оновлення ліцензії) одразу викидає LicenseException, причину відхилення у повідомленні — відкриття ніколи не деградує без повідомлення для недійсної (на відміну від відсутньої) ліцензії. Ліцензія Temporary або підписки, термін якої закінчився за календарем, є винятком: вона не викидає помилку — переходить у водяний знак.
  2. Session creation. Фабрика переглядача вибирає відповідний переглядач формату за розширенням файлу і завантажує документ (див. Rendering Pipeline). Сесія зберігається у IMemoryCache під новим GUID токеном з ковзним терміном дії — DocOptions.TimeOut хвилин, за замовчуванням 60. Кожен запит сторінки скидає таймер.
  3. Security registration. За допомогою UnsafeMode = false (за замовчуванням) токен прив’язується до ASP.NET сесії виклику: в сесію записується маркер secure-{token}, тому лише браузерна сесія, яка відкрила документ, може запитувати його сторінки.
  4. Токен повертається. Це єдині облікові дані для всього подальшого.

Три перевантаження відрізняються лише вхідними даними: шлях до файлу, шлях до файлу плюс конфігурація для формату (PdfConfig, WordConfig, …) або Stream плюс FileInfo, розширення якого визначає формат.

Як віджет отримує сторінки

Віджет клієнта викликає middleware Doconut з токеном у рядку запиту. Що робить middleware, залежить від запиту:

ЗапитПризначення
?token=…&page=NЗображення відрендереної сторінки (PNG)
?token=…&page=N&thumb=1Мініатюра
?token=…&zoom=…Рендеринг збільшеної сторінки
?token=…&search=termПовнотекстовий пошук (з захистом ліцензії)
?token=…&bookmarksСтруктура документа/закладки
?token=…&copy / &showlinks / &fileFormatКопіювання тексту, гіперпосилання та інформація про формат
?token=…&metaТехнічні метадані DICOM; повертає 501 для DICOM сесії на .NET 6
?token=…&action=rotate/flip/closeДії зі сторінками та явне закриття
?token=…&AnnSave=… / &AnnLoadЗбереження/завантаження анотацій

Кожен з цих шляхів спочатку проходить валідацію:

  • No token → middleware повертає 404 (або банер версії, коли ShowDoconutInfo = true).
  • Unknown or expired token → зображення помилки з Document session not found. Please re-open document.
  • Session middleware missing (з UnsafeMode = false) → HTTP 500 з Session middleware not configured. Call UseSession() before UseDoconut().
  • Token opened by a different browser session → зображення помилки з You Are Not Authorized To View This Page.

Обслуговування сторінок з спільного сховища замість вузла відкриття — це зовсім інша схема; див. Розподілені розгортання.

Закриття документа

csharp
viewer.CloseDocument(token);

CloseDocument видаляє сесію з кешу (що звільняє підлеглий движок документа і одразу звільняє пам'ять), видаляє маркер secure-{token} і відкликає доступ. Викликати це необов'язково — ковзний термін дії виконує те ж саме автоматично — але для великих документів це ввічливий спосіб звільнити пам'ять одразу після завершення користувачем.

Висновки

  • Один відкритий документ = одна сесія = один токен. Токени прив'язані до браузерної сесії, а не до глобальних URL.
  • Токен закінчує термін дії у ковзному вікні; переглядач, який залишився без дії після DocOptions.TimeOut, потребує повторного відкриття.
  • Viewer можна інжектити та вільно ділитися; сесії містять весь стан.

Чи була ця сторінка корисною?