[#1107] Document qos-1 announcements.

Signed-off-by: Yufei Cai <yufei.cai@bosch.io>

documentation/src/main/resources/jsonschema/policy.json

@@ -36,6 +36,26 @@
                     "type": "string",
                     "description": "The optional expiry timestamp (formatted in ISO-8601) indicates how long this subject should be considered before it is automatically deleted from the Policy.",
                     "format": "date-time"
+                  },
+                  "requestedAcks": {
+                    "title": "RequestedAcks",
+                    "type": "object",
+                    "description": "Settings to enable at-least-once delivery for policy announcements.",
+                    "properties": {
+                      "labels": {
+                        "type": "array",
+                        "description": "Acknowledgement labels to request when an announcement is published.",
+                        "items": {
+                          "type": "string"
+                        },
+                        "example": ["my-connection:my-issued-acknowledgement"]
+                      },
+                      "timeout": {
+                        "type": "string",
+                        "description": "How long to wait for requested announcements before retrying publication of an announcement.",
+                        "example": "60s"
+                      }
+                    }
                   }
                 },
                 "required": [
@@ -76,19 +96,22 @@
                   }
                 },
                 "required": [
-                  "grant", "revoke"
+                  "grant",
+                  "revoke"
                 ]
               }
             }
           },
           "required": [
-            "subjects", "resources"
+            "subjects",
+            "resources"
           ]
         }
       }
     }
   },
   "required": [
-    "policyId", "entries"
+    "policyId",
+    "entries"
   ]
 }

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -8,7 +8,7 @@ info:
     The Eclipse Ditto HTTP API uses response status codes (see [RFC 7231](https://tools.ietf.org/html/rfc7231#section-6))
     to indicate whether a specific request has been successfully completed, or not.
 
-    However, the descriptions we provide additionally to the status code (e.g. in our API docs, or error codes like. "things:thing.tooLarge") might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.
+    The information Ditto provides additionally to the status code (e.g. in API docs, or error codes like. "things:thing.tooLarge") might change without advance notice. These are not be considered as official API, and must therefore not be applied in your applications or tests.
 servers:
   - url: 'https://ditto.eclipseprojects.io/api/2'
     description: online Ditto Sandbox
@@ -6206,6 +6206,10 @@ components:
             announcement:
               beforeExpiry: 5m
               whenDeleted: true
+              requestedAcks:
+                labels:
+                  - 'my-connection-id:my-issued-acknowledgement'
+                timeout: 30s
       description: Optional request payload for `activateTokenIntegration` policy action.
       required: false
   responses:
@@ -6760,9 +6764,8 @@ components:
         acknowledgements via the `requested-acks` param. Can be specified without unit (then seconds are assumed) or
         together with `s`, `ms` or `m` unit. Example: `42s`, `1m`.
 
-        The default (if omitted) timeout is `10s`. Maximum value: `60s`.
-
-        A value of `0` applies fire and forget semantics for the command resulting in setting `response-required=false`.
+        The default (if omitted) and maximum timeout is `60s`. A value of `0` applies fire and forget semantics for
+        the command resulting in setting `response-required=false`.
       required: false
       schema:
         type: string
@@ -7055,6 +7058,22 @@ components:
         whenDeleted:
           type: boolean
           description: Whether an announcement should be made when this subject is deleted.
+        requestedAcks:
+          type: object
+          description: Whether the announcement should be published at-least-once via acknowledgement requests.
+          properties:
+            labels:
+              type: array
+              description: Acknowledgement labels to request an announcement is published.
+              items:
+                type: string
+            timeout:
+              type: string
+              description: How long to wait for requested announcements before retrying publication of an announcement.
+          example:
+            labels:
+              - 'my-connection-id:my-issued-acknowledgement'
+            timeout: 5s
       example:
         beforeExpiry: 5m
         whenDeleted: true

documentation/src/main/resources/openapi/sources/requests/policies/actions/activateTokenIntegration.yml

@@ -18,5 +18,8 @@ content:
       announcement:
         beforeExpiry: "5m"
         whenDeleted: true
+        requestedAcks:
+          labels: ["my-connection-id:my-issued-acknowledgement"]
+          timeout: "30s"
 description: Optional request payload for `activateTokenIntegration` policy action.
-required: false
+required: false

documentation/src/main/resources/openapi/sources/schemas/policies/subjectAnnouncement.yml

@@ -19,6 +19,21 @@ properties:
   whenDeleted:
     type: boolean
     description: Whether an announcement should be made when this subject is deleted.
+  requestedAcks:
+    type: object
+    description: Settings to enable at-least-once delivery for policy announcements.
+    properties:
+      labels:
+        type: array
+        description: Acknowledgement labels to request when an announcement is published.
+        items:
+          type: string
+      timeout:
+        type: string
+        description: How long to wait for requested announcements before retrying publication of an announcement.
+    example:
+      labels: ["my-connection-id:my-issued-acknowledgement"]
+      timeout: "5s"
 example:
   beforeExpiry: "5m"
-  whenDeleted: true
+  whenDeleted: true

documentation/src/main/resources/pages/ditto/basic-policy.md

@@ -75,6 +75,40 @@ When providing an `"expiry"` for a Policy subject, this timestamp is rounded up:
 Once an expired subject is deleted, it will immediately no longer have access to the resources protected by the policy
 it was deleted from.
 
+### Subject Deletion Announcements
+
+To get notified when your subject is deleted, set the `announcement` field in your subject.
+```json
+{
+  "type": "my-subject",
+  "expiry": "2099-12-31T23:59:59Z",
+  "announcement": {
+    "beforeExpiry": "1h",
+    "whenDeleted": true,
+    "requestedAcks": {
+      "labels": ["my-announcement-receiver"],
+      "timeout": "10s"
+    }
+  }
+}
+```
+
+Here are the meanings of the fields of `announcement`.
+- `beforeExpiry`: The duration before expiration of the subject when a
+  [subject deletion announcement](protocol-examples-policies-announcement-subjectDeletion.html)
+  is published if no previous subject deletion announcement was acknowledged.
+- `whenDeleted`: Whether a
+  [subject deletion announcement](protocol-examples-policies-announcement-subjectDeletion.html)
+  is published if no previous subject deletion announcement was acknowledged.
+- `requestedAcks`: Settings for at-least-once delivery of announcements via
+  [acknowledgements](basic-acknowledgements.html).
+  - `labels`: Declared acknowledgement labels of the websocket or connectivity channel from which the acknowledgement
+    is expected.
+  - `timeout`: How long to wait for acknowledgements before retrying the publication of announcements.
+
+The subject deletion announcements are published to any websocket or connection that has subscribed for policy
+announcements and has the relevant subject ID in its authorization context.
+
 ## Actions
 
 Policy actions are available via Ditto's [HTTP API](httpapi-overview.html) and can be invoked for certain 

documentation/src/main/resources/pages/ditto/protocol-specification-connections-announcement.md

@@ -33,7 +33,7 @@ Announcement indicating that the connection is being opened.
 | **path**  | `/`     |
 | **value** |  `JsonObject` containing<br/>* `openedAt` timestamp (as ISO-8601 `string`)|
 
-**Example:** [Announcement for subject deletion](protocol-examples-connections-announcement-opened.html)
+**Example:** [Announcement for connection opened](protocol-examples-connections-announcement-opened.html)
 
 ### ConnectionClosedAnnouncement
 
@@ -45,4 +45,4 @@ Announcement indicating that the connection is being closed gracefully.
 | **path**  | `/`     |
 | **value** |  `JsonObject` containing<br/>* `closedAt` timestamp (as ISO-8601 `string`)|
 
-**Example:** [Announcement for subject deletion](protocol-examples-connections-announcement-closed.html)
+**Example:** [Announcement for connection closed](protocol-examples-connections-announcement-closed.html)

documentation/src/main/resources/pages/ditto/protocol/examples/connections/protocol-examples-connections-announcement-opened.md

@@ -1,5 +1,5 @@
 ---
-title: ConnectionClosedAnnouncement
+title: ConnectionOpenedAnnouncement
 keywords: examples, connection, connectivity, announcement, opened
 search: exclude
 permalink: protocol-examples-connections-announcement-opened.html