pgtask 0.1.3__tar.gz → 0.3.0__tar.gz

{pgtask-0.1.3 → 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,18 +1195,20 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pgtask"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "pgtask-core",
  "pgtask-otel",
  "pgtask-postgres",
  "pgtask-worker",
  "serde_json",
+ "tokio",
+ "tokio-util",
 ]
 
 [[package]]
 name = "pgtask-bench"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1186,7 +1221,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-cli"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "clap",
  "pgtask",
@@ -1196,10 +1231,11 @@ dependencies = [
 
 [[package]]
 name = "pgtask-core"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "cron",
+ "proptest",
  "rand 0.9.5",
  "serde",
  "serde_json",
@@ -1209,7 +1245,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-otel"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "opentelemetry",
  "opentelemetry_sdk",
@@ -1220,11 +1256,13 @@ dependencies = [
 
 [[package]]
 name = "pgtask-postgres"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask-core",
  "pgtask-otel",
+ "proptest",
+ "proptest-state-machine",
  "serde_json",
  "sqlx",
  "thiserror",
@@ -1235,7 +1273,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-python"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1252,7 +1290,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-web"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1271,7 +1309,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-worker"
-version = "0.1.3"
+version = "0.3.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1375,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"
@@ -1456,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"
@@ -1538,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"
@@ -1578,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"
@@ -1630,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"
@@ -2093,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"
@@ -2310,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"
@@ -2397,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.1.3 → 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.1.3"
+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.3.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pgtask
+Version: 0.3.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Requires-Dist: opentelemetry-api>=1.30
+Requires-Dist: psycopg>=3.2
+Summary: PostgreSQL-native durable tasks and workflows
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# pgtask
+
+Durable tasks and workflows that live entirely in PostgreSQL.
+
+There is no broker, no coordinator, and no extension to install. If your database is up, your queue is up.
+
+> [!WARNING]
+> `pgtask` is under active development. It is not ready for production use.
+
+## Installation
+
+```console
+pip install pgtask
+```
+
+## Define a task and run a worker
+
+A registry maps a task name to the function that runs it. A worker claims work for that queue, one lease
+at a time, so a worker that dies hands its tasks back instead of taking them with it.
+
+```python
+from __future__ import annotations
+
+import asyncio
+import os
+
+from pgtask import Client, Task, TaskRegistry, Worker
+
+tasks = TaskRegistry(queue_name="reports")
+
+
+@tasks.task("reports.render")
+async def render(task: Task, payload: dict) -> dict:
+    return {"report_id": payload["report_id"], "attempt": task.attempt}
+
+
+async def main() -> None:
+    database_url = os.environ["PGTASK_DATABASE_URL"]
+    client = await Client.connect(database_url)
+    await client.migrate()
+    await Worker(database_url, tasks).run()
+
+
+asyncio.run(main())
+```
+
+Delivery is at least once, so write handlers that are safe to run again.
+
+## Enqueue a task
+
+```python
+from __future__ import annotations
+
+import asyncio
+import os
+
+from pgtask import Client, EnqueueRequest
+
+
+async def main() -> None:
+    client = await Client.connect(os.environ["PGTASK_DATABASE_URL"])
+    handle = await client.enqueue(
+        EnqueueRequest("reports.render", {"report_id": "report-123"}, queue_name="reports")
+    )
+    print(await handle.result(timeout=30.0))
+
+
+asyncio.run(main())
+```
+
+## Enqueue inside your transaction
+
+This is the reason to keep the queue in the database. Pass your own connection and the task commits with
+your data or not at all. Roll back and the task never existed, which is what an outbox table is usually
+for.
+
+```python
+async with connection.transaction():
+    await connection.execute("INSERT INTO reports (id) VALUES (%s)", ("report-123",))
+    await Client.enqueue_on(connection, request)
+```
+
+`connection` is your `psycopg` connection, not one of ours.
+
+## Documentation
+
+[kludex.github.io/pgtask](https://kludex.github.io/pgtask/) covers workers, durable execution, signals,
+cancellation, scheduling, and OpenTelemetry propagation.
+

pgtask-0.3.0/README.md

@@ -0,0 +1,88 @@
+# pgtask
+
+Durable tasks and workflows that live entirely in PostgreSQL.
+
+There is no broker, no coordinator, and no extension to install. If your database is up, your queue is up.
+
+> [!WARNING]
+> `pgtask` is under active development. It is not ready for production use.
+
+## Installation
+
+```console
+pip install pgtask
+```
+
+## Define a task and run a worker
+
+A registry maps a task name to the function that runs it. A worker claims work for that queue, one lease
+at a time, so a worker that dies hands its tasks back instead of taking them with it.
+
+```python
+from __future__ import annotations
+
+import asyncio
+import os
+
+from pgtask import Client, Task, TaskRegistry, Worker
+
+tasks = TaskRegistry(queue_name="reports")
+
+
+@tasks.task("reports.render")
+async def render(task: Task, payload: dict) -> dict:
+    return {"report_id": payload["report_id"], "attempt": task.attempt}
+
+
+async def main() -> None:
+    database_url = os.environ["PGTASK_DATABASE_URL"]
+    client = await Client.connect(database_url)
+    await client.migrate()
+    await Worker(database_url, tasks).run()
+
+
+asyncio.run(main())
+```
+
+Delivery is at least once, so write handlers that are safe to run again.
+
+## Enqueue a task
+
+```python
+from __future__ import annotations
+
+import asyncio
+import os
+
+from pgtask import Client, EnqueueRequest
+
+
+async def main() -> None:
+    client = await Client.connect(os.environ["PGTASK_DATABASE_URL"])
+    handle = await client.enqueue(
+        EnqueueRequest("reports.render", {"report_id": "report-123"}, queue_name="reports")
+    )
+    print(await handle.result(timeout=30.0))
+
+
+asyncio.run(main())
+```
+
+## Enqueue inside your transaction
+
+This is the reason to keep the queue in the database. Pass your own connection and the task commits with
+your data or not at all. Roll back and the task never existed, which is what an outbox table is usually
+for.
+
+```python
+async with connection.transaction():
+    await connection.execute("INSERT INTO reports (id) VALUES (%s)", ("report-123",))
+    await Client.enqueue_on(connection, request)
+```
+
+`connection` is your `psycopg` connection, not one of ours.
+
+## Documentation
+
+[kludex.github.io/pgtask](https://kludex.github.io/pgtask/) covers workers, durable execution, signals,
+cancellation, scheduling, and OpenTelemetry propagation.

pgtask-0.3.0/crates/pgtask/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "pgtask"
+description = "PostgreSQL-native durable tasks and workflows"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+readme = "README.md"
+
+[dependencies]
+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
+tokio.workspace = true
+tokio-util.workspace = true
+
+[lints]
+workspace = true

pgtask-0.3.0/crates/pgtask/README.md

@@ -0,0 +1,100 @@
+# pgtask
+
+Durable tasks and workflows that live entirely in PostgreSQL.
+
+There is no broker, no coordinator, and no extension to install. If your database is up, your queue is up.
+
+> [!WARNING]
+> `pgtask` is under active development. It is not ready for production use.
+
+## Installation
+
+```console
+cargo add pgtask tokio tokio-util serde_json
+```
+
+## Run a worker
+
+A worker declares which tasks it can handle and claims work from a queue. Every claim takes a lease, so
+when a worker dies its tasks return to the queue instead of disappearing with it.
+
+```rust,no_run
+use std::error::Error;
+
+use pgtask::{
+    core::{HandlerVersion, QueueName, RetryPolicy, TaskName},
+    postgres::Store,
+    worker::{HandlerRegistry, Worker, WorkerConfig},
+};
+use serde_json::json;
+use tokio_util::sync::CancellationToken;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let store = Store::connect(&std::env::var("PGTASK_DATABASE_URL")?).await?;
+    store.migrate().await?;
+
+    let mut registry = HandlerRegistry::new();
+    registry.register(
+        TaskName::new("reports.render")?,
+        HandlerVersion::default(),
+        RetryPolicy::Never,
+        |task| async move { Ok(json!({ "attempt": task.attempt })) },
+    );
+
+    let config = WorkerConfig::new(QueueName::new("reports")?);
+    Worker::new(store, registry, config)?.run(CancellationToken::new()).await?;
+    Ok(())
+}
+```
+
+Cancel the token to shut down. The worker stops claiming, finishes what it is already running, and lets
+the rest expire back to the queue.
+
+## Enqueue inside your transaction
+
+This is the reason to keep the queue in the database. You pass your own transaction, so the task commits
+with your data or not at all. Roll back and the task never existed.
+
+```rust,no_run
+use std::error::Error;
+
+use pgtask::{
+    core::{EnqueueRequest, QueueName, TaskName},
+    postgres::Store,
+};
+use serde_json::json;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let store = Store::connect(&std::env::var("PGTASK_DATABASE_URL")?).await?;
+
+    let mut request = EnqueueRequest::new(TaskName::new("reports.render")?, json!({"report_id": "report-123"}));
+    request.queue_name = QueueName::new("reports")?;
+
+    let mut transaction = store.pool().begin().await?;
+    // Your own writes belong here, in the same transaction.
+    let result = Store::enqueue_on(&mut transaction, &request).await?;
+    transaction.commit().await?;
+
+    println!("enqueued {}", result.task_id);
+    Ok(())
+}
+```
+
+Without a transaction of your own, `store.enqueue(&request)` does the same on its own connection.
+
+## Crates
+
+This crate re-exports the others. Depend on it unless you need one layer on its own.
+
+| Crate | What it holds |
+| --- | --- |
+| `pgtask-core` | Task, queue, schedule, and retry types shared by every layer |
+| `pgtask-postgres` | The storage protocol: migrate, enqueue, claim, complete |
+| `pgtask-worker` | The worker runtime, scheduler, and retention loop |
+| `pgtask-otel` | OpenTelemetry spans, metrics, and trace propagation |
+
+## Documentation
+
+[kludex.github.io/pgtask](https://kludex.github.io/pgtask/)

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

@@ -1,4 +1,4 @@
-#![doc = "PostgreSQL-native durable tasks and workflows."]
+#![doc = include_str!("../README.md")]
 
 pub use pgtask_core as core;
 pub use pgtask_otel as otel;

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

@@ -6,6 +6,7 @@ license.workspace = true
 repository.workspace = true
 rust-version.workspace = true
 version.workspace = true
+readme = "README.md"
 
 [dependencies]
 chrono.workspace = true
@@ -16,5 +17,8 @@ serde_json.workspace = true
 thiserror.workspace = true
 uuid.workspace = true
 
+[dev-dependencies]
+proptest.workspace = true
+
 [lints]
 workspace = true

pgtask-0.3.0/crates/pgtask-core/README.md

@@ -0,0 +1,13 @@
+# pgtask-core
+
+The types every layer of `pgtask` agrees on: tasks, queues, schedules, retry policies, and the states a
+task can be in.
+
+There is no database access and no runtime here. The crate exists so the storage layer, the worker, and
+the telemetry layer share one definition of a task instead of three that drift apart.
+
+You probably want [`pgtask`](https://crates.io/crates/pgtask), which re-exports this as `pgtask::core`.
+
+## Documentation
+
+[kludex.github.io/pgtask](https://kludex.github.io/pgtask/)

{pgtask-0.1.3 → 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;