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) 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	required

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, 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

Idempotent

• Deleting a job that is already gone succeeds, matching DELETE semantics and JobRepository.delete, which is a no-op on a missing row

• Deleting a file removes the jobs that reference it, so a client holding a list from before that delete would otherwise get a 404 it can never clear. The ownership and in-flight checks do not apply to a row that no longer exists

Parameters:

Name	Type	Description	Default
job_id	UUID	The job id	required
profile_id	str	Validated profile id	required
manager	JobQueueManager	The job worker	required

Raises:

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

get_job(job_id, profile_id) 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	required

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) 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	required

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(profile_id, active=False) async

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

Profile Optional

A poll that arrives without X-Profile-ID (a service-worker replay, which cannot inject the app header) returns an empty list rather than a 400, so it does not surface as a spurious error

Parameters:

Name	Type	Description	Default
profile_id	str | None	Validated profile id, or None when the header is absent	required
active	bool	Restrict to queued / running jobs	False

Returns:

Type	Description
list[JobResponse]	The profile's jobs, newest first, or an empty list when no profile is
list[JobResponse]	set

Raises:

Type	Description
DatabaseError	If the query fails

submit_batch(req, profile_id, 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	required
manager	JobQueueManager	The job worker	required

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, 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	required
manager	JobQueueManager	The job worker	required

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