# Kunstzeal の表示方式と描画プロバイダー契約 2026-11-01、既存の表示方式の選択とKroki図描画を `internal/kunstzeal` に初期分離した。 Kunstzealは描画エンジンを自作する部品ではなく、表示方式と外部描画の呼出し契約をまとめる。 Page/Revisionの正本、認可、HTMLの信頼境界は引き続きアプリケーションが所有する。 スライド、nwdiag、新しい描画サービスの追加は今回含めない。 [コンポーネント命名](component-names.md) と [表示アダプタ設計](../projection-adapters.md) を併読する。 ## 責務と依存方向 | 部品 | 責務 | | --- | --- | | `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化する方式も維持する。 保存先は既存の `//.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、新規描画、直接アクセスでも、従来どおり次を付与する。 ```text 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の版ごとの描画品質や本番通信は今回の検証対象ではない。 実行記録は [コンポーネント検証記録](component-names.md#検証記録) に記載する。 本番DB・取り込み済み外部カレンダーへアクセスせず、commit・push・デプロイは別段階とする。