READMERabitLogic/mbit/core does not have a README file
#Handler
Handler function signature.
All route handlers and middleware share this signature.
#IRoutes
pub trait IRoutes {
fn get(String, Array[async (Context) -> Unit]) -> Unit
fn post(String, Array[async (Context) -> Unit]) -> Unit
fn put(String, Array[async (Context) -> Unit]) -> Unit
fn del(String, Array[async (Context) -> Unit]) -> Unit
fn patch(String, Array[async (Context) -> Unit]) -> Unit
fn head(String, Array[async (Context) -> Unit]) -> Unit
fn options(String, Array[async (Context) -> Unit]) -> Unit
fn any(String, Array[async (Context) -> Unit]) -> Unit
fn handle(Array[Method], String, Array[async (Context) -> Unit]) -> Unit
fn use_mw(async (Context) -> Unit) -> Unit
}IRoutes defines the common route registration methods.
#AppEnvironment
Supported deployment environments.
#AppEnvironment::from_string
Parse environment from string.
#AppEnvironment::to_string
Convert environment to string.
#Config
pub(all) struct Config {
values : Map[String, ConfigValue]
env : AppEnvironment
env_prefix : String
}A configuration store backed by environment variables and defaults.
#Config::environment
Current environment.
#Config::from_env
Load configuration from environment variables.
Reads all env vars matching the prefix and stores them as ConfigValues.
let cfg = Config::from_env()
let port = cfg.get_int("PORT", default=8080)#Config::get_bool
Get a bool config value, or a default if not set.
#Config::get_float
Get a float config value, or a default if not set.
#Config::get_int
Get an int config value, or a default if not set.
#Config::get_string
Get a string config value, or a default if not set.
#Config::is_development
Whether the current environment is development.
#Config::is_production
Whether the current environment is production.
#Config::new
Create an empty config with the given environment.
#ConfigValue
pub(all) enum ConfigValue {
ConfigString(String)
ConfigInt(Int64)
ConfigBool(Bool)
ConfigFloat(Double)
} derive(Debug)Config value types supported by the configuration system.
#ConfigValue::to_string
Convert ConfigValue to string.
#Context
pub(all) struct Context {
req : Request
reader : &Reader
conn : ResponseConn
params : Map[String, String]
query_cache : Map[String, String]?
body : String?
body_bytes : Bytes?
post_form_cache : Map[String, String]?
handlers : Array[async (Context) -> Unit]
index : Int
status_code : Int
written : Bool
aborted : Bool
size : Int
store : Map[String, Json]
errors : Array[String]
headers : Map[String, String]
}Context holds all per-request state.
#Context::abort
Abort the handler chain. No further handlers will be executed.
Does NOT write a response — you should call a render method separately.
#Context::abort_with_error
AbortWithError aborts with a status code and adds an error to the context.
#Context::abort_with_status
Abort with a specific status code and JSON error message.
#Context::abort_with_status_json
AbortWithStatusJSON aborts with a JSON error response.
Convenience method combining abort + JSON error response.
#Context::add_error
Add an error to the context's error list.
#Context::ascii_json
AsciiJSON serializes JSON with ASCII-only characters (escapes non-ASCII).
#Context::bind_api
Bind auto-detects content type and binds, aborting on failure.
See c.Bind() equivalent.
#Context::bind_form_api
BindForm binds form body. On failure, aborts with 400.
#Context::bind_header_api
BindHeader binds request headers. On failure, aborts with 400.
#Context::bind_json_api
BindJSON binds the request body as JSON. On failure, aborts with 400.
See c.BindJSON() equivalent.
#Context::bind_query_api
BindQuery binds query parameters. On failure, aborts with 400.
#Context::body_bytes
Read the full request body as raw bytes (lazy, cached).
Unlike body_string(), this preserves arbitrary binary content and never
fails on non-UTF-8 payloads (e.g. binary file uploads).
#Context::body_json
Parse the request body as JSON.
#Context::body_string
Read the full request body as a string (lazy, cached).
For binary bodies use body_bytes(); text decoding of non-UTF-8 payloads
yields an empty string (same as before).
#Context::content_type
Returns the value of the Content-Type request header.
#Context::cookie
Get a cookie value by name from the request headers.
let session = ctx.cookie("session_id")#Context::data
Send a response with custom content type.
#Context::data_from_reader
DataFromReader writes the specified content type and reads data
from the given reader, sending it as the response body.
ctx.data_from_reader(200, content_length, "application/octet-stream", reader)#Context::default_post_form
Get a post form value with a default fallback.
#Context::default_query
DefaultQuery returns the query value or a default.
See c.DefaultQuery() equivalent.
#Context::end_stream
End a stream response.
#Context::error
Error returns the last error in the context's error list.
See c.Errors.Last() equivalent.
#Context::errors_all
All collected errors.
#Context::file
Send a file as the response body with the given content type.
The file content is read from disk and sent inline.
ctx.file(200, "application/pdf", "./reports/annual.pdf")#Context::file_attachment
Send a file as an attachment (forces download with Content-Disposition).
See c.FileAttachment() equivalent.
#Context::file_from_fs
FileFromFS serves a file from a filesystem path.
See c.FileFromFS() equivalent.
#Context::flush
Flush writes any buffered data to the client.
See c.Writer.Flush() equivalent.
#Context::form_file
FormFile returns the content of an uploaded file from a multipart form.
The file is identified by the form field name.
Returns Some(content) if the file was found, None otherwise.
#Context::full_path
The full request path including query string.
#Context::get
Retrieve a value from the context store.
#Context::get_bool
Retrieve a Bool value from the context store.
#Context::get_duration
GetDuration retrieves a duration value (stored as Int64 nanoseconds) from the store.
See c.GetDuration() equivalent.
#Context::get_float64
Retrieve a Float64 value from the context store.
#Context::get_header
GetHeader is an alias for header() — for API compatibility.
See c.GetHeader() equivalent.
#Context::get_int64
Retrieve an Int64 value from the context store.
#Context::get_post_form_array
GetPostFormArray returns all values for a post form parameter key.
e.g., form with tag=a&tag=b → ["a", "b"]
#Context::get_post_form_file
GetPostFormFile returns the filename from a multipart form file upload.
Returns the filename extracted from the Content-Disposition header.
#Context::get_query_array
GetQueryArray returns all values for a query parameter key.
e.g., ?tag=a&tag=b → ["a", "b"]
#Context::get_raw_data
GetRawData returns the raw request body as a string.
See c.GetRawData() equivalent.
#Context::get_string
Retrieve a string value from the context store.
#Context::get_string_map
GetStringMap returns a string map from the store.
See c.GetStringMap() equivalent.
#Context::get_string_map_string
GetStringMapString returns a flat string map from the store.
See c.GetStringMapString() equivalent.
#Context::get_time
GetTime retrieves a time value (stored as Int64 nanoseconds) from the store.
See c.GetTime() equivalent.
#Context::handler_name
HandlerName returns the name of the last handler in the chain.
Useful for debugging and logging.
#Context::handler_names
HandlerNames returns the names of all handlers in the chain.
#Context::header
A request header value, if present.
Note: the underlying HTTP server lower-cases all request header keys
(moonbitlang/async/http parser does to_lower()), so lookups fall back
to the lower-cased key to stay correct under real HTTP traffic.
#Context::html
Render HTML.
#Context::html_template
Render an HTML template response using the global template store.
#Context::http_method
The HTTP method of the request (e.g., "GET", "POST").
#Context::indented_json
Render indented / pretty-printed JSON.
Same as json() but with indentation for readability.
#Context::is_aborted
Whether the chain has been aborted.
#Context::is_websocket
Check if the request is a WebSocket upgrade request.
#Context::is_written
Whether the response has been written.
#Context::json
Render JSON. This finalizes the response; no further writes are allowed.
#Context::jsonp
Render JSONP — wraps JSON in a callback function.
The callback name is taken from the callback query parameter.
See c.JSONP() equivalent.
#Context::keys
Keys returns all keys in the context store.
See c.Keys equivalent.
#Context::multipart_form
MultipartForm returns the full multipart form data as parsed fields.
Returns a map of field name → file content for simple file uploads.
#Context::must_bind
Like should_bind but raises a catchable Failure (recovered to 400/500 by
recovery()) if binding fails. Deliberately uses raise(Failure(...))
instead of abort() so a bad request cannot crash the server.
#Context::must_bind_with
MustBindWith binds using a custom binding function, raising a catchable
Failure (recovered by recovery()) instead of aborting on failure.
#Context::must_get
MustGet returns the value for the given key if it exists, otherwise raises
a catchable Failure (recovered to 500 by recovery()). Do NOT use
abort() here — it is a hard panic that terminates the whole process.
#Context::negotiate_format
Content negotiation: returns the best accepted content type from the
Accept header. If none matches, sets a 406 status and returns None.
match ctx.negotiate_format(["application/json", "text/html"]) {
Some("application/json") => ctx.json(200, data)
Some("text/html") => ctx.html(200, "<h1>Hello</h1>")
_ => () // 406 already set
}#Context::new
Create a new Context from the raw HTTP components and handler chain.
#Context::next
Next should be called only inside middleware.
It executes the remaining handlers in the chain.
This is the heart of the middleware chain pattern:
- Middleware runs code BEFORE c.next()
- c.next() yields to the next handler and waits for it
- Middleware runs code AFTER c.next() returns
#Context::no_content
Send a 204 No Content response.
#Context::param
Get a path parameter by name.
Route patterns like /api/article/:id populate ctx.param("id").
#Context::param_default
Get a path parameter, returning a default value if not present.
#Context::param_int64
Get a path parameter parsed as Int64.
#Context::params_all
All parsed path parameters.
#Context::path
The request path without the query string.
#Context::post_form
Get a value from the POST form body.
Parses the body as application/x-www-form-urlencoded on first access.
#Context::post_form_map
PostFormMap returns all POST form parameters as a map.
#Context::proto_buf
ProtoBuf renders a protobuf response (placeholder — returns JSON).
#Context::pure_json
Render PureJSON — writes JSON without escaping HTML characters.
(In MoonBit, the default JSON stringify does not escape HTML, so this is
equivalent to json() — included for API completeness.)
#Context::query
Get a query parameter by name.
#Context::query_default
Get a query parameter with a default fallback.
#Context::query_int
Get a query parameter parsed as Int.
#Context::query_int64
Get a query parameter parsed as Int64.
#Context::query_map
QueryMap returns all query parameters as a map.
See c.QueryMap() equivalent.
#Context::raw_data
Get the raw request body as a string.
#Context::redirect
Redirect to another URL.
#Context::render
Render dispatches to the appropriate renderer based on content type.
See c.Render() equivalent.
#Context::request
Request returns the raw HTTP request.
See c.Request equivalent.
#Context::reset
Reset the context state for reuse (used by HandleContext).
#Context::save_uploaded_file
SaveUploadedFile saves an uploaded file to the specified destination path.
Accepts raw Bytes so binary files are written verbatim.
match ctx.form_file("avatar") {
Some(content) => ctx.save_uploaded_file(content, "./uploads/avatar.png")
None => ctx.abort_with_status(400, "No file uploaded")
}#Context::secure_json
Render SecureJSON — prepends while(1); to prevent JSON hijacking.
See c.SecureJSON() equivalent.
#Context::set
Store a value in the context. Useful for middleware to pass data to handlers.
Example: auth middleware stores ctx.set("user_id", json).
#Context::set_accepted
SetAccepted sets the accepted content types for content negotiation.
See c.SetAccepted() equivalent.
#Context::set_cookie
Set a cookie in the response headers.
ctx.set_cookie("session_id", "abc123", max_age=3600, path="/", http_only=true)#Context::set_header
Set a response header.
#Context::set_headers
Set multiple response headers at once.
#Context::set_params
Set parsed path parameters (called by the router after matching).
#Context::should_bind
Auto-detect the content type and bind the request body to a struct.
Supports JSON (application/json) and form-encoded
(application/x-www-form-urlencoded).
Returns Some(value) on success, None on failure.
#Context::should_bind_form
ShouldBindForm binds form-encoded body to a struct.
#Context::should_bind_header
ShouldBindHeader binds request headers to a struct.
#Context::should_bind_json
ShouldBindJSON binds the JSON request body to a struct.
See c.ShouldBindJSON() equivalent.
#Context::should_bind_query
ShouldBindQuery binds query parameters to a struct.
See c.ShouldBindQuery() equivalent.
#Context::should_bind_uri
ShouldBindUri binds URI (path) parameters to a struct.
See c.ShouldBindUri() equivalent.
#Context::should_bind_with
ShouldBindWith binds using a custom binding function.
See c.ShouldBindWith() equivalent.
#Context::size
Returns the number of bytes written to the response so far.
See c.Writer.Size() equivalent.
#Context::sse
Stream a Server-Sent Event (SSE) to the client.
Sets the appropriate headers for SSE.
// Basic SSE
ctx.sse("message", "hello world")#Context::sse_ex
SSE with full options: id, retry, comment.
#Context::sse_flush
Flush the SSE response — sends buffered data to the client immediately.
#Context::sse_keepalive
SSE keep-alive — sends a comment-only event to prevent connection timeout.
Useful for long-lived SSE connections.
ctx.sse_keepalive("ping")#Context::status
Set the HTTP status code for the response.
#Context::stream
Stream writes a streaming response with the given status code and
content type. The writer callback receives a function that writes
chunks to the connection.
ctx.stream(200, "text/event-stream", fn(write) {
for i = 0; i < 10; i = i + 1 {
write("data: chunk " + i.to_string() + "\n\n")
}
})#Context::stream_sse
Backward-compatible alias for sse().
#Context::stream_start
Start a chunked stream response. The response is NOT finalized,
allowing multiple write calls afterwards; call end_stream to finish.
#Context::string
Render a plain text string.
#Context::string_f
StringF renders a formatted string response (printf-style).
Supports simple {0}, {1} placeholders for variable substitution.
ctx.string_f(200, "Hello {0}, you are {1} years old", ["Alice", "30"])#Context::toml
TOML renders a TOML response (placeholder — returns JSON).
#Context::write
Write raw data to an ongoing stream response.
#Context::write_header_now
WriteHeaderNow forces the HTTP headers to be written.
See c.Writer.WriteHeaderNow() equivalent.
#Context::written
Written returns true if the response has been written.
See c.Writer.Written() equivalent.
#Context::xml
Render XML. Converts a JSON object to XML format.
The JSON keys become XML tag names, values become text content.
ctx.xml(200, Json::object(H([
("user", Json::object(H([
("name", Json::string("Alice")),
("age", Json::string("30")),
]))),
])))
// Output: <root><user><name>Alice</name><age>30</age></user></root>#Engine
pub(all) struct Engine {
router : Router
handle_method_not_allowed : Bool
redirect_trailing_slash : Bool
redirect_fixed_path : Bool
remove_extra_slash : Bool
use_raw_path : Bool
unescape_path_values : Bool
max_multipart_memory : Int64
remote_ip_headers : Array[String]
trusted_platform : String
forwarded_by_client_ip : Bool
trusted_proxies : Array[String]
}Engine is the top-level framework instance.
#Engine::any
Register a route that matches ANY HTTP method. Returns Engine for chaining.
app.any("/api/health", [health_check])#Engine::del
Register a DELETE route.
#Engine::get
Register a GET route. Returns Engine for chaining.
app.get("/api/articles", [list_articles])
app.get("/api/articles/:id", [auth, get_article]) // with middleware#Engine::group
Create a route group under the given path prefix.
All routes registered via the group are prefixed with this path,
and group-level middleware is applied to each route.
let api = app.group("/api")
api.use(auth_middleware)
api.get("/profile", [get_profile])#Engine::handle
Handle multiple HTTP methods for the same pattern.
app.handle([GET, POST], "/api/form", [handle_form])#Engine::handle_context
HandleContext re-enters a context that has been rewritten.
This is useful for internal redirects (modify ctx.req.path and re-dispatch).
#Engine::handle_method_not_allowed
Enable or disable automatic 405 Method Not Allowed responses.
#Engine::head
Register a HEAD route.
#Engine::health
Register a built-in /health endpoint that returns 200 OK with JSON status.
Useful for load balancer health checks, container probes, and monitoring.
app.health()#Engine::load_html_files
Load HTML templates from a list of file paths.
#Engine::load_html_glob
Load HTML templates from a glob pattern (e.g., "templates/*.html").
#Engine::no_method
Set a custom 405 handler. Called when a path matches but the method
is not allowed.
#Engine::no_route
Set a custom 404 handler. Called when no route matches.
#Engine::options
Register an OPTIONS route.
#Engine::patch
Register a PATCH route.
#Engine::post
Register a POST route.
#Engine::put
Register a PUT route.
#Engine::redirect_fixed_path
Enable fixed path redirect. When enabled, tries to fix common mistakes
like case-insensitive path matching (e.g., /Users → /users).
Default is false.
#Engine::redirect_trailing_slash
Enable automatic trailing slash redirect.
When enabled, /path redirects to /path/ and vice versa.
#Engine::remove_extra_slash
Enable removal of extra slashes from paths.
When enabled, //api//v1//users is cleaned to /api/v1/users.
Default is false.
#Engine::routes
List all registered routes.
for route in app.routes() {
println("\{route.method} \{route.path}")
}#Engine::run
Start the HTTP server on addr with graceful shutdown support.
This is a blocking call — it runs until shutdown() is invoked (or the
process is killed). On shutdown it stops accepting new connections, waits
for in-flight requests to complete, then closes idle keep-alive
connections before returning.
#Engine::run_default
Start the server on the default address "0.0.0.0:8080".
Equivalent to app.run("0.0.0.0:8080").
app.run_default()#Engine::run_fd
RunFd starts an HTTP server on a given file descriptor.
Useful for systemd socket activation or inherited sockets.
app.run_fd(3) // Listen on fd 3 passed by systemd#Engine::run_listener
fn Engine::run_listener(_self : Engine, _handler : async (Request, ServerConnection) -> Unit) -> UnitRunListener starts the server with a custom request handler.
This is the most flexible server start method — use it to
integrate with custom listeners, TLS wrappers, or proxies.
app.run_listener(fn(request, reader, conn) {
// custom pre-processing
app.router.dispatch(request, reader, conn)
})#Engine::run_tls
RunTLS starts an HTTPS server with TLS encryption.
Reads certificate and key from the given file paths.
Uses @tls.Tls::server_from_pair to wrap raw TCP in TLS,
then delegates to the standard HTTP request handler.
app.run_tls("0.0.0.0:443", "./cert.pem", "./key.pem")#Engine::run_unix
RunUnix starts an HTTP server on a Unix domain socket.
Unix sockets are useful for local IPC without TCP overhead.
Note: Requires platform support (Linux, macOS).
On unsupported platforms, prints a warning and returns.
app.run_unix("/tmp/mbit.sock")#Engine::run_with_404
Run the server with a custom 404 handler (convenience wrapper).
This is equivalent to:
app.no_route([not_found_handler])
app.run(addr)#Engine::run_with_shutdown
RunWithShutdown starts the server with graceful shutdown support.
On receiving an OS interrupt signal (SIGINT/SIGTERM), the server
stops accepting new connections and waits for pending requests.
The optional on_shutdown callback is invoked when shutdown begins.
Note: Full signal handling requires platform-native OS support.
For now, use app.shutdown() from a health-check endpoint.
app.run_with_shutdown("0.0.0.0:8080")#Engine::serve_http
async fn Engine::serve_http(self : Engine, req : Request, reader : &Reader, conn : ServerConnection) -> UnitServeHTTP makes Engine implement the HTTP handler interface.
This allows using the engine with custom HTTP servers.
#Engine::set_forwarded_by_client_ip
Enable/disable trusting the X-Forwarded-For header.
#Engine::set_func_map
SetFuncMap sets a simple template function map (key → replacement value).
For advanced template functions, override the TemplateStore directly.
#Engine::set_html_template
Set a single HTML template by name and content string.
#Engine::set_max_multipart_memory
Set the maximum memory for multipart form parsing.
Default is 32 MB.
#Engine::set_remote_ip_headers
Set the headers to check for client IP.
Default: ["X-Forwarded-For", "X-Real-IP"]
#Engine::set_template_delims
Set custom template delimiters (default: {{ and }}).
#Engine::set_trusted_platform
Set a trusted platform header for determining client IP.
e.g., "X-Appengine-Remote-Addr", "CF-Connecting-IP"
#Engine::set_trusted_proxies
Set trusted proxy CIDRs (e.g., ["10.0.0.0/8", "172.16.0.0/12"]).
#Engine::set_unescape_path_values
Unescape path values (percent-decode URL paths).
Default is true.
#Engine::shutdown
Shutdown initiates a graceful shutdown of the server.
Stops accepting new connections, waits for in-flight requests to complete,
then closes idle keep-alive connections. run() returns afterwards.
This can be called from a signal handler or health check endpoint.
Returns true if the server was running and is now shutting down.
// In a health check or admin endpoint:
app.shutdown(cleanup=fn() {
println("Cleaning up resources...")
})#Engine::static_file
Serve a single static file at the given path.
app.static_file("/favicon.ico", "./assets/favicon.ico")#Engine::static_files_engine
Serve static files from a directory under the given URL prefix.
app.static_files_engine("/assets", "./public")#Engine::static_fs
Serve static files from a file system (alias for static_files_engine).
#Engine::unescape_path_values
Unescape percent-encoded path values (e.g., %20 → space).
Default is true.
#Engine::use
Add global middleware. Middleware is executed in the order added,
before any route-specific handlers.
app.use(@mbit.logger())
app.use(@mbit.cors(@mbit.CORSConfig::default()))#Engine::use_escaped_path
Enable escaped path support — percent-encoded paths are decoded.
Default is false.
#Engine::use_h2c
Enable HTTP/2 cleartext (h2c) support.
Note: Requires platform and library support.
#Engine::use_raw_path
Use the raw (percent-encoded) URL path instead of the decoded one.
Default is false.
#FieldRules
Field validation rules — maps field name to an array of rules.
Example:
let rules = [FieldRules("username", [Required, Min(3), Max(20)]),
FieldRules("email", [Required, Email]),
FieldRules("age", [Min(0), Max(150)])]#FieldRules::new
Create field rules.
#Group
A route group shares a path prefix and middleware.
#Group::any
Register a route that matches ANY HTTP method under this group.
group.any("/health", [health_check])#Group::base_path
Return the base path of this group.
let api = app.group("/api/v1")
println(api.base_path()) // "/api/v1"#Group::del
Register a DELETE route under this group.
#Group::get
Register a GET route under this group.
#Group::group
Create a nested group under this group.
The nested group inherits this group's prefix and middleware.
#Group::handle
Handle multiple HTTP methods for the same pattern under this group.
#Group::handlers
Return the middleware handlers attached to this group.
See group.Handlers equivalent.
#Group::head
Register a HEAD route under this group.
#Group::options
Register an OPTIONS route under this group.
#Group::patch
Register a PATCH route under this group.
#Group::post
Register a POST route under this group.
#Group::put
Register a PUT route under this group.
#Group::static_file
Serve a single static file under this group's prefix.
let assets = app.group("/assets")
assets.static_file("/favicon.ico", "./public/favicon.ico")#Group::static_files
Serve static files from a directory under this group's prefix.
let assets = app.group("/assets")
assets.static("/css", "./public/css")#Group::static_fs
Serve static files from a file system under this group's prefix.
See group.StaticFS() equivalent.
let assets = app.group("/assets")
assets.static_fs("/css", "./public/css")#LogFormat
Log output format.
#LogLevel
#Logger
pub(all) struct Logger {
}Logger — the central logging API for mbit.
All logging goes through moonbit-log (leppard/moonbit-log) and respects
configured log levels and output formats.
#Logger::debug
Log a debug message with optional key-value fields.
Logger::debug("Cache miss", fields=[("key", "user:42")])#Logger::error
Log an error message with optional key-value fields.
#Logger::fatal
Log a fatal message and terminate.
#Logger::info
Log an info message with optional key-value fields.
#Logger::is_enabled
Check if the given log level is enabled.
#Logger::set_app_name
Set the application name for log metadata.
Injected as a field into every log entry.
#Logger::set_environment
Set the environment tag for log metadata.
Injected as a field ("env") into every log entry.
#Logger::set_format
Set the log output format.
- TextFormat: human-readable compact format
- JSONFormat: JSON lines format
#MatchResult
Result of route matching.
#MbitError
pub(all) enum MbitError {
BindError(String)
ValidationError(String)
NotFound(String)
InternalError(String)
} derive(Debug)Framework-level error for binding / validation
#Method
HTTP method enumeration
#Method::from_native
Convert from native HTTP RequestMethod
#Method::to_native
Convert to native HTTP RequestMethod
#MetricsCollector
A simple in-memory metrics collector for request counts and latencies.
#MetricsCollector::new
Create a new metrics collector.
#MetricsCollector::record
fn MetricsCollector::record(self : MetricsCollector, status : Int, path : String, latency_ms : Int64) -> UnitRecord a request in the metrics collector.
#MetricsCollector::to_json
Export metrics as JSON for a /metrics endpoint.
#Mode
#Node
A node in the route trie.
#RenderType
Render type enumeration for the Render() method.
#ResponseConn
The response sink — either a real HTTP server connection or an
in-memory buffer used for testing.
#ResponseConn::end_response
Finish the response.
#ResponseConn::flush
Flush buffered data to the client.
#ResponseConn::send_response
async fn ResponseConn::send_response(self : ResponseConn, code : Int, reason : String, extra_headers? : Map[String, String]) -> UnitSend the response status line and headers.
#ResponseConn::write_body
Write a chunk of the response body.
#ResponseWriter
ResponseWriter wraps the response connection with size tracking.
#ResponseWriter::end
EndResponse signals the end of the response.
#ResponseWriter::flush
Flush any buffered data to the client.
#ResponseWriter::size
Size returns the number of bytes written.
#ResponseWriter::status
Status returns the HTTP status code.
#ResponseWriter::write
Write data to the response body.
#ResponseWriter::write_header
WriteHeader sends the HTTP response header with the given status code.
#ResponseWriter::write_header_now
WriteHeaderNow forces the response header to be written immediately.
#ResponseWriter::write_string
WriteString writes a string to the response.
#ResponseWriter::written
Written returns true if the header has been written.
#RouteInfo
pub(all) struct RouteInfo {
meth : String
path : String
handler_count : Int
}Information about a single registered route.
#Router
The Router stores all routes in a trie and dispatches incoming requests.
#Router::any
Register a route that matches ANY HTTP method.
router.any("/api/health", [health_check])#Router::del
Register a DELETE route.
#Router::dispatch
async fn Router::dispatch(self : Router, req : Request, reader : &Reader, conn : ServerConnection) -> BoolDispatch an incoming native HTTP request through the router.
Returns true if a matching route was found and handlers were executed,
false otherwise (caller should send a fallback 404).
#Router::get
Register a GET route with one or more handlers.
The last handler is typically the "real" handler; preceding ones are middleware.
#Router::handle
Handle multiple HTTP methods for the same pattern.
#Router::head
Register a HEAD route.
#Router::no_method
Set a custom 405 handler. Called when a path matches but the HTTP method
is not allowed.
#Router::no_route
Set a custom 404 handler. Called when no route matches the request path.
#Router::options
Register an OPTIONS route.
#Router::patch
Register a PATCH route.
#Router::post
Register a POST route.
#Router::put
Register a PUT route.
#Router::routes
List all registered routes. Returns an array of (method, path) pairs.
let routes = router.routes()
for route in routes {
println("\{route.method} \{route.path}")
}#Router::trees
Trees returns a human-readable string representation of all routing trees.
Prints routing tree for debugging.
#Router::use
Add global middleware (applied to every route).
#Rule
pub(all) enum Rule {
Required
Min(Int)
Max(Int)
Len(Int)
Pattern(String)
OneOf(Array[String])
Email
URL
Custom((String) -> String?)
}A single validation rule for a field.
#ServerConfig
pub(all) struct ServerConfig {
host : String
port : Int
database_url : String
redis_url : String
log_level : String
log_format : String
secret_key : String
cors_origins : Array[String]
max_upload_size : Int64
rate_limit : Int
rate_limit_window : Int
tls_cert_file : String
tls_key_file : String
environment : AppEnvironment
debug : Bool
}Strongly-typed server configuration populated from environment variables.
#ServerConfig::addr
Get the server address string (host:port).
#ServerConfig::from_env
Load server config from environment variables.
#ServerConfig::has_tls
Whether TLS is configured (cert and key files are set).
#ServerControl
Runtime control state shared between Engine::run() (the server loop) and
Engine::shutdown(). A single process runs at most one server, so a module
global is sufficient. Used to implement graceful shutdown: stop accepting,
drain in-flight requests, then close idle keep-alive connections.
#StructuredLogConfig
Configuration for the structured request logger middleware.
#StructuredLogConfig::default
Default structured log config.
#TestConn
pub(all) struct TestConn {
status : Int
reason : String
headers : Map[String, String]
body : String
header_sent : Bool
ended : Bool
}#ValidationError
A validation error for a single field.
#ValidationError::to_string
Error string for a ValidationError.
#ValidationErrors
Collection of validation errors.
#ValidationErrors::add
Add a validation error.
#ValidationErrors::all
All validation errors.
#ValidationErrors::first_error
Get the first error message, if any.
#ValidationErrors::has_errors
Whether there are any errors.
#ValidationErrors::new
Create a new empty ValidationErrors.
#ValidationErrors::to_json
Convert validation errors to a JSON response body.
#WebSocket
WebSocket connection state.
#WebSocket::close
Close the WebSocket connection.
#WebSocket::is_closed
Check if the WebSocket connection is closed.
#WebSocket::read
Read the next message from the WebSocket connection.
Returns None if the connection is closed or an error occurs.
#WebSocket::send_binary
Send a binary message over the WebSocket connection.
#WebSocket::send_close
Send a close frame with optional code and reason.
#WebSocket::send_ping
Send a ping frame.
#WebSocket::send_pong
Send a pong frame.
#WebSocketMessage
pub(all) enum WebSocketMessage {
Text(String)
Binary(String)
Close(Int, String)
Ping(String)
Pong(String)
} derive(Debug)A parsed WebSocket message.
#WebSocketOpcode
WebSocket opcodes as defined in RFC 6455.
#bind
Try to bind from JSON body first, then fall back to query string.
#bind_form
Bind form-encoded body to a struct that implements from_json.
Returns Some(value) on success, None on parse failure.
struct ContactForm {
name : String
email : String
message : String
} derive(FromJson)
let form : ContactForm? = bind_form(ctx)#bind_header
Bind request headers to a struct that implements from_json.
Header names are normalized to lowercase.
struct Headers {
content_type : String
authorization : String
} derive(FromJson)
let hdrs : Headers? = bind_header(ctx)#bind_json
Bind JSON body to a struct that implements from_json.
Returns Some(value) on success, None on parse failure.
struct LoginRequest {
username : String
password : String
} derive(FromJson)
let req : LoginRequest? = bind_json(ctx)#bind_path
Bind path parameters to a struct that implements from_json.
struct ArticleParams {
id : String
slug : String
} derive(FromJson)
// Route: /article/:id/:slug
let params : ArticleParams? = bind_path(ctx)#bind_query
Bind query parameters to a struct that implements from_json.
Converts query string to a JSON object first.
#bind_uri
Bind URI (path) parameters — alias for bind_path.
#clean_path
fn clean_path(path : String) -> StringClean a URL path by removing duplicate slashes and resolving ".." and ".".
#create_test_context
CreateTestContext returns a Context suitable for testing.
Uses a minimal dummy HTTP request and an in-memory test connection.
let ctx = create_test_context("GET", "/test")
assert_eq(ctx.method(), "GET")#create_test_context_with_handlers
Get a test context with pre-set handlers for chain testing.
#current_environment
Get the current environment from APP_ENV or MOONBIT_ENV.
#debug_print
fn debug_print(msg : String) -> UnitDebug print with format — for general debug logging.
Only prints in debug mode.
#debug_print_default
fn debug_print_default() -> UnitDebug print for default engine creation (with middleware).
#debug_print_route
fn debug_print_route(meth : String, path : String) -> UnitDebug print for route registration.
#default
Create a new Engine pre-configured with logger and recovery middleware.
This is the recommended starting point for most applications.
#disable_bind_validation
fn disable_bind_validation() -> UnitDisable automatic validation during binding.
#enable_bind_validation
fn enable_bind_validation() -> UnitEnable automatic validation during binding.
#gin_bind
Bind is a standalone function that auto-detects content type and binds.
Auto-detect content type and bind - alias.
#guess_content_type
fn guess_content_type(path : String) -> StringGuess MIME type from file extension.
#h
h is a shortcut for building a Map[String, Json] — convenient for
JSON responses.
ctx.json(200, Json::object(h([
("message", Json::string("hello")),
("code", Json::number(200.0)),
])))#is_bind_validation_enabled
fn is_bind_validation_enabled() -> BoolCheck if bind validation is enabled.
#is_websocket_request
Check if a request is a WebSocket upgrade request (convenience wrapper).
#join_strings
Join an array of strings with a separator.
#logger
Logger middleware — logs each request with method, path, status, and latency
via the structured logging system (moonbit-log), respecting configured
log levels and formats. 5xx -> error, 4xx -> warn, otherwise info.
Usage:
app.use(logger())#metrics_middleware
Metrics middleware — records request metrics into the provided collector.
let metrics = MetricsCollector::new()
app.use(metrics_middleware(metrics))
app.get("/metrics", [fn(ctx) { ctx.json(200, metrics.to_json()) }])#new
Create a new Engine with no default middleware.
For a production-ready engine with logger and recovery, use mbit.default().
#recovery
Recovery middleware — catches panics/exceptions in handlers and returns 500.
See recovery.go equivalent.
Usage:
app.use(recovery())#search
fn search(node : Node, segments : Array[String], idx : Int, params : Map[String, String]) -> MatchResult?Recursively search the trie for a matching route.
#status_text
fn status_text(code : Int) -> StringStandard HTTP status codes used by the framework
#structured_logger
Structured request logging middleware — powered by moonbit-log.
Logs each request with structured fields:
- method, path, status, latency
- client_ip, user_agent, content_type
- request_id (if set in context)
app.use(structured_logger(StructuredLogConfig::default()))#upgrade_websocket
Attempt to upgrade an HTTP connection to WebSocket.
Returns Some(WebSocket) on success, None if the request is not a valid
WebSocket upgrade request.
Performs the WebSocket opening handshake (RFC 6455 Section 4):
- Validates the Upgrade, Connection, and Sec-WebSocket-Key headers
- Computes the accept key
- Sends the 101 Switching Protocols response
#validate
fn[T] validate(_value : T) -> String?Validate a value and return the first error message, or None if valid.
Override this in your types for custom validation.
#validate_field
Validate a single field value against a list of rules.
Returns Some(error_message) if validation fails, None if valid.
#validate_map
Validate a map of field values against field rules.
Returns ValidationErrors containing all validation failures.
let values = Map([("username", "alice"), ("email", "alice@example.com")])
let rules = [
FieldRules::new("username", [Required, Min(3)]),
FieldRules::new("email", [Required, Email]),
]
let errors = validate_map(values, rules)
if errors.has_errors() {
ctx.json(400, errors.to_json())
return
}#validate_or_abort
async fn validate_or_abort(ctx : Context, values : Map[String, String], rules : Array[FieldRules]) -> BoolConvenience: validate and abort with 422 if there are errors.
Returns true if valid, false if aborted.
let values = Map([("username", "alice")])
let rules = [FieldRules::new("username", [Required, Min(3)])]
if !validate_or_abort(ctx, values, rules) {
return
}
// Proceed with valid data...#websocket_handler
Create a WebSocket route handler that automatically performs the upgrade
and calls the provided message handler.
app.get("/ws", [websocket_handler(fn(ws) {
ws.send_text("Hello via WebSocket!")
loop {
match ws.read() {
Some(WebSocketMessage::Text(t)) => ws.send_text("Echo: " + t)
Some(WebSocketMessage::Close(_, _)) => break
_ => ()
}
}
})])
A Gin-inspired web framework for MoonBit — fast, lightweight, idiomatic.
webhttpframeworkrouter
0.3.0
Apache-2.0
Updated 16 days ago
17 downloadsDependencies
- moonbitlang/async0.20.3
- moonbitlang/x0.4.47
- leppard/moonbit-log0.1.0