Edge Forms

日本語

English

日本語

English

配色

版が固定されたForm仕様

この版で固定されたURLの規範本文は日本語です。原文を読む。公開はHostやproviderの対応を意味しません。

QueueConsumer 0.3.0 ​

このFormは、一つのAtLeastOnceQueueを一つのModuleWorkerへ接続する消費Attachmentを表します。キューへの消費はBindingではなく内向きの起動関係です。Host API v2のResourceとして管理し、共通の作成・取得・更新・削除と再送規則はTakoform Host API v2 HTTP APIに従います。ModuleWorkerのruntime ABIはModuleWorker 0.3.0 §runtimeに従います。

入力 ​

spec は次のフィールドだけを受け付けます。queue と worker はAttachment UIDの間不変です。変更する場合は旧Attachmentを削除し、新しい名前または解放済みの名前で作り直します。その他の設定は更新できます。

フィールド要件、既定値、範囲作成後の変更
queue必須の { "resourceUid": "…" }。AtLeastOnceQueue 0.2.0のResourceを参照します。既定値なし。不変。
worker必須の { "resourceUid": "…" }。ModuleWorker 0.3.0のResourceを参照し、queue handlerを提供します。既定値なし。不変。
maxBatchSize必須整数 1..100。一回に渡す最大メッセージ数。既定値なし。変更できます。
maxBatchTimeoutSeconds必須整数 0..60。バッチを満たすために待つ最大秒数。0 は待たない設定です。既定値なし。変更できます。
maxConcurrency必須整数 1..250。同時に実行するバッチ数の上限。既定値なし。変更できます。
maxRetries必須整数 0..100。初回配信後の再配信上限。既定値なし。変更できます。
retryDelaySeconds必須整数 0..43200。失敗したメッセージを再配信可能にするまでの既定秒数。既定値なし。変更できます。
deadLetterQueue任意の { "resourceUid": "…" }。AtLeastOnceQueue 0.2.0を参照します。省略時は再試行を使い切ったメッセージを破棄します。変更・省略できます。
json
{
  "queue": { "resourceUid": "queue-uid" },
  "worker": { "resourceUid": "worker-uid" },
  "maxBatchSize": 10,
  "maxBatchTimeoutSeconds": 5,
  "maxConcurrency": 4,
  "maxRetries": 3,
  "retryDelaySeconds": 30
}

秘密入力はありません。空でない privateInputs は拒否します。未知のspecフィールドは拒否します。

配信とInterface操作 ​

参照は resourceUid に固定されます。各参照先は同じHost、同じSpaceにあり、Form URLが上記の正確なForm URLと完全一致しなければなりません。queue と worker は必須です。deadLetterQueue を指定した場合はそれも同じ条件で検証します。参照は認可を付与しません。

参照WorkerはModuleWorker 0.3.0が定める queue handlerを宣言・提供しなければなりません。HostはABI所定のバッチを渡します。batchは1〜maxBatchSize個の順序付きmessageを持ちます。各messageには1〜256文字の安定した不透明ID、UTC Unix epochミリ秒の受理時刻、最大127000 byteの元の不透明バイト列、初回1から始まる整数の試行回数があります。batchには1〜256文字の識別子とQueue Resource名が含まれます。呼出しはat-least-onceで、同じメッセージが複数回・異なる順序で届き得ます。handlerは副作用を重複実行しても安全にする必要があります。

ModuleWorkerの queue handlerが受け取るbatchとsettlement methodはModuleWorker 0.3.0 §runtimeで定義します。各methodはHostのResource管理HTTP APIではなく、配信中messageのsettlementです。handlerにはbatch単位のobjectが渡され、各methodはそのbatchへ束縛されるため、JavaScript呼出しにbatch IDは渡しません。

JavaScript操作必須引数と任意引数成功結果Error.nameによる拒否
batch.acknowledge(messageId)このbatch内のmessage ID（1〜256文字）Promiseがundefinedで解決unknown_batch, unknown_message, already_settled, backend_unavailable
batch.retry(messageId, delaySeconds?)batch内ID；任意の整数遅延 0..43200Promiseがundefinedで解決同上
batch.acknowledgeAll()なしPromiseがundefinedで解決unknown_batch, backend_unavailable
batch.retryAll(delaySeconds?)任意の整数遅延 0..43200Promiseがundefinedで解決unknown_batch, backend_unavailable

batch.acknowledge は一通を配信済みに確定し、二度目のsettlementを already_settled で拒否します。batch.retry は一通を再配信待ちへ戻し、指定遅延がなければ retryDelaySeconds を使います。batch.acknowledgeAll は未settledの全通を配信済みにし、batch.retryAll は未settledの全通を再配信待ちにします。バッチ外IDを受理せず、settle済みメッセージの結果を反転しません。これらのJavaScript Promise拒否はInterfaceのデータ操作失敗であり、Host API v2のHTTP Problem Details やResource Operation.error ではありません。

