2019-09-22 17:12:08 +00:00
|
|
|
#![deny(missing_docs)]
|
|
|
|
|
|
|
|
//! # Background Jobs Core
|
|
|
|
//! _basic types and traits for implementing a background jobs processor_
|
|
|
|
//!
|
|
|
|
//! This crate shouldn't be depended on directly, except in the case of implementing a custom jobs
|
|
|
|
//! processor. For a default solution based on Actix and Sled, look at the `background-jobs` crate.
|
2018-11-18 01:39:04 +00:00
|
|
|
|
2024-02-05 05:35:47 +00:00
|
|
|
mod box_error;
|
2021-09-16 22:50:32 +00:00
|
|
|
mod catch_unwind;
|
2018-11-18 01:39:04 +00:00
|
|
|
mod job;
|
2018-11-08 02:20:30 +00:00
|
|
|
mod job_info;
|
2018-11-18 01:39:04 +00:00
|
|
|
mod processor_map;
|
2018-11-08 02:20:30 +00:00
|
|
|
mod storage;
|
2024-01-08 00:52:09 +00:00
|
|
|
mod unsend_job;
|
2018-11-08 02:20:30 +00:00
|
|
|
|
|
|
|
pub use crate::{
|
2024-02-05 05:35:47 +00:00
|
|
|
box_error::BoxError,
|
2020-04-21 00:30:56 +00:00
|
|
|
job::{new_job, new_scheduled_job, process, Job},
|
2019-05-25 20:22:26 +00:00
|
|
|
job_info::{JobInfo, NewJobInfo, ReturnJobInfo},
|
2019-10-31 18:46:41 +00:00
|
|
|
processor_map::{CachedProcessorMap, ProcessorMap},
|
2019-05-28 00:01:21 +00:00
|
|
|
storage::{memory_storage, Storage},
|
2018-11-08 02:20:30 +00:00
|
|
|
};
|
2018-11-06 02:53:03 +00:00
|
|
|
|
2024-01-08 00:52:09 +00:00
|
|
|
pub use unsend_job::{JoinError, UnsendJob, UnsendSpawner};
|
2020-03-30 15:36:49 +00:00
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
#[derive(Debug, thiserror::Error)]
|
2020-04-21 00:30:56 +00:00
|
|
|
/// The error type returned by the `process` method
|
2018-11-05 02:13:06 +00:00
|
|
|
pub enum JobError {
|
2018-11-18 01:39:04 +00:00
|
|
|
/// Some error occurred while processing the job
|
2024-02-05 04:19:41 +00:00
|
|
|
#[error("{0}")]
|
2024-02-05 05:35:47 +00:00
|
|
|
Processing(#[from] BoxError),
|
2018-11-18 01:39:04 +00:00
|
|
|
|
|
|
|
/// Creating a `Job` type from the provided `serde_json::Value` failed
|
2020-03-21 02:31:03 +00:00
|
|
|
#[error("Could not make JSON value from arguments")]
|
2018-11-05 02:13:06 +00:00
|
|
|
Json,
|
2018-11-18 01:39:04 +00:00
|
|
|
|
2020-04-21 00:30:56 +00:00
|
|
|
/// This job type was not registered for this client
|
|
|
|
#[error("This job type was not registered for the client")]
|
|
|
|
Unregistered,
|
2018-11-05 02:13:06 +00:00
|
|
|
}
|
|
|
|
|
2024-01-08 22:27:46 +00:00
|
|
|
#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Indicate the state of a job after an attempted run
|
2019-05-25 20:22:26 +00:00
|
|
|
pub enum JobResult {
|
2019-09-22 17:12:08 +00:00
|
|
|
/// The job succeeded
|
2019-05-25 20:22:26 +00:00
|
|
|
Success,
|
2019-09-22 17:12:08 +00:00
|
|
|
|
|
|
|
/// The job failed
|
2019-05-25 20:22:26 +00:00
|
|
|
Failure,
|
2019-09-22 17:12:08 +00:00
|
|
|
|
2020-04-21 00:30:56 +00:00
|
|
|
/// The worker had no concept of this job
|
|
|
|
Unregistered,
|
2020-03-21 02:31:03 +00:00
|
|
|
|
|
|
|
/// The worker requesting this job closed
|
|
|
|
Unexecuted,
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
impl JobResult {
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Indicate a successful job
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn success() -> Self {
|
2019-05-25 20:22:26 +00:00
|
|
|
JobResult::Success
|
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Indicate a failed job
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn failure() -> Self {
|
2019-05-25 20:22:26 +00:00
|
|
|
JobResult::Failure
|
|
|
|
}
|
|
|
|
|
2020-04-21 00:30:56 +00:00
|
|
|
/// Indicate that the job was not registered for this worker
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn unregistered() -> Self {
|
2020-04-21 00:30:56 +00:00
|
|
|
JobResult::Unregistered
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job failed
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn is_failure(self) -> bool {
|
|
|
|
matches!(self, JobResult::Failure)
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job succeeded
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn is_success(self) -> bool {
|
|
|
|
matches!(self, JobResult::Success)
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job is missing it's processor
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn is_unregistered(self) -> bool {
|
|
|
|
matches!(self, JobResult::Unregistered)
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
2020-03-21 19:10:29 +00:00
|
|
|
|
|
|
|
/// Check if the job was returned without an execution attempt
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn is_unexecuted(self) -> bool {
|
|
|
|
matches!(self, JobResult::Unexecuted)
|
2020-03-21 19:10:29 +00:00
|
|
|
}
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2024-01-08 22:27:46 +00:00
|
|
|
#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Different styles for retrying jobs
|
2018-11-05 02:13:06 +00:00
|
|
|
pub enum Backoff {
|
|
|
|
/// Seconds between execution
|
2019-09-22 17:12:08 +00:00
|
|
|
///
|
|
|
|
/// For example, `Backoff::Linear(5)` will retry a failed job 5 seconds after the previous
|
|
|
|
/// attempt
|
2018-11-05 02:13:06 +00:00
|
|
|
Linear(usize),
|
|
|
|
|
|
|
|
/// Base for seconds between execution
|
2019-09-22 17:12:08 +00:00
|
|
|
///
|
|
|
|
/// For example, `Backoff::Exponential(2)` will retry a failed job 2 seconds after the first
|
|
|
|
/// failure, 4 seconds after the second failure, 8 seconds after the third failure, and 16
|
|
|
|
/// seconds after the fourth failure
|
2018-11-05 02:13:06 +00:00
|
|
|
Exponential(usize),
|
|
|
|
}
|
|
|
|
|
2024-01-08 22:27:46 +00:00
|
|
|
#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
|
2019-09-22 17:12:08 +00:00
|
|
|
/// How many times a job should be retried before giving up
|
2018-11-05 02:13:06 +00:00
|
|
|
pub enum MaxRetries {
|
|
|
|
/// Keep retrying forever
|
|
|
|
Infinite,
|
|
|
|
|
|
|
|
/// Put a limit on the number of retries
|
|
|
|
Count(usize),
|
|
|
|
}
|
|
|
|
|
2018-11-07 03:26:48 +00:00
|
|
|
impl MaxRetries {
|
2024-01-08 22:27:46 +00:00
|
|
|
fn compare(self, retry_count: u32) -> ShouldStop {
|
|
|
|
match self {
|
2018-11-07 03:26:48 +00:00
|
|
|
MaxRetries::Infinite => ShouldStop::Requeue,
|
2024-01-08 22:27:46 +00:00
|
|
|
MaxRetries::Count(count) => {
|
|
|
|
if (retry_count as usize) <= count {
|
2018-11-07 03:26:48 +00:00
|
|
|
ShouldStop::Requeue
|
|
|
|
} else {
|
|
|
|
ShouldStop::LimitReached
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2024-01-08 22:27:46 +00:00
|
|
|
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
2018-11-18 01:39:04 +00:00
|
|
|
/// A type that represents whether a job should be requeued
|
2018-11-06 02:53:03 +00:00
|
|
|
pub enum ShouldStop {
|
2018-11-18 01:39:04 +00:00
|
|
|
/// The job has hit the maximum allowed number of retries, and should be failed permanently
|
2018-11-05 02:13:06 +00:00
|
|
|
LimitReached,
|
2018-11-18 01:39:04 +00:00
|
|
|
|
|
|
|
/// The job is allowed to be put back into the job queue
|
2018-11-05 02:13:06 +00:00
|
|
|
Requeue,
|
|
|
|
}
|
|
|
|
|
|
|
|
impl ShouldStop {
|
2018-11-18 01:39:04 +00:00
|
|
|
/// A boolean representation of this state
|
2024-01-08 22:27:46 +00:00
|
|
|
pub const fn should_requeue(&self) -> bool {
|
|
|
|
matches!(self, ShouldStop::Requeue)
|
2018-11-05 02:13:06 +00:00
|
|
|
}
|
|
|
|
}
|
2020-03-21 02:31:03 +00:00
|
|
|
|
|
|
|
impl From<serde_json::error::Error> for JobError {
|
|
|
|
fn from(_: serde_json::error::Error) -> Self {
|
|
|
|
JobError::Json
|
|
|
|
}
|
|
|
|
}
|