docs(examples): per-feature example suite — routing, OpenAPI, DI, OAuth2/JWT, forms, SSE, WebSocket (20 new).

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

Author: Lfan-ke

examples/02-routing/main.mbt

@@ -0,0 +1,41 @@
+///|
+/// Routing across every HTTP verb, `:param` path extraction, and the 404-vs-405
+/// distinction. `App::get/post/put/patch/delete` bind a method to a path;
+/// `App::route` binds an explicit `Method`; a `:name` segment lands in
+/// `Context::param`. A path that exists under another verb answers 405, an
+/// unknown path answers 404.
+///
+///     moon run examples/02-routing
+#coverage.skip
+fn main {
+  let app = @moonapi.App::new()
+  app.get("/items/:id", ctx => {
+    @moonapi.text(200, "item " + ctx.param("id").unwrap())
+  })
+  app.post("/items", _ctx => @moonapi.text(201, "created"))
+  app.put("/items/:id", _ctx => @moonapi.text(200, "replaced"))
+  app.patch("/items/:id", _ctx => @moonapi.text(200, "patched"))
+  app.delete("/items/:id", _ctx => @moonapi.text(200, "deleted"))
+  app.route(@moonapi.Head, "/items", _ctx => @moonapi.text(200, ""))
+  app.route(@moonapi.Options, "/items", _ctx => @moonapi.text(204, ""))
+  let hit = (verb : String, path : String) => {
+    let req : @moonasgi.Request = {
+      http_method: verb,
+      path,
+      query_string: b"",
+      headers: [],
+      body: b"",
+    }
+    let r = app.handle(req)
+    println("\{verb} \{path} -> \{r.status} \{@utf8.decode_lossy(r.body[:])}")
+  }
+  hit("GET", "/items/233")
+  hit("POST", "/items")
+  hit("PUT", "/items/233")
+  hit("PATCH", "/items/233")
+  hit("DELETE", "/items/233")
+  hit("HEAD", "/items")
+  hit("OPTIONS", "/items")
+  hit("GET", "/items") // path exists (POST/HEAD/OPTIONS) but not for GET -> 405
+  hit("GET", "/missing") // no such path -> 404
+}

examples/02-routing/moon.pkg

@@ -0,0 +1,7 @@
+import {
+  "Lfan-ke/moonapi",
+  "Lfan-ke/moonasgi",
+  "moonbitlang/core/encoding/utf8",
+}
+
+pkgtype(kind: "executable")

examples/03-openapi-versions/main.mbt

@@ -0,0 +1,39 @@
+///|
+/// One set of typed routes, every mainstream spec version. `App::openapi_json`
+/// emits Swagger 2.0, OpenAPI 3.0.3, and OpenAPI 3.1.0 off the same descriptors;
+/// `App::openapi` additionally takes the document metadata (title, description,
+/// contact, license, servers) and `swagger_ui` returns a ready docs page. The
+/// `demo_app` carries typed bodies, so the emitted specs show `components`
+/// (`definitions` in 2.0) with `$ref`s.
+///
+///     moon run examples/03-openapi-versions
+#coverage.skip
+fn main {
+  let app = @moonapi.demo_app()
+  app.get(
+    "/legacy",
+    _ctx => @moonapi.text(200, "old"),
+    summary="the legacy list",
+    tags=["misc"],
+    deprecated=true,
+  )
+  println("--- Swagger 2.0 (definitions) ---")
+  println(app.openapi_json(version=@moonapi.Swagger20))
+  println("--- OpenAPI 3.0.3 (components/schemas) ---")
+  println(app.openapi_json(version=@moonapi.OpenApi30))
+  println("--- OpenAPI 3.1.0 with full info metadata ---")
+  let doc = app.openapi(
+    version=@moonapi.OpenApi31,
+    title="Widget API",
+    api_version="2.3.0",
+    description="a comprehensive moonapi example",
+    contact=Some({ name: "lfanke", url: "", email: "heke1228@example.com" }),
+    license=Some({
+      name: "Apache-2.0",
+      url: "https://www.apache.org/licenses/LICENSE-2.0",
+    }),
+    servers=[{ url: "https://api.example.com", description: "production" }],
+  )
+  println(doc.stringify(indent=2))
+  println("swagger_ui page: \{@moonapi.swagger_ui().length()} bytes")
+}

examples/03-openapi-versions/moon.pkg

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

examples/04-descriptors/main.mbt

