Skip to content

HTTP Server

The HTTP server functionality provides comprehensive server-side HTTP capabilities, allowing you to build web servers, APIs, and web applications in Harneet. This wraps Go's powerful net/http server with Harneet's simple and consistent API.

Quick Start

Quick Start Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import http
import fmt

// Create a simple HTTP server
var server = http.NewServer(":8080")[0]
var mux = http.NewMux()[0]

// Define a simple handler
function helloHandler(request map, response map) {
    http.WriteResponse(response, 200, "text/plain", "Hello, World!")
}

// Register the handler
http.HandleFunc(mux, "/hello", helloHandler)

// Set the mux as the server handler
http.SetHandler(server, mux)

// Start the server
fmt.Println("Server starting on :8080")
http.ListenAndServe(server)

Server Creation

http.NewServer(addr)

Creates a new HTTP server instance.

Syntax:

NewServer Syntax
1
http.NewServer(addr) (server, error)

Parameters: - addr (string) - Server address (e.g., ":8080", "localhost:3000")

Returns: - server (map) - Server object - error - None on success, error on failure

Examples:

Basic Server Creation:

Basic Server Creation
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import http
import fmt

// Create server on port 8080
var result = http.NewServer(":8080")
var server = result[0]
var err = result[1]

if err != None {
    fmt.Printf("Failed to create server: %s\n", err)
} else {
    fmt.Println("✅ Server created successfully")
    fmt.Printf("Server address: %s\n", server["addr"])
    fmt.Printf("Read timeout: %d seconds\n", server["readTimeout"])
    fmt.Printf("Write timeout: %d seconds\n", server["writeTimeout"])
}

Server with Custom Configuration:

Server with Custom Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import http
import fmt

// Create and configure server
function createConfiguredServer(port string) {
    var server = http.NewServer(":" + port)[0]

    // Configure timeouts (if supported)
    server = http.SetServerTimeout(server, "read", 60)[0]
    server = http.SetServerTimeout(server, "write", 60)[0]
    server = http.SetServerTimeout(server, "idle", 300)[0]

    return server
}

// Usage
var server = createConfiguredServer("8080")
fmt.Printf("Configured server: %s\n", server["addr"])

Server Object Structure

Server objects have the following structure:

Server Object Structure
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "addr": ":8080",              // Server address
    "readTimeout": 30,            // Read timeout in seconds
    "writeTimeout": 30,           // Write timeout in seconds
    "idleTimeout": 120,           // Idle timeout in seconds
    "handler": muxObject,         // Request handler (mux or function)
    "tls": {                      // TLS configuration (if enabled)
        "certFile": "cert.pem",
        "keyFile": "key.pem"
    }
}

Server Lifecycle

http.ListenAndServe(server)

Starts the HTTP server and begins listening for requests.

Syntax:

ListenAndServe Syntax
1
http.ListenAndServe(server) (error)

Parameters: - server (map) - Server object from NewServer

Returns: - error - None on success, error on failure

Examples:

Basic Server Start:

Basic Server Start
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import http
import fmt

function startServer() {
    var server = http.NewServer(":8080")[0]
    var mux = http.NewMux()[0]

    // Add some routes
    http.HandleFunc(mux, "/", homeHandler)
    http.HandleFunc(mux, "/api/health", healthHandler)

    // Set handler
    http.SetHandler(server, mux)

    fmt.Println("🚀 Starting server on :8080")
    fmt.Println("Visit: http://localhost:8080")

    // This blocks until server stops
    var err = http.ListenAndServe(server)[1]
    if err != None {
        fmt.Printf("❌ Server error: %s\n", err)
    }
}

// Handler functions
function homeHandler(request map, response map) {
    var html = "<h1>Welcome to Harneet Server!</h1><p>Server is running.</p>"
    http.WriteResponse(response, 200, "text/html", html)
}

function healthHandler(request map, response map) {
    var healthData = {"status": "healthy", "timestamp": "2024-01-01T12:00:00Z"}
    var jsonData, _ = json.Marshal(healthData)
    http.WriteResponse(response, 200, "application/json", jsonData)
}

// Start the server
startServer()

http.ListenAndServeTLS(server, certFile, keyFile)

Starts an HTTPS server with TLS encryption.

Syntax:

ListenAndServeTLS Syntax
1
http.ListenAndServeTLS(server, certFile, keyFile) (error)

Parameters: - server (map) - Server object - certFile (string) - Path to certificate file - keyFile (string) - Path to private key file

