Files
pages/docs/design/diary-blog-plugins.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

24 KiB
Raw Permalink Blame History

日記・ブログ:ビルトインシステム拡張

初期版 0.1/URL・入口拡張(2026-09-17)。MIME連携アダプタではなく、通常のWiki Pageに 付随する日付・記事情報とナビゲーションを提供する。任意の外部コードをロードする プラグイン機構ではない。

実装した範囲

日記 ブログ
ID content.diary content.blog
UI /v/diary /v/blog
設定 /-/sys/config?panel=diary /-/sys/config?panel=blog
一覧 月別/日付別 日付降順、任意の月・カテゴリで絞り込み
ナビゲーション 月カレンダー、最近8件、自分の記事 月カレンダー、最近8件、カテゴリ、自分の記事
登録制約 同日複数件可 同日複数件可

両方ともDomainごとに既定無効。Domain管理者が有効化する。無効化しても 登録情報、Wikiページ、Revisionは削除しない。

「新規記事」ダイアログは日付・keyword・タイトル・カテゴリ・Markdown本文を まとめて保存する。既存Pageを使う場合は従来のPath指定による登録も可能。 本文の継続編集は既存エディタ、記事情報の変更・登録解除は一覧から行う。

同一インスタンスのDomain射影(第一段階)

  • ドメイン一覧の歯車内で日記・ブログそれぞれの参照元DomainとPath prefixを指定。 空の参照元は従来の自Domain記事を表示する。入口形式・有効状態は上の設定で指定する。
  • periodical_projections(domain_uuid,kind,source_uuid,prefix)で参照のみ保持し、 Page、Revision、Path、記事情報は複製しない。既存の表示先記事も削除しない。
  • Campus管理者による設定に限定。同じCampus(同じコントローラの管理単位)の 有効なlocal配置Domain同士のみ許可。managed Campus上のローカル設定変更は禁止。 自己参照・連鎖・循環を拒否し、閲覧時にも有効状態・配置・所属・連鎖を再検査する。
  • 初期射影範囲は認証済みの一覧・月/日カレンダー・カテゴリ・最近の記事・own。 参照元・表示先の双方の読取ポリシーとprefixで絞り、件数/カテゴリ/ページ送りを その後に計算する。ソース権限は一括読込し、記事ごとのSQL認可問い合わせはしない。 Source側がlegacyモードでも、射影では明示的な読取権限を要求する。
  • 匿名の場合も、設定済みのlocal射影先の / と /v/{kind}/YYYY/MM[/DD] を 閲覧できる。参照元の現在有効な公開承認済みPath/Revisionだけから一覧・件数・ 最近の記事を構成する。日付は承認済み {prefix}/YYYY/MM/DD[/keyword] Path、 登録タイトルはPageの公開状態を継承する公開表示情報とする(2026-09-19変更)。 現在有効な公開承認のあるPageのタイトルだけをJOINで取得し、タイトル変更は 次の要求で反映する。カテゴリ・著者・登録日付は公開しない。タイトル未登録なら 最新20記事に限り承認済みHTMLのh1を64KiB以内で読み、なければ日付/Path末尾。 不正/期限切れの認証情報は匿名へ降格しない。公開変更/失効は次の要求で反映する。 記事本文の公開権限を増やさず、未承認の最新Revisionを公開しない。
  • 表示先の認証セッションでPrincipalを特定する。参照元の同じPrincipalに読取権限が 必要。クロスサブドメインCookie共有やセッションの暗黙継承は実装しない。
  • 専用ドメイン(入口形式がblog/diary)では記事リンクを表示先の /YYYY/MM/DD[/keyword] とし、承認済み本文を同じホストで表示する。 カレンダー・同月の他の記事(最大31件)・前後の記事を同じ公開集合から構成する。 サイト名称・テーマは表示先Domainのもの。記事本文は既存のinert HTML境界を使う。 本文中の既知の公開記事リンクも表示先へ変換し、それ以外は参照元URLを保持する。 画像のCSPは設定済み参照元originだけ追加許可し、画像自体の公開権限は拡張しない。 「参照元で閲覧・編集」は従来通り元FQDNへ移動する。作成・登録・更新・解除の APIを射影先で使うと403。Store transaction側でも射影設定を再検査して拒否する。
  • entries APIはsource_domain・source_origin・projectionを付加する。 Path/Page UUIDは参照元のもの。日付ナビゲーションは表示先の /v/{kind}/...。 日付既定値は参照元Timezone、テーマ・名称は表示先Domainの設定。
  • 一覧は毎回DBから読み、private, no-store。ACL失効・元記事変更は次の要求で反映。 参照先が無効/remote配置/別Campusへ変わった場合は503で閉じ、自Domain記事への 黙った切り替えはしない。同期や既存公開承認をこの参照設定で拡張しない。
  • この参照設定は現時点ではローカル専用でmanifest v2には含めない。 別インスタンスへの参照設定配信・認証付き取得・失効・ タイトル以外の匿名メタデータ公開・SSOは後続。従って「同じコントローラなら任意の配置先で射影」 までを実装済みとはしない。
  • 専用ドメインの /rss.xml はRSS 2.0、最新20記事のタイトル・正規リンク・GUID・ Revision日時と、content:encoded の安全化済み本文HTML(CDATA)を配信する。 本文取得前に正確なRevision公開承認を再確認する。記事リンク・ページ内リンクは 表示先の絶対URL、画像やその他の参照元リンクは元ドメインの絶対URLに変換する。 上限は1記事1MiB入力、本文合計8MiB、生成処理5秒。上限超過は503とし、黙って 本文を切り捨てない。HEADは本文を生成しない。非公開登録情報は含めない。絶対URLは登録FQDNから 作り、Hostヘッダー由来のfeed汚染を防ぐ。HTMLにRSS autodiscoveryとRSSリンクを設置。 毎回公開承認を確認し、HTTP共有キャッシュは使わない。ただし購読者が既に取得した RSSや本文のコピーは、公開撤回しても遠隔削除できない。

