ad-tech-inc-resilient-http 0.1.0__tar.gz

ad_tech_inc_resilient_http-0.1.0/.gemini/agents/issue-runner.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+#-------------------------
+# Config
+#-------------------------
+ITERATIONS="${1:-10}"
+
+MAIN_BRANCH="${MAIN_BRANCH:-main}"
+BRANCH="${BRANCH:-overnight-batch-$(date +%Y%m%d-%H%M%S)}"
+
+PROMPT_FILE=".gemini/prompts/issue-worker.md"
+
+SUCCESS_FILE=".agent-complete"
+STUCK_FILE=".agent-stuck"
+
+#-------------------------
+# Helpers
+#-------------------------
+cleanup() {
+    rm -f "$SUCCESS_FILE" "$STUCK_FILE"
+}
+
+trap cleanup EXIT
+
+#-------------------------
+# Validate
+#-------------------------
+if ! command -v gemini >/dev/null 2>&1; then
+    echo "gemini command not found."
+    exit 1
+fi
+
+if ! command -v gh >/dev/null 2>&1; then
+    echo "GitHub CLI (gh) is not installed. Please install it to use this agent."
+    exit 1
+fi
+
+if [ ! -f "$PROMPT_FILE" ]; then
+    echo "Prompt file missing: $PROMPT_FILE"
+    exit 1
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo "Working directory is dirty. Commit or stash changes first."
+    exit 1
+fi
+
+#-------------------------
+# Setup
+#-------------------------
+git checkout "$MAIN_BRANCH"
+git pull origin "$MAIN_BRANCH"
+
+git checkout -b "$BRANCH"
+
+echo "Branch: $BRANCH"
+echo "Iterations: $ITERATIONS"
+echo "Prompt: $PROMPT_FILE"
+
+#-------------------------
+# Agent Loop
+#-------------------------
+for ((i=1; i<=ITERATIONS; i++)); do
+
+    echo
+    echo "=== Iteration $i/$ITERATIONS ==="
+
+    if ! timeout 5m gemini -p "$(cat "$PROMPT_FILE")"; then
+        echo "Gemini timed out"
+        exit 1
+    fi
+
+    if [ -f "$STUCK_FILE" ]; then
+        echo "Agent stuck:"
+        cat "$STUCK_FILE"
+        exit 1
+    fi
+
+    if [ -f "$SUCCESS_FILE" ]; then
+        echo "All tasks completed."
+        break
+    fi
+
+done
+
+#-------------------------
+# Push
+#-------------------------
+git push -u origin "$BRANCH"
+
+echo
+echo "Finished."
+echo "Review:"
+echo "git log $MAIN_BRANCH..$BRANCH"

ad_tech_inc_resilient_http-0.1.0/.gemini/prompts/issue-worker.md

@@ -0,0 +1,30 @@
+# Issue Worker
+
+## Goal
+
+Complete one issue at a time.
+
+## Instructions
+
+1. Use github-issues skill to fetch open issues.
+2. Check existing Tasks and skip issues already completed or in_progress.
+3. Pick the most appropriate remaining issue.
+4. Create a Task and mark it in_progress.
+5. Implement the fix or feature.
+6. Add tests if needed.
+7. Run formatting.
+8. Run the full test suite.
+
+If tests fail:
+- attempt fixes
+- after 3 failed attempts mark the Task stuck
+- create .agent-stuck with issue number and reason
+
+If no issues remain:
+- create .agent-complete
+- exit
+
+Commit changes:
+ISSUE #<number>: <short description>
+
+Mark the Task completed.

