Create a new Dream instance with explicit configuration

⚠️ Warning: This is a low-level constructor

This function is primarily for internal Dream framework use. Most users should use the builder pattern via dream/servers/mist/server.new() instead.

When You Might Need This

You might use this if:

• You’re building custom server adapters for Dream
• You’re testing Dream internals
• You need to construct a Dream instance programmatically with all fields at once

Better Alternative

Use the builder pattern for better readability and type safety:

server.new()
|> server.context(MyContext)
|> server.services(MyServices)
|> server.router(my_router)
|> server.max_body_size(10_000_000)
|> server.bind("0.0.0.0")

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

Get the bind interface configured for this Dream instance

Returns the network interface the server will bind to if configured, or None if using the default interface.

Example

let app = server.new() |> server.bind("0.0.0.0")
case dream.get_bind_interface(app) {
  Some(interface) -> // Will bind to specified interface
  None -> // Will use default interface
}

Get the context configured for this Dream instance

Returns the context value that will be passed to all controllers.

Example

let app = server.new() |> server.context(MyContext(user: None))
let ctx = dream.get_context(app)

Get the max body size configured for this Dream instance

Returns the maximum request body size in bytes. Requests with bodies larger than this will be rejected.

Example

let app = server.new() |> server.max_body_size(5_000_000)
dream.get_max_body_size(app) // Returns 5_000_000

Get the router configured for this Dream instance

Returns the router if one has been set, or None if not yet configured.

Example

let app = server.new() |> server.router(my_router)
case dream.get_router(app) {
  Some(router) -> // Router is configured
  None -> // No router yet
}

Get the underlying server instance from a Dream instance

⚠️ Warning: This breaks Dream’s server abstraction

This function exposes the underlying server implementation (currently mist.Builder). Using this in your application code creates tight coupling to Mist and prevents Dream from switching server implementations in the future.

The risks_understood Parameter

You must explicitly pass risks_understood: True to call this function. Passing False will panic. This forces you to consciously acknowledge that you’re breaking Dream’s abstraction.

When You Might Need This

You might legitimately need this if:

• You need to configure Mist-specific features not exposed by Dream
• You’re integrating with libraries that expect raw Mist types
• You’re debugging server-level issues

Risks You’re Accepting

By passing risks_understood: True, you acknowledge:

• Vendor lock-in: Your code becomes coupled to Mist
• Breaking changes: If Dream switches servers or upgrades Mist, your code breaks
• Lost abstractions: You bypass Dream’s carefully designed API

Better Alternatives

Before using this, check if Dream provides:

• server.bind() for network interface configuration
• server.max_body_size() for request size limits
• Or open a GitHub issue requesting the feature you need

Example

// You must explicitly acknowledge the risks
let mist_server = dream.get_server(app, risks_understood: True)
// Now you have raw Mist types - your code is coupled to Mist

If you must use this, isolate it in a single module and document why.

Panics

Panics if risks_understood is False. You must pass True to proceed.

Get the services configured for this Dream instance

Returns the services if they have been set, or None if not yet configured.

Example

let app = server.new() |> server.services(my_services)
case dream.get_services(app) {
  Some(services) -> // Services are configured
  None -> // No services yet
}

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