🍮 PudimServer Docs

Getting Started

From zero to a running server in under 5 minutes.

1. Prerequisites

Verify your installation:

lua -v
luarocks --version

2. Install PudimServer

luarocks install PudimServer --local

This pulls luasocket, lua-cjson, and loglua automatically.

For HTTPS support, also install:

luarocks install luasec --local

3. Create your first server

Create a file called main.lua:

local PudimServer = require("PudimServer")

local server = PudimServer:Create{
  ServiceName = "My First API",
  Address = "0.0.0.0",
  Port = 8080
}

server:Routes("/", function(req, res)
  return res:response(200, "Hello from PudimServer!")
end)

server:Routes("/json", function(req, res)
  return res:response(200, {
    message = "Tables are auto-encoded to JSON",
    timestamp = os.time()
  })
end)

server:Run()

4. Run the server

lua main.lua

You should see a log message indicating the server is listening on port 8080.

5. Test with curl

Open another terminal and try these requests:

# Plain text response
curl http://localhost:8080/

# JSON response
curl http://localhost:8080/json

# See full headers
curl -v http://localhost:8080/

# POST request
curl -X POST http://localhost:8080/ -d '{"name":"Pudim"}'

# Test a non-existent route (404)
curl http://localhost:8080/missing

6. Add CORS and middleware

Extend your server by enabling CORS and adding a logging middleware:

server:EnableCors()

server:UseHandler{
  name = "logger",
  Handler = function(req, res, next)
    print(req.method .. " " .. req.path)
    return next()
  end
}

Now every request prints its method and path before route handling.

7. Dynamic routes and query strings

PudimServer supports :param segments and automatic query string parsing:

server:Routes("/users/:id", function(req, res)
  return res:response(200, { userId = req.params.id })
end)

server:Routes("/search", function(req, res)
  return res:response(200, { query = req.query })
end)

Test them:

curl http://localhost:8080/users/42
curl "http://localhost:8080/search?q=pudim&limit=10"

Next steps