非同期実行とdiscord.dicks

目標は、discord.pyが担うGatewayの接続管理、イベント、コマンド、型付きデータの補助機能、モジュール式の機能グループ、バックグラウンドタスク、REST操作を備えたDicksのBotフレームワークです。この文書は実行時の契約を記したもので、discord.pyのAPI全体や音声機能との完全互換を主張するものではありません。

非同期の境界

純粋な計算は同期処理のままです。入出力を行うホストの呼び出しは非同期で、ソースの順番に完了を待ちます。非同期呼び出しは静的な呼び出しグラフ全体へ伝播し、呼び出し側が誤ってawaitを省くことはありません。この仕組みはコンパイラに実装済みです。1回の呼び出しには引き続き、fuel、ホスト呼び出し数、タイムアウト、割り当て予算の上限を適用します。

イベントの並行実行は明示的に制限する必要があります。Gatewayの制御ループは、遅いコマンドハンドラーから独立してheartbeatと再接続の処理を続けなければなりません。コマンドには、上限付きのキュー、スコープ単位の状態処理の直列化、キャンセル、終了時に処理を完了させる仕組みを使います。無制限のPromise生成、変更可能なアプリケーションオブジェクトの共有、成否が曖昧な書き込みの暗黙の再試行を、既定の動作にはしません。

各層の役割

• 汎用の通信、タイマー、暗号署名の検証、Cloudflareのライフサイクルアダプターはプラットフォームのライブラリで扱います。
• Discordのプロトコル状態、RESTの経路、レート制限のバケット、イベントの復号、コマンドの規則、利用者向けの補助機能はDicksモジュールで扱います。
• BotアプリケーションはDicksのイベント・コマンドモジュールを用意します。機能グループを静的にインポートし、非公開シンボルと検証済みのシグネチャで区切ります。
• 認証情報は明示的に許可した環境バインディングから受け取ります。永続化するGatewayの状態、パッケージのメタデータ、診断、イベントログには含めません。

Gatewayのセッションには、heartbeatの応答の追跡、IdentifyとResumeの判断、切断コードの処理、上限付きの再接続待機、明示的なintents設定が必要です。Discordへの接続は外向きWebSocketなので、サーバー側のWebSocketハイバネーションは使えません。そのためCloudflare用の実行アダプターを本番へ展開する前に、常時接続の費用とライフサイクルを明示的に決める必要があります。

Interactionには、元のタイムスタンプと本文のバイト列に対するEd25519署名検証、時刻の鮮度の検査、3秒以内の初回応答、遅延応答、トークンの有効期間の制限が必要です。REST操作はレート制限のためにレスポンスヘッダーを保持し、明確に拒否された書き込みと成否不明の書き込みを区別します。稼働中のBotの設定とコマンド登録は、それぞれ許可を得た別の運用操作です。

参考資料：discord.py、Discord Gateway、Interactionへの応答、レート制限、Cloudflare WebSockets。