@@ -0,0 +1,35 @@
+///|
+/// The descriptor tree drives validation and OpenAPI from one source of truth.
+/// The `demo_app`'s `Endpoint` / `Param` / `Schema` / `ResponseSpec` descriptors
+/// validate an inbound `POST /users` body and a typed `:id` path param, and the
+/// same tree emits the request/response body schemas — objects, arrays, and a
+/// nested `Address` hoisted into `components/schemas` behind a `$ref`. A body
+/// that violates the descriptor comes back as a FastAPI-shaped `422`.
+///
+///     moon run examples/04-descriptors
+#coverage.skip
+fn main {
+  let app = @moonapi.demo_app()
+  let json_headers = [("content-type", "application/json")]
+  let hit = (verb : String, path : String, body : String) => {
+    let req : @moonasgi.Request = {
+      http_method: verb,
+      path,
+      query_string: b"",
+      headers: json_headers,
+      body: @utf8.encode(body),
+    }
+    let r = app.handle(req)
+    println("\{verb} \{path} -> \{r.status} \{@utf8.decode_lossy(r.body[:])}")
+  }
+  // A conforming body validates and deserialises.
+  hit(
+    "POST", "/users", "{\"name\":\"qwq\",\"email\":\"qwq@example.com\",\"age\":23}",
+  )
+  // Missing the required `name` -> 422 with a located `missing` error.
+  hit("POST", "/users", "{\"email\":\"qwq@example.com\",\"age\":23}")
+  // A typed integer path param returns the nested `User` (address + tags).
+  hit("GET", "/users/233", "")
+  println("--- OpenAPI 3.1.0 (note components/schemas + $ref) ---")
+  println(app.openapi_json(version=@moonapi.OpenApi31))
+}

examples/04-descriptors/moon.pkg

@@ -0,0 +1,7 @@
+import {
+  "Lfan-ke/moonapi",
+  "Lfan-ke/moonasgi",
+  "moonbitlang/core/encoding/utf8",
+}
+
+pkgtype(kind: "executable")

examples/05-constraints/main.mbt

@@ -0,0 +1,84 @@
+///|
+/// Pydantic-style field constraints and the scalar schema types, emitted into
+/// the OpenAPI schema and enforced off one descriptor. Every `Constraint` is
+/// exercised — `Minimum` / `Maximum`, `ExclusiveMinimum` / `ExclusiveMaximum`,
+/// `MultipleOf`, `MinLength` / `MaxLength`, `Pattern`, `MinItems` / `MaxItems` —
+/// alongside the scalar types `SInt` / `SFloat` / `SStr` / `SBool` / `SNull` /
+/// `SArray` and a closed `SEnum`. A conforming body validates; a low/short body
+/// and a high/long body each return a `422` naming every violation by its
+/// pydantic error type.
+///
+///     moon run examples/05-constraints
+#coverage.skip
+fn main {
+  let color = @moonapi.SEnum(@moonapi.SStr, [
+    "red".to_json(),
+    "green".to_json(),
+    "blue".to_json(),
+  ])
+  let schema = @moonapi.Schema::object("Order", [
+    @moonapi.Field::new("qty", @moonapi.SInt, constraints=[
+      @moonapi.Minimum(1.0),
+      @moonapi.Maximum(99.0),
+    ]),
+    @moonapi.Field::new("step", @moonapi.SInt, constraints=[
+      @moonapi.MultipleOf(5.0),
+    ]),
+    @moonapi.Field::new("ratio", @moonapi.SFloat, constraints=[
+      @moonapi.ExclusiveMinimum(0.0),
+      @moonapi.ExclusiveMaximum(1.0),
+    ]),
+    @moonapi.Field::new("code", @moonapi.SStr, constraints=[
+      @moonapi.MinLength(3),
+      @moonapi.MaxLength(8),
+      @moonapi.Pattern("^[a-z]+$"),
+    ]),
+    @moonapi.Field::new("tags", @moonapi.Schema::array(@moonapi.SStr), constraints=[
+      @moonapi.MinItems(1),
+      @moonapi.MaxItems(3),
+    ]),
+    @moonapi.Field::new("active", @moonapi.SBool),
+    @moonapi.Field::new("color", color),
+    // A field whose value must be JSON null.
+    @moonapi.Field::new("note", @moonapi.SNull, required=false),
+  ])
+  let ep = @moonapi.Endpoint::new(request_body=Some(schema))
+  let app = @moonapi.App::new()
+  app.post(
+    "/orders",
+    ctx => {
+      let errs = ep.validate(ctx)
+      if errs.length() > 0 {
+        @moonapi.unprocessable(errs)
+      } else {
+        @moonapi.text(201, "order accepted")
+      }
+    },
+    endpoint=Some(ep),
+  )
+  let hit = (label : String, body : String) => {
+    let req : @moonasgi.Request = {
+      http_method: "POST",
+      path: "/orders",
+      query_string: b"",
+      headers: [("content-type", "application/json")],
+      body: @utf8.encode(body),
+    }
+    let r = app.handle(req)
+    println("\{label} -> \{r.status} \{@utf8.decode_lossy(r.body[:])}")
+  }
+  // Within every bound.
+  hit(
+    "ok  ", "{\"qty\":5,\"step\":10,\"ratio\":0.5,\"code\":\"abc\",\"tags\":[\"a\",\"b\"],\"active\":true,\"color\":\"red\"}",
+  )
+  // Below the lower bounds, too short, wrong scalar types, off the enum.
+  hit(
+    "low ", "{\"qty\":0,\"step\":7,\"ratio\":1.5,\"code\":\"AB\",\"tags\":[],\"active\":\"yes\",\"color\":\"pink\",\"note\":5}",
+  )
+  // Above the upper bounds, too long, too many items.
+  hit(
+    "high", "{\"qty\":100,\"step\":5,\"ratio\":0.0,\"code\":\"toolongcode\",\"tags\":[\"a\",\"b\",\"c\",\"d\"],\"active\":false,\"color\":\"green\"}",
+  )
+  println("--- OpenAPI 3.1.0 (constraints + enum in the schema) ---")
+  println(app.openapi_json(version=@moonapi.OpenApi31))
+}

