Sizing & Scaling

Per-module activation

Modules are gated by :active in config.edn. A process can boot a subset — the http-handler mounts only the route contributions present (module-route-contributions in wiring.clj), so a "user-only" process is a config, not a fork.

The protocol seam

Consumers depend on the protocol (e.g. IUserService), never the concrete record. Swapping an in-process record for a remote HTTP client implementing the same protocol leaves the caller untouched.

Wire format ready

Muuntaja (JSON / EDN / Transit) is already in the HTTP stack (reitit_router.clj); Malli schema.clj per module gives ready contracts.

Remote-adapter template

libs/external (SMTP, Twilio) is a gold-standard outbound adapter: record + extend-protocol + clj-http + error envelope + logging. Copy it for a service client.

Clean data boundaries

bb check:ports already forbids one module’s shell from touching another’s shell.persistence/shell.service — the only cross-module path is the service port. No cross-module SQL joins to untangle.

An acyclic dependency graph

allowed-cycle-edges in check_deps.clj is now empty — every source-level cycle was dissolved (#279, #282, #283). A new one fails bb check:deps. What is left between modules is one-directional coupling, which is a porting job; a cycle is not.

Context plumbing

correlation-id, tenant, and auth already flow through the interceptor pipeline and can ride request headers across a network hop.

Context

correlation-id, tenant-id and auth-token ride x-correlation-id, x-tenant-id and Authorization. A request keeps one correlation id across the hop instead of starting a fresh trace on the far side.

Wire format

application/transit+json, negotiated by the muuntaja stack already in the pipeline — so the server side needs no special decoding. Not JSON: both ends are Clojure, and JSON has no keywords. Payments returns {:status :paid}, which over JSON arrives as {:status "paid"}; (= :paid (:status r)) would hold in-process and silently stop holding across the hop, which is the exact transparency the adapter exists to provide. Transit also preserves sets, UUIDs and instants.

Transport errors

Returned as data, in the {:error {:type … :message …}} shape adapters already use, so a caller needs no new branch. The types distinguish cases that need different responses: :rpc/unavailable, :rpc/timeout, :rpc/remote-error, :rpc/protocol, :rpc/unknown-operation. An error envelope the server built on purpose survives its own status code — a refused operation reaches the caller as :rpc/unknown-operation, not as a generic "status 500". These are not raised: they have no in-process equivalent, so no caller has a catch for them.

Thrown exceptions

Raised again on the near side, keeping the :type from the original ex-data. Payment providers throw typed ex-info and nothing catches it — the HTTP boundary reads that :type and maps it to a status (ADR-022). If a throw became a returned map across the hop, the caller’s try/catch would stop firing and the error would flow on as though it were a result. Entries in ex-data that a wire format cannot carry (a connection, a response object) are dropped rather than allowed to fail the encoding; :rpc/remote true on the re-raised exception records that the stack trace describes the calling process, not the one that failed.

HTTP status

A typed error keeps the status it has in-process, read from the same default-error-mappings the HTTP boundary uses — a :not-found answers 404 across the hop as well. The status is what proxies, dashboards and alerting read, and counting a missing record as a server error moves an error budget for something that is not an error. A request the service could not understand is 400; everything else is 500.

Malformed requests

Answered, not thrown. The endpoint is reachable by anything that can post to it, so a body carrying no operation — or an operation that is not a name, or the wrong number of arguments for one — comes back as :rpc/protocol with 400. A request the service could not understand is the caller’s error; reserving 500 for the service actually failing keeps the two apart in an operator’s logs.

Argument count is checked against the protocol’s own :sigs before the method is invoked. Letting apply raise an ArityException would be indistinguishable at that point from the implementation failing, so a client built against a different version of the protocol — the case this is most likely to arise from — would be reported as the service breaking, and re-raised as an exception on the near side.

Retries

Only failures where the call may not have completed, and only :rpc/unavailable among those by default. A timeout is not retried: a call that timed out may well have executed, and re-sending it could charge twice. Override with :retry-on.

Which failures count as never-executed is decided conservatively. A SocketException reading Network is unreachable was never sent and is retryable; one reading Connection reset happened with the request already on the wire and is not, though both are the same class. An unrecognised failure is treated as possibly-executed — being wrong that way costs a retry that would have helped, the other way costs a duplicate payment.

The HTTP client’s own retry handler is disabled. Apache HttpClient resends low-level I/O failures before this code sees an outcome, so :retries 0 and keeping :rpc/timeout out of :retry-on would not have prevented a second checkout submission — whether to resend is a decision this adapter makes, and it cannot make it if something underneath has already decided.

An answer is never retried, whatever :retry-on says — a result, or an error envelope the service built on purpose. That distinction is structural rather than read off the shape of the value, because adapters here return {:error {:type …}} as an ordinary result: a protocol method’s legitimate return can look exactly like a transport failure, and re-sending a call that already ran is a second charge.

Exposure

The server resolves an operation against the protocol’s own :sigs. An operation the protocol does not declare is refused, so the endpoint cannot become a general-purpose remote eval.

Authentication

A service key in x-rpc-service-key, required, minimum 32 characters, compared in constant time. Validated when the handler is built, so a service configured without one fails to start rather than coming up serving port methods to anything that can reach the port. :sigs bounds what may be called; this bounds who. Deliberately not the Authorization header, which carries the end user’s token through the hop — sharing them would let any caller with a valid user token invoke ports directly. {:auth :none} opts out explicitly, for a listener that is not externally reachable; it is spelled out so it can be grepped for and never happens by omission.

This is not a substitute for keeping the endpoint off a public listener. It is the part that can be enforced in code.

Service discovery

Not included — the URL is configuration. Hardcoded or env-supplied for now, as the MVP in this document assumes.

Circuit breaker

Opt-in: pass a :cache component and the breaker keeps its state there, so replicas share one rather than each discovering the outage separately — and when the window elapses a set-if-absent! lease lets exactly one of them probe, instead of all N at once. Without a :cache there is no breaker and the client behaves as it did before.

The failure count is an atomic increment, not a read-modify-write: many callers hitting one outage at the same moment is what a shared breaker is for, and it is exactly when a read-modify-write loses increments — each reads the same value and writes back the same successor, so a burst advances the counter by one and the breaker never trips.

A probe that fails reopens the window from that moment and releases its lease, so the outage is not forgotten on the original window’s schedule and the next window can still be probed.

An invalid :circuit-breaker — :failure-threshold 0, or a :trip-on naming an error the client never produces — throws rather than being accepted, since an inert breaker and a working one look identical from outside.

It protects the traffic after the burst, not the burst. Calls issued at the same instant all pass the check before any of them has failed.

Trips on consecutive :rpc/unavailable and :rpc/timeout by default — failures where the call did not reach the service. A remote error does not count: the service answered, so it is up.

:trip-on overrides that, and the client counts whatever it names. Adding :rpc/protocol is a reasonable policy — a service returning bodies that are not envelopes is broken, and continuing to call it achieves nothing. Whether the call reached the far side governs retries, where re-sending something that already ran is the danger; tripping re-runs nothing, so it is not the same question. Note that :rpc/timeout trips the breaker although it is never retried; retrying a timeout risks running a non-idempotent call twice, while declining to make a new call risks nothing.

A refused call returns :rpc/circuit-open with :retry-after-ms, which is deliberately distinct from :rpc/unavailable: one means we tried and could not reach it, the other that we declined to try.

If the cache itself is unreachable the breaker fails open — the worst case is the behaviour of no breaker, which is better than a cache outage taking every remote call with it.

payments

Easy

Depends on core alone. Already a self-contained provider. The natural pilot for the remote-adapter pattern.

core, observability

Easy

Leaf / infra; no sibling deps. (Usually shared libs, not standalone services.)

user, tenant, external

With work

Depend on platform + the in-process service assumption in middleware. The remote adapter exists and the cycles are gone; what remains is deciding data ownership and pointing consumers at a remote adapter instead of the local component — a wiring change in the application’s config, which is why deploy/compose/per-service.yml demonstrates the mechanism without making it for you.

admin, search, workflow

Entangled

search/workflow depend on admin’s schema provider — a one-directional dep, but a heavy one: slicing either means the schema provider goes over the wire or gets extracted behind its own port. `admin→user is now one-directional too, so this is coupling to untangle, no longer a cycle to break.