pgtask 0.2.0__tar.gz → 0.3.0__tar.gz

{pgtask-0.2.0 → pgtask-0.3.0}/Cargo.lock

@@ -155,6 +155,21 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec",
+]
+
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
 [[package]]
 name = "bitflags"
 version = "2.13.1"
@@ -480,6 +495,12 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.11"
@@ -497,6 +518,12 @@ dependencies = [
  "spin",
 ]
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -990,6 +1017,12 @@ dependencies = [
  "vcpkg",
 ]
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
 [[package]]
 name = "litemap"
 version = "0.8.3"
@@ -1162,7 +1195,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pgtask"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "pgtask-core",
  "pgtask-otel",
@@ -1175,7 +1208,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-bench"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1188,7 +1221,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-cli"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "clap",
  "pgtask",
@@ -1198,10 +1231,11 @@ dependencies = [
 
 [[package]]
 name = "pgtask-core"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "cron",
+ "proptest",
  "rand 0.9.5",
  "serde",
  "serde_json",
@@ -1211,7 +1245,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-otel"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "opentelemetry",
  "opentelemetry_sdk",
@@ -1222,11 +1256,13 @@ dependencies = [
 
 [[package]]
 name = "pgtask-postgres"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask-core",
  "pgtask-otel",
+ "proptest",
+ "proptest-state-machine",
  "serde_json",
  "sqlx",
  "thiserror",
@@ -1237,7 +1273,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-python"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1254,7 +1290,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-web"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1273,7 +1309,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-worker"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1377,6 +1413,34 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "proptest"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
+dependencies = [
+ "bit-set",
+ "bit-vec",
+ "bitflags",
+ "num-traits",
+ "rand 0.9.5",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "rusty-fork",
+ "tempfile",
+ "unarray",
+]
+
+[[package]]
+name = "proptest-state-machine"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e943d140e09d07740fb496487c51fb8eb31c70389ac4a2e9dcd8a0d9fdf228d4"
+dependencies = [
+ "proptest",
+]
+
 [[package]]
 name = "pyo3"
 version = "0.29.2"
@@ -1458,6 +1522,12 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "quick-error"
+version = "1.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
+
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -1540,6 +1610,15 @@ version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
@@ -1580,6 +1659,19 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "rustls"
 version = "0.23.43"
@@ -1632,6 +1724,18 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
+[[package]]
+name = "rusty-fork"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
+dependencies = [
+ "fnv",
+ "quick-error",
+ "tempfile",
+ "wait-timeout",
+]
+
 [[package]]
 name = "ryu"
 version = "1.0.23"
@@ -2095,6 +2199,19 @@ version = "0.13.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "thiserror"
 version = "2.0.20"
@@ -2312,6 +2429,12 @@ version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
 [[package]]
 name = "unicode-bidi"
 version = "0.3.18"
@@ -2399,6 +2522,15 @@ version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
+[[package]]
+name = "wait-timeout"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "wasi"
 version = "0.11.1+wasi-snapshot-preview1"

{pgtask-0.2.0 → pgtask-0.3.0}/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2024"
 license = "MIT"
 repository = "https://github.com/Kludex/pgtask"
 rust-version = "1.94"
-version = "0.2.0"
+version = "0.3.0"
 
 [workspace.dependencies]
 axum = "0.8.9"
@@ -18,6 +18,8 @@ futures = "0.3.34"
 html-escape = "0.2.15"
 opentelemetry = "0.32.0"
 opentelemetry_sdk = "0.32.1"
+proptest = "1"
+proptest-state-machine = "0.3"
 pyo3 = "0.29.2"
 pyo3-async-runtimes = "0.29.0"
 pythonize = "0.29.0"

{pgtask-0.2.0 → pgtask-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgtask
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask/Cargo.toml

@@ -9,10 +9,10 @@ version.workspace = true
 readme = "README.md"
 
 [dependencies]
-pgtask-core = { path = "../pgtask-core", version = "0.2.0" }
-pgtask-otel = { path = "../pgtask-otel", version = "0.2.0" }
-pgtask-postgres = { path = "../pgtask-postgres", version = "0.2.0" }
-pgtask-worker = { path = "../pgtask-worker", version = "0.2.0" }
+pgtask-core = { path = "../pgtask-core", version = "0.3.0" }
+pgtask-otel = { path = "../pgtask-otel", version = "0.3.0" }
+pgtask-postgres = { path = "../pgtask-postgres", version = "0.3.0" }
+pgtask-worker = { path = "../pgtask-worker", version = "0.3.0" }
 
 [dev-dependencies]
 serde_json.workspace = true

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask-core/Cargo.toml

@@ -17,5 +17,8 @@ serde_json.workspace = true
 thiserror.workspace = true
 uuid.workspace = true
 
+[dev-dependencies]
+proptest.workspace = true
+
 [lints]
 workspace = true

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask-core/src/lib.rs

@@ -20,7 +20,7 @@ pub use task::{
 pub const STORAGE_PROTOCOL_MIN_VERSION: u32 = 1;
 
 /// Newest storage protocol understood by this release.
-pub const STORAGE_PROTOCOL_MAX_VERSION: u32 = 1;
+pub const STORAGE_PROTOCOL_MAX_VERSION: u32 = 2;
 
 /// Current storage protocol emitted by this release.
 pub const STORAGE_PROTOCOL_VERSION: u32 = STORAGE_PROTOCOL_MAX_VERSION;

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask-core/src/schedule.rs

@@ -14,9 +14,7 @@ pub enum ScheduleDefinition {
 
 impl ScheduleDefinition {
     pub fn interval(every: Duration) -> Result<Self, ScheduleError> {
-        if every.is_zero() {
-            return Err(ScheduleError::ZeroInterval);
-        }
+        interval_milliseconds(every)?;
         TimeDelta::from_std(every).map_err(|_| ScheduleError::IntervalOutOfRange)?;
         Ok(Self::Interval { every })
     }
@@ -47,11 +45,7 @@ impl ScheduleDefinition {
     fn due_count(&self, first_due: DateTime<Utc>, now: DateTime<Utc>) -> Result<u64, ScheduleError> {
         match self {
             Self::Interval { every } => {
-                let every_milliseconds =
-                    i64::try_from(every.as_millis()).map_err(|_| ScheduleError::IntervalOutOfRange)?;
-                if every_milliseconds == 0 {
-                    return Err(ScheduleError::ZeroInterval);
-                }
+                let every_milliseconds = interval_milliseconds(*every)?;
                 let elapsed_milliseconds = (now - first_due).num_milliseconds().max(0);
                 Ok(u64::try_from(elapsed_milliseconds / every_milliseconds).unwrap_or(0) + 1)
             }
@@ -70,8 +64,7 @@ impl ScheduleDefinition {
     fn latest_due(&self, first_due: DateTime<Utc>, now: DateTime<Utc>) -> Result<DateTime<Utc>, ScheduleError> {
         match self {
             Self::Interval { every } => {
-                let every_milliseconds =
-                    i64::try_from(every.as_millis()).map_err(|_| ScheduleError::IntervalOutOfRange)?;
+                let every_milliseconds = interval_milliseconds(*every)?;
                 let elapsed_milliseconds = (now - first_due).num_milliseconds();
                 let intervals = elapsed_milliseconds / every_milliseconds;
                 first_due
@@ -198,6 +191,8 @@ pub struct Materialization {
 pub enum ScheduleError {
     #[error("interval must be greater than zero")]
     ZeroInterval,
+    #[error("interval must use whole-millisecond precision")]
+    UnsupportedIntervalPrecision,
     #[error("interval exceeds the supported date range")]
     IntervalOutOfRange,
     #[error("cron expression must contain exactly six fields: second minute hour day-of-month month day-of-week")]
@@ -210,6 +205,16 @@ pub enum ScheduleError {
     DateOutOfRange,
 }
 
+fn interval_milliseconds(every: Duration) -> Result<i64, ScheduleError> {
+    if every.is_zero() {
+        return Err(ScheduleError::ZeroInterval);
+    }
+    if !every.as_nanos().is_multiple_of(1_000_000) {
+        return Err(ScheduleError::UnsupportedIntervalPrecision);
+    }
+    i64::try_from(every.as_millis()).map_err(|_| ScheduleError::IntervalOutOfRange)
+}
+
 fn parse_cron(expression: &str) -> Result<CronSchedule, ScheduleError> {
     if expression.split_whitespace().count() != 6 {
         return Err(ScheduleError::InvalidCronFieldCount);

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask-core/src/task.rs

@@ -159,6 +159,7 @@ pub struct Task {
     pub priority: i16,
     pub run_at: DateTime<Utc>,
     pub attempt: u16,
+    pub failed_attempts: u16,
     pub max_attempts: u16,
     pub retry_policy: Option<RetryPolicy>,
     pub lease_token: Option<LeaseToken>,

pgtask-0.3.0/crates/pgtask-core/tests/.gitignore

@@ -0,0 +1,4 @@
+# proptest writes failing seeds here. They are worth committing when they
+# still reproduce, but a seed recorded under a generator that has since changed
+# replays as a different value and only misleads.
+*.proptest-regressions

pgtask-0.3.0/crates/pgtask-core/tests/retry_properties.rs

@@ -0,0 +1,124 @@
+//! Property tests for retry backoff.
+//!
+//! `delay_for` decides how long a failed task waits before it is claimed again.
+//! It is pure apart from the jitter, and the jitter is exactly what makes
+//! example-based tests weak here: a single call proves nothing about the bound.
+//!
+//! Case count follows `PROPTEST_CASES`.
+
+use std::time::Duration;
+
+use pgtask_core::RetryPolicy;
+use proptest::prelude::*;
+
+fn cases() -> u32 {
+    std::env::var("PROPTEST_CASES")
+        .ok()
+        .and_then(|value| value.parse().ok())
+        .unwrap_or(512)
+}
+
+fn config() -> ProptestConfig {
+    ProptestConfig {
+        cases: cases(),
+        ..ProptestConfig::default()
+    }
+}
+
+/// Exponential policies the database would accept: a positive factor and a
+/// ceiling at least as large as the base, matching the CHECK constraint on
+/// `pgtask.handler_policies`.
+fn storable_exponential() -> impl Strategy<Value = RetryPolicy> {
+    (0_u64..3_600_000, 1_u32..16, 0_u64..86_400_000).prop_map(|(base, factor, extra)| RetryPolicy::Exponential {
+        base_delay: Duration::from_millis(base),
+        factor,
+        max_delay: Duration::from_millis(base + extra),
+    })
+}
+
+proptest! {
+    #![proptest_config(config())]
+
+    /// The ceiling is the promise the policy makes. Jitter may shorten a delay,
+    /// never lengthen it past `max_delay`.
+    #[test]
+    fn an_exponential_delay_never_exceeds_its_ceiling(
+        policy in storable_exponential(),
+        attempt in 0_u16..2_000,
+    ) {
+        let RetryPolicy::Exponential { max_delay, .. } = policy else {
+            unreachable!("the strategy only builds exponential policies")
+        };
+        let delay = policy.delay_for(attempt).expect("exponential always yields a delay");
+        prop_assert!(
+            delay <= max_delay,
+            "attempt {attempt} waited {delay:?}, past the {max_delay:?} ceiling"
+        );
+    }
+
+    /// Growth is bounded by the policy's own curve, not just by the ceiling, so
+    /// an early attempt cannot wait as long as a late one.
+    #[test]
+    fn an_exponential_delay_stays_under_the_curve(
+        base_millis in 1_u64..10_000,
+        factor in 2_u32..8,
+        attempt in 1_u16..8,
+    ) {
+        let policy = RetryPolicy::Exponential {
+            base_delay: Duration::from_millis(base_millis),
+            factor,
+            // No effective ceiling, so this measures the curve rather than the clamp.
+            max_delay: Duration::MAX,
+        };
+        // Derived here rather than read from the implementation.
+        let expected_ceiling = Duration::from_millis(
+            base_millis * u64::from(factor).pow(u32::from(attempt) - 1),
+        );
+        let delay = policy.delay_for(attempt).unwrap();
+        prop_assert!(
+            delay <= expected_ceiling,
+            "attempt {attempt} waited {delay:?}, past the {expected_ceiling:?} the curve allows"
+        );
+    }
+
+    /// A fixed policy is exactly that: the same wait every time, with no jitter.
+    #[test]
+    fn a_fixed_delay_is_constant(millis in 0_u64..86_400_000, attempt in 0_u16..2_000) {
+        let delay = Duration::from_millis(millis);
+        prop_assert_eq!(RetryPolicy::Fixed { delay }.delay_for(attempt), Some(delay));
+    }
+
+    /// `Never` means never, at any attempt.
+    #[test]
+    fn never_never_retries(attempt in 0_u16..u16::MAX) {
+        prop_assert_eq!(RetryPolicy::Never.delay_for(attempt), None);
+    }
+
+    /// Attempt numbers come from the database, so the whole `u16` range has to
+    /// be survivable — including the saturating edges.
+    #[test]
+    fn delays_are_computable_for_any_attempt(
+        policy in storable_exponential(),
+        attempt in any::<u16>(),
+    ) {
+        let _ = policy.delay_for(attempt);
+    }
+}
+
+/// The two edges the range strategies above will essentially never generate.
+#[test]
+fn the_extreme_attempt_numbers_are_survivable() {
+    let policy = RetryPolicy::default();
+    assert!(policy.delay_for(0).is_some(), "attempt 0 must not panic");
+    assert!(policy.delay_for(u16::MAX).is_some(), "the last attempt must not panic");
+
+    let saturating = RetryPolicy::Exponential {
+        base_delay: Duration::from_secs(u64::MAX / 2),
+        factor: u32::MAX,
+        max_delay: Duration::MAX,
+    };
+    assert!(
+        saturating.delay_for(u16::MAX).is_some(),
+        "a policy that overflows every multiplication must saturate, not panic"
+    );
+}

{pgtask-0.2.0 → pgtask-0.3.0}/crates/pgtask-core/tests/schedule_clock.rs

@@ -115,13 +115,14 @@ fn a_cron_schedule_reports_discarded_occurrences() {
 }
 
 #[test]
-fn a_sub_millisecond_interval_is_rejected_rather_than_dividing_by_zero() {
-    // `interval` only rejects a zero duration, so an interval below a millisecond reaches
-    // materialization and truncates to zero milliseconds.
-    let schedule = ScheduleDefinition::interval(Duration::from_micros(500)).unwrap();
-    let first_due = Utc.with_ymd_and_hms(2026, 8, 15, 12, 0, 0).unwrap();
-    let now = first_due + chrono::TimeDelta::seconds(1);
-
-    let error = schedule.materialize(first_due, now, MisfirePolicy::Skip).unwrap_err();
-    assert!(matches!(error, ScheduleError::ZeroInterval));
+fn a_fractional_millisecond_interval_is_rejected() {
+    for interval in [Duration::from_micros(500), Duration::from_micros(1_500)] {
+        let error = ScheduleDefinition::interval(interval).unwrap_err();
+        assert!(matches!(error, ScheduleError::UnsupportedIntervalPrecision));
+
+        let schedule = ScheduleDefinition::Interval { every: interval };
+        let now = Utc.with_ymd_and_hms(2026, 8, 15, 12, 0, 0).unwrap();
+        let error = schedule.materialize(now, now, MisfirePolicy::Latest).unwrap_err();
+        assert!(matches!(error, ScheduleError::UnsupportedIntervalPrecision));
+    }
 }