request

HTTP request types and utilities

Core request types and functions for working with HTTP requests in Dream. Includes request methods, path parameters, query parameters, and request inspection.

Quick Example

import dream/http/request.{type Request}

pub fn show_user(request: Request, context, services) {
  // Extract path parameter
  case request.get_int_param(request, "id") {
    Ok(id) -> {
      // Get query parameter
      let format = request.get_query_param(request.query, "format")
      
      // Access request data
      let method = request.method  // Get, Post, etc.
      let path = request.path      // "/users/123"
      let body = request.body      // Request body as string
      
      // Build response...
    }
    Error(msg) -> // Handle error
  }
}

Types

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.

Example

import dream/http/request.{Get, Post, Put, Delete}
import dream/router

router.new
|> router.route(Get, "/users", list_users, [])
|> router.route(Post, "/users", create_user, [])
|> router.route(Put, "/users/:id", update_user, [])
|> router.route(Delete, "/users/:id", delete_user, [])

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),
)

Protocol

</>

HTTP protocol type

Specifies whether the request came over HTTP or HTTPS.

Example

case request.protocol {
  Http -> // Insecure connection
  Https -> // Secure connection
}

pub type Protocol {
  Http
  Https
}

Constructors

```
Http
```
```
Https
```

Request

</>

HTTP request type

Represents a complete HTTP request with all its data. This is what your controllers receive as their first parameter.

Fields

method: HTTP method (Get, Post, Put, etc.)
protocol: HTTP or HTTPS
version: HTTP version (Http1, Http2, Http3)
path: Request path (e.g., “/users/123”)
query: Raw query string (e.g., “format=json&page=2”)
params: Path parameters extracted by router (e.g., [#(“id”, “123”)])
host: Host header value (e.g., “example.com”)
port: Port number (e.g., 443)
remote_address: Client IP address
body: Request body as string
headers: List of HTTP headers
cookies: List of cookies
content_type: Content-Type header value
content_length: Content-Length header value

Example

pub fn show_user(request: Request, context, services) {
  // Access request data
  let method = request.method      // Get
  let path = request.path          // "/users/123"
  let body = request.body          // Request body
  let headers = request.headers    // All headers
  let cookies = request.cookies    // All cookies
  
  // Extract path parameter
  case get_int_param(request, "id") {
    Ok(id) -> show_user_by_id(services.db, id)
    Error(msg) -> error_response(msg)
  }
}

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.Header),
    cookies: List(cookie.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.Header),
  cookies: List(cookie.Cookie),
  content_type: option.Option(String),
  content_length: option.Option(Int),
)

Version

</>

HTTP version type

Specifies which HTTP protocol version was used. Most requests will be Http1 (HTTP/1.1).

Example

case request.version {
  Http1 -> // HTTP/1.1
  Http2 -> // HTTP/2
  Http3 -> // HTTP/3 (QUIC)
}

pub type Version {
  Http1
  Http2
  Http3
}

Constructors

```
Http1
```
```
Http2
```
```
Http3
```

Values

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

is_method

</>

pub fn is_method(request: Request, method: Method) -> Bool

Check if request method matches

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)

set_params

</>

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

Create a new request with updated params