原子的な新規投稿のAPI

  • /v/blog/-/new、/v/diary/-/new は認証必須の独立した新規記事画面。 Domain timezoneの日付・keyword・カテゴリ・Markdown本文を既存posts APIへ送る。 作成/Pathの権限はAPI内のtransactionで検証し、保存だけでは公開承認しない。 未有効のプラグインは404、射影先は参照元の同ルートへ303で案内する。 GETで記事やPathを作成せず、POSTはこの画面URLでは受けない。

  • 投稿完了画面にXのWeb Intentリンクを表示し、ユーザのクリックでのみXへ移動する。 サーバーからの自動投稿・外部SDK・OAuth資格情報の保持は行わない。 posts応答のshare_targetsは有効な同Campus/local射影先と入口設定から生成する。 ブログ専用ドメインの /YYYY/MM/DD[/keyword] を優先し、複数なら選択式。 射影設定があるのに利用可能な共有先がなければ、元ドメインへ黙って切り替えない。 publishedは公開承認の検査結果。未公開なら警告とクリック時の確認を出す。 共有操作で公開承認は変更しない。公開記事ページにはタイトル・canonical URLの OGP/Xカードメタデータを出す(カードの表示や更新時期は外部サービス側に依存)。

  • POST /_/api/v1/extension/content.{diary|blog}/posts:request_id(UUID)、 title、date、keyword、category、body(Markdown)。未知フィールド拒否。 要求JSON上限320 KiB、変換後HTML上限256 KiB。ブラウザ本文入力上限131072文字。

  • prefixとTimezoneはサーバー設定を使用する。Path・Page UUID・著者の指定は不可。 通常のMarkdownレンダラでHTML化し、通常のRevision挿入関数とasset固定処理を共有。

  • SQLite write予約後にactive membership、ローカル配置、有効状態、create/writeの 両権限、上位Locality制限、現在のprefix、Pathの不存在を検査する。 Page・provenance・Path・Revision・asset参照・記事情報・journal・再送receiptを 同一transactionで確定する。既存Pathは409で拒否し、上書きしない。

  • periodical_postsのDomain/kind/actor/request_idと要求digestで再送を識別する。 同じ要求は既存Page UUIDを返し、変更された要求は409。再送にも現在の権限と Path binding/記事登録の存続を要求し、削除後の再送で復元しない。

  • Document Storeのimmutable blobはcommit前に書き込む。DB rollback時には 未参照blobが残り得るが、Page・Revision・Path・記事索引は可視化されない。 未参照blob回収とreceipt保持/GCの統合は後続。プロセス内revision書込ロックを共有。

  • 本文保存は公開承認ではない。匿名の本文・記事情報・日付・件数を追加公開しない。

  • 日付付き一覧へ遷移して保存結果を表示する。ダイアログ内の入力は送信失敗時に 保持し、同じrequest_idで再試行する。ブラウザ永続ストレージには下書きを保存しない。

  • Search/公開失効など既存DB triggerは共通Revision/Path挿入で適用される。 City自動生成・通知への共通outbox配送は依然として後続(journalだけで配送済みとしない)。

