wip refactoring

Author: saviorand

lightbug.mojo

@@ -1,73 +1,133 @@
-from lightbug_api import (
-    App,
-    BaseRequest,
-    FromReq,
-    Router,
-    HandlerResponse,
-    JSONType,
-)
-from lightbug_http import HTTPRequest, HTTPResponse, OK
+# lightbug_api showcase
+# ─────────────────────────────────────────────────────────────────────────────
+# Run:  mojo lightbug.mojo
+# Test: curl http://localhost:8080/
+#       curl http://localhost:8080/items
+#       curl http://localhost:8080/items/42
+#       curl http://localhost:8080/items/42?verbose=true
+#       curl -X POST http://localhost:8080/items \
+#            -H 'Content-Type: application/json' \
+#            -d '{"name":"Widget","price":9.99}'
+#       curl -X PUT http://localhost:8080/items/42 \
+#            -H 'Content-Type: application/json' \
+#            -d '{"name":"Updated","price":19.99}'
+#       curl -X DELETE http://localhost:8080/items/42
+#       curl http://localhost:8080/v1/status
+# ─────────────────────────────────────────────────────────────────────────────
 
+from lightbug_api import App, Router, HandlerResponse
+from lightbug_api.context import Context
+from lightbug_api.response import Response
+from lightbug_http.http.json import Json, JsonSerializable, JsonDeserializable
 
-fn printer(req: HTTPRequest) raises -> HandlerResponse:
-    print("Got a request on ", req.uri.path, " with method ", req.method)
-    return OK(req.body_raw)
 
-fn hello(req: HTTPRequest) raises -> HandlerResponse:
-    return OK("Hello 🔥!")
+# ----------------------------------------------------------------- data types
 
+@fieldwise_init
+struct Item(JsonSerializable, Movable, Defaultable):
+    """An item returned in API responses."""
 
-fn nested(req: HTTPRequest) raises -> HandlerResponse:
-    print("Handling route:", req.uri.path)
-    # Returning a string will get marshaled to a proper `OK` response
-    return req.uri.path
+    var id: Int
+    var name: String
+    var price: Float64
 
+    fn __init__(out self):
+        self.id = 0
+        self.name = ""
+        self.price = 0.0
 
-struct Payload(FromReq):
-    var request: HTTPRequest
-    var json: JSONType
-    var a: Int
 
-    def __init__(out self, request: HTTPRequest, json: JSONType):
-        self.a = 1
-        self.request = request.copy()
-        self.json = json.copy()
+@fieldwise_init
+struct CreateItemRequest(JsonDeserializable, Movable, Defaultable):
+    """JSON body expected for POST /items."""
 
-    def __init__(out self, *, copy: Self):
-        self.a = copy.a
-        self.request = copy.request.copy()
-        self.json = copy.json.copy()
+    var name: String
+    var price: Float64
 
-    def __str__(self) -> String:
-        return String(self.a)
+    fn __init__(out self):
+        self.name = ""
+        self.price = 0.0
 
-    def from_request(mut self, req: HTTPRequest) raises -> Self:
-        self.a = 2
-        return self.copy()
 
+@fieldwise_init
+struct StatusResponse(JsonSerializable, Movable, Defaultable):
+    var status: String
+    var version: String
 
-fn custom_request_payload(req: HTTPRequest) raises -> HandlerResponse:
-    var payload = Payload(request=req, json=JSONType())
-    payload = payload.from_request(req)
-    print(payload.a)
+    fn __init__(out self):
+        self.status = ""
+        self.version = ""
 
-    # Returning a JSON as the response, this is a very limited placeholder for now
-    var json_response = JSONType()
-    json_response["a"] = String(payload.a)
-    return json_response^
 
