自動再接続

WebSocket などのリアルタイム通信で発生する接続断に対し、自動的に再接続を試みる機能を提供します。一定のロジックに基づいて再接続を行い、成功・失敗のイベントを発行します。

autoReconnect 関数は、AutoReconnect クラスのインスタンスを作成し、再接続機能を利用できるようにします。

インポート

import { autoReconnect } from "@tai-kun/surrealdb";

構文

function autoReconnect(
  db: Client,
  options?: AutoReconnectOptions
): AutoReconnect;

引数

`db`

Surreal クラスのインスタンスオブジェクトです。

`options`

再接続の設定を指定するオプションです。再接続間隔、最大遅延時間、再接続の条件などを指定できます。デフォルト設定を使用する場合は省略可能です。

backoffLimit?: number: 再接続を試みる最大回数を指定します。デフォルト値は Infinity です。
initialDelay?: number: 最初の再接続を試みるまでの遅延時間（ミリ秒）です。デフォルト値は 500 です。
maxDelay?: number: 再接続の遅延時間 (ミリ秒) の最大値です。バックオフが進むと遅延が増えますが、この値が上限となります。デフォルト値は 30_000 (30 秒) です。
shouldReconnect?: { ping?: { threshold: number; perMillis: number }} | (error) => boolean: 再接続を行う条件を指定します。関数として指定した場合は、エラーイベントの引数をもとに再接続を実施するかどうかを判断します。

返値

AutoReconnect クラスのインスタンスを返します。このインスタンスは再接続の制御や状態の取得、イベントの監視などに使用できます。

.getReconnectionInfo(): ReconnectionInfo

現在の再接続情報（.state と .phase）を取得します。それぞれ次の意味を示します:

.state:

"waiting" … 初期状態。再接続は 1 度も行われていません。
"running" … 再接続中です。
"success" … 再接続に成功しました。
"failure" … 再接続に失敗しました。

.phase:

"waiting" … 初期状態です。再接続は 1 度も行われていません。
"pending" … 再接続が要求され、実行するまで一定時間待機しているところです。
"disconnecting" … 切断中です。
"connecting" … 接続中です。切断に失敗しても接続しようとします。
"succeeded" … 再接続に成功しました。
"failed" … 再接続に失敗しました。

state	phase
`"waiting"`	`"waiting"\|"pending"`
`"running"`	`"disconnecting"\|"connecting"`
`"success"`	`"pending"\|"succeeded"`
`"failure"`	`"pending"\|"failed"`

.enable(): void: 再接続機能を有効化します。このメソッドを呼び出すことで、再接続が行われるようになります。デフォルトで有効になっています。
.disable(): void: 再接続機能を無効化します。このメソッドを呼び出すと、再接続が無効化されます。
.reset(): void: 再接続カウンタをリセットします。これにより、再接続のバックオフロジックが初期化されます。
.enabled: boolean: 再接続機能が有効かどうかを示す真偽値です。true の場合、再接続が有効です。

例

import { autoReconnect, Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
const ar = autoReconnect(db, {
  initialDelay: 1000,
  maxDelay: 30000,
  backoffLimit: 5,
  shouldReconnect: {
    ping: {
      perMillis: 60000, // 1 分以内に、
      threshold: 3,     // 3 回以上 ping に失敗した場合、再接続する。
    },
  },
});

ar.on("pending", (endpoint, duration) => {
  console.log(`${duration / 1000} 秒後に ${endpoint} へ再接続します...`);
});

ar.on("success", (endpoint) => {
  console.log(`${endpoint} への再接続が成功しました 🎉`);
});

ar.on("failure", (endpoint, cause) => {
  console.error(`${endpoint} への再接続に失敗しました 🤯`);
  console.error("原因:", cause);
});

try {
  await db.connect("ws://127.0.0.1:8000");

  // 長時間に渡って実行される様々な処理

} finally {
  await db.disconnect();
}

注意

再接続のロジックは、WebSocket 接続の安定性や接続回復の頻度を適切に調整するために重要です。オプションの設定は、システムの要件や使用ケースに応じて調整する必要があります。
autoReconnect は接続が失われた際の回復を試みるものであり、すべてのケースで完全な回復が保証されるわけではありません。