C_12633_Anlage - Push Notifications - Konkretisierung der Fehler

Inhaltsverzeichnis

1 Änderungsbeschreibung

Der Begriff "homeserver" verweist auf einen Matrix Server und wird jetzt in "client", "Fachdienst" oder "server" geändert, damit weniger Verwirrung entsteht.

Die Details der Fehler werden konkretisiert, und es wird eine Prioritätenliste erstellt, damit das Push Gateway weiß, in welcher Reinfolge es prüfen soll.

Das Feld "error" ist nun ein Pflichtfeld für die HTTP Statuscodes 400 und 413 bei den Batch Endpunkte.

2 Änderung in pusher_get.yaml

Die Datei pusher_get.yaml wird in den OpenAPI-YAML-Dateien der verschiedenen Fachdienste verwendet. Der Begriff "homeserver" wird durch "Fachdienst" ersetzt.

Alt:

data.properties.format:
                type: string
                description: |-
                  The format to send notifications in to Push Gateways if the
                  `kind` is `http`. The details about what fields the
                  homeserver should send to the push gateway are defined in the
                  [Push Gateway Specification](/push-gateway-api/). Currently the only format
                  available is 'event_id_only'.
      append:
            type: boolean
            description: |-
              If true, the FD should add another pusher with the
              given pushkey and App ID in addition to any others with
              different user IDs. Otherwise, the homeserver must remove any
              other pushers with the same App ID and pushkey for different
              users. The default is `false`.

Neu:

data.properties.format:
                type: string
                description: |-
                  The format to send notifications in to Push Gateways if the
                  `kind` is `http`. The details about what fields the
                  Fachdienst should send to the push gateway are defined in the
                  [Push Gateway Specification](/push-gateway-api/). Currently the only format
                  available is 'event_id_only'.
      append:
            type: boolean
            description: |-
              If true, the FD should add another pusher with the
              given pushkey and App ID in addition to any others with
              different user IDs. Otherwise, the Fachdienst must remove any
              other pushers with the same App ID and pushkey for different
              users. The default is `false`.

3 Änderung in pusher_post_put_delete.yaml

Die Datei pusher_post_put_delete.yaml wird in den OpenAPI-YAML-Dateien der verschiedenen Fachdienste verwendet. Der Begriff "homeserver" wird durch "server" ersetzt.

Alt:

data.properties.format:
          type: string
          description: |-
            The format to send notifications in to Push Gateways if the
            `kind` is `http`. The details about what fields the
            homeserver should send to the push gateway are defined in the
            [Push Gateway Specification](/push-gateway-api/).
            
            **TIM:** Currently the only format available is `event_id_only`.

            **Others:** This property is not used and should be omitted unless
            specified explicitly by the service implementing this specification.

...

append:
      type: boolean
      description: |-
        If true, the homeserver should add another pusher with the
        given pushkey and App ID in addition to any others with
        different user IDs. Otherwise, the homeserver must remove any
        other pushers with the same App ID and pushkey for different
        users. The default is `false`.

Neu:

data.properties.format:
          type: string
          description: |-
            The format to send notifications in to Push Gateways if the
            `kind` is `http`. The details about what fields the
            server should send to the push gateway are defined in the
            [Push Gateway Specification](/push-gateway-api/).
            
            **TIM:** Currently the only format available is `event_id_only`.

            **Others:** This property is not used and should be omitted unless
            specified explicitly by the service implementing this specification.

...

append:
      type: boolean
      description: |-
        If true, the server should add another pusher with the
        given pushkey and App ID in addition to any others with
        different user IDs. Otherwise, the server must remove any
        other pushers with the same App ID and pushkey for different
        users. The default is `false`.

4 Änderungen in push_gateway_openapi.yaml

Die Details des HTTP-Statuscodes 413 werden für alle drei Endpunkte erweitert, und das Feld "error" wird als Pflichtfeld festgelegt:

Alt:

'413':
          description: The request payload exceeds the maximum allowed size.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Batch request payload is too large."

