mainframe.endpoints.job
=======================

.. py:module:: mainframe.endpoints.job


Attributes
----------

.. autoapisummary::

   mainframe.endpoints.job.router
   mainframe.endpoints.job.logger


Functions
---------

.. autoapisummary::

   mainframe.endpoints.job.require_assignment_id
   mainframe.endpoints.job.dead_letter_expired_scans
   mainframe.endpoints.job.get_jobs


Module Contents
---------------

.. py:data:: router

.. py:data:: logger
   :type:  structlog.stdlib.BoundLogger

.. py:function:: require_assignment_id(scan: mainframe.models.orm.Scan) -> uuid.UUID

   Return a claimed scan's assignment ID or fail on a broken database invariant.


.. py:function:: dead_letter_expired_scans(session: sqlalchemy.orm.Session, *, retry_before: datetime.datetime, dead_lettered_at: datetime.datetime, max_job_attempts: int) -> list[mainframe.models.orm.Scan]

   Fail expired scans that have exhausted their worker assignment budget.


.. py:function:: get_jobs(session: Annotated[sqlalchemy.orm.Session, Depends(get_db)], auth: Annotated[mainframe.json_web_token.AuthenticationData, Depends(validate_token)], state: Annotated[mainframe.rules.Rules, Depends(get_rules)], batch: int = 1) -> list[mainframe.models.schemas.JobResult]

   Request one or more releases to work on.

   Clients can specify the number of jobs they want to be given using the `batch` query string parameter.
   If omitted, it defaults to `1`.

   Clients are assigned the oldest release in the queue, i.e., the release with the oldest `queued_at` time.

   We also consider releases with a `pending_at` older than `now() - JOB_TIMEOUT` to be queued at the current time.
   This way, timed out packages are always processed after newly queued packages.