Files
pages/docs/design/ja/extensions.md
T

68 lines
8.8 KiB
Markdown
Raw 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.
# 11. システム拡張・通知・協働
状態:信頼済みビルトインcatalogと設定入口あり。任意第三者コードのロードは未実装。
## アダプタとシステム拡張
アダプタは特定Documentを開く・編集する役割、システム拡張は活動、通知、コメント、予定、メール、RSS、検索provider等のサービスです。外部サービス連携用URLに汎用管理権限を押し込めません。
現行catalogは `/_/api/v1/extension/`、個別操作は `/_/api/v1/extension/{id}/…` の系統です。catalogに載っても任意コード実行や権限付与は許可されません。
## 共通manifest案
安定ID、版、互換範囲、scope、設定schema、必要capability、outbound host、secret reference、購読event、checkpoint、実行image digest、署名、CPU/メモリ/時間/出力制限を宣言します。
設定はinstance / Domain / Principalを区別します。ホスト所有のフォームを基本にし、独自UIはsandboxと型付きメッセージに限定します。無効化はデータ消去と別操作です。export、移行、rollback、孤立データの保持期間を必須契約にします。
## 協働機能の正本
| 機能 | 保存するidentityと状態 | 漏えいさせないもの |
| --- | --- | --- |
| 最近編集 | event、actor、Page/Revision、Domain sequence | 現在読めないPageのタイトル |
| 最近閲覧 | 本人の閲覧履歴と保持期限 | 他者の私的な閲覧履歴 |
| いいね・ランキング | Page、反応者、期間集計、計算版 | 非公開Pageの順位や件数 |
| 品質評価 | rubric版、評価者、対象Revision、根拠 | 機械評価を人の決裁と偽る表示 |
| inline comment | Revision、範囲、周辺hash、孤立状態 | 改訂後の別文章への誤結合 |
| コメントthread | Page、投稿・編集履歴、moderation | 削除・権限失効後の本文 |
| 通知Inbox | event、受信者、配送・既読 | 保存時点の権限で固定した本文 |
通知を開く時点で権限を再評価します。権限を失った相手へ昔のタイトル付きメールを新規送信しません。送信済み外部通知の撤回不能性は別途表示します。
## 外部検索・埋め込み・テーマ
ローカル検索にない場合も、検索語を自動でGoogle等へ転送しません。宛先と送信語を示して選択させます。GROWI、PukiWiki、他PagesWikiは個別API契約・資格情報・上限を確認します。
Spotify/YouTube等のwidgetはprovider許可と同意プレースホルダを使います。文書内の任意scriptを実行しません。時間・日没によるテーマは型付き条件とCSS theme IDを扱い、位置情報を無断取得しません。
## ネットワーク・資産管理拡張(設計TODO)
IPアドレス管理(IPAM)、DNSゾーン/レコード管理、機器・ソフトウェア等の資産管理は、通常のWiki本文を直接書き換えるアダプタではなく、監査可能なシステム拡張として設計します。正本はそれぞれ `network_prefix`、`dns_zone`/`dns_record`、`asset_item` の型付きエンティティとし、説明・手順・添付資料だけをPage/Assetへの参照で持ちます。
| 拡張 | 最初の範囲 | 外部副作用と権限 |
| --- | --- | --- |
| IPAM | prefix、address、予約・割当、重複検査、CIDR表示 | read/writeを分離し、割当変更は承認と監査を必須化 |
| DNS | zone、record、TTL、所有者、検証済みtarget、差分 | zone単位の管理者、DNS providerへのapplyはdry-run→承認→idempotent apply |
| 資産 | asset、serial、owner、場所、状態、保証・関連Page | 個人情報・秘密値を本文や検索snippetへ出さず、履歴と廃棄を保持 |
外部DNSやCMDBへ接続する場合も、secret reference、許可origin、rate limit、最終同期時刻、providerのrevision/etagを保存します。DNSの名前解決やIPスキャンをページ表示中に実行せず、イベントキューのbounded jobにします。削除・再利用・移管はsoft deleteと競合検知を経てから行い、失敗時は外部状態と内部状態の差分を通知Inboxへ送ります。API候補は `/_/api/v1/extension/network.ipam/*`、`network.dns/*`、`inventory.assets/*` とし、schemaが固まるまで実装しません。
## CSV/表・スライド拡張(設計TODO)
初期CSV macroは実装済みです。`{{csv:/data/items.csv range=A1:H200 header=true}}` を認証済みProjectionで展開し、`rev=` で同じObjectのRevisionへ固定できます。現在のPath閲覧権限を毎回検査し、外部URL、匿名公開、asset指定、共有キャッシュはこの段階に含めません。入力256 KiB・UTF-8、表示200行×32列、走査2,000行・100列、セル16 KiB、Projection当たり4種類のCSVまでに制限します。引用符・改行・BOMに対応し、セルはHTML escapeしてmacroや数式を実行しません。処理不能時は内容を漏らさない警告に置き換えます。Authoringでは元のmacroを保持します。
既存CSVの編集は `/e/-/{path}` の組み込みエディタで行います。デスクトップはソースと表を並べ、700px以下では表を全幅表示してソースへ切り替えます。セル編集、行・列追加/削除、20操作までの表のUndo/Redoに対応。表は200行・32列・セル16 KiB以内を25行ずつ描画し、先頭行を自動でヘッダ扱いしません。矩形でない行の欠落セルを勝手に保存せず、列追加時だけ明示的に空セルを補います。全体256 KiB・UTF-8以内を対象とし、超過・不正形式の表を部分編集可能にして保存することはありません。表上限を超えても全体上限内ならソースで編集できます。
CSV正本をHTMLへ変換せず、未変更fieldの引用符、BOM、混在LF/CRLFを保持します。セル内のHTML、macro、数式は実行しません。表編集も既存の下書き・認証切れ検出・言語別Revision CAS・履歴復元を使用し、他の保存と競合したCSVは文字列の自動マージをせず比較画面へ送ります。原文と編集済み表の両方を別正本として保存しません。DBスキーマ変更はありません。CSV新規作成ウィザード、TSV/文字コード変換、大容量表のwindow編集、複数セル貼付、列型/数式、ODSは残件です。
CSVをPage本文へ複製せず、認可済みの別Documentをテーブルとして投影します。共有キャッシュを将来追加する際は、Path、Revision(またはasset hash)、列・行上限、表示モードと権限を考慮します。macroは表示時にboundedなProjectionを作るだけで、結果HTMLを正本へ逆流させません。CSV Editorは元Revisionを編集し、表投影とは別の操作・競合・権限として扱います。
交換形式はRFC 4180互換CSV(UTF-8、CRLF、引用符・改行を含むfield、BOMの扱いを明示)を第一正本とします。複数シート、型、数式、結合セル、書式が必要な場合はODSを別アダプタ/Assetとして扱い、CSVへの不可逆変換を黙って行いません。行数、列数、セル長、総バイト、ネストmacroを制限し、malformed inputは安全なテキスト表示へfallbackします。
スライドは、Markdown/HTMLの正本からReveal.js互換のProjectionを生成する連携アダプタを設けます。HedgeDoc、Slidevは外部originのホスト型アダプタとして、保存・公開・ユーザー情報をPages Wikiの権限へ自動昇格させず、read-only preview→明示的なimport/saveの順にします。JSを使用できない環境向けには、CSS scroll-snap/`:target`/print CSSだけでページ送りできるCSS-only Slide Editorを別実装します。外部ランタイム停止時は静的HTML/Markdownへ安全にfallbackし、任意script、remote import、iframe権限を本文から許可しません。
ネットワーク図ではnwdiagを追加候補とします。ソースをbounded parserで検証し、renderer version/theme/document hashをキーに静的SVGをキュー生成します。include、外部画像・font、未知directive、危険なSVG属性は拒否し、renderer停止時はescaped sourceまたは最後に検証済みの静的画像へfallbackします。編集アダプタの保存はone-use ticketと楽観的Revision競合を使い、Kroki経由の場合もorigin、timeout、quotaを明示します。
## 最初に作る共通部
outbox、actor provenance、現在権限で絞るprojection、設定のsecret参照、connectorの予算と再試行、export/削除です。機能別に通知・認可・秘密管理を作り直さないことを次章以降の前提にします。