Never in the request path
Your app keeps serving when MainSDK Cloud is down. Policy runs in process, telemetry never blocks, and the last good policy stays in force.
Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.
Stability The promise an interface ships with.
- Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
- Beta Usable in production; may change before it becomes stable.
- Experimental May change or go away; needs an explicit opt-in in main.yaml.
MainSDK is a library inside your app, not a service in front of it. No user request ever waits on MainSDK Cloud. When the Cloud, the update mirror or any MainSDK service is slow or down, your app keeps serving with the last good policy, packs and config. We call this fail static.
The rules
| Rule | What it means for your app |
|---|---|
| Decisions are local | policy.decide runs in process, with no network round trip per decision. |
| Telemetry never blocks | Logs and traces go into a bounded queue (by default 10,000 records or 8 MB, whichever comes first). When it's full, the oldest records drop and the caller is never slowed. Dropped counts are reported once the Cloud is reachable. |
| Last good policy | When cached policy or packs expire or fail to verify, the app keeps the last good set. It never falls back to no policy and never blocks traffic because of expiry. |
| Survives restarts | The last good policy is kept in the local cache and verified again at load. |
| Startup doesn't wait | The app loads the local cache and refreshes in the background. Cloud calls use a short timeout (2 s by default) and back off exponentially. |
| Plans never break apps | HTTP 402 and plan limits affect only the Cloud, never the running app. See Free in the app, paid in the Cloud. |
flowchart LR R[Request] --> A[Your handler] --> P[policy.decide<br/>in process] --> D[Driver] --> X[(Provider)] A -. async, bounded .-> T[Telemetry queue] -. when reachable .-> C[(MainSDK Cloud)] U[(Update mirror)] -. background refresh .-> K[Local cache<br/>last good policy] --> P
Driver outages are different. If your email provider is down, email.send raises a typed error with a retry hint, and fallback: in main.yaml fails over:
fallback:
email: [resend, ses]See every remote dependency
$ npx mainsdk status
mainsdk-cloud down since 10:02Z telemetry buffered (4,120 queued, 0 dropped)
tuf stale since 09:40Z last good: baseline 27.0.3, market/in 3
email:resend ok
db:postgres degraded p99 840 msThe same data is available in code, for your own health endpoint:
import { health } from "mainsdk";
export async function GET() {
const parts = health(); // every MainSDK service and every configured driver
const down = parts.filter((d) => d.kind === "driver" && d.state === "down");
return Response.json({ ok: down.length === 0, parts }, { status: down.length ? 503 : 200 });
}Every MainSDK service reports inRequestPath: false, always.
Performance budgets
| Budget (p99 unless noted) | Limit |
|---|---|
| Policy decision, in process | under 1 ms |
| Interface overhead over the raw provider call | under 2 ms |
| Browser bundle subset, gzipped | under 150 KB |
| Added cold start | under 20 ms |
The budgets hold in degraded mode too: with the Cloud unreachable, the update cache stale and the telemetry buffer full. Benchmarks run on every release and are published with it, with the method and harness open source. A regression past any limit fails CI and the release. How they are measured is in Performance budgets.
The queue size and the Cloud timeout are proposed defaults, to confirm after the pilot. The public status page for MainSDK Cloud and update delivery, and the public benchmark dashboard by region, arrive in phase 2.
What we deliberately don't build
No sidecar, no daemon, no remote shell into production. Each would put MainSDK in your request path or open a door into the running app.
Next
Was this page helpful?