Farther ShoreDocs
Go to Farther Shore
Getting startedCore conceptsLaunch checklist
ProductsUpstream routingEnvironmentsDeveloper portals
Billing strategiesPlans and limitsSubscribersAPI keys
Gateway enforcementUsage meteringLimits and creditsGateway sharding
Launch a request-counted product15mAdd monthly included usageAdd subscription plus overageCreate a prepaid credits productMeter AI token usageAdd a custom meterIssue and test an API keyDebug a denied requestUpdate product docsPrepare for launch
TroubleshootingGateway response codesMeter namingPlatform docs publishing
Status
Docs/Enforce & Meter/Gateway sharding

Gateway sharding

How hot products scale across Durable Object shards.

PreviousLimits and creditsNextLaunch a request-counted product

On this page

Why sharding existsProduct-facing behaviorHow scaling is triggeredHandoffsWhat product owners should watch

Some gateway state must be coordinated consistently, such as usage allocation, credit reservation, and concurrency. Farther Shore uses Durable Objects for that coordination.

Why sharding exists

A single Durable Object is simple and consistent, but very hot products can outgrow one object. Sharding lets a product spread coordinated work across multiple objects while keeping routing deterministic.

Product-facing behavior

Sharding should be invisible to subscribers:

  • API keys do not change
  • product hostnames do not change
  • plan behavior does not change
  • usage remains attached to the same subscriber and product

The only expected change is higher runtime capacity for hot products.

How scaling is triggered

The gateway emits usage events. Core ingests aggregated usage and can identify hot shard groups. When a product exceeds the configured threshold, core updates the product shard policy and publishes the new policy to edge configuration.

The gateway then picks up the policy and routes new coordinated work across the expanded shard count.

Handoffs

During a scaling transition, the gateway may need to honor both the previous and current policy so in-flight or recently cached work remains safe. That handoff is managed by the runtime policy published by core.

What product owners should watch

For launch and growth, watch:

  • request volume
  • denied requests
  • usage event delay
  • gateway latency
  • high-traffic subscribers
  • billing totals after scaling

Sharding increases capacity. It does not replace good product limits or abuse protection.