記事URLとドメイン入口(2026-09-17)

  • 設定画面の日記/ブログパネルにDomain・kind単位のprefixを追加。既定値は /diary・/blog。/も指定可能。設定変更は既存Pathを移動しない。
  • 「新規ページ」は日付・任意keywordを指定するダイアログを開く。 {prefix}/yyyy/mm/dd または {prefix}/yyyy/mm/dd/{keyword} をサーバーで 検証し、書き込み権限とPathの不存在を確認してエディタへのリンクを返す。 日本語keyword可。keywordは単一要素とし、traversal・制御文字・URL区切りは拒否。
  • エディタを別タブで開き、本文保存後に元のダイアログから記事登録へ進む。 この任意の従来フローは二段階操作。新規記事ダイアログでは一括保存できる。 計画APIはPageを作成・予約しない。確認後に別の操作が同じ Pathを作成した場合、既存エディタはそのPageを開くため、排他的な新規作成保証は 専用の原子的投稿APIが提供する。計画APIは自動上書き・自動登録を行わない。
  • keywordなしのPageとkeyword付きの子Pageは同日に共存可能。 idx_diary_owner_dateはschema初期化で削除し、既存データは保持する。
  • Domain設定のトップページ形式に日記/ブログを追加。home_layout=diary|blog は認証後の / で直接一覧・カレンダーを描画する。日付選択は以下のviewer Pathへ 進む。従来の /v/diary・/v/blog は残す。既存home_pathを削除しない。
  • 配置先の表示名を「配置先」に短縮。物理的なInstance FQDN・fingerprintと home_layoutは別設定のままとし、別Domainの記事や権限を暗黙に共有しない。
  • 匿名公開処理は従来の承認済みPage/ディレクトリ表示を維持する。 home_layout設定で記事メタデータを公開しない。設定済み射影の匿名カレンダーは 上記の公開Path/Revision由来データのみで構成する。
  • Domain一覧の歯車「ドメインの入口設定」からトップページ・日記/ブログの有効状態・ prefixを一括指定できる。配置先そのものは既存のDomain更新フォームで指定する。 初回ダイアログは現在の設定値を引き継ぐ。保存後はこのパネルを設定の正本とし、 homeパネル/個別プラグインの設定APIからの競合する更新を拒否する。

コントローラからの配信

  • domain_entry_settings(domain_uuid,settings_json)が明示的な入口設定を保持。 Campus管理者のみ更新可能。外部キャンパス管理下ではローカル更新不可。 設定検証・管理権限確認・保存・ローカル配置への反映は同一transaction。
  • 署名付きCampus manifestにdomain_entriesを追加。明示設定がある場合だけ schema_version=2を使用し、設定のない従来manifestはversion=1のままとする。 入口設定も署名・内容hash・revision更新の対象。対象CampusのDomainのみ含める。
  • 受信時はDomainの所属・Layout列挙・prefix・選択したプラグインの有効状態を検証。 Domain snapshot、入口設定、local配置のhome_layout/periodical設定、受信checkpointを 同じtransactionで更新する。remote配置のDomainには実行設定を有効化しない。
  • 記事本文・記事登録・公開承認・資格情報・任意configは配信しない。 prefix変更も記事移動を発生させない。同一revisionの再送は従来どおり冪等。
  • v2非対応ノードは同期を拒否するため、配置先を先に更新してから入口設定を保存する。 enrollmentでmanifest_version=2と専用のcapability_signatureを送信し、 インスタンス鍵で署名したnormalized FQDN + LF + token + LF + manifest=2を検証する。 従来のenrollment署名も併せて必須。古いクライアントの申告なしはversion=1として扱う。
  • federation_instance_capabilities(instance_uuid,manifest_version)で鍵identity単位に 能力を記録。FQDNが同一でも鍵変更は別の申告・承認が必要。 Campus manifestは全承認済みノードに渡るため、一台でもv2未確認なら入口設定保存を 409で拒否し、ダイアログにも案内を表示する。受信側は従来どおり署名・versionを検証し、 設定を削ったv1へ黙ってフォールバックしない。
  • capabilityは対応機能の申告であり、稼働状態・実際の反映完了の証明ではない。 enrollment更新時に申告がなくなればversion=1へ戻す。署名は既存enrollment同様 token期間中のproofでありnonce付きの鮮度証明ではない。反映ACK/鮮度管理は後続。
  • manifestで設定が省略された場合は設定解除を意味しない。既存設定を保持する。 現段階では管理を解除する操作はなく、Wiki形式への変更・各プラグインの無効化も 入口設定パネルから明示的に行う。削除Domainの設定保持/GCは後続。

