**Note**: excluding this property from the Operation implies that all messages from the channel will be included. Explicitly set the `messages` property to `[]` if this operation should contain no messages.
reply | [Operation Reply Object](#operationReplyObject) | [Reference Object](#referenceObject) | The definition of the reply in a request-reply operation. +retry | [Operation Retry Object](#operationRetryObject) | [Reference Object](#referenceObject) | The retry route and policy for a `receive` operation when processing does not complete successfully. +deadLetter | [Operation Dead Letter Object](#operationDeadLetterObject) | [Reference Object](#referenceObject) | The dead-letter route for a `receive` operation when processing cannot be recovered. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -862,7 +869,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "channel": { "$ref": "#/channels/userSignup" }, - "action": "send", + "action": "receive", "security": [ { "type": "oauth2", @@ -910,6 +917,30 @@ This object MAY be extended with [Specification Extensions](#specificationExtens "messages": [ { "$ref": "#/channels/userSignupReply/messages/userSignedUpReply" } ] + }, + "retry": { + "channel": { + "$ref": "#/channels/userSignupRetries" + }, + "messages": [ + { "$ref": "#/channels/userSignupRetries/messages/userSignupRetry" } + ], + "maxAttempts": 3, + "strategy": { + "type": "exponential", + "initialDelay": "PT1S", + "multiplier": 2, + "maxDelay": "PT1M" + } + }, + "deadLetter": { + "channel": { + "$ref": "#/channels/userSignupDeadLetters" + }, + "messages": [ + { "$ref": "#/channels/userSignupDeadLetters/messages/userSignupDeadLetter" } + ], + "maxWaitTime": "PT15S" } } ``` @@ -921,7 +952,7 @@ summary: Action to sign a user up. description: A longer description channel: $ref: '#/channels/userSignup' -action: send +action: receive security: - type: oauth2 description: The oauth security descriptions @@ -953,6 +984,23 @@ reply: $ref: '#/channels/userSignupReply' messages: - $ref: '#/channels/userSignupReply/messages/userSignedUpReply' +retry: + channel: + $ref: '#/channels/userSignupRetries' + messages: + - $ref: '#/channels/userSignupRetries/messages/userSignupRetry' + maxAttempts: 3 + strategy: + type: exponential + initialDelay: PT1S + multiplier: 2 + maxDelay: PT1M +deadLetter: + channel: + $ref: '#/channels/userSignupDeadLetters' + messages: + - $ref: '#/channels/userSignupDeadLetters/messages/userSignupDeadLetter' + maxWaitTime: PT15S ``` #### Operation Trait Object @@ -1040,6 +1088,133 @@ description: Consumer Inbox location: $message.header#/replyTo ``` +#### Operation Retry Object + +Describes the retry path that MAY be applied to a `receive` Operation Object. It defines the channel and messages used to retry a failed operation, together with the retry policy. A retry route is an observable contract outcome; protocol bindings MAY define how the delivery is implemented. + +##### Fixed Fields + +| Field Name | Type | Description | +|-----------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| channel | [Reference Object](#referenceObject) | **Required.** A `$ref` pointer to the channel to which retry messages are sent. The same location rules as the [Operation Reply Object](#operationReplyObject) `channel` field apply. | +| messages | [[Reference Object](#referenceObject)] | **Required.** A non-empty list of `$ref` pointers to messages in the referenced retry channel. | +| maxAttempts | `integer` | **Required.** The maximum number of retry attempts. The value MUST be greater than zero. | +| strategy | [Fixed Retry Strategy Object](#fixedRetryStrategyObject) | [Linear Retry Strategy Object](#linearRetryStrategyObject) | [Exponential Retry Strategy Object](#exponentialRetryStrategyObject) | **Required.** The delay policy applied between retry attempts. | + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Operation Retry Object Example + +```yaml +retry: + channel: + $ref: '#/channels/orderRetries' + messages: + - $ref: '#/channels/orderRetries/messages/retryOrder' + maxAttempts: 3 + strategy: + type: exponential + initialDelay: PT1S + multiplier: 2 + maxDelay: PT1M +``` + +#### Fixed Retry Strategy Object + +Describes a retry policy with the same fixed delay between every retry attempt. + +##### Fixed Fields + +| Field Name | Type | Description | +|---------------------------------------------------|:---------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `"fixed"` | **Required.** Identifies this as a fixed retry strategy. | +| delay | `string` | **Required.** The delay between attempts, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Fixed Retry Strategy Object Example + +```yaml +strategy: + type: fixed + delay: PT30S +``` + +#### Linear Retry Strategy Object + +Describes a retry policy whose delay increases by a fixed increment after each retry attempt. + +##### Fixed Fields + +| Field Name | Type | Description | +|----------------------------------------------------------------------|:----------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `"linear"` | **Required.** Identifies this as a linear retry strategy. | +| initialDelay | `string` | **Required.** The delay before the first retry, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | +| delayIncrement | `string` | **Required.** The amount added to the delay after each retry, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | +| maxDelay | `string` | The maximum delay between attempts, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Linear Retry Strategy Object Example + +```yaml +strategy: + type: linear + initialDelay: PT5S + delayIncrement: PT10S + maxDelay: PT1M +``` + +#### Exponential Retry Strategy Object + +Describes a retry policy whose delay is multiplied after each retry attempt. + +##### Fixed Fields + +| Field Name | Type | Description | +|-----------------------------------------------------------------------|:---------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `"exponential"` | **Required.** Identifies this as an exponential retry strategy. | +| initialDelay | `string` | **Required.** The delay before the first retry, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | +| multiplier | `number` | **Required.** The value by which the delay is multiplied after each retry. The value MUST be greater than zero. | +| maxDelay | `string` | The maximum delay between attempts, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Exponential Retry Strategy Object Example + +```yaml +strategy: + type: exponential + initialDelay: PT1S + multiplier: 2 + maxDelay: PT1M +``` + +#### Operation Dead Letter Object + +Describes the dead-letter path that MAY be applied to a `receive` Operation Object. When processing cannot be recovered, including after the associated retry policy is exhausted, the message is sent to this channel. Protocol bindings MAY define the delivery mechanism and any broker-specific metadata. + +##### Fixed Fields + +| Field Name | Type | Description | +|----------------------------------------------------------------|:--------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| channel | [Reference Object](#referenceObject) | **Required.** A `$ref` pointer to the channel to which dead-letter messages are sent. The same location rules as the [Operation Reply Object](#operationReplyObject) `channel` field apply. | +| messages | [[Reference Object](#referenceObject)] | **Required.** A non-empty list of `$ref` pointers to messages in the referenced dead-letter channel. | +| maxWaitTime | `string` | The maximum time an implementation waits for a dead-letter message to appear, as an ISO 8601 duration limited to seconds, minutes or hours matching `^PT(?=\d)(?:\d+H)?(?:\d+M)?(?:\d+(?:[.,]\d+)?S)?$`. | + +This object MAY be extended with [Specification Extensions](#specificationExtensions). + +##### Operation Dead Letter Object Example + +```yaml +deadLetter: + channel: + $ref: '#/channels/orderDeadLetters' + messages: + - $ref: '#/channels/orderDeadLetters/messages/deadLetterOrder' + maxWaitTime: PT15S +``` + #### Parameters Object Describes a map of parameters included in a channel address.