transaction

HTTP requests and responses

Core HTTP types for Dream applications. For response builders and status codes, see the dream_json module.

Path Parameters

Extract and convert path parameters from routes:

pub fn show_user(request: Request, _context, _services) -> Response {
  let result = get_int_param(request, "id")
  
  case result {
    Ok(id) -> json_response(ok, user_to_json(id))
    Error(msg) -> json_response(bad_request, error_json(msg))
  }
}

Format Detection

PathParam automatically detects format extensions:

// Request to /users/123.json
let result = get_param(request, "id")

case result {
  Ok(param) -> {
    // param.value is "123"
    // param.format is Some("json")
    // param.as_int is Ok(123)
    use_param_data(param)
  }
  Error(msg) -> handle_param_error(msg)
}

Use this for content negotiation without query strings.

Types

</>

HTTP cookie type

pub type Cookie {
  Cookie(
    name: String,
    value: String,
    expires: option.Option(Int),
    max_age: option.Option(Int),
    domain: option.Option(String),
    path: option.Option(String),
    secure: Bool,
    http_only: Bool,
    same_site: option.Option(SameSite),
  )
}

Constructors

Cookie(
  name: String,
  value: String,
  expires: option.Option(Int),
  max_age: option.Option(Int),
  domain: option.Option(String),
  path: option.Option(String),
  secure: Bool,
  http_only: Bool,
  same_site: option.Option(SameSite),
)

</>

HTTP header type

pub type Header {
  Header(name: String, value: String)
}

Constructors

```
Header(name: String, value: String)
```

Method

</>

HTTP request methods

The standard HTTP methods your routes can handle. Use these in your router to specify which method a route responds to.

pub type Method {
  Post
  Get
  Put
  Delete
  Patch
  Options
  Head
}

Constructors

```
Post
```
```
Get
```
```
Put
```
```
Delete
```
```
Patch
```
```
Options
```
```
Head
```

PathParam

</>

Path parameter with automatic type conversion and format detection

When you extract a path parameter with get_param(), you get a PathParam that:

Detects format extensions (e.g., “123.json” → value=“123”, format=Some(“json”))
Provides automatic conversions to Int and Float
Keeps the raw value for custom parsing

This makes content negotiation and type conversion trivial.

pub type PathParam {
  PathParam(
    raw: String,
    value: String,
    format: option.Option(String),
    as_int: Result(Int, Nil),
    as_float: Result(Float, Nil),
  )
}

Constructors

PathParam(
  raw: String,
  value: String,
  format: option.Option(String),
  as_int: Result(Int, Nil),
  as_float: Result(Float, Nil),
)

Request

</>

HTTP request type

