🌙 Crescent Framework

Framework web em Lua sobre OpenResty (Nginx + LuaJIT) com MySQL. Documentação da versão 2.0.

Comece agora

Use o template crescent-starter (hello world, Docker e MySQL) e rode com docker compose up --build.

crescent-starter no GitHub →

O que é o Crescent

Crescent é um framework web em Lua que roda sobre o OpenResty (Nginx + LuaJIT) e usa MySQL. O Nginx cuida do HTTP (TLS, workers, keep-alive, limites, arquivos estáticos); o Crescent cuida de rotas, middleware, validação, ORM, migrations, templates, segurança e CLI.

Esta documentação é da versão 2.0. Vindo do Crescent 1.x (Luvit)? Veja Migrando do 1.x.

Requisitos

Com Docker Sem Docker
Docker com Compose OpenResty (inclui resty, lua-resty-mysql, lua-resty-openssl)
— LuaRocks (para instalar etlua, lua-resty-http, lua-resty-mail)
— MySQL 8 ou MariaDB

Criando um projeto

O jeito mais rápido é partir do template crescent-starter: ele já traz um hello world, Docker, MySQL e a CLI.

git clone https://github.com/daniel-m-tfs/crescent-starter.git meu-app
cd meu-app

Se você tem o repositório do framework, lua cli.lua new meu-app gera o mesmo projeto e já cria o .env com APP_KEY e JWT_SECRET aleatórios (pule o cp abaixo).

Com Docker (recomendado)

lua cli.lua setup    # git do zero, usuário/senha do MySQL, Redis opcional e sobe o Docker

O setup pergunta antes de cada passo (Enter aceita o padrão): recomeça o histórico do git sem o remote do template e adiciona o seu remote (opcional), grava usuário e senha do banco no .env (que ele cria com APP_KEY e JWT_SECRET aleatórios), pergunta se você quer Redis para cache e filas (sem ele, ambos usam a memória do servidor) e sobe a aplicação com hot reload. Depois, no dia a dia:

lua cli.lua run      # sobe app + MySQL (hot reload)
lua cli.lua rerun    # reconstrói a imagem: Dockerfile, dependências ou Nginx mudaram
lua cli.lua stop     # para, mantendo o banco

Pronto:

  • http://127.0.0.1:8080 — página hello world
  • /api/hello?name=Ada — exemplo JSON com validação
  • /health e /ready — liveness e readiness (verifica o banco)

O código fica montado no container com recarga automática (edite e recarregue a página) e as migrations pendentes rodam ao subir. Rode a CLI dentro do container:

docker compose exec app bin/crescent routes

Sem Docker

./deps.sh                      # instala as dependências Lua em ./lua_modules
cp .env.example .env           # ajuste DB_* para o seu MySQL
lua cli.lua server start       # http://127.0.0.1:8080
curl http://127.0.0.1:8080/health

O deps.sh encontra o LuaJIT do OpenResty (Homebrew, /usr/local/openresty ou /opt/openresty); para outro local, use OPENRESTY_LUAJIT=/caminho/luajit ./deps.sh.

lua cli.lua server stop para o servidor. Em desenvolvimento o nginx.conf usa lua_code_cache off, então alterações no código valem na próxima requisição.


Estrutura do projeto

app.lua            monta a aplicação: middlewares + módulos
config/            configuração por ambiente (development.lua, production.lua, test.lua)
src/<módulo>/      init.lua (register), controllers/, services/, models/, routes/
views/             templates etlua (layout.etlua + páginas)
public/            arquivos estáticos, servidos pelo Nginx em /public/
migrations/        lua cli.lua make:migration
seeds/             lua cli.lua make:seeder
storage/           uploads (upload_root = "storage")
tests/             lua cli.lua test
crescent/  cli/    o framework, versionado junto com o projeto
nginx.conf         Nginx de desenvolvimento local
conf/              Nginx de produção e dos containers
Dockerfile  docker-compose.yml  docker/

O app.lua gerado:

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

Primeiro módulo

Gere um CRUD completo (controller, service, model, rotas, teste e migration):

lua cli.lua make:module Product

Registre o módulo no app.lua:

require("src.product").register(app)

Crie a tabela (com Docker: docker compose exec app bin/crescent db:migrate):

lua cli.lua db:migrate

E teste:

curl -X POST http://127.0.0.1:8080/products \
  -H 'Content-Type: application/json' -d '{"name":"Teclado"}'
# 201 {"data":{"id":1,"name":"Teclado","created_at":"...","updated_at":"..."}}

curl http://127.0.0.1:8080/products
# {"data":[...],"meta":{"page":1,"per_page":15,"total":1,"last_page":1,"from":1,"to":1}}

curl http://127.0.0.1:8080/products/1
curl -X PUT http://127.0.0.1:8080/products/1 \
  -H 'Content-Type: application/json' -d '{"name":"Teclado mecânico"}'
curl -X DELETE http://127.0.0.1:8080/products/1    # 204

Um POST sem name responde 422 com os erros por campo; um id inexistente responde 404.

Método Caminho Nome da rota
GET /products products.index
GET /products/{id} products.show
POST /products products.store
PUT /products/{id} products.update
DELETE /products/{id} products.destroy

Próximos passos

  • Conceitos — rotas, ctx, middleware, validação, erros e views.
  • Banco de dados — models, relações, query builder e migrations.
  • Segurança — JWT, sessões, CSRF, CORS e rate limit.
  • Cache e filas — ctx.cache, jobs em segundo plano e Redis opcional.
  • CLI — todos os comandos de lua cli.lua.
  • Deploy — imagem Docker e Nginx de produção.

A aplicação

O app.lua cria a aplicação com Crescent.new(config), registra middlewares e módulos e retorna o app. O Nginx executa esse arquivo uma vez por worker e, a cada requisição, chama require("app"):run():

location / {
    content_by_lua_block {
        require("app"):run()
    }
}

Consequências práticas:

  • Código no topo de app.lua e dos módulos roda uma vez por worker, não por requisição. Não guarde estado de requisição em variáveis de módulo; use ctx.state.
  • Em produção (lua_code_cache on) é preciso recarregar o Nginx para aplicar mudanças. Em desenvolvimento o nginx.conf usa lua_code_cache off e recarrega o código a cada requisição.
  • O Nginx de produção constrói o app já no init_by_lua_block: um erro de configuração falha o start/reload em vez da primeira requisição.

Cada módulo expõe uma função register(app):

-- src/hello/init.lua
local controller = require("src.hello.controllers.hello")

local Module = {}

function Module.register(app)
    app:get("/", controller.index, "hello.index")
end

return Module

Configuração e ambiente

Config.load() carrega config/<APP_ENV>.lua (padrão development). Os arquivos de config leem variáveis com crescent.env:

-- config/production.lua
local Env = require("crescent.env")

return {
    environment = "production",
    debug = false,
    server = { host = "127.0.0.1", port = 8080, max_body_size = 5 * 1024 * 1024 },
    database = {
        host = Env.get("DB_HOST"),
        port = Env.number("DB_PORT", 3306),
        database = Env.get("DB_NAME"),
        user = Env.get("DB_USER"),
        password = Env.get("DB_PASSWORD"),
    },
}
Função Retorno
Env.get(nome, padrão) string; ordem: variável do processo, depois .env, depois o padrão
Env.number(nome, padrão) número (erro se o valor não for numérico)
Env.boolean(nome, padrão) true/false a partir de true, 1, yes, false, 0, no

Pegadinha do Nginx: o Nginx limpa o ambiente dos workers. Toda variável lida pela aplicação precisa de uma diretiva env NOME; no nginx.conf e nos arquivos de conf/, senão Env.get não a enxerga (em produção, sem .env, ela simplesmente vem vazia). Os arquivos gerados já declaram APP_*, DB_*, JWT_SECRET, SMTP_*, REDIS_*, CACHE_DRIVER e QUEUE_DRIVER.

O .env é só conveniência local; em produção use variáveis de ambiente de verdade. A porta é definida pelo listen do nginx.conf (o server.port da config é apenas validado).

Outras chaves aceitas pela config da aplicação:

Chave Uso
debug inclui detalhes internos nas respostas de erro e desativa o cache de templates
database conexão MySQL; quando tem database, o app configura o banco e expõe ctx.db
cache / queue / redis expõem ctx.cache e ctx.queue; redis é usado pelos drivers redis (veja Cache e filas)
views_root / view_layout pasta dos templates (padrão views) e layout padrão
error_handler função (ctx, err) para erros não tratados (veja Erros)
logger instância de crescent.logger ou function(level, message, fields)
secret_key / secret_key_fallbacks segredo de cookies assinados, sessões e CSRF (padrão: APP_KEY)
upload_root / upload destino de ctx:save_upload e limites de upload

Rotas

app:get("/users", list_users)
app:post("/users", create_user)
app:put("/users/{id}", update_user)
app:patch("/users/{id}", patch_user)
app:delete("/users/{id}", delete_user)
Padrão Exemplo ctx.params
/users/{id} /users/42 { id = "42" }
/posts/{slug?} /posts e /posts/ola slug é nil quando ausente
/files/{path*} /files/a/b/c.txt { path = "a/b/c.txt" } (só no último segmento)

