⚡ Background Tasks

Lightweight background task execution for tenant-level operations with retry logic and status tracking.

🎯 Overview

Category	Components	Purpose
📦 Model	`TenantJob`	Tenant-level job record with retry support
⚡ Manager	`BackgroundTaskManager`	Submit, execute, and track background tasks

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    FastHTML Route                               │
│  return response, bg_task  ←─────────────────────┐              │
└─────────────────────────────────────────────────────────────────┘
                              │                    │
                              ▼                    │
┌─────────────────────────────────────────────────────────────────┐
│                 BackgroundTaskManager                           │
├─────────────────────────────────────────────────────────────────┤
│  submit()           → Create job + return BackgroundTask        │
│  _execute_with_retry() → Run with auto-retry on failure         │
│  get_job()          → Check job status                          │
│  list_jobs()        → Query jobs by type/status                 │
├─────────────────────────────────────────────────────────────────┤
│  Retry Logic: 2^n seconds backoff (2s, 4s, 8s)                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Tenant Database                              │
│                    └── tenant_jobs table                        │
└─────────────────────────────────────────────────────────────────┘

📚 Quick Reference

Job Status Flow

pending → running → completed
    ↑        │
    └────────┴──→ failed (after max retries)

Usage Pattern

# In your FastHTML route
manager = BackgroundTaskManager(tenant_db)
job_id, bg_task = manager.submit("sync_data", my_sync_func, user_id="123")
return response, bg_task  # Starlette runs bg_task after response

📦 TenantJob Model

Tracks background jobs at the tenant level with retry support.

Field	Type	Description
`id`	str	Unique job identifier
`job_type`	str	Job category (e.g., “sync”, “email”)
`status`	str	`pending` / `running` / `completed` / `failed`
`payload`	str	JSON kwargs passed to task function
`result`	str	JSON result on completion
`error_log`	str	Stack trace on failure
`retry_count`	int	Current retry attempt
`max_retries`	int	Max attempts before marking failed

source

TenantJob


def TenantJob(
    args:VAR_POSITIONAL, kwargs:VAR_KEYWORD
):

Tenant-level background job with retry support.

⚡ BackgroundTaskManager

Submit and track background tasks with automatic retry logic.

Method	Purpose
`submit`	Create job and return BackgroundTask for Starlette
`get_job`	Get job status and details by ID
`list_jobs`	Query jobs with optional type/status filters

💡 Use case: Long-running operations like syncing data, sending emails, or processing uploads

source

BackgroundTaskManager


def BackgroundTaskManager(
    db:Database
):

Lightweight background task manager for tenant-level operations.

source

BackgroundTaskManager.list_jobs


def list_jobs(
    job_type:Optional=None, status:Optional=None, limit:int=100
)->list:

List jobs with optional filtering.

source

BackgroundTaskManager.get_job


def get_job(
    job_id:str
)->TenantJob:

Get job status and details.

source

BackgroundTaskManager.submit


def submit(
    job_type:str, task_func:Callable, max_retries:int=3, task_kwargs:VAR_KEYWORD
)->tuple:

Submit a new background task for execution.