feat: update project metadata, enhance documentation, and add new middleware guides (#77)

Author: Leoj030

docs/.vitepress/config.mjs

@@ -31,7 +31,17 @@ export default defineConfig({
             { text: 'Project Stucture', link: '/docs/guides/project-structure' },
             { text: 'Routing', link: '/docs/guides/routing' },
             { text: 'Request & Response', link: '/docs/guides/req-res' },
-            { text: 'Middlewares', link: '/docs/guides/middleware' }
+            {
+                text: 'Middleware',
+                link: '/docs/guides/middleware',
+                items: [
+                    { text: 'Guard', link: '/docs/guides/middleware/guard' },
+                    { text: 'Validator', link: '/docs/guides/middleware/validator' },
+                    { text: 'Interceptor', link: '/docs/guides/middleware/interceptor' },
+                    
+                ]
+            },
+            { text: 'Exception', link: '/docs/guides/exception' },
           ]
         },
         {

docs/docs/blog/changelog.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## `v0.6.0` - June 2, 2026
+
+***`Nova.chain()` has been removed from the public API. Route-specific middleware is now handled exclusively through Attributes (`--@Guard`, `--@Interceptor`, `--@Validator`).***
+
+### Added
+
+- Exception handling utility with common HTTP error responses (`Nova.exception`) (#76)
+- Request validation via `--@Validator` attribute with support for `body`, `param`, and `query` (#73)
+- Interceptor support via `--@Interceptor` attribute using onion architecture (#72)
+- Guard attribute now supports multiple rules — `--@Guard(Auth, Admin)` (#72)
+- Initial `--@Guard` attribute support with comment-based syntax (#69)
+
+### Changed
+
+- Startup logger now displays registered routes with their applied Attributes (#75)
+- Runtime request logs now include status code and applied Attributes, with color-coded output by status class (`2xx` green, `3xx` blue, `4xx`/`5xx` red) (#75)
+- Core architecture restructured and modularized; adapters renamed (#71)
+- `libs/` renamed to `adapters/` (#69)
+- `Nova.chain()` is no longer exposed publicly — route-specific middleware must now be defined using Attributes (#69)
+
+### Fixed
+
+- Correct status property access in `devMiddleware` (#74)
+
+---
+
+**Before**
+```luau
+Home.Get = Nova.chain({ AuthMiddleware, AdminMiddleware }, function()
+    return Nova.response.send("Hello, World")
+end)
+```
+
+**After**
+```luau
+--@Guard(AuthRule, AdminRule)
+--@Interceptor(TransformRule)
+function Home.Get()
+    return Nova.response.send("Hello, World")
+end
+```
+
 ## `v0.5.7-test` - May 4, 2026
 
 ### Changed

docs/docs/guides/exception.md

@@ -0,0 +1,69 @@
+# Exception
+
+Nova provides a built-in `Exception` module for throwing structured HTTP errors from anywhere in your application — route handlers, Guard rules, Interceptors, or Validators. Exceptions are caught by Nova's global error handler and converted into a proper HTTP response automatically.
+
+## Usage
+
+Luau does not have a `throw` keyword, but `error()` behaves similarly — it halts execution immediately and can be caught by `pcall`. Nova's global error handler uses `pcall` under the hood, so it detects when an Exception is thrown and responds with the appropriate status code and message.
+
+```luau
+local Nova = require("@nova")
+local Exception = Nova.exception
+
+local function Auth(req: Nova.Request)
+    error(Exception.Forbidden())
+end
+
+return Auth
+```
+
+This reads almost exactly like `throw new ForbiddenException()` in other languages.
+
+## Custom Messages
+
+Every built-in Exception accepts an optional message. If omitted, a default message is used.
+
+```luau
+-- Uses default message: "Forbidden"
+error(Exception.Forbidden())
+
+-- Uses a custom message
+error(Exception.Forbidden("You do not have access to this resource"))
+```
+
+## Built-in Exceptions
+
+### 4xx — Client Errors
+
+| Function | Status | Default Message |
+|---|---|---|
+| `Exception.BadRequest()` | `400` | Bad Request |
+| `Exception.Unauthorized()` | `401` | Unauthorized |
+| `Exception.Forbidden()` | `403` | Forbidden |
+| `Exception.NotFound()` | `404` | Not Found |
+| `Exception.Conflict()` | `409` | Conflict |
+| `Exception.TooManyRequests()` | `429` | Too Many Requests |
+
+### 5xx — Server Errors
+
+| Function | Status | Default Message |
+|---|---|---|
+| `Exception.InternalServerError()` | `500` | Internal Server Error |
+| `Exception.BadGateway()` | `502` | Bad Gateway |
+| `Exception.ServiceUnavailable()` | `503` | Service Unavailable |
+
+## Custom Exceptions
+
+If you need a status code not covered by the built-in functions, use `Exception.HttpException()` directly — it is the base function all others are built on:
+
+```luau
+error(Exception.HttpException(418, "I'm a teapot"))
+```
+
+The first argument is the status code and the second is the message. Both are required.
+
+## Important Notes
+
+- `error()` halts execution immediately. Nothing after it runs.
+- Exceptions are only meaningful when thrown inside Nova's request pipeline. Throwing one outside of a request context will not produce an HTTP response.
+- All built-in Exceptions accept an optional custom message. `HttpException` requires one.

docs/docs/guides/middleware.md

@@ -7,45 +7,52 @@ Common use cases include:
 - **Logging:** Tracking request times and paths.
 - **Authentication:** Checking if a user is logged in.
 - **Validation:** Ensuring the request body contains the correct data.
-- **Security:** Adding headers or blocking malicious IPs.
+- **Security:** Adding headers.
 
 ## The Middleware Function
 
 A middleware in Nova is a simple function that receives two arguments:
 
-- `req:` The Request object.
-- `next:` A function that, when called, passes control to the next middleware in the stack.
+- `req` — The Request object.
+- `next` — A function that, when called, passes control to the next middleware in the stack.
 
 ### The Onion Pattern
 
-Nova uses the **Onion Pattern**. This means that when you call `next()`, the code execution **dives** into the next middleware or the final handler. Once the handler finishes, the execution "bubbles" back up, running the code after `next()`.
+Nova uses the **Onion Pattern**. This means that when you call `next()`, execution **dives** into the next middleware or the final handler. Once the handler finishes, execution "bubbles" back up, running the code after `next()`.
 
 ```luau
 local function myMiddleware(req, next)
     print("1. This runs BEFORE the route handler")
-    
-    next() -- Move to the next middleware or handler
-    
+
+    next()
+
     print("2. This runs AFTER the route handler is finished")
 end
 ```
 
+**Example Flow:**
+
+If you have Global Middleware `A`, Attribute `B`, and Handler `C`:
+
+```bash
+A (before next) → B (before next) → C (Handler) → B (after next) → A (after next)
+```
+
 ## Global Middleware
 
-Global middlewares are executed for **every single request** made to your server. These are defined when you initialize your Nova application.
+Global middleware runs on **every single request** made to your server. These are defined when you initialize your Nova application.
 
-The `Nova.new()` constructor accepts an optional second argument: a table of middleware functions.
+`Nova.new()` accepts an optional second argument: a table of middleware functions.
 
 ```luau
 local Nova = require("path/to/nova")
 
 local app = Nova.new(8080, {
-    function(req, next)
+    myMiddleware1 = function(req, next)
         print(`[{req.method}] {req.path}`)
         next()
     end,
-    function(req, next)
-        -- Another global middleware
+    myMiddleware1 = function(req, next)
         next()
     end
 })
@@ -55,57 +62,58 @@ app:listen(function()
 end)
 ```
 
-## Route-Specific Middleware (`Nova.chain`)
-
-Sometimes you only want middleware to run on specific routes (e.g., protecting a `/dashboard` route). For this, Nova provides the `Nova.chain` utility.
+Global middlewares execute in the order they are defined.
 
-`Nova.chain` takes two arguments:
+## Route-Specific Middleware (Attributes)
 
-- A table of middlewares.
-- The final route handler function.
+For middleware that should only run on specific routes, Nova uses **Attributes** — a comment-based syntax inspired by how decorators work in other languages.
 
-Usage in `route.luau`
+Attributes are defined directly above a route handler function using the `--@` prefix:
 
 ```luau
-local Nova = require("path/to/nova")
-
 local Home = {}
 
--- A simple auth middleware
-local function checkAuth(req, next)
-    if req.headers["Authorization"] then
-        next()
-    else
-        -- If we don't call next(), the chain stops here
-        return Nova.response.json({ error = "Unauthorized" }, { status = 401 })
-    end
+--@Guard(Auth)
+--@Interceptor(Transform)
+function Home.Get()
+    return Nova.response.send("Hello, World")
 end
 
--- Using Nova.chain to protect this specific GET route
-Home.Get = Nova.chain({ checkAuth }, function(req)
-    return Nova.response.json({ 
-        message = "Welcome to the protected dashboard!" 
-    })
-end)
-
 return Home
 ```
 
-## Execution Order
+Nova ships with three built-in Attributes, each serving a distinct purpose:
 
-It is important to understand the order in which Nova executes your code:
+| Attribute | Purpose |
+|---|---|
+| [`--@Guard`](/middleware/guard) | Protect routes — authentication and authorization |
+| [`--@Interceptor`](/middleware/interceptor) | Wrap the handler — logging, response transformation |
+| [`--@Validator`](/middleware/validator) | Validate incoming data — body, params, and query |
 
-- **Global Middlewares:** Executed in the order they were defined in `Nova.new`.
-- **Route Middlewares:** Executed in the order they appear in the `Nova.chain` table.
-- **Route Handler:** The actual logic inside your `Home.Get` or similar function.
-- **The "Bubble Up":** The code after `next()` in all middlewares runs in reverse order.
+### Execution Order
 
-**Example Flow:**
+Attributes always execute in this order, regardless of how they are defined:
+
+```bash
+Guard → Validator → Interceptor → Route Handler
+```
+
+Nova enforces this order at startup. If your Attributes are defined out of order, Nova will throw an error with a clear message telling you what to fix.
+
+### Convention-Driven Resolution
+
+Each Attribute references a **Rule** by name. Nova resolves Rules by convention from your `src/` directory:
+
+| Attribute | Rule Directory |
+|---|---|
+| `--@Guard(...)` | `src/guards/` |
+| `--@Interceptor(...)` | `src/interceptors/` |
+| `--@Validator(...)` | `src/validators/` |
 
-If you have Global Middleware `A`, Route Middleware `B`, and Handler` C`:
-`A (before next)` → `B (before next)` → `C (Handler)` → `B (after next)` → `A (after next)`
+See the dedicated pages for each Attribute to learn how to define Rules.
 
 ## Important Notes
 
-- **Always call `next()`:** If you do not call `next()`, the request will "hang" and never reach the handler (unless you intentionally return a response early to stop the request).
-- **Order Matters:** If Middleware A depends on data added to the request by Middleware B, Middleware B must come first in the table.
+- **Always call `next()`** in global middleware. If you do not, the request will never reach the handler unless you are intentionally returning an early response.
+- **Global middleware runs first**, before any Attributes on the route.
+- **Attributes are route-specific** — they have no effect on routes that do not declare them.

docs/docs/guides/middleware/guard.md

@@ -0,0 +1,77 @@
+# Guard
+
+A Guard protects a route by running an authorization check before the handler is reached. If the check passes, the request proceeds. If it fails, Nova halts the pipeline and responds immediately.
+
+Guards are the first Attribute to execute in the pipeline:
+
+```bash
+Guard → Validator → Interceptor → Route Handler
+```
+
+## Defining a Guard Attribute
+
+Apply a Guard to a route handler using the `--@Guard` comment above the function:
+
+```luau
+local Home = {}
+
+--@Guard(Auth)
+function Home.Get()
+    return Nova.response.send("Hello, World")
+end
+
+return Home
+```
+
+Multiple rules can be passed to a single Guard:
+
+```luau
+--@Guard(Auth, Admin)
+function Home.Get()
+    return Nova.response.send("Hello, World")
+end
+```
+
+Rules are executed left to right. If any rule fails, the pipeline halts.
+
+## Defining a Guard Rule
+
+Guard Rules live in `src/guards/`. Each file exports a single function that receives the request and returns a `boolean`.
+
+```luau
+-- src/guards/Auth.luau
+local Nova = require("@nova")
+
+local function Auth(req: Nova.Request)
+    return true -- allow the request
+end
+
+return Auth
+```
+
+If the rule returns `false`, Nova responds with `401 Unauthorized` and the pipeline stops. If it returns `true`, the request moves to the next step.
+
+## Throwing Exceptions
+
+Returning `false` always produces a `401`. If you need a different status code, use `Nova.exception` with Luau's `error()` instead:
+
+```luau
+local Nova = require("@nova")
+local Exception = Nova.exception
+
+local function Auth(req: Nova.Request)
+    error(Exception.Forbidden())
+end
+
+return Auth
+```
+
+`error()` halts execution immediately and Nova's global error handler catches it, responding with the appropriate status code and message.
+
+You can also pass a custom message:
+
+```luau
+error(Exception.Forbidden("You do not have access to this resource"))
+```
+
+See the [Exception](/docs/guides/exception) page for all available exceptions.