Persistence

Persistence は、JSON のトラックを、それを通して読まれている間、開発者のストレージに保存し、保存した文書を、書き手が全員去った後でも、読む人に渡します。

パス

{path} は読み手のルートからの相対です。そのプロジェクトのパスは、同じパスをプロジェクトのルートから見たものです。

誰	パス	トラック	中身
読み手	`.persistence/{path}`	`{track}`	`{path}` の `{track}` の保存した文書。JSON スナップショットのトラック: 最初の値は保存した文書か、何も保存されていなければ `null`。その後は保存した版ごと
誰でも	`{path}`	`{track}`	元: JSON スナップショットのトラック
ストレージ	`{STORAGE_PREFIX}{project path}/{track}`		UTF-8 の JSON の文書。保存のたびに置き換える

パスの各段はキーの一つの段になり、制御文字、改行、\、{、}、^、%、[、]、"、<、>、~、#、|、*、?、バッククォートを含む所と、段が . か .. の所はパーセントエンコードします。.persistence/{path} を読むと {path} の中身が分かるので、{path} と同じように許してください。

TypeScript（ブラウザー） · persistence.ts

// Saved JSON through Persistence: notes publishes notes.json, and reading .persistence/notes keeps it
// saved in your storage and gives the saved document first, also after everyone has left.
import { type Connection, json } from 'tablebox.io';

export function write(connection: Connection) {
  const notes = new json.Snapshot.Producer({ track: connection.publish('notes').createTrack('notes.json') });
  return (value: unknown) => notes.update(value);
}

export async function read(connection: Connection, show: (notes: unknown) => void) {
  const saved = await connection.read('.persistence/notes');
  // The first value is the saved document, or null when nothing is saved yet; then each saved version.
  for await (const notes of new json.Snapshot.Consumer({ track: saved.track('notes.json').subscribe() })) show(notes);
}

保存

.persistence/{path} のトラック {track} を読むことが、保存するものを選ぶことです。Persistence は元が出ているたびにそれを読み、変わってから 2 秒後に、変わり続けている間も最低 10 秒ごとに、出した人が去ったときはすぐに保存します。これは出力が読まれている間続き、最後の読み手が去ってから 20 秒で、まだ保存していないものを保存して止まります。読み手の最初の値は、元があってもなくても、保存した文書の全体です。

ストレージ

Persistence は、プロジェクトの環境変数が指す、開発者の S3 互換のバケットに書きます。

変数	意味
`STORAGE_BUCKET`	バケット。必須
`STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY`	認証情報。必須
`STORAGE_ENDPOINT`	`https://` の S3 互換のエンドポイント。設定しなければその地域の AWS S3
`STORAGE_REGION`	地域。設定しなければ `us-east-1`
`STORAGE_PREFIX`	すべてのキーの前にそのまま付ける。設定しなければ空

保存したオブジェクトはふつうの JSON なので、どの S3 クライアントでも読めます。置き換えたオブジェクトは、次に Persistence がそのパスを読み始めるときに渡すものになります。Egress は同じストレージに録り、Aggregation はまとめた文書を Persistence を通して、.aggregation/ で始まるキーに保存します。

失敗

必須のストレージの変数がない: トラックは missing-variable で断られます。変数を設定してから読み直せば動きます。
ストレージが失敗する: 動いている間、間隔を延ばしながらやり直します。最初の値は最初に読めるまで、その後の版は次に保存できるまで待ちます。
STORAGE_ENDPOINT のホストが、インターネットではなくネットワークの中のアドレス（ループバック、プライベート、リンクローカルなどの特別な用途の範囲。IPv6 のアドレスがそれを運ぶ場合も含む）であるか、そこに名前が引ける: トラックは bad-request で断られます。
元が JSON スナップショットのトラックでない: トラックは bad-request で断られます。
インスタンスが止まる: 読み出しは終わり、読み直すと引き継いだインスタンスに届きます。最後の保存より後の変更は、元がまだ出ていればまた保存され、去っていれば（最大 10 秒分）失われます。
元が変わり続けている間に 20 秒誰も .persistence/{path} を読まない: その後の変更は、誰かがまた読んだときに保存されます。

前へ: Aggregation 次へ: Egress