# C_12633_Anlage - Push Notifications - Konkretisierung der Fehler

Inhaltsverzeichnis

#

- C_12633_Anlage - Push Notifications - Konkretisierung der Fehler
- 1 Änderungsbeschreibung
- 2 Änderung in pusher_get.yaml
- 3 Änderung in pusher_post_put_delete.yaml
- 4 Änderungen in push_gateway_openapi.yaml

## 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.