Examples:

HTTPS Server:

HTTPS Server
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import http
import fmt

function startHTTPSServer() {
    var server = http.NewServer(":8443")[0]
    var mux = http.NewMux()[0]

    // Add secure routes
    http.HandleFunc(mux, "/secure", secureHandler)
    http.SetHandler(server, mux)

    fmt.Println("🔒 Starting HTTPS server on :8443")

    var err = http.ListenAndServeTLS(server, "cert.pem", "key.pem")[1]
    if err != None {
        fmt.Printf("❌ HTTPS Server error: %s\n", err)
    }
}

function secureHandler(request map, response map) {
    var data = {"message": "This is a secure endpoint", "encrypted": true}
    var jsonData, _ = json.Marshal(data)
    http.WriteResponse(response, 200, "application/json", jsonData)
}

http.Shutdown(server)

Gracefully shuts down the server.

Syntax:

Shutdown Syntax
1
http.Shutdown(server) (error)

Examples:

Graceful Shutdown:

Graceful Shutdown Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import http
import fmt

var globalServer = None

function startServerWithShutdown() {
    globalServer = http.NewServer(":8080")[0]
    var mux = http.NewMux()[0]

    http.HandleFunc(mux, "/", homeHandler)
    http.HandleFunc(mux, "/shutdown", shutdownHandler)
    http.SetHandler(globalServer, mux)

    fmt.Println("Server starting with shutdown endpoint")
    http.ListenAndServe(globalServer)
}

function shutdownHandler(request map, response map) {
    http.WriteResponse(response, 200, "text/plain", "Server shutting down...")

    // Shutdown in background (simplified)
    fmt.Println("Initiating graceful shutdown...")
    var err = http.Shutdown(globalServer)[1]
    if err != None {
        fmt.Printf("Shutdown error: %s\n", err)
    }
}

Handler Management

http.SetHandler(server, handler)

Sets the main handler for the server.

Syntax:

SetHandler Syntax
1
http.SetHandler(server, handler) (error)

Parameters: - server (map) - Server object - handler (map) - Handler object (usually a mux)

Examples:

Setting Server Handler:

Setting Server Handler
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import http

function setupServer() {
    var server = http.NewServer(":8080")[0]
    var mux = http.NewMux()[0]

    // Configure routes
    http.HandleFunc(mux, "/api/users", usersHandler)
    http.HandleFunc(mux, "/api/posts", postsHandler)

    // Set the mux as the server's handler
    var err = http.SetHandler(server, mux)[1]
    if err != None {
        fmt.Printf("Failed to set handler: %s\n", err)
        return None
    }

    return server
}

Response Writing

http.WriteResponse(response, status, contentType, body)

Writes an HTTP response.

Syntax:

WriteResponse Syntax
1
http.WriteResponse(response, status, contentType, body) (error)

Parameters: - response (map) - Response writer object - status (int) - HTTP status code - contentType (string) - Content-Type header - body (string) - Response body

Examples:

Different Response Types:

Different Response Types
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
import http
import json
import fmt

// JSON response
function jsonResponse(response map, data map) {
    var jsonData, err = json.Marshal(data)
    if err != None {
        http.WriteResponse(response, 500, "text/plain", "JSON encoding error")
        return
    }
    http.WriteResponse(response, 200, "application/json", jsonData)
}

// HTML response
function htmlResponse(response map, html string) {
    http.WriteResponse(response, 200, "text/html", html)
}

// Error response
function errorResponse(response map, status int, message string) {
    var errorData = {"error": message, "status": status}
    var jsonData, _ = json.Marshal(errorData)
    http.WriteResponse(response, status, "application/json", jsonData)
}

// File response
function fileResponse(response map, filename string, content string) {
    var contentType = "application/octet-stream"

    // Set content type based on file extension
    match filename {
        f if strings.HasSuffix(f, ".html") => contentType = "text/html",
        f if strings.HasSuffix(f, ".css") => contentType = "text/css",
        f if strings.HasSuffix(f, ".js") => contentType = "application/javascript",
        f if strings.HasSuffix(f, ".json") => contentType = "application/json",
        _ => contentType = "application/octet-stream"
    }

    http.SetHeader(response, "Content-Disposition", "attachment; filename=" + filename)
    http.WriteResponse(response, 200, contentType, content)
}

// Usage in handlers
function apiHandler(request map, response map) {
    var data = {"message": "Hello from API", "timestamp": "2024-01-01T12:00:00Z"}
    jsonResponse(response, data)
}