+# ------------------------------------------------------------------ handlers
+
+fn index(ctx: Context) raises -> HandlerResponse:
+    """GET /  — plain-text welcome message."""
+    return Response.text("Welcome to lightbug_api 🔥")
+
+
+fn list_items(ctx: Context) raises -> HandlerResponse:
+    """GET /items  — return a hard-coded list as JSON."""
+    # In a real app you'd query a database here.
+    return Response.json(Item(1, "Widget", 9.99))
+
+
+fn get_item(ctx: Context) raises -> HandlerResponse:
+    """GET /items/{id}  — return one item by ID."""
+    var id = ctx.path_param("id", "unknown")
+    var verbose = ctx.query("verbose", "false")
+
+    if verbose == "true":
+        print("GET /items/", id, " (verbose mode)")
+
+    # Demonstrate that a bare Json value also works as HandlerResponse.
+    return Json(Item(42, String("Item ", id), 9.99))
+
+
+fn create_item(ctx: Context) raises -> HandlerResponse:
+    """POST /items  — deserialize JSON body, return 201 Created."""
+    var body = ctx.json[CreateItemRequest]()
+    var created = Item(100, body.name, body.price)
+    return Response.created(created)
+
+
+fn update_item(ctx: Context) raises -> HandlerResponse:
+    """PUT /items/{id}  — update an item."""
+    var id = ctx.path_param("id", "0")
+    var body = ctx.json[CreateItemRequest]()
+    return Response.json(Item(42, body.name, body.price))
+
+
+fn delete_item(ctx: Context) raises -> HandlerResponse:
+    """DELETE /items/{id}  — delete an item, return 204 No Content."""
+    var id = ctx.path_param("id", "0")
+    print("Deleting item", id)
+    return Response.no_content()
+
+
+fn health(ctx: Context) raises -> HandlerResponse:
+    """GET /v1/status  — health check mounted under the v1 sub-router."""
+    return Response.json(StatusResponse("ok", "1.0.0"))
+
+
+# --------------------------------------------------------------------- main
 
 fn main() raises:
     var app = App()
 
-    app.get("/", hello)
-
-    app.get("custom/", custom_request_payload)
+    # Root
+    app.get("/", index)
 
-    app.post("/", printer)
+    # Items resource — all HTTP verbs
+    app.get("/items",       list_items)
+    app.get("/items/{id}",  get_item)
+    app.post("/items",      create_item)
+    app.put("/items/{id}",  update_item)
+    app.delete("/items/{id}", delete_item)
 
-    var nested_router = Router("nested")
-    nested_router.get(path="all/echo/", handler=nested)
-    app.add_router(nested_router^)
+    # Sub-router mounted at /v1
+    var v1 = Router("v1")
+    v1.get("status", health)
+    app.add_router(v1^)
 
-    app.start_server()
+    app.run()

lightbug_api/__init__.mojo

@@ -1,30 +1,93 @@
 from lightbug_http import HTTPRequest, HTTPResponse, Server
+from lightbug_api.context import Context
+from lightbug_api.response import Response
 from lightbug_api.routing import (
     BaseRequest,
     FromReq,
+    Handler,
+    HandlerResponse,
+    PathPattern,
+    RouteMatch,
     RootRouter,
     Router,
-    HandlerResponse,
-    JSONType,
-    Handler,
 )
 
 
 struct App:
+    """The top-level application — register routes then call ``run()``.
+
+    Example::
+
+        fn main() raises:
+            var app = App()
+
+            app.get("/",              index)
+            app.get("/users/{id}",    get_user)
+            app.post("/users",        create_user)
+            app.delete("/users/{id}", delete_user)
+
+            var api = Router("v1")
+            api.get("status", health)
+            app.add_router(api^)     # mounts at /v1/status
+
+            app.run()
+    """
+
     var router: RootRouter
 
     def __init__(out self) raises:
         self.router = RootRouter()
 
+    # ------------------------------------------ route registration
+
     def get(mut self, path: String, handler: Handler) raises:
+        """Register a GET handler."""
         self.router.get(path, handler)
 
     def post(mut self, path: String, handler: Handler) raises:
+        """Register a POST handler."""
         self.router.post(path, handler)
 
+    def put(mut self, path: String, handler: Handler) raises:
+        """Register a PUT handler."""
+        self.router.put(path, handler)
+
+    def delete(mut self, path: String, handler: Handler) raises:
+        """Register a DELETE handler."""
+        self.router.delete(path, handler)
+
+    def patch(mut self, path: String, handler: Handler) raises:
+        """Register a PATCH handler."""
+        self.router.patch(path, handler)
+
+    def options(mut self, path: String, handler: Handler) raises:
+        """Register an OPTIONS handler."""
+        self.router.options(path, handler)
+
+    def head(mut self, path: String, handler: Handler) raises:
+        """Register a HEAD handler."""
+        self.router.head(path, handler)
+
     def add_router(mut self, var router: Router) raises -> None:
+        """Mount a sub-router under its path fragment."""
         self.router.add_router(router^)
 
+    # ------------------------------------------ start server
+
+    def run(mut self, host: String = "0.0.0.0", port: Int = 8080) raises:
+        """Start the HTTP server.
+
+        Args:
+            host: Bind address (default ``0.0.0.0``).
+            port: TCP port (default ``8080``).
+        """
+        var server = Server()
+        server.listen_and_serve(String(host, ":", port), self.router)
+
     def start_server(mut self, address: String = "0.0.0.0:8080") raises:
+        """Start the HTTP server.
+
+        Deprecated: use ``run(host, port)`` instead.
+        """
         var server = Server()
         server.listen_and_serve(address, self.router)