Merge pull request #2 from pessoa736/dev

feat: add CORS, pipeline, cache, tests and docs

Author: pessoa736

.github/copilot-instructions.md

@@ -0,0 +1,91 @@
+# Copilot Instructions for PudimServer
+
+## Project Overview
+
+PudimServer is a Lua HTTP server library distributed via LuaRocks. It provides a routing system where users create a server instance with `PudimServer:Create{}`, register routes with `:Routes(path, handler)`, and start with `:Run()`. Route handlers receive `(req, res)` and must return `res:response(status, body, headers)`.
+
+## Dependencies & Runtime
+
+- **Lua >= 5.4** (`.luarc.json` targets Lua 5.5)
+- **LuaRocks** for package management
+- Core deps: `luasocket`, `lua-cjson`, `loglua`, `luasec` (ssl)
+
+Install dependencies:
+
+```sh
+luarocks install luasocket --local
+luarocks install lua-cjson --local
+```
+
+## Running the Test Server
+
+```sh
+lua ./PudimServer/mysandbox/test.lua
+```
+
+This starts a local server on `localhost:8080` serving HTML/CSS pages from `PudimServer/mysandbox/`.
+
+## Running Tests
+
+Unit tests use [busted](https://lunarmodules.github.io/busted/). Tests live in `spec/`.
+
+```sh
+# Run all tests
+./lua_modules/bin/busted --no-auto-insulate spec/
+
+# Run a single test file
+./lua_modules/bin/busted --no-auto-insulate spec/utils_spec.lua
+
+# Run tests matching a pattern
+./lua_modules/bin/busted --no-auto-insulate spec/ --filter "ParseRequest"
+```
+
+## Architecture
+
+The library entry point is `PudimServer/init.lua`, which exports the `PudimServer` table (used as a class via metatables). Key modules:
+
+- **`init.lua`** — Server lifecycle: `Create`, `Routes`, `Run`, `SetMiddlewares`, `RemoveMiddlewares`. `Run()` enters an infinite accept loop with middleware pipeline.
+- **`http.lua`** — HTTP parsing (`ParseRequest`) and response building (`response`). Tables passed as body are auto-encoded to JSON via `cjson`.
+- **`utils.lua`** — Shared utilities: file I/O, runtime type-checking system (`createInterface`/`verifyTypes`), and `loadMessageOnChange` for deduplicated logging.
+- **`cors.lua`** — CORS helpers: `createConfig`, `buildHeaders`, `preflightResponse`. Enabled via `Server:EnableCors(config)`.
+- **`pipeline.lua`** — Request/response pipeline (middleware chain at HTTP level). Handlers receive `(req, res, next)` and call `next()` to continue or return early to short-circuit.
+- **`cache.lua`** — In-memory response cache with TTL and eviction. Provides `Cache.new(config)` and `Cache.createPipelineHandler(cache)` for pipeline integration.
+- **`ServerChecks.lua`** — Network utilities (port-open check via TCP connect).
+
+### Runtime Type System
+
+The codebase uses a custom interface/contract system instead of relying solely on Lua's dynamic typing. Interfaces are created with `utils:createInterface{field = "type"}` and validated with `utils:verifyTypes(value, interface, logFn, shouldExit)`. This pattern is used extensively — new code should follow it.
+
+### Middleware Pipeline
+
+Middlewares are registered via `Server:SetMiddlewares{name = "...", Handler = function(client) ... end}` and run sequentially in `GetClient()` on each accepted connection. The `Run()` method currently auto-registers an SSL middleware.
+
+### Logging
+
+All logging uses the `loglua` library via the global `_G.log`. Modules use `log.inSection("name")` for scoped loggers and `utils:loadMessageOnChange()` to avoid duplicate log messages.
+
+## Code Conventions
+
+- **Indentation:** 2 spaces
+- **Naming:** `camelCase` for variables/functions, `PascalCase` for classes/modules
+- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
+- **PR target:** Always target the `dev` branch
+- **LuaDoc annotations:** Use `---@class`, `---@field`, `---@type`, `---@param` annotations for type hints
+- **Comments:** Portuguese or English are both acceptable
+- **Globals:** `_G.log` and `_G.cjson` are initialized on first require and expected to be available globally
+
+## LuaRocks Module Map
+
+The rockspec at `rockspecs/pudimserver-0.1.0-1.rockspec` maps module names to files:
+
+```
+PudimServer              → PudimServer/init.lua
+PudimServer.http         → PudimServer/http.lua
+PudimServer.utils        → PudimServer/utils.lua
+PudimServer.cors         → PudimServer/cors.lua
+PudimServer.pipeline     → PudimServer/pipeline.lua
+PudimServer.cache        → PudimServer/cache.lua
+PudimServer.ServerChecks → PudimServer/ServerChecks.lua
+```
+
+New modules must be added to both the `modules` table in the rockspec and follow the `PudimServer/` directory structure.

.gitignore

@@ -43,3 +43,7 @@ luac.out
 
 *.crt
 *.key
+/luarocks
+/lua
+/lua_modules
+/.luarocks

.luarc.json

@@ -0,0 +1,3 @@
+{
+  "runtime.version": "Lua 5.5"
+}

PS/ServerChecks.lua PudimServer/ServerChecks.luaPS/ServerChecks.lua renamed to PudimServer/ServerChecks.lua

@@ -1,6 +1,9 @@
+---@diagnostic disable: duplicate-doc-field
+
+
 if not _G.log then _G.log = require("loglua") end
 local socket = require("socket")
-local utils = require("PS.utils")
+local utils = require("PudimServer.utils")
 
 
 --- interfaces

PudimServer/cache.lua

@@ -0,0 +1,154 @@
+---@diagnostic disable: duplicate-doc-field
+
+if not _G.log then _G.log = require("loglua") end
+local utils = require("PudimServer.utils")
+local socket = require("socket")
+
+
+--- interfaces
+
+---@class CacheConfig
+---@field MaxSize number? Máximo de entradas no cache (default: 100)
+---@field DefaultTTL number? TTL padrão em segundos (default: 60)
+
+local CacheConfigInter = utils:createInterface{
+  MaxSize = {"number", "nil"},
+  DefaultTTL = {"number", "nil"},
+}
+
+
+---@class CacheEntry
+---@field response string Resposta HTTP cacheada
+---@field expiresAt number Timestamp de expiração
+
+
+---------
+--- main
+
+---@class Cache
+---@field _entries table<string, CacheEntry>
+---@field _maxSize number
+---@field _defaultTTL number
+local Cache = {}
+Cache.__index = Cache
+
+
+---@param config? CacheConfig
+---@return Cache
+function Cache.new(config)
+  local CL = log.inSection("Cache")
+
+  config = config or {}
+  utils:verifyTypes(config, CacheConfigInter, CL.error, true)
+
+  local self = setmetatable({}, Cache)
+  self._entries = {}
+  self._maxSize = config.MaxSize or 100
+  self._defaultTTL = config.DefaultTTL or 60
+  self._size = 0
+  return self
+end
+
+
+---@param key string
+---@return string? response
+function Cache:get(key)
+  local entry = self._entries[key]
+  if not entry then return nil end
+
+  if socket.gettime() > entry.expiresAt then
+    self._entries[key] = nil
+    self._size = self._size - 1
+    return nil
+  end
+
+  return entry.response
+end
+
+
+---@param key string
+---@param response string
+---@param ttl? number TTL em segundos (usa default se nil)
+function Cache:set(key, response, ttl)
+  if not self._entries[key] then
+    -- Evict oldest if full
+    if self._size >= self._maxSize then
+      self:_evict()
+    end
+    self._size = self._size + 1
+  end
+
+  self._entries[key] = {
+    response = response,
+    expiresAt = socket.gettime() + (ttl or self._defaultTTL)
+  }
+end
+
+
+---@param key string
+function Cache:invalidate(key)
+  if self._entries[key] then
+    self._entries[key] = nil
+    self._size = self._size - 1
+  end
+end
+
+
+function Cache:clear()
+  self._entries = {}
+  self._size = 0
+end
+
+
+function Cache:_evict()
+  local oldestKey = nil
+  local oldestTime = math.huge
+
+  for key, entry in pairs(self._entries) do
+    if entry.expiresAt < oldestTime then
+      oldestTime = entry.expiresAt
+      oldestKey = key
+    end
+  end
+
+  if oldestKey then
+    self._entries[oldestKey] = nil
+    self._size = self._size - 1
+  end
+end
+
+
+---@param cacheInstance Cache
+---@param ttl? number TTL customizado
+---@return PipelineEntry
+function Cache.createPipelineHandler(cacheInstance, ttl)
+  return {
+    name = "cache",
+    Handler = function(req, res, next)
+      -- Só cacheia GET requests
+      if req.method ~= "GET" then
+        return next()
+      end
+
+      local key = req.method .. ":" .. req.path
+      local cached = cacheInstance:get(key)
+
+      if cached then
+        log.inSection("Cache").debug("cache hit: " .. key)
+        return cached
+      end
+
+      local response = next()
+
+      if response then
+        cacheInstance:set(key, response, ttl)
+        log.inSection("Cache").debug("cache set: " .. key)
+      end
+
+      return response
+    end
+  }
+end
+
+
+return Cache

PudimServer/cors.lua

@@ -0,0 +1,102 @@
+---@diagnostic disable: duplicate-doc-field
+
+if not _G.log then _G.log = require("loglua") end
+local utils = require("PudimServer.utils")
+
+
+--- interfaces
+
+---@class CorsConfig
+---@field AllowOrigins string|string[]? Origins permitidas (default: "*")
+---@field AllowMethods string|string[]? Métodos permitidos (default: "GET, POST, PUT, DELETE, PATCH, OPTIONS")
+---@field AllowHeaders string|string[]? Headers permitidos (default: "Content-Type, Authorization")
+---@field ExposeHeaders string|string[]? Headers expostos ao browser
+---@field AllowCredentials boolean? Permitir credentials (default: false)
+---@field MaxAge number? Tempo em segundos do cache preflight (default: 86400)
+
+local CorsConfigInter = utils:createInterface{
+  AllowOrigins = {"string", "table", "nil"},
+  AllowMethods = {"string", "table", "nil"},
+  AllowHeaders = {"string", "table", "nil"},
+  ExposeHeaders = {"string", "table", "nil"},
+  AllowCredentials = {"boolean", "nil"},
+  MaxAge = {"number", "nil"},
+}
+
+
+---------
+--- main
+
+---@type table
+local cors = {}
+
+
+---@param value string|string[]|nil
+---@param default string
+---@return string
+local function toHeaderValue(value, default)
+  if not value then return default end
+  if type(value) == "table" then
+    return table.concat(value, ", ")
+  end
+  return value
+end
+
+
+---@param config? CorsConfig
+---@return table corsHeaders Headers CORS resolvidos
+---@return CorsConfig resolvedConfig Config com defaults aplicados
+function cors.createConfig(config)
+  local CL = log.inSection("CORS")
+
+  config = config or {}
+  utils:verifyTypes(config, CorsConfigInter, CL.error, true)
+
+  local resolved = {
+    AllowOrigins = toHeaderValue(config.AllowOrigins, "*"),
+    AllowMethods = toHeaderValue(config.AllowMethods, "GET, POST, PUT, DELETE, PATCH, OPTIONS"),
+    AllowHeaders = toHeaderValue(config.AllowHeaders, "Content-Type, Authorization"),
+    ExposeHeaders = toHeaderValue(config.ExposeHeaders, ""),
+    AllowCredentials = config.AllowCredentials or false,
+    MaxAge = config.MaxAge or 86400,
+  }
+
+  return resolved
+end
+
+
+---@param config table Config resolvida do CORS
+---@param requestOrigin string? Origin do request
+---@return table headers Headers CORS para adicionar na resposta
+function cors.buildHeaders(config, requestOrigin)
+  local headers = {}
+
+  headers["Access-Control-Allow-Origin"] = config.AllowOrigins
+  headers["Access-Control-Allow-Methods"] = config.AllowMethods
+  headers["Access-Control-Allow-Headers"] = config.AllowHeaders
+
+  if config.ExposeHeaders ~= "" then
+    headers["Access-Control-Expose-Headers"] = config.ExposeHeaders
+  end
+
+  if config.AllowCredentials then
+    headers["Access-Control-Allow-Credentials"] = "true"
+  end
+
+  headers["Access-Control-Max-Age"] = tostring(config.MaxAge)
+
+  return headers
+end
+
+
+---@param config table Config resolvida do CORS
+---@return string Resposta HTTP para preflight
+function cors.preflightResponse(config)
+  local http = require("PudimServer.http")
+  local headers = cors.buildHeaders(config)
+  headers["Content-Length"] = "0"
+  return http:response(204, "", headers)
+end
+
+
+return cors