Files
pages/docs/design/ja/kunstzeal.md
T
Anya Tokugawa d5d21b7841
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s
Refactor architecture into eight components and consolidate reliability work
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.
2026-11-01 15:23:31 +09:00

126 lines
9.2 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は実装されていない。
- [ ] 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・デプロイは別段階とする。