Skip to content

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

Once, in the root Cargo.toml, on the minor that generated the project:

Cargo.toml
[workspace.dependencies]
puerto-nucleo = "0.21"
puerto-web = "0.21"
puerto-sqlx = "0.21"

Then each crate inherits what its layer may use:

contextos/producto/rest/Cargo.toml
[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.

  • Lockstep. The CLI and every runtime crate share one version. puerto 0.21 generates projects that ask for 0.21, and puerto validar warns when they drift apart.
  • The app calls the runtime. There is no Hooks trait to implement and no container that calls into your code: main.rs and bootstrap.rs call 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 builds rdkafka.
  • Traits you implement for your own types stay in your project. Rust’s orphan rule keeps a rest_<c> crate from implementing puerto-web’s IntoRespuestaError for its domain’s error, so each errores.rs exports a free function, a_respuesta_error, instead (ADR-0023).