Crescent 2.0OpenRestyLuaJITMySQL

O Nginx cuida do HTTP.
Você escreve Lua.

Um framework web sobre OpenResty: rotas, middleware, validação, ORM para MySQL, segurança e CLI — no mesmo processo que já atende suas requisições.

Open source · Licença MIT · Lua 5.1 / LuaJIT

Role para continuar

01Primeiro contato

Do clone à primeira resposta.

O crescent-starter traz um hello world, OpenResty e MySQL em containers. As migrations pendentes rodam ao subir e o código é recarregado a cada edição.

  • /api/hello — JSON com a query validada
  • /health — liveness, sem dependências
  • /ready — readiness, verifica o banco
$ git clone https://github.com/daniel-m-tfs/crescent-starter meu-app
$ cd meu-app && cp .env.example .env
$ docker compose up --build
# MySQL sobe, as migrations rodam, o OpenResty escuta em :8080
 
# em outro terminal
$ curl "http://127.0.0.1:8080/api/hello?name=Ada"
{"message":"Hello, Ada!"}
$ curl http://127.0.0.1:8080/ready
{"status":"ready","checks":{"database":{"status":"ok","duration_ms":1}}}
$ 
Saídas reais do hello world do starter. duration_ms varia conforme o ambiente.

02Arquitetura

Cada camada faz o que sabe fazer.

O Nginx recebe a conexão. O Crescent roda dentro de cada worker do OpenResty, montado uma única vez, e conversa com o MySQL por cosockets — sem bloquear o worker.

  1. Cliente HTTP / HTTPS
  2. Nginx · OpenResty TLS, workers, keep-alive, limites, arquivos estáticos
  3. Crescent
    1. middleware
    2. router
    3. action
    montado 1× por worker
  4. MySQL cosockets · SQL parametrizado
Uma requisição sai do cliente, passa pelo Nginx/OpenResty, entra no Crescent (middleware, router e action) e, quando necessário, consulta o MySQL por cosockets não bloqueantes.

O OpenResty cuida de

Conexões HTTP e HTTPS, terminação TLS, workers, keep-alive, limites de body e header, timeouts e arquivos estáticos em /public/.

O Crescent cuida de

Rotas, controllers, middleware, validação, erros padronizados, ORM e migrations, templates, segurança e CLI.

I/O não bloqueante

MySQL, cliente HTTP e SMTP usam os cosockets do OpenResty: enquanto uma consulta espera, o worker continua atendendo outras requisições.

03Código

Pouca cerimônia. Nada escondido.

Um módulo registra suas rotas; a action recebe ctx e responde. O schema valida a query antes da action — entrada inválida vira 422 com validation_failed.

Os três primeiros arquivos vêm do hello world do starter (a action mostra só o endpoint JSON). O model é o exemplo da documentação.

src/hello/init.lua

local controller = require("src.hello.controllers.hello")

local Module = {}

function Module.register(app)
    app:get("/", controller.index, "hello.index")
    app:get("/api/hello", app:validated({
        name = { type = "string", min_length = 1, max_length = 50 },
    }, controller.greet, "query"), "hello.greet")
end

return Module

src/hello/controllers/hello.lua

local HelloController = {}

-- GET /api/hello?name=Ada — `name` já foi validado por app:validated
function HelloController.greet(ctx)
    local name = ctx.query.name
    if name == nil or name == "" then name = "World" end
    return ctx:json(200, { message = "Hello, " .. name .. "!" })
end

return HelloController

app.lua

-- Montado uma vez por worker; o nginx chama require("app"):run()
local Crescent = require("crescent")
local Config = require("crescent.config")

local app = Crescent.new(Config.load())

app:use(Crescent.middleware.security_headers.create())
app:use(Crescent.middleware.request_log.create({
    skip = function(ctx) return ctx.path == "/health" or ctx.path == "/ready" end,
}))

require("src.health").register(app)
require("src.hello").register(app)

return app

src/users/models/user.lua

local Model = require("crescent.model")

local User = Model:extend({
    table = "users",
    fillable = { "name", "email", "password" },
    hidden = { "password" },
    timestamps = true,      -- created_at / updated_at
    soft_deletes = true,    -- deleted_at
    validates = {
        name = { required = true, min_length = 3 },
        email = { required = true, email = true, unique = true },
    },
    relations = {
        posts = { type = "has_many", model = "src.blog.models.post" },
    },
})

-- Eager loading: uma query por relação, sem N+1
local users = User:query():with("posts"):get()

return User

04Recursos

O necessário para uma API de verdade.

  • Rotas

    Parâmetros, opcionais e wildcard, grupos e rotas nomeadas. HEAD usa a rota GET; 405 inclui Allow.

    app:group("/api", fn)

  • Middleware e validação

    Middleware em cadeia com next(); schemas validam body ou query antes da action. Erros com code estável.

    app:validated(schema, action)

  • ORM e migrations

    Models com relações, paginação, soft deletes e hooks; migrations e seeders versionados. Todo SQL é parametrizado.

    Model:extend{ ... }

  • Cache e filas

    Cache e jobs em segundo plano com retry na memória do servidor, sem serviço extra. Redis opcional para durabilidade e várias réplicas.

    ctx.queue:push(job, payload)

  • Segurança

    JWT com revogação compartilhada entre workers, senhas com PBKDF2 via OpenSSL, auth, CORS, headers de segurança e rate limit.

    crescent.security.jwt

  • Web

    Cookies, sessões criptografadas, proteção CSRF, uploads multipart e views em etlua com layout.

    ctx:view("page.etlua", data)

  • Observabilidade

    Logs JSON estruturados com redação de segredos, X-Request-Id em toda requisição, /health e /ready.

    crescent.health

  • CLI

    Novo projeto, módulo CRUD completo com testes, migrations, seeders, servidor, lista de rotas e testes.

    bin/crescent make:module Product

  • Docker

    Imagem de produção com logs em stdout e um docker-compose de desenvolvimento com MySQL e recarga automática.

    docker compose up --build

05Status

Onde estamos, sem exageros.

O Crescent 2.0 é uma reescrita. A versão 1.x rodava sobre Luvit; a 2.0 entrega o HTTP ao OpenResty e mantém o estilo de módulos, controllers e models declarativos.

Versão
2.0 — reescrita sobre OpenResty
Runtime
OpenResty (Nginx + LuaJIT, Lua 5.1)
Banco
MySQL / MariaDB — o único suportado por enquanto
Licença
MIT

Vindo do 1.x

A API mudou em alguns pontos — por exemplo, ctx.json(...) virou ctx:json(...) e middleware interrompe a cadeia retornando uma resposta. As notas de migração estão no README do framework.

Próximos passos

A prioridade é consolidar uma API pública pequena e estável. Outros bancos dependem de adapters e não têm data prometida. Bugs e sugestões são bem-vindos nas issues.

Comece pelo starter.

Um repositório, dois comandos, uma API respondendo em :8080.

cp .env.example .env && docker compose up --build