Consolidated issue for duration, extentDuration, startedAt, expiredAt, maxDuration and their formats (to be updated)

hdamker commented 2 months ago

Problem description

A placeholder for the consolidation of the following existing issues

249
266
280
281
288

Possible evolution

Decide on format for all time and date related parameters
Define the semantic of maxDuration and if additional parameter in QoS Profiles regarding duration are needed
Revisit the behaviour of extent duration in relation to these parameters
describe the value of startedAt, expiredAt, duration within the states of an QoS Session resource, including the changes by extendDuration
...

Alternative solution

tbd

Additional context

jlurien commented 1 month ago

Proposal:

For creation, duration is made required. Maximum and default are deprecated, relying on the QoS Profile API for any limit.

I have added that implementations can grant or set a different value in the response. This can be discussed.

            duration:
              description: |
                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
              example: 3600
          required:
            - duration

As reflected in the meeting minutes, the maxDuration in QoS Profiles is assumed to be the absolute maximum duration including any extensions. That is, extensions can extend the current session duration to the maximumDuration but no longer. Alternative is a maximum that applies individually to the initial duration and to any subsequent requestedAdditionalDuration, making in practice the session unlimited while being extended.

        maxDuration:
          description: |
            The maximum time period that this profile can be deployed.
            Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions.

So the new logic for the extendQosSessionDuration operations is

      summary: "Extend the duration of an active session"
      description: |
        Extend the overall session duration of an active QoS session. If this operation is executed successfully, the new duration of the target session will be the previous duration plus the additionally requested duration.
        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)

Session info changes:

dates are formatted as string, date-format.
startedAt and expiredAt are both optional and not expected to be returned when qosStatus is "REQUESTED". It is always a date in the past.
duration is the overall session duration, including any extension. It should be the interval between startedAt and expiresAt, so it is redundant, unless the qosStatus is "REQUESTED". In this case it would reflect the requested or granted duration. For sessions with qosStatus = "UNAVAILABLE", it must be adjusted to the effective duration. Date can be in the future or in the past. Name "expiresAt" could be changed to "expirationAt" or "expirationTime", but this same name is also used in the Subscriptions model, where it can be also in the future or in the past.

            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: 3600
            startedAt:
              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:
              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"

The originally requested session duration is not part of the SessionInfo object. We may discuss if this is necessary or convenient.

jlurien commented 1 month ago

PR #296 created with proposal above, so changes can be seen altogether:

camaraproject / QualityOnDemand

Consolidated issue for duration, extentDuration, startedAt, expiredAt, maxDuration and their formats (to be updated) #291

249

266

280

281

288