# システム拡張の詳細設計 ## 境界と今回の実装 連携アダプタは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表示への無影響を確認する。未実装機能を有効ボタンだけで 動作済みに見せない。ロードマップの完了チェックは縦断した機能単位で付ける。