SimpleWebServer

Declare the server as a process global, initialize it in AppStart, then call Start to begin listening. Define your handler subroutines in the same module.

Main.bas

Sub Process_Globals
    Private WebServer As SimpleWebServer
    Private StaticFilesFolder As String
End Sub

Sub AppStart(Args() As String)
    StaticFilesFolder = File.Combine(File.DirApp, "www")
    WebServer.Initialize(8080, StaticFilesFolder, "WebServer")
    WebServer.Start
End Sub

Sub WebServer_Get(Path As String, QueryString As String) As String
    Select Case Path
        Case "", "/", "/index"
            Return page_index.Handle(QueryString)
        Case "/healthcheck"
            Return "{""status"":""ok""}"
    End Select
    Return Null
End Sub

Sub WebServer_Post(Path As String, Body As String) As String
    Select Case Path
        Case "/config"
            Return page_config.Post(Body)
    End Select
    Return Null
End Sub

Creates an HTTP server on the specified port. Static files are served from StaticFilesFolder. Unhandled requests are routed to the B4J subroutines SubName_Get and SubName_Post in the calling module. The server does not begin listening until you call Start.

• HttpPort — Port number to listen on (e.g. 8080).
• StaticFilesFolder — Absolute path to the folder containing static files to serve.
• SubName — Prefix for the handler subroutines in the calling module. Case-insensitive.

Example

WebServer.Initialize(8080, File.Combine(File.DirApp, "www"), "WebServer")
WebServer.Start

Creates both an HTTPS server and an HTTP server. The HTTP server issues a 301 redirect to the HTTPS port for every request, ensuring all traffic is encrypted. The HTTPS server uses a Java keystore (JKS) file for TLS configuration. Neither server begins listening until you call Start.

• HttpPort — Port that redirects all requests to HTTPS (e.g. 80).
• HttpsPort — Port the HTTPS server listens on (e.g. 443).
• StaticFilesFolder — Absolute path to the folder containing static files to serve.
• SubName — Prefix for the handler subroutines in the calling module.
• KeystoreFile — Absolute path to the JKS keystore file containing the TLS certificate.
• KeyStorePassword — Password for the keystore.

Example

WebServer.Initialize2(80, 443, File.Combine(File.DirApp, "www"),
    "WebServer", "/etc/myapp/keystore.jks", "keystorepassword")
WebServer.Start

Sets the size of the thread pool used to handle requests. Call this before Initialize or Initialize2, as the executor is configured during initialization.

• Count — Number of worker threads. The default of 0 means no thread pool is set, so requests are handled serially on the server's dispatch thread. A value greater than 0 creates a fixed thread pool of that size, allowing requests to be handled concurrently.

Example

WebServer.SetThreadCount(8)
WebServer.Initialize(8080, StaticFilesFolder, "WebServer")
WebServer.Start

Starts the server(s) listening for connections. Call this after Initialize or Initialize2 (and after SetThreadCount, if used). Until Start is called the server accepts no connections. When initialized with Initialize2, both the HTTP and HTTPS servers are started.

Returns True if the server started successfully, False if it was not initialized or an error occurred.

Example

If WebServer.Start = False Then
    Log("Server failed to start")
    ExitApplication
End If

Returns True if the server was initialized successfully (via Initialize or Initialize2), False otherwise. Useful for confirming initialization succeeded before calling Start, or guarding against double-initialization.

Example

If WebServer.IsInitialised = False Then
    Log("Server failed to initialize")
    ExitApplication
End If

Stops the server, waiting up to 2.5 seconds for in-flight requests to complete. If both HTTP and HTTPS servers are running (from Initialize2), both are stopped. Returns True on success, False if an error occurred or the server was not running.

Example

WebServer.Stop

Called when a GET request arrives for a path that has no matching static file on disk. Define this subroutine in the same module that calls Initialize, replacing SubName with the value you passed to the Initialize method.

• Path — The request path, e.g. /config. Leading slash included.
• QueryString — The raw query string, e.g. page=2&sort=asc. May be Null if no query string was sent.

Return a String to send as the response body. Return Null to send a 404 Not Found. The Content-Type header is set automatically from the content of your return value (see Auto-Detection).

Example

Sub WebServer_Get(Path As String, QueryString As String) As String
    Select Case Path
        Case "", "/", "/index"
            Return page_index.Handle(QueryString)
        Case "/healthcheck"
            Return "{""status"":""ok""}"
        Case "/config"
            Return page_config.Get(QueryString)
        Case "/restart"
            Return page_restart.Handle(QueryString)
    End Select
    Return Null
