add documentation

Author: CrowdHailer

src/gleam/http.gleam

@@ -499,8 +499,8 @@ fn parse_cookie_list(cookie_string) {
       case string.split_once(string.trim(pair), "=") {
         Ok(tuple("", _)) -> Error(Nil)
         Ok(tuple(key, value)) -> {
-            let key = string.trim(key)
-            let value = string.trim(value)
+          let key = string.trim(key)
+          let value = string.trim(value)
           try _ = check_token(bit_string.from_string(key))
           try _ = check_token(bit_string.from_string(value))
           Ok(tuple(key, value))
@@ -512,14 +512,16 @@ fn parse_cookie_list(cookie_string) {
 }
 
 /// Fetch the cookies sent in a request.
+///
+/// Note badly formed cookie pairs will be ignored.
 pub fn get_req_cookies(req) -> List(tuple(String, String)) {
   let Request(headers: headers, ..) = req
 
   headers
   |> list.filter_map(
     fn(header) {
-      let tuple(key, value) = header
-      case key {
+      let tuple(name, value) = header
+      case name {
         "cookie" -> Ok(parse_cookie_list(value))
         _ -> Error(Nil)
       }
@@ -528,7 +530,10 @@ pub fn get_req_cookies(req) -> List(tuple(String, String)) {
   |> list.flatten()
 }
 
-pub fn set_req_cookie(req, key, value) {
+/// Send a cookie with a request
+///
+/// Multiple cookies are added to the same cookie header.
+pub fn set_req_cookie(req, name, value) {
   let Request(
     method: method,
     headers: headers,
@@ -539,7 +544,7 @@ pub fn set_req_cookie(req, key, value) {
     path: path,
     query: query,
   ) = req
-  let new_cookie_string = string.join([key, value], "=")
+  let new_cookie_string = string.join([name, value], "=")
 
   let tuple(cookies_string, headers) = case list.key_pop(headers, "cookie") {
     Ok(tuple(cookies_string, headers)) -> {
@@ -564,14 +569,20 @@ pub fn set_req_cookie(req, key, value) {
   )
 }
 
-pub fn set_resp_cookie(resp, key, value, attributes) {
+/// Set a cookie value for a client
+///
+/// The attributes record is defined in `gleam/http/cookie`
+pub fn set_resp_cookie(resp, name, value, attributes) {
   prepend_resp_header(
     resp,
     "set-cookie",
-    cookie.set_cookie_string(key, value, attributes),
+    cookie.set_cookie_string(name, value, attributes),
   )
 }
 
-pub fn expire_resp_cookie(resp, key, attributes) {
-  set_resp_cookie(resp, key, "", cookie.expire_attributes(attributes))
+/// Expire a cookie value for a client
+///
+/// Not the attributes value should be the same as when the response cookie was set.
+pub fn expire_resp_cookie(resp, name, attributes) {
+  set_resp_cookie(resp, name, "", cookie.expire_attributes(attributes))
 }

src/gleam/http/cookie.gleam

@@ -3,26 +3,30 @@ import gleam/list
 import gleam/option.{Option, Some}
 import gleam/string
 
-const epoch = "aa"
+const epoch = "Expires=Thu, 01 Jan 1970 00:00:00 GMT"
 
+/// Policy options for the SameSite cookie attribute
+///
+/// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite
 pub type SameSitePolicy {
   Lax
   Strict
   None
 }
 
+/// Attributes of a cookie when sent to a client in the `set-cookie` header.
 pub type Attributes {
   Attributes(
     max_age: Option(Int),
     domain: Option(String),
     path: Option(String),
     secure: Bool,
     http_only: Bool,
-    // TODO I don't think it needs Option
     same_site: Option(SameSitePolicy),
   )
 }
 
+/// Helper to create empty `Attributes` for a cookie.
 pub fn empty_attributes() {
   Attributes(
     max_age: option.None,
@@ -34,6 +38,7 @@ pub fn empty_attributes() {
   )
 }
 
+/// Helper to create sensible default attributes for a set cookie.
 pub fn default_attributes() {
   Attributes(
     max_age: option.None,
@@ -53,6 +58,8 @@ fn same_site_to_string(policy) {
   }
 }
 
+/// Update the MaxAge of a set of attributes to 0.
+/// This informes the client that the cookie should be expired.
 pub fn expire_attributes(attributes) {
   let Attributes(
     max_age: _max_age,
@@ -87,7 +94,7 @@ fn attributes_to_list(attributes) {
     // Only when deleting cookies is the exception made to use the old format,
     // to ensure complete clearup of cookies if required by an application.
     case max_age {
-      Some(0) -> Some(["Expires=Thu, 01 Jan 1970 00:00:00 GMT"])
+      Some(0) -> Some([epoch])
       _ -> option.None
     },
     option.map(max_age, fn(max_age) { ["MaxAge=", int.to_string(max_age)] }),
@@ -109,8 +116,11 @@ fn attributes_to_list(attributes) {
   |> list.filter_map(option.to_result(_, Nil))
 }
 
-pub fn set_cookie_string(key, value, attributes) {
-  [[key, "=", value], ..attributes_to_list(attributes)]
+/// Serialize a cookie and attributes.
+///
+/// This is the serialization of a cookie for the `set-cookie` header
+pub fn set_cookie_string(name, value, attributes) {
+  [[name, "=", value], ..attributes_to_list(attributes)]
   |> list.map(string.join(_, ""))
   |> string.join("; ")
 }

test/gleam/http_test.gleam

@@ -859,6 +859,6 @@ pub fn expire_resp_cookie_test() {
   |> http.expire_resp_cookie("k1", cookie.default_attributes())
   |> http.get_resp_header("set-cookie")
   |> should.equal(
-    Ok("k1=; expires=Thu, 01 Jan 1970 00:00:00 GMT; MaxAge=0; Path=/; HttpOnly"),
+    Ok("k1=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; MaxAge=0; Path=/; HttpOnly"),
   )
 }