Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
9.2 KiB
Kunstzeal の表示方式と描画プロバイダー契約
2026-11-01、既存の表示方式の選択とKroki図描画を internal/kunstzeal に初期分離した。
Kunstzealは描画エンジンを自作する部品ではなく、表示方式と外部描画の呼出し契約をまとめる。
Page/Revisionの正本、認可、HTMLの信頼境界は引き続きアプリケーションが所有する。
スライド、nwdiag、新しい描画サービスの追加は今回含めない。
コンポーネント命名 と 表示アダプタ設計 を併読する。
責務と依存方向
| 部品 | 責務 |
|---|---|
kunstzeal.SelectAdapter |
有効MIME・ファイル名から、既存の優先順で表示方式を選択 |
kunstzeal.Catalog |
ビルトイン14種類の定義のコピーを返す。呼出し元から共有registryを変更させない |
DiagramProvider / Kroki |
型・入出力サイズ・時間を制限したSVG描画要求。エラーを一般化 |
| 図のhash・cache | 既存hashの計算、有界読込、一時ファイルからの原子的なcache置換 |
| server | 対象解決・認可・Domain/Path由来情報・HTTP応答・CSP・Kroki接続設定・hosted plugin管理 |
| Grammaratur | HTML/Markdown等の文書形式変換。描画された図を正本へ書き込まない |
| Dregarnuhr / 既存preview処理 | PDF・動画等の背景サムネイル生成。今回は移動しない |
server/compiler → kunstzeal の一方向依存とする。 Kunstzealはstore/server/DBへ依存せず、認証CookieやBearer tokenを受け取らない。 図cacheのファイルI/Oと設定済みKrokiへのHTTP以外に、新たな実行環境を持たない。 任意の実行ファイルやshellを起動する機構ではない。
表示方式の選択と互換性
順序は html、excalidraw、csv、archive、debian-package、eml、pe、
json、text、image、audio、video、pdf、download を維持する。
特殊形式を一般JSON/textより先に選択し、未知の形式はdownloadへ落とす。
MIME検出、文字コード変換、各形式のparserとViewer実装自体は今回移動しない。
MIMEと拡張子の優先関係も変更しない。
Descriptor・Adapter・Delivery はserverの旧型をaliasで接続する。
ID、Kind、Delivery、NeedsText、WindowableText、2MiBのテキストwindow閾値は同一。
/_/api/v1/adapter のビルトイン一覧も同じcatalogを参照する。
Catalogは複製したsliceを返すため、一覧編集が別要求の選択結果を変えない。
hosted viewer/editorの設定キー・有効無効・URL検証・起動ticket・保存経路は変更しない。 ビルトイン選択registryを任意コードをロードするプラグイン機構へ変更するものではない。 Excalidrawの別コンテナ/ブラウザ内描画、PDF、media、archive等の実行環境は従来のまま。
Krokiの実行契約
DiagramProvider.Render(ctx, kind, source) はSVGバイト列またはエラーを返す。
既存Kroki呼出しはmermaid・plantuml・graphviz・dot・d2のみ許可し、dotはgraphvizへ正規化する。
任意のURL・出力形式・エンジン名は文書から指定できない。
| 項目 | 契約 |
|---|---|
| 図ソースPOST | 最大1MiB。超過時は送信せず413 |
| HTML内の図ブロック | 32KiBまで。超過時は元のコードブロックを残す |
| 描画要求 | POST、text/plain; charset=utf-8、最大15秒。親contextの取消も反映 |
| 結果 | 2xxのみ成功、最大4MiB。非2xxの応答本文は利用者へ返さない |
| endpoint | 管理者の KROKI_URL、空なら既存の http://kroki:8000。API入力から選択しない |
| client | 呼出し元のHTTP clientが必須。未設定時に既定clientで送信しない |
| redirect | serverのclientで全redirectを拒否。301/302/307/308も描画失敗として扱う |
| エラー | 設定不備500、描画失敗502。接続先URL・provider本文・元ソースをエラー文へ含めない |
今回の是正として、endpointにuserinfo・query・fragmentを含む設定は拒否する。 内部ComposeサービスへのHTTP接続は既存仕様なので許可する。公開IP限定の一般URL取得とは異なる。 既存のHTTP clientによるproxy環境設定の扱いは変えない。接続先は信頼された運用設定として扱う。 DNS/IP固定、providerのTLS認証・egress制限、描画サービス自体のファイル/ネットワークアクセス制限は この抽出だけでは提供しない。配置先・ネットワーク隔離と合わせた後続契約とする。
clientはcontextを尊重する必要がある。コアの時間制限は任意の悪意ある実装を強制停止するsandboxではない。 HTTP clientとcoreの両方に時間予算を設けるが、描画サービス側のCPU/RAM使用量は別管理である。
Cacheと認可
hashは従来の SHA256(kind + NUL + format + NUL + source) を維持し、
compiler.DiagramHash とserverの旧入口は共通実装へ委譲する。
HTML由来ではsourceの前に既存のHTML projection version・Domain・Pathを組み込み、
同じ図でも異なるPathの権限参照を共有しない。POSTの入力そのものをhash化する方式も維持する。
保存先は既存の <diagramRoot>/<kind>/<hash>.svg。DB migrationやcache移行は不要。
読込は最大4MiB。書込は同じディレクトリの一時ファイルを完成させてからrenameする。
並行読込に途中までのSVGを渡さず、失敗時は一時ファイルを削除する。
cacheの保存に失敗しても、正常に描画できた応答は返す。これは再生成可能なcacheであり、
fsyncを伴う正本文書の耐障害commitや、同一キーの二重生成抑止ではない。
GETの認可はcache読込より先に行う。既存のソース由来情報はメモリ上で128件、30分以内。 kind・Domain・Pathの現在の読み取り権限を検査し、期限切れ・由来不明・別Domain・権限なしは404。 ディスクにSVGが残っていること自体はアクセス権にならない。 POSTは既存のdomain read endpoint policyを通り、利用者が送ったソースを描画する別経路である。 これを新たな匿名描画APIへ変更しない。
SVGの信頼境界
providerが返すSVGをアプリケーションのHTMLへ直接挿入しない。 cache hit、新規描画、直接アクセスでも、従来どおり次を付与する。
Content-Type: image/svg+xml; charset=utf-8
Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:
X-Content-Type-Options: nosniff
Cache-Control: private, no-store
バイト数を制限することとSVGの内容を安全と認定することは異なる。 今回SVG sanitizerや完全な構文検証は追加しない。Kunstzealの出力は信頼済みHTMLではなく、 上記のsandbox応答で扱う必要がある。HTML本文のsanitizer・macro展開・CSPはserverが引き続き適用する。 図の正本ソース、Page/Revision、既存の表示URIは変更しない。
後続TODO
- provider ID/version・テーマ・オプションを含む新しいcache keyと、旧cacheからの移行/失効を設計する。
- 同時描画上限、同一キーの実行集約、優先度、キャンセル、Dregarnuhrへの背景生成、過負荷時の安全な再試行表示を整備する。
- provider単位の停止・切戻し・health・CPU/RAM/時間/件数/失敗の観測を統一する。今回hosted pluginの既存設定は維持したが、この統一機構は追加していない。
- ソース由来cacheをプロセスglobalからinstance単位へ整理し、再起動・複数nodeでも認可と失効を保てる取得方式にする。
- ディスクcacheの容量・TTL・清掃、renderer更新時の不整合、障害後の一時ファイル残留を管理する。
- provider宛通信と描画サービス内の外部参照を分け、送信許可・接続先・ネットワーク隔離・バージョン固定を契約化する。
- nwdiagの有界parser・安全なSVG出力・編集preview、Draw.io等のproviderを追加する。現在のregistryにnwdiagは実装されていない。
- Reveal互換・HedgeDoc・Slidev・CSS-onlyスライドのimport/save/printを独立providerとして設計する。
- Excalidrawのhosted/browser実行とPDF/動画サムネイル・metadata subprocessを、各々の安全境界を維持したまま段階的に接続する。
検証と反映
合成ソース・一時ディレクトリ・偽HTTP client・localhostの偽Krokiだけで検証する。 入力/出力上限、取消、全redirect拒否、エラー情報の非開示、cacheの並行読込/置換、 kind/hashとcatalog互換、Domain/Pathの認可、由来情報の期限、CSPを確認する。 実Krokiの版ごとの描画品質や本番通信は今回の検証対象ではない。
実行記録は コンポーネント検証記録 に記載する。 本番DB・取り込み済み外部カレンダーへアクセスせず、commit・push・デプロイは別段階とする。