10. Proxying inter-protocollo tra CoAP e HTTP
CoAP supporta un sottoinsieme limitato delle funzionalità HTTP, e quindi il proxying inter-protocollo verso HTTP è semplice. Ci possono essere diverse ragioni per fare proxying tra CoAP e HTTP, ad esempio quando si progetta un'interfaccia web da usare su uno dei due protocolli o quando si realizza un proxy CoAP-HTTP. Analogamente, CoAP potrebbe ugualmente essere sottoposto a proxying verso altri protocolli come XMPP [RFC6120] o SIP [RFC3264]; la definizione di questi meccanismi è fuori dall'ambito di questa specifica.
Esistono due possibili direzioni per accedere a una risorsa tramite un forward-proxy:
CoAP-HTTP Proxying: Consente ai client CoAP di accedere a risorse su server HTTP attraverso un intermediario. Ciò viene avviato includendo l'opzione Proxy-Uri o Proxy-Scheme con un URI "http" o "https" in una richiesta CoAP a un proxy CoAP-HTTP.
HTTP-CoAP Proxying: Consente ai client HTTP di accedere a risorse su server CoAP attraverso un intermediario. Ciò viene avviato specificando un URI "coap" o "coaps" nella Request-Line di una richiesta HTTP a un proxy HTTP-CoAP.
In entrambi i casi, solo il modello request/response di CoAP è mappato su HTTP. Il modello sottostante dei messaggi Confirmable o Non-confirmable, ecc., è invisibile e non deve avere alcun effetto su una funzione di proxy (MUST). Le sezioni seguenti descrivono la gestione delle richieste a un forward-proxy. I reverse-proxy non sono specificati, poiché la funzione di proxy è trasparente al client, con il proxy che agisce come se fosse l'origin server. Tuttavia, considerazioni simili si applicano ai reverse-proxy come ai forward-proxy, e in generale ci sarà l'aspettativa che i reverse-proxy operino in modo simile a come opererebbero i forward-proxy. Come nota implementativa, le librerie client HTTP possono rendere difficile gestire un forward-proxy HTTP-CoAP non fornendo un modo per inserire un URI CoAP nella Request-Line HTTP; il reverse-proxying può quindi portare a una maggiore applicabilità di un proxy. Una specifica separata può definire una convenzione per gli URI che gestiscono un tale reverse-proxy HTTP-CoAP [MAPPING].
10.1. Proxying CoAP-HTTP
Se una richiesta contiene un'opzione Proxy-Uri o Proxy-Scheme con un URI 'http' o 'https' [RFC2616], allora all'endpoint CoAP ricevente (chiamato "il proxy" d'ora in poi) viene richiesto di eseguire l'operazione specificata dal metodo di richiesta sulla risorsa HTTP indicata e di restituire il risultato al client. (Vedere anche la Sezione 5.7 per come viene formulata la richiesta al proxy, inclusi i requisiti di sicurezza.)
Questa sezione specifica, per qualsiasi richiesta CoAP, la risposta CoAP che il proxy dovrebbe restituire al client. Come il proxy soddisfi effettivamente la richiesta è un dettaglio implementativo, sebbene il caso tipico si preveda essere che il proxy traduca e inoltri la richiesta a un origin server HTTP.
Poiché HTTP e CoAP condividono l'insieme di base dei metodi di richiesta, eseguire una richiesta CoAP su una risorsa HTTP non è molto diverso dall'eseguirla su una risorsa CoAP. I significati dei singoli metodi CoAP quando eseguiti su risorse HTTP sono spiegati nelle sottosezioni di questa sezione.
Se il proxy non è in grado o non è disposto a servire una richiesta con un URI HTTP, viene restituita al client una risposta 5.05 (Proxying Not Supported). Se il proxy serve la richiesta interagendo con una terza parte (come l'origin server HTTP) e non è in grado di ottenere un risultato entro un lasso di tempo ragionevole, viene restituita una risposta 5.04 (Gateway Timeout); se un risultato può essere ottenuto ma non viene compreso, viene restituita una risposta 5.02 (Bad Gateway).
10.1.1. GET
Il metodo GET richiede al proxy di restituire una rappresentazione della risorsa HTTP identificata dall'URI della richiesta.
In caso di successo, dovrebbe essere restituito un Response Code 2.05 (Content) (SHOULD). Il payload della risposta deve essere una rappresentazione della risorsa HTTP di destinazione, e l'opzione Content-Format deve essere impostata di conseguenza (MUST). La risposta deve indicare un valore Max-Age non superiore al tempo rimanente in cui la rappresentazione può essere considerata fresca (MUST). Se l'entità HTTP ha un entity-tag, il proxy dovrebbe includere un'opzione ETag nella risposta ed elaborare le opzioni ETag nelle richieste come descritto di seguito (SHOULD).
Un client può influenzare l'elaborazione di una richiesta GET includendo la seguente opzione:
Accept: La richiesta può includere un'opzione Accept, che identifica il content-format preferito per la risposta (MAY).
ETag: La richiesta può includere una o più opzioni ETag, che identificano le risposte che il client ha memorizzato (MAY). Ciò richiede al proxy di inviare una risposta 2.03 (Valid) ogni volta che altrimenti invierebbe una risposta 2.05 (Content) con un entity-tag nell'insieme richiesto. Si noti che gli ETag di CoAP sono sempre ETag strong nel senso di HTTP; CoAP non ha l'equivalente degli ETag weak di HTTP, e non c'è un buon modo per utilizzarli in un cross-proxy.
10.1.2. PUT
Il metodo PUT richiede al proxy di aggiornare o creare la risorsa HTTP identificata dall'URI della richiesta con la rappresentazione acclusa.
Se una nuova risorsa viene creata all'URI della richiesta, deve essere restituita al client una risposta 2.01 (Created) (MUST). Se una risorsa esistente viene modificata, deve essere restituita una risposta 2.04 (Changed) per indicare il completamento con successo della richiesta (MUST).
10.1.3. DELETE
Il metodo DELETE richiede al proxy di eliminare la risorsa HTTP identificata dall'URI della richiesta presso l'origin server HTTP.
In caso di successo, o se la risorsa non esiste al momento della richiesta, deve essere restituita al client una risposta 2.02 (Deleted) (MUST).
10.1.4. POST
Il metodo POST richiede al proxy di far elaborare dall'origin server HTTP la rappresentazione acclusa nella richiesta. La funzione effettiva eseguita dal metodo POST è determinata dall'origin server e dipende dalla risorsa identificata dall'URI della richiesta.
Se l'azione eseguita dal metodo POST non produce una risorsa che possa essere identificata da un URI, deve essere restituita al client una risposta 2.04 (Changed) (MUST). Se una risorsa è stata creata sull'origin server, deve essere restituita una risposta 2.01 (Created) (MUST).
10.2. Proxying HTTP-CoAP
Se una richiesta HTTP contiene un Request-URI con un URI "coap" o "coaps", allora all'endpoint HTTP ricevente (chiamato "il proxy" d'ora in poi) viene richiesto di eseguire l'operazione specificata dal metodo di richiesta sulla risorsa CoAP indicata e di restituire il risultato al client.
Questa sezione specifica, per qualsiasi richiesta HTTP, la risposta HTTP che il proxy dovrebbe restituire al client. Salvo diversa indicazione, tutte le affermazioni fatte sono comportamento RACCOMANDATO (RECOMMENDED); alcune implementazioni altamente vincolate potrebbero dover ricorrere a scorciatoie. Come il proxy soddisfi effettivamente la richiesta è un dettaglio implementativo, sebbene il caso tipico si preveda essere che il proxy traduca e inoltri la richiesta a un origin server CoAP. I significati dei singoli metodi HTTP quando eseguiti su risorse CoAP sono spiegati nelle sottosezioni di questa sezione.
Se il proxy non è in grado o non è disposto a servire una richiesta con un URI CoAP, viene restituita al client una risposta 501 (Not Implemented). Se il proxy serve la richiesta interagendo con una terza parte (come l'origin server CoAP) e non è in grado di ottenere un risultato entro un lasso di tempo ragionevole, viene restituita una risposta 504 (Gateway Timeout); se un risultato può essere ottenuto ma non viene compreso, viene restituita una risposta 502 (Bad Gateway).
10.2.1. OPTIONS e TRACE
Poiché i metodi OPTIONS e TRACE non sono supportati in CoAP, deve essere restituito al client un errore 501 (Not Implemented) (MUST).
10.2.2. GET
Il metodo GET richiede al proxy di restituire una rappresentazione della risorsa CoAP identificata dal Request-URI.
In caso di successo, viene restituita una risposta 200 (OK). Il payload della risposta deve essere una rappresentazione della risorsa CoAP di destinazione, e i campi di intestazione Content-Type e Content-Encoding devono essere impostati di conseguenza (MUST). La risposta deve indicare una direttiva max-age che indichi un valore non superiore al tempo rimanente in cui la rappresentazione può essere considerata fresca (MUST). Se la risposta CoAP ha un'opzione ETag, il proxy dovrebbe includere un campo di intestazione ETag nella risposta.
Un client può influenzare l'elaborazione di una richiesta GET includendo le seguenti opzioni:
Accept: Il tipo di media più preferito del campo di intestazione HTTP Accept in una richiesta viene mappato su un'opzione Accept di CoAP. Gli intervalli di tipi di media, i parametri e le estensioni di HTTP Accept non sono supportati dall'opzione Accept di CoAP. Se il proxy non può inviare una risposta accettabile secondo il valore combinato del campo Accept, allora il proxy invia una risposta 406 (Not Acceptable). Il proxy può quindi ritentare la richiesta con altri tipi di media dal campo di intestazione HTTP Accept (MAY).
Conditional GETs: Le richieste HTTP GET condizionali che includono un campo request-header "If-Match" o "If-None-Match" possono essere mappate su una corrispondente richiesta CoAP. I campi request-header "If-Modified-Since" e "If-Unmodified-Since" non sono supportati direttamente da CoAP ma sono implementati localmente da un proxy di caching.
10.2.3. HEAD
Il metodo HEAD è identico a GET, tranne per il fatto che il server non deve restituire un message-body nella risposta (MUST NOT).
Sebbene non esista un equivalente diretto del metodo HEAD di HTTP in CoAP, un proxy HTTP-CoAP risponde alle richieste HEAD per le risorse CoAP, e gli header HTTP vengono restituiti senza un message-body.
Nota implementativa: Un proxy HTTP-CoAP potrebbe voler provare a usare un'opzione di block-wise transfer [BLOCK] per minimizzare la quantità di dati effettivamente trasferiti, ma deve essere preparato al caso in cui l'origin server non supporti i block-wise transfers.
10.2.4. POST
Il metodo POST richiede al proxy di far elaborare dall'origin server CoAP la rappresentazione acclusa nella richiesta. La funzione effettiva eseguita dal metodo POST è determinata dall'origin server e dipende dalla risorsa identificata dall'URI della richiesta.
Se l'azione eseguita dal metodo POST non produce una risorsa che possa essere identificata da un URI, deve essere restituita al client una risposta 200 (OK) o 204 (No Content) (MUST). Se una risorsa è stata creata sull'origin server, deve essere restituita una risposta 201 (Created) (MUST).
Se una qualsiasi delle opzioni Location-* è presente nella risposta CoAP, viene restituito un campo di intestazione Location costruito dai valori di queste opzioni.
10.2.5. PUT
Il metodo PUT richiede al proxy di aggiornare o creare la risorsa CoAP identificata dal Request-URI con la rappresentazione acclusa.
Se una nuova risorsa viene creata al Request-URI, viene restituita al client una risposta 201 (Created). Se una risorsa esistente viene modificata, viene inviato il Response Code 200 (OK) o 204 (No Content) per indicare il completamento con successo della richiesta.
10.2.6. DELETE
Il metodo DELETE richiede al proxy di eliminare la risorsa CoAP identificata dal Request-URI presso l'origin server CoAP.
Una risposta di successo è 200 (OK) se la risposta include un'entità che descrive lo stato, oppure 204 (No Content) se l'azione è stata eseguita ma la risposta non include un'entità.
10.2.7. CONNECT
Questo metodo attualmente non può essere soddisfatto da una funzione di proxy HTTP-CoAP, poiché il tunneling da TLS a DTLS non è ancora stato specificato. Per ora, viene restituito al client un errore 501 (Not Implemented).