版が固定されたForm仕様
この版で固定されたURLの規範本文は日本語です。原文を読む。公開はHostやproviderの対応を意味しません。
AtLeastOnceQueue 0.2.0
このFormは、Hostが所有する一つのメッセージキューを表します。配信は少なくとも一度で、順序は保証されません。重複と送信順以外の順序での配信があり得るため、利用者の処理は冪等でなければなりません。Host API v2のResourceとして管理します。共通の作成・取得・更新・削除と再送規則はTakoform Host API v2 HTTP APIに従います。特定Hostへの対応、容量、可用性、料金、アプリケーションの稼働を保証しません。
入力
spec は次のフィールドだけを受け付けます。整数は小数や文字列へ暗黙変換しません。
| フィールド | 要件、既定値、範囲 | 作成後の変更 |
|---|---|---|
deliveryDelaySeconds | 任意の整数。省略時のForm既定値は 0 秒（遅延なし）。0..43200。各送信で別の遅延を指定した場合はその送信値が優先されます。 | 変更できます。更新は以後に受理するメッセージの既定遅延だけを変更し、すでに受理したメッセージの時刻を変更しません。 |
messageRetentionSeconds | 必須の整数。Form既定値なし。60..1209600 秒。キューがメッセージを保持する最大期間です。 | 変更できます。更新は以後の保持判定に適用します。既に期限切れとなったメッセージを復元しません。 |
{
"deliveryDelaySeconds": 0,
"messageRetentionSeconds": 86400
}秘密入力はありません。空でない privateInputs は拒否します。spec の未知のフィールドも拒否します。
producer Bindingとメッセージ
WorkerVersionはこのQueueをJavaScript producer Bindingとして参照できます。Bindingの実行時呼出しは下記のWorkerVersion 0.5.0 producer Binding契約に従います。キューを受け取るWorkerのイベントとバッチsettlement APIはModuleWorker 0.3.0 runtime契約およびQueueConsumer 0.3.0に従います。
成功した send / sendBatch は受理・永続化を意味し、消費済み・処理済みを意味しません。配信は後続し、重複し、送信順と異なる順序になり得ます。messageId は1〜256文字のキュー内で一意な不透明値で、再配信中は変わりません。timestampMillis はHostが受理したUTC時刻のUnix epochミリ秒で、再配信中も変わりません。attempts は1以上の整数で、初回が1、再配信ごとに1増えます。
キューあたりのQueueConsumerは最大1つです。複数Consumerが同じストリームを別々の再試行・dead-letter方針で分割しないよう、Hostは2つ目を拒否します。接続先の許可はResource参照だけから推定せず、producer Bindingのすべての呼出しを実行主体に認可します。
観測、出力、利用可能状態
observed はHostが最後に確認したキューの存在を表し、確認できた場合は queueExists: true、存在しないことを確認した場合は queueExists: false を含みます。初回の観測前や外部状態が不明な間は {} とし、未確認を空キューや不在として扱ってはいけません。任意の messageCount は0以上の整数で、観測時点にHostが把握した件数の概数です。これを将来の配信量、厳密な在庫、処理完了の証明として扱ってはいけません。
{
"queueExists": true,
"messageCount": 12
}このFormの output は常に {} です。キューResourceの操作が成功しても、Consumerの存在、メッセージ処理、外部サービスの健全性や到達性を保証しません。このFormはアプリケーションの利用可能状態を定義しません。
操作、失敗、復旧
- 作成: v2の認可、名前、入力、Offering、参照の検証後にキューを一つ作成します。同じHost/SpaceのResource名衝突、無効な値、容量や実行先の拒否は副作用前に返します。キュー作成後に応答が失われた場合、Hostは操作IDと作成対象を永続化し、再起動後も同じOperationを照合します。作成結果が不明なら
effect:unknownのままreconcilingし、別キューを盲目的に作りません。 - 取得: Resourceの管理記録と最後に確定した観測を返します。GETが配信や再送を開始することはありません。削除済みResourceのHTTP結果は共通Host APIに従います。
- 更新:
spec全体置換として設定を更新します。既定遅延の変更は既に受理したメッセージを書き換えません。保持期間は受理時刻を起点にし、現在の設定を未配信メッセージに適用します。すでに期限切れとして破棄されたメッセージは復元しません。Hostは外部状態とのずれを同じResource UIDで収束させます。 - 削除: キューとそのメッセージをこのResourceの所有範囲として削除します。Queueを
queueまたはdeadLetterQueueとして参照するQueueConsumer、またはqueueProducerBindingsからこのUIDを参照する未削除WorkerVersionがあればdependency_conflictとして削除を拒否します。未選択Versionも参照を保持するため削除を妨げます。ConsumerやWorkerVersionを暗黙に削除しません。キューとメッセージが既に無いことを確認できた場合は削除完了です。
送信の結果が不明なWorkerは、同じ論理送信を新しいBinding呼出しとして繰り返すのではなく、Promiseの結果とアプリケーション固有の重複排除を用います。Host APIのIdempotency-KeyはCRUD Operationの再送を識別し、producer Bindingの send を一般的なexactly-once送信へ変換しません。Host再起動後もキューの受理記録と配信義務を復元し、未確定のメッセージを破棄済み・未受理と推定しません。外部キューの結果を照合できないときは、未知の効果として停止・報告します。
最大保持期間経過後の未配信メッセージは破棄されます。配信不能、保存上限、基盤障害はHostが明示する失敗です。部分変更があれば effect:partial、副作用が無いと確定した場合にだけ effect:none を返します。応答待ち時間超過や再起動だけを理由に none としてはいけません。既知の部分失敗または孤児状態はResourceに残し、同じUIDへの明示的な更新または削除で収束・後始末できる必要があります。未知の結果中に別Operationで同じキューを作成しません。
参照、所有、削除
このFormはキューとその格納メッセージを所有します。QueueConsumer 0.3.0はキューを所有せず、参照は { "resourceUid": "…" } です。参照先は同じHost、同じSpaceにあり、Form URLがこの文書の formUrl と完全一致するResourceでなければなりません。WorkerVersion 0.5.0からのproducer参照も同じHost/Spaceと正確なForm URLを満たし、参照を使う主体にQueueへの権限が必要です。名前からUIDを再解決したり、別Host/SpaceのResourceを参照したりしてはいけません。参照は権限を与えず、Hostは参照先と各JavaScript Binding呼出しを認可します。
削除はキューResourceとそのメッセージだけに及びます。Queueを queue または deadLetterQueue として参照するQueueConsumerが一つでも残る場合、またはこのQueueを queueProducerBindings から参照する未削除WorkerVersionが一つでも残る場合は dependency_conflict で拒否します。未稼働・非選択Versionも参照を保持するため削除を妨げます。Consumer、WorkerVersion、他のキュー、アプリケーションデータは連鎖削除しません。明示的にすべての参照元を削除してからQueueを削除します。
未知のフィールド
spec とproducer Bindingの各入力オブジェクトは閉じた形です。未知のフィールドは拒否し、無視・保持・転送してはいけません。将来意味を増やす場合は新しいForm URLで契約を定義します。send の options および sendBatch の各message objectに未知のフィールドを渡してはいけません。
WorkerVersionのproducer Binding
WorkerVersion 0.5.0の queueProducerBindings は省略時 []、最大64要素です。各要素は {"name":string,"resource":{"resourceUid":string}} で、resource は同じHost/Space上のこのForm URLのQueueを指します。name は1〜64文字のJavaScript識別子（^[A-Za-z_$][A-Za-z0-9_$]{0,63}$）で、各配列内に重複できず、同じWorkerVersionの他Binding名・vars・秘密変数名とも衝突できません。name から環境変数 env[name] を作ります。
このBindingは send と sendBatch だけを持ち、Queueからの受信、peek、settlement操作は提供しません。send(body, options?) の body は ArrayBuffer、ArrayBufferView、またはUTF-8文字列、options は任意の {delaySeconds?: integer} です。send はPromiseで1〜256文字のHost発行message IDを返します。sendBatch(messages) は1〜100個の {body, delaySeconds?} を順序付きで原子的に送信し、入力順に対応する1〜100個の1〜256文字のmessage ID配列を返します。文字列本文はUTF-8のbyte列として扱います。各送信の delaySeconds は整数 0..43200 で、省略時はResourceの deliveryDelaySeconds を使います。各本文のbyte長は最大127000です。送信成功はHostが受理・永続化したことを示し、配信や処理完了を示しません。
{
"queueProducerBindings": [
{
"name": "TASKS",
"resource": { "resourceUid": "queue-uid" }
}
]
}JavaScript呼出しの失敗はPromise rejectionで、Error.name は invalid_body、message_too_large、batch_too_large、backend_unavailable のいずれかです。これはHost API v2のResource管理HTTP status、Problem Details、Operation状態とは別のエラー境界です。曖昧な結果で送信を繰り返すと重複し得るため、利用者はmessage IDと業務上の重複排除を用います。
Queueの削除は、参照が残る間だけでなく、削除対象外の未削除WorkerVersionが queueProducerBindings に参照を持つ間も拒否されます。WorkerVersionがまだ queueProducerBindings を実行していなくても同じです。参照元Versionを明示的に削除した後にQueueを削除します。