版が固定されたForm仕様
この版で固定されたURLの規範本文は日本語です。原文を読む。公開はHostやproviderの対応を意味しません。
Edge KV Namespace 0.2.0
このFormは世界各地へ複製される、一つのキーと値の名前空間を表します。値は文字列ではなく、不透明なbyte列です。書込みの複製には遅れがあり、直後の読取りが古い値を返すことがあります。この意味はFormに固定され、Host設定で強い一貫性へ変更できません。SQLiteのschema変更はSQLiteMigrationApplicationが所有します。この仕様はHost API v2用のForm契約であり、公開だけでHostの対応や実装を示すものではありません。
Resourceの作成・取得・更新・削除と管理OperationのHTTP形式はHost API v2に従います。ここでは名前空間固有の入力とWorkerから呼ぶJavaScript機能を定めます。データの読書きはHost管理Operationではなく、Worker内から直接行う非同期Binding呼出しです。
1. 目的と範囲
名前空間はキーから不透明なbyte列への対応を保持します。キーごとに読み書きでき、複数キーをまたぐtransactionや強い整合性はありません。TTLを設定した値は指定時間より後に削除されることがあります。WorkerにBindingを作る場合のJavaScript機能も本Formが定めます。
Formのcanonical URLは https://edge.forms.takoform.com/forms/EdgeKVNamespace/0.2.0/ です。末尾スラッシュを含む完全なURL文字列が識別子です。URLの正規化、リダイレクト、別名で置換してはいけません。
2. 入力と既定値
specは空のJSON object {}だけを受け付けます。フィールドはありません。Form由来の既定値、作成後に変更できるフィールド、Host個別設定はありません。null、配列、未知のフィールドを含むobjectは拒否します。HostのOfferingがある場合も、それはHost API共通の選択であり、specの一部ではありません。
各JavaScript関数の引数・options objectは定義したものだけを受け付けます。キー・prefix・メタデータkeyはUTF-8 byte数、それ以外の文字列上限はUnicode scalar value数で数えます。数値は整数です。
3. 秘密入力
privateInputsはありません。privateInputsにキーを一つでも指定する要求は拒否します。値とメタデータは通常入力であり、秘密情報を格納する用途ではありません。
4. 観測状態、出力、利用可能状態
作成直後はobserved: {}、output: {}、observedAt: nullです。観測後のobservedは次の五fieldをすべて持つobjectです。namespaceExistsとconsistencyはbooleanと"eventual"、残りは整数です。
{
"namespaceExists": true,
"maxKeyBytes": 467,
"maxValueBytes": 26214400,
"maxMetadataBytes": 1024,
"consistency": "eventual"
}namespaceExists:falseは確認済みの不在、observed:{}は未観測です。上限はキー467 UTF-8 byte、値26,214,400 byte、メタデータ1,024 UTF-8 byteです。観測値が上限と違うHostは本Formに適合しません。observedAtは最後に全fieldを確認した時刻で、個々のキーの状態は示しません。outputは常に空objectです。
このFormは利用可能状態を定義しません。名前空間の作成が完了しても、直前の書込みが別の複製先から読めるとは限りません。Hostは複製目標をサポート情報に示せますが、自分の書込みを直後に読める保証にはなりません。
5. 操作と失敗
HostはResourceのcreate、read、update、deleteを実装します。空のspecと異なる更新は副作用前に拒否します。同じ空specのPUTはHost API v2に従う新generation・新Operationとして受理し、名前空間の実在と管理対応を再確認します。HTTP受付と管理OperationはHost API v2に従います。次表の関数はWorkerのJavaScriptから直接呼び出し、個別のHTTP経路や管理Operation IDを持ちません。
作成では空名前空間を一つ作ります。既に存在する名前空間を別Resourceとして初期化または引き継いではいけません。新しいUIDで盲目的に作り直してはいけません。
作成や削除の応答を失った場合、元要求の再送はHost API v2の再試行と保持に従います。保持期間内の同一要求・同一Idempotency-Keyの再送は元Operationを返します。期限後はResource/Operationを照合し、結果不明のまま盲目的に再送してはいけません。Resource GETとOperation GETは観測だけを行い、実行を始めません。
Hostは元の実行先と識別子を使い、バックグラウンドで結果の照合を試みます。結果を安全に判定できない間はreconcilingを維持し、運用者による確定を待ちます。元Operationが非終端の間、同じResourceへの新しいPUT/DELETEを受理してはいけません。
元Operationがfailedで終了した後は、最新generationを指定した新しいPUT/DELETEで同じUIDの状態を収束させます。既知の部分削除は保存した進捗から再開し、対象の不在を確認できれば削除を成功にできます。PUTによる一般的な名前空間の再作成・初期化は保証しません。
readは管理記録と最後に確認したnamespace状態を返します。外部状態を確認できない場合は不在と断定しません。deleteは対象namespaceとその配下データを削除します。WorkerVersionから参照されている間は削除を受理せず409 dependency_conflictを返し、参照元のWorkerVersionを連鎖削除しません。
key/valueのPUT応答が失われた場合、その呼出しにHost管理Operation IDや管理用再送keyはありません。アプリケーションが再試行の効果を決めます。二重書込みを避ける必要がある場合、keyとvalueに応じた条件付けやアプリケーション側の重複防止を用います。
以下の名前はWorker Bindingで呼ぶJavaScript関数名です。すべてPromiseを返し、成功時は表の値で解決します。関数固有の失敗は、nameがerror codeであるErrorによりPromiseを拒否します。引数型やoptionsの形が不正ならTypeErrorです。Host APIのHTTP応答や管理Operation IDは使いません。
| 関数 | 入力（必須を太字） | Promiseが解決する値 | 拒否時のError.name | 再実行と一貫性 |
|---|---|---|---|---|
get | key: 1〜467 UTF-8 byte | ArrayBufferまたはnull | invalid_key, backend_unavailable | 読取専用。どの複製先から読むかによって古い値や不在が返る。 |
getWithMetadata | key: 同上 | {value:ArrayBuffer, metadata?: Metadata}またはnull | invalid_key, backend_unavailable | valueとmetadataは同じ複製先の値。metadata未設定時は省略。 |
put | key, value; options? | undefined | invalid_key, value_too_large, metadata_too_large, backend_unavailable | 非冪等。値を置換。受付側に保存した後、他の複製先への反映は遅れる。 |
delete | key | undefined | invalid_key, backend_unavailable | 冪等。不在でも成功。削除後も他の複製先には古い値が残り得る。 |
list | options? | {keys:[{name:string}], listComplete:boolean, cursor?:string} | invalid_cursor, backend_unavailable | 読取専用。UTF-8 byte辞書順。結果への複製反映は遅れる。 |
Worker Bindingのputでは値に文字列（UTF-8へ変換）またはArrayBuffer/typed arrayを渡します。文字列はUTF-8へ符号化し、ArrayBuffer/typed arrayは指定byte範囲を保存します。値は最大26,214,400 byteです。範囲外はvalue_too_largeです。キーは1〜467 UTF-8 byteで、違反はinvalid_keyです。メタデータは省略または最大64項目のstring mapです。keyは最大256 UTF-8 byte、valueは最大8,192 Unicode文字。RFC 8785 canonical JSONで表したmap全体は1,024 UTF-8 byte以下です。上限超過はmetadata_too_large。メタデータは秘密ではありません。
PutOptionsのexpirationTtlSecondsは省略可能で、省略時は期限なしです。指定時は60〜315,360,000秒。指定時間より後に削除が進みますが、正確な時刻は保証しません。同じキーへのputは値・メタデータ・TTLを置換します。再実行も書込みになるため、応答不明時はむやみに再試行せず、アプリケーション側で効果を判断します。
ListOptionsのlimitは省略時100、指定時1〜1,000件です。prefixは省略時空文字列で最大467 UTF-8 byteです。cursorはHostが発行する不透明な文字列（1〜4,096文字）で、次頁要求へ変更せず渡します。無効なcursorはinvalid_cursorです。listComplete:falseならcursorを含めます。ページ間のsnapshot一貫性はありません。
putのPromiseが解決しても、別の複製先からのgetが新しい値を直ちに返す保証はありません。同じWorkerや同じ場所での自分の書込み直後の読取りにも保証はありません。getとgetWithMetadataは不在時にnullで解決します。listも複製が収束するまで作成・削除を反映しないことがあります。読取りは冪等、書込みは非冪等です。応答不明時の再実行が安全かはアプリケーションが判断します。未知optionや型・形が不正な引数はTypeErrorとして拒否します。正しい型で仕様範囲を外れる要求は表のError.nameを持つErrorで拒否します。
6. 参照、所有、削除
Resourceが所有するのはnamespaceとそのkey/valueです。WorkerVersionはnamespaceをUIDで参照できます。生きたWorkerVersionが参照中なら削除は409 dependency_conflictで拒否し、何も削除しません。参照を持つWorkerVersionをHostが強制削除することもありません。参照がなくなった後のdeleteは対象namespaceと配下データを削除し、別Resourceや別namespaceには触れません。Hostは管理記録と実行先識別子を照合してから操作します。
7. Worker JavaScript Binding
WorkerVersionのkvBindingsからこのResourceを参照すると、Worker内のenv.NAMEに次のオブジェクトを渡します。NAMEはWorkerVersionで宣言されたJavaScript識別子です。参照だけで呼出者やWorkerに新しいHost認可を与えることはなく、HostはWorkerVersion作成・実行時に権限を解決します。以下の関数は本Formの規範APIで、独立したInterface版は持ちません。
type Metadata = Record<string, string>
type PutOptions = { metadata?: Metadata; expirationTtlSeconds?: number }
type ListOptions = { prefix?: string; limit?: number; cursor?: string }
get(key: string): Promise<ArrayBuffer | null>
getWithMetadata(key: string): Promise<{ value: ArrayBuffer; metadata?: Metadata } | null>
put(key: string, value: ArrayBuffer | ArrayBufferView | string, options?: PutOptions): Promise<void>
delete(key: string): Promise<void>
list(options?: ListOptions): Promise<{ keys: { name: string }[]; listComplete: boolean; cursor?: string }>文字列valueはUTF-8へ変換し、ArrayBuffer/typed arrayはそのbyte範囲を保存します。getとgetWithMetadataが返すArrayBufferは複製された値bytesです。PutOptionsは§5のmetadata、expirationTtlSecondsだけを持ちます。ListOptionsは§5のprefix、limit、cursorだけを持ちます。metadata未設定時は戻り値からmetadataを省略します。各field上限は§5に定め、外部の名前付きAPIを追加要件にしません。
8. 未知のフィールドと拡張
spec、JavaScript関数のoptions、および各引数で定義した値以外を拒否します。metadataは文字列keyから文字列valueへのmapだけです。Host API Resource/Operation応答の未知propertyはHost API v2の共通規則に従います。Formの入力や動作を変える場合は別Form URLを公開します。