Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
upstream_error
What it is
Shared classification for failures of third-party services (GitHub, FusionAuth, ...) so they reach clients as 502/503 with a message the user can act on, instead of a 500 that blames our code.
How it works
An outbound adapter turns a provider's 5xx, 429, unreachable host, or
undecodable body into an UpstreamError { service, failure } with
UpstreamFailure::from_status / from_transport. The domain error carries it
in its own Upstream variant. The inbound adapter answers it with
UpstreamError::into_response: 503 (plus Retry-After when throttled) or 502,
with an UpstreamErrorResponse { message, code } body.
Start here
src/lib.rs: the classification and what counts as an upstream failure.src/response.rs: status codes, body, andRetry-After.
Scope
- Owns: classifying provider HTTP and transport failures; their HTTP answer.
- Not here: connection state the user can fix (not linked, grant revoked, reauthentication). Each domain models it as its own 4xx error.
Boundaries
- Depends on:
http;reqwestandaxumbehind features of the same name. - Used by:
crates/fusionauth,crates/github,services/authentication_service.
Recipes
- Classify a new provider: in its outbound adapter, map non-success responses
through
UpstreamFailure::from_status(after handling the 4xx the endpoint documents) and request failures throughfrom_transport; give the domain error anUpstream(UpstreamError)variant; answer it withinto_response()in the inbound adapter's exhaustive match.
Checks
cargo test -p upstream_errorrules/ast-grep/rust-fusionauth-classify-transport.yml(run byjust check) fails a FusionAuthsend()/json()/text()mapped to anything butFusionAuthClientError::transport.
Gotchas
- Domain code may hold
UpstreamError, butsrc/domain/**must not see axum: depend withdefault-features = falsethere and enableaxumonly in the crate or feature that owns the inbound adapter. - Providers signal throttling differently. GitHub's primary limit is a 403 with
x-ratelimit-remaining: 0, whichfrom_statuscannot see; the GitHub adapter detects it before falling back tofrom_status. serviceis user-facing ("GitHub", "Google", "The sign-in service"), not a log tag. A crate that calls several providers names each one:fusionauthreports Google token refresh failures as "Google", not as itself.
Related
- Skills:
cloud-storage-hexagonal-architecture· Docs:docs/development/rust.md