#express

#Quick start

///|
fn main {
  let app = @express.express()

  app.use(@express.logger())
  app.use(@express.express_json())

  app.get("/users/:id", fn(req, res, _next) {
    res.json_string("{\"id\":\"" + req.param("id") + "\"}")
  })

  app.post("/echo", fn(req, res, _next) {
    match req.json_body() {
      Some(value) => res.json(value)
      None => res.send("body=" + req.body())
    }
  })

  app.get("/boom", fn(_req, _res, next) { next.fail("boom!") })

  app.use_error(fn(message, _req, res, _next) {
    res.status(500).send("caught: " + message)
  })

  app.listen(8080, fn(ok) { println(ok.to_string()) })
}

#Features

• Express-compatible routing — app.get/post/put/patch/delete/options/head/all(path, handler), app.add_route(method, path, handler), app.route(path).get(...).post(...) chainable builder, app.use(mw) / app.use_at(path, mw)
• Route parameters — :name params, * and *name wildcards, req.param(name) / req.params()
• Middleware chain — (Req, Res, Next) -> Unit with next.proceed() / next.fail(msg) / next.resume_with(err?)
• Error middleware — app.use_error(mw) / app.use_error_at(path, mw) with (String, Req, Res, Next) -> Unit signature
• Query & body parsing — req.query_param(name) / req.query_map() / req.raw_query(), JSON / URL-encoded (flat or extended) / text / raw body middleware
• Cookies — req.cookie(name) / req.cookies(), signed cookies (req.signed_cookie, req.signed_cookies, res.cookie_with(..., signed=true)), res.cookie(name, value) / res.cookie_with(...) / res.clear_cookie(name)
• Static files — express_static(root, options?) with ETag, Last-Modified, 304, Range (206/416), directory index, dotfiles and fallthrough control
• Content negotiation — req.accepts/accepts_charsets/accepts_encodings/accepts_languages, res.format, res.type_
• Conditional responses — req.fresh / req.stale, weak ETags, If-None-Match / If-Modified-Since → 304
• Mounted routers — app.use_router(path, router) / router.use_router(path, router) with prefix stripping, base_url accumulation and merge_params
• View rendering — app.engine(ext, fn) / app.set("view engine", ext) / res.render(view, locals?) / app.render(view, locals?)
• Streaming — res.write / res.write_bytes / res.end_stream / res.flush_headers
• Trust proxy — app.set("trust proxy", ...) drives req.ip / req.ips / req.protocol / req.secure / req.host / req.subdomains
• Native WebSockets — direct µWebSockets upgrade, no Node.js http workaround
• TLS / HTTPS — app.listen_tls(cert, key, port, cb) and listen_tls_host / listen_tls_async, with full UwsSslOptions support
• CORS — built-in permissive CORS middleware with preflight handling
• No X-Powered-By — the framework never sends that header

#Requirements

• MoonBit toolchain with the native backend (preferred_target = "native")
• A C++17 compiler (g++ / clang++) — µWebSockets is header-only C++
• zlib development headers, linked as -lz
• OpenSSL development headers (libssl-dev), linked as -lssl -lcrypto

#Building an application

import {
  "kupas/express" @lib,
}

supported_targets = "native"

pkgtype(kind: "executable")

options(
  "link": {
    "native": {
      "cc-link-flags": "-lstdc++ -lz -lssl -lcrypto",
    },
  },
)

moon run example/main        # demo server on :8080
moon test                   # router/query unit tests

#API

#Application

#Request (Req)

#Response (Res)

#Middleware

• Call next.proceed() to continue to the next middleware/route
• Call next.fail(message) to jump to error middleware
• A route handler is also (Req, Res, Next) -> Unit; calling next.proceed() falls through to later routes

fn(req, res, next) {
  println("before: " + req.path())
  next.proceed()
  println("after: " + req.path())
}

#Built-in middleware

#WebSockets

app.ws("/chat/:room", @express.ws_behavior(
  open=fn(conn) { conn.send("welcome") },
  message=fn(conn, message) {
    match message {
      @express.WsMessage::Text(text) => conn.send("echo:" + text)
      @express.WsMessage::Binary(data) => conn.send_bytes(data)
    }
  },
  close=fn(_conn, _code, _reason) { () },
))

#TLS / HTTPS

///|
fn main {
  let app = @express.express()

  app.get("/", fn(req, res, _next) { res.send("hello over " + req.protocol()) })

  // Switches the app to TLS, then blocks in the µWebSockets event loop.
  app.listen_tls("cert.pem", "key.pem", 8443, fn(ok) {
    println("TLS listen: " + ok.to_string())
  })
}

///|
fn main {
  let app = @express.express()
  app.get("/", fn(_req, res, _next) { res.send("hello over TLS") })

  app.listen_tls_async("cert.pem", "key.pem", "0.0.0.0", 8443, fn(ok) {
    println("TLS listen: " + ok.to_string())
  })
  app.run() // blocks
}

///|
fn main {
  let app = @express.express()
  app.enable_tls_with(@express.UwsSslOptions::{
    cert_file: "cert.pem",
    key_file: "key.pem",
    passphrase: Some("secret"),
    dh_params_file: None,
    ca_file: None,
    ssl_ciphers: Some("ECDHE+AESGCM"),
  })
  app.get("/", fn(_req, res, _next) { res.send("hello over TLS") })
  app.listen(8443, fn(ok) { println("TLS listen: " + ok.to_string()) })
}

openssl req -x509 -newkey rsa:2048 -nodes -days 30 \
  -keyout key.pem -out cert.pem -subj "/CN=localhost"
moon run example/tls   # HTTPS demo on :8443

#Helpers exported for tests and custom routers

#How it works

1. libusockets.h defines LIBUS_NO_SSL unless MOONBIT_UWS_WITH_TLS is set.
2. internal/ and eventing/ includes use paths relative to their own files, so the stubs compile without -I flags.
3. crypto/openssl.c includes ../internal/internal.h for the same reason.
4. µWebSockets headers include the vendored libusockets.h by relative path.

#Differences from Express

• Handlers and middleware must name the extra parameter (fn(req, res, _next)) because MoonBit has no arity-based overloading.
• next is a struct: next.proceed() / next.fail(msg) / next.resume_with(err?).
• Errors are strings, not Error objects.
• Route patterns support :name, * and *name; there is no regexp route.
• Body parsing is opt-in per middleware, exactly like body-parser.
• res.set() replaces a header; use res.append() to add multi-value headers.
• req.params is a Map[String, String]; use req.has_param(name) to check existence.
• X-Powered-By is never sent.
• compression, session and multipart handling are out of scope (they are separate packages in the Express ecosystem); bring your own middleware.
• trust proxy accepts "true", a hop count, a comma-separated IP list or the loopback / linklocal / uniquelocal presets. CIDR ranges are not parsed.
• express.static does not support the setHeaders callback.
• Router does not host WebSocket routes (app.ws is application-level only).
• RouteInfo.method is exposed as http_method() (MoonBit reserves method).

#Tests

moon run example/main
curl 'http://localhost:8080/users/42?tab=info'
curl -X POST -H 'Content-Type: application/json' -d '{"a":1}' http://localhost:8080/echo

#License