3. Requisiti lato client (Client-Side Requirements)
3.1. Richiesta (Request)
Un client registra il suo interesse in una risorsa emettendo una richiesta GET con un'Opzione Observe impostata a 0 (registra). Se il server restituisce una risposta 2.xx che include anche un'Opzione Observe, il server ha aggiunto con successo una voce con l'endpoint del client e il token di richiesta all'elenco degli osservatori della risorsa di destinazione, e il client sarà notificato dei cambiamenti dello stato della risorsa.
Proprio come una risposta fresca può essere utilizzata per soddisfare una richiesta senza contattare il server, il flusso di aggiornamenti risultante da una richiesta di osservazione può essere utilizzato per soddisfare un'altra richiesta (di osservazione o normale GET) se la risorsa di destinazione è la stessa. Un client DEVE aggregare tali richieste e NON DEVE registrarsi più di una volta per la stessa risorsa di destinazione. La risorsa di destinazione è identificata da tutte le opzioni nella richiesta che fanno parte della Cache-Key. Ciò include, ad esempio, l'URI completo della richiesta e l'Opzione Accept.
3.2. Notifiche (Notifications)
Le notifiche sono risposte aggiuntive inviate dal server in risposta alla singola richiesta GET estesa che ha creato la registrazione. Ogni notifica include il token specificato dal client nella richiesta. L'unica differenza tra una notifica e una risposta normale è la presenza dell'Opzione Observe.
Le notifiche hanno tipicamente un codice di risposta 2.05 (Content). Includono un'Opzione Observe con un numero di sequenza per il rilevamento del riordino (vedere Sezione 3.4) e un payload nello stesso Content-Format della risposta iniziale. Se il client ha incluso una o più Opzioni ETag nella richiesta GET (vedere Sezione 3.3), le notifiche possono avere un codice di risposta 2.03 (Valid) piuttosto che un codice di risposta 2.05 (Content). Tali notifiche includono un'Opzione Observe con un numero di sequenza ma nessun payload.
Nel caso in cui la risorsa cambi in un modo che causerebbe a una normale richiesta GET in quel momento di restituire una risposta non-2.xx (ad esempio, quando la risorsa viene eliminata), il server invia una notifica con un codice di risposta appropriato (come 4.04 Not Found) e rimuove la voce del client dall'elenco degli osservatori della risorsa. Le risposte non-2.xx non includono un'Opzione Observe.
3.3. Caching
Poiché le notifiche sono solo risposte aggiuntive a una richiesta GET, le notifiche partecipano al caching come definito nella Sezione 5.6 di RFC 7252 [RFC7252]. Sono supportati sia il modello di freschezza che il modello di convalida.
3.3.1. Freschezza (Freshness)
Un client PUÒ memorizzare una notifica come una risposta nella sua cache e utilizzare una notifica memorizzata che è fresca senza contattare il server. Come una risposta, una notifica è considerata fresca finché la sua età non è maggiore del valore indicato dall'Opzione Max-Age (e non è stata ricevuta alcuna notifica/risposta più recente).
Il server farà del suo meglio per mantenere lo stato della risorsa osservato dal client il più strettamente sincronizzato possibile con lo stato effettivo. Tuttavia, un client non può contare sull'osservazione di ogni singolo stato che una risorsa potrebbe attraversare. Ad esempio, se la rete è congestionata o lo stato cambia più frequentemente di quanto la rete possa gestire, il server può saltare le notifiche per qualsiasi numero di stati intermedi.
Il server utilizza l'Opzione Max-Age per indicare un'età fino alla quale è accettabile che lo stato osservato e lo stato effettivo siano incoerenti. Se l'età dell'ultima notifica diventa maggiore del suo Max-Age indicato, allora il client NON DEVE assumere che la rappresentazione inclusa rifletta lo stato effettivo della risorsa.
Per assicurarsi di avere una rappresentazione attuale e/o per registrare nuovamente il suo interesse in una risorsa, un client PUÒ emettere una nuova richiesta GET con lo stesso token dell'originale in qualsiasi momento. Tutte le opzioni DEVONO essere identiche a quelle nella richiesta originale eccetto per il set di Opzioni ETag. Si RACCOMANDA che il client non emetta la richiesta mentre ha ancora una notifica/risposta fresca per la risorsa nella sua cache. Inoltre, il client DOVREBBE almeno attendere una quantità di tempo casuale tra 5 e 15 secondi dopo la scadenza di Max-Age per ridurre le collisioni con altri client.
3.3.2. Convalida (Validation)
Quando un client ha una o più notifiche memorizzate nella sua cache per una risorsa, può utilizzare l'Opzione ETag nella richiesta GET per dare al server l'opportunità di selezionare una notifica memorizzata da utilizzare.
Il client PUÒ includere un'Opzione ETag per ogni risposta memorizzata che è applicabile nella richiesta GET. Ogni volta che la risorsa osservata cambia in una rappresentazione identificata da una delle Opzioni ETag, il server può selezionare una risposta memorizzata inviando una notifica 2.03 (Valid) con un'Opzione ETag appropriata invece di una notifica 2.05 (Content).
Un'implementazione client deve mantenere tutte le risposte candidate nella sua cache finché non è più interessata alla risorsa di destinazione o si registra nuovamente con un nuovo set di tag di entità.
3.4. Riordino (Reordering)
I messaggi con notifiche possono arrivare in un ordine diverso da quello in cui sono stati inviati. Poiché l'obiettivo è mantenere lo stato osservato il più strettamente sincronizzato possibile con lo stato effettivo, un client DEVE considerare la notifica che è stata inviata più recentemente come la più fresca, indipendentemente dall'ordine di arrivo.
Per fornire un ordine tra le notifiche per il client, il server imposta il valore dell'Opzione Observe in ogni notifica ai 24 bit meno significativi di un numero di sequenza strettamente crescente. Una notifica in arrivo è stata inviata più recentemente della notifica più fresca finora quando una delle seguenti condizioni è soddisfatta:
(V1 < V2 e V2 - V1 < 2^23) o
(V1 > V2 e V1 - V2 > 2^23) o
(T2 > T1 + 128 secondi)
dove V1 è il valore dell'Opzione Observe nella notifica più fresca finora, V2 è il valore dell'Opzione Observe nella notifica in arrivo, T1 è un timestamp locale del client per la notifica più fresca finora, e T2 è un timestamp locale del client per la notifica in arrivo.
Nota di progettazione: Le prime due condizioni verificano che V1 sia minore di V2 nell'aritmetica dei numeri seriali a 24 bit [RFC1982]. La terza condizione assicura che se il server sta generando numeri seriali basati su un orologio locale, il tempo trascorso tra i due messaggi in arrivo non è così grande che la differenza tra V1 e V2 è diventata maggiore del più grande intero che ha senso aggiungere a un numero seriale a 24 bit; in altre parole, dopo che sono trascorsi 128 secondi senza alcuna notifica, un client non ha bisogno di controllare i numeri di sequenza per assumere che una notifica in arrivo sia stata inviata più recentemente della notifica più fresca che ha ricevuto finora.
La durata di 128 secondi è stata scelta come un bel numero tondo maggiore di MAX_LATENCY (Sezione 4.8.2 di RFC 7252 [RFC7252]).
3.5. Trasmissione (Transmission)
Una notifica può essere confermabile o non confermabile, cioè può essere inviata in un messaggio confermabile o non confermabile. Il tipo di messaggio utilizzato per una notifica è indipendente dal tipo utilizzato per la richiesta e da qualsiasi notifica precedente.
Se un client non riconosce il token in una notifica confermabile, NON DEVE riconoscere il messaggio e DOVREBBE rifiutarlo con un messaggio Reset; altrimenti, il client DEVE riconoscere il messaggio come al solito. Nel caso di una notifica non confermabile, rifiutare il messaggio con un messaggio Reset è OPZIONALE.
Un messaggio di riconoscimento segnala al server che il client è vivo e interessato a ricevere ulteriori notifiche; se il server non riceve un riconoscimento in risposta a una notifica confermabile, assumerà che il client non è più interessato e alla fine rimuoverà la voce associata dall'elenco degli osservatori (Sezione 4.5).
3.6. Cancellazione (Cancellation)
Un client che non è più interessato a ricevere notifiche per una risorsa può semplicemente "dimenticare" l'osservazione. Quando il server invia poi la notifica successiva, il client non riconoscerà il token nel messaggio e quindi restituirà un messaggio Reset. Ciò fa sì che il server rimuova la voce associata dall'elenco degli osservatori. Le voci negli elenchi degli osservatori sono effettivamente "garbage collected" dal server.
Nota di implementazione: A causa della potenziale perdita di messaggi, il messaggio Reset potrebbe non raggiungere il server. Il client potrebbe quindi dover rifiutare più notifiche, ciascuna con un messaggio Reset, finché il server non rimuove finalmente la voce associata dall'elenco degli osservatori e smette di inviare notifiche.
In alcune circostanze, potrebbe essere desiderabile cancellare un'osservazione e rilasciare le risorse allocate dal server ad essa più avidamente. In questo caso, un client PUÒ cancellarsi esplicitamente emettendo una richiesta GET che ha il campo Token impostato sul token dell'osservazione da cancellare e include un'Opzione Observe con il valore impostato a 1 (cancellare). Tutte le altre opzioni DEVONO essere identiche a quelle nella richiesta di registrazione eccetto per il set di Opzioni ETag. Quando il server riceve tale richiesta, rimuoverà qualsiasi voce corrispondente dall'elenco degli osservatori ed elaborerà la richiesta GET come al solito.