| Method | Purpose | Functionality | Handling multi-intances |
|---|---|---|---|
| scan_orphaned_tokens | Finds tokens that are either unassigned or have expired heartbeats, after this instance can start handling this token | Runs parallel queries on DynamoDB using a sparse index for unassigned tokens and a composite index for expired tokens | Safe for multiple instances since it only reads data |
| claim_token | Atomically assigns a token to a specific instance, claims ownership for the instance | Updates token assignment with a conditional check to prevent race conditions and necessary data | Uses DynamoDB conditional expressions for atomic operations; only succeeds if token is unassigned or expired |
| update_token_heartbeat | Updates the last heartbeat timestamp for a token owned by an instance, informing other instances that this token is being handled | Conditionally updates heartbeat only if caller owns the token | Safe across instances - conditional check ensures only token owner can update heartbeat |
| get_tokens_for_instance | Retrieves all tokens currently assigned to a specific instance, used on graceful shutdown | Queries by instance ID using GSI | Safe for multiple instances since it only reads data |
| release_token | Releases a token back to the unassigned pool, used on graceful shutdown | Atomically removes assignment info and marks as unassigned | Uses conditional expression to ensure only token owner can release; prevents unauthorized releases |
| get_total_tokens_count | Returns total count of tokens in the system, used for metrics | Performs count-only scan operation | Safe for multiple instances since it only reads data |
Depends on D15228
