durablestack 0.1.0b1__tar.gz

durablestack-0.1.0b1/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends unixodbc-dev
+
+      - name: Install package and dev dependencies
+        run: python -m pip install -U pip && python -m pip install -e ".[dev]"
+
+      - name: Ruff
+        run: python -m ruff check .
+
+      - name: Mypy
+        run: python -m mypy
+
+      - name: Pytest
+        run: python -m pytest -q

durablestack-0.1.0b1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,85 @@
+name: Publish PyPI
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "pyproject.toml"
+      - "src/**"
+      - "README.md"
+      - ".github/workflows/publish-pypi.yml"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends unixodbc-dev
+
+      - name: Install package and dev dependencies
+        run: python -m pip install -U pip && python -m pip install -e ".[dev]"
+
+      - name: Quality gates
+        run: python -m ruff check . && python -m mypy && python -m pytest -q
+
+      - name: Build artifacts
+        run: python -m build && python -m twine check dist/*
+
+      - name: Resolve package version
+        id: version
+        shell: pwsh
+        run: |
+          python -c "import pathlib, tomllib; data = tomllib.loads(pathlib.Path('pyproject.toml').read_text(encoding='utf-8')); print('version=' + data['project']['version'])" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+
+      - name: Check if version exists on PyPI
+        id: pypi_check
+        shell: pwsh
+        run: |
+          $url = "https://pypi.org/pypi/durablestack/${{ steps.version.outputs.version }}/json"
+          $status = 0
+          try {
+            $response = Invoke-WebRequest -Uri $url -Method Get -ErrorAction Stop
+            $status = [int]$response.StatusCode
+          } catch {
+            if ($_.Exception.Response) {
+              $status = [int]$_.Exception.Response.StatusCode
+            } else {
+              throw
+            }
+          }
+          if ($status -eq 200) {
+            "exists=true" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+            "Version already exists on PyPI; skipping publish." 
+          } else {
+            "exists=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+            "Version does not exist on PyPI; publishing."
+          }
+
+      - name: Publish to PyPI
+        if: steps.pypi_check.outputs.exists != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Publish summary
+        shell: pwsh
+        run: |
+          if ('${{ steps.pypi_check.outputs.exists }}' -eq 'true') {
+            "No publish: durablestack ${{ steps.version.outputs.version }} already exists." | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+          } else {
+            "Published durablestack ${{ steps.version.outputs.version }} to PyPI." | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+          }

durablestack-0.1.0b1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+dist/
+build/
+*.egg-info/

durablestack-0.1.0b1/ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# DurableStack Python Architecture
+
+## Goals
+
+- Match DurableStack runtime semantics defined by the .NET runtime for run lifecycle, leasing, retries, recurring scheduling, and retention.
+- Preserve platform-facing contract compatibility for telemetry/event ingestion and runtime-control sync.
+- Provide a Python-idiomatic runtime that is async-first and production-safe.
+
+## Source of Truth and Compatibility Rules
+
+- .NET behavior is canonical when there is any ambiguity.
+- Node.js behavior is a secondary parity reference where it intentionally mirrors .NET.
+- Cross-runtime worker execution is not supported: Python workers execute Python handlers only.
+- Cross-runtime external contracts are required: payload fields, status values, and command semantics must match hosted platform expectations.
+
+## Runtime Shape (Phase 0 Contract)
+
+- Runtime API surface is explicit and lifecycle-driven (`start`, `stop`, registration, enqueue/schedule/query/admin operations).
+- Processor contract separates orchestration from storage provider specifics.
+- Storage operations are abstracted via a provider interface that all durable backends must implement.
+- Event sink contract is pluggable and independent of run-state persistence.
+- Runtime-control sync contract is pluggable and uses durable command receipts.
+
+## Phase 0 Deliverables
+
+- Canonical constants for:
+  - run statuses,
+  - event types and event version,
+  - runtime-control command and receipt status values.
+- Options model and normalization entrypoint.
+- Core abstraction layer (runtime, processor, client/admin/query services, job store, event sink).
+- External DTO models and validators for telemetry and runtime-control payloads.
+- Package scaffold and test scaffold.
+
+## Planned Runtime Semantics (Parity Targets)
+
+1. Run lifecycle states: `pending` -> `leased` -> `succeeded|failed`.
+2. Lease-based distributed claiming and heartbeat extension while executing.
+3. Lease-fenced completion writes.
+4. Retry scheduling with max-attempt terminal behavior.
+5. Recurring materialization with IANA timezone handling and slot uniqueness semantics.
+6. Retention that prunes only terminal runs.
+7. Runtime-control sync and command receipt lifecycle semantics.
+8. Event payload compatibility with hosted ingestion APIs.
+
+## Design Notes
+
+- Runtime implementation will be `asyncio`-first.
+- Handlers will support both async and sync callables (sync handlers executed via an executor).
+- Startup must include schema migration and schema verification when durable providers are used.
+- Runtime-specific schema separation is intentional. Shared DB instances are allowed; shared runtime tables are not.
+
+## Non-goals for Phase 0
+
+- Durable provider implementations.
+- Full runtime host loop and execution engine.
+- Framework-specific integrations.
+- Job autodiscovery.

durablestack-0.1.0b1/CONTRACTS.md

@@ -0,0 +1,155 @@
+# DurableStack Python Contracts (Phase 3)
+
+## Run Status Vocabulary
+
+- `pending`
+- `leased`
+- `succeeded`
+- `failed`
+
+## Event Types
+
+- `job_claimed`
+- `job_started`
+- `job_succeeded`
+- `job_failed`
+- `job_retried`
+- `retry_scheduled`
+- `worker_heartbeat`
+
+## Event Version
+
+- `2`
+
+## Runtime-Control Command Types
+
+- `set_schedule_enabled`
+- `run_schedule_now`
+- `update_schedule_cron`
+
+## Runtime-Control Receipt Status Values
+
+- `leased`
+- `acknowledged`
+- `succeeded`
+- `failed`
+
+## External Payload Contract Policy
+
+- Field names and value semantics align with current platform-facing .NET payloads.
+- Validators are strict for required fields and permissive for nullable optional fields.
+- Breaking payload changes require coordinated runtime + platform versioning.
+
+## Telemetry Ingestion DTOs
+
+### Telemetry Event DTO
+
+Required fields:
+
+- `eventType` (string, one of contract event types)
+- `eventVersion` (int, current value `2`)
+- `occurredAtUtc` (ISO-8601 UTC timestamp)
+- `workerName` (non-empty string)
+- `runtime` (non-empty string)
+- `runtimeVersion` (non-empty string)
+
+Conditionally required for run-scoped events:
+
+- `runId` (non-empty string)
+- `jobName` (non-empty string)
+- `attempt` (int, >= 1)
+- `maxAttempts` (int, >= 1)
+
+Optional fields:
+
+- `durationMs` (int >= 0)
+- `errorType` (string)
+- `errorMessage` (string)
+- `payloadJson` (string)
+
+### Telemetry Batch Request DTO
+
+Required fields:
+
+- `tenantId` (non-empty string)
+- `idempotencyKey` (non-empty string)
+- `events` (non-empty array of telemetry event DTO)
+
+Optional fields:
+
+- `serviceName` (string)
+
+## Runtime-Control DTOs
+
+### Runtime-Control Sync Request DTO
+
+Required fields:
+
+- `tenantId` (non-empty string)
+- `workerName` (non-empty string)
+- `runtime` (non-empty string)
+- `runtimeVersion` (non-empty string)
+- `sentAtUtc` (ISO-8601 UTC timestamp)
+- `snapshotItems` (array)
+- `receipts` (array)
+
+`snapshotItems` item fields:
+
+- `jobName` (non-empty string)
+- `cronExpression` (non-empty string)
+- `timeZone` (non-empty string)
+- `enabled` (boolean)
+- `nextRunAtUtc` (ISO-8601 UTC timestamp)
+- `maxAttempts` (int >= 1)
+- `allowConcurrentRuns` (boolean)
+- `lastSeenAtUtc` (ISO-8601 UTC timestamp)
+
+`receipts` item fields:
+
+- `commandId` (non-empty string)
+- `status` (one of: `leased`, `acknowledged`, `succeeded`, `failed`)
+- `recordedAtUtc` (ISO-8601 UTC timestamp)
+
+Optional receipt fields:
+
+- `completedAtUtc` (ISO-8601 UTC timestamp)
+- `runId` (string)
+- `errorCode` (string)
+- `errorMessage` (string)
+
+### Runtime-Control Sync Response DTO
+
+Top-level fields:
+
+- `commands` or `Commands` (array of command envelope)
+
+Command envelope fields (camelCase or PascalCase accepted by parser):
+
+- `commandId`/`CommandId` (non-empty string)
+- `commandType`/`CommandType` (one of runtime-control command types)
+- `payloadJson`/`PayloadJson` (string JSON object)
+- `issuedAtUtc`/`IssuedAtUtc` (ISO-8601 UTC timestamp)
+- `expiresAtUtc`/`ExpiresAtUtc` (optional ISO-8601 UTC timestamp)
+
+### Runtime-Control Command Payload Shapes
+
+- `set_schedule_enabled`
+  - required: `jobName` (or `JobName`), `enabled` (or `Enabled`)
+- `run_schedule_now`
+  - required: `jobName` (or `JobName`)
+- `update_schedule_cron`
+  - required: `jobName`/`JobName`, `cronExpression`/`CronExpression`, `timeZone`/`TimeZone`
+
+## Error/Retry Policy Contracts
+
+- 2xx responses are treated as success.
+- 401/403 are treated as terminal auth failures without retry.
+- Transient statuses (`408`, `409`, `425`, `429`, `5xx`) are retried with bounded attempts and backoff.
+- Non-transient non-2xx statuses are terminal for that sync attempt.
+- Sync services include correlation ID headers and must include tenant/client-secret headers when credentials are configured.
+
+## Schema and Runtime Boundaries
+
+- Runtime schemas are runtime-specific by design.
+- Python and .NET runtimes may share a DB instance but must use separate tables/prefixes.
+- Startup must verify that existing tables at the configured prefix match Python runtime schema expectations.

durablestack-0.1.0b1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: durablestack
+Version: 0.1.0b1
+Summary: DurableStack Python runtime
+Project-URL: Homepage, https://durablestack.com
+Project-URL: Repository, https://github.com/durablestack/durablestack-python
+Project-URL: Issues, https://github.com/durablestack/durablestack-python/issues
+Author: DurableStack
+License: MIT
+Keywords: background-workers,distributed-systems,durable-jobs,job-queue,scheduling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: croniter>=3.0.3
+Requires-Dist: pymysql>=1.1.1
+Requires-Dist: pyodbc>=5.1.0
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# durablestack-python
+
+DurableStack Python runtime (in active development): durable background jobs and recurring scheduling with platform-compatible contracts.
+
+## Status
+
+This package has completed Phase 4 (provider parity).
+
+Implemented so far:
+
+- Phase 0: scaffold, contracts/constants, validators baseline, docs
+- Phase 1: in-memory runtime/store with lease fencing, retries, recurring materialization, retention, parity tests
+- Phase 2: PostgreSQL provider, migrations, schema verification, Postgres store/runtime factory, integration tests
+- Phase 3: hosted ingestion + runtime-control sync services with contract validators and golden payload fixtures
+- Phase 4: SQLite, MySQL, and SQL Server providers implemented with shared contract coverage
+
+Observability note:
+
+- We are explicitly applying lessons from the Node.js rollout around hosted API sync (tenant/client-secret auth, endpoint safety, retry policy, idempotency, shutdown flush). The Python ingestion sync foundation now includes these guardrails and dedicated tests.
+
+## Key documents
+
+- `ARCHITECTURE.md`
+- `CONTRACTS.md`
+- `PROVIDER_PARITY.md`
+- `RELEASING.md`
+
+## Local development
+
+Python 3.11+ is required.
+
+Install dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run lint + typing:
+
+```bash
+ruff check .
+mypy
+```
+
+Run Postgres integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_POSTGRES_DSN=postgresql://user:pass@localhost:5432/dbname
+pytest -q tests/test_postgres_integration.py
+```
+
+Run SQLite integration tests:
+
+```bash
+pytest -q tests/test_sqlite_integration.py
+```
+
+Run MySQL integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_MYSQL_DSN=mysql://user:pass@localhost:3306/dbname
+pytest -q tests/test_mysql_integration.py
+```
+
+Run SQL Server integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_SQLSERVER_DSN=Driver={ODBC Driver 18 for SQL Server};Server=localhost,1433;Database=durablestack;Uid=sa;Pwd=Your_password123;Encrypt=no;TrustServerCertificate=yes;
+pytest -q tests/test_sqlserver_integration.py
+```
+
+## Provider matrix
+
+| Provider | Runtime factory | Driver dependency | Integration env var | Integration test |
+| --- | --- | --- | --- | --- |
+| InMemory | `create_durable_stack(...)` | none | none | `tests/test_runtime_phase1.py` |
+| PostgreSQL | `create_durable_stack_postgres(...)` | `asyncpg` | `DURABLESTACK_TEST_POSTGRES_DSN` | `tests/test_postgres_integration.py` |
+| SQLite | `create_durable_stack_sqlite(...)` | stdlib `sqlite3` | none | `tests/test_sqlite_integration.py` |
+| MySQL | `create_durable_stack_mysql(...)` | `pymysql` | `DURABLESTACK_TEST_MYSQL_DSN` | `tests/test_mysql_integration.py` |
+| SQL Server | `create_durable_stack_sqlserver(...)` | `pyodbc` | `DURABLESTACK_TEST_SQLSERVER_DSN` | `tests/test_sqlserver_integration.py` |

durablestack-0.1.0b1/PROVIDER_PARITY.md

@@ -0,0 +1,45 @@
+# Provider Parity (Phase 4)
+
+This document captures provider parity status and migration/locking expectations for the Python runtime.
+
+## Current status
+
+- PostgreSQL: implemented with migrations, schema probes, and lease-fenced semantics.
+- SQLite: implemented with migrations, schema probes, and single-writer transaction locking (`BEGIN IMMEDIATE`).
+- MySQL: implemented with migrations, schema probes, and lease-fenced semantics.
+- SQL Server: implemented with migrations, schema probes, and lease-fenced semantics.
+
+## Shared provider contract expectations
+
+All providers must preserve these behaviors:
+
+- Run lifecycle: `pending -> leased -> succeeded|failed`.
+- Lease-fenced completion: stale worker completion writes are rejected.
+- Retry semantics: failed runs can requeue to `pending`; terminal failure when max attempts reached.
+- Recurring slot uniqueness: one run per (`job_name`, `schedule_slot_utc`) slot.
+- Runtime-control receipts: receipt lease/ack/success/failure lifecycle with command-id dedupe.
+- Retention cleanup: prune terminal runs only.
+
+## Locking and migration notes
+
+- PostgreSQL:
+  - Migration lock: `pg_advisory_xact_lock` using stable key from table prefix.
+  - Claim path: `FOR UPDATE SKIP LOCKED` candidate selection + fenced update.
+- SQLite:
+  - Migration lock: transactional lock via `BEGIN IMMEDIATE`.
+  - Claim/materialization paths: `BEGIN IMMEDIATE` guarded read-update sequences.
+  - Concurrency scope: safe for multi-worker processes sharing one DB file with SQLite single-writer model.
+- MySQL:
+  - Migration lock: named lock via `GET_LOCK` / `RELEASE_LOCK` keyed by table prefix.
+  - Claim path: `FOR UPDATE SKIP LOCKED` candidate selection + fenced updates in transactions.
+- SQL Server:
+  - Migration lock: `sp_getapplock` with transaction-scoped exclusive lock keyed by table prefix.
+  - Claim path: `UPDLOCK` + `READPAST` row selection and fenced updates.
+
+## Test coverage in repo
+
+- Postgres integration: `tests/test_postgres_integration.py` (env-gated).
+- SQLite integration: `tests/test_sqlite_integration.py`.
+- MySQL integration: `tests/test_mysql_integration.py` (env-gated).
+- SQL Server integration: `tests/test_sqlserver_integration.py` (env-gated).
+- Phase 4 provider scaffolds: `tests/test_provider_scaffold_phase4.py`.

durablestack-0.1.0b1/README.md

@@ -0,0 +1,86 @@
+# durablestack-python
+
+DurableStack Python runtime (in active development): durable background jobs and recurring scheduling with platform-compatible contracts.
+
+## Status
+
+This package has completed Phase 4 (provider parity).
+
+Implemented so far:
+
+- Phase 0: scaffold, contracts/constants, validators baseline, docs
+- Phase 1: in-memory runtime/store with lease fencing, retries, recurring materialization, retention, parity tests
+- Phase 2: PostgreSQL provider, migrations, schema verification, Postgres store/runtime factory, integration tests
+- Phase 3: hosted ingestion + runtime-control sync services with contract validators and golden payload fixtures
+- Phase 4: SQLite, MySQL, and SQL Server providers implemented with shared contract coverage
+
+Observability note:
+
+- We are explicitly applying lessons from the Node.js rollout around hosted API sync (tenant/client-secret auth, endpoint safety, retry policy, idempotency, shutdown flush). The Python ingestion sync foundation now includes these guardrails and dedicated tests.
+
+## Key documents
+
+- `ARCHITECTURE.md`
+- `CONTRACTS.md`
+- `PROVIDER_PARITY.md`
+- `RELEASING.md`
+
+## Local development
+
+Python 3.11+ is required.
+
+Install dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run lint + typing:
+
+```bash
+ruff check .
+mypy
+```
+
+Run Postgres integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_POSTGRES_DSN=postgresql://user:pass@localhost:5432/dbname
+pytest -q tests/test_postgres_integration.py
+```
+
+Run SQLite integration tests:
+
+```bash
+pytest -q tests/test_sqlite_integration.py
+```
+
+Run MySQL integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_MYSQL_DSN=mysql://user:pass@localhost:3306/dbname
+pytest -q tests/test_mysql_integration.py
+```
+
+Run SQL Server integration tests (optional):
+
+```bash
+set DURABLESTACK_TEST_SQLSERVER_DSN=Driver={ODBC Driver 18 for SQL Server};Server=localhost,1433;Database=durablestack;Uid=sa;Pwd=Your_password123;Encrypt=no;TrustServerCertificate=yes;
+pytest -q tests/test_sqlserver_integration.py
+```
+
+## Provider matrix
+
+| Provider | Runtime factory | Driver dependency | Integration env var | Integration test |
+| --- | --- | --- | --- | --- |
+| InMemory | `create_durable_stack(...)` | none | none | `tests/test_runtime_phase1.py` |
+| PostgreSQL | `create_durable_stack_postgres(...)` | `asyncpg` | `DURABLESTACK_TEST_POSTGRES_DSN` | `tests/test_postgres_integration.py` |
+| SQLite | `create_durable_stack_sqlite(...)` | stdlib `sqlite3` | none | `tests/test_sqlite_integration.py` |
+| MySQL | `create_durable_stack_mysql(...)` | `pymysql` | `DURABLESTACK_TEST_MYSQL_DSN` | `tests/test_mysql_integration.py` |
+| SQL Server | `create_durable_stack_sqlserver(...)` | `pyodbc` | `DURABLESTACK_TEST_SQLSERVER_DSN` | `tests/test_sqlserver_integration.py` |

durablestack-0.1.0b1/RELEASING.md

@@ -0,0 +1,54 @@
+# Releasing DurableStack Python
+
+This guide covers local pre-publish validation for beta and stable releases.
+
+## Versioning
+
+- Use PEP 440 versioning in `pyproject.toml`.
+- Beta example: `0.1.0b1`.
+- Next beta: increment beta number (`0.1.0b2`, `0.1.0b3`, ...).
+
+## Pre-publish quality gates
+
+Run from `durablestack-python/`:
+
+```bash
+python -m ruff check .
+python -m mypy
+python -m pytest -q
+```
+
+## Build and package validation
+
+Run from `durablestack-python/`:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+Expected artifacts:
+
+- `dist/durablestack-<version>-py3-none-any.whl`
+- `dist/durablestack-<version>.tar.gz`
+
+If `twine check` passes and tests are green, the package is ready for CI-driven publish.
+
+## CI-driven publish on `main`
+
+This repo includes:
+
+- `.github/workflows/ci.yml`: PR/push quality gates
+- `.github/workflows/publish-pypi.yml`: publish pipeline for `main`
+
+Required GitHub secret:
+
+- `PYPI_API_TOKEN`: API token from PyPI account settings
+
+Publish behavior:
+
+1. Push to `main` with an updated `project.version` in `pyproject.toml`.
+2. Workflow runs quality gates, build, and `twine check`.
+3. Workflow checks whether that exact version already exists on PyPI.
+4. If version is new, it publishes `dist/*` to PyPI.
+5. If version already exists, it exits without publishing.