🥮 mooncakes.io

mars

Hono-inspired MoonBit web framework with trie routing, middleware, SSE, and mizchi/x HTTP backend for native and Node.js

moonbit
http
router
web-framework
middleware
sse
nodejs
api
moon add mizchi/mars@0.3.11
Download zip
Author
Version
0.3.11
License
MIT
Repository
Last updated
last month
Downloads
5K

Dependencies

README

#Mars

A Hono-inspired HTTP framework for MoonBit.

#Features

  • Trie-based Router: Fast URL matching with parameter extraction
  • Dynamic Parameters: Support for :id style URL parameters
  • Wildcard Routes: Support for * wildcard patterns
  • Optional Parameters: Support for :param? optional parameters
  • Regex Parameters: Support for :id{[0-9]+} regex-constrained parameters
  • HTTP Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE
  • Middleware Support: Chain multiple handlers
  • JSON/HTML/Text Responses: Built-in response helpers

#Installation

Add to your moon.mod.json:

{
  "deps": {
    "mizchi/mars": "0.1.0"
  }
}

#Usage

async fn main {
  let app = @mars.Mars::new()

  // Static route
  let _ = app.get("/", @mars.handler(async fn(ctx) {
    ctx.text("Hello, Mars!")
  }))

  // Dynamic parameter
  let _ = app.get("/users/:id", @mars.handler(async fn(ctx) {
    let id = ctx.param("id").unwrap_or("unknown")
    ctx.json({ "id": id })
  }))

  // Wildcard
  let _ = app.get("/files/*", @mars.handler(async fn(ctx) {
    ctx.text("File path: " + ctx.path())
  }))

  // Multiple methods
  let _ = app.post("/users", @mars.handler(async fn(ctx) {
    ctx.json({ "status": "created" }, status=201)
  }))

  // Start server
  app.serve(host="127.0.0.1", port=3000)
}

#JWT Middleware

jwt_bearer_with_key and jwt_bearer_with_jwks are temporarily disabled while cross-target JWT verification is being redesigned. Current verifier behavior is fail-closed (always unauthorized).

jwks_fetch_native, jwks_fetch_node, and jwks_fetch_wasm fetch JWKS documents for applications that need the transport helper directly. Native and Node.js targets use mizchi/x/http.

Claims helper APIs are still available:

  • jwt_claims_json
  • jwt_claims_map
  • jwt_claims_decode
  • jwt_claims_decode_string

#API

#Mars

  • Mars::new() -> Mars - Create new application
  • Mars::get(path, handler) -> Mars - Register GET route
  • Mars::post(path, handler) -> Mars - Register POST route
  • Mars::put(path, handler) -> Mars - Register PUT route
  • Mars::delete(path, handler) -> Mars - Register DELETE route
  • Mars::patch(path, handler) -> Mars - Register PATCH route
  • Mars::all(path, handler) -> Mars - Register route for all methods
  • Mars::use_(middleware) -> Mars - Add middleware
  • Mars::serve(host?, port?) - Start HTTP server

#Context

  • Context::param(name) -> String? - Get URL parameter
  • Context::path() -> String - Get request path
  • Context::request() -> @http.Request - Get raw HTTP request
  • Context::header(name) -> String? - Get request header
  • Context::text(body, status?) - Send text response
  • Context::json(data, status?) - Send JSON response
  • Context::html(body, status?) - Send HTML response
  • Context::redirect(url) - Send redirect response
  • Context::not_found() - Send 404 response

