feat(webhooks): add confirmationMode subscription option

.vscode/settings.json

@@ -7,6 +7,7 @@
     "actioned",
     "APIID",
     "autometa",
+    "besteffort",
     "bifactory",
     "blobstore",
     "blockchainids",

doc-site/docs/reference/types/_includes/subscription_description.md

@@ -171,10 +171,13 @@ allowing you to customize your HTTP requests as follows:
   - To retry requests to your Webhook on a non-`2xx` HTTP status code
     or other error, you should enable and configure
     [options.retry](#webhookretryoptions)
-  - The event is acknowledged once the request (with any retries), is
+  - By default the event is acknowledged once the request (with any retries), is
     completed - regardless of whether the outcome was a success or failure.
+- Use `confirmationMode` to choose whether a delivery has to be confirmed before
+  the subscription checkpoint advances (see below).
 - Use `fastack` to acknowledge against FireFly immediately and make multiple
-  parallel calls to the HTTP API in a fire-and-forget fashion.
+  parallel calls to the HTTP API in a fire-and-forget fashion. **Deprecated**:
+  please use `confirmationMode: fastack` instead.
 - Set the HTTP request details dynamically from `message_confirmed` events:
   - Map data out of the first `data` element in message events
   - Requires `withData` to be set on the subscription, in addition to the
@@ -185,6 +188,37 @@ allowing you to customize your HTTP requests as follows:
   - Sets a `tag` in the reply message, per the configuration, or dynamically
     based on a field in the input request data.
 
+#### Delivery confirmation
+
+The `confirmationMode` option determines whether - and when - a Webhook delivery
+causes the subscription checkpoint to advance:
+
+| `confirmationMode` | Behavior |
+| ------------------ | -------- |
+| `fastack`     | Acknowledge each event *before* the delivery is attempted. The delivery runs detached, and its outcome never affects the checkpoint. Equivalent to the deprecated `fastack: true` option. |
+| `besteffort`  | Deliver synchronously - holding the checkpoint while the invocation, including any configured [options.retry](#webhookretryoptions) attempts, completes - then acknowledge each event regardless of the response status or any error. **This is the default**, and the behavior of all releases before this option existed. |
+| `assured`     | Deliver synchronously and acknowledge only on a `2xx` response. Anything else - including a connection failure - holds the subscription checkpoint, so the event(s) are redelivered. |
+
+Use `assured` when your application needs at-least-once semantics and would
+rather the subscription stall on a broken endpoint than silently skip past
+events it never received. Note that this means a persistently failing endpoint
+will block that subscription, so configure
+[options.retry](#webhookretryoptions) to suit, and monitor for a subscription
+that stops progressing.
+
+> Delivery confirmation does not apply when `reply` is enabled. In reply mode
+> the Webhook response - whatever its status - *is* the payload relayed back to
+> the original caller, so there is nothing to hold the checkpoint for.
+
+The `fastack` boolean is retained for backwards compatibility, but is
+deprecated in favor of `confirmationMode`:
+
+- `fastack: true` with no `confirmationMode` resolves to `confirmationMode: fastack`
+- Neither set resolves to `confirmationMode: besteffort` - today's default, unchanged
+- `fastack: true` combined with any `confirmationMode` other than `fastack` is
+  rejected when the subscription is created or updated, as the two are saying
+  contradictory things
+
 #### Batching events
 
 Webhooks have the ability to batch events into a single HTTP request instead of sending an event per HTTP request. The interface will be a JSON array of events instead of a top level JSON object with a single event. The size of the batch will be set by the `readAhead` limit and an optional timeout can be specified to send the events when the batch hasn't filled.

doc-site/docs/reference/types/subscription.md

@@ -90,7 +90,8 @@ title: Subscription
 | `withData` | Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. | `bool` |
 | `batch` | Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. | `bool` |
 | `batchTimeout` | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. | `string` |
-| `fastack` | Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations | `bool` |
+| `fastack` | Webhooks only: Deprecated - please use a confirmationMode of fastack instead. When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations | `bool` |
+| `confirmationMode` | Webhooks only: Determines whether a webhook delivery must be confirmed before the subscription checkpoint advances. Use fastack to acknowledge the event before the webhook is invoked, besteffort (the default) to hold the checkpoint while the invocation - including any configured client-side retries - completes, then acknowledge regardless of its outcome, or assured to acknowledge only on a 2xx response and otherwise hold the checkpoint and redeliver | `FFEnum`:<br/>`"fastack"`<br/>`"besteffort"`<br/>`"assured"` |
 | `url` | Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config | `string` |
 | `method` | Webhooks only: HTTP method to invoke. Default=POST | `string` |
 | `json` | Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type | `bool` |

doc-site/docs/reference/types/wsstart.md

@@ -81,7 +81,8 @@ title: WSStart
 | `withData` | Whether message events delivered over the subscription, should be packaged with the full data of those messages in-line as part of the event JSON payload. Or if the application should make separate REST calls to download that data. May not be supported on some transports. | `bool` |
 | `batch` | Events are delivered in batches in an ordered array. The batch size is capped to the readAhead limit. The event payload is always an array even if there is a single event in the batch, allowing client-side optimizations when processing the events in a group. Available for both Webhooks and WebSockets. | `bool` |
 | `batchTimeout` | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. | `string` |
-| `fastack` | Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations | `bool` |
+| `fastack` | Webhooks only: Deprecated - please use a confirmationMode of fastack instead. When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations | `bool` |
+| `confirmationMode` | Webhooks only: Determines whether a webhook delivery must be confirmed before the subscription checkpoint advances. Use fastack to acknowledge the event before the webhook is invoked, besteffort (the default) to hold the checkpoint while the invocation - including any configured client-side retries - completes, then acknowledge regardless of its outcome, or assured to acknowledge only on a 2xx response and otherwise hold the checkpoint and redeliver | `FFEnum`:<br/>`"fastack"`<br/>`"besteffort"`<br/>`"assured"` |
 | `url` | Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config | `string` |
 | `method` | Webhooks only: HTTP method to invoke. Default=POST | `string` |
 | `json` | Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type | `bool` |