Files
pages/docs/design/system-extensions.md
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

209 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# システム拡張の詳細設計
## 境界と今回の実装
連携アダプタはDocument/Revisionを特定のMIMEに応じて編集・表示する。
システム拡張はナビゲーション、活動、通知、検索、ストレージ、テーマ、監視などの
サービスを提供する。設定・API・実行権限をアダプタのURLテンプレートに混在させない。
実装済みの入口:
- `internal/extensions/registry.go`: バージョン付きの信頼済みビルトインmanifest。
- `GET /_/api/v1/extension/`: 管理者向けcatalog。書き込み・インストールAPIは未公開。
- `/-/sys/config?panel=extensions`: 連携アダプタとは独立したシステム拡張一覧。
- `system.resources`: instanceスコープのバックグラウンド監視。
- `navigation.bookmarks`: domainスコープのカードと子ページリンク。
- `content.diary`/`content.blog`: Domain別に有効化する記事メタデータ、カレンダー、
最近の記事、カテゴリ一覧。初期版はログイン必須・既存Page登録型。
[実装範囲と後続タスク](diary-blog-plugins.md)を参照。
これは外部プラグインローダーではない。任意Go plugin、JS、シェル、URLからの実行、
manifestアップロードによる権限付与は未実装・不許可。現在のcapabilities一覧はサービス
境界の宣言であり、既存の認証を置換しない。実際のハンドラは既存のmanage/read権限と
管理者グループを確認する。ビルトインの設定入口を分離した最初の実装である。
vim.wasmの動作改善はユーザー指示により保留。この変更でVim本体を変更しない。
## Manifest/ライフサイクル契約
将来の外部パッケージmanifestに必要な項目:
| 項目 | 意味 |
| --- | --- |
| id, version, api_version, compatibility | 安定ID、パッケージ版、ホスト契約との互換性 |
| kind, scope | activity/comment/diary/theme/monitor/storage/search/bookmark-source、instance/domain/principal |
| capabilities, outbound_hosts, secret_refs | 要求能力・送信先許可リスト・秘密参照。manifestのみでは許可しない |
| config_schema, migrations | 型付き設定と設定版移行。未知フィールド拒否 |
| events, hooks, checkpoints | 定期ジョブ・購読イベント・再実行位置 |
| runtime, image_digest, signature | 分離プロセス/コンテナ、固定イメージ、署名 |
| timeouts, concurrency, memory, payload_limit | リソース上限。前景処理をブロックしない |
| health, export, retention | 健全性、移行・アンインストール時のデータ保護 |
設定は `(scope_type, scope_uuid, extension_id, schema_version)` で分離する。
外部拡張導入時には `system_extension_installations` と `system_extension_config` を追加し、
installed → configured → enabled → disabled/failed の状態遷移を監査する。
署名・互換性・要求能力を確認するまで実行しない。アップグレード中は新しいジョブを
止め、checkpointを保持して移行する。無効化はデータ削除を意味しない。
設定UIはホスト所有のschema rendererを基本とする。独自UIは固定originのsandbox iframe
と型付きメッセージ契約に限定し、通常のログインBearer/Cookieを渡さない。
第三者コードはホストプロセス内にロードせず、短命の委譲capabilityでAPIにアクセスする。
## ビルトインのリソース監視
- 定義ID `builtin.resource.sample`、イベント型 `resource.sample`。
- 起動時に未登録の場合のみ追加。既定60秒、変更可能範囲30〜86400秒。
- 既存キューのpriority=100、通常のclaim/履歴/ログ/キャンセルを利用する。
CPU・メモリ・ファイルシステム情報だけを収集し、外部コマンドや再帰走査をしない。
- `resource_samples(id, job_uuid UNIQUE, timestamp_ms, payload)` に永続化。
同一jobの再実行は重複登録しない。書き込みと期限切れ削除は同一トランザクション。
- 7日保持。期限切れ削除は収集時に実行する。停止中に過去データを捏造して補間しない。
- `GET /_/api/v1/queue/resources/history?hours=1|24|168` は最大361点。
timestamp索引で期間を絞り、バケット内の最終サンプルを返す。平均/最大値ではない。
- 現在値APIと履歴を区別する。グラフの更新停止やブラウザを閉じる操作は収集を止めない。
収集停止は監視イベントのenabledまたはキューのpausedによる。
- ビルトイン定義は削除不可。無効化と間隔変更は再起動後も維持する。
- データはこのSQLiteインスタンスのローカル監視。Campus全ノードの集約ではない。
CPUはホストload average、メモリはGo heap、容量はDocument Storeファイルシステム。
コンテナのCPU使用率/RSS/cgroup制限として表示しない。
既存運用APIと同じインスタンス全体の管理権限を利用する。複数管理主体での厳密な分離は
`instance_operator` 相当の運用権限設計後に移行する。HAではinstance UUID/boot IDを追加し、
各ノードの収集と中央集約・leaseを分ける。SQLiteファイルの共有マウントで代用しない。
### ディスクI/O
`queue/resources` と `resource.sample` の保存payloadへ
`io: {scope:"process", available, process_id, read_bytes, write_bytes}` を追加。
Linuxの `/proc/self/io` を読み取り、読み込み・書き込みの累積カウンタを保存する。
HTTPハンドラで待機や外部コマンド実行、ディレクトリ走査は行わない。
`process_id` はアプリプロセスごとのランダムUUIDで、コンテナでPIDが再利用されても区別できる。
表示速度は同一process_idの隣接サンプルの差分bytes/差分秒。最初のサンプル、
旧履歴でI/Oフィールドがない場合、取得失敗、再起動、時刻逆転、カウンタ減少、
JSの安全整数範囲外は欠測にし、0や巨大なスパイクで代用しない。
ライブカードは画面取得間の速度、履歴は保存サンプル間の平均速度であり、ピーク値ではない。
[Linux kernelのproc仕様](https://docs.kernel.org/filesystems/proc.html#proc-pid-io-display-the-io-accounting-fields)
に従うストレージ層の計上値。`rchar/wchar`(キャッシュ等を含むread/write呼び出しの量)
とは区別する。write_bytesはページ変更時の計上で、実デバイスへのflush完了や
cancelled_write_bytes差引後の正味書き込みを意味しない。
ホスト全体・全コンテナ・外部アダプタ・全ワーカーの合算やデバイス利用率/レイテンシ/IOPS
は今回の対象外。必要に応じてcgroup/デバイス別collectorを別スコープとして追加する。
### SNMPの将来オプション
`monitor.snmp` は別collectorとして設計する。初期候補はSNMPv3 authPriv、読み取り専用、
対象FQDN/IP・OIDを管理者が許可し、秘密はsecret_refで参照する。SNMPv1/v2cは必要性と
ネットワーク制約を確認するまで既定無効。到達先制限、タイムアウト、再試行間隔、
最大varbind数、単位変換、Counter32/64の周回、再起動によるカウンタリセットを扱う。
欠測/認証失敗を0使用率に変換しない。SNMPサーバーの公開やネットワーク探索は今回行わない。
## 各拡張のデータと処理
| 拡張 | 保存モデル・表示 | 実行・権限と最初の実装単位 |
| --- | --- | --- |
| ランキング/いいね | `page_metric_buckets(domain,page_uuid,bucket,metric)`、`page_reactions(domain,page_uuid,principal,reaction)` | 日別閲覧・いいねを集約。閲覧可能Pageだけ表示し、非公開Pageの件数や順位から漏らさない。bot・連打除外、期間と計算版を固定 |
| 最新編集 | `page_activity_events` と日別/domain別projection | UUID/Revisionを軸に作成・編集・renameを表示。可視Pathを出力時に解決。bodyを再走査しない |
| ユーザー別直近編集 | `(domain,principal,page_uuid,last_edit_at,revision)` projection | actorをクライアント申告にせずサーバーで記録。既定は本人のみ閲覧。現時点のPage権限で再検査 |
| コメント | `comment_threads`、`comments`、`comment_anchors` | スレッドはPage UUID、インラインはRevision+範囲+周辺テキストhash。改訂後に再アンカー/孤立を区別。投稿・編集・モデレーション・通知を別capabilityにする |
| 日記 | `diary_entries(domain,owner,local_date,page_uuid,timezone)` | 専用Pageを通常のRevisionとして作成。日付は設定timezone、同日作成は冪等。`/u/{name}/diary/YYYY/MM/DD` は初期Path案でありrename後もUUID保持 |
| 条件付きテーマ | `theme_rules(domain/principal,priority,condition,theme_id)` | 時刻、曜日、経過時間、OS配色を型付き条件にする。日没はユーザー指定の緯度経度/timezoneで計算し、無断で位置情報を取得しない。CSSテーマIDのみ、任意JS条件は禁止 |
| S3互換 | immutable Document Store provider+配置情報 | `PutIfAbsent/Stat/Open/ReadAt/Verify/DeleteUnreferenced` 契約。sha256 identityを維持し、ETagをhashと決めつけない。署名URLは短命、RangeとGC証明・失敗再試行を検証 |
| WebDAV/SSHFS | external collection connector または検証済みDocument backend | 編集可能な外部ファイルと正本CASを区別。まずread-only参照/取り込み。WebDAVの条件付き更新・Range、SSHのhost key pinを設計。SSHFSマウント・FUSE権限は専用sidecarで管理しWeb要求からmountしない |
| 外部検索 | `search_connectors`+正規化result | PagesWiki/GROWI/PukiWikiは機能検出とAPI契約確認後に個別connector。検索対象domain・資格情報・timeout・最大結果・URL allowlistを設定。外部の権限とローカル権限を混同しない |
| Wikipedia/Google補助検索 | 外部検索リンクまたは契約済み検索API provider | ローカル0件でも自動送信しない。送信クエリを表示してユーザーが選択。まず外部検索リンクから開始し、APIは規約・課金・制限を確認して別実装。無許可スクレイピングはしない |
| Linkding等のブックマーク引用 | `bookmark_sources`、`external_bookmark_items(source,remote_id,url,title,tags,updated_at)` | URL/タイトル/タグ/出典を同期。本文コピーは別の許可付きimport。個人tokenは個人スコープ、共有を明示。セクションsource providerとして注入し、手動リンクを消さない |
外部検索APIの共通結果は `provider_id, remote_id, title, canonical_url, snippet,
updated_at, source_scope` とし、外部由来を常に表示する。HTMLはサニタイズし、検索結果URLを
サーバー側で無制限にfetchしない。
## イベント/API設計
## Network and composition extensions (design TODO)
IPAM, DNS zone/record administration, and inventory/asset management are typed
system extensions, not free-form editor adapters. Their records (`network_prefix`,
`dns_zone`/`dns_record`, `asset_item`) retain ownership, audit history, soft-delete
state, and references to Pages/Assets. Provider writes use dry-run, approval,
idempotency keys, etag/revision checks, secret references, allowlisted origins,
rate limits, and bounded queue jobs; DNS resolution or scanning never runs in a
foreground Page request. Candidate API namespaces are
`/_/api/v1/extension/network.ipam/*`, `network.dns/*`, and
`inventory.assets/*`, pending schema and permission review.
The CSV macro is a read projection of an authorized immutable Revision, for
example `{{csv:/data/items.csv range=A1:H200 header=true}}`. It must retain the
source Path and Revision/hash in its cache key, cap rows/columns/cell size and
nested macros, and never write rendered HTML back to the Page. RFC 4180-compatible
UTF-8 CSV is the canonical interchange format; ODS is a separate adapter when
multiple sheets, formulas, or styles are required. Malformed or oversized data
falls back to the bounded text adapter.
Slide projection/editor support is also TODO. A Reveal-compatible adapter may
host HedgeDoc or Slidev behind an explicitly configured origin, CSP, read-only
preview, and explicit import/save operation. A CSS-only editor using scroll-snap,
`:target`, and print CSS provides a JavaScript-free fallback. Remote scripts,
imports, and iframe privileges are never inherited from document content.
### 日記拡張の追加要件(初期一覧を実装、移行・コメントは未実装)
日記は主要なシステム拡張として扱い、tDiaryからの移行と日記専用画面を提供する。
- カレンダーウィジェットから年月日を選択。最近の日記と最近のコメントを同じ画面に配置。
個人日記/共有日記、公開/限定公開の範囲を明示し、各ウィジェットも閲覧権限で絞る。
- tDiaryインポートは既存のimport session/journalを再利用し、事前解析・プレビュー・
日付/タイトル/本文/セクション/コメント/添付画像の対応確認、修正、再実行を分ける。
日付・タイムゾーン・旧URLの対応表とインポート元IDを保持し、重複取り込みを防ぐ。
- 対応するtDiary版、データ形式、記法、添付・コメントの実際の形式は、実装着手時に
公式仕様とユーザーのサンプルで確認する。Rubyファイルやプラグインをeval/実行せず、
宣言的な安全な読み取りと変換のみを行う。対応範囲外はスキップ理由を表示する。
- 移行コメントは元の著者名・日時を出典として保持し、認証済みローカルユーザーによる
投稿と偽って結び付けない。非公開内容の公開、HTML由来XSS、通知の大量送信を防止する。
- 順序は日記モデル+カレンダー/最近の日記 → コメント基盤との接続+最近のコメント
→ tDiary取り込みの縦切り。実データを使う前に小規模fixtureでドライランと再実行を検証。
以下の共通outboxは日記・コメントの通知や一覧projectionにも利用する。
Pageの正本更新と `domain_event_outbox` へのイベント挿入を同一transactionで行う。
型は `page.created.v1`, `revision.saved.v1`, `path.renamed.v1`, `page.deleted.v1`,
`comment.created.v1`, `reaction.changed.v1` など。actor、domain、Page/Revision UUID、
domain sequence、payload version、idempotency keyを含める。本文を無条件に複製しない。
subscriberごとにcheckpointを持ち、at-least-once配送に対して冪等に集計する。
最近編集・ランキング・通知をPage表示ハンドラから同期再計算しない。
イベント実行は `/_/api/v1/event/`、キュー状態は `/_/api/v1/queue/` を引き続き利用する。
拡張API案は `/_/api/v1/extension/{id}/{operation}`。実装時はoperationごとにtyped policyを
登録する。未知ID/operationをgeneric proxyしてはならない。
閲覧イベントは正本更新ではないため、dedupe/rate limit付きの軽量batch ingestionを
分離する。ランキングには匿名化集計を用い、個人閲覧履歴を無期限に保存しない。
## Kill switch とリソース観測(設計・実装方針)
各Domain/instanceの `system_extension_states` に拡張IDごとの有効状態を保存し、未登録は有効と解釈する。設定画面または `POST /_/api/v1/extension/` の `{id, enabled}` で切り替え、反映は次の要求・次のジョブから行う。無効化はデータを削除せず、対応画面は安全な404または組み込みfallbackを返す。CLIにも `pageswiki-cli extension [ID] [on|off]` を用意し、DBのWeb UIが利用できない障害時にも切り戻せるようにする。
システム拡張と連携アダプタは、jobのextension ID、開始・終了時刻、CPU時間、最大RSS、読み書きバイト、待ち時間、出力件数、エラー/キャンセルを共通の実行メトリクスへ記録する。foregroundのProjectionはrequest IDとadapter IDをログへ付け、background処理はイベントキューのbounded jobとしてリソース画面へ集計する。上限超過・連続失敗・queue滞留は拡張単位で通知し、ページ表示のレイテンシーを拡張処理が奪わないことをDone条件にする。
## 次の実装順序と受入条件
以下は追加機能同士の順序。先に [実装状況の是正順序](implementation-status.md#ordered-next-work)
にある認証・更新整合性・重い要求処理の是正を通す。監視画面統合の次の最初の是正として、
ownerの通常更新による降格防止と、並行削除時の最後のowner保持を実装済み。
1. 今回:ビルトインcatalog、管理パネル、監視イベントと履歴、レスポンシブなカード。
2. outboxと監査actorの統一、domain/principal別の最新編集projection。transaction rollback、
rename追従、失効権限での非表示をテスト。これを最初の追加システム拡張にする。
3. diary(カレンダー・最近の日記・tDiary移行設計)と時刻/OS条件テーマ。
最近のコメントは次のコメント基盤に接続。日没計算はtimezone/DSTと位置情報同意を検証して追加。
4. reactions・ランキング・コメント。モデレーション、消去/保持、通知契約を先に固める。
5. Linkdingのread-only同期、明示操作の外部検索リンク、続いて各Wiki API connector。
6. S3 Document Store、WebDAV/SSHのread-only collection、SNMP collectorを独立スライスで実装。
7. 外部パッケージの署名・分離runtime・secret store・権限制限・upgrade/rollbackを備えてから
第三者プラグインのインストールを公開する。
全スライスでdomain越境拒否、再実行の冪等性、入力/応答上限、キャンセル、負荷上限、
秘密の非表示、停止時の既存Wiki表示への無影響を確認する。未実装機能を有効ボタンだけで
動作済みに見せない。ロードマップの完了チェックは縦断した機能単位で付ける。