Neu:

'413':
          description: |-
            The request payload exceeds the maximum allowed size.
            Push Gateway implementations MUST support request payloads of at least 256 KB.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    example: "Batch request payload is too large."
                  details:
                    type: object
                    description: Additional information about the size limit.
                    properties:
                      max_request_size_kb:
                        type: integer
                        description: |-
                          The maximum allowed request payload size in kilobytes.
                          Implementations MUST support at least 256 KB.
                        example: 1024

Die Details des HTTP-Statuscodes 400 werden für die Endpunkte /notify/batch und /notifyEncrypted/batch erweitert, und das Feld "error" wird für diese Endpunkte als Pflichtfeld festgelegt:

Alt:

'400':
          description: Invalid batch request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum: 
                      - "Invalid data format"
                      - "Batch size exceeds maximum limit"
                      - "Duplicate notification IDs in batch"
                      - "Individual notification too large"
                    example: "Batch size exceeds maximum limit"
                  details:
                    type: object
                    properties:
                      max_batch_size:
                        type: integer
                        example: 100
                      max_notification_size_kb:
                        type: integer
                        example: 64
                      duplicate_ids:
                        type: array
                        items:
                          type: string
                        example: ["enc_batch_1", "enc_batch_1"]
                      current_batch_size:
                        type: integer
                        example: 150

Neu:

'400':
          description: Invalid batch request
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum: 
                      - "Invalid data format"
                      - "Batch size exceeds maximum limit"
                      - "Duplicate notification IDs in batch"
                      - "Individual notification too large"
                    example: "Batch size exceeds maximum limit"
                    description: |-
                      The type of validation error that occurred. When multiple validation errors
                      are present, the Push Gateway returns the first applicable error in the
                      following priority order (highest to lowest):
                      1. `Invalid data format` - JSON parsing or schema validation failed
                      2. `Batch size exceeds maximum limit` - too many notifications in batch
                      3. `Duplicate notification IDs in batch` - non-unique IDs detected
                      4. `Individual notification too large` - a single notification exceeds size limit
                  details:
                    type: object
                    description: |-
                      Additional details about the error. The properties included depend on the
                      `error` type and contain only information relevant to that specific error.
                    properties:
                      max_batch_size:
                        type: integer
                        minimum: 100
                        description: |-
                          The maximum number of notifications allowed per batch request.
                          Push Gateway implementations must support at least 100 notifications
                          per batch. Higher values may be supported depending on the implementation.
                        example: 100
                      max_notification_size_kb:
                        type: integer
                        description: |-
                          The maximum allowed size (in kilobytes) for a single notification
                          object within the batch. Size is measured as the byte length of the
                          UTF-8 encoded JSON serialization of the `notification` object.
                          Enforcement of this limit is optional for Push Gateway implementations.
                        example: 64
                      duplicate_ids:
                        type: array
                        description: |-
                          List of notification IDs that appear more than once in the batch.
                          Each duplicate ID is listed only once. No specific order is guaranteed.
                        items:
                          type: string                       
                        example: ["enc_batch_1"]

Der Begriff "Homeserver" wird durch "Client" ersetzt:

Alt:

schemas.RejectedPushKeys:
      type: array
      description: |-
        A list of all pushkeys given in the notification request that
        are not valid. These could have been rejected by an upstream
        gateway because they have expired or have never been valid.
        Homeservers must cease sending notification requests for these
        pushkeys and remove the associated pushers. It may not
        necessarily be the notification in the request that failed:
        it could be that a previous notification to the same pushkey
        failed. May be empty.

Neu:

schemas.RejectedPushKeys:
      type: array
      description: |-
        A list of all pushkeys given in the notification request that
        are not valid. These could have been rejected by an upstream
        gateway because they have expired or have never been valid.
        Clients must cease sending notification requests for these
        pushkeys and remove the associated pushers. It may not
        necessarily be the notification in the request that failed:
        it could be that a previous notification to the same pushkey
        failed. May be empty.