ad_tech_inc_resilient_http-0.1.0/.gemini/skills/github-issues/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: github-issues
+description: Use this skill whenever work should be selected from GitHub issues, tasks need tracking, or an autonomous agent is processing repository issues.
+---
+
+# GitHub Issues Skill
+
+## Purpose
+
+Process repository issues one at a time in a predictable and repeatable manner.
+
+## Workflow
+
+### 1. Fetch Issues
+
+Retrieve all open GitHub issues.
+
+Ignore:
+
+* closed issues
+* duplicate issues
+* blocked issues
+* issues already marked completed
+* issues already marked in_progress
+
+### 2. Select Issue
+
+Choose exactly one issue.
+
+Priority order:
+
+1. high priority
+2. oldest open issue
+3. smallest independent issue
+
+### 3. Start Task
+
+Create or update task tracking.
+
+Mark issue status:
+
+in_progress
+
+Record:
+
+* issue number
+* title
+
+### 4. Implement
+
+Implement only the changes necessary to satisfy the issue.
+
+Avoid unrelated refactoring.
+
+Follow existing project conventions.
+
+### 5. Testing
+
+Add or update tests if required.
+
+Run formatting.
+
+Run the complete test suite.
+
+### 6. Failure Handling
+
+If tests fail:
+
+1. investigate
+2. fix
+3. rerun tests
+
+Maximum attempts: 3
+
+If still failing:
+
+Create:
+
+.agent-stuck
+
+Contents:
+
+Issue #<number>
+Reason: <explanation>
+
+Mark task:
+
+stuck
+
+Stop execution.
+
+### 7. Success Handling
+
+Commit changes:
+
+ISSUE #<number>: <short description>
+
+Mark task:
+
+completed
+
+### 8. Completion
+
+If no issues remain:
+
+Create:
+
+.agent-complete
+
+Exit successfully.
+
+## Rules
+
+* Work on exactly one issue.
+* Never skip testing.
+* Never skip formatting.
+* Never create both `.agent-complete` and `.agent-stuck`.
+* Prefer small reviewable commits.

ad_tech_inc_resilient_http-0.1.0/.gemini/skills/resilience-expert/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: resilience-expert
+description: Expert guidance for maintaining, extending, and debugging the Resilient HTTP Client library. Use when adding resilience patterns, new storage backends, or fixing integration bugs in examples and tests.
+---
+
+# Resilience Expert
+
+Expert guidance for the `resilient-http-client` library.
+
+## Core Concepts
+
+- **Architecture**: See [architecture.md](references/architecture.md) for how components coordinate.
+- **Testing**: See [testing-patterns.md](references/testing-patterns.md) for standardized mocks.
+
+## Workflows
+
+### Extending the Library
+
+1.  **New Resilience Pattern**: Implement the logic in a new module, integrate it into `ResilientHttpClient.request()`, and add configuration to `ResilienceConfig`.
+2.  **New Storage Backend**: Inherit from the same interface used by `FailureStore` (methods like `get_state`, `set_state`, `increment_failures`).
+
+### Debugging Issues
+
+1.  **Verify State**: Check the `FailureStore` state in Redis using `redis-cli`.
+2.  **Check Transitions**: Use `simulate_outage.py` to verify Circuit Breaker transitions (CLOSED -> OPEN -> HALF-OPEN -> CLOSED).
+3.  **Await Everything**: Ensure all async methods in `FailureStore` and `Client` are properly awaited.
+
+### Testing Requirements
+
+- Always add unit tests in `tests/`.
+- Use `pytest-asyncio` for async tests.
+- Maintain consistency with `FakeRedis` and `MockResponse` mocks.
+- Ensure `PYTHONPATH=.` is set when running tests.
+
+## Rules
+
+- Use `CircuitState` enum for all state-related logic.
+- Prefer `async with` context managers for `ResilientHttpClient`.
+- Maintain docstrings for public interfaces in `src/client.py`.

ad_tech_inc_resilient_http-0.1.0/.gemini/skills/resilience-expert/references/architecture.md

@@ -0,0 +1,23 @@
+# Resilient HTTP Client Architecture
+
+The library is designed around the **Orchestrator** pattern where `ResilientHttpClient` coordinates several specialized components.
+
+## Component Coordination
+
+1.  **ResilientHttpClient**: The entry point. It manages the lifecycle of the request.
+2.  **CircuitBreaker**: Consulted before every request. Updates state based on success/failure.
+3.  **FailureStore**: Persistent storage (e.g., Redis) for failure metrics and circuit state.
+4.  **RetryPolicy**: Determines if and when to retry based on exponential backoff.
+5.  **HttpExecutor**: Wraps `httpx` and normalizes responses into `HttpResponse`.
+6.  **FallbackHandler**: Executes registered fallback logic when all else fails.
+
+## Request Flow
+
+1.  Check `circuit.allow_request()`.
+2.  If blocked, return `fallback.run("circuit_open")`.
+3.  Loop for retries:
+    a. Execute `http.send()`.
+    b. If success, `circuit.on_success()` and return data.
+    c. If failure, `circuit.on_failure()`.
+    d. Check `retry.can_retry()`. If yes, `retry.wait()` and continue.
+4.  If loop exits, return `fallback.run(last_error)`.

