The puerto.toml manifest
puerto.toml is the source of truth of a project. The generators write it; cableado,
bootstrap.rs, eventos.rs, registro.rs and the frontend’s generated files are derived from
it; and puerto validar checks the code against it. You can edit it by hand; run
puerto generar bootstrap and puerto validar afterwards.
A complete example, from a project with a database, events, auth and a mail:
[proyecto]nombre = "tienda"db = trueweb = trueeventos = "db"auth = "local"
[[entidad]]nombre = "Cliente"casos_de_uso = [ "crear_cliente", "obtener_cliente", "listar_clientes", "actualizar_cliente", "borrar_cliente",]db = true
[[entidad.campos]]nombre = "email"tipo = "String"objeto_valor = "Email"
[[entidad.campos]]nombre = "nombre"tipo = "String"
[[entidad]]nombre = "Producto"casos_de_uso = [ "crear_producto", "obtener_producto", "listar_productos", "actualizar_producto", "borrar_producto", "publicar_producto",]db = truepublicos = [ "listar_productos", "obtener_producto",]eventos = ["producto_publicado"]
[entidad.roles]borrar_producto = ["admin"]
[[entidad.campos]]nombre = "nombre"tipo = "String"
[[entidad.campos]]nombre = "sku"tipo = "String"unico = true
[[entidad]]nombre = "Pedido"casos_de_uso = [ "crear_pedido", "obtener_pedido", "listar_pedidos", "actualizar_pedido", "borrar_pedido",]db = true
[[entidad.campos]]nombre = "cliente_id"tipo = "Uuid"referencia = "Cliente"
[[entidad.campos]]nombre = "estado"tipo = "String"objeto_valor = "Estado"clase_objeto_valor = "enum"variantes = [ "Pendiente", "Confirmado", "Cancelado",]
[[objeto_valor]]nombre = "Email"tipo = "String"
[[consumidor]]nombre = "avisar_producto_nuevo"eventos = [ "producto_creado", "producto_publicado",]
[[correo]]nombre = "bienvenida"tras = ["cliente_creado"][proyecto]
Section titled “[proyecto]”| Key | Type | Set by | Meaning |
|---|---|---|---|
nombre |
string | nuevo --nombre |
The project’s name: crates, database, topics |
db |
bool | nuevo --db |
Postgres through SQLx. Absent means false |
web |
bool | nuevo (default), --sin-web |
The React frontend in web/ |
eventos |
"db" | "kafka" |
nuevo --eventos |
Domain events and their transport. Needs db |
auth |
"oidc" | "local" |
nuevo --auth |
Authentication mode. local needs db |
[[entidad]]
Section titled “[[entidad]]”| Key | Type | Set by | Meaning |
|---|---|---|---|
nombre |
string | scaffold, dominio |
PascalCase. Each entity is a context, contextos/<snake>/ |
casos_de_uso |
string[] | scaffold, caso-de-uso |
Every use case cableado builds. The five CRUD ones make it a CRUD entity, with routes and screens |
db |
bool | scaffold in a db project |
Postgres repository instead of in memory |
publicos |
string[] | scaffold --publico |
Auth projects: use cases whose routes need no token |
roles |
table | scaffold --rol |
Auth projects: caso_de_uso = ["rol", …]; the caller needs all of them |
eventos |
string[] | generar evento |
Custom event types, beyond _creado, _actualizado, _borrado |
[[entidad.campos]]
Section titled “[[entidad.campos]]”| Key | Type | Meaning |
|---|---|---|
nombre |
string | snake_case |
tipo |
string | String, i64, f64, bool, Uuid, DateTime<Utc>, HashMap<String, String>, or Option<…> / Vec<…> of them. See Field types |
unico |
bool | A partial unique index, and 409 on a duplicate |
objeto_valor |
string | The value object wrapping it, local or shared |
clase_objeto_valor |
"enum" |
An enum value object; tipo is then String |
variantes |
string[] | Its PascalCase variants |
referencia |
string | Another CRUD entity whose id this field holds; tipo is then Uuid or Option<Uuid>. A foreign key in db projects. See References |
[[objeto_valor]]
Section titled “[[objeto_valor]]”Shared value objects, declared by generar objeto-valor: nombre (PascalCase) and tipo (its
inner primitive). They live in the nucleo crate. A field that names one without a type uses
this one.
[[consumidor]]
Section titled “[[consumidor]]”Events projects. Written by generar consumidor: nombre (snake_case, the handler’s file and
its consumer group) and eventos (the event types it handles). A consumer whose file is missing
makes validar fail and generar bootstrap refuse.
[[correo]]
Section titled “[[correo]]”Written by generar correo: nombre, and tras when the worker sends it after events.
What puerto validar checks
Section titled “What puerto validar checks”- Names: PascalCase entities, snake_case fields and use cases, no Rust keywords, no SQL reserved
words in
dbprojects, no names the generated code or another context already uses. - Types: every field type is one Puerto generates, and every shared value object exists.
- Consistency:
eventosandauth = "local"needdb; every declared entity, consumer and mail has its files; in web projects, every CRUD entity has its screens; in auth projects, each route’sBearerAuthand#[requiere_rol]matchpublicosandroles; everyreferencianames another declared CRUD entity, is aUuidorOption<Uuid>, and closes no cycle between contexts. - The runtime: a warning for each
puerto-*crate on another minor than the CLI.