14 · Starting Background Work Without Carrying the Request With It
In the previous lesson, the browser polled:
GET /documents/101/statusand watched the database status change:
pending→ processing→ completedBut polling only observed the work. Nothing actually performed the review.
Today we add that missing half.
The user will click Start review. The browser will send a write request, FastAPI will authorize it, the service will mark the document as pending, and the server will return immediately.
Only after that response has been returned will a background function begin the slower review.
The two sides work independently:
Start requestBrowser → POST → FastAPI → SQLite → 202 Accepted ↓ background task begins ↓ processing → completed
Status observationBrowser → repeated GET requests → SQLite → current statusThe background task changes the database. Polling informs the browser about those changes.
The new document begins as not_started, as established in lessons 8 and 9. Only an accepted start request moves it to pending. A newly created document is therefore eligible for its first review.
Those are still two separate mechanisms.
Where today’s code sits
Section titled “Where today’s code sits”The complete lifecycle is now:
Browser click→ JavaScript POST request→ session middleware→ authentication dependency→ document authorization→ action authorization→ CSRF validation→ router→ service marks document pending→ SQLAlchemy commits to SQLite→ FastAPI returns 202 Accepted→ browser begins polling→ background function opens a new SQLAlchemy Session→ background function marks document processing→ slow review runs→ background function marks document completed or failed→ polling discovers the final status→ JavaScript updates the DOMThe most important boundary today is between:
The request that schedules the workand:
The later function that performs the workThey must not share a SQLAlchemy Session.
The Jinja page
Section titled “The Jinja page”We add a Start review button to the document page:
<section id="review-panel" data-status-url="{{ url_for( 'document_status', document_id=review_document.id ) }}"> <p> Review status: <strong id="review-status"> {{ review_document.status }} </strong> </p>
<button id="start-review" type="button" data-start-url="{{ url_for( 'start_document_review', document_id=review_document.id ) }}" > Start review </button>
<button id="check-status" type="button" disabled > Check now </button>
<p id="status-message" role="status" aria-live="polite" ></p></section>
<meta name="csrf-token" content="{{ csrf_token }}">Jinja produces concrete URLs such as:
data-start-url="/documents/101/review"data-status-url="/documents/101/status"The CSRF token is also generated by the server and placed in the page.
A simplified page route can prepare it like this:
import secrets
from fastapi import Request
@router.get("/{document_id}", response_class=HTMLResponse)def document_page( request: Request, document: AuthorizedDocument,): csrf_token = request.session.get("csrf_token")
if csrf_token is None: csrf_token = secrets.token_urlsafe(32) request.session["csrf_token"] = csrf_token
return templates.TemplateResponse( request=request, name="documents/detail.html", context={ "review_document": document, "csrf_token": csrf_token, }, headers={"Cache-Control": "no-store"}, )The token is not an authentication credential. It is an unpredictable value tying the write request to a page that our application rendered for this browser session.
The CSRF dependency
Section titled “The CSRF dependency”Because the browser authenticates using a cookie, a malicious website might attempt to cause the browser to submit a request to our application.
The browser may attach applicable cookies automatically. Therefore, a write request needs CSRF protection in addition to authentication.
Here is a small dependency:
import secretsfrom typing import Annotated
from fastapi import Depends, HTTPException, Request, status
def require_csrf(request: Request) -> None: expected_token = request.session.get("csrf_token") submitted_token = request.headers.get("X-CSRF-Token")
if ( expected_token is None or submitted_token is None or not secrets.compare_digest( expected_token.encode("utf-8"), submitted_token.encode("utf-8"), ) ): raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="Invalid CSRF token", )
CsrfProtected = Annotated[ None, Depends(require_csrf),]The dependency obtains two values:
expected_token→ Previously stored in the authenticated browser session
submitted_token→ Sent explicitly by our JavaScriptcompare_digest() performs the comparison without the timing behavior of a casual string comparison.
This dependency answers:
Did this write request include the token issued to the current browser session?
It does not answer:
Is this user allowed to review this document?
That remains a separate authorization question.
Action authorization
Section titled “Action authorization”Our existing AuthorizedDocument dependency proves that the current user may access this document.
But viewing and starting a review may require different permissions.
from typing import Annotated
from fastapi import Depends, HTTPException, status
def require_review_operator( current_user: CurrentUserDep,) -> dict: if current_user["role"] not in { "reviewer", "admin", }: raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, detail="Review permission required", )
return current_user
ReviewOperator = Annotated[ dict, Depends(require_review_operator),]The route will therefore require both:
AuthorizedDocument→ This user may access document 101
ReviewOperator→ This user may start review operationsHiding the button from unauthorized users would improve the interface, but it would not enforce anything. A user could construct the POST request manually.
The server must enforce both rules.
The service that queues the state change
Section titled “The service that queues the state change”Before scheduling background work, we make the pending state durable.
from sqlalchemy import updatefrom sqlalchemy.orm import Session
from ..models.documents import Document
ACTIVE_REVIEW_STATUSES = { "pending", "processing",}
class ReviewAlreadyRunningError(Exception): pass
def queue_document_review( *, db: Session, document: Document,) -> int: if document.status in ACTIVE_REVIEW_STATUSES: raise ReviewAlreadyRunningError( "A review is already running" )
transition = db.execute( update(Document) .where( Document.id == document.id, Document.status.in_({ "not_started", "completed", "failed", }), ) .values(status="pending") )
if transition.rowcount != 1: db.rollback() raise ReviewAlreadyRunningError( "A review cannot be started in the current state" )
db.commit()
return document.idThis is ordinary service-layer logic.
It receives a SQLAlchemy session and an authorized document. It does not know about JavaScript, HTTP headers, CSRF tokens, or response status codes.
The business rule is:
if document.status in ACTIVE_REVIEW_STATUSES:If the document is already pending or processing, starting another review would create two competing operations.
The service raises an application exception:
raise ReviewAlreadyRunningError(...)The route will translate that into an HTTP response.
The Python check makes the business rule easy to read. The conditional SQL UPDATE is the final guard when two requests arrive together: SQLite changes a row only while its stored state is still startable. A second caller cannot rely on an earlier Python object to prove the review is still idle.
If the operation is allowed, the conditional statement sets:
.values(status="pending")The surrounding db.execute() sends that UPDATE to SQLite immediately inside the current transaction. The change is not committed yet.
The important line is:
db.commit()SQLite commits the transaction containing that UPDATE.
Only after that commit can another database session reliably observe:
status = pendingThat includes both the polling requests and the background function.
The response model
Section titled “The response model”The start endpoint returns a small acknowledgment:
from typing import Literal
from pydantic import BaseModel
class ReviewAccepted(BaseModel): document_id: int status: Literal["pending"] status_url: strA successful response will resemble:
{ "document_id": 101, "status": "pending", "status_url": "/documents/101/status"}This does not claim that the review succeeded.
It says:
The server accepted the request and recorded the operation as pending.
The FastAPI route
Section titled “The FastAPI route”Here is the complete start endpoint:
from fastapi import ( BackgroundTasks, HTTPException, Request, Response, status,)
@router.post( "/{document_id}/review", response_model=ReviewAccepted, status_code=status.HTTP_202_ACCEPTED,)def start_document_review( request: Request, response: Response, background_tasks: BackgroundTasks, document: AuthorizedDocument, operator: ReviewOperator, csrf: CsrfProtected, db: DbSession,): try: document_id = queue_document_review( db=db, document=document, )
except ReviewAlreadyRunningError as exc: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(exc), ) from exc
status_url = str( request.url_for( "document_status", document_id=document_id, ) )
background_tasks.add_task( process_document_review, document_id, )
response.headers["Location"] = status_url
return ReviewAccepted( document_id=document_id, status="pending", status_url=status_url, )Let’s follow it in execution order.
FastAPI prepares the route arguments
Section titled “FastAPI prepares the route arguments”The browser sends:
POST /documents/101/review HTTP/1.1Cookie: app_session=...X-CSRF-Token: T0jN...Accept: application/jsonThere is no request body today. The document ID is already in the URL.
Before calling the route, FastAPI resolves the dependency graph.
It obtains:
document→ SQLAlchemy Document authorized for this user
operator→ Authenticated user with reviewer or admin permission
csrf→ Successful CSRF validation
db→ Request-scoped SQLAlchemy SessionThe variables operator and csrf are not otherwise used in the function body.
That is intentional. Their presence in the signature means:
Do not enter this route unless these dependencies succeed.
If authentication, authorization, document lookup, or CSRF validation fails, the service is never called and no background task is scheduled.
Marking the document pending first
Section titled “Marking the document pending first”The route calls:
document_id = queue_document_review( db=db, document=document,)The service commits the pending state before the route schedules the background function.
This ordering matters.
A dangerous sequence would be:
Schedule background work→ return response→ eventually record that work was requestedThe background function could begin before the request transaction becomes visible. Or the application could return success but fail before recording any status.
Our sequence is clearer:
Validate request→ commit pending state→ schedule background function→ return acknowledgmentIt still is not perfectly durable, as we’ll see shortly, but the database has at least recorded the intended state before the response leaves.
Adding the background task
Section titled “Adding the background task”The route calls:
background_tasks.add_task( process_document_review, document_id,)background_tasks is a FastAPI-provided object. We did not construct it ourselves and did not wrap it in Depends().
The first argument is a function reference:
process_document_reviewThere are no parentheses. We are giving FastAPI a function to call later.
The second argument:
document_idwill be supplied when that function is called.
Conceptually, FastAPI records:
After the response:call process_document_review(101)add_task() does not call the function at that line.
FastAPI documents BackgroundTasks as a mechanism for running work after returning a response and recommends it for relatively small same-process tasks; heavier work may warrant a separate worker system. FastAPI background-task documentation
Why we pass an ID
Section titled “Why we pass an ID”Notice what we do not pass:
background_tasks.add_task( process_document_review, db, document, request, operator,)That would carry request-bound objects into work that happens later.
Instead, we pass:
document_idAn integer is stable, serializable, and contains no open database connection or transaction state.
The background function can use that identifier to load current data through its own database session.
This boundary is worth remembering:
Request hands background work:→ IDs→ strings→ numbers→ immutable configuration
Request should not hand background work:→ request-scoped Session→ ORM objects attached to that Session→ Request object→ open file handles owned by the requestAn ORM object is not simply a bag of values. It is associated with SQLAlchemy session state. Passing it between concurrent units of work can produce stale data, detached-object errors, or unsafe session sharing.
SQLAlchemy’s documented concurrency model is “Session per thread, AsyncSession per task,” with sessions kept locally scoped through context managers. SQLAlchemy session-concurrency documentation
Returning 202 Accepted
Section titled “Returning 202 Accepted”The route returns:
ReviewAccepted( document_id=document_id, status="pending", status_url=status_url,)FastAPI serializes it through the Pydantic response model and creates:
HTTP/1.1 202 AcceptedContent-Type: application/jsonLocation: /documents/101/status
{ "document_id": 101, "status": "pending", "status_url": "/documents/101/status"}202 Accepted specifically means that processing has been accepted but has not necessarily completed—or even started yet. The initial HTTP exchange cannot later transform itself into a second response reporting the final result. MDN’s 202 Accepted reference
That is why the response supplies:
status_urlThe browser can use another communication mechanism—currently polling—to discover what happens later.
A 202 response means:
The request to begin was accepted.It does not mean:
The review completed successfully.The background function
Section titled “The background function”After the response has been returned, FastAPI runs:
process_document_review(101)Here is our simplified implementation:
import loggingimport timefrom typing import Literal
from ..database import SessionLocalfrom ..models.documents import Document
logger = logging.getLogger(__name__)
StoredReviewStatus = Literal[ "processing", "completed", "failed",]
def process_document_review( document_id: int,) -> None: try: set_review_status( document_id=document_id, new_status="processing", )
run_document_analysis( document_id=document_id, )
set_review_status( document_id=document_id, new_status="completed", )
except Exception: logger.exception( "Document review failed", extra={"document_id": document_id}, )
set_review_status( document_id=document_id, new_status="failed", )
def set_review_status( *, document_id: int, new_status: StoredReviewStatus,) -> None: with SessionLocal.begin() as db: document = db.get( Document, document_id, )
if document is None: raise LookupError( f"Document {document_id} no longer exists" )
document.status = new_status
def run_document_analysis( *, document_id: int,) -> None: # Placeholder for file extraction, an external API, # or another slow review operation. time.sleep(5)The five-second sleep merely makes the lifecycle visible. A real service would call the document-analysis code here.
A fresh session for each status change
Section titled “A fresh session for each status change”The helper begins:
with SessionLocal.begin() as db:Recall that:
SessionLocal→ Application-level session factory
SessionLocal.begin()→ New Session plus a transaction contextThis session is unrelated to the db object used by the POST request.
Inside the context, Python loads the document:
document = db.get( Document, document_id,)SQLAlchemy asks SQLite for the row whose primary key is 101.
Then:
document.status = new_statuschanges the ORM object.
When the with block exits normally, SQLAlchemy:
flushes the UPDATE→ commits the transaction→ closes the SessionIf an exception leaves the block, it rolls back and closes instead. This transaction-scoped sessionmaker.begin() pattern is part of SQLAlchemy’s recommended session lifecycle. SQLAlchemy session basics
The first call stores:
pending → processingThe session then closes before the slow analysis begins.
That detail is valuable.
Do not hold a database transaction open during slow work
Section titled “Do not hold a database transaction open during slow work”The document operation runs here:
run_document_analysis( document_id=document_id,)It may take several seconds or minutes.
We deliberately do not keep the previous SQLAlchemy session and transaction open during that wait.
The flow is:
Open Session→ write processing→ commit→ close Session
Perform slow external work
Open new Session→ write completed→ commit→ close SessionHolding an open transaction throughout a slow AI call would:
- Keep database resources occupied.
- Delay visibility of state changes.
- Increase SQLite locking pressure.
- Make transaction failures more expensive.
- Combine two unrelated lifetimes: database work and external processing.
A transaction should usually cover one coherent database operation, not the entire wall-clock lifetime of a slow workflow.
How polling observes the changes
Section titled “How polling observes the changes”Shortly after the browser receives 202, it starts the polling loop from the previous lesson.
The first poll might see:
{ "id": 101, "status": "pending"}The background function then commits processing.
The next poll creates its own request-scoped session and sees:
{ "id": 101, "status": "processing"}After the analysis succeeds, the background function opens another session and commits completed.
A later poll sees:
{ "id": 101, "status": "completed"}The polling loop stops and updates the page.
The background function never talks directly to the browser:
Background function→ writes SQLite
Polling endpoint→ reads SQLite
JavaScript→ displays the returned statusIf the user closes the browser, the task may continue.
If JavaScript polling fails because the network drops, the task may continue.
If the task fails, polling may still work perfectly and eventually display failed.
The browser’s start request
Section titled “The browser’s start request”Here is the JavaScript that connects the button to the new route:
This extends the polling script from lesson 13. Keep its existing panel, statusElement, and messageElement declarations once in the combined file; the declarations below show those inputs again for reading context. Redeclaring the same top-level const names twice would prevent the script from running.
const startButton = document.querySelector("#start-review");
const panel = document.querySelector("#review-panel");
const statusElement = document.querySelector("#review-status");
const messageElement = document.querySelector("#status-message");
const csrfToken = document.querySelector( 'meta[name="csrf-token"]' ).content;
startButton.addEventListener( "click", startReview,);
async function startReview() { startButton.disabled = true; messageElement.textContent = "Starting review…";
try { const response = await fetch( startButton.dataset.startUrl, { method: "POST", headers: { Accept: "application/json", "X-CSRF-Token": csrfToken, }, }, );
if (response.status === 401) { throw new Error( "Your session expired." ); }
if (response.status === 403) { throw new Error( "You cannot start this review." ); }
if (response.status === 409) { throw new Error( "A review is already running." ); }
if (!response.ok) { throw new Error( "The review could not be started." ); }
const data = await response.json();
statusElement.textContent = data.status; panel.dataset.statusUrl = data.status_url;
messageElement.textContent = "Review accepted. Waiting for progress…";
startPolling();
} catch (error) { messageElement.textContent = error instanceof TypeError ? "Connection problem. Please try again." : error.message;
startButton.disabled = false; }}The write request uses:
method: "POST"The authentication cookie is included automatically for this same-origin request.
The CSRF token is explicit:
"X-CSRF-Token": csrfTokenJavaScript cannot grant authorization. It merely supplies the token and initiates the request. FastAPI still checks the session, role, document access, and CSRF token.
After parsing the 202 response, JavaScript changes the visible status to:
pendingand calls the existing:
startPolling();The background task and polling loop now proceed independently.
What if the POST response is lost?
Section titled “What if the POST response is lost?”Suppose FastAPI commits:
status = pendingbut the browser loses its connection before receiving the 202 response.
The browser sees a network failure and cannot safely conclude:
The operation did not start.The server may already have accepted it.
If the user retries, the service’s active-status check will ordinarily produce:
409 ConflictThe conditional update protects the active-state transition when two callers race. An idempotency key adds another benefit: it lets a retry identify the already accepted operation and return it successfully. Lesson 19 introduces that distinction.
A disabled button is not concurrency control. Two tabs, two devices, or a manually constructed request can still race.
The major limitation of BackgroundTasks
Section titled “The major limitation of BackgroundTasks”FastAPI’s built-in background task runs in the application process.
That gives us a dangerous gap:
SQLite commits pending→ response returns 202→ application process crashes→ background task never finishesAfter a restart, SQLite still contains:
status = pendingBut the function call that existed only in process memory is gone.
The browser may poll forever.
Built-in background tasks ordinarily do not provide:
- Durable job storage
- Automatic retries
- Crash recovery
- Worker leases
- Dead-letter handling
- Cross-server coordination
- Job monitoring
- Independent worker scaling
They are appropriate for small, best-effort work such as sending a noncritical notification or writing an audit supplement.
A document review whose result matters should generally be represented as a durable job.
What the durable version changes
Section titled “What the durable version changes”A durable version might introduce a migrated review_jobs table:
review_jobs├── id├── document_id├── status├── attempt_count├── available_at├── started_at├── finished_at└── last_errorThe start request would commit both:
documents.status = pendingreview_jobs.status = queuedin one database transaction.
A separate worker process would repeatedly look for queued jobs:
Worker starts→ claims queued job→ marks it running→ performs review→ stores result→ marks job completedIf the web server restarts, the job row remains in SQLite.
If the worker fails, another worker can retry the persisted job according to explicit rules.
The durable architecture becomes:
Browser POST→ FastAPI validates and authorizes→ SQLite records durable job→ 202 Accepted
Independent worker→ claims durable job→ performs analysis→ stores progress and result
Browser polling→ reads durable state→ updates pageFor a small deployment, a database-backed worker may be sufficient. Larger deployments commonly use a dedicated queue and worker system.
That adds infrastructure and operational complexity, but it solves a fundamentally different problem:
BackgroundTasks→ Do this later if this application process stays alive.
Durable job→ Record that this work must eventually be attempted, even across crashes and restarts.Alembic would manage the new review_jobs table just as it managed the earlier document-schema changes.
The complete lifecycle
Section titled “The complete lifecycle”For a successful built-in background review:
- Jinja renders the document page and CSRF token.
- The browser constructs the DOM and registers the click handler.
- The user clicks Start review.
- JavaScript disables the button.
fetch()sends an authenticatedPOST.- Session middleware reconstructs the browser session.
- FastAPI matches the start route.
- Dependencies authenticate the user.
- Authorization checks document access and reviewer permission.
- The CSRF dependency verifies the submitted token.
- The request-scoped SQLAlchemy session loads the document.
- The service checks that no review is active.
- The service changes the status to
pending. - SQLAlchemy commits the change to SQLite.
- The route registers a background function using only the document ID.
- FastAPI returns
202 Acceptedand the status URL. - JavaScript parses the acknowledgment.
- JavaScript updates the DOM to
pending. - JavaScript starts polling.
- FastAPI runs the background function.
- The background function creates its own SQLAlchemy session.
- It commits
processingand closes that session. - The slow review runs without an open database transaction.
- The background function opens another session.
- It commits
completedorfailed. - A polling request reads the final status.
- JavaScript updates the DOM and stops polling.
The route accepts and records the request. The background function performs the work. SQLite holds the shared state. Polling carries that state to the browser.
The central lesson is not merely how to call add_task().
It is the lifetime boundary:
Request lifetime→ authentication→ authorization→ request transaction→ 202 response→ request session closes
Background-work lifetime→ receives stable identifiers→ creates its own database sessions→ commits visible progress→ succeeds or fails independentlyIn the next installment, we’ll keep the same background workflow but replace repeated polling requests with Server-Sent Events. The server will stream one-way status updates to the browser over a longer-lived HTTP connection, while the background worker remains a separate concern.