README
Tr
Env
T
BackgroundTask
- ::bodyContext::body
- ::body_jsonContext::body_json
- ::connContext::conn
- ::cookieContext::cookie
- ::cookiesContext::cookies
- ::delete_cookieContext::delete_cookie
- ::end_responseContext::end_response
- ::env_bindingContext::env_binding
- ::env_varContext::env_var
- ::getContext::get
- ::headerContext::header
- ::htmlContext::html
- ::is_response_sentContext::is_response_sent
- ::jsonContext::json
- ::methContext::meth
- ::newContext::new
- ::not_foundContext::not_found
- ::paramContext::param
- ::pathContext::path
- ::queriesContext::queries
- ::queryContext::query
- ::redirectContext::redirect
- ::setContext::set
- ::set_cookieContext::set_cookie
- ::set_headerContext::set_header
- ::set_statusContext::set_status
- ::sse_startContext::sse_start
- ::textContext::text
- ::wait_untilContext::wait_until
- ::with_envContext::with_env
- ::write_rawContext::write_raw
- ::newEmptyEnv::new
- ::deactivateExecutionContext::deactivate
- ::get_tasksExecutionContext::get_tasks
- ::is_activeExecutionContext::is_active
- ::newExecutionContext::new
- ::pending_countExecutionContext::pending_count
- ::run_tasksExecutionContext::run_tasks
- ::wait_untilExecutionContext::wait_until
- ::innerHandler::inner
- ::newMapEnv::new
- ::with_bindingMapEnv::with_binding
- ::with_varMapEnv::with_var
- ::allMars::all
- ::deleteMars::delete
- ::getMars::get
- ::newMars::new
- ::patchMars::patch
- ::postMars::post
- ::putMars::put
- ::queryMars::query
- ::serveMars::serve
- ::serve_with_envMars::serve_with_env
- ::use_Mars::use_
- ::newPlatformContext::new
- ::get_boolVariables::get_bool
- ::get_jsonVariables::get_json
- ::get_numberVariables::get_number
- ::get_stringVariables::get_string
- ::hasVariables::has
- ::keysVariables::keys
- ::newVariables::new
- ::removeVariables::remove
- ::set_boolVariables::set_bool
- ::set_jsonVariables::set_json
- ::set_numberVariables::set_number
- ::set_stringVariables::set_string
V
compose
V
handler

mars

Hono-inspired HTTP framework for MoonBit

http

router

web-framework

Download zip

Author

mizchi

Version

0.2.3

License

MIT

Repository

github.com/mizchi/mars.mbt

Last updated

8 months ago

Downloads

#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(@socket.Addr::parse("127.0.0.1:3000"))
}

#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(addr) - Start HTTP server

#Context

Context::param(name) -> String? - Get URL parameter
Context::path() -> String - Get request path
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

Env

source

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

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

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 : @moonbitlang/async/http.Request
Request
  params : @mizchi/mars/router.Params
Params
  vars : Variables
  execution_ctx : ExecutionContext
  // 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

fn Context::conn(self : Context) -> @moonbitlang/async/http.ServerConnection
ServerConnection

Get server connection (native only)

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

Context::delete_cookie

source

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

fn Context::meth(self : Context) -> @moonbitlang/async/http.RequestMethod
RequestMethod

Get request method

Context::new

source

fn Context::new(request : @moonbitlang/async/http.Request
Request, params : @mizchi/mars/router.Params
Params, conn : @moonbitlang/async/http.ServerConnection
ServerConnection, body_reader : &@moonbitlang/async/io.Reader
Reader) -> Context

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::set

source

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

Set custom data

Context::set_cookie

source

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

fn Context::with_env(request : @moonbitlang/async/http.Request
Request, params : @mizchi/mars/router.Params
Params, conn : @moonbitlang/async/http.ServerConnection
ServerConnection, body_reader : &@moonbitlang/async/io.Reader
Reader, env : MapEnv) -> Context

Create a new Context with environment bindings (native-specific constructor)

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

fn ExecutionContext::get_tasks(self : ExecutionContext) -> Array[BackgroundTask]

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

fn ExecutionContext::new() -> ExecutionContext

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) type Handler async (Context) -> Unit

Handler function signature Handler receives a Context and returns Unit

Handler::inner

source

#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn Handler::inner(self : Handler) -> (async (Context) -> Unit)

Convert newtype to its underlying type, automatically derived.

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

Mars

source

pub(all) struct Mars {
  router : @mizchi/mars/router/trie.TrieRouter
TrieRouter
  handlers : Array[Handler]
  middlewares : Array[Handler]
}

Mars HTTP Framework A Hono-inspired HTTP framework for MoonBit

Mars::all

source

fn Mars::all(self : Mars, path : String, handler : Handler) -> Mars

Mars::delete

source

fn Mars::delete(self : Mars, path : String, handler : Handler) -> Mars

Mars::get

source

fn Mars::get(self : Mars, path : String, handler : Handler) -> Mars

Mars::new

source

fn Mars::new() -> Mars

Create a new Mars application

Mars::patch

source

fn Mars::patch(self : Mars, path : String, handler : Handler) -> Mars

Mars::post

source

fn Mars::post(self : Mars, path : String, handler : Handler) -> Mars

Mars::put

