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.
19 KiB
システム拡張の詳細設計
境界と今回の実装
連携アダプタは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登録型。 実装範囲と後続タスクを参照。
これは外部プラグインローダーではない。任意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にアクセスする。
ビルトインのリソース監視
収集と履歴の期間・保持ルールは Seheweit に初期分離済み。 serverが認可とキュー状態を扱い、storeが保存する。URI・schema・監視周期は変更しない。
- 定義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索引で期間を絞り、バケット内の最後に挿入されたサンプル(MAX(id))を返す。 時刻が逆転した入力では最大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仕様
に従うストレージ層の計上値。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条件にする。
次の実装順序と受入条件
以下は追加機能同士の順序。先に 実装状況の是正順序 にある認証・更新整合性・重い要求処理の是正を通す。監視画面統合の次の最初の是正として、 ownerの通常更新による降格防止と、並行削除時の最後のowner保持を実装済み。
- 今回:ビルトインcatalog、管理パネル、監視イベントと履歴、レスポンシブなカード。
- outboxと監査actorの統一、domain/principal別の最新編集projection。transaction rollback、 rename追従、失効権限での非表示をテスト。これを最初の追加システム拡張にする。
- diary(カレンダー・最近の日記・tDiary移行設計)と時刻/OS条件テーマ。 最近のコメントは次のコメント基盤に接続。日没計算はtimezone/DSTと位置情報同意を検証して追加。
- reactions・ランキング・コメント。モデレーション、消去/保持、通知契約を先に固める。
- Linkdingのread-only同期、明示操作の外部検索リンク、続いて各Wiki API connector。
- S3 Document Store、WebDAV/SSHのread-only collection、SNMP collectorを独立スライスで実装。
- 外部パッケージの署名・分離runtime・secret store・権限制限・upgrade/rollbackを備えてから 第三者プラグインのインストールを公開する。
全スライスでdomain越境拒否、再実行の冪等性、入力/応答上限、キャンセル、負荷上限、 秘密の非表示、停止時の既存Wiki表示への無影響を確認する。未実装機能を有効ボタンだけで 動作済みに見せない。ロードマップの完了チェックは縦断した機能単位で付ける。