function pageHandler(request map, response map) {
    var html = "<html><body><h1>Welcome!</h1></body></html>"
    htmlResponse(response, html)
}

function notFoundHandler(request map, response map) {
    errorResponse(response, 404, "Resource not found")
}

http.SetResponseHeader(response, key, value)

Sets a response header.

Syntax:

SetResponseHeader Syntax
1
http.SetResponseHeader(response, key, value) (error)

Examples:

Custom Response Headers:

Custom Response Headers
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import http

function corsHandler(request map, response map) {
    // Set CORS headers
    http.SetResponseHeader(response, "Access-Control-Allow-Origin", "*")
    http.SetResponseHeader(response, "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
    http.SetResponseHeader(response, "Access-Control-Allow-Headers", "Content-Type, Authorization")

    // Set caching headers
    http.SetResponseHeader(response, "Cache-Control", "no-cache, no-store, must-revalidate")
    http.SetResponseHeader(response, "Pragma", "no-cache")
    http.SetResponseHeader(response, "Expires", "0")

    // Set security headers
    http.SetResponseHeader(response, "X-Content-Type-Options", "nosniff")
    http.SetResponseHeader(response, "X-Frame-Options", "DENY")
    http.SetResponseHeader(response, "X-XSS-Protection", "1; mode=block")

    var data = {"message": "CORS enabled endpoint"}
    var jsonData, _ = json.Marshal(data)
    http.WriteResponse(response, 200, "application/json", jsonData)
}

Request Processing

Request Object Structure

Request objects passed to handlers have this structure:

Request Object Structure
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "method": "GET",              // HTTP method
    "url": "/api/users",          // Request URL path
    "path": "/api/users",         // URL path
    "query": {                    // Query parameters
        "page": "1",
        "limit": "10"
    },
    "headers": {                  // Request headers
        "Content-Type": "application/json",
        "Authorization": "Bearer token123",
        "User-Agent": "Mozilla/5.0..."
    },
    "body": "request body...",    // Request body
    "cookies": {                  // Request cookies
        "session": "abc123",
        "theme": "dark"
    },
    "remoteAddr": "127.0.0.1:12345",  // Client address
    "userAgent": "Mozilla/5.0...",     // User agent string
    "referer": "https://example.com"   // Referer header
}

Accessing Request Data

Accessing Request Data
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import http
import json
import fmt

function requestInfoHandler(request map, response map) {
    var method = request["method"]
    var path = request["path"]
    var query = request["query"]
    var headers = request["headers"]
    var body = request["body"]

    fmt.Printf("Method: %s\n", method)
    fmt.Printf("Path: %s\n", path)
    fmt.Printf("User-Agent: %s\n", headers["User-Agent"])

    // Process query parameters
    var page = query["page"]
    var limit = query["limit"]

    if page != None {
        fmt.Printf("Page: %s\n", page)
    }

    // Process JSON body
    if method == "POST" and headers["Content-Type"] == "application/json" {
        var data, parseErr = json.Unmarshal(body)
        if parseErr == None {
            fmt.Printf("JSON data received: %s\n", data)
        }
    }

    var responseData = {
        "received": {
            "method": method,
            "path": path,
            "queryParams": query,
            "hasBody": body != "",
            "contentType": headers["Content-Type"]
        }
    }

    var jsonResponse, _ = json.Marshal(responseData)
    http.WriteResponse(response, 200, "application/json", jsonResponse)
}

Server Configuration

Timeout Configuration

Timeout Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import http

function createProductionServer(port string) {
    var server = http.NewServer(":" + port)[0]

    // Configure timeouts for production
    server = http.SetServerConfig(server, {
        "readTimeout": 30,      // 30 seconds
        "writeTimeout": 30,     // 30 seconds  
        "idleTimeout": 300,     // 5 minutes
        "maxHeaderBytes": 1048576  // 1MB
    })[0]

    return server
}

TLS Configuration

TLS Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import http

function createSecureServer(port string) {
    var server = http.NewServer(":" + port)[0]

    // Configure TLS
    server = http.SetTLSConfig(server, {
        "certFile": "/path/to/cert.pem",
        "keyFile": "/path/to/key.pem",
        "minVersion": "TLS1.2",
        "cipherSuites": ["TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"]
    })[0]

    return server
}

Request IDs

Every request automatically receives a unique requestID that can be used for logging, tracing, and correlation.

Using Request IDs
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import http
import fmt

