Skip to content
bucker

DSN and the region model

Format

https://<publicKey>@<region>.<ingestHost>/<projectId>

Example: https://a1b2c3d4@us.ingest.example.com/clx0project0id

Part Rules
scheme https (http is tolerated for local development only)
publicKey [A-Za-z0-9_-]+, unique across the install
password half must be empty — a DSN carrying a secret is rejected as malformed
region first hostname label; [a-z][a-z0-9-]{0,15}
ingestHost everything after the region label, port included
path exactly one segment, the project id
query / fragment must be absent

Parsing lives in domain/src/lib/dsn.ts (parseDsn / buildDsn) and, for SDKs, in shared/src/protocol/dsn.ts. create-bucker re-implements the same rules locally so that npx pulls down zero dependencies.

The Sentry-SDK form: the project's number

Every Sentry SDK refuses a DSN whose project segment is not an integer. The JavaScript SDKs disable themselves without saying so outside debug mode (Invalid Sentry Dsn: Invalid projectId), and sentry-python raises at init (invalid literal for int()). A Bucker project id is not an integer, so the DSN above cannot be given to an unmodified Sentry SDK.

Each project therefore also has a number (Project.sentryProjectId), and every key reports a second, equivalent DSN with it, sentryDsn:

https://<publicKey>@<region>.<ingestHost>/<projectNumber>

Use sentryDsn in Sentry.init({ dsn }). Every DSN-authenticated route (the envelope, OTLP, check-ins, feedback and the rest) accepts either form in its <projectId> path segment. The number only identifies the project. It never authenticates: the public key must still belong to the project the path names, so a key addressed at another project's number is refused with a 403, exactly as with another project's id. Bucker's own SDKs accept both forms.

The public key is not a credential for anything but ingest

ProjectKey.publicKey appears in client bundles by design. It authenticates ingest only — it cannot read an issue, list a project, or call the control plane. There is no secret half to protect, which is why listing keys back to project members is safe and why the onboarding endpoint can return the DSN.

Legacy Sentry DSNs carried a secret in the password slot. Bucker DSNs never do, and parseDsn rejects one that tries.

Why the region prefix exists on day one

The first hostname label is the data region. Adding an EU region later is then purely additive — a new hostname, the same identifier scheme — instead of a migration that rewrites every customer's DSN and every config file that quotes it.

The DSN is derived, never stored: key.service.ts builds it from { publicKey, projectId, region } on every read. Changing INGEST_HOST or INGEST_REGION propagates to every key immediately.

Today only us and eu are accepted values for the server's own INGEST_REGION, and only one region actually runs. The parser accepts any well-formed region label, so SDKs and the CLI are already forward-compatible.

Ingest endpoint

POST https://<region>.<ingestHost>/api/<projectId>/envelope/
Content-Type: application/x-sentry-envelope   (or any type: the route reads the body raw)

The bare form without the trailing slash is registered too, so curl and hand-rolled clients do not hit a surprise 404.

Authentication is the public key, sent either as the sentry_key query parameter or inside the envelope header's dsn field. The browser SDK avoids a preflight on every event, and that takes two things together. First, auth goes in the query string, because an X-Sentry-Auth header is not CORS-safelisted. Second, the SDK sends Content-Type: text/plain;charset=UTF-8, which the ingest route accepts because it ignores the type. Query-string auth with application/x-sentry-envelope is still preflighted. A sendBeacon built that way is credentialed, so it cannot pass the ingest route's */no-credentials preflight and is silently dropped. code/sdks/browser/src/transport.ts (SIMPLE_CONTENT_TYPE) explains why. Do not relax the server policy to fix this.

A 200 carries { "id": "<eventId>" } and an X-Bucker-Ingest-Disposition header. It means the envelope was accepted and queued, not that an issue exists yet — that happens when a worker drains the queue.

A process serves one region, and refuses the rest

INGEST_REGION is also the region this process SERVES. An organization lives in one region (Organization.region), and a process in another refuses it with 409 and error.details.redirectTo, the region's API URL. The check is on every path that reaches an organization, not only the compliance routes:

Path Where What it costs
REST routes naming :orgSlug, and every authenticated route (a :projectId in the URL, an org-bound credential) plugins/residency.ts, after authentication one cached lookup per org per 30 s
Ingest, OTLP, the platform drains and the replay recorder config lib/ingest-door.ts (and replay/config-routes.ts), right after the DSN key resolves one cached lookup per project per 30 s
Explore explore/printer/guard.ts, on the org row it already loads nothing
MCP tools mcp-server/src/tools/common.ts and the status resolvers nothing for an issue, one cached lookup otherwise
Worker job claims db/src/queue/postgres-driver.ts and the remediation claim one semi-join in the claim statement

Details a client can rely on:

  • GET /orgs/:orgSlug/compliance/residency is exempt. It reports servedByThisRegion: false, which is the answer that explains the refusals everywhere else.
  • On an authenticated route, a signed-in caller who is not a member of the org gets a 404 and never the 409: whether someone else's organization lives in eu is not theirs to learn, and 404 is what the other region's own deployment would answer here. The route itself never runs, even one that authorizes non-members (the operator console). On a public or optional-auth route (status pages, SSO entry points) everyone gets the 409, as an anonymous caller does.
  • redirectServing: false in the 409 means the named region is not operating. eu is listed in the registry and not active: it has no DNS name and no stores, so there is nowhere to redirect to yet.
  • The ingest door takes the project from the key, never from the body.
  • The region of an org is cached for 30 seconds per process. A region migration is the only thing that changes it, and for up to 30 seconds after a cutover a process may still serve the org from its old region (the cutover does not yet evict the cache).
  • No token changes. The refusal is made by the resolver, so a token issued before this check verifies exactly as it did; the audience stays bucker-mcp.

residency_get (MCP, project:read) tells an agent which region serves the org, which provider and region hold each store (a ? is "not yet confirmed", never a guess), and any region move in flight; include: [manifest] adds the published trust manifest from https://bucker.io/trust.json.

Configuration

Variable Default Meaning
INGEST_REGION us Region label this install stamps into DSNs
INGEST_HOST localhost:4000 Ingest host without the region prefix
INGEST_INLINE_MAX_BYTES 65536 Above this, the raw envelope goes to blob storage instead of the row
INGEST_MAX_ENVELOPE_BYTES 20971520 Hard reject above this, with an accounted too_large outcome