日付ナビゲーションの正規URL

  • 月別:GET /v/{diary|blog}/yyyy/mm。
  • 日別:GET /v/{diary|blog}/yyyy/mm/dd。
  • 自分の記事:存在フラグ?own。カテゴリは?category=...、ページ送りは offsetを維持する。組み合わせは?category=Work&own。
  • /v/blogは全期間、/v/diaryはDomain timezoneの当月。
  • 旧month/date/mine=1は認証確認後、302で正規URLへ転送する。 date単独でも対象月を導出する。矛盾する日付、存在しない日付、重複した日付query、 桁数不正は400。未知のHTTPメソッドを許可せず、現段階はGETのみ。
  • カテゴリ/ownは月移動・日付選択・ページ送りで保持する。フィルタフォームの 再適用は日付選択とoffsetをリセットし、指定月(ブログは全期間も可)から表示する。
  • 専用ドメインの / は入口。/yyyy/mm/ddは通常Pageの本文を置けるため、 日付別一覧をそこへマウントしない。月・日への移動は/v/{kind}/...を使用する。
  • 新規投稿計画APIのdateは記事作成パラメータであり、閲覧URLの日付queryとは別。 将来のQUERY対応はTODO。現段階ではルータや認証middlewareに追加しない。

データモデル

  • periodical_settings(domain_uuid, kind, enabled):Domainとプラグイン単位の有効状態。
  • periodical_prefixes(domain_uuid, kind, prefix):投稿先prefix。未設定時はkind別既定値。
  • periodical_entries(domain_uuid, kind, page_uuid, owner_uuid, local_date, title, category, timezone, version):正本はPage UUIDで参照する。Pathは保存せず 閲覧時に現在のbindingから解決する。renameで日付・カテゴリが失われない。
  • periodical_events(id, domain_uuid, kind, page_uuid, actor_uuid, operation, version, created_at_ms):設定/登録/解除と同一transactionで記録する変更journal。 本文・タイトル・資格情報は複写しない。これは共通outbox配送や通知機能そのものではない。

本文はDocument Storeと既存Revisionにのみ保存する。登録解除はメタデータだけを 外し、Pageを削除しない。最後のPathがなくなったPageは一覧から非表示になる。 メタデータの孤立行のGC・完全消去・履歴保持期間は後続の保持ポリシーで扱う。

日付は明示したcivil date(YYYY-MM-DD)であり、UTC時刻への暗黙変換をしない。 作成時のDomain timezoneをサーバーで記録する。設定timezone変更後も過去の記事を 別日に移動しない。未来の日付を指定しても公開予約や時刻による自動公開は行わない。 著者は最初の登録時の認証済みPrincipalで固定し、クライアントのowner指定は信用しない。

権限と公開範囲

  • 登録情報を利用するUI/APIは認証必須。legacyモードでも匿名メタデータ一覧を 許さない。設定済み射影の公開Path/Revision由来一覧は上記の限定例外。
  • 設定変更はactiveなDomain管理者グループのowner/manager。
  • 記事登録・情報更新・解除は対象Pathのwrite権限と上位Locality制限を再検査する。 upload_onlyやread_write_onceだけでは、既存Pageの記事情報を書き換えられない。 既存エディタと同じく、本人の /u/{username} Wiki配下は本人の編集権限で扱う。 この場合もactive membership・実際のidentity・上位Locality制限を検査する。
  • 一覧・カテゴリ・カレンダー件数・最近の記事・ページ送りは、現在のPage閲覧権限で 絞った後に構築する。非公開の別名で先にdedupeして可視Pageを失わない。
  • 登録操作は匿名公開承認ではない。Page本文の匿名公開は従来の正確なRevision承認に 従う。登録タイトルのみPageの公開状態を継承し、それ以外は個別の承認契約が必要。
  • 下書き/公開/予約公開を、この登録テーブルの有無や日付と混同しない。 公開一覧・RSS/Atomには記事メタデータの承認されたスナップショットと失効検査が必要。

