Why Rust for Microservices?
svc-family compiles to a single ~15MB static binary with no runtime, no GC pauses, and compile-time guarantees about concurrency. For health data (HIPAA/GDPR territory) the pitch is stronger still: the compiler enforces who owns what data, so entire bug classes β use-after-free, data races, iterator invalidation β cannot reach production.
Memory safety, no GC
Ownership + borrow checker prove at compile time that every allocation has exactly one owner and no dangling references.
Fearless concurrency
Send/Sync marker traits make "safe to share across threads" a type-level fact. Data races are compiler errors.
Cheap abstraction
Traits are zero-cost: dyn Trait is one vtable pointer, generics are monomorphised. Hexagonal indirection costs ~nothing.
Spring Boot β Rust concept map
If you're coming from Java/Spring, this mapping makes the transition concrete:
| Spring Boot | Rust (this guide) | Key Difference |
|---|---|---|
@SpringBootApplication | src/main.rs | Much thinner β just config + server start |
@Service, @Repository | Plain structs + traits | No annotations; DI is manual |
| JVM + GC | Compiled binary, no GC | Memory managed at compile time |
| Maven multi-module | Cargo workspace | Same idea, different syntax |
| Spring Data JPA | Traits (ports) | You define the interface, implement per backend |
Lombok @Data | #[derive(...)] | Compile-time code generation via macros |
The Big Idea: Rust has no runtime. No JVM, no Spring context, no reflection. Everything is explicit, and the compiler checks it all before you ship. This means many bugs that would be runtime exceptions in Java become compile-time errors in Rust.
The three ownership concepts you must internalise first
| Concept | Rule | Where you'll see it in svc-family |
|---|---|---|
| Ownership | Every value has exactly one owner; assignment moves ownership by default | FamilyService::new(...) takes repos by value and stores them |
| Borrowing | Many immutable borrows (&T) XOR one mutable borrow (&mut T) at a time | Repo methods take &self and read &Family |
| Lifetimes | Borrows can't outlive their owner (usually inferred) | Handlers borrow request data only for the handler's scope |
Mental model: imagine family2 = family in Java did not copy the reference but actually transferred it and
family became null automatically. That is Rust's default. The side-by-side:
Family family = new Family("Smith"); Family family2 = family; // family is still valid! System.out.println(family.getName()); // OK
let family = Family::new("Smith"); let family2 = family; // println!("{:?}", family); // COMPILE ERROR! // family is no longer valid
Interactive: watch ownership move
Click each step to see what happens. Steps 3 and 5 would be compile errors.
let family = Family::new("Smith");
let family2 = family;
println!("{:?}", family);
let family_ref = &family2; // immutable borrow
let family_mut = &mut family2;
Shared ownership across async tasks: Arc<T>
An HTTP server handles thousands of concurrent requests on a thread pool. Every request handler needs access to the same service.
Rust's answer is Arc β Atomic Reference Counting β a heap pointer whose count is incremented/decremented atomically.
Clone an Arc and both clones point at the same object:
Why AppState derives Clone: Axum clones state per request internally. Cloning an Arc is a single atomic increment β nanoseconds. Cloning the underlying FamilyService would be impossible anyway (it holds non-clonable trait objects), which is exactly why we wrap it.
Spring developers: where's your @Service injection?
Spring injects singleton beans into controllers via @Autowired. Rust has no DI framework β you build the shared state yourself and hand it to the router once. A clone of the Arc is your "injected dependency":
@Service singleton
@Service public class FamilyService { ... } @RestController public class FamilyController { @Autowired private FamilyService service; // injected by the container }
Arc state
#[derive(Clone)] pub struct AppState { pub service: Arc<FamilyService>, // what handlers receive } // router.with_state(AppState{ service }) β injected ONCE, // each request gets a cheap Arc clone (atomic increment)
Send and Sync: the two markers tokio demands
| Marker | Means | Java equivalent | Why it matters here |
|---|---|---|---|
Send | The value can be moved to another thread | Like Serializable, but for thread boundaries | Tokio may poll your future on any worker thread |
Sync | &T is safe to share between threads | Thread-safe read-only access | Many requests hold references to the same Arc<FamilyService> simultaneously |
This is why every port trait declares : Send + Sync as a supertrait β see Section 06. Drop those bounds and
Arc<dyn FamilyRepository> refuses to compile inside axum's threaded runtime. The compiler, not a code review,
catches the design mistake.
Cargo & Workspaces
Cargo is Rust's build tool and package manager. A workspace is a group of crates that share one
Cargo.lock, one target/ directory, and one dependency graph β so all services in the repo build with the same
versions of axum, serde, uuid, etc.
One crate, two artifacts: library + binary
src/lib.rs β library target
Compiles to libsvc_family.rlib. Other crates (the gateway binary) depend on svc_family and reuse its router, service, and in-memory doubles without spawning a process.
src/main.rs β binary target
Compiles to the deployable executable svc-family for standalone Cloud Run deploys. It's thin on purpose β just config + server startup (Section 12).
The binary imports from the library via the crate name with underscores:
use svc_family::{build_router_with_firestore, openapi_router}; β hyphens in package names become underscores in code.
Concepts that trip people up
| Concept | What it does | In this PR |
|---|---|---|
| Edition | Dialect of the language; opt-in per crate, never breaking existing code | edition = "2021" |
| Features | Cargo's conditional compilation; crates gate optional code behind feature flags | axum's ws (websockets) and macros; serde's derive; uuid's v4 |
| Cargo.lock | Exact resolved versions for reproducible builds; committed for binaries | +2,355 lines in this PR alone |
| dev-dependencies | Available only to tests/examples/benches β excluded from release builds | mockall |
| Path dependency | Local sibling crate reference instead of a registry version | svc-shared = { path = "../svc-shared" } |
β Check yourself β Cargo
1. What does having both src/lib.rs and src/main.rs in one crate produce?
2. Why is mockall under [dev-dependencies] rather than [dependencies]?
Modules & lib.rs β the Crate's Public API
Rust has no folders-as-namespaces magic: every directory needs a module declaration. mod.rs is the module's front door,
and pub use re-exports flatten the tree into an ergonomic API. Here is the complete module layout of svc-family:
lib.rs is a contract, not a formality
pub modmakes a whole submodule public β anyone can reachcrate::adapters::secondary::firestore::family_repo::FirestoreFamilyRepository.pub usecreates an alias at the current path βuse svc_family::FamilyRepository;works because of the re-export above.- Anything not marked
pubis private to the module β Rust's default is encapsulation, unlike Java/C#. //!at file top is an inner doc comment documenting the module itself (see//! svc-family - Family management...in lib.rs).
The three path keywords you'll read in every file
| Keyword | Resolves relative to | Example from the PR |
|---|---|---|
crate:: | This crate's root | use crate::domain::model::Family; in handlers.rs |
super:: | Parent module | repos referencing super::firestore_client::FirestoreClient-style siblings |
self:: | Current module | rare; usually omitted |
Design signal worth copying: domain/model.rs contains exactly five lines β re-exports from svc_shared.
The shared kernel crate owns canonical domain types (Family, ConsentGrant, PatientIdβ¦); each service aliases them locally.
One definition, every service consistent β no drift between services on what a PatientId is.
β Check yourself β Modules
3. ports/mod.rs contains pub use family_repo::FamilyRepository;. What does this enable?
Hexagonal Architecture (Ports & Adapters)
Alistair Cockburn's hexagonal architecture puts business logic at the centre, with everything else plugged in through explicit interfaces. The dependency rule: all source dependencies point inward. The domain knows nothing about HTTP or Firestore; the outside world knows the domain.
Why teams actually adopt this (not just aesthetics)
- Swap Firestore for Postgres by writing four new structs β zero lines change in domain or handlers.
- Test business rules in microseconds against in-memory doubles, no emulator, no network, no flakiness.
- Parallel workstreams: one engineer ships endpoints against in-memory repos while another builds the Firestore adapter.
- Compile-time architecture enforcement: if domain/service.rs tries to
use crate::adapters::..., that's visible in review β and linters likecargo-denyor module-visibility tricks can make it fail CI outright.
Deep dive: where each layer is ALLOWED to import from
Read the use block at the top of any file and you know instantly whether the dependency rule holds:
- domain/service.rs may import: std, uuid, chrono, tracing, its own ports and models. It must NOT import axum, firestore_db_and_auth, or anything from
adapters/. - ports/*.rs may import: async_trait, domain models, domain error. Nothing else.
- adapters/** may import: everything β framework SDKs, DTOs, ports, domain. Adapters sit at the rim; they see it all.
PR #18 mostly holds this rule β but Section 13, Drill 7 shows where the "pure domain" claim bends (bcrypt inside service.rs).
Domain Layer β Pure Business Logic
FamilyService is the heart of the service: 608 lines of business rules β who may join a family, when an invitation
expires, what "effective permissions" means. It holds four repository ports, injected once at construction, and every method
returns the domain's own Result<T>.
The shape every service method follows
| Step | Mechanism | Example |
|---|---|---|
| 1 Β· Load | repo.get_...().await? | get_by_id(family_id) β Option<Family> |
| 2 Β· Convert None to error | .ok_or(...)? | ok_or(FamilyError::FamilyNotFound(family_id))? |
| 3 Β· Authorise | explicit rule call | verify_family_access(&family, user_id).await? |
| 4 · Enforce rules | early-return errors | Forbidden, InvitationExpired, DuplicateMember⦠|
| 5 Β· Persist + return | repo write, then Ok | create(&member).await?; Ok(member) |
Note the absence of HTTP concepts. No StatusCode, no JSON, no request structs. The domain speaks in
FamilyError::Forbidden; only the adapter layer (Section 09) translates that to a 403. That translation table is the entire
contract between layers β which is why the same service can later serve gRPC or Lambda without touching one line here.
Ports β Repository Traits with async_trait
A port is just a Rust trait the core owns. It states what persistence capability the domain needs β never how.
PR #18 defines four, one per aggregate. In Spring Data terms, the port replaces the @Repository interface:
@Repository interface
public interface FamilyRepository { Family save(Family family); Optional<Family> findById(UUID id); List<Family> findByUserId(UUID userId); }
#[async_trait] pub trait FamilyRepository: Send + Sync { async fn create(&self, family: &Family) -> Result<()>; async fn get_by_id(&self, id: Uuid) -> Result<Option<Family>>; async fn list_for_user(&self, user_id: Uuid, after: Option<String>, limit: usize) -> Result<Vec<Family>>; }
What the annotations hide: Spring @Repository silently wires an implementation (JPA proxy, Redis, whatever);
Rust makes you implement the interface per backend yourself β Firestore, in-memory, Postgres. That's the whole hexagonal payoff:
you see every backend, and the domain never knows which one is plugged in.
Anatomy lesson β four details doing heavy lifting
| Detail | Why it's there |
|---|---|
#[async_trait] | Rust traits historically couldn't have async fns usable as trait objects. This macro rewrites each async fn to return Pin<Box<dyn Future + Send + 'async>>, making the trait object-safe (dyn-compatible). Without it, Arc<dyn FamilyRepository> won't compile. (Native async-in-traits stabilised in 1.75 but still isn't dyn-compatible.) |
: Send + Sync | Supertrait bounds. Tokio shares repos across worker threads inside Arc; without these bounds the future produced by handlers isn't Send and axum rejects the handler at compile time. |
&self, never &mut self | Shared ownership via Arc means mutable access is impossible. Adapters achieve interior mutability themselves (Firestore is remote state; in-memory uses locks). Ports encode the concurrency contract: all methods are callable concurrently. |
Result<T> alias | type Result<T> = std::result::Result<T, FamilyError> from domain/error.rs β repo failures speak the domain's vocabulary (Conflict, Internal), not Firestore's. |
Port design smell to watch for: methods that leak storage dialect into the port name or signature
(query_by_firestore_cursor, upsert_document). Compare get_by_token_hash(&str) β good:
expresses intent ("find by hashed token") that both Firestore and in-memory can honour differently.
Deep dive: object safety (dyn compatibility) β the #1 beginner trap
To create dyn Trait, the compiler must build a vtable: one function pointer per method, called through the trait object.
Rules that break it:
- Generic methods (
fn save<T: Entity>(&self, e: T)) β vtable can't list infinite monomorphisations β not dyn-compatible. Self: Sizedrequirements on methods used through dyn.- Native async fn in traits β desugars to an associated type/impl-Trait generic, same problem. Hence
#[async_trait]'s Boxed-future rewrite costs one heap allocation per call β negligible next to a network hop to Firestore. - Associated consts / static dispatch helpers similarly block dyn.
Compiler error you'll see if violated: "the trait FamilyRepository cannot be made into an object." When you hit it, either
drop the generics from the trait or reach for #[async_trait]/boxed returns.
β Check yourself β Ports
4. Why does FamilyRepository need #[async_trait] for Arc<dyn FamilyRepository> to work?
5. Port methods take &self even though they insert/update data. How do implementations mutate safely?
DTOs β the API Contract Layer
Data Transfer Objects live in the primary adapter (adapters/primary/http/dto.rs) and exist for one reason:
the wire format must evolve independently of the domain model. Domain types change when business rules change;
DTOs change when API clients need a different shape. Conflating them couples every frontend release to your internal refactors.
Each derive is load-bearing
| Derive | Gives you |
|---|---|
Serialize / Deserialize | serde generates JSON β struct code. Axum's Json<T> extractor requires Deserialize; responses require Serialize. |
ToSchema | utoipa generates the OpenAPI schema component β powers Swagger UI and generated client SDKs. |
Debug, Clone | Loggable in handlers; cloneable for retries/multi-insert paths (invitation + consents). |
DTO β domain conversion happens explicitly
The handler destructures the DTO, passes plain values into the service, and wraps the returned domain model back in the envelope.
No From<Dto> for DomainModel magic β conversions stay visible at the boundary where mistakes are easiest to spot.
Note also the standard error envelope every endpoint shares:
Machine-readable code strings (FAMILY_NOT_FOUND, INVITATION_EXPIRED) let frontends switch on
behaviour without parsing prose messages. skip_serializing_if keeps payloads clean instead of emitting "details": null.
Axum HTTP Layer β Handlers, Extractors, Router, OpenAPI
Axum handlers are plain async functions whose parameters declare their dependencies as extractors. Axum inspects each
argument's type and pulls the right piece out of the request: path segments, query string, headers, or the JSON body.
A Spring @PostMapping controller and its axum twin:
@PostMapping("/families") public ResponseEntity<Family> create( @RequestHeader("X-User-ID") UUID userId, @RequestBody CreateFamilyRequest req ) { Family f = service.createFamily(userId, req.getName()); return ResponseEntity.status(201).body(f); }
#[utoipa::path(post, path = "/api/v1/families", request_body = CreateFamilyRequest, responses( (status = 201, body = Family), tag = "Families"))] pub async fn create_family( State(state): State<AppState>, // β @Autowired state headers: HeaderMap, // β @RequestHeader Json(req): Json<CreateFamilyRequest>, // β @RequestBody (last!) ) -> Result<(StatusCode, Json<Family>), AppError> { let user_id = extract_user_id(&headers)?; let family = state.service.create_family(user_id, req.name).await?; Ok((StatusCode::CREATED, Json(family))) }
What extractors buy you: Spring binds params by annotation; axum binds by type. The compiler enforces that
Json<T> comes last, that the return type implements IntoResponse, and that errors implement it too β errors you'd
only catch at runtime in Spring are compile errors here. Scroll on for the ordered dissection.
Extractor rules that matter
- Order matters:
Path,Query,State,HeaderMapconsume parts of the request and can appear in any order β but the body extractor (Json<T>) must be the last argument because it consumes the whole request stream. - Exactly one body extractor per handler.
- Return types implement
IntoResponse: tuples like(StatusCode, Json<T>)compose β status plus typed body. - Errors must implement
IntoResponsetoo β that'sAppError/FamilyError, Section 09. Path(family_id): Path<Uuid>parses the segment and rejects non-UUIDs with 400 automatically.
How utoipa wires up (three moving parts)
#[utoipa::path]on each handler emits metadata + a hidden item named__path_create_family.#[derive(OpenApi)] #[openapi(paths(...), components(schemas(...)), tags(...), servers(...))]collects them into one spec β note the explicit import of those__path_*items in router.rs.SwaggerUimounts interactive docs at/swagger-uiserving the generatedopenapi.json. Free documentation that cannot rot β it compiles from the same signatures as the routes.
Generic-state trick: Router<AppState> is "missing its state". Calling .with_state(state) converts it to plain
Router once, in lib.rs composition roots. This means the router function itself never touches Firestore or config β
another dependency-rule win.
β Check yourself β Axum
6. A colleague writes a handler with signature (Json(body), State(state)). What happens?
Error Handling β thiserror β HTTP Mapping
The domain defines one enum of every failure mode. thiserror derives the boilerplate (Display,
std::error::Error); a single From impl defines how each variant becomes an HTTP response. Errors flow upward through
? and get translated exactly once, at the edge.
public enum FamilyError extends RuntimeException { FAMILY_NOT_FOUND, FORBIDDEN, INVITATION_EXPIRED, INTERNAL } // throwing (anywhere...) throw new FamilyException(FamilyError.FORBIDDEN, "Only owner"); // catching (one layer, if you remember) @ExceptionHandler(FamilyException.class) public ResponseEntity<ErrorResponse> handle(FamilyException e) { ... }
Result
#[derive(Debug, Error)] pub enum FamilyError { #[error("Family not found: {0}")] FamilyNotFound(Uuid), #[error("Forbidden: {0}")] Forbidden(String), #[error("Invitation expired")] InvitationExpired, } pub type Result<T> = std::result::Result<T, FamilyError>; // EVERY fallible call returns Result β the compiler // forces you to handle or propagate with `?`
Exceptions hide in the stack; Results sit in the signature. A Spring method can throw anything passengers-wise and you
discover it in testing; a Rust function's return type is the complete failure contract β nobody can forget to handle a case the
compiler listed. What Spring calls @ExceptionHandler wiring, Rust does in one From impl per error type
(below).
The propagation chain, end to end
| Status | Variants mapped | Rationale |
|---|---|---|
| 404 Not Found | FamilyNotFound Β· MemberNotFound Β· InvitationNotFound Β· ConsentNotFound | Resource lookup miss |
| 401 / 403 | Unauthorized Β· Forbidden | Identity vs permission distinction preserved |
| 409 Conflict | Conflict Β· InvitationInvalid Β· DuplicateMember | State-machine violations |
| 422 Unprocessable | Validation Β· SelfConsent | Syntactically valid JSON, semantically rejected |
| 410 Gone | InvitationExpired | Was valid once, no longer actionable |
| 500 | Internal | Generic message only β see below |
Security detail worth praising in review: Internal(_) maps to the fixed string
"Internal server error", deliberately discarding the real message. Internal details (SQL fragments, file paths,
Firestore doc names) must never leak to clients. Log the full error server-side; return the generic body.
Firestore Adapter β Persistence Model & Mapping
The secondary adapters implement the ports against real infrastructure. The Firestore adapter uses
firestore-db-and-auth 0.8 with a ServiceSession (service-account auth, no user tokens). Three ideas matter:
a thin client wrapper, a separate persistence struct per aggregate, and explicit two-way mapping.
Why a separate FamilyDoc at all? serde could serialize Family directlyβ¦
- Schema evolution: rename a domain field without a live migration of stored documents β the mapping layer absorbs old/new shapes.
- Type coercion: Firestore has no UUID type; documents store strings. Storage format β memory format.
- No accidental writes: domain models can gain computed/transient fields that must not persist; the doc struct is the allow-list.
- Multi-backend symmetry: Postgres row structs or Kafka payloads follow the same pattern β the port stays stable while each adapter picks its own representation.
Field-mapping fragility: this low-level fields.get("name") style means adding one domain field requires touching
create/read/update paths by hand β miss one and you get silent data loss on read-back. Newer crates (firestore) derive this
mapping from structs with serde. Worth flagging as future maintenance cost, not a blocker.
Test Doubles β In-Memory Adapters & Composition Roots
Because the ports are traits, tests get real implementations β just backed by HashMaps instead of GCP. These doubles ship in the library crate (not dev-deps) so integration harnesses and the gateway binary can reuse them.
Why this beats @MockBean/Mockito: Spring tests swap in a mocked bean per test; the mock's behaviour is
declared in test code, so it can silently diverge from the real implementation. Rust's portfolio of doubles
(InMemoryFamilyRepository etc.) are real implementations of the same trait β they behave like the production
repo, just faster and in-process. You mock only when asserting an interaction, not as your default test strategy.
Two composition roots β production vs testing
lib.rs provides both wiring functions. This is the hexagonal payoff in its purest form: identical routers, identical service, different adapters.
The testing pyramid this enables
| Level | Mechanism | Speed | Catches |
|---|---|---|---|
| Unit | mockall mocks of ports; assert service rules in isolation | ΞΌs | Business-rule logic |
| Integration (HTTP) | build_router_in_memory() + tower's oneshot/axum-test β real request/response cycles, no sockets | ms | Extractor wiring, status codes, JSON contracts |
| E2E | Firestore emulator or staging project behind build_router_with_firestore | s | Real query semantics, index requirements |
The fidelity trap: a double that doesn't honour port semantics makes every test built on it a fiction.
PR #18's in-memory get_effective_permissions returns an empty map "for now" β Drill #4 dissects why that's the most
dangerous kind of bug in this architecture: everything compiles, all green, prod diverges.
Wiring & main.rs β Config, Tokio, Tracing
The binary is deliberately boring β read env config, build the router, serve. All interesting logic lives in the library.
main.rs β completeCloud Run readiness checklist β what this main gets right & what it's missing
| Requirement | Status | Note |
|---|---|---|
Listen on $PORT, all interfaces | done | SocketAddr::from(([0,0,0,0], port)) |
| Structured JSON logging | done | fmt layer json() β parses natively into Cloud Logging |
| Config via env with safe defaults | done | Fallback chain pattern |
| Graceful shutdown on SIGTERM | missing | Needs axum::serve(...).with_graceful_shutdown(signal_handler); Cloud Run gives ~10s before hard-kill β in-flight requests should drain |
| Liveness/readiness endpoints | missing | Add /healthz returning 200 without touching Firestore; readiness can check a cheap session ping |
| Startup failure = fast crash | done | build_router_with_firestore(...)? propagates β bad creds kill the container immediately instead of serving 500s forever |
Return type decode: Box<dyn Error + Send + Sync> is idiomatic main() ergonomics β "any error type, as long as it's
thread-safe". Every error in the chain auto-converts via From. In libraries prefer concrete typed errors;
boxed dyn errors are for binaries and FFI boundaries.
β Check yourself β Production wiring
7. Why bind to 0.0.0.0 instead of localhost?
8. What's the operational risk of the missing graceful-shutdown handler?
Code Review Playbook
You now know the architecture. This section trains the harder skill: finding the bugs that don't fail CI. First a rubric to structure any hexagonal-Rust review; then seven drills built from real issues in PR #18 β each one subtle enough that it shipped merged.
The reviewer's rubric for hexagonal Rust services
| Lens | Ask yourself |
|---|---|
| Dependency rule | Do domain/ports import adapters or frameworks? Read only the use blocks of every file under domain/ first. |
| Error integrity | Any unwrap/expect/unwrap_or(default) on fallible external input? Any error swallowed into a default value? Any Internal message leaked to clients? |
| Async hygiene | std::sync locks inside async fns? Blocking calls (bcrypt! heavy CPU!) on the runtime? .unwrap() on lock poisoning = panic cascade? |
| Security surface | Where does identity come from? Are secrets returned more than once? Is there rate limiting on expensive unauthenticated endpoints? TOCTOU races on state transitions? |
| Contract honesty | Does pagination actually paginate? Does the OpenAPI spec match real behaviour? Do status codes match semantics? |
| Test-double fidelity | Does each in-memory adapter implement port semantics fully, or return placeholder results that make tests green while prod diverges? |
| Data integrity | Multi-document writes atomic? Corrupt records fail loudly or silently coerce? Sort keys stable for pagination? |
| Operational readiness | Graceful shutdown? Health endpoints? Startup fails fast? Log levels sane? PII in logs? |
How to use the drills: read the snippet, form your own hypothesis before answering, then check. The analysis sections go deeper than the multiple-choice answer β root cause β blast radius β concrete fix β how to phrase it in review.
Silent coercion at the persistence boundary
data integrityContext: Firestore adapter converts stored documents back into domain models during every read.
A document was hand-edited in the Firestore console and its id is now "fam_123". What happens on read?
Root cause
unwrap_or(default) converts "this data is invalid" into "here is a valid-looking wrong value". The failure mode moves from loud-and-immediate to silent-and-deferred β the worst trade you can make at a trust boundary between storage and business logic.
Blast radius
- All corrupt docs share identity
00000000-β¦-0000: authorization checks againstowner_user_id == nil, updates writing to nil-keyed paths, cross-family leakage if nil matches another nil record's checks. - No observability signal exists, so MTTR β β. You find out from a user report weeks later.
- It also hides programmer errors β e.g. accidentally storing an int-typed id field reads as corrupt rather than failing the deploy loudly.
Fix pattern
Fail the single read with context, or skip-and-count corrupt docs behind a metric/alert β never invent identities. Reserve defaults for values that are genuinely optional, not for validating identifiers.
Identity from a spoofable header
securityContext: All 18 endpoints call this helper before touching data. There is no JWT middleware yet.
The service deploys to Cloud Run behind an API gateway that is supposed to inject X-User-ID after JWT verification. What's still wrong?
Root cause
The security boundary lives outside the artifact being reviewed. Header-based identity is legitimate only when the network path makes spoofing impossible (service mesh stripping inbound headers, mTLS between known callers). Nothing here enforces stripping, so any caller that can reach the port β including other workloads in the same project β declares itself as anyone.
Blast radius
- This is health data: family membership, NHS numbers, consent grants over data categories. Impersonation = reading strangers' medical relationships and granting yourself consent scope.
- Audit trail poisoned: logs attribute actions to victim's user_id.
- "We'll add JWT later" TODOs have no issue link, no milestone β they don't exist until scheduled.
Fix pattern
- Validate a signed token in-service (
jsonwebtokenmiddleware extractingsub) β even behind a gateway, verify independently. - If header-mode must exist for local dev: gate it behind a compile feature flag or explicit env like
AUTH_MODE=header-devthat refuses to boot in prod config. - Add the follow-up as a tracked issue linked from the TODO before merging.
Blocking locks + poisoning panics inside async fns
async correctnessContext: The in-memory repositories run under tokio's multi-threaded runtime, shared by every test/integration request via Arc.
Which combination of problems does this code carry?
Root cause Γ3
- Poisoning:
std::sync::RwLockmarks itself poisoned if a thread panics while holding it; subsequent.write().unwrap()panics forever. One flaky panic cascades into permanent 500s / test-suite chaos until process restart. - Non-atomic multi-lock: consents map updated before indexes; a reader between acquisitions sees a consent with no index entry. Three locks also invite ordering bugs (deadlock) as code grows.
- Blocking the executor: sync locks stall a tokio worker thread. Tolerable at microsecond scale, but it's a habit that gets copy-pasted around long critical sections β and reviewers can't tell which without reading each body.
Fix pattern
For pure in-memory doubles, short critical sections with std/parking_lot locks are idiomatic β the fix is collapsing to one lock (atomicity) and eliminating unwraps (poisoning), not reaching for tokio::sync (async locks) which these hot paths don't need.
The lying test double
test fidelityContext: GET /families/:id/consents/effective is the endpoint other services will trust for authorization decisions.
Integration tests hit build_router_in_memory(), grant a consent, then request effective permissions and get {}. What is the deepest problem?
Root cause
Misplaced responsibility: computing effective permissions needs two aggregates (consents + members), but the method sits on ConsentRepository, which by design can't see members. The double "solves" the impossibility by returning nothing; the comment admits the design flaw and defers it invisibly.
Blast radius
- Any consumer coding against in-memory behaviour ships authorization logic that grants nobody anything β or worse, devs invert logic ("empty means deny") that breaks catastrophically against real Firestore responses.
- The divergence is invisible in diffs: trait signature satisfied, types match, CI green.
Fix pattern β push orchestration up where the repos already meet
Rule of thumb: a double that returns canned data for logic-bearing methods is a design complaint in disguise β the method belongs higher, where dependencies are available, or the port is too wide.
Pagination theatre β cursor accepted, never used
contract bugContext: The list endpoint advertises cursor pagination via ListResponse<T>.next_cursor.
A well-behaved client pages: fetch β get 20 items + cursor C β fetch again with ?after=C. What do they see?
Root cause
Layer-by-layer param dropping: handler parses after but calls a service method whose signature has no room for it; the service method likewise calls list_for_user(user_id, after, limit)-shaped port... except here even the port's own after/limit params go unused by implementations. Each layer individually looks plausible β the bug is only visible tracing one parameter across four layers. Classic distributed monolith review failure.
Blast radius
- Infinite duplicate loops in spec-following clients; data loss appearance (users with >limit families can never see beyond page one).
- Cursor derived from last item's id, not a sort key β even if wired through, unordered Firestore queries give no stable "after this" position.
Fix pattern
And add the missing test: "requesting with the returned next_cursor yields zero overlap and eventually termination."
Unauthenticated O(n) bcrypt scan + TOCTOU race
security Β· concurrencyContext: Accept-invitation is intentionally public (that's the invitation flow). bcrypt DEFAULT_COST = 12 β 250ms per verify. Status transitions happen on plain read-modify-write.
An attacker POSTs garbage tokens in a tight loop to /invitations/{token}/accept while two legit tabs accept the same valid invitation simultaneously. What goes wrong?
Root cause Γ2
- Crypto in the wrong place: bcrypt is built for verifying a known password hash pair, not for looking up which row matches. Lookup requires a deterministic, indexable digest β bcrypt salts are random per hash, so you cannot query by hash directly, forcing the full scan.
- Check-then-act without transaction: status read, member inserted, status written β three operations, no transaction, no conditional update. Firestore executes them independently; interleaved requests interleave states.
Blast radius
- DoS: ~100 pending invitations Γ 250ms β 25s CPU per crafted request; 40 req/s saturates a 1-vCPU instance. No auth needed β invitations are public by design.
- Duplicate membership / consent rows from the race; second accept may also resurrect an already-revoked invitation depending on timing.
Fix pattern
Note how Drill 7 completes this fix: hashing/generating tokens should be a port anyway β moving crypto out of the domain is what makes swapping bcryptβHMAC possible without touching business rules.
The "pure domain" that imports bcrypt
architectureContext: The PR description claims: βdomain/ β Pure business logic (FamilyService), zero external crate importsβ. Top of domain/service.rs:
What's the most defensible review position on this?
Root cause
The claim vs reality gap matters less than the coupling itself. Domain purity isn't aesthetic: it exists so that (a) business rules can be tested without paying infrastructure costs, and (b) policies that change for non-business reasons (upgrade bcryptβargon2, rotate token entropy) touch exactly one layer. Crypto embedded in service.rs couples invitation lifecycle rules to a specific KDF and its cost parameter forever.
Blast radius
- Every invitation unit test pays ~250ms Γ cases; suites slow down multiplicatively as flows grow.
- Algorithm migration requires editing business logic β the highest-review-cost file in the crate.
- Domain tests can't stub verification, so edge-case matrices (expired+accepted+revokedΓvalid token) need the real slow path.
Fix pattern
Calibration for reviews: treat uuid/chrono/tracing/serde as ecosystem-stdlib β acceptable in domain. Treat I/O, crypto, randomness sources, clock implementations (inject Clock if determinism matters), HTTP clients as ports. Say why in review; "it's impure" convinces no one.
Bonus quick-fire findings (from the same PR)
| Spot | Finding |
|---|---|
main.rs | Silent fallback to project "agentic-health-dev" if env vars unset β in prod this boots successfully pointed at the WRONG database. Prefer expect("GCP_PROJECT_ID required") outside dev profiles. |
Cargo.toml | Missing trailing newline; tokio features=["full"] pulls unused subsystems β slim to ["macros","rt-multi-thread"]. |
router.rs | Route params use :param (axum β€0.7 style); axum 0.8 moved to {param} β works now via compat, flagged deprecated. Watch for it in the upgrade. |
handlers.rs | Double .map_err(...).map_err(AppError) chains β a newtype would collapse them; minor readability. |
dto.rs / InvitationResponse | Good instinct: raw token present only on create response. Worth a comment stating the invariant so future edits preserve it. |
Glossary
| Term | Meaning |
|---|---|
| Hexagonal architecture | Cockburn's pattern: core logic surrounded by ports/interfaces; adapters plug in. Dependencies point inward only. |
| Port | A trait the core owns defining a capability boundary (e.g. FamilyRepository). Primary ports are implemented by the core & called by drivers; secondary ports are called by the core & implemented by driven adapters. |
| Adapter | Concrete implementation connecting a technology to a port: axum handlers (primary/driving), Firestore & in-memory repos (secondary/driven). |
| DTO | Data Transfer Object β wire-shaped struct in the adapter layer, decoupled from domain models; carries serde + OpenAPI derives. |
| Composition root | Single place where concrete implementations are chosen and injected (build_router_with_firestore vs build_router_in_memory). |
| Trait object / dyn | Type-erased dispatch through a vtable: dyn FamilyRepository. Requires object safety. |
| Object safety (dyn compatibility) | Rules a trait must satisfy to be usable as dyn β no generic methods, no native async fn without boxing. |
| #[async_trait] | Proc macro rewriting trait async fns to return boxed futures, enabling dyn-compatible async traits. |
| Arc<T> | Atomically reference-counted shared pointer; the mechanism for sharing service/repos across tokio tasks. |
| Send / Sync | Marker traits: movable across threads / referable from many threads. Required bounds for multi-threaded runtimes. |
| Interior mutability | Mutation through shared references using locks/atomics (RwLock, Mutex, Cell) β how &self repo methods persist data. |
| thiserror | Derive macro generating Display/Error impls for typed error enums. |
| IntoResponse | Axum trait converting any type into an HTTP response; the hook where FamilyError becomes status+JSON. |
| utoipa | OpenAPI codegen from annotations/derives; pairs with SwaggerUi mount for live docs. |
| ServiceSession | firestore-db-and-auth session authenticated via GCP service account (server-to-server). |
| Test double fidelity | Degree to which an in-memory implementation honours port semantics; low fidelity = tests validate fiction. |
| TOCTOU | Time-of-check to time-of-use race: state validated, then changed by others before acting β fixed with transactions/conditional updates. |
| Keyset (cursor) pagination | Page tokens derived from ordered last-seen key (created_at,id), not offsets; requires deterministic sort + start_after support. |
| Workspace | Cargo multi-crate layout sharing one lockfile/target dir; versions unified via [workspace.dependencies]. |
| Graceful shutdown | On SIGTERM: stop accepting, drain in-flight requests, then exit β axum::serve(..).with_graceful_shutdown(..). |