#Core

• HttpRequest -- an incoming HTTP request (method, URL, headers, body) with helpers for path extraction, query parsing, cookie reading, and typed body deserialization.
• HttpResponse -- an outgoing HTTP response (status code, headers, cookies, body) with a fluent builder API and factory methods for common status codes.
• StatusCode -- a comprehensive enum covering every IANA-registered HTTP status code, plus a Custom(Int) escape hatch.
• HttpMethod -- an enum for standard HTTP methods (GET, POST, PUT, etc.) with string round-tripping.
• Responder -- a trait that any type can implement to become a valid response body. Built-in implementations for String, Json, Bytes, HttpResponse, HttpRequest, and Html.
• BodyReader -- a trait for deserializing request bodies into typed values.

#Install

import {
  "bobzhang/crescent/core"
  ...
}

#HttpRequest

///|
test "construct and inspect a request" {
  let req = @core.HttpRequest(
    Get,
    "/users?page=2",
    { "Authorization": "Bearer token" },
    raw_body=b"",
  )
  debug_inspect(
    req,
    content=(
      #|{
      #|  http_method: Get,
      #|  url: "/users?page=2",
      #|  headers: { "Authorization": "Bearer token" },
      #|  raw_body: ...,
      #|  cached_path: None,
      #|  cached_query_params: None,
      #|}
    ),
  )
  assert_eq(req.path(), "/users")
  assert_eq(req.query_string(), Some("page=2"))
  assert_eq(req.get_query("page"), Some("2"))
  assert_eq(req.get_header("authorization"), Some("Bearer token"))
}

#Path and query parsing

///|
test "query parameters are percent-decoded" {
  let req = @core.HttpRequest(
      Get,
      "/search?q=hello%20world&lang=en",
      {},
      raw_body=b"",
    )
    |> x => { (x.get_query("q"), x.get_query("lang"), x.get_query("missing")) }
  debug_inspect(
    req,
    content=(
      #|(Some("hello world"), Some("en"), None)
    ),
  )
}

#Typed body reading

///|
test "read body as string" {
  let req = @core.HttpRequest(Post, "/", {}, raw_body=b"hello")
  let text : String = req.body()
  assert_eq(text, "hello")
}

///|
test "read body as JSON" {
  let req = @core.HttpRequest(Post, "/", {}, raw_body=b"{\"name\":\"Alice\"}")
  let body : Json = req.body()
  debug_inspect(
    body,
    content=(
      #|Object({ "name": String("Alice") })
    ),
  )
}

#JSON deserialization shorthand

///|
#warnings("-unnecessary_annotation")
struct CoreDocUser {
  name : String
  age : Int
} derive(FromJson, Eq, Debug)

///|
test "json shorthand parses typed value" {
  let req = @core.HttpRequest(
    Post,
    "/",
    {},
    raw_body=b"{\"name\":\"Bob\",\"age\":30}",
  )
  let user : CoreDocUser = req.json()
  debug_inspect(
    user,
    content=(
      #|{ name: "Bob", age: 30 }
    ),
  )
}

#Cookie reading

///|
test "read a cookie from the request" {
  let req = @core.HttpRequest(
    Get,
    "/",
    { "Cookie": "session=abc123; theme=dark" },
    raw_body=b"",
  )
  guard req.get_cookie("session") is Some(c) else {
    fail("expected session cookie")
  }
  assert_eq(c.value, "abc123")
  assert_eq(req.get_cookie("missing"), None)
}

#HttpResponse

#Factory methods

///|
test "factory methods set the right status code" {
  assert_eq(@core.HttpResponse::ok().status_code, OK)
  assert_eq(@core.HttpResponse::created().status_code, Created)
  assert_eq(@core.HttpResponse::not_found().status_code, NotFound)
  assert_eq(@core.HttpResponse::bad_request().status_code, BadRequest)
  assert_eq(
    @core.HttpResponse::internal_server_error().status_code,
    InternalServerError,
  )
}

#Fluent builder