#Router Patterns

  • /users - Static path
  • /users/:id - Dynamic parameter
  • /users/:id{[0-9]+} - Regex-constrained parameter
  • /files/* - Wildcard (matches any path)
  • /api/:type? - Optional parameter

#License

MIT

#
AppHandler

source

#
Env

source
pub(open) trait Env {
  fn get_var(Self, String) -> String?
  fn get_binding(Self, String) -> Json?
}

Environment trait for platform-specific bindings Implement this trait for your platform (Cloudflare, Deno, etc.)

#
ExecCtx

source
pub(open) trait ExecCtx {
  fn wait_until(Self, async () -> Unit, name~ : String) -> Unit
}

Execution context trait for background tasks Similar to Cloudflare Workers ExecutionContext

#
Var

source
pub(open) trait Var {
  fn to_json(Self) -> Json
  fn from_json(Json) -> Self?
}

Trait for types that can be stored in Variables
impl Var for Bool
impl Var for Double
impl Var for String
impl Var for Json

#
BackgroundTask

source
pub(all) struct BackgroundTask {
  task : async () -> Unit
  name : String
}

Background task that will run after response is sent

#
Context

source
pub(all) struct Context {
  request : 
Request
  params : 
Params
  vars : Variables
  exec_ctx : &ExecCtx
  // private fields
}

HTTP Context for request/response handling

#
Context::body

source
async fn Context::body(self : Context) -> String

Read request body as string (native implementation)

#
Context::body_json

source
async fn Context::body_json(self : Context) -> Json?

Parse request body as JSON

#
Context::conn

source

Get server connection (native only)

#
Context::cookie

source
fn Context::cookie(self : Context, name : String) -> String?

Get a cookie by name

#
Context::cookies

source
fn Context::cookies(self : Context) -> Map[String, String]

Get all cookies
fn Context::delete_cookie(self : Context, name : String) -> Unit

Delete a cookie

#
Context::end_response

source
async fn Context::end_response(self : Context) -> Unit

End the response (native implementation)

#
Context::env_binding

source
fn Context::env_binding(self : Context, name : String) -> Json?

Get environment binding as JSON

#
Context::env_var

source
fn Context::env_var(self : Context, name : String) -> String?

Get environment variable

#
Context::get

source
fn Context::get(self : Context, key : String) -> String?

Get custom data

#
Context::header

source
fn Context::header(self : Context, name : String) -> String?

Get a request header

#
Context::html

source
async fn Context::html(self : Context, body : String, status? : Int) -> Unit

Send an HTML response (native implementation)

#
Context::is_response_sent

source
fn Context::is_response_sent(self : Context) -> Bool

Check if response has been sent

#
Context::json

source
async fn Context::json(self : Context, data : Json, status? : Int) -> Unit

Send a JSON response (native implementation)

#
Context::meth

source

Get request method

#
Context::new

source

Create a new Context (native-specific constructor)

#
Context::not_found

source
async fn Context::not_found(self : Context) -> Unit

Send a 404 Not Found response (native implementation)

#
Context::param

source
fn Context::param(self : Context, name : String) -> String?

Get a URL parameter by name

#
Context::path

source
fn Context::path(self : Context) -> String

Get request path

#
Context::queries

source
fn Context::queries(self : Context) -> Map[String, String]

Get all query parameters

#
Context::query

source
fn Context::query(self : Context, name : String) -> String?

Get a query parameter by name

#
Context::redirect

source
async fn Context::redirect(self : Context, url : String) -> Unit

Send a redirect response (native implementation)

#
Context::request

source

Get raw HTTP request

#
Context::set

source
fn Context::set(self : Context, key : String, value : String) -> Unit

Set custom data
fn Context::set_cookie(self : Context, name : String, value : String, max_age? : Int, path? : String, http_only? : Bool, same_site? : String) -> Unit

Set a cookie

#
Context::set_header

source
fn Context::set_header(self : Context, name : String, value : String) -> Unit

Set a response header

#
Context::set_status

source
fn Context::set_status(self : Context, status : Int) -> Unit

Set response status code

#
Context::sse_start

source
async fn Context::sse_start(self : Context) -> Unit

Start an SSE response (native implementation)

#
Context::text

source
async fn Context::text(self : Context, body : String, status? : Int) -> Unit

Send a text response (native implementation)

#
Context::wait_until

source
fn Context::wait_until(self : Context, task : async () -> Unit, name? : String) -> Unit

Schedule a background task (like Cloudflare's waitUntil)

#
Context::with_env

source

Create a new Context with environment and execution context (native-specific)

#
Context::write_raw

source
async fn Context::write_raw(self : Context, data : String) -> Unit

Write raw data to the response (native implementation)

#
EmptyEnv

source
pub(all) struct EmptyEnv {
}

Empty environment (no bindings)
impl Env for EmptyEnv

#
EmptyEnv::new

source
fn EmptyEnv::new() -> EmptyEnv

#
ExecutionContext

source
pub(all) struct ExecutionContext {
  // private fields
}

ExecutionContext manages background tasks

#
ExecutionContext::deactivate

source
fn ExecutionContext::deactivate(self : ExecutionContext) -> Unit

Deactivate context (no more tasks can be added)

#
ExecutionContext::get_tasks

source

Get all pending tasks (for testing)

#
ExecutionContext::is_active

source
fn ExecutionContext::is_active(self : ExecutionContext) -> Bool

Check if context is still active

#
ExecutionContext::new

source

Create a new ExecutionContext

#
ExecutionContext::pending_count

source
fn ExecutionContext::pending_count(self : ExecutionContext) -> Int

Get number of pending tasks

#
ExecutionContext::run_tasks

source
async fn ExecutionContext::run_tasks(self : ExecutionContext) -> Unit

Execute all pending background tasks Called after response is sent

#
ExecutionContext::wait_until

source
fn ExecutionContext::wait_until(self : ExecutionContext, task : async () -> Unit, name? : String) -> Unit

Schedule a background task to run after response is sent Similar to Cloudflare's ctx.waitUntil()

#
Handler

source
pub(all) struct Handler(async (Context) -> Unit)

Handler function signature Handler receives a Context and returns Unit

#
MapEnv

source
pub(all) struct MapEnv {
  vars : Map[String, String]
  bindings : Map[String, Json]
}

Map-based environment (for testing and simple use cases)
impl Env for MapEnv

#
MapEnv::new

source
fn MapEnv::new() -> MapEnv

#
MapEnv::with_binding

source
fn MapEnv::with_binding(self : MapEnv, name : String, value : Json) -> MapEnv

#
MapEnv::with_var

source
fn MapEnv::with_var(self : MapEnv, name : String, value : String) -> MapEnv

#
PlatformContext

source
pub(all) struct PlatformContext {
  conn : 
ServerConnection
  body_reader : &
Reader
}

Native platform-specific context data

#
PlatformContext::new

source

Create a new PlatformContext for native

#
Server

source
pub(all) struct Server {
  router : 
TrieRouter
  handlers : Array[Handler]
  middlewares : Array[Handler]
  routes : Array[(
Method, String, Int)]
}

Server HTTP Framework A Hono-inspired HTTP framework for MoonBit

#
Server::all

source
fn Server::all(self : Server, path : String, handler : Handler) -> Unit

Register a route for all HTTP methods

#
Server::delete

source
fn Server::delete(self : Server, path : String, handler : Handler) -> Unit

Register a DELETE route

#
Server::get

source
fn Server::get(self : Server, path : String, handler : Handler) -> Unit

Register a GET route

#
Server::middleware

source
fn Server::middleware(self : Server, handler : Handler) -> Unit

Add a middleware to the application

#
Server::mount

source
fn Server::mount(self : Server, prefix : String, sub : Server) -> Unit

Mount a sub-application at the given prefix

#
Server::new

source
fn Server::new() -> Server

Create a new Server application

#
Server::new_debug

source
fn Server::new_debug() -> Server

Create a new Server application with debug mode enabled

#
Server::patch

source
fn Server::patch(self : Server, path : String, handler : Handler) -> Unit

Register a PATCH route

#
Server::post

source
fn Server::post(self : Server, path : String, handler : Handler) -> Unit

Register a POST route

#
Server::put

source
fn Server::put(self : Server, path : String, handler : Handler) -> Unit

Register a PUT route

#
Server::query

source
fn Server::query(self : Server, path : String, handler : Handler) -> Unit

Register a QUERY route (RFC 9110)

#
Server::serve

source
async fn Server::serve(self : Server, host? : String, port? : Int) -> Unit

Start the HTTP server

#
Server::serve_with_env

source
async fn[E : Env, C : ExecCtx] Server::serve_with_env(self : Server, host? : String, port? : Int, env : E, exec_ctx : C) -> Unit

Start the HTTP server with environment and execution context

#
Server::to_handler

source

Convert Server app to a platform handler function (native only)

#
Server::to_handler_with_env

source
fn[E : Env, C : ExecCtx] Server::to_handler_with_env(self : Server, env : E, exec_ctx : C) -> (async (
Request, &
Reader, 
ServerConnection) -> Unit)

Convert Server app to a platform handler function with environment and execution context (native only)

#
Variables

source
pub(all) struct Variables {
  data : Map[String, Json]
}

Typed variables storage Uses Json for flexible storage with runtime type checking

#
Variables::get

source
fn Variables::get(self : Variables, key : String) -> Json?

Get a variable as Json for pattern matching

#
Variables::has

source
fn Variables::has(self : Variables, key : String) -> Bool

Check if variable exists

#
Variables::keys

source
fn Variables::keys(self : Variables) -> Array[String]

Get all keys

#
Variables::new

source
fn Variables::new() -> Variables

#
Variables::remove

source
fn Variables::remove(self : Variables, key : String) -> Unit

Remove a variable

#
Variables::set

source
fn[V : Var] Variables::set(self : Variables, key : String, value : V) -> Unit

Set a variable (trait-based)

#
char_to_lower

source
fn char_to_lower(c : Char) -> Char

Convert character to lowercase

#
compose

source
fn compose(handlers : Array[Handler]) -> Handler

Compose multiple handlers into a chain Each handler is called in order

#
find_char

source
fn find_char(s : String, c : Char) -> Int

Find first occurrence of character in string, returns -1 if not found

#
handler

source
fn handler(f : async (Context) -> Unit) -> Handler

Helper to create a Handler from an async function

#
hex_to_int

source
fn hex_to_int(c : Char) -> Int

Convert hex character to integer, returns -1 for invalid

#
is_debug

source
fn is_debug() -> Bool

Check if debug mode is enabled

#
is_whitespace

source
fn is_whitespace(c : Char) -> Bool

Check if character is whitespace

#
set_debug

source
fn set_debug(enabled : Bool) -> Unit

Enable or disable debug mode globally

#
split_by_char

source
fn split_by_char(s : String, sep : Char) -> Array[String]

Split string by separator character

#
strip_query_string

source
fn strip_query_string(path : String) -> String

Strip query string from path (everything from first '?' onwards)

#
substring

source
fn substring(s : String, start : Int, end : Int) -> String

Extract substring from start to end index

#
substring_from

source
fn substring_from(s : String, start : Int) -> String

Extract substring from start to end of string

#
to_lower

source
fn to_lower(s : String) -> String

Convert string to lowercase

#
trim

source
fn trim(s : String) -> String

Trim whitespace from both ends of string

#
url_decode

source
fn url_decode(s : String) -> String

URL decode a string (handles %XX and + encoding)

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io