Plugins

מערכת התוספים

דף זה מתעד את הצד של אוצריא — הגשר, האכיפה וה־runtime. למי שרוצה לכתוב תוסף: פיתוח תוספים.

lib/plugins/ — תוספים הם אפליקציות web (‏HTML/JS) שרצות ב־WebView ומדברות עם אוצריא דרך גשר RPC. עקרון האבטחה המרכזי: כתיבה לדיסק מגודרת בהסכמת משתמש מפורשת (בחירת תיקייה/קובץ), לא בהרשאת manifest בלבד.

מבנה תוסף

• PluginManifest — ‏id, ‏name (עד 14 תווים), ‏version, ‏entrypoint, ‏backgroundEntrypoint (ריצת רקע), אייקון, טווח גרסאות אפליקציה, permissions[], רשת (networkEnabled + ‏allowlist), הגדרות לשונית כלים, publishedDataTypes, ‏databaseSources.
• InstalledPlugin — רשומת ההתקנה: ‏enabled, ‏pinned (גם ל־nav rail), הרשאות שניתנו בפועל, סוג מקור (‏packaged / development / localhost_dev), סדר משתמש.
• אריזה: קובץ .otzplugin‏ (ZIP). אפשר לארוז גם מה־CLI:‏ otzaria pack-plugin.

הגשר — PluginBridgeAdapter

bridge/plugin_bridge_adapter.dart (~2150 שורות) מממש את כל תחומי ה־RPC:

תחום	פעולות עיקריות
app	מידע, ‏theme (‏payload מלא של ColorScheme — נבנה מאותו createColorScheme של האפליקציה), ‏locale, פתיחת URL
library	חיפוש ספרים, מטא־דטה, תוכן ספר (chunks של עד 5000 תווים עם מטמון LRU), ‏TOC, עץ הספרייה
search	חיפוש מלא־טקסט
reader	פתיחת ספר / פתיחה לפי מראה מקום (openBookAtRef — עם מנוע find_ref), מצב נוכחי, בחירה, פריטי תפריט הקשר, הדגשות
navigation	מעבר מסכים
notes	קריאה/כתיבה של הערות אישיות
ui	הודעות, אישורים, בחירת תיקייה (רושמת תיקייה מאושרת)
fs	חילוץ ZIP / מחיקה (רק בתיקיות מאושרות, עם קנוניזציה נגד traversal); קבצים אישיים — בחירת קובץ, קריאת טקסט (עד 10MB), הגשת קובץ דרך שרת מקומי
storage	‏KV פר־תוסף
settings	קריאת הגדרות לפי allowlist מפורש (בלי סיסמאות/נתיבים/סודות)
database	שאילתות read-only דקלרטיביות
network	‏fetch/הורדה דרך צד ה־Flutter (עוקף CORS) עם allowlist
נוספים	לוח שנה, נתונים מפורסמים בין תוספים, היסטוריה, התראות, קיצורי דרך, התקנת תוספים

אכיפה — PluginBridgeHandler

• Rate limiting — ‏token bucket‏ (50 טוקנים); getBookContent פטור.
• מיפוי הרשאות — כל domain/action ממופה למחרוזת הרשאה (library.content.read, ‏fs.user_files.read, ‏network.access...).
• ‏timeout ברירת מחדל 30 שניות; קודי שגיאה אחידים.

שרת הקבצים המקומי — PluginFileServer

HttpServer על ‏127.0.0.1 בפורט אקראי, מגיש רק קבצים שנרשמו עם token אקראי 256-bit. תומך ב־HTTP Range (חיוני ל־PDF.js). נועד להגיש PDF גדול בלי להעבירו כ־base64 דרך הגשר. הערה: PDF ב־iframe מובנה לא עובד ב־Android/Linux — תוספים חייבים PDF.js.

התקנה, פיתוח וחיי ריצה

• PluginInstallerService — התקנה דו־שלבית: ‏prepare (חילוץ ב־isolate, ‏validation) ← ‏finalize (העתקה ל־plugins/installed/<id>/current, ‏seed הרשאות — משמר revokes של המשתמש בעדכון).
• תוספי פיתוח — טעינה מתיקייה מקומית או מ־localhost, עם מעקב שינויי קבצים ו־reload אוטומטי.
• PluginRuntimeDispatcher — ‏singleton שמנהל את ה־WebViews: ‏foreground‏ (לשונית) ורקע (PluginBackgroundHost, בהרשאת app.run_on_startup), השהיה/חידוש לחיסכון משאבים, שידור אירועים (בכפוף להרשאת events.subscribe:<topic>), ‏teardown לפני restart.
• ReaderLocationTracker — עוקב אחרי מיקום הקריאה הנוכחי ומשדר reader.current_ref_changed לתוספים (debounce‏ 150ms).
• אחסון — ‏SQLite‏ plugins_host.db: התקנות, הרשאות, ‏KV, נתונים מפורסמים, לוגים.
• חיבור למערכת ההפעלה — רישום פרוטוקול otzaria:// ושיוך סיומת .otzplugin‏ (Windows: ‏reg.exe; ‏Linux: ‏desktop entry + ‏MIME). קישורי חנות: otzaria://plugin/install?url=....

גישת DB לתוספים — PluginDatabaseService

שאילתות דקלרטיביות (JSON: ‏from/joins/select/where/orderBy/limit) שמקומפלות ל־SQL פרמטרי, עם policy מלא של טבלאות/עמודות/joins מותרים, ‏read-only, ומטמון תוצאות קצר.

ולידציה ב־CI

קיים ריפו נפרד — Otzaria Plugin Validator — ‏GitHub Action שבודק תוספים (מניפסט, מבנה, מגבלות) לפני קבלתם לחנות.

דפים קשורים

• פיתוח תוספים
• הגדרות
• ארכיטקטורה (deep links)
• גיבוי ושחזור