pub type Request {
  Request(
    method: Method,
    protocol: Protocol,
    version: Version,
    path: String,
    query: String,
    params: List(#(String, String)),
    host: option.Option(String),
    port: option.Option(Int),
    remote_address: option.Option(String),
    body: String,
    headers: List(Header),
    cookies: List(Cookie),
    content_type: option.Option(String),
    content_length: option.Option(Int),
  )
}

Constructors

Request(
  method: Method,
  protocol: Protocol,
  version: Version,
  path: String,
  query: String,
  params: List(#(String, String)),
  host: option.Option(String),
  port: option.Option(Int),
  remote_address: option.Option(String),
  body: String,
  headers: List(Header),
  cookies: List(Cookie),
  content_type: option.Option(String),
  content_length: option.Option(Int),
)

Response

</>

HTTP response type

The status field is an Int (HTTP status code like 200, 404, 500). For JSON encoding utilities, use dream_json.

pub type Response {
  Response(
    status: Int,
    body: ResponseBody,
    headers: List(Header),
    cookies: List(Cookie),
    content_type: option.Option(String),
  )
}

Constructors

Response(
  status: Int,
  body: ResponseBody,
  headers: List(Header),
  cookies: List(Cookie),
  content_type: option.Option(String),
)

ResponseBody

</>

Response body types

Supports text, binary data, and streaming for different use cases:

Text for JSON, HTML, plain text
Bytes for images, PDFs, files
Stream for large files, AI responses, real-time data

pub type ResponseBody {
  Text(String)
  Bytes(BitArray)
  Stream(yielder.Yielder(BitArray))
}

Constructors

```
Text(String)
```
```
Bytes(BitArray)
```
```
Stream(yielder.Yielder(BitArray))
```

Values

add_header

</>

pub fn add_header(
  headers: List(Header),
  name: String,
  value: String,
) -> List(Header)

Add a header without removing existing ones with the same name

get_header

</>

pub fn get_header(
  headers: List(Header),
  name: String,
) -> option.Option(String)

Get the value of a header by name (case-insensitive)

get_int_param

</>

pub fn get_int_param(
  request: Request,
  name: String,
) -> Result(Int, String)

Extract a path parameter as an integer

Returns a Result with a custom error message if the parameter is missing or cannot be converted to an integer.

Examples

// Route: /users/:id
// Request: /users/123
case get_int_param(request, "id") {
  Ok(id) -> show_user(id)
  Error(msg) -> json_response(status.bad_request, error_json(msg))
}

get_param

</>

pub fn get_param(
  request: Request,
  name: String,
) -> Result(PathParam, String)

Extract a path parameter by name

Returns a PathParam with automatic type conversion and format detection. If the parameter doesn’t exist, returns an error message.

For common cases, use get_int_param() or get_string_param() instead, which return Result(Int, String) or Result(String, String) with custom error messages.

Examples

// Route: /users/:id
// Request: /users/123
case get_param(request, "id") {
  Ok(param) -> {
    param.value  // "123"
    param.as_int // Ok(123)
  }
  Error(msg) -> // handle error
}

// Route: /users/:id
// Request: /users/123.json
case get_param(request, "id") {
  Ok(param) -> {
    param.value  // "123"
    param.format // Some("json")
    param.as_int // Ok(123)
  }
  Error(msg) -> // handle error
}

// For simple integer extraction, use get_int_param:
case get_int_param(request, "id") {
  Ok(id) -> show_user(id)
  Error(msg) -> json_response(status.bad_request, error_json(msg))
}

get_query_param

</>

pub fn get_query_param(
  query: String,
  name: String,
) -> option.Option(String)

Get a query parameter value from the raw query string

Properly decodes URL-encoded values (e.g., %20 → space, %26 → &) Returns None if the parameter is not found.

get_string_param

</>

pub fn get_string_param(
  request: Request,
  name: String,
) -> Result(String, String)

Extract a path parameter as a string

Returns a Result with a custom error message if the parameter is missing.

Examples

// Route: /users/:name
// Request: /users/john
case get_string_param(request, "name") {
  Ok(name) -> show_user_by_name(name)
  Error(msg) -> json_response(status.bad_request, error_json(msg))
}

has_content_type

</>

pub fn has_content_type(
  request: Request,
  content_type: String,
) -> Bool

Check if request has a specific content type

method_to_string

</>

pub fn method_to_string(method: Method) -> String

Convert Method to its string representation

parse_method

</>

pub fn parse_method(str: String) -> option.Option(Method)

Parse a string to Method (case-insensitive)

remove_header

</>

pub fn remove_header(
  headers: List(Header),
  name: String,
) -> List(Header)

Remove a header by name (case-insensitive)

secure_cookie

</>

pub fn secure_cookie(name: String, value: String) -> Cookie

Create a secure cookie for sensitive data

Sets secure=True, httpOnly=True, and sameSite=Strict. Use this for session IDs, authentication tokens, or any sensitive data. The httpOnly flag prevents JavaScript access, protecting against XSS attacks.

set_cookie

</>

pub fn set_cookie(
  cookies: List(Cookie),
  cookie: Cookie,
) -> List(Cookie)

Set or replace a cookie

set_header

</>

pub fn set_header(
  headers: List(Header),
  name: String,
  value: String,
) -> List(Header)

Set or replace a header

If the header exists, replaces its value. If not, adds it. Header names are case-insensitive but you should use standard casing for compatibility.

Example

response.headers
|> set_header("Cache-Control", "max-age=3600")
|> set_header("X-Custom-Header", "value")

set_params

</>

pub fn set_params(
  request: Request,
  new_params: List(#(String, String)),
) -> Request

Create a new request with updated params

simple_cookie

</>

pub fn simple_cookie(name: String, value: String) -> Cookie

Create a simple cookie with just name and value

Creates an unsecured cookie with no expiration. Use secure_cookie() for sensitive data like sessions or authentication tokens.