mongoose — API Reference

HTTP server and client for Donna, backed by Mongoose

v0.2.1By Nikolas Skyl <skylnikolas@gmail.com>MITRepository →

mongoose

HTTP server and client for Donna, backed by the Mongoose C library.

Server — blocking accept/respond loop:

import mongoose

pub fn main() -> Nil:
case mongoose.start(8080):
mongoose.Err(e) -> echo e
mongoose.Ok(server) ->
serve(server)

fn serve(server: mongoose.Server) -> Nil:
case mongoose.accept(server):
mongoose.Err(e) -> echo e
mongoose.Ok(req) ->
let body = "Hello from Donna!\n"
let _ = mongoose.respond(server, 200, "text/plain", body)
serve(server)

HTTP client — blocking fetch:

import mongoose

pub fn example() -> String:
case mongoose.get("http://example.com"):
mongoose.Err(e) -> e
mongoose.Ok(resp) -> mongoose.body(resp)

Types

pub type Server

An opaque handle to a running HTTP server.

Server(Int)

pub type Request

An HTTP request received by the server.

Use method, path, query, content_type, headers, and body to access fields.

Request(String, String, String, String, String, String)

pub type Response

An HTTP response received from a client fetch.

Use status and body to access fields.

Response(Int, String, String)

pub type Result(a)

Result of a server or client operation.

Ok(a)

Err(String)

pub type Event

An event from the server — either an HTTP request or a WebSocket event.

Http(Request)

WsOpen(String, String)

WsMsg(String, String)

WsClose(String)

Functions

pub fn serve(root: String, port: Int) -> Int

Serve a static directory at http://localhost:<port>.

This call blocks until the process is stopped.

import mongoose

pub fn main() -> Int:
  mongoose.serve("docs", 1313)

pub fn start(port: Int) -> Result(Server)

Start a dynamic HTTP server on the given port.

Returns a Server handle that you pass to accept and respond.

import mongoose

pub fn example() -> mongoose.Result(mongoose.Server):
  mongoose.start(8080)

pub fn accept(server: Server) -> Result(Request)

pub fn accept_event(server: Server) -> Result(Event)

Block until the next event — HTTP request or WebSocket event.

pub fn ws_send(server: Server, conn_id: String, msg: String) -> Nil

Send a WebSocket text message to a connected client.

pub fn ws_broadcast(server: Server, msg: String) -> Nil

Broadcast a WebSocket text message to all connected clients.

pub fn respond(server: Server, code: Int, ct: String, rbody: String) -> Nil

Send an HTTP response to the current pending request.

import mongoose

pub fn example(server: mongoose.Server) -> Nil:
  mongoose.respond(server, 200, "application/json", "{\"ok\":true}")

pub fn respond_with_headers(server: Server, code: Int, ct: String, hdrs: String, rbody: String) -> Nil

Like respond but with additional HTTP headers.

Pass headers as a string in "Key: Value\r\n" form.

pub fn respond_file(server: Server, status: Int, ct: String, path: String) -> Nil

Send a file from disk as the HTTP response, handling binary content correctly.

Use this instead of read_file + respond for images and other binary files.

pub fn stop(server: Server) -> Nil

Stop the server and release all resources.

pub fn get(url: String) -> Result(Response)

Perform a blocking HTTP GET request.

import mongoose

pub fn example() -> mongoose.Result(mongoose.Response):
  mongoose.get("http://httpbin.org/get")

pub fn post(url: String, body: String, content_type: String) -> Result(Response)

Perform a blocking HTTP POST request.

import mongoose

pub fn example() -> mongoose.Result(mongoose.Response):
  mongoose.post("http://httpbin.org/post", "{\"x\":1}", "application/json")

pub fn fetch(url: String, method: String, body: String, extra_headers: String) -> Result(Response)

Perform a blocking HTTP request with full control over method and headers.

pub fn method(req: Request) -> String

Return the HTTP method from a request (e.g. "GET", "POST").

pub fn path(req: Request) -> String

Return the URL path from a request (e.g. "/api/users").

pub fn query(req: Request) -> String

Return the raw query string from a request (e.g. "id=1&fmt=json").

pub fn content_type(req: Request) -> String

Return the Content-Type header from a request.

pub fn headers(req: Request) -> String

Return all request headers as a "Key: Value\r\n" blob.

pub fn body(req: Request) -> String

Return the request body.

pub fn status(resp: Response) -> Int

Return the HTTP status code from a response (e.g. 200, 404).

pub fn resp_content_type(resp: Response) -> String

Return the Content-Type header from a response.

pub fn resp_body(resp: Response) -> String

Return the response body.

pub fn is_ok(r: Result(a)) -> Bool

Return True when a Result is Ok.

pub fn is_err(r: Result(a)) -> Bool

Return True when a Result is Err.

pub fn read_file(pth: String) -> Result(String)

Read the contents of a file from disk.

Returns Err when the file does not exist or cannot be read.