変更transactionは最初にSQLiteのwrite予約を取得し、active membership、設定、Pathの Page UUID、write grant、group/locality caps、期待versionを同一snapshotで検査する。 既存記事の変更にはPage UUIDも要求し、renameやPathの再bindを検出する。 削除・再登録後もjournalからversionを引き継ぎ、古い編集要求の再利用を拒否する。 古いversionによる登録更新は409で明示し、上書きしない。同日複数記事は許可する。

APIと負荷上限

/_/api/v1/extension/content.{diary|blog}/{settings|entries}:

  • GET settings:有効状態。POST settings:{enabled: bool}。 GETはprefixも返す。POSTは任意のprefixを受け、有効状態・prefix・journalを 同一transactionで保存する。prefix省略時は既存設定を維持する。
  • GET plan?date=YYYY-MM-DD&keyword=...:認証・有効状態・対象Pathのwrite権限を 確認し、未使用Pathとeditor_hrefを返す。既存Pathは409。POSTは不可。
  • GET entries:現在読める記事のメタデータのみ。
  • POST entries:path,title,date,category,version(新規は0)。更新/解除は page_uuidと現在のversionを付け、解除にはremove:trueを指定する。
  • 未定義メソッド・未知フィールド・複数JSON値は拒否。本文上限8 KiB。
  • UIは20件単位、最近の記事は8件。索引取得は本文を読まない2秒のmetadata query、 最大5,000 binding行/4 MiB。超過時は黙って結果を欠落させず503。 設定・更新transactionは3秒。UIの編集権限評価は表示中の最大20件だけ。
  • 初期版はpermission-filtered keyset pagingではない。大規模サイト向けには上限を 単純に広げず、バッチ権限評価・索引分割・不透明cursorを先に実装する。
  • ブラウザ側に記事や権限を永続キャッシュしない。BFCache復帰時に再読込。 設定パネルは表示された時だけ非同期で読む。fetchは15秒で打ち切る。

次の実装/TODO

  • Page+初回Revision+記事情報を原子的に作成するMarkdown投稿フォーム。 既存の本文保存・asset固定とjournal、冪等再送を実装。
  • 投稿journalから共通outboxへの配送、City自動生成・通知、receipt保持期間とGC。
  • 同一Campus・同一インスタンスの参照型一覧/カレンダー射影と双方の読取権限検査。
  • 承認済みPath/Revision由来の匿名射影一覧・カレンダー。
  • 専用ドメイン内の記事本文、登録タイトル、同月/前後ナビゲーション、RSS 2.0。
  • タイトル以外の登録メタデータの匿名射影承認、別インスタンスの 参照設定配信と認証付き取得・失効、クロスDomain SSO。
  • Domain入口設定ダイアログと署名付きmanifest v2による設定配信・原子的反映。
  • 署名付きcapability申告・全承認済みノードのv2事前確認・UI案内。
  • Domain新規作成フォームとの一体化、設定の管理解除・GC、配信反映ACK/鮮度管理。
  • 残りの記事メタデータの公開承認・Atom。承認ポリシー/Inboxと接続し、 Pageや上位階層の公開範囲を広げない。タイトル変更・公開撤回で即時失効。
  • 本文抜粋、表紙、複数カテゴリ/タグ。
  • 個人/共有コレクション、著者選択、所有者移管/引き継ぎ。
  • コメント基盤と最近のコメント:閲覧制限、モデレーション、削除・通知を共通化。
  • tDiary取り込み:提供サンプルと公式仕様を確認して対応版/形式を固定する。 Ruby/eval/Marshalの任意実行は禁止。既存import session/journalを使い、事前確認、 日付・timezone・旧URL・セクション・添付・コメントの対応、再開・重複防止を実装。 移行著者は出典であり、ローカル認証ユーザーと偽って紐付けない。
  • 共通outbox・保持/export/削除ポリシー・metadata履歴、孤立メタデータのGC。
  • 索引のkeyset pagingと負荷試験、外部拡張の署名・分離runtimeは別途。

検証:登録/更新/解除、同日複数記事、うるう日、write拒否、Domain越境、グループ失効、 rename追従、非公開カテゴリ/件数の漏えい、journal失敗時のrollback、version再利用、 無効化時のデータ保持、厳格JSON、匿名拒否、PC/モバイルでの設定と登録操作。