rust-job-queue-api-worker-system 0.1.0

A production-shaped Rust job queue: Axum API + async workers + Postgres SKIP LOCKED dequeue, retries with decorrelated jitter, idempotency, cooperative cancellation, OpenAPI, Prometheus metrics.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

//! OpenAPI 3.0 spec assembled from `#[utoipa::path]` annotations on the
//! route handlers and `#[derive(utoipa::ToSchema)]` on the DTOs.
//!
//! [`ApiDoc`] is the assembly point. It enumerates:
//!
//! - `paths(...)` — every handler the spec should document. Add a new
//!   handler here when adding a new route.
//! - `components(schemas(...))` — every Rust type referenced by the
//!   path annotations. utoipa cannot auto-discover these because the
//!   `body = ...` references in `#[utoipa::path]` are macro inputs, not
//!   real type uses, so the schemas have to be listed explicitly.
//! - `tags(...)` — logical grouping in Swagger UI.
//!
//! The struct itself is empty — its only purpose is to be the target of
//! the `#[derive(OpenApi)]` macro, which adds an inherent
//! `ApiDoc::openapi()` method that returns the assembled spec.

use utoipa::OpenApi;

use crate::api::dto::{CancelResponse, CreateJobRequest, ErrorBody, HealthResponse, JobResponse};
use crate::api::routes;
use crate::domain::{JobKind, JobStatus};
use crate::ids::JobId;

/// The crate's OpenAPI document. Serialise via `ApiDoc::openapi()`
/// (provided by the `#[derive(OpenApi)]` macro) and mount under
/// Swagger UI in [`crate::api::app::build_router`].
#[derive(OpenApi)]
#[openapi(
    info(
        title = "Rust Job Queue API",
        description = "Production-shaped job queue with Postgres SKIP LOCKED dequeue, retries, idempotency, cooperative cancellation, and Prometheus metrics.",
        version = "0.1.0",
        license(name = "Apache-2.0"),
    ),
    paths(
        routes::jobs::create_job,
        routes::jobs::get_job,
        routes::jobs::list_jobs,
        routes::jobs::cancel_job,
        routes::health::health,
        routes::metrics::metrics,
    ),
    components(schemas(
        CreateJobRequest,
        JobResponse,
        CancelResponse,
        HealthResponse,
        ErrorBody,
        JobKind,
        JobStatus,
        JobId,
    )),
    tags(
        (name = "jobs", description = "Create, fetch, list, and cancel jobs"),
        (name = "ops", description = "Operational endpoints: health, metrics"),
    ),
)]
pub struct ApiDoc;