handlerが例外なく戻った場合、未settled分をacknowledgeします。handlerがthrowまたは返却Promiseがrejectした場合、既にsettleされた結果は維持し、残る未settled分をretryします。maxRetries は再配信回数であり初回を数えません。最大配信回数は 1 + maxRetries です。上限到達後、deadLetterQueue があればそのキューへ新しいメッセージとして移し、なければ破棄します。移動先のメッセージIDと受理時刻は新しくなり、attemptsは1に戻ります。元メッセージとの対応を表す移植可能な情報はありません。

queue参照ごとに有効なConsumerは最大1つです。二つ目、存在しない/削除中/型違い/他SpaceのResource、Workerが必要なhandlerを持たない参照は副作用前に拒否します。dead-letterグラフに自己参照または長さを問わない循環が生じる更新・作成も拒否します。dead-letter転送でattemptsがリセットされ、メッセージが循環することを防ぎます。

観測、出力、利用可能状態 ​

observed は初回観測前は {} です。確認後は queueExists、workerExists、consumerAttached の真偽値を含み、各値はHostが最後に確認した状態を示します。確認できない項目は省略し、false は確認済みの不在・未接続だけに使います。形の例:

json
{
  "queueExists": true,
  "workerExists": true,
  "consumerAttached": true
}

このFormの output は常に {} です。Attachmentの作成・更新成功は設定が受理されたことを意味し、Worker handlerが成功したこと、キューが空であること、アプリケーションが健全であることを意味しません。

CRUD、拒否、障害復旧 ​

  • 作成: Host API v2の共通検証の後、両参照、必須handler、キューごとの単一Consumer制約、dead-letter循環、主体の参照権限を副作用前に検査します。制約を満たさない場合はAttachmentや配信設定を変更しません。
  • 取得: AttachmentのResourceと最後に確定した観測を返します。読み取りはメッセージ配信を開始しません。
  • 更新: spec を全体置換します。queue と worker の変更は invalid_spec として副作用前に拒否します。他の設定変更も、制約検証が済むまで適用しません。Consumer有効化の変更結果が不明なら別Consumerを追加せず照合します。
  • 削除: このAttachmentだけを解除します。Queue、Worker、dead-letter Queueを削除せず、未処理メッセージを別Queueへ移しません。Hostは停止境界を確定してからAttachmentを削除し、進行中のhandlerや未settledメッセージを成功扱いしません。

未settledメッセージはACKが確定するまで再配信義務として残ります。Host再起動後もsettlement記録と未settled状態を回復します。ACKまたはretry要求の結果が不明なら、同じbatch/message識別子を照合し、settlementが確認できない間は未知として扱います。処理済みと確定しない限りメッセージを消失扱いにしてはいけません。再起動やtimeoutでACKがあったと推測してはいけません。handler再実行による重複はこのFormのat-least-once契約の一部です。

v2 Operationで作成・更新・削除を再送するとき、同じIdempotency-Keyは同じOperationを返します。外部設定の反映が一部だけ成功した場合は effect:partial、反映結果を確定できない場合は effect:unknown としてOperationを reconciling に保ちます。応答待ち時間超過だけで失敗・無効果と断定しません。HostはOperationを再起動後に復元し、未完了中に新しいOperationで別Attachmentを作りません。既知の部分失敗は同一Resource UIDへの明示的PUTまたはDELETEで収束・解除できる必要があります。

削除時、キューに未settledメッセージがあってもAttachment解除はそれらをACKしません。進行中の配送が終了または安全に再配信可能となるまでHostは削除を完了扱いしません。Hostがその安全境界を証明できなければOperationはunknown/reconcilingのままです。

所有、参照、削除の範囲 ​

このResourceが所有するのはQueueConsumer Attachmentだけです。Queue、Worker、dead-letter Queueは { "resourceUid": "…" } で参照します。参照先は同じHost/Spaceに属し、それぞれのForm URLが https://edge.forms.takoform.com/forms/AtLeastOnceQueue/0.2.0/ または https://edge.forms.takoform.com/forms/ModuleWorker/0.3.0/ に完全一致しなければなりません。dead-letterQueueはQueueConsumer自身が排出するQueueへ戻らず、全dead-letter参照のグラフに循環を作らない必要があります。Queueの送信操作とメッセージ形式はAtLeastOnceQueue 0.2.0に従います。

Attachment削除は接続だけを外し、参照先Resourceやそのデータを連鎖削除しません。参照先Queueの削除はこのAttachmentが残る間拒否されます。参照UIDは名前変更・再作成後も別Resourceへ付け替えません。参照の存在から利用権限を得ることはありません。

未知のフィールド ​

spec、参照オブジェクト、Interface呼出しオブジェクトは閉じた形です。未知フィールドは拒否し、無視・保存・転送してはいけません。参照オブジェクトは resourceUid 一つだけを持ちます。