relier 0.1.0__tar.gz

relier-0.1.0/.env.example

@@ -0,0 +1,110 @@
+# =============================================================================
+# Relier configuration — copy to `.env` and customize.
+#
+# Every value below maps to a `RELIER_*` environment variable consumed by
+# `relier.config.Settings`. The defaults shown match the in-code defaults;
+# secrets are left blank.
+#
+# Precedence: real env vars > .env file > built-in defaults.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Core
+# -----------------------------------------------------------------------------
+# Minimum log level: DEBUG | INFO | WARNING | ERROR | CRITICAL
+RELIER_LOG_LEVEL=INFO
+
+# Secret used for internal signing operations. CHANGE before production.
+RELIER_SECRET_KEY=
+
+# -----------------------------------------------------------------------------
+# Redis — direct connection
+# -----------------------------------------------------------------------------
+# Schemes: redis:// | rediss:// (TLS) | redis+unix://
+RELIER_REDIS_URL=redis://localhost:6379/0
+RELIER_REDIS_MAX_CONNECTIONS=20
+RELIER_REDIS_SOCKET_TIMEOUT=5.0
+RELIER_REDIS_CONNECT_TIMEOUT=2.0
+# Set to 0 to disable idle-connection health checks.
+RELIER_REDIS_HEALTH_CHECK_INTERVAL=30
+# Password for data nodes (requirepass / masterauth). Applies to direct AND
+# Sentinel-managed connections.
+RELIER_REDIS_PASSWORD=
+
+# -----------------------------------------------------------------------------
+# Redis — Sentinel (high availability)
+# -----------------------------------------------------------------------------
+# When true, ignores RELIER_REDIS_URL and uses Sentinel for master discovery.
+RELIER_REDIS_USE_SENTINEL=false
+# Comma-separated host:port list. Required when USE_SENTINEL=true.
+# Example: sentinel-1:26379,sentinel-2:26379,sentinel-3:26379
+RELIER_REDIS_SENTINEL_NODES=
+RELIER_REDIS_SENTINEL_MASTER_NAME=relier-master
+# Sentinel's own requirepass — distinct from the data-node password above.
+RELIER_REDIS_SENTINEL_PASSWORD=
+
+# -----------------------------------------------------------------------------
+# Celery integration
+# -----------------------------------------------------------------------------
+RELIER_CELERY_WORKER_COUNT=8
+RELIER_CELERY_WORKER_CONCURRENCY=8
+
+# -----------------------------------------------------------------------------
+# Phoenix — crash detection & resurrection
+# -----------------------------------------------------------------------------
+# Heartbeat TTL in seconds. Worker death is detected after this expires
+# without renewal. Lower = faster detection, more Redis writes.
+RELIER_HEARTBEAT_TTL=10
+# Cap on resurrection attempts before a task is quarantined to the DLQ.
+# Set to 0 to disable resurrection entirely.
+RELIER_MAX_RESURRECTIONS=5
+RELIER_RESURRECTION_CHECK_INTERVAL=2
+RELIER_RESURRECTION_REQUEUE_DELAY=0.05
+RELIER_RESURRECTION_BATCH_SIZE=1000
+# Backpressure: skip resurrector scan when recovery queue is at least this deep.
+RELIER_RESURRECTION_MAX_QUEUE_DEPTH=10000
+
+# -----------------------------------------------------------------------------
+# Idempotency
+# -----------------------------------------------------------------------------
+# Default TTL for result-cache keys (seconds).
+RELIER_IDEMPOTENCY_DEFAULT_TTL=3600
+# In-flight lock TTL. MUST be > RELIER_HARD_TIMEOUT to prevent double execution.
+# Recommended: hard_timeout + 10 seconds safety buffer.
+RELIER_IDEMPOTENCY_INFLIGHT_TTL=120
+
+# -----------------------------------------------------------------------------
+# Checkpointing — partial-result storage
+# -----------------------------------------------------------------------------
+# Checkpoints <= this many bytes are stored inline in Redis.
+RELIER_CHECKPOINT_MAX_INLINE_BYTES=262144
+# Backend for oversized checkpoints: inline | filesystem
+# 'inline' rejects anything above CHECKPOINT_MAX_INLINE_BYTES.
+# 'filesystem' spills to CHECKPOINT_DIR (which MUST be shared storage
+# accessible by every worker and the resurrector).
+RELIER_CHECKPOINT_BACKEND=inline
+RELIER_CHECKPOINT_DIR=/var/lib/relier/checkpoints
+
+# -----------------------------------------------------------------------------
+# Timeouts & graceful shutdown
+# -----------------------------------------------------------------------------
+# SOFT < HARD is enforced at startup.
+RELIER_SOFT_TIMEOUT=25
+RELIER_HARD_TIMEOUT=30
+RELIER_GRACEFUL_SHUTDOWN_TIMEOUT=30
+
+# -----------------------------------------------------------------------------
+# Admission control
+# -----------------------------------------------------------------------------
+# Max dispatches per ADMISSION_WINDOW seconds. Excess returns HTTP 429-able
+# AdmissionRejectedError with Retry-After.
+RELIER_ADMISSION_LIMIT=5000
+RELIER_ADMISSION_WINDOW=10
+
+# -----------------------------------------------------------------------------
+# OpenTelemetry
+# -----------------------------------------------------------------------------
+# When false (default), no-op providers are used; nothing is exported.
+RELIER_OTEL_ENABLED=false
+# OTLP gRPC collector endpoint. Example: http://otel-collector:4317
+RELIER_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