examples/05-constraints/moon.pkg

@@ -0,0 +1,7 @@
+import {
+  "Lfan-ke/moonapi",
+  "Lfan-ke/moonasgi",
+  "moonbitlang/core/encoding/utf8",
+}
+
+pkgtype(kind: "executable")

examples/06-typed-body/main.mbt

@@ -0,0 +1,49 @@
+///|
+/// The typed body extractors. `Context::body_validated[T]` checks the JSON body
+/// against a descriptor and only then deserialises into a `derive(FromJson)`
+/// struct, returning either the built value or a FastAPI-shaped `422`;
+/// `Context::body[T]` is the unchecked, total counterpart that yields `None`
+/// rather than erroring. `GreetReq` is a library struct with `derive(FromJson)`
+/// and a `schema()`.
+///
+///     moon run examples/06-typed-body
+#coverage.skip
+fn main {
+  let app = @moonapi.App::new()
+  // Validated extraction: conform, or get located errors.
+  app.post("/greet", ctx => {
+    match
+      (
+        ctx.body_validated(@moonapi.GreetReq::schema()) :
+        Result[@moonapi.GreetReq, _]) {
+      Ok(g) => @moonapi.text(200, "Hello, " + g.name)
+      Err(errs) => @moonapi.unprocessable(errs)
+    }
+  })
+  // Unchecked extraction: a total `T?`, `None` when the body cannot shape-match.
+  app.post("/echo", ctx => {
+    let parsed : @moonapi.GreetReq? = ctx.body()
+    match parsed {
+      Some(g) => @moonapi.text(200, "parsed name=" + g.name)
+      None => @moonapi.text(200, "unparseable")
+    }
+  })
+  let hit = (path : String, body : String) => {
+    let req : @moonasgi.Request = {
+      http_method: "POST",
+      path,
+      query_string: b"",
+      headers: [("content-type", "application/json")],
+      body: @utf8.encode(body),
+    }
+    let r = app.handle(req)
+    println(
+      "POST \{path} \{body} -> \{r.status} \{@utf8.decode_lossy(r.body[:])}",
+    )
+  }
+  hit("/greet", "{\"name\":\"lfanke\"}") // 200
+  hit("/greet", "{\"name\":233}") // 422 string_type
+  hit("/greet", "") // 422 missing body
+  hit("/echo", "{\"name\":\"qwq\"}") // parsed
+  hit("/echo", "not json at all") // unparseable
+}

examples/06-typed-body/moon.pkg

@@ -0,0 +1,7 @@
+import {
+  "Lfan-ke/moonapi",
+  "Lfan-ke/moonasgi",
+  "moonbitlang/core/encoding/utf8",
+}
+
+pkgtype(kind: "executable")