Router System Guide

Overview

cHttpServerRouter is the core component of HttpServer, responsible for mapping HTTP requests to corresponding handlers. Supports manual routing and auto routing modes, along with HTTP method restrictions, route groups, and other advanced features.

Router Execution Flow

┌─────────────────────────────────────────────────────────────┐
│                      Request Arrives                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  1. Static File Check                                        │
│     └─> If matches file in WebRoot, return static file     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  2. Execute Pre-Middleware (RouteBefore)                     │
│     └─> Can intercept requests, verify permissions, etc.   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  3. Route Matching                                          │
│     ├─> a) Check manually registered routes                  │
│     ├─> b) Check auto routes (if enabled)                   │
│     └─> c) 404 Not Found                                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  4. Execute Controller Method                                │
│     └─> Call matched Controller@Action                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  5. Execute Post-Processing (RouteAfter)                    │
│     └─> Can add response headers, log responses, etc.       │
└─────────────────────────────────────────────────────────────┘

Manual Routing

Basic Routes

' Register controllers
Call Server.Router.Reg("User", New cUserController)
Call Server.Router.Reg("Api", New cApiController)

' Add routes
Call Server.Router.Add("/", "User@Index")           ' Accessible by GET/POST
Call Server.Router.Add("/list", "User@List", OnlyGet)  ' GET only
Call Server.Router.Add("/create", "User@Create", OnlyPost)  ' POST only

HTTP Method Restriction

' Any method (default)
Call Server.Router.Add("/any", "Home@Any", Any_)

' GET only
Call Server.Router.Add("/get", "Home@Get", OnlyGet)

' POST only
Call Server.Router.Add("/post", "Home@Post", OnlyPost)

' PUT only
Call Server.Router.Add("/put", "Home@Put", OnlyPut)

' DELETE only
Call Server.Router.Add("/delete", "Home@Delete", OnlyDelete)

RESTful API Route Examples

' User resource RESTful API
Call Server.Router.Reg("User", New cUserController)

' GET    /users       -> List
Call Server.Router.Add("/users", "User@Index", OnlyGet)

' GET    /users/:id   -> Detail
Call Server.Router.Add("/users/detail", "User@Detail", OnlyGet)

' POST   /users       -> Create
Call Server.Router.Add("/users", "User@Create", OnlyPost)

' PUT    /users/:id   -> Update
Call Server.Router.Add("/users/update", "User@Update", OnlyPut)

' DELETE /users/:id   -> Delete
Call Server.Router.Add("/users/delete", "User@Delete", OnlyDelete)

Controller Writing Standards

' cUserController.cls
Option Explicit

' GET /users
Public Sub Index(ctx As cHttpServerContext)
    Dim users As New Scripting.Dictionary
    users("items") = Array("John", "Jane")
    users("total") = 2
    ctx.Response.Json users, 0, "Success"
End Sub

' GET /users/detail?id=123
Public Sub Detail(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request.QueryString("id")
    
    Dim user As New Scripting.Dictionary
    user("id") = id
    user("name") = "John"
    ctx.Response.Json user
End Sub

' POST /users
Public Sub Create(ctx As cHttpServerContext)
    ' Get form data
    Dim name As String, email As String
    name = ctx.Request.Form("name")
    email = ctx.Request.Form("email")
    
    ' Or get JSON data
    ' name = ctx.Request.Json.GetItem("name")
    
    ' Business logic...
    
    ctx.Response.Json Nothing, 0, "Created successfully"
End Sub

' PUT /users/update
Public Sub Update(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request("id")  ' Auto-get from Query/Form/Json
    
    ctx.Response.Json Nothing, 0, "Updated successfully"
End Sub

' DELETE /users/delete
Public Sub Delete(ctx As cHttpServerContext)
    Dim id As String
    id = ctx.Request.QueryString("id")
    
    ctx.Response.Json Nothing, 0, "Deleted successfully"
End Sub

Auto Routing

When auto routing is enabled, the framework automatically parses controller and method based on URL path.

' Enable auto routing
Server.Router.AutoRoute = True

URL Parsing Rules

Format: /ControllerName/ActionName?param1=value1&param2=value2

Examples:
  /User/List         -> List method of User controller
  /User/Detail?id=1  -> Detail method of User controller
  /Home/Index        -> Index method of Home controller

Auto Routing Usage Example

' Only need to register controllers, no manual routes required
Call Server.Router.Reg("User", New cUserController)
Call Server.Router.Reg("Product", New cProductController)

' Enable auto routing
Server.Router.AutoRoute = True

' The following URLs will route automatically:
' GET  /User/List    -> Call cUserController.List
' GET  /User/Detail  -> Call cUserController.Detail
' POST /Product/Add  -> Call cProductController.Add

Manual vs Auto Routing

Feature	Manual Routing	Auto Routing
Performance	Faster (direct dictionary lookup)	Slightly slower (needs URL parsing)
Flexibility	Can customize URL paths	Follows fixed format
Security	Only exposes registered routes	Exposes all public methods
Use Case	API services, production	Rapid development, admin panels

Route and Middleware Integration

' Pre-middleware: Login verification
Public Sub AuthMiddleware(ctx As cHttpServerContext)
    ' Exclude login endpoint
    If ctx.Request.PathInfo = "/login" Then Exit Sub
    
    ' Check session
    If ctx.Session("user_id") = "" Then
        ctx.Response.State401 "Please login first"
        ctx.fIsAbort = True  ' Terminate subsequent processing
    End If
End Sub

' Register middleware
Call Server.RouteBefore.Add("auth", New cAuthMiddleware)

' Route registration (will be intercepted by auth)
Call Server.Router.Add("/api/data", "Api@Data", OnlyGet)

Route Performance Optimization Tips

1. Use manual routing in production: Better performance, higher security
2. Static files first: Files in WebRoot are returned first, not entering routing
3. Use HTTP method restrictions wisely: Can match route dictionaries faster
4. Controller caching: Controller objects are registered once and reused

---

Last Updated: 2026-05-17