function tracedHandler(request map, response map) {
    // Access the auto-generated request ID
    var requestID = request["requestID"]

    fmt.Printf("[%s] Processing request: %s %s\n", requestID, request["method"], request["path"])

    // Include request ID in response for client correlation
    response.setHeader("X-Request-ID", requestID)

    var data = {
        "message": "Request processed",
        "requestID": requestID
    }
    response.json(data)
}

Metrics Hooks

Use http.WithMetrics to attach a metrics handler that receives detailed information about each request.

Syntax:

WithMetrics Syntax
1
http.WithMetrics(mux, metricsHandler) (mux, error)

Parameters: - mux (map) - Multiplexer object created by http.NewMux() - metricsHandler (function) - Metrics handler function with signature function(event map)

Event Object Structure:

Metrics Event Structure
1
2
3
4
5
6
7
8
9
{
    "type": "request",           // Event type
    "method": "GET",             // HTTP method
    "path": "/api/users",        // Request path
    "status": 200,               // HTTP status code
    "durationMs": 45,            // Request duration in milliseconds
    "requestID": "abc123...",    // Unique request ID
    "error": None                // Error message if any, None otherwise
}

Example:

Metrics Handler Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import http
import fmt

function metricsHandler(event map) {
    fmt.Printf("METRICS: %s %s -> %d (%dms) [%s]\n",
        event["method"],
        event["path"],
        event["status"],
        event["durationMs"],
        event["requestID"]
    )

    // In production, you might send this to a metrics service
    // e.g., Prometheus, DataDog, etc.
    if event["error"] != None {
        fmt.Printf("ERROR: %s\n", event["error"])
    }
}

function setupMetricsServer() {
    var server = http.NewServer(":8080")[0]
    var mux = http.NewMux()[0]

    // Attach metrics handler
    var metricsMux = http.WithMetrics(mux, metricsHandler)[0]

    http.HandleFunc(metricsMux, "/", homeHandler)
    http.HandleFunc(metricsMux, "/api/users", usersHandler)

    http.SetHandler(server, metricsMux)
    http.ListenAndServe(server)
}

Context Cancellation

Use http.IsCancelled to check if a request has been cancelled by the client.

Syntax:

IsCancelled Syntax
1
http.IsCancelled(request) (cancelled, error)

Parameters: - request (map) - Request object from the handler

Returns: - cancelled (bool) - True if the request context has been cancelled - error - None on success, error on failure

Example:

Context Cancellation Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import http
import fmt

function longRunningHandler(request map, response map) {
    // Simulate a long-running operation with cancellation checks
    for i in range(100) {
        // Check if client disconnected
        var cancelled, _ = http.IsCancelled(request)
        if cancelled {
            fmt.Printf("[%s] Request cancelled by client\n", request["requestID"])
            return
        }

        // Do some work...
        processChunk(i)
    }

    response.json({"status": "completed"})
}

Error Handling

Server Error Handling

Use http.WithErrorHandling to attach a centralized error handler to a mux.

Syntax:

WithErrorHandling Syntax
1
http.WithErrorHandling(mux, errorHandler) (mux, error)

Parameters: - mux (map) - Multiplexer object created by http.NewMux() - errorHandler (function) - Error handler function with signature function(error string, request map, response map)

Example:

Server Error Handling
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import http
import fmt

function errorHandlingServer() {
    var server = http.NewServer(":8080")[0]
    var mux = http.NewMux()[0]

    // Add error handling middleware
    var errorMux = http.WithErrorHandling(mux, errorHandler)[0]

    http.HandleFunc(errorMux, "/", homeHandler)
    http.HandleFunc(errorMux, "/error", triggerErrorHandler)

    http.SetHandler(server, errorMux)
    http.ListenAndServe(server)
}

function errorHandler(error string, request map, response map) {
    fmt.Printf("Server error [%s]: %s\n", request["requestID"], error)

    var errorResponse = {
        "error": "Internal server error",
        "message": "Something went wrong",
        "requestID": request["requestID"],
        "timestamp": "2024-01-01T12:00:00Z"
    }

    var jsonData, _ = json.Marshal(errorResponse)
    http.WriteResponse(response, 500, "application/json", jsonData)
}

function triggerErrorHandler(request map, response map) {
    // Simulate an error
    panic("Something went wrong!")
}

Combined Production Setup

Here's a complete example combining all production features:

Production Server Setup
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
import http
import fmt
import json