Parâmetros chegam sempre como string. Rotas estáticas têm prioridade sobre rotas com parâmetros, independentemente da ordem de registro.

Grupos e nomes:

app:group("/api/v1", function(api)
    api:get("/users/{id}", show_user, "users.show")   -- GET /api/v1/users/{id}
end)

app:route("users.show")   -- "/api/v1/users/{id}"
  • HEAD usa a rota GET automaticamente.
  • Caminho existente com outro método responde 405 com o header Allow; caminho inexistente responde 404 (route_not_found).
  • lua cli.lua routes lista todas as rotas com método, caminho e nome.

Controllers e o ctx

Um handler de rota é uma função que recebe o contexto da requisição (ctx) e responde. Nos módulos, os handlers ficam em controllers/ e delegam as regras de negócio para services/:

app:get("/users/{id}", function(ctx)
    local user = User:find_or_fail(ctx.params.id)
    return ctx:json(200, { data = user:to_table() })
end)

Dados da requisição

Campo Conteúdo
ctx.params parâmetros da rota
ctx.query query string (valores string; chave repetida vira lista)
ctx.body JSON ou form decodificado em tabela; outros tipos ficam como string
ctx.raw_body corpo original em texto
ctx.files arquivos de um multipart/form-data (veja Uploads)
ctx:get_header("User-Agent") header (nome sem diferenciar maiúsculas)
ctx:get_bearer() token de Authorization: Bearer ..., ou nil
ctx:cookie("nome") cookie (veja Cookies)
ctx.method, ctx.path, ctx.route método, caminho e padrão da rota encontrada
ctx.request_id, ctx.remote_addr id da requisição (também no header X-Request-Id) e IP do cliente
ctx.state tabela livre para passar dados entre middleware e action
ctx.db, ctx.config, ctx.app, ctx.debug banco, configuração, aplicação e modo debug
ctx.cache, ctx.queue, ctx.redis cache, fila de jobs e cliente Redis, quando configurados

Um corpo JSON inválido é recusado antes da action com 400 malformed_json.

Respostas

Método Resposta
ctx:json(status, valor) JSON (application/json; charset=utf-8)
ctx:text(status, texto) texto puro
ctx:html(status, html) HTML
ctx:view(nome, dados, opções) template etlua (veja Views e layouts)
ctx:redirect(url, status) redirecionamento (padrão 302)
ctx:no_content() 204 sem corpo
ctx:error(status, mensagem, detalhes, código) erro JSON padronizado
ctx:header(nome, valor) define um header da resposta (encadeável)

Atalhos: retornar uma tabela envia 200 JSON e retornar uma string envia 200 texto. Uma action que não responde nem retorna nada gera 500 empty_response.

app:get("/ping", function() return { pong = true } end)   -- 200 {"pong":true}
  • ctx:redirect aceita só caminhos locais (/...); para outro domínio passe { allowed_hosts = { "exemplo.com" } } como terceiro argumento.
  • Para listas vazias em JSON use json.array({}) (de crescent.json), senão uma tabela vazia vira {}.
  • Models não viram JSON sozinhos: use model:to_table().

Middleware

Um middleware recebe (ctx, next). Chame next() para continuar; para bloquear, responda sem chamar next():

app:use(function(ctx, next)
    if ctx:get_header("X-Api-Key") ~= "segredo" then
        return ctx:error(401, "unauthorized", nil, "unauthorized")
    end
    ctx.state.client = "interno"
    return next()
end)
  • Middlewares rodam na ordem de app:use, antes do roteamento, em todas as requisições.
  • Código depois de next() roda depois da action. Para alterar headers da resposta nesse momento, use ctx.res:before_flush(function(res) ... end), pois a resposta normalmente já foi enviada quando next() retorna.
  • Para proteger uma rota só, envolva a action com auth.protect (aceita um middleware ou uma lista):
local auth = require("crescent.middleware.auth")

app:get("/admin", auth.protect({ auth.jwt(), require_admin }, admin_action))

lua cli.lua make:middleware nome gera o esqueleto em src/middleware/nome.lua. Os middlewares prontos (auth, CORS, rate limit, sessão, CSRF, headers de segurança, log) estão em Segurança e Utilitários.


Validação

app:validated(schema, action, origem) valida antes de chamar a action e responde 422 validation_failed com os erros por campo. A origem padrão é "body"; use "query" para a query string.

app:post("/users", app:validated({
    name = { required = true, string = true, min_length = 3, max_length = 50 },
    email = { required = true, email = true },
    age = { number = true, min = 18 },
    role = { custom = function(v) return v == "admin" or v == "user", "role inválido" end },
}, function(ctx)
    return ctx:json(201, ctx.body)
end))

Resposta de erro:

{
  "status": 422,
  "code": "validation_failed",
  "error": "validation failed",
  "details": { "name": [{ "code": "min_length", "message": "name must be at least 3 characters" }] }
}
Regra Valida
required presente e diferente de ""
type = "string" tipo Lua exato (interrompe as demais regras do campo)
string, number tipo do valor
min_length, max_length, length tamanho de strings (em caracteres UTF-8)
email, format e-mail simples; padrão Lua (format = "^%d+$")
min, max, range = { 1, 10 } limites de números
custom function(valor) que retorna true ou false, "mensagem"

Campos ausentes só falham com required. Valores de query string e de formulários são strings: number = true só passa para JSON; para query use format ou converta com tonumber na action.

Para validar manualmente: local ok, errors = ctx:validate(schema, "query").


Erros

Todo erro é um JSON com status, code (estável, para o cliente tratar) e error (mensagem); details é opcional:

return ctx:error(409, "e-mail já cadastrado", { field = "email" }, "email_taken")
-- 409 {"status":409,"code":"email_taken","error":"e-mail já cadastrado","details":{"field":"email"}}

Erros lançados (error(...)) dentro de controllers e middlewares:

  • Viram 500 internal_error e são registrados no log com o request id. O detalhe (mensagem e stack trace) só aparece na resposta com debug = true.
  • Uma tabela com status 4xx vira essa resposta, sem log de erro. É assim que Model:find_or_fail produz 404 model_not_found:
error({ status = 403, code = "no_access", public_message = "sem acesso" })
-- 403 {"status":403,"code":"no_access","error":"sem acesso"}

Para personalizar a resposta de erros 500, registre um handler (ele precisa responder):

app:on_error(function(ctx, err)
    return ctx:json(500, { error = "algo deu errado", request_id = ctx.request_id })
end)

Códigos que o próprio framework gera:

Código Status Quando
route_not_found 404 nenhuma rota para o caminho
method_not_allowed 405 caminho existe com outro método
validation_failed 422 app:validated
model_not_found 404 find_or_fail
malformed_json, malformed_form 400 corpo inválido
invalid_redirect 400 ctx:redirect para destino não permitido
internal_error, empty_response 500 erro não tratado; action sem resposta
template_error 500 falha ao renderizar um template

Autenticação, CSRF, CORS, rate limit e uploads têm seus próprios códigos (missing_credentials, csrf_invalid, rate_limited...), listados em Segurança.


Views e layouts

Templates usam etlua e ficam em views/. O nome inclui a extensão .etlua:

app:get("/", function(ctx)
    return ctx:view("hello/index.etlua", { title = "Início" }, { layout = "layout.etlua" })
end)
<!-- views/hello/index.etlua -->
<h1><%= title %></h1>
<ul>
  <% for _, item in ipairs(items or {}) do %>
    <li><%= item %></li>
  <% end %>
</ul>
<!-- views/layout.etlua -->
<!doctype html>
<html lang="pt-BR">
<head><title><%= title or "Crescent" %></title></head>
<body><%- content %></body>
</html>
  • <%= valor %> escapa HTML; <%- valor %> imprime sem escapar (use só com HTML confiável, como content e csrf_field()).
  • O layout recebe a página pronta em content e os mesmos dados da página.
  • Opções: status (padrão 200) e layout. Defina view_layout = "layout.etlua" na config para ter um layout padrão; layout = false desliga em uma página.
  • Helpers globais: app.view_renderer:helper("upper", function(s) return s:upper() end).
  • Com o middleware de sessão ativo, todo template recebe csrf_token() e csrf_field().
  • Templates ficam em cache quando debug = false.

Configuração

O Crescent 2.0 suporta somente MySQL/MariaDB, via lua-resty-mysql (não bloqueia o worker). A conexão vem de config.database:

-- config/development.lua
database = {
    host = Env.get("DB_HOST", "127.0.0.1"),
    port = Env.number("DB_PORT", 3306),
    database = Env.get("DB_NAME", "meu_app_dev"),
    user = Env.get("DB_USER", "crescent"),
    password = Env.get("DB_PASSWORD", ""),
},

Crescent.new(config) configura o banco no boot (sem abrir conexão: cada query pega uma conexão do pool do worker). A partir daí, models e query builder usam esse banco automaticamente, e os controllers o recebem em ctx.db.

Chave opcional Padrão Descrição
charset "utf8mb4" charset da conexão
connect_timeout / timeout 5000 / 10000 em ms
pool_size 100 conexões mantidas por worker
max_idle_timeout 10000 tempo ocioso no pool (ms)
ssl, ssl_verify — TLS com o MySQL