source

fn Mars::put(self : Mars, path : String, handler : Handler) -> Mars

Mars::query

source

fn Mars::query(self : Mars, path : String, handler : Handler) -> Mars

Mars::serve

source

async fn Mars::serve(self : Mars, addr : @moonbitlang/async/socket.Addr
Addr) -> Unit

Start the HTTP server (native only)

Mars::serve_with_env

source

async fn Mars::serve_with_env(self : Mars, addr : @moonbitlang/async/socket.Addr
Addr, env : MapEnv) -> Unit

Start the HTTP server with environment bindings (native only)

Mars::use_

source

fn Mars::use_(self : Mars, handler : Handler) -> Mars

Add a middleware to the application

PlatformContext

source

pub(all) struct PlatformContext {
  conn : @moonbitlang/async/http.ServerConnection
ServerConnection
  body_reader : &@moonbitlang/async/io.Reader
Reader
}

Native platform-specific context data

PlatformContext::new

source

fn PlatformContext::new(conn : @moonbitlang/async/http.ServerConnection
ServerConnection, body_reader : &@moonbitlang/async/io.Reader
Reader) -> PlatformContext

Create a new PlatformContext for native

Variables

source

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

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

Variables::get_bool

source

fn Variables::get_bool(self : Variables, key : String) -> Bool?

Get a boolean variable

Variables::get_json

source

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

Get a JSON variable

Variables::get_number

source

fn Variables::get_number(self : Variables, key : String) -> Double?

Get a number variable

Variables::get_string

source

fn Variables::get_string(self : Variables, key : String) -> String?

Get a string variable

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_bool

source

fn Variables::set_bool(self : Variables, key : String, value : Bool) -> Unit

Set a boolean variable

Variables::set_json

source

fn Variables::set_json(self : Variables, key : String, value : Json) -> Unit

Set a JSON variable

Variables::set_number

source

fn Variables::set_number(self : Variables, key : String, value : Double) -> Unit

Set a number variable

Variables::set_string

source

fn Variables::set_string(self : Variables, key : String, value : String) -> Unit

Set a string variable

compose

source

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

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

handler

source

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

Helper to create a Handler from an async function

Source Files

Site source Report issue Packages Build queue Skills Statistics

mars

#Mars

#Features

#Installation

#Usage

#API

#Mars

#Context

#Router Patterns

#License

#Env

#BackgroundTask

#Context

#Context::body

#Context::body_json

#Context::conn

#Context::cookie

#Context::cookies

#Context::delete_cookie

#Context::end_response

#Context::env_binding

#Context::env_var

#Context::get

#Context::header

#Context::html

#Context::is_response_sent

#Context::json

#Context::meth

#Context::new

#Context::not_found

#Context::param

#Context::path

#Context::queries

#Context::query

#Context::redirect

#Context::set

#Context::set_cookie

#Context::set_header

#Context::set_status

#Context::sse_start

#Context::text

#Context::wait_until

#Context::with_env

#Context::write_raw

#EmptyEnv

#EmptyEnv::new

#ExecutionContext

#ExecutionContext::deactivate

#ExecutionContext::get_tasks

#ExecutionContext::is_active

#ExecutionContext::new

#ExecutionContext::pending_count

#ExecutionContext::run_tasks

#ExecutionContext::wait_until

#Handler

#Handler::inner

#MapEnv

#MapEnv::new

#MapEnv::with_binding

#MapEnv::with_var

#Mars

#Mars::all

#Mars::delete

#Mars::get

#Mars::new

#Mars::patch

#Mars::post

#Mars::put

#Mars::query

#Mars::serve

#Mars::serve_with_env

#Mars::use_

#PlatformContext

#PlatformContext::new

#Variables

#Variables::get_bool

#Variables::get_json

#Variables::get_number

#Variables::get_string

#Variables::has

Env

BackgroundTask

Context

Context::body

Context::body_json

Context::conn

Context::cookie

Context::cookies

Context::delete_cookie

Context::end_response

Context::env_binding

Context::env_var

Context::get

Context::header

Context::html

Context::is_response_sent

Context::json

Context::meth

Context::new

Context::not_found

Context::param

Context::path

Context::queries

Context::query

Context::redirect

Context::set

Context::set_cookie

Context::set_header

Context::set_status

Context::sse_start

Context::text

Context::wait_until

Context::with_env

Context::write_raw

EmptyEnv

EmptyEnv::new

ExecutionContext

ExecutionContext::deactivate

ExecutionContext::get_tasks

ExecutionContext::is_active

ExecutionContext::new

ExecutionContext::pending_count

ExecutionContext::run_tasks

ExecutionContext::wait_until

Handler

Handler::inner

MapEnv

MapEnv::new

MapEnv::with_binding

MapEnv::with_var

Mars

Mars::all

Mars::delete

Mars::get

Mars::new

Mars::patch

Mars::post

Mars::put

Mars::query

Mars::serve

Mars::serve_with_env

Mars::use_

PlatformContext

PlatformContext::new

Variables

Variables::get_bool

Variables::get_json

Variables::get_number

Variables::get_string

Variables::has

Variables::keys

Variables::new

Variables::remove

Variables::set_bool

Variables::set_json

Variables::set_number

Variables::set_string

compose

handler