プロジェクトの管理

Manager は PaaS の側を保ちます。プロジェクト、キー、リンク、環境変数、取り外し、閉鎖、使用量、上限です。Console か管理 API で使います。人がやり取りするものは Relay を通り、Manager はその道筋には入りません。

Console

Console には GitHub でサインインし、自分のプロジェクトを、英語か日本語で、デスクトップでもスマホでも見て管理します。プロジェクト、キー、リンク、環境変数の削除、参加者の取り外し、範囲の閉鎖は、どれも先に確認を求めます。

パスとパターンは、API と同じく、プロジェクトのルートからの相対で入力します。

管理 API

API は Manager API のアドレス（リファレンス）の /v1 にあり、本体は JSON です。呼び出しはキーで認証し（Authorization: Basic base64({key id}:{secret})）、そのキーのプロジェクトに働きます。Console はセッションで呼びます。エラーは HTTP のステータスと {"code", "message"} で、bad-request（400。message が誤った項目を示す）、unauthenticated（401）、forbidden（403。キーでプロジェクトを一覧・作成しようとした）、not-found（404。管理していないプロジェクトにも）、internal（500）です。

• Project: {id, name, created, limits: {monthlyBytes, connections}, state}。上限は数か null（なし）。state は running、full、stopped のどれか。id は a–z 0–9 の 12 文字。
• Link: {id, root, publish, subscribe, created}。
• 一覧は古い順（環境変数は名前順）です。DELETE と PUT は本体なしの 204 で答えます。PATCH は渡したものだけを変え、null は上限を外します。パスはそのままの形（ワイルドカードなし）で、プロジェクトのルートからの相対です。空か省いた path はプロジェクト全体です。時刻は UTC の RFC 3339、day は UTC の YYYY-MM-DD で、usage は使用量のある日だけを並べます。

// The management API with a project key: a link, a variable, a limit, a removal, a closing and this month's usage.
const auth = `Basic ${btoa(`${process.env.TABLEBOX_KEY_ID}:${process.env.TABLEBOX_KEY_SECRET}`)}`;
const project = `${process.env.TABLEBOX_MANAGER_URL}/v1/projects/${process.env.TABLEBOX_PROJECT}`;

async function call(method: string, path: string, body?: unknown) {
  const reply = await fetch(project + path, {
    method, headers: { authorization: auth, 'content-type': 'application/json' }, body: JSON.stringify(body),
  });
  if (!reply.ok) throw new Error(`${method} ${path}: ${reply.status} ${await reply.text()}`);
  return reply.status === 204 ? undefined : reply.json();
}

const link = await call('POST', '/links', { root: 'rooms/42', publish: ['{id}/**'], subscribe: ['**'] });
console.log(`link ${link.id} for rooms/42`);
await call('PUT', '/variables/STORAGE_BUCKET', { value: 'my-bucket' });
await call('PATCH', '', { limits: { connections: 1_000 } });
await call('POST', '/removals', { sub: 'mallory', path: 'rooms/42' });
await call('POST', '/closings', { path: 'rooms/41' });
const today = new Date().toISOString().slice(0, 10);
console.log(await call('GET', `/usage?from=${today.slice(0, 8)}01&to=${today}`));

キー、リンク、環境変数

• キー: ID は tb_ と A–Z a–z 0–9 の 20 文字、シークレットは 43 文字で、作ったときに一度だけ表示します。キーはトークンに署名し（接続する）、そのプロジェクトの API 呼び出しを認証します。削除すると、そのキーで受け入れたセッションは invalid-token で閉じます。
• リンク: ID は lk_ と A–Z a–z 0–9 の 22 文字で、リンクが削除されるまで、持つ人をリンクのルートとパターンで受け入れます（接続する）。
• 環境変数: 名前は英字、数字、_ からなり英字で始まる 70 文字まで、値は 16 KiB まで、一つのプロジェクトに 100 個までです。値は設定と置き換えだけで、再び表示されることはなく、名前は更新日時と一緒に一覧されます。Tablebox のプログラムが読みます。

取り外しと閉鎖

• パス X の中で sub S を取り外す: 5 秒以内に、ルートが X かその下にある S のセッションはすべて removed で閉じます。その後、ルートが X の中なら、Relay は取り外し以前に発行された S のトークンと、それより前に作られたリンクでの S の接続を拒みます。後から発行したトークンと後から作ったリンクは受け入れます。同じパスの中で S をもう一度取り外すと、その時刻が進みます。
• パス X を閉じる: 5 秒以内に、ルートが X かその下にあるセッションはすべて closed で閉じます。その後、ルートが X の中なら、Relay は閉鎖以前に発行されたトークンと、それより前に作られたリンクを拒みます。後からのものは受け入れます。X より上をルートにするセッションは残るので、一つの範囲を閉じても、ロビーやバックエンドは動き続けます。
• Tablebox のプログラムは、取り外しや閉鎖の後も動き続けます。プロジェクトを削除すると、そのセッションは closed で閉じ、プログラムはそのプロジェクトを受け持たなくなります。

上限と使用量

月間のバイト数の上限（UTC の暦月の送受信バイト数）と接続数の上限を、それぞれ任意で決めます。バイト数の上限に達すると、プロジェクトは月が終わるか上限が上がるまで stopped になり、プログラムのものも含めてすべてのセッションが limit で閉じ、新しいものは拒否されます。接続数の上限に達すると、数がそこにある間 full になり、新しいセッションは limit で拒否され、開いているものは続きます。上限は、Relay が一回の報告の間隔（10 秒）に運ぶ分と、変更が届くまでの時間の分だけ超えることがあります。

使用量は、プロジェクトと UTC の日ごとに、Relay に出入りしたバイト数、接続秒数、最大同時接続数を、プログラムのセッションも含めて数え、1 分以内に見えるようになります。

Manager が止まっている間

進行中のセッションは続きます。Relay は最後に読んだ状態で、自分を再起動した後も、受け入れ、取り外し、上限を行い、プログラムは最後に読んだ環境変数で動き続けます。Console と API は使えません。取り外し、閉鎖、設定は Manager が戻ってから効き、その間に数えた使用量もそのときに報告されます。

前へ: Ingress 次へ: リファレンス