Module: PudimServer

Main module to create and run the server.

PudimServer:Create(config?)

Creates the main server instance with host, port, and advanced feature options.

Inputs: config? (optional table: ServiceName, Address, Port, Middlewares, Https, Concurrency, HotReload).

Output: configured server instance.

local server = PudimServer:Create{ Port = 8080 }

server:Routes(path, handler)

Registers a route and delegates request handling to the provided handler.

Inputs: path (string), handler (function (req, res)).

Output: no meaningful return value (internal route registration).

server:Routes("/health", function(req, res)
  return res:response(200, "ok")
end)

server:EnableCors(config?)

Enables CORS and automatic OPTIONS preflight handling.

Inputs: config? (optional table with CORS policies).

Output: no meaningful return value (CORS enabled on server instance).

server:EnableCors{
  AllowOrigins = {"https://app.example.com"},
  AllowMethods = {"GET", "POST"}
}

server:UseHandler(entry)

Adds HTTP middleware to the pipeline before route execution.

Inputs: entry (table with name and Handler(req,res,next)).

Output: no meaningful return value (handler registered).

server:UseHandler{
  name = "auth",
  Handler = function(req, res, next)
    if not req.headers["authorization"] then
      return res:response(401, "Unauthorized")
    end
    return next()
  end
}

server:RemoveHandler(name)

Removes HTTP middleware by name.

Inputs: name (string).

Output: boolean indicating whether removal succeeded.

local removed = server:RemoveHandler("auth")
print("handler removed?", removed)

server:SetMiddlewares(middleware)

Adds socket middleware to operate on the raw TCP client before HTTP parsing.

Inputs: middleware (table with name and Handler(client)).

Output: no meaningful return value (middleware registered).

server:SetMiddlewares{
  name = "socket-log",
  Handler = function(client)
    print("new tcp connection")
    return client
  end
}

server:RemoveMiddlewares(name)

Removes socket middleware by name.

Inputs: name (string).

Output: boolean indicating whether removal succeeded.

local removed = server:RemoveMiddlewares("socket-log")
print("socket middleware removed?", removed)

server:EnableHotReload(config?)

Configures development hot reload by invalidating modules in package.loaded.

Inputs: config? (optional table with Enabled, Modules, Prefixes).

Output: no meaningful return value (hot reload configured).

server:EnableHotReload{
  Enabled = true,
  Modules = {"examples.hot_reload_message"},
  Prefixes = {"app."}
}

server:Run()

Starts the main server loop, accepts connections, and processes requests.

Inputs: no parameters (uses server configuration already set).

Output: blocking server execution loop.

server:Run()

Request Object

Every route handler receives a req table built by http:ParseRequest. These are the available fields:

server:Routes("/users/:id", function(req, res)
  print(req.method)        -- "GET"
  print(req.path)          -- "/users/42"
  print(req.params.id)     -- "42"
  print(req.headers["host"]) -- "localhost:8080"
  return res:response(200, { id = req.params.id })
end)

Create Config

Full field reference for the config table passed to PudimServer:Create(config?).

HttpsConfig

Enables native TLS via luasec. Requires the luasec rock installed.

local server = PudimServer:Create{
  Port = 8443,
  Https = {
    Enabled = true,
    Key = "./certs/server.key",
    Certificate = "./certs/server.crt"
  }
}

ConcurrencyConfig

Enables cooperative concurrency using Lua coroutines to handle multiple connections without blocking.

local server = PudimServer:Create{
  Port = 8080,
  Concurrency = { Enabled = true, Sleep = 0.001 }
}

HotReloadConfig

Development hot reload by clearing package.loaded entries before each request. No file watcher required.

local server = PudimServer:Create{
  Port = 8080,
  HotReload = {
    Enabled = true,
    Modules = {"examples.hot_reload_message"},
    Prefixes = {"app."}
  }
}

Request Lifecycle

Every incoming connection goes through these steps inside server:Run():

1. TCP accept — socket:accept() receives a raw client connection.
2. Socket middlewares — each middleware registered with SetMiddlewares runs sequentially on the raw TCP client (e.g. TLS wrapping).
3. Hot reload — if enabled, configured modules are cleared from package.loaded so the next require picks up fresh code.
4. Receive — client:receive() reads the raw HTTP data from the socket.
5. Parse — http:ParseRequest(raw) transforms the raw string into a Request table (method, path, headers, body, query, params).
6. CORS preflight — if the method is OPTIONS and CORS is enabled, a 204 preflight response is returned immediately.
7. Pipeline execute — pipeline:execute(req, res, routeHandler) runs all handlers added via UseHandler, each calling next() or short-circuiting.
8. Route match — the final handler in the pipeline finds the matching route and calls its handler function.
9. CORS headers — CORS response headers are injected into the final response string.
10. Send — client:send(response) writes the HTTP response back to the client and closes the connection.