Richieste e risposte

In http4s una Request[F] è un valore immutabile che contiene metodo, URI, intestazioni, versione HTTP e un body in streaming. La esamina con accessor puri e non la modifica mai direttamente.

Per modificare una richiesta, produca una copia tramite withHeaders, withUri o combinatori simili.

Il body di una richiesta o risposta è uno fs2.Stream[F, Byte]. Viene consumato in modo lazy e tramite effetti, quindi i payload di grandi dimensioni non devono mai risiedere interamente in memoria.

Di solito non deve gestire i byte grezzi: se ne occupa un EntityDecoder.

Un EntityDecoder[F, A] sa trasformare lo stream del body in un valore A. Chiami req.as[A] per decodificare; il risultato è F[A] e l'effetto fallisce se il body non è valido.

È disponibile un decoder integrato per String; quelli più ricchi provengono dai moduli JSON.

Per accedere all'oggetto richiesta all'interno di un caso, lo associ con @. Qui req identifica l'intera richiesta, mentre il pattern continua a confrontare metodo e percorso.

Senza il binder dispone solo delle parti destrutturate e non può leggere il body o le intestazioni.

Le intestazioni si trovano in request.headers. Usi headers.get[H] con un modello di intestazione tipizzato, oppure headers.get(CIString("X-Custom")) per nomi arbitrari.

Le intestazioni tipizzate, come Authorization e Content-Type, analizzano e convalidano automaticamente i propri valori.

I builder di risposta della DSL, come Ok, Created e NotFound, sono funzioni che restituiscono F[Response[F]]. Passando un argomento, imposta il body tramite un EntityEncoder.

Ogni builder corrisponde a un codice di stato, quindi Created(...) produce 201.

Per uno stato senza builder dedicato, o per personalizzarlo, costruisca un Response[F] con uno Status esplicito e concateni withEntity.

In questo modo ottiene il pieno controllo su stato, intestazioni e body in un'unica espressione.

Un EntityEncoder[F, A] serializza un valore nel body della risposta e imposta il Content-Type. Gli encoder per String e per i byte sono integrati; gli encoder JSON provengono da circe.

Quando passa un valore a Ok(value), http4s cerca implicitamente l'encoder.

Aggiunga le intestazioni passandole come argomenti aggiuntivi a un builder, oppure concateni .map(_.putHeaders(...)) all'effetto della risposta.

I modelli di intestazione tipizzati garantiscono valori formattati correttamente, ad esempio un'intestazione Location per una risposta 201 Created.

req.as[A] fa fallire l'effetto F quando il body non può essere decodificato. Usi req.attemptAs[A].value per ottenere un F[Either[DecodeFailure, A]] e risponda con 400 nel ramo sinistro.

In questo modo la gestione degli input non validi rimane esplicita e totale.

Imposti i cookie con response.addCookie(ResponseCookie(name, value)). Per i redirect, usi un builder 3xx e un'intestazione Location.

SeeOther(Location(uri)) esegue un 303, la risposta idiomatica per il post-redirect-get.

Le richieste e le risposte sono valori immutabili con body fs2 in streaming. Si esegue il decoding con as/attemptAs tramite EntityDecoder e l’encoding con EntityEncoder.

I builder impostano i codici di stato, gli header tipizzati mantengono la sicurezza dei tipi e cookie e redirect sono semplicemente trasformazioni della risposta.