Ok, thanks, we need to make more improvement. A new business logic appeared from the…
- User
Ok, thanks, we need to make more improvement. A new business logic appeared from the product team + a few moment we need to improve:
-
While we can have only 3 claim types: direct, ref, or convert ref into direct, now we also have different actions. Each of this action can have one of those claim types. I will provide you with those actions, corresponding claim type and description on what is this action and what cooldown does it have: a. action: daily_tap, claim_type: direct. This type of action has a cooldown based on a streak (as we previously have: max(24 - streak, 8)) b. action: ref_points_acquire, claim_type: ref. This type of action has no cooldown because it generated automatically in FastAPI app when your referral claim his points. c. action: ref_points_claim, claim_type: convert. This type of action has a cooldown based on a streak (as we previously have: max(24 - streak, 8)) d. action: daily_login, claim_type: direct. This action available to user once a day (UTC timezone) It gives user some amount of direct points and the cooldown calculation is basically as I've said - it should be available once a day UTC time, it means the cooldown is dynamic. If I claimed this action 23:59 UTC then cooldown will be 1 minute, if I claimed 00:01 - cooldown is 23 hours 59 minutes, etc. e. action: lucky_ball_claim, claim_type: direct. This type of action is available to user each 4 days of his streak, so it basically has a cooldown of at least 72 hours + streak % 4 == 0 f. action: task_completed, claim_type: direct. This type of action has no cooldown as it is used for every user task. To make sure that user claimed each task only once, this action will use task_uuid as idempotency_key.
-
Idempotency key for each action per user (except task because task_uuid is used instead) should be generated and stored in DB and cache and propagated with updates after each claim. So FE could pass one of those keys(based on action) with each call to FastAPI app, so we don't need to make any additional calls to DB in FastAPI app and could just pass it to worker to handle it.
-
Any cooldown violation or idempotency key unique violation should be treated as idempotency, so this claim should be just skipped without any points or keys update as if it already was done.
-
Most likely worker will have multiple instances, so we need somehow to make sure that each worker will work with it's own partition of the topic due to sequencial messages partitioned by auth_user_uuid. Other wise we could have concurrent claims of same user because messages from same user that goes sequecially to one partition will be handled by different worker instances. We need this to prevent concurrency problems and dataloss.
-
Because we need to store current valid idempotency key per each action for each user, we can create new table to handle this. While claims event log could be separated from User. While claims even log will store user_uuid to maintain claims idempotency per user, we don't need it to be actually related to User model, as we need this uuid only to create some unique constraint in this evenlog to prevent false claims and double claims.
Please adjust our worker using those new improvements.
-
- Assistant
Certainly! To incorporate the new business logic and improvements outlined, we'll need to make several modifications to your FastAPI application and the worker process handling claims. Below is a comprehensive guide addressing each of your points, including architecture adjustments, database schema changes, and code snippets to help implement these features effectively.
1. Update Claim Types and Actions with Corresponding Cooldowns
a. Define Actions and Claim Types
First, we'll define the new actions, their claim types, and associated cooldown logic. It's beneficial to use an Enum for actions and claim types for better type safety and maintainability.
from enum import Enum from typing import Optional import datetime class ClaimType(Enum): DIRECT = "direct" REF = "ref" CONVERT = "convert" class Action(Enum): DAILY_TAP = "daily_tap" REF_POINTS_ACQUIRE = "ref_points_acquire" REF_POINTS_CLAIM = "ref_points_claim" DAILY_LOGIN = "daily_login" LUCKY_BALL_CLAIM = "lucky_ball_claim" TASK_COMPLETED = "task_completed"b. Implement Cooldown Calculations
Create a utility function to calculate cooldowns based on the action type and user streak.
def calculate_cooldown(action: Action, streak: int, last_claim_time: Optional[datetime.datetime] = None) -> Optional[datetime.timedelta]: if action == Action.DAILY_TAP or action == Action.REF_POINTS_CLAIM: cooldown_hours = max(24 - streak, 8) return datetime.timedelta(hours=cooldown_hours) elif action == Action.DAILY_LOGIN: if last_claim_time: now = datetime.datetime.utcnow() next_available = last_claim_time + datetime.timedelta(days=1) remaining = next_available - now return remaining if remaining > datetime.timedelta(0) else datetime.timedelta(0) elif action == Action.LUCKY_BALL_CLAIM: if streak % 4 == 0: return datetime.timedelta(hours=72) # No cooldown for REF_POINTS_ACQUIRE and TASK_COMPLETED return Nonec. Update the Claims Processing Logic
Ensure that each action's specific logic is integrated into your claims processing. Here's a simplified example:
async def process_claim(user_id: str, action: Action, task_uuid: Optional[str] = None): user = await get_user(user_id) streak = user.streak last_claim_time = await get_last_claim_time(user_id, action) cooldown = calculate_cooldown(action, streak, last_claim_time) if cooldown: if datetime.datetime.utcnow() < last_claim_time + cooldown: # Handle cooldown violation (see point 3) return handle_cooldown_violation() # Proceed with claim processing if action == Action.TASK_COMPLETED: if not task_uuid: raise ValueError("task_uuid is required for TASK_COMPLETED action") # Handle task completion with idempotency based on task_uuid await handle_task_completed(user_id, task_uuid) else: # Handle other actions with idempotency keys idempotency_key = await get_or_create_idempotency_key(user_id, action) await handle_standard_claim(user_id, action, idempotency_key)
2. Implement Idempotency Keys
a. Database Schema for Idempotency Keys
Create a new table to store the current valid idempotency key for each action per user.
CREATE TABLE user_idempotency_keys ( user_uuid UUID NOT NULL, action VARCHAR(50) NOT NULL, idempotency_key VARCHAR(255) NOT NULL, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (user_uuid, action) );b. Idempotency Key Generation and Storage
Implement functions to generate, store, and retrieve idempotency keys.
import uuid from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy import select, insert, update async def get_or_create_idempotency_key(user_id: str, action: Action, db: AsyncSession) -> str: result = await db.execute( select(UserIdempotencyKey).where( UserIdempotencyKey.user_uuid == user_id, UserIdempotencyKey.action == action.value ) ) record = result.scalar_one_or_none() if record: return record.idempotency_key else: new_key = str(uuid.uuid4()) await db.execute( insert(UserIdempotencyKey).values( user_uuid=user_id, action=action.value, idempotency_key=new_key ) ) await db.commit() return new_keyc. Frontend Integration
Ensure the frontend retrieves and submits the correct idempotency key with each claim request. For example:
// Example using fetch API const response = await fetch('/api/claim', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': currentIdempotencyKey, // Retrieved from the backend }, body: JSON.stringify({ action: 'daily_tap', // ... other data }), });
3. Handle Cooldown and Idempotency Violations
When a cooldown is violated or an idempotency key conflict occurs, treat the claim as already processed and skip it without updating points or keys.
a. Implement Violation Handling
def handle_cooldown_violation(): # Log the violation logger.info("Cooldown violation detected. Claim skipped.") return {"status": "skipped", "reason": "Cooldown active"} async def handle_idempotency_violation(): # Log the idempotency violation logger.info("Idempotency violation detected. Claim skipped.") return {"status": "skipped", "reason": "Idempotency key already used"}b. Integrate Violation Checks
Modify the claim processing to include these checks.
async def handle_standard_claim(user_id: str, action: Action, idempotency_key: str): async with db_session() as db: try: # Attempt to insert the idempotency key await db.execute( insert(ClaimsEventLog).values( user_uuid=user_id, action=action.value, idempotency_key=idempotency_key, timestamp=datetime.datetime.utcnow() ).on_conflict_do_nothing() ) await db.commit() except IntegrityError: # Handle idempotency violation return handle_idempotency_violation() # Proceed to update points await update_user_points(user_id, action) return {"status": "success"}
4. Ensure Worker Instances Handle Partitions Correctly
To prevent concurrency issues and data loss, ensure that each worker instance handles specific partitions based on
auth_user_uuid. This can be achieved by leveraging the partitioning capabilities of message brokers like Kafka.a. Partitioning Strategy
Ensure that the message broker partitions messages based on
auth_user_uuid. This guarantees that all messages for a specific user are handled by the same worker instance.For Kafka:
When producing messages, set the partition key to
auth_user_uuid.from kafka import KafkaProducer import json producer = KafkaProducer(bootstrap_servers='kafka:9092') def send_claim_message(user_uuid: str, claim_data: dict): producer.send( 'claims_topic', key=user_uuid.encode('utf-8'), value=json.dumps(claim_data).encode('utf-8') ) producer.flush()b. Worker Configuration
Configure each worker instance to consume from specific partitions. This can be managed automatically by Kafka consumer groups, where each consumer in a group is assigned distinct partitions.
from aiokafka import AIOKafkaConsumer async def consume(): consumer = AIOKafkaConsumer( 'claims_topic', bootstrap_servers='kafka:9092', group_id='claims_group', key_deserializer=lambda m: m.decode('utf-8'), value_deserializer=lambda m: json.loads(m.decode('utf-8')) ) await consumer.start() try: async for msg in consumer: await process_claim(msg.key, msg.value['action'], msg.value.get('task_uuid')) finally: await consumer.stop() # Run consumer in each worker instance import asyncio asyncio.run(consume())This setup ensures that all messages for a
user_uuidare directed to the same partition and thus handled by a single worker instance, preventing concurrent processing of the same user's claims.
5. Database Schema Adjustments
a. Idempotency Keys Table
As mentioned earlier, create a table to store idempotency keys per user and action.
CREATE TABLE user_idempotency_keys ( user_uuid UUID NOT NULL, action VARCHAR(50) NOT NULL, idempotency_key VARCHAR(255) NOT NULL, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (user_uuid, action) );b. Claims Event Log Table
Create a separate table to log claim events, ensuring idempotency and preventing duplicate claims.
CREATE TABLE claims_event_log ( id SERIAL PRIMARY KEY, user_uuid UUID NOT NULL, action VARCHAR(50) NOT NULL, idempotency_key VARCHAR(255) NOT NULL, timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, UNIQUE (user_uuid, action, idempotency_key) );c. SQLAlchemy Models
Define SQLAlchemy models for the new tables.
from sqlalchemy import Column, String, DateTime, func from sqlalchemy.dialects.postgresql import UUID from sqlalchemy.ext.declarative import declarative_base Base = declarative_base() class UserIdempotencyKey(Base): __tablename__ = 'user_idempotency_keys' user_uuid = Column(UUID(as_uuid=True), primary_key=True) action = Column(String(50), primary_key=True) idempotency_key = Column(String(255), nullable=False) updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now()) class ClaimsEventLog(Base): __tablename__ = 'claims_event_log' id = Column(Integer, primary_key=True, autoincrement=True) user_uuid = Column(UUID(as_uuid=True), nullable=False) action = Column(String(50), nullable=False) idempotency_key = Column(String(255), nullable=False) timestamp = Column(DateTime(timezone=True), server_default=func.now()) __table_args__ = ( UniqueConstraint('user_uuid', 'action', 'idempotency_key', name='_user_action_key_uc'), )
Putting It All Together
Below is an integrated example that encompasses the points above:
import uuid import datetime from enum import Enum from fastapi import FastAPI, HTTPException, Depends, Header from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy import select, insert, UniqueConstraint from sqlalchemy.exc import IntegrityError from aiokafka import AIOKafkaConsumer import json app = FastAPI() # Enums as defined earlier class ClaimType(Enum): DIRECT = "direct" REF = "ref" CONVERT = "convert" class Action(Enum): DAILY_TAP = "daily_tap" REF_POINTS_ACQUIRE = "ref_points_acquire" REF_POINTS_CLAIM = "ref_points_claim" DAILY_LOGIN = "daily_login" LUCKY_BALL_CLAIM = "lucky_ball_claim" TASK_COMPLETED = "task_completed" # Utility Functions def calculate_cooldown(action: Action, streak: int, last_claim_time: Optional[datetime.datetime] = None) -> Optional[datetime.timedelta]: # Implementation as defined earlier ... async def get_user(user_id: str) -> User: # Fetch user from DB ... async def get_last_claim_time(user_id: str, action: Action) -> Optional[datetime.datetime]: # Fetch last claim time from claims_event_log ... async def get_or_create_idempotency_key(user_id: str, action: Action, db: AsyncSession) -> str: # Implementation as defined earlier ... def handle_cooldown_violation(): # Implementation as defined earlier ... def handle_idempotency_violation(): # Implementation as defined earlier ... async def update_user_points(user_id: str, action: Action): # Update user points based on action ... async def handle_task_completed(user_id: str, task_uuid: str): async with db_session() as db: existing = await db.execute( select(ClaimsEventLog).where( ClaimsEventLog.user_uuid == user_id, ClaimsEventLog.action == Action.TASK_COMPLETED.value, ClaimsEventLog.idempotency_key == task_uuid ) ) if existing.scalar_one_or_none(): return handle_idempotency_violation() # Log the task completion await db.execute( insert(ClaimsEventLog).values( user_uuid=user_id, action=Action.TASK_COMPLETED.value, idempotency_key=task_uuid ) ) await db.commit() # Update points await update_user_points(user_id, Action.TASK_COMPLETED) return {"status": "success"} async def handle_standard_claim(user_id: str, action: Action, idempotency_key: str): async with db_session() as db: try: await db.execute( insert(ClaimsEventLog).values( user_uuid=user_id, action=action.value, idempotency_key=idempotency_key ).on_conflict_do_nothing() ) await db.commit() except IntegrityError: return handle_idempotency_violation() await update_user_points(user_id, action) return {"status": "success"} # API Endpoint @app.post("/claim") async def claim_action( action: Action, user_id: str, task_uuid: Optional[str] = None, idempotency_key: Optional[str] = Header(None) ): if action == Action.TASK_COMPLETED and not task_uuid: raise HTTPException(status_code=400, detail="task_uuid is required for TASK_COMPLETED") async with db_session() as db: user = await get_user(user_id) streak = user.streak last_claim_time = await get_last_claim_time(user_id, action) cooldown = calculate_cooldown(action, streak, last_claim_time) if cooldown: if datetime.datetime.utcnow() < last_claim_time + cooldown: return handle_cooldown_violation() if action == Action.TASK_COMPLETED: return await handle_task_completed(user_id, task_uuid) else: if not idempotency_key: idempotency_key = await get_or_create_idempotency_key(user_id, action, db) return await handle_standard_claim(user_id, action, idempotency_key) # Worker Process async def process_claim(user_id: str, action: str, task_uuid: Optional[str] = None): action_enum = Action(action) await process_claim_logic(user_id, action_enum, task_uuid) async def consume(): consumer = AIOKafkaConsumer( 'claims_topic', bootstrap_servers='kafka:9092', group_id='claims_group', key_deserializer=lambda m: m.decode('utf-8'), value_deserializer=lambda m: json.loads(m.decode('utf-8')) ) await consumer.start() try: async for msg in consumer: user_id = msg.key action = msg.value['action'] task_uuid = msg.value.get('task_uuid') await process_claim(user_id, action, task_uuid) finally: await consumer.stop() # Startup Event to launch consumer @app.on_event("startup") async def startup_event(): asyncio.create_task(consume()) # Database Session Dependency from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession from sqlalchemy.orm import sessionmaker DATABASE_URL = "postgresql+asyncpg://user:password@localhost/dbname" engine = create_async_engine(DATABASE_URL, echo=True) AsyncSessionLocal = sessionmaker(engine, expire_on_commit=False, class_=AsyncSession) async def db_session(): async with AsyncSessionLocal() as session: yield session
Summary of Changes
- Action and Claim Type Definitions: Introduced Enums for clarity and type safety.
- Cooldown Logic: Implemented dynamic cooldown calculations based on action type and user streak.
- Idempotency Keys: Managed idempotency using a dedicated database table, ensuring unique claims per user and action.
- Violation Handling: Ensured that any cooldown or idempotency violations result in skipped claims without affecting user points or state.
- Worker Partitioning: Configured Kafka to partition messages by
user_uuid, ensuring single-worker processing per user to prevent concurrency issues. - Database Schema Enhancements: Added new tables to manage idempotency keys and log claim events, enforcing uniqueness to prevent duplicate processing.
By following the above guide, your FastAPI application and worker processes should effectively handle the new business logic, ensuring data integrity, preventing duplicate claims, and managing cooldowns appropriately.
If you have any specific questions or need further assistance with any of the steps, feel free to ask!