Jobs

jobs

This module defines the jobs_router of the Mirumoji API

Exposes endpoints for submitting a long-running operation which uses an existing profile file, and tracking its status by polling

Attributes:

Name	Type	Description
LOGGER	Logger	Module's logging object
jobs_router	APIRouter	The FastAPI router object

cancel_job(job_id, profile_id=Depends(ensure_profile_exists)) async

Cancels a queued or running job owned by the active profile

How Cancellation Works

• A queued job is skipped by the worker when it would otherwise run

• A running job is marked cancelled on a best-effort basis (it may still finish)

• Cancelling a batch parent cascades to its still-active children

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)

Returns:

Type	Description
JobResponse	The (possibly updated) job

Raises:

Type	Description
HTTPException	If the job isn't owned by the profile
RecordNotFoundError	If the job does not exist
DatabaseError	If the update fails

delete_job(job_id, profile_id=Depends(ensure_profile_exists), manager=Depends(get_job_manager)) async

Deletes a finished job owned by the active profile (its record, not its produced files)

A batch parent's child jobs are removed with it. A job that is still active (queued / running) or still being finished by the worker (a cancelled job whose handler has not returned yet) is refused, so the worker is never left holding a deleted row

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)
manager	JobQueueManager	The job worker	Depends(get_job_manager)

Raises:

Type	Description
HTTPException	If the job isn't owned by the profile, or is still active or in flight
RecordNotFoundError	If the job does not exist
DatabaseError	If the deletion fails

get_job(job_id, profile_id=Depends(ensure_profile_exists)) async

Fetches a single job owned by the active profile

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)

Returns:

Type	Description
JobResponse	The job

Raises:

Type	Description
HTTPException	If the job isn't owned by the profile
RecordNotFoundError	If the job does not exist
DatabaseError	If the lookup fails

list_job_children(job_id, profile_id=Depends(ensure_profile_exists)) async

Lists the per-file child jobs of a batch parent owned by the profile

Single-op jobs have no children and return an empty list

Parameters:

Name	Type	Description	Default
job_id	UUID	The parent job id	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)

Returns:

Type	Description
list[JobResponse]	The child jobs, in submit order

Raises:

Type	Description
HTTPException	If the parent isn't owned by the profile
RecordNotFoundError	If the parent does not exist
DatabaseError	If the query fails

list_jobs(active=False, profile_id=Depends(ensure_profile_exists)) async

Lists the active profile's top-level jobs (batch children are excluded)

Parameters:

Name	Type	Description	Default
active	bool	Restrict to queued / running jobs	False
profile_id	str	Validated profile id	Depends(ensure_profile_exists)

Returns:

Type	Description
list[JobResponse]	The profile's jobs, newest first

Raises:

Type	Description
DatabaseError	If the query fails

submit_batch(req, profile_id=Depends(ensure_profile_exists), manager=Depends(get_job_manager)) async

Submits a batch job that runs one operation across several profile files

How It Works

• Creates a parent job + one queued child job per file_id

• enqueues the parent, and returns it for the client to track

• The worker runs the parent, which either runs the children in parallel or one at a time depending on the handler

• Per-file status lives on the children, reachable via GET /jobs/{id}/children

Parameters:

Name	Type	Description	Default
req	SubmitBatchRequest	The batch submission	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)
manager	JobQueueManager	The job worker	Depends(get_job_manager)

Returns:

Type	Description
JobResponse	The created parent job (202 Accepted)

Raises:

Type	Description
HTTPException	If a file_id is malformed or not owned by the profile
DatabaseError	If persistence fails

submit_job(req, profile_id=Depends(ensure_profile_exists), manager=Depends(get_job_manager)) async

Submits a long-running job to perform an operation on an existing profile file

Creates a queued job referencing req.file_id, enqueues it, and returns immediately with the job to track. The worker then runs the operation

Parameters:

Name	Type	Description	Default
req	SubmitJobRequest	The job submission	required
profile_id	str	Validated profile id	Depends(ensure_profile_exists)
manager	JobQueueManager	The job worker	Depends(get_job_manager)

Returns:

Type	Description
JobResponse	The created job (202 Accepted)

Raises:

Type	Description
HTTPException	If file_id is malformed or not owned by the profile
DatabaseError	If persistence fails