Merge pull request #296 from jlurien/feat/consolidate-duration-dates

Consolidation of changes related to session duration

code/API_definitions/qos-profiles.yaml

@@ -231,8 +231,7 @@ components:
         maxDuration:
           description: |
             The maximum time period that this profile can be deployed.
-            NOTE: currently the duration within `sessionInfo` is limited to 86400 seconds (1 day).
-            The value of `maxDuration` shouldn't therefore exceed this time period. The limitation might be removed in later versions.
+            Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions.
           allOf:
             - $ref: "#/components/schemas/Duration"
         priority:

code/API_definitions/quality-on-demand.yaml

@@ -12,7 +12,7 @@ info:
 
     ![QoD API Overview](https://github.com/raw/camaraproject/QualityOnDemand/main/documentation/API_documentation/resources/QoD_latency_overview.PNG)
 
-    The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically. The automatic process is triggered either when the requested specified duration of a QoS session has reached its limit or the default session expiration time has been reached (within an example provider implementation it is set to 24hrs).
+    The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted. The deletion of a requested session can be triggered by the API consumer or can be triggered automatically once the QoS session has reached its limit.
 
     # Relevant terms and definitions
 
@@ -35,7 +35,7 @@ info:
     The precise application data flow the developer wants to prioritize and have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the device and the application server. And it can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features.
 
     * **Duration**:
-    Duration (in seconds) for which the QoS session (between application client and application server) should be created. This parameter is optional. When not specified, a default session duration (e.g. 24 hours) is applied. The user may request a termination before its expiration.
+    Duration (in seconds) for which the QoS session (between application client and application server) should be created. Limits for session duration can be set by the implementation for the QoS profile. The user may request a termination before its expiration.
 
     * **Notification URL and token**:
     Developers may provide a callback URL on which notifications about all status change events of the session (eg. session termination) can be received from the service provider. This is an optional parameter.
@@ -97,8 +97,7 @@ paths:
 
         A `QOS_STATUS_CHANGED` event notification with `qosStatus` as `UNAVAILABLE` will also be send if the network terminates the session before the requested duration expired
 
-        NOTE: in case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session
-        are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
+        NOTE: in case of a `QOS_STATUS_CHANGED` event with `qosStatus` as `UNAVAILABLE` and `statusInfo` as `NETWORK_TERMINATED` the resources of the QoS session are not directly released, but will get deleted automatically at earliest 360 seconds after the event.
         This behavior allows clients which are not receiving notification events but are polling to get the session information with
         the `qosStatus` `UNAVAILABLE` and `statusInfo` `NETWORK_TERMINATED`. Before a client can attempt to create a new QoD session
         for the same device and flow period they must release the session resources with an explicit `delete` operation if not yet automatically deleted.
@@ -359,14 +358,12 @@ paths:
         - QoS Sessions
       summary: "Extend the duration of an active session"
       description: |
-        Extend the overall duration of an active QoS session. If this operation is executed successfully, the new duration of the target session will be the original duration plus the additionally requested duration.
-        The new remaining duration of the QoS session shall not exceed the maximum remaining duration limit (currently fixed at 86,400 seconds) where the remaining duration is calculated as the difference between the `expiresAt` and current time when the request to extend the session duration is received. If this maximum limit would be exceeded, the overall duration shall be set such that the remaining duration is equal to this limit.
-        An example: A QoD session was originally created with duration 80,000 seconds. 10,000 seconds later, the developer requested to extend the session by 20,000 seconds.
-        - Original duration: 80,000 seconds
-        - Elapsed time: 10,000 seconds
-        - Remaining duration: 70,000 seconds
-        - New remaining duration: 86,400 seconds (the maximum allowed)
-        - New overall session duration: 96,400 seconds
+        Extend the overall session duration of an active QoS session.
+        The overall duration of the QoS session, including the additional extended duration, shall not exceed the maximum duration limit fixed for the QoS Profile. If the current duration plus the value of `requestedAdditionalDuration` exceeds the maximum limit, the new overall duration shall be capped to the maximum value allowed.
+        An example: For a QoS profile limited to a `maxDuration` of 50,000 seconds, a QoD session was originally created with duration 30,000 seconds. Before the session expires, the developer requests to extend the session by another 30,000 seconds:
+        - Previous duration: 30,000 seconds
+        - Requested additional duration: 30,000 seconds
+        - New overall session duration: 50,000 seconds (the maximum allowed)
       operationId: extendQosSessionDuration
       parameters:
         - name: sessionId
@@ -527,20 +524,30 @@ components:
             sessionId:
               $ref: "#/components/schemas/SessionId"
             duration:
+              description: |
+                Session duration in seconds. Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
+                - When `qosStatus` is "REQUESTED", the value is the duration to be scheduled, granted by the implementation.
+                - When `qosStatus` is AVAILABLE", the value is the overall duration since `startedAt. When the session is extended, the value is the new overall duration of the session.
+                - When `qosStatus` is "UNAVAILABLE", the value is the overall effective duration since `startedAt` until the session was terminated.
               type: integer
               format: int32
               minimum: 1
-              example: 86400
+              example: 3600
             startedAt:
-              type: integer
-              example: 1639479600
-              description: Timestamp of session start in seconds since Unix epoch
-              format: int64
+              description: Date and time when the QoS status became "AVAILABLE". Not to be returned when `qosStatus` is "REQUESTED". Format must follow RFC 3339 and must indicate time zone (UTC or local).
+              type: string
+              format: date-time
+              example: "2024-06-01T12:00:00Z"
             expiresAt:
-              type: integer
-              example: 1639566000
-              description: Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch
-              format: int64
+              description: |
+                Date and time of the QoS session expiration. Format must follow RFC 3339 and must indicate time zone (UTC or local).
+                - When `qosStatus` is "AVAILABLE", it is the limit time when the session is scheduled to finnish, if not terminated by other means.
+                - When `qosStatus` is "UNAVAILABLE", it is the time when the session was terminated.
+                - Not to be returned when `qosStatus` is "REQUESTED".
+                When the session is extended, the value is the new expiration time of the session.
+              type: string
+              format: date-time
+              example: "2024-06-01T13:00:00Z"
             qosStatus:
               $ref: "#/components/schemas/QosStatus"
             statusInfo:
@@ -552,8 +559,6 @@ components:
           required:
             - sessionId
             - duration
-            - startedAt
-            - expiresAt
             - qosStatus
 
     CreateSession:
@@ -564,17 +569,13 @@ components:
           properties:
             duration:
               description: |
-                Session duration in seconds. Maximal value of 24 hours is used if not set.
-                After session is expired the, client will receive a `QOS_STATUS_CHANGED` event with
-                - `qosStatus` as `UNAVAILABLE`, and,
-                - `statusInfo` as `DURATION_EXPIRED`.
-                See notification callback.
+                Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the [Qos Profile API](TBC). Implementations can grant the requested session duration or set a different duration, based on network policies or conditions.
               type: integer
               format: int32
               minimum: 1
-              maximum: 86400
-              default: 86400
-              example: 86400
+              example: 3600
+          required:
+            - duration
 
     Port:
       description: TCP or UDP port number
@@ -621,12 +622,11 @@ components:
       properties:
         requestedAdditionalDuration:
           description: |
-            Additional duration in seconds to be extended.
+            Additional duration in seconds to be added to the current session duration. The overall session duration, including extensions, shall not exceed the maximum duration limit for the QoS Profile.
           type: integer
           format: int32
           minimum: 1
-          maximum: 86399
-          example: 60
+          example: 1800
       required:
         - requestedAdditionalDuration
 
@@ -995,8 +995,9 @@ components:
   examples:
     SESSION_AVAILABLE_EXAMPLE:
       summary: QoS session status is available
+      description: QoS session info when status is available
       value:
-        duration: 86400
+        duration: 3600
         device:
           ipv4Address:
             publicAddress: 203.0.113.0
@@ -1007,14 +1008,15 @@ components:
         webhook:
           notificationUrl: https://application-server.com
         sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
-        startedAt: 1639479600
-        expiresAt: 1639566000
+        startedAt: "2024-06-01T12:00:00Z"
+        expiresAt: "2024-06-01T13:00:00Z"
         qosStatus: AVAILABLE
 
     SESSION_UNAVAILABLE_EXAMPLE:
       summary: QoS session is unavailable
+      description: QoS session info when status is unavailable due to network termination
       value:
-        duration: 86400
+        duration: 2428
         device:
           ipv4Address:
             publicAddress: 203.0.113.0
@@ -1025,20 +1027,20 @@ components:
         webhook:
           notificationUrl: https://application-server.com
         sessionId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
-        startedAt: 1639479600
-        expiresAt: 1639566000
+        startedAt: "2024-06-01T12:00:00Z"
+        expiresAt: "2024-06-01T12:40:28Z"
         qosStatus: UNAVAILABLE
         statusInfo: NETWORK_TERMINATED
 
     QOS_STATUS_CHANGED_EXAMPLE:
-      description: QoS status changed
-      summary: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
+      summary: QoS status changed
+      description: Cloud event example for QoS status change to UNAVAILABLE due to DURATION_EXPIRED
       value:
         id: 83a0d986-0866-4f38-b8c0-fc65bfcda452
         source: 'https://api.example.com/qod/v0/sessions/123e4567-e89b-12d3-a456-426614174000'
         specversion: '1.0'
         type: 'org.camaraproject.qod.v0.qos-status-changed'
-        time: '2021-12-12T00:00:00Z'
+        time: '2024-06-01T13:00:00Z'
         data:
           sessionId: '123e4567-e89b-12d3-a456-426614174000'
           qosStatus: 'UNAVAILABLE'