From c993e920155254e815deaf869213bf02a97b44e9 Mon Sep 17 00:00:00 2001 From: summer97souls Date: Tue, 16 Jun 2026 15:52:20 +0530 Subject: [PATCH] feat: add async core, AsyncSentinel, and async test suite chore: release 0.4.0 --- sentinel-py/CHANGELOG.md | 70 ++++++++++++++++++++++++++++++++++ sentinel-py/ROADMAP.md | 77 ++++++++++++++++++++++++++++++++++++++ sentinel-py/pyproject.toml | 40 +++++++++++++++++++- 3 files changed, 185 insertions(+), 2 deletions(-) create mode 100644 sentinel-py/CHANGELOG.md create mode 100644 sentinel-py/ROADMAP.md diff --git a/sentinel-py/CHANGELOG.md b/sentinel-py/CHANGELOG.md new file mode 100644 index 0000000..90e8c3f --- /dev/null +++ b/sentinel-py/CHANGELOG.md @@ -0,0 +1,70 @@ +# Changelog + +All notable changes to this project will be documented in this file. +The format loosely follows Keep a Changelog. + +--- + +## [0.4.0] - 2026 + +### Added + +- AsyncSentinel +- AsyncOnce +- Async execution coordination support +- Async reconciliation support +- Async helper utilities +- Async database initialization + +### Improved + +- Sync and async execution parity +- CI coverage +- Package metadata + +--- + +## [0.3.1] - 2026 + +### Improved + +- Documentation updates +- Packaging improvements +- Public repository improvements + +--- + +## [0.3.0] - 2026 + +### Added + +- Explicit reconciliation APIs +- Execution uncertainty handling +- Improved execution lifecycle management + +--- + +## [0.2.0] - 2026 + +### Added + +- Heartbeat management +- Cached result replay +- Ownership validation +- Fencing token support + +--- + +## [0.1.0] - 2026 + +### Initial Release + +Introduced Sentinel. + +Features included: + +- PostgreSQL-backed execution coordination +- Lease acquisition +- Single execution semantics +- Canonical completion +- Django integration \ No newline at end of file diff --git a/sentinel-py/ROADMAP.md b/sentinel-py/ROADMAP.md new file mode 100644 index 0000000..ee58e9a --- /dev/null +++ b/sentinel-py/ROADMAP.md @@ -0,0 +1,77 @@ +# Roadmap + +Sentinel is a PostgreSQL-backed execution coordination primitive for correctness-sensitive distributed work. + +The focus is to keep the core small, explicit, and reliable rather than continuously expanding the surface area. + +## Principles + +- PostgreSQL first +- Explicit over automatic +- Correctness over convenience +- Small core API +- Framework agnostic + +--- + +## Completed + +### Core Runtime + +- [x] Lease acquisition with conditional upsert +- [x] Ownership validation via fencing tokens +- [x] Heartbeat management on OS threads +- [x] Hard TTL as absolute execution deadline +- [x] Cached result replay on repeat calls +- [x] Explicit reconciliation (`reconcile`, `force_complete`, `reset`) +- [x] Execution uncertainty surfaced on `fn()` failure +- [x] `expire_lease` to collapse uncertainty window immediately on failure + +### APIs + +- [x] `Sentinel` — synchronous client +- [x] `AsyncSentinel` — async client with full execution parity +- [x] `init_db` / `async_init_db` — schema initialization + +### Integrations + +- [x] Django — `DjangoSentinel` with borrowed connection and optional migrations + +### Tooling + +- [x] pytest suite covering core, once, helper, and reconciliation (sync and async) +- [x] GitHub Actions CI against Postgres service container +- [x] PyPI publishing as `sentinel-coordination` + +--- + +## Near Term (0.5.0) + +- [ ] `sentinel_events` append-only event log written in the same transaction as state transitions +- [ ] FastAPI integration after async core stabilizes +- [ ] Expanded test coverage for edge cases and contention scenarios +- [ ] Improved examples and integration guides + +--- + +## Under Consideration + +These are ideas being explored and are not guaranteed. + +- [ ] Correlate — separate OSS library that reads `sentinel_events` for cross-service execution observability +- [ ] Batched adaptive heartbeats — bucket-level batch `UPDATE` with adaptive interval +- [ ] Additional framework adapters (Flask, Starlette) +- [ ] Embeddable reconciliation dashboard + +--- + +## Non Goals + +Sentinel is intentionally not: + +- A queue +- A workflow engine +- A scheduler +- A retry framework +- A distributed lock library +- A framework-specific tool \ No newline at end of file diff --git a/sentinel-py/pyproject.toml b/sentinel-py/pyproject.toml index 8dd546a..a5a01e7 100644 --- a/sentinel-py/pyproject.toml +++ b/sentinel-py/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "sentinel-coordination" -version = "0.3.1" +version = "0.4.0" description = "PostgreSQL-backed execution coordination primitive for correctness-sensitive distributed work." authors = [ { name = "Sreejay Reddy", email = "reddysreejay@gmail.com" } @@ -9,6 +9,32 @@ readme = "README.md" requires-python = ">=3.9" dependencies = ["psycopg[binary]"] +keywords = [ + "postgresql", + "distributed-systems", + "idempotency", + "execution-coordination", + "fault-tolerance", + "concurrency", + "fencing-tokens" +] + +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Software Development", + "Topic :: System :: Distributed Computing", + "Topic :: Database" +] + +license = { file = "LICENSE" } + [project.optional-dependencies] django = ["django>=4.2"] @@ -17,4 +43,14 @@ requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [tool.setuptools] -packages = ["sentinel", "sentinel.integrations"] \ No newline at end of file +packages = [ + "sentinel", + "sentinel.integrations", + "sentinel.integrations.migrations" +] + +[project.urls] +Homepage = "https://github.com/sreejay-reddy/sentinel" +Repository = "https://github.com/sreejay-reddy/sentinel" +Issues = "https://github.com/sreejay-reddy/sentinel/issues" +Documentation = "https://github.com/sreejay-reddy/sentinel#readme"