///|
test "fluent response building" {
  let res = @core.HttpResponse::ok()
    .header("X-Request-Id", "abc-123")
    .body(@core.html("<h1>Hello</h1>"))
  assert_eq(res.status_code, OK)
  debug_inspect(
    res.headers.get("Content-Type"),
    content="Some(\"text/html; charset=utf-8\")",
  )
  debug_inspect(res.headers.get("X-Request-Id"), content="Some(\"abc-123\")")
}

#JSON responses

///|
test "json response sets content type and body" {
  let res = @core.HttpResponse::ok().json(({ "status": "ok" } : Json))
  debug_inspect(
    res.headers.get("Content-Type"),
    content="Some(\"application/json; charset=utf-8\")",
  )
}

#Redirects

///|
test "redirect helpers" {
  let r301 = @core.HttpResponse::redirect("/new")
  debug_inspect(
    r301,
    content=(
      #|{
      #|  status_code: MovedPermanently,
      #|  headers: { "Location": "/new" },
      #|  cookies: {},
      #|  raw_body: ...,
      #|}
    ),
  )

  let r302 = @core.HttpResponse::redirect_temporary("/temp")
  assert_eq(r302.status_code, Found)

  let r307 = @core.HttpResponse::redirect_307("/keep-method")
  assert_eq(r307.status_code, TemporaryRedirect)
}

#Cookies

///|
test "set and delete cookies" {
  let res = @core.HttpResponse::ok()
  res.set_cookie("session", "xyz", path="/", http_only=true, secure=true)
  guard res.cookies.get("session") is Some(c) else {
    fail("expected session cookie")
  }
  assert_eq(c.value, "xyz")
  assert_eq(c.path, Some("/"))
  assert_eq(c.http_only, Some(true))

  // Deleting sets Max-Age=0
  res.delete_cookie("session")
  guard res.cookies.get("session") is Some(deleted) else {
    fail("expected deleted cookie")
  }
  assert_eq(deleted.max_age, Some(0))
}

#Error responses

///|
test "error helper creates structured JSON body" {
  let res = @core.HttpResponse::error(BadRequest, "name is required")
  assert_eq(res.status_code, BadRequest)
  let body : String = res.read_body()
  assert_true(body.contains("name is required"))
  assert_true(body.contains("400"))
}

#StatusCode

///|
test "status code round-trips through integer" {
  assert_eq(@core.StatusCode::from_int(200), OK)
  assert_eq(@core.StatusCode::from_int(404), NotFound)
  let ok : @core.StatusCode = OK
  assert_eq(ok.to_int(), 200)
  // Unknown codes become Custom
  assert_eq(@core.StatusCode::from_int(599), Custom(599))
}

#HttpMethod

///|
test "method round-trips through string" {
  assert_eq(@core.HttpMethod::from_string("GET"), Get)
  let get : @core.HttpMethod = Get
  assert_eq(get.to_method_string(), "GET")
  // Unknown methods use Other
  let custom = @core.HttpMethod::from_string("PURGE")
  assert_eq(custom.to_method_string(), "PURGE")
}

#Traits

#trait Responder

///|
pub(open) trait Responder {
  fn options(Self, HttpResponse) -> Unit
  fn output(Self, Buffer) -> Unit
  fn output_bytes(Self) -> Bytes?
}

#String as a responder

///|
test "string responder sets text/plain" {
  let res = @core.HttpResponse(status_code=OK)
  let responder : &@core.Responder = "hello"
  responder.options(res)
  debug_inspect(
    res.headers.get("Content-Type"),
    content="Some(\"text/plain; charset=utf-8\")",
  )
}

#html() and text() helpers

///|
test "html helper sets text/html content type" {
  let res = @core.HttpResponse(status_code=OK)
  let responder = @core.html("<h1>Hello</h1>")
  responder.options(res)
  debug_inspect(
    res.headers.get("Content-Type"),
    content="Some(\"text/html; charset=utf-8\")",
  )
  let buf = Buffer()
  responder.output(buf)
  assert_eq(buf.contents(), @utf8.encode("<h1>Hello</h1>"))
}

#trait BodyReader

///|
pub(open) trait BodyReader {
  fn from_request(HttpRequest) -> Self raise
}

///|
test "read response body as typed value" {
  let res = @core.HttpResponse(status_code=OK, raw_body=b"hello")
  let text : String = res.read_body()
  assert_eq(text, "hello")
}