Change Details

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

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

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