relier-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,112 @@
+name: Bug Report
+description: Something isn't working as documented or expected
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in as much detail as you can, reproduction steps and env info cut resolution time significantly.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug. What did you expect? What actually happened?
+      placeholder: |
+        I called `task.apush(...)` and expected the Phoenix resurrector to re-queue it
+        within ~8s after SIGKILL, but after 60s the task still had not reappeared.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: The smallest code snippet or `docker compose` setup that reliably triggers the bug.
+      render: python
+      placeholder: |
+        from relier.tasks.decorator import rl_task
+
+        @rl_task(hard_timeout=10)
+        async def my_task(x: str) -> str:
+            return x
+
+        # Steps to trigger the bug:
+        # 1. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Error output / logs
+      description: Paste the full traceback, structured logs, or `rl tasks inflight` output if available.
+      render: text
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Which component is affected?
+      multiple: true
+      options:
+        - Phoenix resurrector
+        - Idempotency
+        - Admission control
+        - Dead Letter Queue (DLQ)
+        - Graceful shutdown
+        - Timeouts (soft / hard)
+        - Checkpointing
+        - Schema versioning
+        - CLI (rl)
+        - OpenTelemetry / metrics
+        - Redis HA / Sentinel
+        - Config / settings
+        - Other
+
+  - type: input
+    id: relier-version
+    attributes:
+      label: Relier version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11.9"
+    validations:
+      required: true
+
+  - type: input
+    id: redis-version
+    attributes:
+      label: Redis version and config
+      description: Version + AOF status (redis-cli INFO server | grep redis_version; redis-cli CONFIG GET appendonly)
+      placeholder: "Redis 7.2.4, AOF=yes, maxmemory-policy=noeviction"
+    validations:
+      required: true
+
+  - type: input
+    id: celery-version
+    attributes:
+      label: Celery version
+      placeholder: "5.3.6"
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment environment
+      options:
+        - Bare metal (direct Python processes)
+        - Docker (single node)
+        - Docker Compose
+        - Kubernetes
+        - Other
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Anything else — rl bench output, network topology, load characteristics, etc.

relier-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Troubleshooting & FAQ
+    url: https://getrelier.github.io/relier/troubleshooting/
+    about: Most common issues and their fixes are documented here.
+  - name: Documentation
+    url: https://getrelier.github.io/relier/
+    about: Full docs — configuration, deployment, patterns, API reference.
+  - name: GitHub Discussions
+    url: https://github.com/getrelier/relier/discussions
+    about: General questions, ideas, and show-and-tell.

