Static File Serving

Overview

HttpServer has built-in static file serving. When WebRoot is configured, it automatically handles static resource requests without writing controllers.

Quick Configuration

Private Sub Form_Load()
    Set Server = New cHttpServer
    
    ' Configure static file root directory
    Server.Start 8080, "C:\WebRoot"
    
    Debug.Print "Static file service: http://localhost:8080/"
End Sub

Directory Structure Example

C:\WebRoot\
├── index.html          # Home page
├── favicon.ico         # Site icon
├── css\
│   ├── style.css
│   └── theme.css
├── js\
│   ├── app.js
│   └── utils.js
├── images\
│   ├── logo.png
│   └── banner.jpg
└── upload\
    └── avatar.png

Request Mapping

Request URL	Maps to File
/	C:\WebRoot\index.html
/css/style.css	C:\WebRoot\css\style.css
/js/app.js	C:\WebRoot\js\app.js
/images/logo.png	C:\WebRoot\images\logo.png

Supported MIME Types

' System automatically identifies Content-Type for the following file types

' Text types
text/html          -> .html, .htm
text/css           -> .css
text/javascript    -> .js
text/plain         -> .txt

' Image types
image/png          -> .png
image/jpeg         -> .jpg, .jpeg
gif/image          -> .gif
image/svg+xml      -> .svg
image/x-icon       -> .ico

' Application types
application/json   -> .json
application/xml    -> .xml
application/pdf    -> .pdf

' Font types
font/woff2         -> .woff2
font/woff          -> .woff

Priority Explanation

Static files take priority over route matching:

Request /index.html
   │
   ├──> Check if C:\WebRoot\index.html exists
   │     ├─> Exists -> Return static file
   │     └─> Does not exist -> Go to route matching
   │
   └──> Match route /index.html

Mixed Mode (Static Files + API)

Private Sub Form_Load()
    Set Server = New cHttpServer
    
    ' ========== Configure Routes ==========
    ' API controllers
    Call Server.Router.Reg("Api", New cApiController)
    Call Server.Router.Add("/api/users", "Api@Users", OnlyGet)
    Call Server.Router.Add("/api/data", "Api@Data", OnlyGet)
    
    ' Business controllers
    Call Server.Router.Reg("User", New cUserController)
    Call Server.Router.Add("/user/login", "User@Login", OnlyPost)
    
    ' ========== Start Service ==========
    ' WebRoot for static files, API requests go to routing
    Server.Start 8080, "C:\WebRoot"
    
    Debug.Print "Service started successfully"
    Debug.Print "  Frontend: http://localhost:8080/"
    Debug.Print "  API:      http://localhost:8080/api/users"
End Sub

Single Page Application (SPA) Support

For React/Vue/Angular SPAs, configure all routes to return index.html:

' cSpaController.cls
Public Sub Index(ctx As cHttpServerContext)
    ' Return index.html for frontend routing
    ctx.Response.File "/index.html"
End Sub

' Register routes
Private Sub Form_Load()
    Set Server = New cHttpServer
    
    ' API routes
    Call Server.Router.Reg("Api", New cApiController)
    Call Server.Router.Add("/api/*", "Api@Handle")
    
    ' SPA routes: All non-API requests return index.html
    Call Server.Router.Reg("Spa", New cSpaController)
    Call Server.Router.Add("/*", "Spa@Index")
    
    Server.Start 8080, "C:\WebRoot"
End Sub

File Upload Directory

' Upload files to static directory
Public Sub Upload(ctx As cHttpServerContext)
    ' Save uploaded file
    Dim savePath As String
    savePath = ctx.Server.WebRoot & "\upload\" & filename
    
    Call SaveUploadFile(ctx.Request.RawBodyBin, savePath)
    
    ' Return accessible URL
    Dim result As New Scripting.Dictionary
    result("url") = "/upload/" & filename
    ctx.Response.Json result
End Sub

Cache Control

' cCacheMiddleware.cls
Public Sub Entry(ctx As cHttpServerContext)
    ' Add cache headers for static files
    If IsStaticFile(ctx.Request.PathInfo) Then
        ' Cache for 1 hour
        ctx.Response.Header("Cache-Control") = "public, max-age=3600"
        ctx.Response.Header("Expires") = FormatHttpDate(DateAdd("h", 1, Now))
    End If
End Sub

Private Function IsStaticFile(path As String) As Boolean
    Dim ext As String
    ext = LCase(Mid(path, InStrRev(path, ".")))
    
    IsStaticFile = (ext = ".css" Or ext = ".js" Or ext = ".png" Or _
                    ext = ".jpg" Or ext = ".gif" Or ext = ".ico")
End Function

---

Last Updated: 2026-05-17