🌙 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.
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/healthe/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.luae 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; usectx.state. - Em produção (
lua_code_cache on) é preciso recarregar o Nginx para aplicar mudanças. Em desenvolvimento onginx.confusalua_code_cache offe 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}"
HEADusa a rotaGETautomaticamente.- Caminho existente com outro método responde
405com o headerAllow; caminho inexistente responde404(route_not_found). lua cli.lua routeslista 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:redirectaceita só caminhos locais (/...); para outro domínio passe{ allowed_hosts = { "exemplo.com" } }como terceiro argumento.- Para listas vazias em JSON use
json.array({})(decrescent.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, usectx.res:before_flush(function(res) ... end), pois a resposta normalmente já foi enviada quandonext()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_errore são registrados no log com o request id. O detalhe (mensagem e stack trace) só aparece na resposta comdebug = true. - Uma tabela com
status4xx vira essa resposta, sem log de erro. É assim queModel:find_or_failproduz404 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, comocontentecsrf_field()).- O layout recebe a página pronta em
contente os mesmos dados da página. - Opções:
status(padrão200) elayout. Definaview_layout = "layout.etlua"na config para ter um layout padrão;layout = falsedesliga 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()ecsrf_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,saveeupdateretornam o model, ounil, 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 emget(),first(),count()oupage().user.namelê o atributo. Se a coluna tiver o nome de um método do model (table,save,update...), useuser:get("coluna")euser:set("coluna", valor).- Converta para JSON com
user:to_table(); ela respeitahiddene 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()gravadeleted_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)geraIS NULL. updateedeletesemwherelançam erro (proteção contra alterar a tabela inteira).- Linhas do query builder não passam pelos casts: ids
BIGINTchegam 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
COMMITquando a função retorna normalmente eROLLBACKquando ela lança erro, retornafalseounil, err. - Passe
txcomo ú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 usaSAVEPOINT.
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 dedb:migrateforma um lote. - O arquivo gerado por
make:migrationdeduz a tabela do nome (create_<tabela>ouadd_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_inerefresh_expires_in, em segundos, mudam isso). O payload levauser_id,nameeemail. auth.jwt()recusa refresh tokens;verify_refresh_tokenaceita só refresh tokens.- Tokens revogados ficam no
lua_shared_dict crescent_jwt(compartilhado entre workers, já declarado nonginx.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
204pelo próprio middleware; não crie rotasOPTIONS. cors.strict({ "https://app.example.com" })liga credenciais, cache de preflight de 24 h e responde403a outras origens.credentials = truecomorigins = "*"é 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_limitedcomRetry-After. Toda resposta trazX-RateLimit-Limit,X-RateLimit-RemainingeX-RateLimit-Reset. - Use um
prefixdiferente para cada limitador. - A chave padrão é o IP (
ctx.remote_addr). Atrás de proxy, configure orealipdo Nginx (veja Deploy); nunca use oX-Forwarded-Forcru como chave.key = function(ctx) ... endpersonaliza; retornarnilisenta a requisição.
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_uploadsão apagados ao fim da requisição. filenameecontent_typevêm do cliente: valide o conteúdo e gere você o nome final. Caminhos com..ou fora deupload_rootsão recusados.- Ajuste também
client_max_body_sizenonginx.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, epost(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
>= 400retornamnil, err, comerr.messagee, quando houve resposta,err.statuseerr.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.
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,bccereply_to. - Atalhos:
send_text(para, assunto, texto),send_html(para, assunto, html)esend_template(para, assunto, "emails/welcome.etlua", dados), que renderiza um template deviews/. - 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 delevelsã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 comLogger.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)
rememberevita 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.
getdevolvenil, err(cache miss) e
remember recalcula. Uma queda do Redis deixa a app mais lenta, mas ela continua funcionando.
nilnão pode ser cacheado;setcom 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): oinit_worker_by_luados 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-fate instala as dependências Lua em uma camada própria. - Roda como o usuário sem privilégios
crescent; sólogs/,tmp/estorage/são graváveis. Uploads vão parastorage/(upload_root = "storage"): monte um volume nesse caminho para que sobrevivam a novos containers (odocker-compose.ymlde desenvolvimento já usa o volumeapp-storage). - Usa
conf/nginx.docker.conf: cache de código ligado,worker_processes auto, app construído noinit_by_luae logs em stdout/stderr. - Tem
HEALTHCHECKem/health. - Com
RUN_MIGRATIONS=true, o entrypoint rodabin/crescent db:migrateantes 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 volumemysql-data). - Usa
conf/nginx.docker-dev.conf: um worker elua_code_cache off, com o código montado em/apppara 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_PORTmuda a porta no host. As senhas do.env.examplesão só para desenvolvimento.- Com
COMPOSE_PROFILES=redisno.env, sobem também um Redis 7.4 (AOF ligado, senhaREDIS_PASSWORD, exposto em127.0.0.1:6380, dados no volumeredis-data) e o serviçoworker(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 olua_package_pathpartem 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 oreloadfalhar, 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(oubin/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 |
|
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
timeoutdele: escreva handlers idempotentes. - O
HEALTHCHECKda imagem testa o HTTP; desligue-o nos containers de worker (healthcheck: disable: trueno compose). --max-time=3600faz 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, paralogs/. X-Request-Id: o Crescent mantém o do proxy quando ele envia um, senão usa o$request_iddo 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=productionedebug = false(oconfig/production.luajá define).APP_KEYeJWT_SECRETcom 32+ caracteres, fora do repositório; nada de.envem 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_sizee limites de upload ajustados ao que a aplicação aceita.set_real_ip_fromconfigurado 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=rediseQUEUE_DRIVER=redis, Redis com senha e fora da internet pública, e workers rodandoqueue: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 porpassword.verify. Usepassword.needs_rehashno 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.testse o formatotests/test-*.luacontinuam; rode combin/crescent test.- O banco é o mesmo MySQL: suas tabelas continuam servindo. Confira as migrations antigas contra o formato novo (
up/downretornando SQL; veja Migrations).
Pontos de atenção
- Estado global: o
app.luaroda 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 oungx.shared. - Variáveis de ambiente: declare cada uma com
env NOME;nonginx.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,fsassí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.