relier-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,76 @@
+name: Feature Request
+description: Suggest a new feature or improvement to an existing one
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening, check [the docs](https://getrelier.github.io/relier/) and existing issues the feature may already exist or be planned. The most useful requests include a concrete use-case from a real system.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the specific situation where this feature would help. Concrete workload beats abstract ask every time.
+      placeholder: |
+        We dispatch ~10k tasks/minute from multiple FastAPI pods. When one pod is
+        doing a rolling deploy, admission control triggers across the cluster, we
+        need per-producer quotas, not a single global counter.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed solution
+      description: What would the API / behaviour look like? A code sketch is worth a thousand words.
+      render: python
+      placeholder: |
+        @rl_task(admission_key="producer:{producer_id}", admission_limit=1000)
+        async def process(item: str, producer_id: str) -> None:
+            ...
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What are you doing today to work around this? What other solutions did you consider?
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      multiple: true
+      options:
+        - Phoenix resurrection
+        - Idempotency
+        - Admission control
+        - Dead Letter Queue
+        - Graceful shutdown
+        - Timeouts
+        - Checkpointing
+        - Schema versioning
+        - CLI (rl)
+        - OpenTelemetry / metrics
+        - Redis HA / Sentinel
+        - Configuration
+        - Documentation
+        - Performance
+        - New primitive (not listed)
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How blocked are you without this?
+      options:
+        - Not blocked — nice to have
+        - Somewhat blocked — have a workaround
+        - Very blocked — can't use Relier without this
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Relevant links, prior art (Temporal, Faust, AWS Step Functions equivalent), or architecture diagrams.

relier-0.1.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,55 @@
+name: Question / Support
+description: Usage question, integration help, or something the docs didn't answer
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Check the [Troubleshooting & FAQ](https://getrelier.github.io/relier/troubleshooting/) first — your question may be answered there. For quick questions, GitHub Discussions is faster than an issue.
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Your question
+      description: Be as specific as you can. What are you trying to do? What did you try?
+      placeholder: |
+        I'm integrating Relier with a Django app that uses `task.apply_async()` everywhere.
+        Should I switch all call sites to `task.push()`, or is there a compatibility shim?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Getting started / installation
+        - FastAPI integration
+        - Django integration
+        - Flask integration
+        - Configuration
+        - Phoenix resurrection
+        - Idempotency
+        - Admission control
+        - DLQ / dead letter queue
+        - Timeouts
+        - Graceful shutdown
+        - CLI (rl)
+        - Redis HA / Sentinel
+        - OpenTelemetry / metrics
+        - Performance / benchmarks
+        - Deployment
+        - Other
+
+  - type: textarea
+    id: what-tried
+    attributes:
+      label: What have you tried?
+      description: Relevant code, config, or docs sections you already looked at.
+      render: python
+
+  - type: input
+    id: relier-version
+    attributes:
+      label: Relier version
+      placeholder: "0.1.0"

relier-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+## What this PR does
+
+<!-- One sentence: the change and its motivation. -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature / primitive
+- [ ] Performance improvement
+- [ ] Refactor (no behaviour change)
+- [ ] Documentation
+- [ ] CI / tooling
+- [ ] Dependency update
+
+## Checklist
+
+### Code quality
+- [ ] `make check` passes (ruff + mypy)
+- [ ] `pre-commit run --all-files` passes (or `make setup` to install hooks, then commit runs them automatically)
+- [ ] No debug `print()` / `breakpoint()` left in `src/`
+- [ ] New public API has type annotations
+
+### Tests
+- [ ] New or updated unit tests cover the change
+- [ ] Integration tests cover the change (if it touches Redis, Celery, or the decorator)
+- [ ] Coverage stays at or above 90% (`make test-integration`)
+
+### Reliability (for changes to core primitives)
+- [ ] Considered fence-token correctness (stale worker cannot commit after resurrection)
+- [ ] Considered idempotency invariants (no double-execution window)
+- [ ] Considered Redis AOF + noeviction assumptions
+- [ ] Chaos suite still validates the guarantees (`make bench` or `python -m bench.bench --synthetic`)
+
+### Documentation
+- [ ] `docs/` updated if this changes user-visible behaviour
+- [ ] `.env.example` updated if new config fields were added
+- [ ] CLI help text updated if new `rl` commands were added
+
+## Testing notes
+
+<!-- How did you verify this? Paste relevant test output, bench results, or `rl tasks inflight` screenshots. -->
+
+## Breaking changes
+
+<!-- If this changes the public API, Redis key layout, Lua scripts, or wire format, describe the impact and migration path. -->

relier-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3

relier-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: Relier CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    # Run on every PR targeting main, regardless of source branch name.
+    # The previous glob-list silently skipped chore/, docs/, refactor/, etc.
+    branches: [main]
+
+jobs:
+  lint-and-typecheck:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run Ruff Linter
+        run: uv run ruff check src/
+
+      - name: Run Ruff Formatter (Check)
+        run: uv run ruff format --check src/
+
+      - name: Run Mypy Type Checker
+        run: uv run mypy src/
+
+  test-unit:
+    name: Unit Tests (>=95% coverage)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install Relier and Dev Dependencies
+        run: uv sync --all-groups
+
+      - name: Run unit suite with 95% coverage gate
+        run: |
+          uv run pytest tests/unit/ \
+            --cov=src/relier \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=95
+
+  test-integration:
+    name: Integration Tests (>=80% coverage)
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7.2-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install Relier and Dev Dependencies
+        run: uv sync --all-groups
+
+      - name: Run integration suite with 80% coverage gate
+        env:
+          RELIER_REDIS_URL: redis://localhost:6379/0
+        run: |
+          uv run pytest tests/integration/ \
+            --cov=src/relier \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=80 \
+            --timeout=120 \
+            --reruns 2 \
+            --reruns-delay 1
+
+  build-check:
+    name: Validate Build Artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - name: Build Package Wheels
+        run: uv build

relier-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,30 @@
+name: "CodeQL Security Scanning"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '30 18 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze Code
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4

relier-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Relier Docs CI/CD
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  validate-and-deploy:
+    name: Build and Verify Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Strict Build Validation Test
+        run: uv run --with mkdocs-material --with pymdown-extensions mkdocs build --strict
+
+      - name: Deploy to GitHub Pages (Main Branch Only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+          uv run --with mkdocs-material --with pymdown-extensions mkdocs gh-deploy --force