Runtime crates
What is the same in every project and not meant to be edited is not generated: it is a crate. The
runtime follows the same dependency rule as your project, so it is split by layer instead of being
one crate with features (ADR-0017).
The framework is hexagonal too: puerto-nucleo holds the ports, and the other crates are
adapters. Their API is in Spanish, like the code that calls it.
| Crate | Owns | Used by | Present when |
|---|---|---|---|
puerto-nucleo |
ErrorRepositorio, PeticionPagina / Pagina<T>; the event envelope (SobreEvento), ManejadorEvento, the delivery policy and the transport ports; the mail ports (Correo, EnviadorCorreo, CorreosEnviados); the auth port (Autenticador) and Principal |
every crate, the domain included: no driver, no runtime, no I/O | always |
puerto-web |
the server (App), Config, CORS, health probes, graceful shutdown, RespuestaError, BearerAuth, #[requiere_rol] |
the rest_<c> crates and api |
always |
puerto-sqlx |
the pool, migrations at startup, the readiness ping, mapear_error_sqlx; the unit of work, outbox and db transport; the sent-mail log; local sessions and credentials |
the infra_<c> crates and the binaries |
--db |
puerto-eventos |
the worker: the outbox relay, the consume loops, their health probes and shutdown | worker |
--eventos |
puerto-kafka |
the Kafka publisher and subscription | worker |
--eventos kafka |
puerto-correo |
the SMTP adapter, the template renderer, enviar_una_vez |
infra_correo, worker |
a mail |
puerto-auth |
feature oidc: AutenticadorOidc; feature local: argon2id hashing |
api |
--auth |
puerto-macros |
#[requiere_rol] |
through puerto-web |
--auth |
How a project depends on them
Section titled “How a project depends on them”Once, in the root Cargo.toml, on the minor that generated the project:
[workspace.dependencies]puerto-nucleo = "0.21"puerto-web = "0.21"puerto-sqlx = "0.21"Then each crate inherits what its layer may use:
[dependencies]puerto-nucleo = { workspace = true }puerto-web = { workspace = true }
[dev-dependencies]puerto-nucleo = { workspace = true, features = ["pruebas"] }pruebas exposes test doubles (MockAutenticador, MadrePrincipal, EnviadorCorreoGrabador,
CorreosEnviadosEnMemoria) to a project’s tests and keeps them out of its binaries.
The contract
Section titled “The contract”- Lockstep. The CLI and every runtime crate share one version.
puerto 0.21generates projects that ask for0.21, andpuerto validarwarns when they drift apart. - The app calls the runtime. There is no
Hookstrait to implement and no container that calls into your code:main.rsandbootstrap.rscall runtime building blocks, in plain Rust you can follow. #[non_exhaustive]from day one. Every public enum and struct you may receive can grow without a breaking change.- Ports in
puerto-nucleo, adapters in their crates. To swap an adapter, implement the port. A project only compiles the adapters it uses: a project without Kafka never buildsrdkafka. - Traits you implement for your own types stay in your project. Rust’s orphan rule keeps a
rest_<c>crate from implementingpuerto-web’sIntoRespuestaErrorfor its domain’s error, so eacherrores.rsexports a free function,a_respuesta_error, instead (ADR-0023).