Class ShardCoordinator

Durable Object for coordinating shard allocation and maintaining statistics

The ShardCoordinator is a Cloudflare Durable Object that provides centralized coordination for shard allocation across multiple D1 databases. It maintains state about available shards, allocation strategies, and usage statistics.

Key responsibilities:

Track available D1 shards and their current load
Implement allocation strategies (round-robin, random, hash-based)
Provide HTTP API for shard allocation and management
Maintain persistent state using Durable Object storage

Example

// Allocate a shard for a new primary key
const response = await coordinator.fetch('http://coordinator/allocate', {
  method: 'POST',
  body: JSON.stringify({ primaryKey: 'user-456', strategy: 'hash' })
});
const { shard } = await response.json();

Index

Constructors

constructor

Methods

decrementShardCount fetch incrementShardCount

Constructors

constructor

new ShardCoordinator(state: DurableObjectState): ShardCoordinator
Creates a new ShardCoordinator instance
Parameters
- state: DurableObjectState
  Durable Object state provided by Cloudflare runtime
Returns ShardCoordinator
- Defined in durable.ts:65

Methods

decrementShardCount

decrementShardCount(shard: string): Promise<void>
Atomically decrements the key count for a specific shard and updates the last modified timestamp. Used when primary keys are removed or moved from a shard. Prevents negative counts.
Parameters
- shard: string
  The shard binding name to decrement
Returns Promise<void>
Promise that resolves when the count is updated
Throws
If the shard is not known to the coordinator
Example
```
await coordinator.decrementShardCount('db-west');
```
- Defined in durable.ts:424

fetch

fetch(request: Request): Promise<Response>
Handles HTTP requests to the Durable Object

Main entry point for all HTTP requests to the ShardCoordinator. Routes requests based on method and path to appropriate handler functions.

Supported endpoints:
- GET /shards - List all known shards
- POST /shards - Add a new shard
- DELETE /shards - Remove a shard
- GET /stats - Get shard statistics
- POST /stats - Update shard statistics
- POST /allocate - Allocate a shard for a primary key
- POST /flush - Clear all coordinator state (development only)
- GET /health - Health check endpoint
Parameters
- request: Request
  The incoming HTTP request
Returns Promise<Response>
Promise resolving to HTTP response
Example
```
// Allocate a shard
const response = await coordinator.fetch('http://coordinator/allocate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ primaryKey: 'user-123' })
});
```
- Defined in durable.ts:135

incrementShardCount

incrementShardCount(shard: string): Promise<void>
Atomically increments the key count for a specific shard and updates the last modified timestamp. Used when new primary keys are assigned to a shard.
Parameters
- shard: string
  The shard binding name to increment
Returns Promise<void>
Promise that resolves when the count is updated
Throws
If the shard is not known to the coordinator
Example
```
await coordinator.incrementShardCount('db-east');
```
- Defined in durable.ts:403

Class ShardCoordinator

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns ShardCoordinator

Methods

decrementShardCount

Parameters

Returns Promise<void>

Throws

Example

fetch

Parameters

Returns Promise<Response>

Example

incrementShardCount

Parameters

Returns Promise<void>

Throws

Example

Settings

On This Page