コア概念
ActivityPlug は、クライアント API が異なるサーバに対して TypeScript・ HTTP・GraphQL・ブラウザ向けの統一契約を提供します。以下の概念は、 ポータビリティが及ぶ範囲とサーバ固有の動作が残る範囲を定義します。
アダプタ
アダプタは ActivityPlugAdapter を実装します。メタデータとして安定した ID、表示名、アダプタ種別、認識するソフトウェアファミリ、静的な capability 判定を提供します。オプションの操作グループは、インスタンス、 アカウント、投稿、タイムライン、検索、メディア、投票、ソーシャル、通知、 リスト、フォローリクエスト、フィルタ、予約投稿、ブックマークフォルダ、 ストリーミングの動作を実装します。
アダプタ ID はすべての公開エンティティ ID とページカーソルの一部です。 変更すると、以前のバージョンで作成された参照が壊れます。製品固有のアダプタは、実際に API 契約をマッピングしていないソフトウェア との互換性を主張してはいけません。
インスタンスと origin
インスタンスとは、Fediverse サーバソフトウェアの個々の配備を指します。 ActivityPlug は https://social.example のような正規 origin で インスタンスを選択します。パス、クエリ、フラグメント、埋め込まれた認証 情報はインスタンス識別子ではありません。
ライブラリクライアントは 1 つのアダプタを 1 つの origin にバインドします。 サーバリクエストにはアダプタと origin のセレクタが含まれるため、単一の ActivityPlug サーバから複数のソフトウェアファミリと配備を対象にできます。
インスタンス検出では NodeInfo、OAuth メタデータ、製品固有のインスタンス エンドポイント、明示的な機能プローブを組み合わせられます。検出リンクは 選択したインスタンスの origin 内に収める必要があります。リモートアクセス には設定済みの origin ポリシとネットワークポリシも適用されます。
セッション
AuthSession は AuthSessionStore の背後に保存された認証情報を指す公開 オブジェクトです。セッション ID、アダプタ、origin、認証方式、スコープ、 capability メタデータ、オプションのアカウント情報と有効期限を記録します。 保存されたアクセストークンやリフレッシュトークンは公開しません。
セッションは発行元のアダプタと origin にバインドされます。別のクライアント ターゲットにセッションを渡すと認証に失敗します。対応する方式は OAuth、 インポートしたトークン、メールチャレンジ、パスキーですが、各アダプタは 自身が実装した方式だけを通知します。
コアパッケージはデフォルトでインメモリの認証ストアと credential リース ストアを使います。サーバには、ブラウザセッション、OAuth state、短期 キャッシュ、ストリームチケット用の追加ストアがあります。再起動後や複数 レプリカ間での継続性が必要な本番配備では、適切な永続性と共有特性を備えた ストアを設定してください。
Capability
capability とはポータブルな動作に対する名前付き判定です。たとえば posts.update や streaming.notifications があります。状態は次の とおりです。
supported: 選択したアダプタと既知のインスタンス契約がその動作を サポートします。unsupported: その動作が利用できない、またはマッピングされていない ことが判明しています。unknown: 得られた根拠ではサポートの有無を確定できません。
判定には理由、ソフトウェアバージョンの制約、受け付ける入力、メディアの 制限を含められます。ActivityPlug は静的なアダプタメタデータ、NodeInfo、 OAuth メタデータ、インスタンスメタデータ、プローブの順に根拠レイヤを マージします。より具体的なレイヤが先行する判定を上書きできます。
capability の確認は UI ヒントではなく、操作上の契約です。クライアント サービスは、契約で許可されていないリクエストを送信せず、必須 capability が unsupported または unknown であれば操作を拒否します。サーバや バージョンによって動作が変わる場合は、実行時に判定を確認してください。
エンティティ参照と不透明 ID
正規化されたエンティティには以下の要素を持つ EntityRef が含まれます。
id: ポータブルな不透明 ID。type: 正規化されたエンティティ型。adapterとorigin: エンティティを所有するターゲット。rawId: アダプタ固有の識別子。- オプションの
rawUrl: リモートリソースの URL。
不透明 ID はアダプタ、origin、エンティティ型、raw ID をバージョン付き エンベロープにエンコードします。分割できない単一の公開値として扱って ください。クライアントはアダプタを呼び出す前に不透明 ID をデコード・ 検証し、別のアダプタ・origin・エンティティ型の参照を拒否します。 rawId は診断や明示的なアダプタ相互運用にのみ使ってください。
正規化されたエンティティはリモートの生データ raw と名前付き extensions も公開できます。これらのフィールドはポータブル契約の対象外 です。
ページとカーソル
リスト操作は nodes と pageInfo を持つ Connection<Node> を返します。 PageInput は after、before、limit を受け付けます。ActivityPlug は PORTABLE_PAGE_LIMIT を超える正の limit を 100 に制限します。
ActivityPlug のカーソルはリモートカーソルをアダプタ、origin、公開操作に バインドします。カーソルを別のタイムライン、操作、アダプタ、インスタンス で再利用できません。アダプタはエンティティ ID からカーソルを生成せず、 リモート API の正確なカーソルを保持する必要があります。リモート エンドポイントが信頼できる continuation セマンティクスを提供できない場合、 アダプタはカーソル入力を拒否するか、該当する continuation 値を省略する 必要があります。
エラー
ポータブルな失敗は ActivityPlugError を使います。code が失敗を 分類し、context がアダプタ、origin、操作、capability、リモートの 詳細を識別します。一般的なカテゴリには検証、認証、未対応の動作、リモート プロトコルエラー、ネットワーク障害、origin ポリシ拒否、リクエスト上限の 超過があります。
code で分岐する前に isActivityPlugError() を使ってください。 メッセージ文字列をパースしてはいけません。UNSUPPORTED_OPERATION は明示的な結果であり、null で代替しないで ください。呼び出し元がサポートされている動作またはターゲットを選ぶ必要 があります。
リモート権限
すべてのリモート操作は RemoteAuthority を経由します。 RemoteAuthority はリクエストを送信先と公開操作にバインドし、credential が origin や表現を越えて送信されるかどうかを制御します。同一 origin への credential 送信は権限に設定された表現に応じて許可 されます。origin をまたぐ credential 送信には、方向を明示した完全一致の 許可が必要です。
ライブラリユーザはリモート I/O の前に権限を明示的に指定する必要が あります。サーバは origin 検査、DNS ピンニング、プライベートネットワーク 制御、リクエスト予算、レスポンス制限を備えた審査済み Node.js 権限を構築 します。ブラウザコードでは createBrowserRemoteAuthority() を使って ブラウザの fetch 境界を明示的に有効にできます。