3. Clientseitige Anforderungen (Client-Side Requirements)
3.1. Anfrage (Request)
Ein Client registriert sein Interesse an einer Ressource, indem er eine GET-Anfrage mit einer auf 0 (registrieren) gesetzten Observe-Option ausgibt. Wenn der Server eine 2.xx-Antwort zurückgibt, die ebenfalls eine Observe-Option enthält, hat der Server erfolgreich einen Eintrag mit dem Client-Endpunkt und dem Anfrage-Token zur Liste der Beobachter der Zielressource hinzugefügt, und der Client wird über Änderungen des Ressourcenzustands benachrichtigt.
So wie eine frische Antwort verwendet werden kann, um eine Anfrage zu erfüllen, ohne den Server zu kontaktieren, kann der aus einer Beobachtungsanfrage resultierende Strom von Aktualisierungen verwendet werden, um eine andere (Beobachtungs- oder normale GET-) Anfrage zu erfüllen, wenn die Zielressource dieselbe ist. Ein Client MUSS solche Anfragen aggregieren und DARF sich NICHT mehr als einmal für dieselbe Zielressource registrieren. Die Zielressource wird durch alle Optionen in der Anfrage identifiziert, die Teil des Cache-Key sind. Dies umfasst beispielsweise den vollständigen Anfrage-URI und die Accept-Option.
3.2. Benachrichtigungen (Notifications)
Benachrichtigungen sind zusätzliche Antworten, die vom Server als Antwort auf die einzelne erweiterte GET-Anfrage gesendet werden, die die Registrierung erstellt hat. Jede Benachrichtigung enthält das vom Client in der Anfrage angegebene Token. Der einzige Unterschied zwischen einer Benachrichtigung und einer normalen Antwort ist das Vorhandensein der Observe-Option.
Benachrichtigungen haben typischerweise einen 2.05 (Content) Antwortcode. Sie enthalten eine Observe-Option mit einer Sequenznummer zur Erkennung von Umordnungen (siehe Abschnitt 3.4) und eine Nutzlast im gleichen Content-Format wie die ursprüngliche Antwort. Wenn der Client eine oder mehrere ETag-Optionen in die GET-Anfrage aufgenommen hat (siehe Abschnitt 3.3), können Benachrichtigungen einen 2.03 (Valid) Antwortcode anstelle eines 2.05 (Content) Antwortcodes haben. Solche Benachrichtigungen enthalten eine Observe-Option mit einer Sequenznummer, aber keine Nutzlast.
Für den Fall, dass sich die Ressource auf eine Weise ändert, die dazu führen würde, dass eine normale GET-Anfrage zu diesem Zeitpunkt eine Nicht-2.xx-Antwort zurückgibt (zum Beispiel, wenn die Ressource gelöscht wird), sendet der Server eine Benachrichtigung mit einem entsprechenden Antwortcode (wie 4.04 Not Found) und entfernt den Eintrag des Clients aus der Liste der Beobachter der Ressource. Nicht-2.xx-Antworten enthalten keine Observe-Option.
3.3. Caching
Da Benachrichtigungen nur zusätzliche Antworten auf eine GET-Anfrage sind, nehmen Benachrichtigungen am Caching teil, wie in Abschnitt 5.6 von RFC 7252 [RFC7252] definiert. Sowohl das Frische-Modell als auch das Validierungsmodell werden unterstützt.
3.3.1. Frische (Freshness)
Ein Client KANN eine Benachrichtigung wie eine Antwort in seinem Cache speichern und eine gespeicherte Benachrichtigung, die frisch ist, verwenden, ohne den Server zu kontaktieren. Wie eine Antwort wird eine Benachrichtigung als frisch betrachtet, solange ihr Alter nicht größer ist als der durch die Max-Age-Option angegebene Wert (und keine neuere Benachrichtigung/Antwort empfangen wurde).
Der Server wird sein Bestes tun, um den vom Client beobachteten Ressourcenzustand so eng wie möglich mit dem tatsächlichen Zustand synchron zu halten. Ein Client kann sich jedoch nicht darauf verlassen, jeden einzelnen Zustand zu beobachten, den eine Ressource durchlaufen könnte. Wenn beispielsweise das Netzwerk überlastet ist oder sich der Zustand häufiger ändert, als das Netzwerk bewältigen kann, kann der Server Benachrichtigungen für eine beliebige Anzahl von Zwischenzuständen überspringen.
Der Server verwendet die Max-Age-Option, um ein Alter anzugeben, bis zu dem es akzeptabel ist, dass der beobachtete Zustand und der tatsächliche Zustand inkonsistent sind. Wenn das Alter der neuesten Benachrichtigung größer wird als ihr angegebenes Max-Age, dann DARF der Client NICHT annehmen, dass die beigefügte Repräsentation den tatsächlichen Ressourcenzustand widerspiegelt.
Um sicherzustellen, dass er eine aktuelle Repräsentation hat und/oder um sein Interesse an einer Ressource erneut zu registrieren, KANN ein Client jederzeit eine neue GET-Anfrage mit demselben Token wie das Original ausgeben. Alle Optionen MÜSSEN mit denen in der ursprünglichen Anfrage identisch sein, mit Ausnahme des Satzes von ETag-Optionen. Es wird EMPFOHLEN, dass der Client die Anfrage nicht ausgibt, solange er noch eine frische Benachrichtigung/Antwort für die Ressource in seinem Cache hat. Zusätzlich SOLLTE der Client mindestens eine zufällige Zeitspanne zwischen 5 und 15 Sekunden warten, nachdem Max-Age abgelaufen ist, um Kollisionen mit anderen Clients zu reduzieren.
3.3.2. Validierung (Validation)
Wenn ein Client eine oder mehrere Benachrichtigungen für eine Ressource in seinem Cache gespeichert hat, kann er die ETag-Option in der GET-Anfrage verwenden, um dem Server die Möglichkeit zu geben, eine gespeicherte Benachrichtigung zur Verwendung auszuwählen.
Der Client KANN eine ETag-Option für jede gespeicherte Antwort aufnehmen, die in der GET-Anfrage anwendbar ist. Wann immer sich die beobachtete Ressource zu einer Repräsentation ändert, die durch eine der ETag-Optionen identifiziert wird, kann der Server eine gespeicherte Antwort auswählen, indem er eine 2.03 (Valid) Benachrichtigung mit einer entsprechenden ETag-Option anstelle einer 2.05 (Content) Benachrichtigung sendet.
Eine Client-Implementierung muss alle Kandidatenantworten in seinem Cache behalten, bis er nicht mehr an der Zielressource interessiert ist oder er sich mit einem neuen Satz von Entity-Tags erneut registriert.
3.4. Umordnung (Reordering)
Nachrichten mit Benachrichtigungen können in einer anderen Reihenfolge eintreffen, als sie gesendet wurden. Da das Ziel ist, den beobachteten Zustand so eng wie möglich mit dem tatsächlichen Zustand synchron zu halten, MUSS ein Client die Benachrichtigung, die am aktuellsten gesendet wurde, als die frischeste betrachten, unabhängig von der Ankunftsreihenfolge.
Um eine Reihenfolge unter Benachrichtigungen für den Client bereitzustellen, setzt der Server den Wert der Observe-Option in jeder Benachrichtigung auf die 24 niedrigstwertigen Bits einer streng monoton steigenden Sequenznummer. Eine eingehende Benachrichtigung wurde aktueller gesendet als die bisher frischeste Benachrichtigung, wenn eine der folgenden Bedingungen erfüllt ist:
(V1 < V2 und V2 - V1 < 2^23) oder
(V1 > V2 und V1 - V2 > 2^23) oder
(T2 > T1 + 128 Sekunden)
wobei V1 der Wert der Observe-Option in der bisher frischesten Benachrichtigung ist, V2 der Wert der Observe-Option in der eingehenden Benachrichtigung ist, T1 ein client-lokaler Zeitstempel für die bisher frischeste Benachrichtigung ist und T2 ein client-lokaler Zeitstempel für die eingehende Benachrichtigung ist.
Design-Hinweis: Die ersten beiden Bedingungen verifizieren, dass V1 kleiner als V2 in der 24-Bit-Seriennummer-Arithmetik [RFC1982] ist. Die dritte Bedingung stellt sicher, dass, wenn der Server Seriennummern basierend auf einer lokalen Uhr generiert, die zwischen den beiden eingehenden Nachrichten verstrichene Zeit nicht so groß ist, dass die Differenz zwischen V1 und V2 größer geworden ist als die größte Ganzzahl, die sinnvoll zu einer 24-Bit-Seriennummer addiert werden kann; mit anderen Worten, nachdem 128 Sekunden ohne Benachrichtigung vergangen sind, muss ein Client die Sequenznummern nicht überprüfen, um anzunehmen, dass eine eingehende Benachrichtigung aktueller gesendet wurde als die frischeste Benachrichtigung, die er bisher erhalten hat.
Die Dauer von 128 Sekunden wurde als eine schöne runde Zahl größer als MAX_LATENCY (Abschnitt 4.8.2 von RFC 7252 [RFC7252]) gewählt.
3.5. Übertragung (Transmission)
Eine Benachrichtigung kann bestätigbar oder nicht bestätigbar sein, d. h. sie kann in einer bestätigbaren oder einer nicht bestätigbaren Nachricht gesendet werden. Der für eine Benachrichtigung verwendete Nachrichtentyp ist unabhängig von dem für die Anfrage und für jede vorherige Benachrichtigung verwendeten Typ.
Wenn ein Client das Token in einer bestätigbaren Benachrichtigung nicht erkennt, DARF er die Nachricht NICHT bestätigen und SOLLTE sie mit einer Reset-Nachricht ablehnen; andernfalls MUSS der Client die Nachricht wie üblich bestätigen. Im Falle einer nicht bestätigbaren Benachrichtigung ist das Ablehnen der Nachricht mit einer Reset-Nachricht OPTIONAL.
Eine Bestätigungsnachricht signalisiert dem Server, dass der Client am Leben ist und daran interessiert ist, weitere Benachrichtigungen zu erhalten; wenn der Server keine Bestätigung als Antwort auf eine bestätigbare Benachrichtigung erhält, nimmt er an, dass der Client nicht mehr interessiert ist, und entfernt schließlich den zugehörigen Eintrag aus der Liste der Beobachter (Abschnitt 4.5).
3.6. Stornierung (Cancellation)
Ein Client, der nicht mehr daran interessiert ist, Benachrichtigungen für eine Ressource zu erhalten, kann die Beobachtung einfach "vergessen". Wenn der Server dann die nächste Benachrichtigung sendet, erkennt der Client das Token in der Nachricht nicht und gibt daher eine Reset-Nachricht zurück. Dies veranlasst den Server, den zugehörigen Eintrag aus der Liste der Beobachter zu entfernen. Die Einträge in Listen von Beobachtern werden vom Server effektiv "garbage collected".
Implementierungshinweis: Aufgrund von potenziellem Nachrichtenverlust erreicht die Reset-Nachricht den Server möglicherweise nicht. Der Client muss daher möglicherweise mehrere Benachrichtigungen ablehnen, jede mit einer Reset-Nachricht, bis der Server schließlich den zugehörigen Eintrag aus der Liste der Beobachter entfernt und aufhört, Benachrichtigungen zu senden.
Unter bestimmten Umständen kann es wünschenswert sein, eine Beobachtung zu stornieren und die vom Server dafür zugewiesenen Ressourcen eifriger freizugeben. In diesem Fall KANN sich ein Client explizit abmelden, indem er eine GET-Anfrage ausgibt, deren Token-Feld auf das Token der zu stornierenden Beobachtung gesetzt ist und die eine Observe-Option mit dem auf 1 (abmelden) gesetzten Wert enthält. Alle anderen Optionen MÜSSEN mit denen in der Registrierungsanfrage identisch sein, mit Ausnahme des Satzes von ETag-Optionen. Wenn der Server eine solche Anfrage empfängt, entfernt er jeden passenden Eintrag aus der Liste der Beobachter und verarbeitet die GET-Anfrage wie üblich.