ad_tech_inc_resilient_http-0.1.0/.gemini/skills/resilience-expert/references/testing-patterns.md

@@ -0,0 +1,44 @@
+# Testing Patterns
+
+Consistency in testing is critical to ensure mocks correctly simulate the production components.
+
+## FakeRedis Mock
+
+Always use the standardized `FakeRedis` for unit and integration tests. It must support `nx` and `ex` arguments.
+
+```python
+class FakeRedis:
+    def __init__(self):
+        self.db = {}
+
+    async def get(self, key):
+        return self.db.get(key)
+
+    async def set(self, key, value, ex=None, nx=False):
+        if nx and key in self.db:
+            return False
+        self.db[key] = value
+        return True
+
+    async def incr(self, key):
+        self.db[key] = int(self.db.get(key, 0)) + 1
+        return self.db[key]
+
+    async def expire(self, key, ttl, nx=False):
+        pass # Optional: implement for TTL specific tests
+
+    async def delete(self, key):
+        self.db.pop(key, None)
+```
+
+## Mocking HTTP Responses
+
+When mocking `HttpExecutor`, return a `MockResponse` object that implements `is_success`, `status_code`, and `data`.
+
+```python
+class MockResponse:
+    def __init__(self, is_success, status_code, data):
+        self.is_success = is_success
+        self.status_code = status_code
+        self.data = data
+```

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

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pytest
+        run: uv run pytest

ad_tech_inc_resilient_http-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Required for trusted publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ad_tech_inc_resilient_http-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

ad_tech_inc_resilient_http-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ad_tech_inc_resilient_http-0.1.0/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "cooldown"
+    ]
+}

ad_tech_inc_resilient_http-0.1.0/GEMINI.md

@@ -0,0 +1,32 @@
+# 🛡️ Resilient HTTP Client - Project Instructions
+
+This file provides foundational guidance for AI agents working on the `resilient-http-client` project.
+
+## 🏗️ Architectural Core
+This library is built on the principle of **strict state management** for resilience patterns.
+- **State Machine**: All circuit breaker logic must strictly follow the `CLOSED`, `OPEN`, `HALF-OPEN` transitions.
+- **Async First**: All network and storage operations MUST be asynchronous and properly awaited.
+- **Pluggable Storage**: The `FailureStore` is the source of truth. Ensure any changes maintain compatibility with distributed backends (like Redis).
+
+## 🛠️ Tech Stack & Tooling
+- **Language**: Python 3.12+
+- **HTTP Engine**: `httpx` (Asynchronous)
+- **Dependency Management**: `uv`
+- **Testing**: `pytest` with `pytest-asyncio`
+- **Quality**: Adhere to PEP 8; use explicit type hints for all public APIs.
+
+## 🧪 Testing Mandates
+A change is not complete without verification.
+- **Unit Tests**: Every new resilience logic must have 100% branch coverage in `tests/`.
+- **Chaos Testing**: When modifying `CircuitBreaker` or `RetryPolicy`, you must run or update `tests/test_flaky_resilience.py` to simulate real-world failure modes.
+- **Integration**: Verify changes against the Redis backend if storage logic is modified.
+
+## 🔄 Workflows
+- **Specialized Guidance**: Always activate the `resilience-expert` skill (`activate_skill(name="resilience-expert")`) before making architectural changes.
+- **Environment**: Always run commands with `PYTHONPATH=.` or via `uv run` to ensure local modules are discoverable.
+- **Validation**: Before finishing a task, run `pytest` to ensure no regressions.
+
+## 📚 References
+- Architecture: `docs/diagrams/architecture.mmd`
+- State Machine: `docs/diagrams/state_machine.mmd`
+- Core Implementation: `src/client.py`