// Metrics handler for observability
function metricsHandler(event map) {
    fmt.Printf("METRIC: method=%s path=%s status=%d duration=%dms request_id=%s\n",
        event["method"],
        event["path"],
        event["status"],
        event["durationMs"],
        event["requestID"]
    )
}

// Error handler for centralized error management
function errorHandler(error string, request map, response map) {
    fmt.Printf("ERROR: request_id=%s error=%s\n", request["requestID"], error)

    var errorData = {
        "error": "Internal server error",
        "requestID": request["requestID"]
    }
    var jsonData, _ = json.Marshal(errorData)
    http.WriteResponse(response, 500, "application/json", jsonData)
}

// API handler with request ID logging
function apiHandler(request map, response map) {
    fmt.Printf("[%s] Handling API request\n", request["requestID"])

    response.setHeader("X-Request-ID", request["requestID"])
    response.json({"status": "ok", "requestID": request["requestID"]})
}

function startProductionServer() {
    var server, serverErr = http.NewServer(":8080")
    if serverErr != None {
        fmt.Printf("Failed to create server: %s\n", serverErr)
        return
    }

    var mux, muxErr = http.NewMux()
    if muxErr != None {
        fmt.Printf("Failed to create mux: %s\n", muxErr)
        return
    }

    // Chain production features
    var errMux, err1 = http.WithErrorHandling(mux, errorHandler)
    if err1 != None {
        fmt.Printf("Failed to attach error handler: %s\n", err1)
        return
    }
    var metricsMux, err2 = http.WithMetrics(errMux, metricsHandler)
    if err2 != None {
        fmt.Printf("Failed to attach metrics handler: %s\n", err2)
        return
    }

    // Register routes
    var _, routeErr = http.HandleFunc(metricsMux, "/api/health", apiHandler)
    if routeErr != None {
        fmt.Printf("Failed to register route: %s\n", routeErr)
        return
    }

    var setErr = http.SetHandler(server, metricsMux)[1]
    if setErr != None {
        fmt.Printf("Failed to set handler: %s\n", setErr)
        return
    }

    fmt.Println("Production server starting on :8080")
    http.ListenAndServe(server)
}

startProductionServer()

CORS Configuration with http.WithCORS

Use http.WithCORS to attach Cross-Origin Resource Sharing (CORS) settings to a mux. The CORS configuration is applied to all routes registered on that mux.

CORS Configuration
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
import http
import fmt

function corsExampleHandler(request any, response any) {
    response.setStatus(200)
    response.write("CORS is configured correctly")
}

function startServerWithCORS() {
    var server, serverErr = http.NewServer(":8080")
    if serverErr != None {
        fmt.Printf("Server error: %s\n", serverErr)
        return
    }

    var mux, muxErr = http.NewMux()
    if muxErr != None {
        fmt.Printf("Mux error: %s\n", muxErr)
        return
    }

    // Attach default CORS configuration (suitable for development)
    var corsMux, corsErr = http.WithCORS(mux)
    if corsErr != None {
        fmt.Printf("CORS error: %s\n", corsErr)
        return
    }

    // Optionally override with a stricter configuration
    var config = {
        "allowedOrigins": ["https://example.com"],
        "allowedMethods": ["GET", "POST"],
        "allowedHeaders": ["Content-Type", "Authorization"],
        "allowCredentials": true,
        "maxAge": 600,
    }
    var strictMux, strictErr = http.WithCORS(corsMux, config)
    if strictErr != None {
        fmt.Printf("Strict CORS error: %s\n", strictErr)
        return
    }

    var _, routeErr = http.HandleFunc(strictMux, "/cors-demo", corsExampleHandler)
    if routeErr != None {
        fmt.Printf("Route error: %s\n", routeErr)
        return
    }

    var setErr = http.SetHandler(server, strictMux)[1]
    if setErr != None {
        fmt.Printf("SetHandler error: %s\n", setErr)
        return
    }

    fmt.Println("Server with CORS starting on :8080")
    http.ListenAndServe(server)
}

Authentication & Rate Limiting Helpers

The HTTP server exposes mux-level helpers for authentication and rate limiting:

  • http.WithAuth(mux, authHandler) (mux, error)
  • http.WithRateLimit(mux, rateLimitHandler) (mux, error)
  • http.WithAPIKeyAuth(mux, headerName, requiredValue) (mux, error)
  • http.WithSimpleIPRateLimit(mux, requestsPerMinute) (mux, error)

These hooks are evaluated for routes registered with http.HandleRoute before your main handler.