SQL direto, sempre com ? (os valores são escapados):

local rows, err = ctx.db:query("SELECT id, name FROM users WHERE email = ?", { email })
local result = ctx.db:execute("UPDATE users SET name = ? WHERE id = ?", { "Ada", 1 })
-- result = { affected_rows = 1, insert_id = 0 }

Erros retornam nil, err, errno, sqlstate, kind, em que kind é "unique_violation", "foreign_key_violation", "deadlock", "lock_timeout", "connection", "bind" ou "query".


Models

-- src/users/models/user.lua
local Model = require("crescent.model")

return Model:extend({
    table = "users",
    fillable = { "name", "email", "password" },  -- campos aceitos em create/update
    hidden = { "password" },                     -- fora de to_table()
    timestamps = true,                           -- created_at / updated_at
    validates = {
        name = { required = true, min_length = 3 },
        email = { required = true, email = true, unique = true },
    },
})

lua cli.lua make:model User users gera um esqueleto em src/users/models/user.lua. As regras de validates são as mesmas de Validação, mais unique = true (consulta o banco; mantenha também um índice UNIQUE).

CRUD

local User = require("src.users.models.user")

local user, errors = User:create({ name = "Ada", email = "ada@example.com" })
if not user then
    return ctx:error(422, "validation failed", errors, "validation_failed")
end

local user = User:find(1)                    -- model ou nil
local user = User:find_or_fail(1)            -- lança 404 model_not_found
local admins = User:where("role", "admin"):order_by("name"):get()
local first = User:where("email", email):first()
local total = User:count()

user.name = "Ada Lovelace"
user:save()                                  -- UPDATE só das colunas alteradas
user:update({ name = "Ada Byron" })          -- fill + save
user:delete()

return ctx:json(200, { data = user:to_table() })
  • create, save e update retornam o model, ou nil, erros. Erros de validação (e de chave única do MySQL) chegam como tabela { campo = { { code, message } } }; falhas de banco chegam como string.
  • User:where(...) aceita o mesmo encadeamento do query builder e termina em get(), first(), count() ou page().
  • user.name lê o atributo. Se a coluna tiver o nome de um método do model (table, save, update...), use user:get("coluna") e user:set("coluna", valor).
  • Converta para JSON com user:to_table(); ela respeita hidden e inclui relações carregadas.
  • O último argumento opcional de todos os métodos é o adaptador de banco (por exemplo, a transação tx).

Paginação

local result = User:where("active", 1):order_by("name"):page(ctx.query.page, ctx.query.per_page)
-- result.data = { models }
-- result.meta = { page, per_page, total, last_page, from, to }

Valores inválidos voltam ao padrão (página 1, 15 por página) e per_page é limitado a 100 (passe { max_per_page = n } como terceiro argumento para mudar).

Tipos das colunas (casts)

O MySQL devolve BIGINT como string. O model converte automaticamente a chave primária e colunas *_id para número. Para outras colunas, declare casts:

casts = { active = "boolean", price = "number", external_id = "string" },

Tipos: string, number, integer, boolean (1/0 vira true/false).

Soft deletes

return Model:extend({ table = "users", soft_deletes = true })   -- precisa da coluna deleted_at
  • user:delete() grava deleted_at; consultas passam a ignorar o registro.
  • User:with_trashed() inclui os apagados; User:only_trashed() traz só eles.
  • user:restore() desfaz; user:force_delete() apaga de verdade.

Hooks

Funções na definição do model que recebem a instância. Um hook before_* que retorna false cancela a operação.

before_save = function(user)
    user.email = user.email:lower()
end,

Disponíveis: before_save, before_create, before_update, after_create, after_update, after_save, before_delete, after_delete.


Relações

Declare as relações na tabela relations. model pode ser o nome do módulo (resolvido sob demanda, evita require circular):

-- users
relations = {
    posts = { type = "has_many", model = "src.blog.models.post" },
    profile = { type = "has_one", model = "src.users.models.profile" },
},

-- posts
relations = {
    user = { type = "belongs_to", model = "src.users.models.user" },
},
Tipo Chave estrangeira padrão
has_many, has_one singular da tabela do pai + _id, na tabela relacionada (users → user_id)
belongs_to singular da tabela relacionada + _id, na própria tabela

Informe foreign_key (e local_key/owner_key) quando o padrão não servir.

Eager loading com with: uma query por relação para todos os registros, sem N+1.

local users = User:with("posts"):get()
users[1].posts                    -- lista de Post

local posts = Post:with("user", "comments.author"):get()   -- relações aninhadas

-- restringir a query da relação
User:query():with({ posts = function(q) q:order_by("created_at", "DESC") end }):get()

Sem eager loading, user:get("posts") carrega a relação na primeira chamada (user.posts só funciona depois de carregada).


Query builder

Para consultas sem model (os resultados são tabelas simples):

local QueryBuilder = require("crescent.database.query_builder")

local rows = QueryBuilder.table("users")
    :select("users.id", "users.name", "profiles.bio")
    :left_join("profiles", "profiles.user_id", "users.id")
    :where("active", true)
    :where("age", ">=", 18)
    :where(function(q) q:where("role", "admin"):or_where("verified", true) end)
    :where_in("country", { "BR", "PT" })
    :order_by("users.name")
    :limit(20)
    :get()
Grupo Métodos
Filtros where, or_where, where_in, where_not_in, where_null, where_not_null, where_raw(sql, bindings)
Junções join, left_join, right_join
Ordem e limite order_by(coluna, "ASC" ou "DESC"), limit, offset, paginate(página, por_página)
Execução get(), first(), count(), exists(), page(página, por_página)
Escrita insert(valores), update(valores), delete()
Depuração to_sql() retorna sql, bindings sem executar
  • Operadores aceitos: =, !=, <>, <, <=, >, >=, LIKE, NOT LIKE. where("coluna", nil) gera IS NULL.
  • update e delete sem where lançam erro (proteção contra alterar a tabela inteira).
  • Linhas do query builder não passam pelos casts: ids BIGINT chegam como string.
  • QueryBuilder.raw(sql, bindings) executa SQL livre.

Transações

local Database = require("crescent.database")

local user, err = Database.transaction(function(tx)
    local user = assert(User:create({ name = "Ada", email = "ada@example.com" }, tx))
    tx:execute("INSERT INTO audit (user_id) VALUES (?)", { user.id })
    return user
end)
  • Faz COMMIT quando a função retorna normalmente e ROLLBACK quando ela lança erro, retorna false ou nil, err.
  • Passe tx como último argumento para models e query builder (User:create(attrs, tx), QueryBuilder.table("users"):get(tx)), senão eles usam outra conexão, fora da transação.
  • tx:transaction(fn) aninhado usa SAVEPOINT.

Migrations

lua cli.lua make:migration create_orders_table     # CREATE TABLE orders
lua cli.lua make:migration add_total_to_orders     # ALTER TABLE orders
lua cli.lua db:migrate                             # aplica as pendentes
lua cli.lua db:status                              # lista o que rodou
lua cli.lua db:rollback                            # desfaz o último lote (batch)

Cada migration retorna up e down, que devolvem uma string SQL ou uma lista delas:

return {
    up = function(db)
        return {
            [[CREATE TABLE `orders` (
                `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
                `user_id` BIGINT UNSIGNED NOT NULL,
                `total` DECIMAL(10,2) NOT NULL,
                `created_at` TIMESTAMP NULL,
                `updated_at` TIMESTAMP NULL
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4]],
            "CREATE INDEX `orders_user_id` ON `orders` (`user_id`)",
        }
    end,
    down = function(db)
        return "DROP TABLE `orders`"
    end,
}
  • Os arquivos rodam em ordem de nome e ficam registrados na tabela migrations. Cada execução de db:migrate forma um lote.
  • O arquivo gerado por make:migration deduz a tabela do nome (create_<tabela> ou add_x_to_<tabela>) e traz colunas de exemplo: revise antes de rodar.
  • DDL do MySQL faz commit implícito: migrations não rodam em transação. Se uma migration com vários comandos falhar no meio, ela fica parcialmente aplicada e sem registro. Prefira um comando de schema por migration.

Seeders

lua cli.lua make:seeder 01_admin_user   # cria seeds/01_admin_user.lua
lua cli.lua db:seed                     # roda todos, em ordem de nome
lua cli.lua db:seed 01_admin_user       # só um
-- seeds/01_admin_user.lua
local User = require("src.users.models.user")

return function(db)
    if not User:where("email", "admin@example.com"):first(db) then
        assert(User:create({ name = "Admin", email = "admin@example.com" }, db))
    end
end

Cada seeder roda em uma transação (erro ou return false desfaz). Não há registro de execução, então escreva seeders idempotentes, como acima.

Referência completa (adaptador, bindings, testes com banco falso): docs/database.md do framework.


Autenticação

crescent.middleware.auth traz middlewares para JWT, Bearer, Basic e API key. Em caso de sucesso eles colocam o usuário em ctx.state.user; em caso de falha respondem 401 sem chamar a action.

local auth = require("crescent.middleware.auth")

-- uma rota
app:get("/me", auth.protect(auth.jwt(), function(ctx)
    return ctx:json(200, ctx.state.user)
end))

-- todas as rotas registradas depois
app:use(auth.jwt())

auth.jwt() lê o segredo de JWT_SECRET (mínimo de 32 bytes; gere com openssl rand -base64 48). Sem ele, o app falha ao iniciar.

Middleware Uso
auth.jwt(opções) JWT de acesso no header Authorization: Bearer; define também ctx.state.jwt (payload)
auth.bearer(fn) token opaco; fn(token, ctx) retorna true, usuário ou false, "mensagem"
auth.basic(fn, { realm = "Admin" }) HTTP Basic; fn(usuário, senha, ctx)
auth.api_key("X-Api-Key", fn) chave em um header; fn(chave, ctx)
auth.protect(middleware, action) aplica um middleware (ou uma lista) a uma action

Opções de auth.jwt: secret, issuer, audience, algorithms (padrão { "HS256" }), leeway, optional = true (não bloqueia; só preenche o usuário se o token for válido) e get_user:

app:use(auth.jwt({
    get_user = function(payload, ctx)
        return User:find(payload.user_id)   -- nil → 401
    end,
}))

API key e Basic:

app:get("/internal", auth.protect(auth.api_key("X-Api-Key", function(key, ctx)
    if auth.secure_compare(key, os.getenv("INTERNAL_KEY") or "") then
        return true, { name = "servico-interno" }
    end
    return false, "invalid api key"
end), internal_action))

Use auth.secure_compare(a, b) para comparar segredos (tempo constante).


Login com JWT

local auth = require("crescent.middleware.auth")
local password = require("crescent.security.password")
local User = require("src.users.models.user")

app:post("/auth/login", app:validated({
    email = { required = true, email = true },
    password = { required = true },
}, function(ctx)
    local user = User:where("email", ctx.body.email):first()
    if not user or not password.verify(ctx.body.password, user.password) then
        return ctx:error(401, "invalid credentials", nil, "invalid_credentials")
    end
    return auth.generate_token_pair(user)
    -- { access_token, refresh_token, token_type = "Bearer", expires_in, refresh_expires_in }
end))

app:post("/auth/refresh", function(ctx)
    local ok, payload = auth.verify_refresh_token(ctx.body.refresh_token)
    if not ok then return ctx:error(401, "invalid token", nil, "invalid_token") end
    auth.revoke_token(payload)   -- o refresh token antigo deixa de valer
    return auth.generate_token_pair(payload.user_id)
end)

app:post("/auth/logout", auth.protect(auth.jwt(), function(ctx)
    auth.revoke_token(ctx.state.jwt)
    return ctx:no_content()
end))
  • O access token dura 15 minutos e o refresh token 30 dias (access_expires_in e refresh_expires_in, em segundos, mudam isso). O payload leva user_id, name e email.
  • auth.jwt() recusa refresh tokens; verify_refresh_token aceita só refresh tokens.
  • Tokens revogados ficam no lua_shared_dict crescent_jwt (compartilhado entre workers, já declarado no nginx.conf) até expirarem. O dict é perdido ao reiniciar o Nginx e não é compartilhado entre servidores.

Para assinar e verificar diretamente, use crescent.security.jwt:

local jwt = require("crescent.security.jwt")

local token = jwt.sign({ user_id = 1 }, secret, { expires_in = 900, issuer = "api" })
local ok, payload_or_message, code = jwt.verify(token, secret, { issuer = "api" })

Algoritmos HS256/HS384/HS512; o algoritmo é fixado por quem verifica (algorithms), nunca pelo token, e none nunca é aceito.


Senhas

local password = require("crescent.security.password")

local hash = password.hash("s3cr3t")          -- "600000$<salt>$<hash>"
password.verify("s3cr3t", hash)               -- true
password.needs_rehash(hash)                   -- true se as iterações mudaram

PBKDF2-HMAC-SHA256 com 600.000 iterações (recomendação OWASP), executado pelo OpenSSL. Cada hash leva dezenas de milissegundos e ocupa o worker: aplique rate limit no login. PASSWORD_HASH_ITERATIONS ajusta o padrão. Hashes gerados pelo Crescent 1.x continuam válidos.


CORS

Registre o CORS antes da autenticação, com app:use, para que o preflight (OPTIONS) seja respondido antes de exigir credenciais:

local cors = require("crescent.middleware.cors")

app:use(cors.create({
    origins = { "https://app.example.com" },   -- ou "*", ou function(origin, ctx)
    methods = { "GET", "POST", "PUT", "DELETE" },
    allowed_headers = { "Content-Type", "Authorization" },
    credentials = true,
    max_age = 600,
}))
  • O preflight é respondido com 204 pelo próprio middleware; não crie rotas OPTIONS.
  • cors.strict({ "https://app.example.com" }) liga credenciais, cache de preflight de 24 h e responde 403 a outras origens.
  • credentials = true com origins = "*" é recusado.

Headers de segurança

app:use(Crescent.middleware.security_headers.create({
    hsts = true,                                         -- só se o site for 100% HTTPS
    csp = "default-src 'self'; frame-ancestors 'none'",
}))

Sem opções, envia X-Content-Type-Options: nosniff, X-Frame-Options: DENY e Referrer-Policy: strict-origin-when-cross-origin (o app.lua gerado já registra esse middleware). Outras opções: frame_options, referrer_policy, permissions_policy, cross_origin_opener_policy e headers (extras; false remove um header).


Rate limit

local rate_limit = require("crescent.middleware.rate_limit")

app:use(rate_limit.create({ limit = 100, window = 60 }))   -- 100 req/min por IP

app:post("/auth/login", auth.protect(
    rate_limit.create({ limit = 5, window = 60, prefix = "rl:login:" }), login))
  • Janela fixa no lua_shared_dict crescent_limits, compartilhada entre workers.
  • Acima do limite: 429 rate_limited com Retry-After. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.
  • Use um prefix diferente para cada limitador.
  • A chave padrão é o IP (ctx.remote_addr). Atrás de proxy, configure o realip do Nginx (veja Deploy); nunca use o X-Forwarded-For cru como chave. key = function(ctx) ... end personaliza; retornar nil isenta a requisição.

Cookies

ctx:set_cookie("theme", "dark", { max_age = 3600 })
ctx:cookie("theme")                         -- "dark"
ctx:clear_cookie("theme")                   -- mesmo path/domain usados no set

ctx:set_cookie("uid", tostring(user.id), { signed = true })
ctx:signed_cookie("uid")                    -- nil se ausente ou adulterado
Opção Padrão
path "/"
max_age / expires cookie de sessão
http_only true
secure true fora de debug
same_site "Lax" ("Strict", "Lax" ou "None"; None exige secure)
domain, signed —

Cookies assinados, sessões e CSRF usam o segredo APP_KEY (ou secret_key na config), com no mínimo 32 caracteres: openssl rand -base64 48. Para trocar a chave sem invalidar tudo, mova a antiga para secret_key_fallbacks.


Sessões

local session = require("crescent.middleware.session")

app:use(session.create())   -- cookie criptografado (AES-256-GCM), 24 h, expira após 1 h sem uso
app:post("/login", function(ctx)
    local user = authenticate(ctx.body.email, ctx.body.password)
    if not user then
        ctx.session:flash("error", "credenciais inválidas")
        return ctx:redirect("/login")
    end
    ctx.session:regenerate()              -- sempre após login (evita session fixation)
    ctx.session:set("user_id", user.id)
    return ctx:redirect("/")
end)

app:post("/logout", function(ctx)
    ctx.session:destroy()
    return ctx:redirect("/")
end)
Método Efeito
get(k), set(k, v), delete(k) valores (serializáveis em JSON)
flash(k, v) / get_flash(k) valor disponível só na próxima requisição
regenerate() nova sessão com os mesmos dados
destroy() apaga a sessão e expira o cookie
clear(), is_new() limpa os valores; sessão criada nesta requisição
Opção Padrão
store "cookie" "shared" guarda os dados no lua_shared_dict crescent_sessions e o cookie leva só um id
name "crescent_session" nome do cookie
max_age / idle_timeout 86400 / 3600 segundos; false desativa
cookie { path = "/", same_site = "Lax", http_only = true } opções do cookie

O store cookie não guarda estado no servidor, mas tem limite de 4 KB (guarde ids, não objetos) e um cookie copiado continua válido até expirar. O store shared invalida a sessão de verdade no destroy, porém é perdido ao reiniciar o Nginx e não é compartilhado entre servidores.


CSRF

Formulários com login por cookie precisam de proteção CSRF. Registre o middleware depois da sessão:

local session = require("crescent.middleware.session")
local csrf = require("crescent.middleware.csrf")

app:use(session.create())
app:use(csrf.create({
    skip = function(ctx) return ctx:get_bearer() ~= nil end,   -- APIs com bearer token
}))

Nos templates, inclua o campo com <%- (sem escape, pois é HTML):

<form method="post" action="/posts">
  <%- csrf_field() %>
  <input name="title">
  <button>Salvar</button>
</form>

<meta name="csrf-token" content="<%= csrf_token() %>">

Requisições POST, PUT, PATCH e DELETE precisam enviar o token no campo _csrf ou no header X-CSRF-Token (para AJAX, leia a meta tag). Sem token válido: 403 csrf_invalid.

  • Protegido contra BREACH: o segredo de 256 bits fica na sessão e nunca aparece numa resposta. csrf_token() devolve o segredo mascarado com uma máscara aleatória nova a cada requisição, então páginas comprimidas não repetem os bytes do segredo. Qualquer token mascarado do segredo atual é aceito (várias abas funcionam).
  • ctx.session:regenerate() no login troca o segredo: tokens obtidos antes do login deixam de valer.

Uploads

Requisições multipart/form-data são lidas em streaming: os campos de texto vão para ctx.body e os arquivos para ctx.files, gravados em arquivos temporários.

app:post("/avatar", function(ctx)
    local file = ctx.files.avatar   -- { filename, content_type, size, path, field }
    if not file then return ctx:error(422, "avatar obrigatório", nil, "avatar_required") end
    if file.content_type ~= "image/png" then
        return ctx:error(422, "apenas PNG", nil, "invalid_type")
    end
    local path, err = ctx:save_upload(file, "avatars/" .. ctx.state.user.id .. ".png", { overwrite = true })
    if not path then return ctx:error(500, "falha ao salvar", nil, "upload_failed") end
    return ctx:json(201, { path = path })
end)

Configure o destino e os limites na config da aplicação:

upload_root = "storage",              -- única pasta em que save_upload grava (relativa ao projeto)
upload = {
    max_file_size = 10 * 1024 * 1024,
    max_files = 10,
    max_total_size = 50 * 1024 * 1024,
},
  • Temporários não salvos com ctx:save_upload são apagados ao fim da requisição.
  • filename e content_type vêm do cliente: valide o conteúdo e gere você o nome final. Caminhos com .. ou fora de upload_root são recusados.
  • Ajuste também client_max_body_size no nginx.conf.
Situação Status Código
arquivo, campo ou total acima do limite 413 upload_too_large
arquivos ou campos demais 413 too_many_files, too_many_fields
multipart inválido 400 malformed_multipart

Códigos de erro

Código Status Origem
missing_credentials 401 header de autenticação ausente
invalid_token, invalid_credentials 401 token ou credenciais inválidos
token_expired, token_revoked 401 JWT expirado ou revogado
csrf_invalid 403 token CSRF ausente ou errado
cors_origin_not_allowed 403 origem fora da lista (preflight ou cors.strict)
rate_limited 429 limite excedido

Referência completa: security.md e web.md do framework.


Usando a CLI

A CLI vem dentro do projeto. Rode-a da raiz do projeto com lua cli.lua:

lua cli.lua <comando> [argumentos]
lua cli.lua help

Geradores, new, server e test rodam no Lua comum (5.1 a 5.4 ou LuaJIT). Comandos que precisam do OpenResty (db:*, queue:*, cache:clear e routes) são repassados automaticamente para bin/crescent, que roda no mesmo LuaJIT do OpenResty que atende as requisições (via resty). bin/crescent <comando> aceita os mesmos comandos e é o que se usa no Docker: docker compose exec app bin/crescent <comando>.

A CLI lê o .env da raiz do projeto (variáveis do ambiente têm prioridade). A saída é colorida no terminal; NO_COLOR=1 desliga as cores.

Variável Uso
RESTY_BIN caminho do resty, se não estiver em um local padrão
OPENRESTY_BIN caminho do openresty, usado por server
APP_ENV ambiente carregado (config/<APP_ENV>.lua)

Códigos de saída: 0 sucesso, 1 falha, 2 comando desconhecido.


Servidor e rotas

Comando Descrição
server start inicia o OpenResty com o nginx.conf do projeto (porta 8080)
server stop para de forma graciosa
server reload recarrega configuração e código
server status mostra se está rodando e o pid
routes lista as rotas: método, caminho e nome

Opções de server: --conf <arquivo> escolhe outra configuração do Nginx e --env <nome> define o APP_ENV:

lua cli.lua server start --conf conf/nginx.production.conf --env production

Erros de inicialização vão para logs/error.log.


Desenvolvimento com Docker

Comando Descrição
setup Prepara o projeto, perguntando antes de cada passo: (1) git — recomeça o histórico do zero (git init, branch main, commit inicial) sem o remote do template e, opcionalmente, adiciona o seu remote e faz o push; (2) banco — usuário e senha do MySQL do Docker gravados no .env (senha vazia = gerada; DB_ROOT_PASSWORD aleatória); (3) cache e filas — memória do servidor (shared) ou Redis (COMPOSE_PROFILES=redis, CACHE_DRIVER/QUEUE_DRIVER=redis e REDIS_PASSWORD aleatória; veja Cache e filas); (4) Docker — sobe a aplicação com run.
run [--logs] docker compose up -d, espera o /health responder e mostra as URLs. O código fica montado no container com lua_code_cache off: alterações em src/, views/ e app.lua valem na próxima requisição. --logs acompanha os logs da aplicação.
rerun [--logs] [--fresh] Reconstrói a imagem e reinicia (up -d --build, com cache): use depois de mudar Dockerfile, dependências (deps.sh) ou configuração do Nginx. --fresh reconstrói sem cache.
stop docker compose down (inclusive redis e worker): para os containers e mantém os volumes (banco, Redis e uploads).

Se o volume do MySQL já existe, o setup avisa: o MySQL só lê usuário e senha ao criar o volume (docker compose down -v recria, apagando os dados do banco do Docker). O setup se recusa a rodar no repositório do próprio framework.


Geradores

Os geradores nunca sobrescrevem arquivos e mostram cada arquivo criado (✓ Controller src/...). BlogPost e blog-post viram blog_post em nomes de arquivo e BlogPost no código. Quando o módulo é omitido, ele recebe o próprio nome.

Comando Cria
make:module <nome> módulo CRUD completo em src/<nome>/, teste e migration (veja abaixo)
make:controller <nome> [módulo] src/<módulo>/controllers/<nome>.lua
make:service <nome> [módulo] src/<módulo>/services/<nome>.lua
make:model <nome> [módulo] src/<módulo>/models/<nome>.lua
make:routes <nome> [módulo] src/<módulo>/routes/<nome>.lua
make:middleware <nome> [módulo] src/middleware/<nome>.lua (ou dentro do módulo)
make:job <nome> [módulo] src/<módulo>/jobs/<nome>.lua: job de fila com handle(payload, job) e failed
make:test <nome> tests/test-<nome>.lua
make:migration <nome> migrations/AAAAMMDDHHMMSS_<nome>.lua
make:seeder <nome> seeds/<nome>.lua (prefixe com 01_ para definir a ordem)
new <nome> novo projeto em ./<nome> (a partir do repositório do framework)

Nomes começam com letra e usam letras, números, _ ou -. Migrations usam só letras, números e _; seeders também podem começar com número (01_admin_user). make:action (nome do 2.0.0) continua funcionando como alias de make:controller.

make:migration deduz a tabela do nome: create_products_table (ou create_products) gera um CREATE TABLE products; add_price_to_products, remove_x_from_products e alter_products_table geram um esqueleto de ALTER TABLE products.

make:module

Todo módulo segue a mesma estrutura (a do Crescent 1.x):

src/<módulo>/
  init.lua          Module.register(app)
  controllers/      recebem ctx, chamam services e respondem (ctx:json, ctx:view, ctx:error)
  services/         regras de negócio, sem ctx (fáceis de testar)
  models/           Model:extend({ table, fillable, validates, ... })
  routes/           function(app, prefix) com rotas nomeadas
lua cli.lua make:module Product
🌙 Creating module Product

✓ Module      src/product/init.lua
✓ Controller  src/product/controllers/product.lua
✓ Service     src/product/services/product.lua
✓ Model       src/product/models/product.lua
✓ Routes      src/product/routes/product.lua
✓ Test        tests/test-product-module.lua
✓ Migration   migrations/20261117140952_create_products_table.lua

ℹ Register the module in app.lua:
    require("src.product").register(app)
ℹ Then create the table and run the module test:
    lua cli.lua db:migrate
    lua cli.lua test product

O controller traz index, show, store, update, destroy e o schema de validação; o service traz page, find, create, update e delete. Para acrescentar peças a um módulo existente, passe o módulo: lua cli.lua make:controller Report product. As rotas geradas estão em Primeiro módulo.


Banco de dados

Comando Alias Descrição
db:migrate migrate aplica as migrations pendentes
db:rollback migrate:rollback desfaz o último lote de migrations
db:status migrate:status lista migrations (ran, pending ou missing) e lote
db:seed [nome] — roda todos os seeders, ou só um

Os comandos usam config.database do ambiente atual (APP_ENV). Detalhes em Migrations e Seeders.


Filas e cache

Os comandos de fila exigem QUEUE_DRIVER=redis: com o driver shared a fila vive na memória do servidor, que a CLI não alcança. Detalhes em Cache e filas.

Comando Descrição
queue:work [--queue=a,b] [--once] processa jobs; --sleep, --max-jobs, --max-time, --stop-when-empty; logs JSON no stdout
queue:status [fila] contagem de ready, delayed, reserved e failed
queue:failed [fila] últimos jobs que falharam (--limit=20)
`queue:retry <id\ all> [--queue=]` reenfileira jobs que falharam, com as tentativas zeradas
queue:clear-failed [fila] apaga os jobs que falharam
cache:clear apaga as chaves do prefixo do cache (Redis)

Testes

lua cli.lua test             # todos os arquivos tests/test*.lua
lua cli.lua test product     # só os que contêm "product" no nome
lua cli.lua test:http        # tests/test-http.sh contra um OpenResty real
./test.sh                    # test + test:http

Cada arquivo roda no resty. A saída mostra cada teste (✓/✗ com a mensagem de erro) e, no fim, um resumo com arquivos, testes, tempo e a lista dos arquivos que falharam:

🌙 Test summary

  Files:  3 run, 3 passed, 0 failed
  Tests:  5 run, 5 passed, 0 failed
  Time:   0s

✅ All tests passed! (3/3 files)
``` Os testes usam `crescent.utils.tests` e podem chamar a aplicação sem servidor, com `app:handle`:

```lua
package.path = "./?.lua;./?/init.lua;" .. package.path

local tests = require("crescent.utils.tests")
local Crescent = require("crescent")
local json = require("crescent.json")

local function greets_by_name()
    local app = Crescent.new({ environment = "test", debug = true, root = ".", logger = function() end })
    require("src.hello").register(app)

    local writer = { headers = {} }
    app:handle({ method = "GET", path = "/api/hello", headers = {}, query = { name = "Ada" } }, writer)

    tests.assertEquals(writer.status, 200)
    tests.assertEquals(json.decode(writer.body).message, "Hello, Ada!")
end

assert(tests.runSuite("Hello", { greets_by_name = greets_by_name }))

Asserções disponíveis: assertEquals, assertNotEquals, assertTrue, assertFalse, assertNil, assertNotNil, assertType, assertContains, assertNotContains, assertMatches, assertTableEquals, assertError, assertNoError.

test:http roda tests/test-http.sh: projetos novos trazem um teste que sobe o OpenResty com APP_ENV=test na porta 8080, confere /health, / e /api/hello com curl e para o servidor. Acrescente suas rotas com a função expect <status> <caminho> [texto].


Cliente HTTP

crescent.http_client faz requisições de saída sem bloquear o worker (sobre lua-resty-http):

local HttpClient = require("crescent.http_client")

local api = HttpClient.new({
    base_url = "https://api.example.com/v1",
    timeout = 5,                                   -- segundos (padrão 30)
    headers = { Authorization = "Bearer " .. token },
})

app:get("/repos", function(ctx)
    local res, err = api:get("/repos", { params = { page = 2 } })
    if not res then
        return ctx:error(502, "upstream failed", ctx.debug and err.message or nil, "upstream_error")
    end
    return ctx:json(200, res.data)
end)
  • Métodos: get(url, config), delete, head, options, e post(url, dados, config), put, patch.
  • Uma tabela em dados é enviada como JSON; uma string vai como está.
  • A resposta é { status, headers, body, data }; data é o JSON já decodificado (ou o corpo bruto).
  • Falhas de rede e status >= 400 retornam nil, err, com err.message e, quando houve resposta, err.status e err.data.
  • TLS é verificado por padrão, redirecionamentos não são seguidos e respostas acima de 10 MiB são abortadas (max_response_size).
  • Para chamadas avulsas: HttpClient.get(url).

O Nginx resolve DNS e verifica certificados para o Lua: os nginx.conf gerados já trazem resolver e lua_ssl_trusted_certificate. Sem eles, nomes não resolvem e conexões HTTPS falham. O cliente funciona em controllers, middlewares e timers, mas não em init_by_lua.


E-mail

crescent.mail envia por SMTP (com STARTTLS) sobre lua-resty-mail. Os dados do servidor vêm das variáveis SMTP_SERVER, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM e SMTP_FROM_NAME, ou podem ser passados em Mail.new({ server, port, user, password, from, from_name }):

local Mail = require("crescent.mail")

local mailer = Mail.new()

local ok, err = mailer:send({
    to = { "ada@example.com", { email = "grace@example.com", name = "Grace" } },
    subject = "Bem-vinda",
    text = "Olá!",
    html = "<p>Olá!</p>",
})
if not ok then ctx.state.log:error("falha no e-mail", { error = err }) end
  • Também aceita cc, bcc e reply_to.
  • Atalhos: send_text(para, assunto, texto), send_html(para, assunto, html) e send_template(para, assunto, "emails/welcome.etlua", dados), que renderiza um template de views/.
  • Porta 465 usa TLS direto; as demais usam STARTTLS.
  • Envie fora do caminho crítico quando possível: o envio espera a resposta do servidor SMTP.

Logs

crescent.logger grava uma linha JSON por entrada no error log do Nginx (no Docker, em stderr). Campos sensíveis são mascarados automaticamente:

local Logger = require("crescent.logger")

local log = Logger.new({ level = "info", fields = { service = "api" } })
log:info("login", { user_id = 7, password = "x" })
-- {"level":"info","msg":"login","service":"api","user_id":7,"password":"[REDACTED]"}

log:with({ request_id = ctx.request_id }):warn("cota excedida")
  • Níveis: debug, info, warn, error; entradas abaixo de level são ignoradas.
  • Mascarados (por substring no nome do campo): password, passwd, secret, token, authorization, cookie, api_key, credit_card, card_number, cvv, private_key. Acrescente outros com Logger.new({ redact = { "cpf" } }).
  • Logger.redact(tabela, { "cpf" }) devolve uma cópia mascarada.

Log por requisição

O app.lua gerado registra request_log, que grava uma entrada por requisição com método, caminho, rota, status, duração, IP, user_id (de ctx.state.user) e request id. Status 5xx saem como error e 4xx como warn.

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

-- nos controllers, um logger já com o request id:
ctx.state.log:info("pedido criado", { order_id = order.id })

Todo erro 500 também é registrado pela aplicação com request id, método e caminho. Para usar seu próprio logger nesses registros: Crescent.new({ logger = Logger.new({ level = "warn" }) }).


JSON

crescent.json envolve o cjson com a política do framework:

local json = require("crescent.json")

json.encode({ ok = true })            -- '{"ok":true}'
json.decode('{"items":[]}')           -- items continua lista ao reenviar
json.array({})                        -- força [] em vez de {}

Tabelas vazias viram {} em JSON. Para listas que podem estar vazias na resposta, use json.array(lista). Barras não são escapadas ("/a" em vez de "\/a").


Health e readiness

crescent.health registra dois endpoints (o projeto gerado já faz isso em src/health):

require("crescent.health").register(app, {
    service = "api",
    checks = {
        database = require("crescent.health").checks.database,
        cache = function(ctx) return redis_ping() end,   -- true, ou nil e erro
    },
})
Endpoint Resposta
GET /health 200 enquanto o worker responde; não consulta dependências
GET /ready 200 se todos os checks passam, 503 caso contrário, com status e duração de cada check

Sem checks, /ready verifica o banco (SELECT 1) quando há um configurado e o Redis (PING) quando algum driver de cache ou fila usa Redis. Mensagens de erro dos checks só aparecem na resposta com debug = true; sempre vão para o log. Use /health para reiniciar o processo e /ready para o balanceador decidir se envia tráfego.


Configuração

crescent.cache e crescent.queue funcionam sem nenhum serviço extra, na memória compartilhada do OpenResty (lua_shared_dict). O Redis é opcional e entra quando você precisa de durabilidade ou de mais de um servidor. O lua-resty-redis já vem com o OpenResty, então não há dependência nova.

Driver Cache Fila Quando usar
shared (padrão) memória dos workers de um servidor, LRU jobs executados dentro do próprio OpenResty um servidor, jobs que podem se perder num restart (e-mails de boas-vindas, webhooks com retry do lado de lá)
redis compartilhado entre servidores, sobrevive a restart durável, worker separado (queue:work) mais de uma instância, jobs que não podem se perder
sync — executa o job dentro do push() testes e scripts

config/<env>.lua (os projetos novos já vêm com isso):

redis = {
    host = Env.get("REDIS_HOST", "127.0.0.1"),
    port = Env.number("REDIS_PORT", 6379),
    password = Env.get("REDIS_PASSWORD"),
    database = Env.number("REDIS_DB", 0),
},
cache = {
    driver = Env.get("CACHE_DRIVER", "shared"),
    prefix = "minha_app:cache:",
    ttl = 3600,                       -- padrão em segundos; 0 = sem expiração
},
queue = {
    driver = Env.get("QUEUE_DRIVER", "shared"),
    prefix = "minha_app:queue:",
    attempts = 3,                     -- padrões; cada job pode sobrescrever
    backoff = { 10, 60, 300 },        -- segundos entre tentativas (número ou lista)
    timeout = 60,                     -- após isso o job volta para a fila (redis)
    workers = {
        embedded = nil,               -- padrão: true com "shared", false com "redis"
        concurrency = 1,              -- loops por worker do nginx
        queues = { "default" },       -- ordem = prioridade
        sleep = 1,                    -- segundos entre consultas quando vazia
    },
},

O cliente Redis só é criado quando algum driver é redis (ou com redis.enabled = true). Nesse caso o /ready também verifica o Redis.

Os lua_shared_dict crescent_cache e crescent_queue e as variáveis REDIS_*, CACHE_DRIVER e QUEUE_DRIVER já estão em nginx.conf e conf/*.conf.


Cache: ctx.cache

ctx.cache:set("user:1", user, 300)          -- tabelas, strings, números, booleanos (JSON)
ctx.cache:get("user:1")                     -- valor ou nil
ctx.cache:get("user:1", default)
ctx.cache:add("lock:import", true, 60)      -- só grava se não existir -> true/false
ctx.cache:has("user:1")
ctx.cache:delete("user:1")                  -- alias: forget
ctx.cache:pull("token")                     -- lê e apaga
ctx.cache:incr("visits")                    -- contador atômico; incr(key, n, ttl), decr
ctx.cache:flush()                           -- shared: limpa o dict; redis: só as chaves do prefixo

local stats = ctx.cache:remember("stats", 60, function()
    return StatsService.compute(ctx.db)
end)
  • remember evita stampede: só um chamador calcula por vez. Os outros esperam

até lock_wait segundos (padrão 5) pelo valor e só então calculam por conta própria. Um resultado nil não é guardado, e erros da função propagam.

  • Falha do backend nunca lança erro. get devolve nil, err (cache miss) e

remember recalcula. Uma queda do Redis deixa a app mais lenta, mas ela continua funcionando.

  • nil não pode ser cacheado; set com função ou userdata lança erro.

Filas: ctx.queue

Um job é um módulo Lua com handle(payload, job). O nome do job é o caminho do módulo, então qualquer processo consegue carregá-lo sem registro:

lua cli.lua make:job send_welcome users     # src/users/jobs/send_welcome.lua
-- src/users/jobs/send_welcome.lua
local SendWelcome = {
    queue = "mail",          -- opcionais: padrões vindos de config.queue
    attempts = 5,
    backoff = { 30, 120 },
    timeout = 120,
}

function SendWelcome.handle(payload, job)
    local user = User:find(payload.user_id)
    if not user then return end                     -- nada a fazer: sucesso
    local ok, err = Mail.new():send({ to = user.email, subject = "Bem-vindo", text = "..." })
    if not ok then error(err) end                   -- ou `return false, err`: tenta de novo
end

-- Opcional: roda depois da última tentativa.
function SendWelcome.failed(payload, err, job)
    job.log("error", "boas-vindas não enviadas", { user_id = payload.user_id })
end

return SendWelcome
ctx.queue:push("src.users.jobs.send_welcome", { user_id = user.id })
ctx.queue:push("src.users.jobs.send_welcome", { user_id = user.id }, {
    delay = 60, queue = "mail", attempts = 3, backoff = 10, timeout = 30,
})

push devolve o id do job (ou nil, err se o backend falhar). Ele lança erro se o job não existir, se o payload não for serializável em JSON ou se as opções forem inválidas.

O segundo argumento do handle traz id, name, queue, attempts, max_attempts, db, cache, config, app, dispatch(name, payload, options) (para enfileirar outro job) e log(level, message, fields).

Entrega pelo menos uma vez. Um job pode rodar de novo se o worker morrer ou se passar do timeout. Escreva handlers idempotentes, por exemplo checando se o e-mail já foi enviado antes de enviar. O timeout precisa ser maior que a execução mais longa do job. Com Redis, se o job passar do timeout, ele volta para a fila e outro worker o pega.

Onde os jobs rodam

  • Workers embutidos (padrão com shared): o init_worker_by_lua dos confs

chama app:start_workers(), que inicia concurrency loops em cada worker do nginx, sem processo extra. Os jobs rodam no mesmo processo que atende as requisições, então jobs pesados de CPU competem com elas.

  • Worker dedicado (padrão com redis): lua cli.lua queue:work, ou o

serviço worker do Docker. Escale rodando mais processos.

Em desenvolvimento (debug = true) o worker recarrega os módulos src.* a cada job, então editar um job não exige reiniciar nada.

Comandos (driver redis)

lua cli.lua queue:work [--queue=mail,default] [--once] [--sleep=1]
                       [--max-jobs=N] [--max-time=S] [--stop-when-empty]
lua cli.lua queue:status [fila]             # ready / delayed / reserved / failed
lua cli.lua queue:failed [fila] [--limit=20]
lua cli.lua queue:retry <id|all> [--queue=fila]
lua cli.lua queue:clear-failed [fila]
lua cli.lua cache:clear

Com o driver shared a fila vive na memória do servidor, que a CLI não alcança. Os mesmos dados estão disponíveis no código via app.queue:size(name), :failed(name), :retry(name, id) e :clear_failed(name).


Docker

O docker-compose.yml traz os serviços redis (com AOF, senha via REDIS_PASSWORD) e worker no profile redis. Eles ficam desligados até você ligar o profile no .env:

COMPOSE_PROFILES=redis
CACHE_DRIVER=redis
QUEUE_DRIVER=redis
REDIS_PASSWORD=uma-senha-longa

O lua cli.lua setup pergunta "Use Redis for cache and queues?" e grava isso para você. Depois, lua cli.lua run sobe app + MySQL + Redis + worker e docker compose logs -f worker mostra os jobs em JSON. Dentro do compose, REDIS_HOST aponta para o serviço redis; fora dele, use 127.0.0.1:${REDIS_FORWARD_PORT:-6380}.

Em produção, rode a mesma imagem com command: ["bin/crescent", "queue:work"] para os workers e deixe QUEUE_DRIVER=redis em todos os containers. Veja Deploy.


Redis direto

local redis = ctx.redis          -- ou require("crescent.redis").new(config.redis)
redis:command("hset", "k", "f", "v")
redis:eval("return redis.call('get', KEYS[1])", { "k" })
redis:with(function(red)          -- conexão do pool, para pipelines
    red:init_pipeline()
    red:incr("a"); red:incr("b")
    return red:commit_pipeline()
end)

Testes

config/test.lua usa queue.driver = "sync": push executa o job na hora e os erros dele aparecem no teste. O cache shared funciona nos testes (o lua cli.lua test cria os dicts crescent_cache e crescent_queue).


Imagem Docker

O Dockerfile do projeto gera a imagem de produção:

docker build -t meu-app .

docker run -d -p 8080:8080 \
  -e APP_ENV=production \
  -e DB_HOST=db.interno -e DB_NAME=meu_app -e DB_USER=meu_app -e DB_PASSWORD=... \
  -e APP_KEY=... -e JWT_SECRET=... \
  -e RUN_MIGRATIONS=true \
  meu-app

O que a imagem faz:

  • Parte de openresty/openresty:*-alpine-fat e instala as dependências Lua em uma camada própria.
  • Roda como o usuário sem privilégios crescent; só logs/, tmp/ e storage/ são graváveis. Uploads vão para storage/ (upload_root = "storage"): monte um volume nesse caminho para que sobrevivam a novos containers (o docker-compose.yml de desenvolvimento já usa o volume app-storage).
  • Usa conf/nginx.docker.conf: cache de código ligado, worker_processes auto, app construído no init_by_lua e logs em stdout/stderr.
  • Tem HEALTHCHECK em /health.
  • Com RUN_MIGRATIONS=true, o entrypoint roda bin/crescent db:migrate antes de subir (até 10 tentativas, a cada 3 s, enquanto o banco não responde). O padrão da imagem é false.

Para rodar um comando avulso com a mesma imagem, passe-o como argumento:

docker run --rm --env-file prod.env meu-app bin/crescent db:migrate

Com várias réplicas, prefira rodar as migrations uma vez, num passo do deploy, em vez de RUN_MIGRATIONS=true em todas.


Docker Compose (desenvolvimento)

O docker-compose.yml é para desenvolvimento:

cp .env.example .env
docker compose up --build
  • Sobe a app e um MySQL 8.4 (exposto só em 127.0.0.1:3307; dados no volume mysql-data).
  • Usa conf/nginx.docker-dev.conf: um worker e lua_code_cache off, com o código montado em /app para recarga automática.
  • Roda as migrations pendentes ao subir e cria o banco de testes (DB_TEST_NAME) na primeira inicialização do volume.
  • APP_PORT muda a porta no host. As senhas do .env.example são só para desenvolvimento.
  • Com COMPOSE_PROFILES=redis no .env, sobem também um Redis 7.4 (AOF ligado, senha REDIS_PASSWORD, exposto em 127.0.0.1:6380, dados no volume redis-data) e o serviço worker (bin/crescent queue:work). Veja Cache e filas.

Não use esse arquivo em produção: ele monta o código-fonte e desliga o cache de código.


Sem Docker

Instale OpenResty, LuaRocks e as dependências (./deps.sh) no servidor e use conf/nginx.production.conf (revise antes):

APP_ENV=production openresty -p /srv/app/ -c conf/nginx.production.conf

# ou, de dentro do projeto
bin/crescent server start --conf conf/nginx.production.conf --env production
  • -p é a raiz do projeto (com / no final): caminhos relativos, .env, logs/ e o lua_package_path partem dela.
  • O arquivo traz user nobody; (só tem efeito quando o master roda como root), worker_processes auto, lua_code_cache on, access log em JSON e timeouts de cliente.
  • O init_by_lua_block { require("app") } constrói o app no master: um erro de configuração faz o start ou o reload falhar, em vez de quebrar a primeira requisição.
  • Deploy de código novo: atualize os arquivos e rode openresty -p /srv/app/ -c conf/nginx.production.conf -s reload (ou bin/crescent server reload --conf conf/nginx.production.conf).
  • O caminho do bundle de CAs (lua_ssl_trusted_certificate) é o do Debian/Ubuntu; ajuste em outras distribuições.

Use o supervisor do seu sistema (systemd, por exemplo) para iniciar o OpenResty no boot e repassar as variáveis de ambiente.


Variáveis de ambiente

Variável Uso
APP_ENV ambiente (development, production, test); escolhe config/<APP_ENV>.lua
APP_DEBUG true mostra detalhes de erros (só desenvolvimento)
APP_KEY segredo de cookies assinados, sessões e CSRF (32+ caracteres)
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD conexão MySQL
DB_TEST_NAME banco usado pelo ambiente test
JWT_SECRET segredo do auth.jwt() (32+ bytes)
PASSWORD_HASH_ITERATIONS iterações do PBKDF2 (padrão 600000)
SMTP_SERVER, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_FROM_NAME e-mail
CACHE_DRIVER, QUEUE_DRIVER shared (memória do servidor, padrão) ou redis; a fila também aceita sync
REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB conexão Redis (só usada pelos drivers redis)
NGINX_CONF, RUN_MIGRATIONS Docker: configuração do Nginx e migrations ao subir
APP_PORT, DB_FORWARD_PORT, DB_ROOT_PASSWORD, COMPOSE_PROFILES, REDIS_FORWARD_PORT Docker Compose

Gere segredos com openssl rand -base64 48.

Cada variável lida pela aplicação precisa de uma diretiva env NOME; em todos os arquivos do Nginx que você usa (nginx.conf e conf/*.conf). Ao criar uma variável nova, acrescente a diretiva, senão ela chega vazia nos workers.


TLS, proxy e IP real

Normalmente o TLS termina num balanceador ou proxy na frente do OpenResty. Nesse caso, faça o Nginx confiar no IP informado pelo proxy, descomentando no conf/nginx.production.conf (ou nginx.docker.conf):

set_real_ip_from 10.0.0.0/8;          # rede do seu balanceador
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Assim ctx.remote_addr (usado pelo rate limit e pelos logs) passa a ser o IP do cliente. Nunca confie no X-Forwarded-For sem isso: qualquer cliente pode forjá-lo.

Para terminar o TLS no próprio OpenResty, ajuste o bloco server:

server {
    listen 443 ssl;
    server_name app.example.com;
    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    location /public/ {
        alias public/;
        expires 1h;
    }

    location / {
        content_by_lua_block {
            require("app"):run()
        }
    }
}

Com o site 100% em HTTPS, ligue hsts = true no middleware de headers de segurança. Arquivos estáticos ficam em public/ e são servidos pelo Nginx em /public/, sem passar pelo Lua.


Workers de fila

Com QUEUE_DRIVER=shared, os jobs rodam dentro do próprio OpenResty: o init_worker_by_lua dos confs chama app:start_workers(). Não há processo extra, mas os jobs pendentes se perdem num restart e cada servidor só processa a própria fila.

Com várias réplicas ou jobs que não podem se perder, use QUEUE_DRIVER=redis em todos os containers e rode workers com a mesma imagem:

docker run -d --env-file prod.env meu-app bin/crescent queue:work
docker run -d --env-file prod.env meu-app bin/crescent queue:work --queue=mail
  • Escale rodando mais containers de worker; cada um processa um job por vez.
  • Um job cujo worker morre (deploy, OOM) volta para a fila quando passa o timeout dele: escreva handlers idempotentes.
  • O HEALTHCHECK da imagem testa o HTTP; desligue-o nos containers de worker (healthcheck: disable: true no compose).
  • --max-time=3600 faz o worker sair depois de uma hora para o orquestrador reiniciá-lo, o que ajuda com vazamentos de memória em jobs.
  • Os logs dos jobs saem em JSON no stdout do worker.

Logs e observabilidade

  • Access log do Nginx: uma linha JSON por requisição com horário, request id (rid), IP, método, URI, status, bytes e duração. É a fonte de verdade do tráfego.
  • Error log: erros do Nginx e as entradas JSON do crescent.logger (log por requisição, erros 500 com request id).
  • No Docker, os dois vão para stdout/stderr (docker logs); fora dele, para logs/.
  • X-Request-Id: o Crescent mantém o do proxy quando ele envia um, senão usa o $request_id do Nginx, e devolve o valor na resposta. Use-o para cruzar logs.
  • /health (liveness) e /ready (readiness, verifica o banco e, quando usado, o Redis). Veja Health e readiness.

Checklist de produção

  • APP_ENV=production e debug = false (o config/production.lua já define).
  • APP_KEY e JWT_SECRET com 32+ caracteres, fora do repositório; nada de .env em produção.
  • Usuário do MySQL com acesso só ao banco da aplicação; migrations aplicadas no deploy.
  • Toda variável nova declarada com env NOME; nos arquivos do Nginx.
  • client_max_body_size e limites de upload ajustados ao que a aplicação aceita.
  • set_real_ip_from configurado se houver proxy; rate limit no login.
  • HSTS só com HTTPS em todo o site; CORS com lista explícita de origens.
  • Balanceador usando /ready; orquestrador reiniciando por /health.
  • lua_shared_dict (crescent_limits, crescent_jwt, crescent_sessions, crescent_cache, crescent_queue) mantidos no conf; lembre que eles são locais a cada servidor.
  • Mais de uma réplica: CACHE_DRIVER=redis e QUEUE_DRIVER=redis, Redis com senha e fora da internet pública, e workers rodando queue:work.

O que mudou

O Crescent 2.0 é uma reescrita: troca o Luvit pelo OpenResty (Nginx + LuaJIT). O Nginx passa a cuidar do servidor HTTP, dos workers e dos arquivos estáticos, e o banco continua sendo MySQL. A organização em módulos (src/<módulo> com controllers, services, models e rotas) continua a mesma, mas a API mudou em pontos que quebram código existente.

A forma mais simples de migrar é criar um projeto novo a partir do starter e trazer seus módulos, ajustando-os com a lista abaixo.


Mudanças que quebram código

1.x (Luvit) 2.0 (OpenResty)
ctx.json(200, dados), ctx.text, ctx.redirect... ctx:json(200, dados), ctx:text, ctx:redirect... (dois-pontos em todo o contexto)
app:listen(8080) e luvit app.lua app.lua retorna o app; o Nginx o executa (bin/crescent server start); a porta fica no listen do nginx.conf
middleware interrompe com return false middleware responde sem chamar next(): return ctx:error(401, ...)
middleware só global também por rota: auth.protect(middleware, action)
jwt.sign(..., { expiresIn = 900, notBefore = 0 }) opções em snake_case: expires_in, not_before
require("crescent.utils.jwt") require("crescent.security.jwt")
require("crescent.utils.hash"), hash.encrypt require("crescent.security.password"), password.hash / password.verify
require("crescent.utils.http") require("crescent.http_client")
require("crescent.utils.mail") require("crescent.mail")
require("crescent.utils.env") require("crescent.env") (e env NOME; no nginx.conf)
require("crescent.database.model") require("crescent.model")
Model:where(...):get() devolvia linhas devolve instâncias do model (use to_table() para JSON)
middleware static arquivos em public/, servidos pelo Nginx em /public/
middleware logger Crescent.middleware.request_log
luvit crescent-cli.lua <comando> lua cli.lua <comando> (ou bin/crescent <comando>)

O que continua valendo

  • Hashes de senha do 1.x (iteracoes$salt$hash) são verificados normalmente por password.verify. Use password.needs_rehash no login para atualizá-los para 600.000 iterações aos poucos.
  • Nomes camelCase do ORM (findOrFail, orderBy, whereIn, toTable...) continuam disponíveis como apelidos, mas a documentação usa snake_case.
  • crescent.utils.tests e o formato tests/test-*.lua continuam; rode com bin/crescent test.
  • O banco é o mesmo MySQL: suas tabelas continuam servindo. Confira as migrations antigas contra o formato novo (up/down retornando SQL; veja Migrations).

Pontos de atenção

  • Estado global: o app.lua roda uma vez por worker e vários workers atendem em paralelo. Estado em variáveis de módulo não é compartilhado entre workers; use o banco ou ngx.shared.
  • Variáveis de ambiente: declare cada uma com env NOME; no nginx.conf, senão os workers não as enxergam.
  • I/O: use as bibliotecas do OpenResty (cosockets): crescent.http_client, crescent.mail, lua-resty-*. Módulos do Luvit (coro-http, fs assíncrono...) não funcionam.
  • Erros: os erros gerados pelo framework (404, 405, validação, autenticação...) seguem o formato { status, code, error, details }; ajuste clientes que dependiam das respostas antigas.