#MoonBack

#Features

• Async HTTP server integration through moonbitlang/async
• Module-based app composition with Module and ModuleContext
• Route registration for GET, POST, and arbitrary HTTP methods
• Middleware chaining
• Typed query parameter and cookie helpers
• Response helpers for text, type-safe HTML, JSON, empty responses, and WebSocket upgrade
• App lifecycle cleanup with ctx.on_close
• Module-only dependency injection using TypedKey
• Typed custom application configuration values
• Optional app mounting for composing independent apps

#Installation

import {
  "moonbitlang/async@0.21.0",
  "moonbitlang/moonback@0.8.2",
}

preferred_target = "native"

#Migrating from hackwaly/moonback

import {
  "moonbitlang/moonback@0.8.2",
}

#Quick start

async fn main {
  let app = @moonback.App(ctx => {
    ctx.get("/", (_req, res) => {
      res.send_text("Hello, MoonBack!")
    })
  })
  defer app.close()

  let server = @moonback.listen(port=3000)
  println("Server listening on \{server.addr}")
  app.serve(server)
}

moon run .

http://127.0.0.1:3000/

#Modules

let posts_module : @moonback.Module = @moonback.Module(ctx => {
  ctx.get("/posts", list_posts)
  ctx.get("/posts/:id", show_post)
})

let admin_module : @moonback.Module = @moonback.Module(ctx => {
  ctx.add_middleware(require_admin)
  ctx.get("/admin/users", list_users)
})

async fn main {
  let app = @moonback.App(ctx => {
    ctx.use_(posts_module)
    ctx.use_(admin_module)
  })
  defer app.close()

  let server = @moonback.listen(port=3000)
  app.serve(server)
}

#Routing

ctx.get("/", (_req, res) => {
  res.send_text("home")
})

ctx.get("/posts/:id", (req, res) => {
  let id = req.params["id"]
  res.send_text("post \{id}")
})

ctx.add_route(@http.Put, "/posts/:id", update_post)

ctx.get(path, handler)
ctx.post(path, handler)
ctx.add_route(method, path, handler)

#Requests

ctx.get("/search", (req, res) => {
  let q = match req.query().get("q") {
    Some(q) => q
    None => ""
  }
  let cookies = req.cookie()
  let has_session = match cookies.get("session") {
    Some(_) => true
    None => false
  }
  let ip = match req.ip() {
    Some(ip) => ip.to_string()
    None => ""
  }

  res.send_json({
    "query": q,
    "has_session": has_session,
    "ip": ip,
  })
})

• req.meth
• req.path
• req.search
• req.headers
• req.params
• req.body.text()
• req.body.binary()
• req.body.json()
• req.query()
• req.cookie()
• req.ip()
• req.ips()

#Responses

res.send_text("ok")
res.send_html(@moonback.Html::raw("<h1>Hello</h1>"))
res.send_json({ "ok": true })
res.send_void(status=204)

let page = @moonback.Html(builder => {
  let title = "Hello, <MoonBack>"
  builder  "<h1>\{title}</h1>"
})

res.send_html(page)

ctx.get("/stream", (_req, res) => {
  let w = res.respond(status=200, headers={ "Content-Type": "text/plain" })
  w.write("first line\n")
  w.flush()
  w.write("second line\n")
})

#WebSocket

import {
  "moonbitlang/async/websocket",
  "moonbitlang/moonback",
}

async fn serve_websocket(
  req : @moonback.Request,
  res : @moonback.Responder,
) -> Unit {
  let ws = res.upgrade(req)
  defer ws.close()

  try {
    for ;; {
      let msg = ws.recv()
      match msg.kind {
        Text => {
          let text = msg.read_all().text()
          ws.send_text("echo: \{text}")
        }
        Binary => {
          let data = msg.read_all().binary()
          ws.send_binary(data)
        }
      }
    }
  } catch {
    @websocket.ConnectionClosed(_, _) => ()
    err => raise err
  }
}

let app = @moonback.App(ctx => {
  ctx.get("/ws", serve_websocket)
})

#Middleware

let log_requests = @moonback.Middleware(next => {
  (req, res) => {
    println("\{req.meth} \{req.path}")
    next(req, res)
  }
})

let app = @moonback.App(ctx => {
  ctx.add_middleware(log_requests)
  ctx.get("/", (_req, res) => res.send_text("ok"))
})

#Dependency injection

struct Greeter {
  prefix : String
}

 @moonback.TypedBox  {
  GreeterDependency(Greeter)
}

let greeter_key : @moonback.TypedKey[Greeter] = @moonback.TypedKey(
  name="greeter",
  box=greeter => GreeterDependency(greeter),
  unbox=err => {
    match err {
      GreeterDependency(greeter) => Some(greeter)
      _ => None
    }
  },
)

let greeter_module : @moonback.Module = @moonback.Module(ctx => {
  let greeter = ctx.require(greeter_key)

  ctx.get("/", (_req, res) => {
    res.send_text("\{greeter.prefix}, MoonBack!")
  })
})

let app = @moonback.App(ctx => {
  ctx.provide(greeter_key, { prefix: "Hello" })
  ctx.use_(greeter_module)
})

ctx.provide(key, value)
ctx.resolve(key)
ctx.require(key)

#Request userdata

req.ctx.set_userdata(key, value)
req.ctx.get_userdata(key)

• dependencies are app-scoped and module-initialization only
• userdata is request-scoped

#App configuration

let app = @moonback.App(
  root_module(),
  config=@moonback.Config(
    trust_proxy=true,
    max_connections=1024,
    stop_timeout=5.0,
  ),
)

• trust_proxy: use proxy headers such as X-Forwarded-For
• max_connections: limit concurrent accepted connections
• stop_timeout: graceful shutdown timeout in seconds

 @moonback.TypedBox  {
  UploadRoot(String)
}

let upload_root_key : @moonback.TypedKey[String] = @moonback.TypedKey(
  name="upload_root",
  box=root => UploadRoot(root),
  unbox=boxed => {
    match boxed {
      UploadRoot(root) => Some(root)
      _ => None
    }
  },
)

let app = @moonback.App(
  root_module(),
  config=@moonback.Config(
    custom=[
      @moonback.Config::custom(upload_root_key, "/srv/uploads"),
    ],
  ),
)

let upload_root = app.config().get_custom(upload_root_key)

#Cleanup hooks

let app = @moonback.App(ctx => {
  let db = connect_db()
  ctx.on_close(() => db.close())
})

defer app.close()

#Mounting apps

let api = @moonback.App(ctx => {
  ctx.get("/health", (_req, res) => res.send_text("ok"))
})

let app = @moonback.App(ctx => {
  ctx.mount("/api", api)
})

ctx.mount("/api", api, error_mode=@moonback.Isolate)

#Development

moon update
moon check
moon test
moon fmt
moon info

#License

#Embedded static assets

ctx.add_middleware(
  @static.from_assets(
    warren_assets(), // Map[String, Bytes], keyed by paths such as /index.js
    rewrite_trailing_slash_index=true,
  ),
)