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
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
use anyhow::Error;
|
2018-11-05 02:13:06 +00:00
|
|
|
|
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::{
|
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
|
2020-03-21 02:31:03 +00:00
|
|
|
#[error("Error performing job: {0}")]
|
|
|
|
Processing(#[from] Error),
|
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
|
|
|
}
|
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
#[derive(Clone, 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
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn success() -> Self {
|
|
|
|
JobResult::Success
|
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Indicate a failed job
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn failure() -> Self {
|
|
|
|
JobResult::Failure
|
|
|
|
}
|
|
|
|
|
2020-04-21 00:30:56 +00:00
|
|
|
/// Indicate that the job was not registered for this worker
|
|
|
|
pub fn unregistered() -> Self {
|
|
|
|
JobResult::Unregistered
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job failed
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn is_failure(&self) -> bool {
|
|
|
|
*self == JobResult::Failure
|
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job succeeded
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn is_success(&self) -> bool {
|
|
|
|
*self == JobResult::Success
|
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job is missing it's processor
|
2020-04-21 00:30:56 +00:00
|
|
|
pub fn is_unregistered(&self) -> bool {
|
|
|
|
*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
|
|
|
|
pub fn is_unexecuted(&self) -> bool {
|
|
|
|
*self == JobResult::Unexecuted
|
|
|
|
}
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
#[derive(Clone, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
|
2018-11-18 01:39:04 +00:00
|
|
|
/// Set the status of a job when storing it
|
2018-11-05 02:13:06 +00:00
|
|
|
pub enum JobStatus {
|
2018-11-07 02:01:43 +00:00
|
|
|
/// Job should be queued
|
2018-11-05 02:13:06 +00:00
|
|
|
Pending,
|
2018-11-07 02:01:43 +00:00
|
|
|
|
|
|
|
/// Job is running
|
|
|
|
Running,
|
2019-05-25 20:22:26 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
impl JobStatus {
|
2019-09-22 17:12:08 +00:00
|
|
|
/// The job should be queued
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn pending() -> Self {
|
|
|
|
JobStatus::Pending
|
|
|
|
}
|
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// The job is running
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn running() -> Self {
|
|
|
|
JobStatus::Running
|
|
|
|
}
|
2018-11-07 02:01:43 +00:00
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job is ready to be queued
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn is_pending(&self) -> bool {
|
|
|
|
*self == JobStatus::Pending
|
|
|
|
}
|
2018-11-07 02:01:43 +00:00
|
|
|
|
2019-09-22 17:12:08 +00:00
|
|
|
/// Check if the job is running
|
2019-05-25 20:22:26 +00:00
|
|
|
pub fn is_running(&self) -> bool {
|
|
|
|
*self == JobStatus::Running
|
|
|
|
}
|
2018-11-05 02:13:06 +00:00
|
|
|
}
|
|
|
|
|
2020-03-22 19:59:36 +00:00
|
|
|
impl std::fmt::Display for JobStatus {
|
|
|
|
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
|
|
|
|
match self {
|
|
|
|
JobStatus::Pending => write!(f, "Pending"),
|
|
|
|
JobStatus::Running => write!(f, "Running"),
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, thiserror::Error)]
|
|
|
|
#[error("Invalid job status")]
|
2020-03-22 21:04:49 +00:00
|
|
|
/// The error generated when parsing a job's status if it's not 'Pending' or 'Running'
|
2020-03-22 19:59:36 +00:00
|
|
|
pub struct JobStatusError;
|
|
|
|
|
|
|
|
impl std::str::FromStr for JobStatus {
|
|
|
|
type Err = JobStatusError;
|
|
|
|
|
|
|
|
fn from_str(s: &str) -> Result<Self, Self::Err> {
|
|
|
|
match s {
|
|
|
|
"Pending" => Ok(JobStatus::Pending),
|
|
|
|
"Running" => Ok(JobStatus::Running),
|
|
|
|
_ => Err(JobStatusError),
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
#[derive(Clone, 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),
|
|
|
|
}
|
|
|
|
|
2020-03-21 02:31:03 +00:00
|
|
|
#[derive(Clone, 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 {
|
|
|
|
fn compare(&self, retry_count: u32) -> ShouldStop {
|
|
|
|
match *self {
|
|
|
|
MaxRetries::Infinite => ShouldStop::Requeue,
|
|
|
|
MaxRetries::Count(ref count) => {
|
2018-11-07 03:32:40 +00:00
|
|
|
if (retry_count as usize) <= *count {
|
2018-11-07 03:26:48 +00:00
|
|
|
ShouldStop::Requeue
|
|
|
|
} else {
|
|
|
|
ShouldStop::LimitReached
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2018-11-05 02:13:06 +00:00
|
|
|
#[derive(Clone, 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
|
2018-11-06 02:53:03 +00:00
|
|
|
pub fn should_requeue(&self) -> bool {
|
2018-11-05 02:13:06 +00:00
|
|
|
*self == ShouldStop::Requeue
|
|
|
|
}
|
|
|
|
}
|
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
|
|
|
|
}
|
|
|
|
}
|