Further documentation

Author: lpil

src/gleam/http.gleam

@@ -5,12 +5,12 @@
 ////
 //// This module does not implement a HTTP client or HTTP server, but it can be used as a base for them.
 
-import gleam/dynamic.{type DecodeError, type Dynamic, DecodeError}
-import gleam/string
 import gleam/bit_array
-import gleam/result
-import gleam/list
 import gleam/bool
+import gleam/dynamic.{type DecodeError, type Dynamic, DecodeError}
+import gleam/list
+import gleam/result
+import gleam/string
 
 /// HTTP standard method as defined by [RFC 2616](https://tools.ietf.org/html/rfc2616),
 /// and PATCH which is defined by [RFC 5789](https://tools.ietf.org/html/rfc5789).
@@ -112,6 +112,7 @@ pub fn method_from_dynamic(value: Dynamic) -> Result(Method, List(DecodeError))
 
 pub type MultipartHeaders {
   /// The headers for the part have been fully parsed.
+  /// Header keys are all lowercase.
   MultipartHeaders(
     headers: List(Header),
     /// The remaining content that has not yet been parsed. This will contain
@@ -270,8 +271,7 @@ fn parse_headers_after_prelude(
   // compiler support this.
 
   use <- bool.guard(
-    when: dsize
-    < required_size,
+    when: dsize < required_size,
     return: more_please_headers(parse_headers_after_prelude(_, boundary), data),
   )
 
@@ -561,7 +561,7 @@ fn do_method_from_dynamic(a: Dynamic) -> Result(Method, nil)
 @external(javascript, "../gleam_http_native.mjs", "decode_method")
 fn do_method_from_dynamic(a: Dynamic) -> Result(Method, Nil)
 
-/// A HTTP header is a key-value pair. Header keys should be all lowercase
+/// A HTTP header is a key-value pair. Header keys must be all lowercase
 /// characters.
 pub type Header =
   #(String, String)

src/gleam/http/request.gleam

@@ -1,17 +1,21 @@
-import gleam/result
-// TODO: validate_req
 import gleam/http.{type Header, type Method, type Scheme, Get}
 import gleam/http/cookie
-import gleam/option.{type Option}
-import gleam/uri.{type Uri, Uri}
 import gleam/list
+import gleam/option.{type Option}
+import gleam/result
 import gleam/string
 import gleam/string_builder
+import gleam/uri.{type Uri, Uri}
 
-// TODO: document
+/// A HTTP request.
+///
+/// The body of the request is parameterised. The HTTP server or client you are
+/// using will have a particular set of types it supports for the body.
+/// 
 pub type Request(body) {
   Request(
     method: Method,
+    /// The request headers. The keys must always be lowercase.
     headers: List(Header),
     body: body,
     scheme: Scheme,
@@ -66,13 +70,20 @@ pub fn from_uri(uri: Uri) -> Result(Request(String), Nil) {
 ///
 /// If the request does not have that header then `Error(Nil)` is returned.
 ///
+/// Header keys are always lowercase in `gleam_http`. To use any uppercase
+/// letter is invalid.
+///
 pub fn get_header(request: Request(body), key: String) -> Result(String, Nil) {
   list.key_find(request.headers, string.lowercase(key))
 }
 
 /// Set the header with the given value under the given header key.
 ///
 /// If already present, it is replaced.
+///
+/// Header keys are always lowercase in `gleam_http`. To use any uppercase
+/// letter is invalid.
+///
 pub fn set_header(
   request: Request(body),
   key: String,
@@ -86,6 +97,10 @@ pub fn set_header(
 ///
 /// Similar to `set_header` except if the header already exists it prepends
 /// another header with the same key.
+///
+/// Header keys are always lowercase in `gleam_http`. To use any uppercase
+/// letter is invalid.
+///
 pub fn prepend_header(
   request: Request(body),
   key: String,

src/gleam/http/response.gleam

@@ -1,13 +1,22 @@
-import gleam/result
 import gleam/http.{type Header}
 import gleam/http/cookie
 import gleam/list
-import gleam/string
 import gleam/option
+import gleam/result
+import gleam/string
 
-// TODO: document
+/// A HTTP response.
+///
+/// The body of the request is parameterised. The HTTP server or client you are
+/// using will have a particular set of types it supports for the body.
+/// 
 pub type Response(body) {
-  Response(status: Int, headers: List(Header), body: body)
+  Response(
+    status: Int,
+    /// The request headers. The keys must always be lowercase.
+    headers: List(Header),
+    body: body,
+  )
 }
 
 /// Update the body of a response using a given result returning function.
@@ -43,6 +52,10 @@ pub fn get_header(response: Response(body), key: String) -> Result(String, Nil)
 /// Set the header with the given value under the given header key.
 ///
 /// If the response already has that key, it is replaced.
+///
+/// Header keys are always lowercase in `gleam_http`. To use any uppercase
+/// letter is invalid.
+///
 pub fn set_header(
   response: Response(body),
   key: String,
@@ -56,6 +69,10 @@ pub fn set_header(
 ///
 /// Similar to `set_header` except if the header already exists it prepends
 /// another header with the same key.
+///
+/// Header keys are always lowercase in `gleam_http`. To use any uppercase
+/// letter is invalid.
+///
 pub fn prepend_header(
   response: Response(body),
   key: String,