docs(examples): per-feature example suite — middleware, resilience, discovery, tracing, zrpc (14 new).

Signed-off-by: 林晨 (Leo Cheng) <chengkelfan@qq.com>

Author: Lfan-ke

examples/00-metrics/main.mbt

@@ -18,6 +18,7 @@
 /// Prometheus exposition a `/metrics` scrape would read back.
 ///
 ///     moon run --target native examples/00-metrics
+#coverage.skip
 async fn main {
   let app = @moonapi.App::new()
   let api = @moonzero.Group::new(app, "/api/v1")

examples/01-config/main.mbt

@@ -0,0 +1,63 @@
+///|
+/// Load a `ServiceConf` three ways — the `new()` defaults, a partial JSON config
+/// filled from those defaults, and the YAML `etc/*.yaml` format go-zero ships —
+/// then read the `LogLevel` ordering and the raw `yaml_parse` output.
+///
+///     moon run examples/01-config
+#coverage.skip
+fn main {
+  try {
+    let def = @moonzero.ServiceConf::new()
+    println("defaults: " + describe(def))
+
+    // A partial JSON config: only the fields present override; the rest fall back
+    // to the same defaults `new()` uses (go-zero's `,optional`/`,default=`).
+    let json_src =
+      #|{ "name": "greet", "port": 9000, "log_level": "error" }
+    let from_json = @moonzero.ServiceConf::from_json(json_src)
+    println("from_json: " + describe(from_json))
+
+    // The YAML config format go-zero actually writes, decoded through the same
+    // lenient field reader so it agrees with JSON field-for-field.
+    let yaml_src = "name: greet\nhost: 127.0.0.1\nport: 9000\ntimeout_ms: 1500\nlog_level: debug\n"
+    let from_yaml = @moonzero.ServiceConf::from_yaml(yaml_src)
+    println("from_yaml: " + describe(from_yaml))
+
+    // LogLevel derives Compare in verbosity order, so thresholds test directly.
+    let debug = @moonzero.LogLevel::parse("debug")
+    let error = @moonzero.LogLevel::parse("error")
+    println(
+      "log levels: " +
+      debug.to_string() +
+      " < " +
+      error.to_string() +
+      " = " +
+      (debug < error).to_string(),
+    )
+    println(
+      "unknown level falls back to: " +
+      @moonzero.LogLevel::parse("verbose").to_string(),
+    )
+
+    // The self-built YAML parser lowered to the same Json the JSON loader reads.
+    let doc = @moonzero.yaml_parse(
+      "name: greet\nnested:\n  port: 9000\n  tags:\n    - a\n    - b\n",
+    )
+    println("yaml_parse -> " + doc.stringify())
+  } catch {
+    ConfigError(msg) => println("config error: " + msg)
+  }
+}
+
+///|
+fn describe(conf : @moonzero.ServiceConf) -> String {
+  conf.name +
+  " " +
+  conf.host +
+  ":" +
+  conf.port.to_string() +
+  " timeout=" +
+  conf.timeout_ms.to_string() +
+  "ms level=" +
+  conf.log_level.to_string()
+}

examples/01-config/moon.pkg

@@ -0,0 +1,5 @@
+import {
+  "Lfan-ke/moonzero",
+}
+
+pkgtype(kind: "executable")

examples/01-config/pkg.generated.mbti

@@ -0,0 +1,12 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Lfan-ke/moonzero/examples/01-config"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits

examples/02-middleware/main.mbt

@@ -0,0 +1,130 @@
+///|
+/// Assemble the base middleware onion — CORS, request-id, tracing, structured
+/// logging, request logging, and recovery — over a two-route app, then drive a
+/// normal request (watching the injected response headers and the JSON access log)
+/// and one that raises (watching recovery answer 500 instead of crashing).
+///
+///     moon run --target native examples/02-middleware
+#coverage.skip
+async fn main {
+  let app = @moonapi.App::new()
+  let api = @moonzero.Group::new(app, "/api/v1")
+  api.get("/ping", _ctx => @moonapi.text(200, "pong"))
+  api.get("/boom", _ctx => raise Boom)
+
+  // An incrementing clock so the access log shows a real elapsed duration.
+  let tick : Ref[Int64] = { val: 0L }
+  let clock = @moonzero.Clock::new(() => {
+    let now = tick.val
+    tick.val = now + 5L
+    now
+  })
+  let conf = @moonzero.ServiceConf::new(
+    name="greet",
+    host="127.0.0.1",
+    port=8888,
+  )
+  let onion = @moonzero.Server::new(conf, app)
+    .use_(@moonzero.cors(@moonzero.CorsConf::new()))
+    .use_(@moonzero.request_id())
+    .use_(@moonzero.tracing())
+    .use_(@moonzero.structured_logging(clock))
+    .use_(@moonzero.logging)
+    .use_(@moonzero.recovery)
+  println(onion.describe())
+  let handler = onion.to_asgi()
+
+  // A normal request: 200, with the middleware's response headers stamped on.
+  let (status, headers, body) = drive(handler, "GET", "/api/v1/ping", [])
+  println("ping -> " + status.to_string() + " body=" + text(body))
+  println("  x-request-id=" + hget(headers, "x-request-id"))
+  println("  x-trace-id=" + hget(headers, "x-trace-id"))
+  println("  traceparent=" + hget(headers, "traceparent"))
+  println(
+    "  access-control-allow-origin=" +
+    hget(headers, "access-control-allow-origin"),
+  )
+
+  // A client-supplied request id is reused verbatim rather than minted.
+  let (_, reused, _) = drive(handler, "GET", "/api/v1/ping", [
+    ("x-request-id", "heke1228"),
+  ])
+  println("supplied request id reused: " + hget(reused, "x-request-id"))
+
+  // A handler that raises: recovery answers 500 instead of letting it escape.
+  let (boom_status, _, boom_body) = drive(handler, "GET", "/api/v1/boom", [])
+  println("boom -> " + boom_status.to_string() + " body=" + text(boom_body))
+
+  // The structured access-log record on its own, rendered as one JSON line.
+  let entry = @moonzero.RequestLog::{
+    http_method: "GET",
+    path: "/api/v1/ping",
+    status: 200,
+    duration_ms: 5L,
+    request_id: "req-1",
+    client_ip: "127.0.0.1",
+    user_agent: "lfanke",
+  }
+  println("RequestLog: " + entry.render())
+}
+
+///|
+/// A local error a route raises to exercise recovery.
+suberror Boom
+
+///|
+/// Feed one request through an assembled ASGI onion in-process, capturing the
+/// response status, the `HttpResponseStart` headers, and the body.
+async fn drive(
+  handler : @moonasgi.AsgiApp,
+  verb : String,
+  path : String,
+  headers : Array[(String, String)],
+) -> (Int, Array[(String, String)], Bytes) {
+  let scope = @moonasgi.Scope::Http(
+    @moonasgi.HttpScope::new(http_method=verb, path~, headers~),
+  )
+  let sent : Ref[Bool] = { val: false }
+  let receive : @moonasgi.Receive = () => {
+    if sent.val {
+      @moonasgi.Event::HttpDisconnect
+    } else {
+      sent.val = true
+      @moonasgi.Event::HttpRequest(body=b"", more_body=false)
+    }
+  }
+  let status : Ref[Int] = { val: 0 }
+  let out : Ref[Array[(String, String)]] = { val: [] }
+  let body = Buffer()
+  let sink : @moonasgi.Send = event => {
+    match event {
+      HttpResponseStart(status=s, headers=h, ..) => {
+        status.val = s
+        out.val = h
+      }
+      HttpResponseBody(body=b, ..) => body.write_bytes(b)
+      _ => ()
+    }
+  }
+  handler(scope, receive, sink)
+  (status.val, out.val, body.to_bytes())
+}
+
+///|
+fn hget(headers : Array[(String, String)], name : String) -> String {
+  for pair in headers {
+    if pair.0 == name {
+      return pair.1
+    }
+  }
+  "(none)"
+}
+
+///|
+fn text(b : Bytes) -> String {
+  let sb = StringBuilder::new()
+  for i = 0; i < b.length(); i = i + 1 {
+    sb.write_char(b[i].to_int().unsafe_to_char())
+  }
+  sb.to_string()
+}

examples/02-middleware/moon.pkg

@@ -0,0 +1,12 @@
+// Drives the assembled ASGI onion in-process, awaiting the async app the
+// middleware wraps — native-only, like moonzero's other async edges.
+supported_targets = "native"
+
+import {
+  "Lfan-ke/moonzero",
+  "Lfan-ke/moonapi",
+  "Lfan-ke/moonasgi",
+  "moonbitlang/async",
+}
+
+pkgtype(kind: "executable")

examples/03-resilience-core/main.mbt

@@ -0,0 +1,111 @@
+///|
+/// Drive each resilience decision core over an explicit clock, so its whole state
+/// machine is visible without a running server: the token bucket, the circuit
+/// breaker, the request deadline, the max-conns permit pool, and the fixed-window
+/// period limiter.
+///
+///     moon run examples/03-resilience-core
+#coverage.skip
+fn main {
+  // TokenBucket: a burst of `capacity` back-to-back, then empty until it refills.
+  let bucket = @moonzero.TokenBucket::new(3.0, burst=3.0, now=0)
+  let burst = [
+    bucket.allow(0),
+    bucket.allow(0),
+    bucket.allow(0),
+    bucket.allow(0),
+  ]
+  println("token bucket burst-of-3 then empty: " + bools(burst))
+  println("  available after 1s refill: " + bucket.available(1000L).to_string())
+  println("  admits again once refilled: " + bucket.allow(1000L).to_string())
+
+  // Breaker: two consecutive failures trip it Open; after the cool-down it admits
+  // one HalfOpen probe, and a probe success closes it again.
+  let breaker = @moonzero.Breaker::new(
+    max_failures=2,
+    open_ms=1000L,
+    half_open_max=1,
+  )
+  breaker.record_failure(0L)
+  breaker.record_failure(0L)
+  println("breaker after 2 failures: " + breaker.state().to_string())
+  println("  admits while open (t=500): " + breaker.allow(500L).to_string())
+  let probe = breaker.allow(1000L)
+  println(
+    "  admits half-open probe (t=1000): " +
+    probe.to_string() +
+    ", state=" +
+    breaker.state().to_string(),
+  )
+  breaker.record_success()
+  println("  after probe success: " + breaker.state().to_string())
+
+  // Deadline: a budget measured from a start instant; a non-positive budget never
+  // expires (go-zero's disabled-timeout convention).
+  let deadline = @moonzero.Deadline::start(500L, 0L)
+  println(
+    "deadline remaining at t=100: " +
+    deadline.remaining(100L).to_string() +
+    "ms, expired at t=600: " +
+    deadline.expired(600L).to_string(),
+  )
+  println(
+    "  disabled deadline expires: " +
+    @moonzero.Deadline::start(0L, 0L).expired(999999L).to_string(),
+  )
+
+  // MaxConns: a permit pool that admits up to `max` in flight at once.
+  let conns = @moonzero.MaxConns::new(2)
+  let taken = [conns.try_acquire(), conns.try_acquire(), conns.try_acquire()]
+  println(
+    "max-conns(2) three acquires: " +
+    bools(taken) +
+    ", in_flight=" +
+    conns.in_flight().to_string(),
+  )
+  conns.release()
+  println(
+    "  after one release, acquire again: " + conns.try_acquire().to_string(),
+  )
+
+  // PeriodLimit: a fixed window of `quota` per period, per key.
+  let period = @moonzero.PeriodLimit::new(period_secs=1, quota=3)
+  let window = [
+    period.take("k", 0L),
+    period.take("k", 0L),
+    period.take("k", 0L),
+    period.take("k", 0L),
+  ]
+  println("period-limit quota-3 window: " + join(window.map(period_name)))
+  println(
+    "  next window (t=1s) resets: " + period_name(period.take("k", 1000L)),
+  )
+}
+
+///|
+fn period_name(r : @moonzero.PeriodResult) -> String {
+  match r {
+    PeriodAllowed => "allowed"
+    PeriodHitQuota => "hit-quota"
+    PeriodOverQuota => "over-quota"
+  }
+}
+
+///|
+fn bools(items : Array[Bool]) -> String {
+  join(items.map(b => b.to_string()))
+}
+
+///|
+fn join(items : Array[String]) -> String {
+  let sb = StringBuilder::new()
+  sb.write_char('[')
+  for i = 0; i < items.length(); i = i + 1 {
+    if i > 0 {
+      sb.write_string(", ")
+    }
+    sb.write_string(items[i])
+  }
+  sb.write_char(']')
+  sb.to_string()
+}

examples/03-resilience-core/moon.pkg

@@ -0,0 +1,5 @@
+import {
+  "Lfan-ke/moonzero",
+}
+
+pkgtype(kind: "executable")

examples/03-resilience-core/pkg.generated.mbti

@@ -0,0 +1,12 @@
+// Generated using `moon info`, DON'T EDIT IT
+package "Lfan-ke/moonzero/examples/03-resilience-core"
+
+// Values
+
+// Errors
+
+// Types and methods
+
+// Type aliases
+
+// Traits