איך הצופה עובד

Doconut מציג מסמכים כתמונות ממפוצות בדפים המוגשות דרך Middleware של ASP.NET Core. הבנת מחזור החיים — פתיחה, אסימון, בקשות דפים, סגירה — מסבירה כמעט כל התנהגות שתצפו, כולל הודעות השגיאה.

שלושת החלקים הנעים

• Viewer — השירות הציבורי שאתה מוזרק. הוא פותח מסמכים ומחזיר אסימוני סשן.
• סשן המסמך — אובייקט בצד השרת המחזיק את המסמך הטעון, ממופה באמצעות אסימון ב-IMemoryCache.
• ה‑Middleware של Doconut — נוסף על ידי UseDoconut(); משיב לכל בקשה שהווידג'ט של הדפדפן מבצע (pages, thumbnails, search, annotations, …), תמיד מאומת באמצעות האסימון.

Viewer הוא חסר מצב — לפי תכנון

Viewer סגור, אינו מחזיק במצב מסמך לכל בקשה, ובכוונה אינו מממש IDisposable. סשנים קיימים באופן עצמאי במנהל הסשנים ומנוקים על ידי תפוגת המטמון או CloseDocument(token) מפורש.

הזרק אותו בכל מקום שבו אתה צריך אותו:

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 עושה תלוי בבקשה:

כל אחד מהנתיבים האלה מתבצע אימות תחילה:

• אין אסימון → ה‑middleware מחזיר 404 (או באנר גרסה כאשר ShowDoconutInfo = true).
• אסימון לא ידוע או שפג → תמונת שגיאה עם סשן המסמך לא נמצא. אנא פתחו את המסמך מחדש.
• חוסר Middleware של סשן (עם UnsafeMode = false) → HTTP 500 עם Middleware של סשן לא הוגדר. קראו UseSession() לפני UseDoconut().
• אסימון נפתח על ידי סשן דפדפן שונה → תמונת שגיאה עם אינכם מורשים לצפות בדף זה.

סגירת מסמך

viewer.CloseDocument(token);

CloseDocument מסיר את הסשן מהמטמון (שמשחרר את מנוע המסמך הבסיסי ומשחרר את הזיכרון שלו מייד), מוחק את הסמן secure-{token}, ומבטל את ההרשאה לגישה. קריאה אליו היא אופציונלית — תפוגה מחליק עושה את הניקוי באופן אוטומטי — אך עבור מסמכים גדולים זו הדרך המנומסת לשחרר זיכרון ברגע שהמשתמש סיים.

מסקנות

• מסמך פתוח אחד = סשן אחד = אסימון אחד. אסימונים הם לכל סשן דפדפן, לא כתובות URL גלובליות.
• האסימון פג בתפוגה מחליקה; צפייה שנשארה במצב מנוחה מעבר ל-DocOptions.TimeOut דורשת פתיחה מחדש.
• ניתן להזריק ולשתף את Viewer בחופשיות; הסשנים נושאים את כל המצב.