127 lines
9.6 KiB
Markdown
127 lines
9.6 KiB
Markdown
# 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化する方式も維持する。
|
||
|
||
保存先は既存の `<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、新規描画、直接アクセスでも、従来どおり次を付与する。
|
||
|
||
```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は実装されていない。
|
||
- [x] Reveal.jsの有界ビューア・既存HTML/Markdownエディタ内previewをローカル固定版で接続する。Path認可・sandbox・ドメイン停止を持ち、正本への保存は既存エディタを利用する([スライド設計](extensions.md))。
|
||
- [ ] Revealの縦スライド・発表者notes・専用print、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・デプロイは別段階とする。
|