End Sub

Called for every POST request, regardless of whether a static file exists at that path. The request body is read as UTF-8 text and passed directly to your subroutine.

• Path — The request path, e.g. /config.
• Body — The raw request body as a UTF-8 string. Commonly JSON or URL-encoded form data.

Return a String to send as the response body, or Null for a 404 Not Found.

Example

Sub WebServer_Post(Path As String, Body As String) As String
    Select Case Path
        Case "/config"
            Return page_config.Post(Body)
        Case "/api/data"
            Return page_api.Post(Body)
    End Select
    Return Null
End Sub

The Content-Type response header is set automatically based on the first non-whitespace character of the string your handler returns. You do not need to set it yourself.

Examples

' Detected as application/json
Return "{""status"":""ok""}"

' Detected as text/html
Return "<!DOCTYPE html><html>...</html>"

' Detected as text/plain
Return "Server is running"

Return a string beginning with redirect: to send a 302 Found redirect to any path or URL. This works from both GET and POST handlers and is the standard way to navigate between pages in your app.

Syntax

Return "redirect:/target-path"

Example — conditional redirect based on config state

' page_index.bas
Sub Handle(QueryString As String) As String
    If Main.ConfigGood = False Then Return "redirect:/config"
    Return "redirect:/agent.html"
End Sub

Example — redirect after a successful POST

' page_config.bas
Sub Post(Body As String) As String
    SaveConfig(Body)
    Return "redirect:/config?saved=1"
End Sub

Any file present in StaticFilesFolder is served directly without calling your handler subs. The URL path maps directly to the file system: a request for /css/mvp.css serves StaticFilesFolder/css/mvp.css.

A request for / is automatically rewritten to /index.html if that file exists. Path traversal attempts (e.g. /../etc/passwd) are blocked and return a 403 Forbidden.

Recommended folder layout

www/
  index.html
  agent.html
  css/
    mvp.css
  js/
    chart.js
  favicon.ico

For anything beyond trivial responses, the recommended approach is to create a separate B4J code module for each page or endpoint. The main handler subs act purely as a router, delegating to each module.

Main.bas — router only

Sub WebServer_Get(Path As String, QueryString As String) As String
    Select Case Path
        Case "", "/", "/index"  :  Return page_index.Handle(QueryString)
        Case "/healthcheck"      :  Return page_healthcheck.Handle(QueryString)
        Case "/config"           :  Return page_config.Get(QueryString)
        Case "/restart"          :  Return page_restart.Handle(QueryString)
    End Select
    Return Null
End Sub

Sub WebServer_Post(Path As String, Body As String) As String
    Select Case Path
        Case "/config"  :  Return page_config.Post(Body)
    End Select
    Return Null
End Sub

page_index.bas — redirect based on app state

Sub Handle(QueryString As String) As String
    If Main.ConfigGood = False Then Return "redirect:/config"
    Return "redirect:/agent.html"
End Sub

page_healthcheck.bas — JSON response

Sub Handle(QueryString As String) As String
    Return "{""status"":""ok""}"
End Sub

When an HTML form submits with method="POST", the request body arrives as URL-encoded key=value pairs separated by &. Use the helper below to parse the body into a Map before processing it.

page_config.bas

Sub Post(Body As String) As String
    Dim Params As Map = ParseFormBody(Body)
    SaveConfig(Params)
    Return Get("") ' re-render the page
End Sub

Private Sub ParseFormBody(Body As String) As Map
    Dim Result As Map
    Result.Initialize
    If Body.Length = 0 Then Return Result
    Dim Parts() As String = Regex.Split("&", Body)
    For Each Part As String In Parts
        Dim Idx As Int = Part.IndexOf("=")
        If Idx > 0 Then
            Dim Key As String = URLDecode(Part.SubString2(0, Idx))
            Dim Value As String = URLDecode(Part.SubString(Idx + 1))
            Result.Put(Key, Value)
        End If
    Next
    Return Result
End Sub

Private Sub URLDecode(s As String) As String
    Try
        Dim jo As JavaObject
        jo.InitializeStatic("java.net.URLDecoder")
        Return jo.RunMethod("decode", Array(s, "UTF-8"))
    Catch
        Return s.Replace("+", " ")
    End Try
End Sub

The following MIME types are built in and applied automatically when serving static files.

The server returns the following HTTP status codes automatically.