dream - v2.1.0

dream/dream

Core Dream server type and shared functionality

This module provides the generic Dream server type and core routing functionality that is shared across all server implementations.

Most applications will use dream/servers/mist/server instead of this module directly. This module contains the core types and routing logic that the server implementations build upon.

Types

Dream

</>

Generic Dream server type

Represents a configured Dream web server, parameterized over:

  • server: The underlying server implementation (e.g., Mist)
  • context: Your application’s context type
  • services: Your application’s services type

This type holds all the configuration needed to run a web server: router, context template, services, and server-specific settings.

Fields

  • server: The underlying HTTP server (Mist Builder)
  • router: Optional router with all routes configured
  • context: Template context cloned for each request
  • services: Optional services instance (database, cache, etc.)
  • max_body_size: Maximum allowed request body size in bytes

Type Parameters

The Dream type is generic over three parameters:

  1. server: The underlying server type (usually Mist)
  2. context: Your application’s context type
  3. services: Your application’s services type

This allows the type system to verify that your router, controllers, and middleware all use compatible types.

Example

import dream/servers/mist/server as dream
import mist.{type Connection, type ResponseData}

// Your application types
pub type MyContext {
  MyContext(request_id: String, user: Option(User))
}

pub type Services {
  Services(db: Connection, cache: Cache)
}

// Dream server with your types
// Type: Dream(mist.Builder(Connection, ResponseData), MyContext, Services)
let server = 
  dream.new()
  |> dream.context(MyContext(request_id: "", user: None))
  |> dream.services(Services(db: my_db, cache: my_cache))
  |> dream.router(my_router)

pub type Dream(server, context, services) {
  Dream(
    server: server,
    router: option.Option(router.Router(context, services)),
    context: context,
    services: option.Option(services),
    max_body_size: Int,
  )
}

Constructors

Values

execute_route

</> 
pub fn execute_route(
  route: router.Route(context, services),
  request: request.Request,
  params: List(#(String, String)),
  context: context,
  services: services,
) -> response.Response

Execute a route with its params, middleware, and controller

Helper function to execute a route that’s already been matched. Used by route_request and can be called directly when route is already known (e.g., in server handlers that need to find the route first to determine if it’s streaming).

Parameters

  • route: The matched route to execute
  • request: HTTP request (may have body/stream already attached)
  • params: Path parameters extracted from the route pattern
  • context: Application context
  • services: Application services

Returns

HTTP response from the controller

</> 
pub fn parse_cookie_string(
  cookie_string: String,
) -> List(cookie.Cookie)

Parse a cookie header string into a list of cookies

Parses the raw cookie header value format (“name1=value1; name2=value2”) into a list of Cookie objects with simple cookies (no attributes).

Parameters

  • cookie_string: Raw Cookie header value

Returns

List of parsed simple cookies

Example

let cookie_str = "session=abc123; theme=dark; lang=en"
let cookies = parse_cookie_string(cookie_str)
// Returns: [
//   simple_cookie("session", "abc123"),
//   simple_cookie("theme", "dark"),
//   simple_cookie("lang", "en")
// ]

parse_cookies_from_headers

</> 
pub fn parse_cookies_from_headers(
  headers: List(header.Header),
) -> List(cookie.Cookie)

Parse cookies from HTTP headers

Extracts cookies from the Cookie header in a list of headers. Parses the cookie string format (“name1=value1; name2=value2”) into a list of Cookie objects.

Parameters

  • headers: List of HTTP headers to search

Returns

List of parsed cookies (empty list if no Cookie header found)

Example

import dream/http/header.{Header}

let headers = [
  Header("Content-Type", "application/json"),
  Header("Cookie", "session=abc123; theme=dark"),
]

let cookies = parse_cookies_from_headers(headers)
// Returns: [
//   Cookie(name: "session", value: "abc123", ...),
//   Cookie(name: "theme", value: "dark", ...)
// ]

route_request

</> 
pub fn route_request(
  router_instance: router.Router(context, services),
  request: request.Request,
  context: context,
  services: services,
) -> response.Response

Route a request through the router

Takes an incoming HTTP request, matches it against the router’s routes, executes any middleware, calls the appropriate controller, and returns the response.

This is the core routing function that:

  1. Finds a matching route based on method and path
  2. Extracts path parameters (e.g., :id from /users/:id)
  3. Builds the middleware chain
  4. Executes middleware and controller
  5. Returns the response

If no route matches, returns a 404 response.

Parameters

  • router_instance: Router with all routes configured
  • request: HTTP request to route
  • context: Request-specific context
  • services: Application services (database, cache, etc.)

Returns

HTTP response from the controller or 404 if no route matches

Example

// Internal use - normally called by the request handler
let response = route_request(
  my_router,
  incoming_request,
  request_context,
  my_services
)
✨ Search Document