Mux-Level Auth and Rate Limiting
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
import http
import fmt

// Custom auth handler used with http.WithAuth
function authHandler(request any, response any) {
    var headers = request["headers"]
    var token = headers["X-Auth-Token"]
    if token == None or token == "" {
        response.setStatus(401)
        response.write("missing auth token")
        return
    }
    // In a real app, validate the token here
    response.setHeader("X-Auth-Checked", "1")
}

// Simple handler for a protected route
function protectedHandler(request any, response any) {
    response.json({"status": "ok", "path": request["path"]})
}

function startSecureServer() {
    var server, serverErr = http.NewServer(":8080")
    if serverErr != None {
        fmt.Printf("Server error: %s\n", serverErr)
        return
    }

    var mux, muxErr = http.NewMux()
    if muxErr != None {
        fmt.Printf("Mux error: %s\n", muxErr)
        return
    }

    // Attach built-in helpers
    var mux1, err1 = http.WithAPIKeyAuth(mux, "X-API-Key", "secret-123")
    if err1 != None {
        fmt.Printf("API key auth error: %s\n", err1)
        return
    }

    var mux2, err2 = http.WithSimpleIPRateLimit(mux1, 60)  // 60 requests/min per IP
    if err2 != None {
        fmt.Printf("Rate limit error: %s\n", err2)
        return
    }

    // Optionally layer a custom auth policy as well
    var mux3, err3 = http.WithAuth(mux2, authHandler)
    if err3 != None {
        fmt.Printf("Custom auth error: %s\n", err3)
        return
    }

    // Register a method-aware route using HandleRoute
    var _, routeErr = http.HandleRoute(mux3, "GET", "/secure/{id}", protectedHandler)
    if routeErr != None {
        fmt.Printf("Route error: %s\n", routeErr)
        return
    }

    var setErr = http.SetHandler(server, mux3)[1]
    if setErr != None {
        fmt.Printf("SetHandler error: %s\n", setErr)
        return
    }

    fmt.Println("Secure server starting on :8080")
    fmt.Println("Try: curl -H 'X-API-Key: secret-123' http://localhost:8080/secure/42")
    http.ListenAndServe(server)
}

Best Practices

1. Always Set Content-Type

Always Set Content-Type
1
2
3
4
5
// Good
http.WriteResponse(response, 200, "application/json", jsonData)

// Bad
http.WriteResponse(response, 200, "", jsonData)

2. Handle Errors Gracefully

Handle Errors Gracefully
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
function safeHandler(request map, response map) {
    var data, err = processRequest(request)
    if err != None {
        http.WriteResponse(response, 500, "application/json", "{\"error\": \"Processing failed\"}")
        return
    }

    var jsonData, jsonErr = json.Marshal(data)
    if jsonErr != None {
        http.WriteResponse(response, 500, "application/json", "{\"error\": \"JSON encoding failed\"}")
        return
    }

    http.WriteResponse(response, 200, "application/json", jsonData)
}

3. Use Appropriate Status Codes

Appropriate Status Codes
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Success responses
http.WriteResponse(response, 200, contentType, data)  // OK
http.WriteResponse(response, 201, contentType, data)  // Created
http.WriteResponse(response, 204, "", "")             // No Content

// Client error responses
http.WriteResponse(response, 400, contentType, error) // Bad Request
http.WriteResponse(response, 401, contentType, error) // Unauthorized
http.WriteResponse(response, 404, contentType, error) // Not Found

// Server error responses
http.WriteResponse(response, 500, contentType, error) // Internal Server Error

4. Set Security Headers

Set Security Headers
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
function secureHandler(request map, response map) {
    // Security headers
    http.SetResponseHeader(response, "X-Content-Type-Options", "nosniff")
    http.SetResponseHeader(response, "X-Frame-Options", "DENY")
    http.SetResponseHeader(response, "X-XSS-Protection", "1; mode=block")
    http.SetResponseHeader(response, "Strict-Transport-Security", "max-age=31536000")

    // Your handler logic here
    http.WriteResponse(response, 200, "text/html", "<h1>Secure Page</h1>")
}

5. Log Requests

Log Requests
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import log

function loggedHandler(request map, response map) {
    var method = request["method"]
    var path = request["path"]
    var userAgent = request["headers"]["User-Agent"]

    log.Printf("Request: %s %s from %s", method, path, userAgent)

    // Your handler logic here
    http.WriteResponse(response, 200, "application/json", "{\"status\": \"ok\"}")
}

Next Steps