#moonzero

flowchart LR
  conf["RestConf"] --> engine["RestEngine"]
  app["application"] --> engine
  engine -->|"build()"| server["Server"]
  server -->|"to_asgi()"| asgi(["AsgiApp"])
  asgi --> host["any ASGI host"]

#Install

moon add moonbitstack/moonzero

#Quickstart

let app = @moonapi.App::new()
let api = @moonzero.Group::new(app, "/api/v1")   // a prefix for a set of routes
api.get("/ping", _ctx => @moonapi.text(200, "pong"))

let conf = @moonzero.ServiceConf::new(
  name="greet", host="127.0.0.1", port=12000, timeout_ms=3000, log_level=Info,
)
let server = @moonzero.Server::new(conf, app)
  .use_(@moonzero.cors(@moonzero.CorsConf::new()))   // Access-Control-* headers
  .use_(@moonzero.request_id())                      // x-request-id per request
  .use_(@moonzero.recovery)                          // 500 while nothing is sent
  .use_(@moonzero.logging)

println(server.describe())   // "greet listening on 127.0.0.1:12000"

#Packages

#Ports

#Configuration

let conf = @moonzero.RestConf::from_yaml(
  #|Name: greet-api
  #|Host: 127.0.0.1
  #|Port: 12000
  #|Timeout: 5000
  #|Middlewares:
  #|  Gunzip: false
  #|Log:
  #|  Level: error
)
let engine = @moonzero.RestEngine::new(conf)
println(engine.names().join(", "))

#Route options

let api = @moonzero.Group::new(app, "/api/v1")
let admin = api.sub("/admin").options_(
  @moonzero.RouteOptions::new()
    .jwt(secret="current", prev_secret=Some("retiring"))
    .timeout(500)
    .max_bytes(4096)
    .priority(engine.priority_shedder()),
)
admin.get("/stats", ctx => @moonapi.text(200, "ok"))

#Middlewares

let clock = @moonzero.Clock::new(() => 0L)   // inject time; no hidden reads
let server = @moonzero.Server::new(conf, app)
  .use_(@moonzero.maxbytes(1 << 20))                     // 413 past 1 MiB
  .use_(@moonzero.rate_limit(@moonzero.TokenBucket::new(100.0), clock))
  .use_(@moonzero.breaker(@moonzero.Breaker::new(clock)))
  .use_(@moonzero.timeout(3000L, clock))
  .use_(@moonzero.tracing())                             // W3C traceparent in/out
  .use_(@moonzero.metrics(metrics, clock))               // path/method/code families

• cors matches an origin against the allowed set and its subdomains, answers a preflight with 204, and never pairs * with credentials.
• recovery answers 500 only while nothing of the response has gone out; once the status line is on the wire the error is re-raised for the server to close on.
• gunzip inflates a Content-Encoding: gzip body, with an optional cap on the inflated size; a body that will not inflate is answered 400.
• content_security verifies X-Content-Security: RSA-sealed envelope, HS256-class MAC over the request, a timestamp inside the tolerance, and an AES-ECB payload when the envelope says the body is sealed.
• metrics records two families labelled path, method and code; the labels stay three labels, so a dashboard can select on any one of them.
• layer adapts any mid.Layer from the ASGI toolkit, so a layer written for the host drops in unchanged.

#zRPC

let rpc = @moonzero.RpcServer::of(@moonzero.RpcServerConf::new(name="greeter"))
rpc.group("hello.Greeter").register("SayHello", req => req)

let ch = @moonzero.RpcChannel::connect(rpc)
  .with_interceptors(@moonzero.client_interceptors(conf.middlewares, deps))
let reply = ch.call_through("/hello.Greeter/SayHello", b"world")

// native: a listener is a socket
let listener = @socket.Listener::new(rpc)
@async.with_task_group(g => {
  g.spawn_bg(() => listener.serve(port=12001))
  let ch = @socket.SocketChannel::connect("127.0.0.1", 12001)
  let reply = ch.call("/hello.Greeter/SayHello", b"world")
  ch.close()
  listener.stop()
})

#Balancing

let ch = @moonzero.LoadBalancedChannel::new(
  _ => view.endpoints(),
  cluster,
  "greeter",
  balancer=@moonzero.Balancer::p2c(),
)

#Stores

// with `moonbitstack/moonzero/stores/redis` as @redis and `.../stores/cache` as @cache
let store = @redis.RedisStore::new(client, prefix="orders:")
let cache : @cache.Cache[Order] = @cache.Cache::new(
  store, encode=order_to_bytes, decode=order_of_bytes, ttl_ms=60_000L,
)
let order = cache.take("42", () => load_order(42))

#Resilience

• Breaker counts the last ten seconds in forty buckets and sheds a fraction of calls once the failure ratio is past its budget — a struggling backend keeps the load it can still serve.
• Shedder refuses work only when the machine is both hot and full: the CPU at or above the threshold, and more calls in flight than the recent throughput and latency can carry.
• limit offers a token bucket, a fixed window and a connection count, each in memory or on Redis. The Redis token limiter marks the shared bucket down the moment a call fails and keeps limiting from its local bucket until a probe finds Redis again.

#Discovery

@moonzero.hold(registry, "greeter", @moonzero.Endpoint::new("10.0.0.1", 12001))
let view = @moonzero.View::new()
group.spawn_bg(no_wait=true, () => view.follow(registry, "greeter"))

#Observability

mount_metrics(app, engine.metrics())     // GET /metrics

#Licence