@earth-app/collegedb
    Preparing search index...

    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 database instances. It maintains state about available shards, allocation strategies, and usage statistics.

    Key responsibilities:

    • Track available shards and their current load
    • Implement allocation strategies (round-robin, random, hash-based)
    • Provide HTTP API for shard allocation and management
    • Maintain persistent state in the object's SQLite database (ctx.storage.sql)

    State from earlier versions lives under legacy storage keys. The first requests copy it into SQL in pages, and until ShardCoordinator.retireLegacy runs every write also lands on the legacy keys, so the previous version can still read the object. That window is read-only for a downgrade: writes the previous version makes to the legacy keys are not copied back when the object upgrades again, and the new version overwrites them.

    // 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
    constructor
    decrementShardCount fetch forgetAllocation incrementShardCount retireLegacy

    • Creates a new ShardCoordinator instance

      Parameters

      • state: DurableObjectState

        Durable Object state provided by Cloudflare runtime

      Returns ShardCoordinator

    • 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

      If the shard is not known to the coordinator

      await coordinator.decrementShardCount('db-west');

    • 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 /forget - Drop the recorded allocation for a primary key
      • POST /sequence - Take the next value of a named sequence
      • GET /allocations - Page through recorded allocations (?after=<key>&limit=<n>, since 1.4.0)
      • POST /allocations/prune - Drop the named allocations, at most 128 keys (since 1.4.0)
      • POST /retire-legacy - Delete the legacy storage keys (since 1.4.0)
      • 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

      // Allocate a shard
      const response = await coordinator.fetch('http://coordinator/allocate', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ primaryKey: 'user-123' })
      });

    • Forgets the recorded allocation for a primary key.

      Called when a key is reassigned or its mapping deleted, so a later first-touch allocates afresh instead of being handed the stale decision.

      Parameters

      • primaryKey: string

        The key whose recorded allocation should be dropped

      Returns Promise<void>

      1.3.0

    • 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

      If the shard is not known to the coordinator

      await coordinator.incrementShardCount('db-east');

    • Stops writing the legacy keys and deletes them

      Finishes any pending copy first. The phase flips to sql-only before the keys go, so an interrupted run leaves unused keys behind and calling it again finishes the cleanup. Afterwards the previous coordinator version cannot read this object; downgrading past this call is unsupported.

      Returns Promise<void>

      Promise that resolves when the legacy keys are gone

      1.4.0

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods