5. Requesting Push Message Delivery

Der Anwendungsserver fordert die Zustellung durch HTTP POST auf die vom User Agent verteilte push resource an. Der Nachrichteninhalt steht im Request-Body.

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

201 (Created) bedeutet Annahme. Die URI der erzeugten Push-Message-Ressource MUST in Location stehen. Das bedeutet nicht, dass die Nachricht beim User Agent angekommen ist.

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:55 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

5.1. Requesting Push Message Receipts

Der Anwendungsserver kann Prefer [RFC7240] mit respond-async setzen, um nach Zustellung und Bestätigung durch den User Agent eine Quittung zu erhalten. Der Push-Dienst MUST Zustellbestätigungen unterstützen.

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
Prefer: respond-async
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

Bei Annahme mit Bestätigung MUST der Dienst 202 (Accepted) zurückgeben. Location enthält die Nachrichten-URI. Zusätzlich MUST eine URI für die receipt subscription in urn:ietf:params:push:receipt geliefert werden.

HTTP/1.1 202 Accepted
Date: Thu, 11 Dec 2014 23:56:55 GMT
Link: </receipt-subscription/3ZtI4YVNBnUUZhuoChl6omUvG4ZM>;
        rel="urn:ietf:params:push:receipt"
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

Für weitere Quittungsanfragen an dieselbe Origin [RFC6454] SHOULD die zurückgegebene receipt subscription mitgesendet werden. Der Dienst SHOULD dieselbe subscription zurückgeben, MAY aber eine neue, falls Wiederverwendung nicht möglich.

Der Anwendungsserver MAY die subscription weglassen, wenn er Quittungen nicht aggregiert empfangen kann.

Bei ungültiger receipt subscription MUST der Dienst 400 antworten. Zur Begrenzung der Anzahl MAY er 429 [RFC6585] senden, wenn die subscription fehlt.

5.2. Push Message Time-To-Live

Zwischenspeicherung verbessert die Zuverlässigkeit. User Agents sind oft nur zeitweise online.

Verzögerte Zustellung kann Kommunikation mit dem User Agent bündeln und Funkressourcen schonen.

Manche Nachrichten sind nach einer gewissen Zeit nutzlos; spätere Zustellung verschwendet Ressourcen (z. B. Anrufbenachrichtigung nach Auflegen).

TTL MUST im Zustellungsrequest enthalten sein (Sekunden, gewünschte Aufbewahrungsdauer).

TTL ist eine nicht negative Ganzzahl. Empfänger SHOULD mindestens 31 Bit nutzen. Bei Überlauf oder zu großem Wert MUST der Wert als 2147483648 (2^31) behandelt werden.

TTL = 1*DIGIT

Ohne TTL MUST der Dienst 400 antworten.

Der Dienst MAY kürzer speichern und den tatsächlichen TTL in der Antwort mitteilen; dieser MUST kleiner oder gleich dem angeforderten Wert sein.

Nach Ablauf MUST NOT der Dienst zustellen. Der Dienst kann den TTL-Wert anpassen, um Zeiterfassungsfehler auszugleichen (z. B. Verteilung im Cluster, Uhrabweichung, Laufzeitverzögerung).

Der Dienst muss weder die Zeit bis zur Annahme beim Dienst noch Verzögerungen bis zum User Agent anrechnen. Der Anwendungsserver muss Transitverzögerungen bei der TTL-Wahl berücksichtigen.

TTL 0: sofortige Zustellung wenn der User Agent verfügbar ist; danach sofortiges Löschen möglich, bevor DELETE erfolgt; Quittungen für TTL 0 sind unzuverlässig. Ohne User Agent verfügbar: Nachricht verfällt.

5.3. Push Message Urgency

Bei batteriebetriebenen Geräten ist langes Ruhen wichtig; Funk verbraucht viel Energie.

Der Anwendungsserver MAY Urgency setzen. Der Push-Dienst MUST NOT dieses Feld an den User Agent weiterleiten. Ohne Urgency gilt normal.

Der User Agent MAY beim Überwachen Urgency setzen (minimale akzeptierte Dringlichkeit). Der Dienst MUST NOT Nachrichten mit geringerer Dringlichkeit zustellen. Ohne Urgency vom User Agent werden alle Stufen zugestellt.

Urgency = urgency-option
urgency-option = ("very-low" / "low" / "normal" / "high")

Urgency	Device State	Example Application Scenario
very-low	On power and Wi-Fi	Advertisements
low	On either power or Wi-Fi	Topic updates
normal	On neither power nor Wi-Fi	Chat or Calendar Message
high	Low battery	Incoming phone call or time-sensitive alert

Mehrere Urgency-Werte MUST NOT in einer Anfrage vorkommen; sonst MUST 400.

5.4. Replacing Push Messages

Gespeicherte Nachrichten können ersetzt werden. Nur Nachrichten mit Topic sind ersetzbar; gleiches Topic ersetzt ausstehende mit identischem Topic.

Topic steht im Header Topic; korreliert nur Nachrichten zum selben Abonnement.

Topic = token

Topic MUST höchstens 32 Zeichen aus URL- und dateinamen-sicherem Base64 [RFC4648] sein; sonst MUST 400.

Eine Ersetzungsanfrage erzeugt eine neue Push-Message-Ressource und löscht gleichzeitig jede bestehende Nachrichtenressource mit passendem Topic. Wurde die gelöschte Nachricht zugestellt versucht, kann eine Bestätigung nach der Ersetzung beim Dienst eintreffen. Zustellquittungen für solche gelöschten Nachrichten SHOULD unterdrückt werden.

Die Ersetzung aktualisiert auch gespeichertes TTL, Urgency und jede receipt subscription der vorherigen Nachricht zum gleichen Topic.

Eine Push-Nachricht mit einem Topic, das von keiner ausstehenden Nachricht zum selben Abonnement geteilt wird, wird normal gespeichert oder zugestellt.

Die folgende Nachricht könnte beispielsweise eine bestehende ersetzen:

POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 600
Topic: upd
Content-Type: text/plain;charset=utf8
Content-Length: 36

ZuHSZPKa2b1jtOKLGpWrcrn8cNqt0iVQyroF

Identifiziert der Push-Dienst eine ausstehende Push-Nachricht mit Topic upd, wird deren Ressource gelöscht. 201 (Created) bedeutet, dass die Ersetzung akzeptiert wurde. Location enthält die URI der neu erzeugten Push-Message-Ressource.

HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:57:02 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt

Der Wert des Topic-Headerfeldes MUST NOT an User Agents weitergeleitet werden. Er ist weder verschlüsselt noch authentisiert.