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

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

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. Ліцензійний шлюз. Відхилена або прострочена за версією ліцензія (чорний список, підроблена або збірка поза вікном оновлення ліцензії) миттєво генерує LicenseException, з причиною відхилення у повідомленні — відкриття ніколи не деградує безшумно для недійсної (на відміну від відсутньої) ліцензії. Ліцензія, що закінчилася за календарем (тимчасова або підписка), є винятком: вона не генерує виключення — переходить у водяний знак.
  2. Створення сесії. Фабрика переглядача вибирає відповідний переглядач формату за розширенням файлу та завантажує документ (див. Rendering Pipeline). Сесія зберігається у IMemoryCache під новим GUID токеном з ковзним терміном дії — DocOptions.TimeOut хвилин, за замовчуванням 60. Кожен запит сторінки скидає таймер.
  3. Реєстрація безпеки. За допомогою 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 / &metaКопіювання тексту, гіперпосилання, інформація про формат, технічні метадані DICOM
?token=…&action=rotate/flip/closeДії зі сторінкою та явне закриття
?token=…&AnnSave=… / &AnnLoadЗбереження/завантаження анотацій

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

  • Відсутній токен → middleware повертає 404 (або банер версії, коли ShowDoconutInfo = true).
  • Невідомий або прострочений токен → зображення помилки з Document session not found. Please re-open document.
  • Відсутній middleware сесії (з UnsafeMode = false) → HTTP 500 з Session middleware not configured. Call UseSession() before UseDoconut().
  • Токен відкритий іншою браузерною сесією → зображення помилки з You Are Not Authorized To View This Page.

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

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

csharp
viewer.CloseDocument(token);

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

Висновки

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

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