interposition 0.1.0__tar.gz

interposition-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Osoekawa IT Laboratory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

interposition-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: interposition
+Version: 0.1.0
+Summary: Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control.
+Author: osoken
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/osoekawaitlab/interposition
+Project-URL: Repository, https://github.com/osoekawaitlab/interposition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Dynamic: license-file
+
+# interposition
+
+Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control.
+
+## Overview
+
+Interposition is a Python library for replaying recorded interactions. Unlike VCRpy or other HTTP-specific tools, **Interposition does not automatically hook into network libraries**.
+
+Instead, it provides a **pure logic engine** for storage, matching, and replay. You write the adapter for your specific target (HTTP client, database driver, IoT message handler), and Interposition handles the rest.
+
+**Key Features:**
+
+- **Protocol-agnostic**: Works with any protocol (HTTP, gRPC, SQL, Pub/Sub, etc.)
+- **Type-safe**: Full mypy strict mode support with Pydantic v2
+- **Immutable**: All data structures are frozen Pydantic models
+- **Serializable**: Built-in JSON/YAML serialization for cassette persistence
+- **Memory-efficient**: O(1) lookup with fingerprint indexing
+- **Streaming**: Generator-based response delivery
+
+## Architecture
+
+Interposition sits behind your application's data access layer. You provide the "Adapter" that captures live traffic or requests replay from the Broker.
+
+```text
++-------------+      +------------------+      +---------------+
+| Application | <--> | Your Adapter     | <--> | Interposition |
++-------------+      +------------------+      +---------------+
+                            |                          |
+                       (Traps calls)              (Manages)
+                                                       |
+                                                  [Cassette]
+```
+
+## Installation
+
+```bash
+pip install interposition
+```
+
+## Practical Integration (Pytest Recipe)
+
+The most common use case is using Interposition as a test fixture. Here is a production-ready recipe for `pytest`:
+
+```python
+import pytest
+from interposition import Broker, Cassette, InteractionRequest
+
+@pytest.fixture
+def cassette_broker():
+    # Load cassette from a JSON file (or create one programmatically)
+    with open("tests/fixtures/my_cassette.json", "rb") as f:
+        cassette = Cassette.model_validate_json(f.read())
+    return Broker(cassette)
+
+def test_user_service(cassette_broker, monkeypatch):
+    # 1. Create your adapter (mocking your actual client)
+    def mock_fetch(url):
+        request = InteractionRequest(
+            protocol="http",
+            action="GET",
+            target=url,
+            headers=(),
+            body=b"",
+        )
+        # Delegate to Interposition
+        chunks = list(cassette_broker.replay(request))
+        return chunks[0].data
+
+    # 2. Inject the adapter
+    monkeypatch.setattr("my_app.client.fetch", mock_fetch)
+
+    # 3. Run your test
+    from my_app import get_user_name
+    assert get_user_name(42) == "Alice"
+```
+
+## Protocol-Agnostic Examples
+
+Interposition shines where HTTP-only tools fail.
+
+### SQL Database Query
+
+```python
+request = InteractionRequest(
+    protocol="postgres",
+    action="SELECT",
+    target="users_table",
+    headers=(),
+    body=b"SELECT id, name FROM users WHERE id = 42",
+)
+# Replay returns: b'[(42, "Alice")]'
+```
+
+### MQTT / PubSub Message
+
+```python
+request = InteractionRequest(
+    protocol="mqtt",
+    action="subscribe",
+    target="sensors/temp/room1",
+    headers=(("qos", "1"),),
+    body=b"",
+)
+# Replay returns stream of messages: b'24.5', b'24.6', ...
+```
+
+## Usage Guide
+
+### Manual Construction (Quick Start)
+
+If you need to build interactions programmatically (e.g., for seeding tests):
+
+```python
+from interposition import (
+    Broker,
+    Cassette,
+    Interaction,
+    InteractionRequest,
+    ResponseChunk,
+)
+
+# 1. Define the Request
+request = InteractionRequest(
+    protocol="api",
+    action="query",
+    target="users/42",
+    headers=(),
+    body=b"",
+)
+
+# 2. Define the Response
+chunks = (
+    ResponseChunk(data=b'{"id": 42, "name": "Alice"}', sequence=0),
+)
+
+# 3. Create Interaction & Cassette
+interaction = Interaction(
+    request=request,
+    fingerprint=request.fingerprint(),
+    response_chunks=chunks,
+)
+cassette = Cassette(interactions=(interaction,))
+
+# 4. Replay
+broker = Broker(cassette=cassette)
+response = list(broker.replay(request))
+```
+
+### Persistence & Serialization
+
+Interposition models are Pydantic v2 models, making serialization trivial.
+
+```python
+# Save to JSON
+with open("cassette.json", "w") as f:
+    f.write(cassette.model_dump_json(indent=2))
+
+# Load from JSON
+with open("cassette.json") as f:
+    cassette = Cassette.model_validate_json(f.read())
+
+# Generate JSON Schema
+schema = Cassette.model_json_schema()
+```
+
+### Streaming Responses
+
+For large files or streaming protocols, responses are yielded lazily:
+
+```python
+# The broker returns a generator
+for chunk in broker.replay(request):
+    print(f"Received chunk: {len(chunk.data)} bytes")
+```
+
+### Error Handling
+
+If a matching interaction is not found, the broker raises `InteractionNotFoundError`:
+
+```python
+from interposition import InteractionNotFoundError
+
+try:
+    broker.replay(unknown_request)
+except InteractionNotFoundError as e:
+    print(f"Not recorded: {e.request.target}")
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) (recommended)
+
+### Setup & Testing
+
+```bash
+# Clone and install
+git clone https://github.com/osoekawaitlab/interposition.git
+cd interposition
+uv pip install -e . --group=dev
+
+# Run tests
+nox -s tests
+```
+
+## License
+
+MIT

interposition-0.1.0/README.md

@@ -0,0 +1,210 @@
+# interposition
+
+Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control.
+
+## Overview
+
+Interposition is a Python library for replaying recorded interactions. Unlike VCRpy or other HTTP-specific tools, **Interposition does not automatically hook into network libraries**.
+
+Instead, it provides a **pure logic engine** for storage, matching, and replay. You write the adapter for your specific target (HTTP client, database driver, IoT message handler), and Interposition handles the rest.
+
+**Key Features:**
+
+- **Protocol-agnostic**: Works with any protocol (HTTP, gRPC, SQL, Pub/Sub, etc.)
+- **Type-safe**: Full mypy strict mode support with Pydantic v2
+- **Immutable**: All data structures are frozen Pydantic models
+- **Serializable**: Built-in JSON/YAML serialization for cassette persistence
+- **Memory-efficient**: O(1) lookup with fingerprint indexing
+- **Streaming**: Generator-based response delivery
+
+## Architecture
+
+Interposition sits behind your application's data access layer. You provide the "Adapter" that captures live traffic or requests replay from the Broker.
+
+```text
++-------------+      +------------------+      +---------------+
+| Application | <--> | Your Adapter     | <--> | Interposition |
++-------------+      +------------------+      +---------------+
+                            |                          |
+                       (Traps calls)              (Manages)
+                                                       |
+                                                  [Cassette]
+```
+
+## Installation
+
+```bash
+pip install interposition
+```
+
+## Practical Integration (Pytest Recipe)
+
+The most common use case is using Interposition as a test fixture. Here is a production-ready recipe for `pytest`:
+
+```python
+import pytest
+from interposition import Broker, Cassette, InteractionRequest
+
+@pytest.fixture
+def cassette_broker():
+    # Load cassette from a JSON file (or create one programmatically)
+    with open("tests/fixtures/my_cassette.json", "rb") as f:
+        cassette = Cassette.model_validate_json(f.read())
+    return Broker(cassette)
+
+def test_user_service(cassette_broker, monkeypatch):
+    # 1. Create your adapter (mocking your actual client)
+    def mock_fetch(url):
+        request = InteractionRequest(
+            protocol="http",
+            action="GET",
+            target=url,
+            headers=(),
+            body=b"",
+        )
+        # Delegate to Interposition
+        chunks = list(cassette_broker.replay(request))
+        return chunks[0].data
+
+    # 2. Inject the adapter
+    monkeypatch.setattr("my_app.client.fetch", mock_fetch)
+
+    # 3. Run your test
+    from my_app import get_user_name
+    assert get_user_name(42) == "Alice"
+```
+
+## Protocol-Agnostic Examples
+
+Interposition shines where HTTP-only tools fail.
+
+### SQL Database Query
+
+```python
+request = InteractionRequest(
+    protocol="postgres",
+    action="SELECT",
+    target="users_table",
+    headers=(),
+    body=b"SELECT id, name FROM users WHERE id = 42",
+)
+# Replay returns: b'[(42, "Alice")]'
+```
+
+### MQTT / PubSub Message
+
+```python
+request = InteractionRequest(
+    protocol="mqtt",
+    action="subscribe",
+    target="sensors/temp/room1",
+    headers=(("qos", "1"),),
+    body=b"",
+)
+# Replay returns stream of messages: b'24.5', b'24.6', ...
+```
+
+## Usage Guide
+
+### Manual Construction (Quick Start)
+
+If you need to build interactions programmatically (e.g., for seeding tests):
+
+```python
+from interposition import (
+    Broker,
+    Cassette,
+    Interaction,
+    InteractionRequest,
+    ResponseChunk,
+)
+
+# 1. Define the Request
+request = InteractionRequest(
+    protocol="api",
+    action="query",
+    target="users/42",
+    headers=(),
+    body=b"",
+)
+
+# 2. Define the Response
+chunks = (
+    ResponseChunk(data=b'{"id": 42, "name": "Alice"}', sequence=0),
+)
+
+# 3. Create Interaction & Cassette
+interaction = Interaction(
+    request=request,
+    fingerprint=request.fingerprint(),
+    response_chunks=chunks,
+)
+cassette = Cassette(interactions=(interaction,))
+
+# 4. Replay
+broker = Broker(cassette=cassette)
+response = list(broker.replay(request))
+```
+
+### Persistence & Serialization
+
+Interposition models are Pydantic v2 models, making serialization trivial.
+
+```python
+# Save to JSON
+with open("cassette.json", "w") as f:
+    f.write(cassette.model_dump_json(indent=2))
+
+# Load from JSON
+with open("cassette.json") as f:
+    cassette = Cassette.model_validate_json(f.read())
+
+# Generate JSON Schema
+schema = Cassette.model_json_schema()
+```
+
+### Streaming Responses
+
+For large files or streaming protocols, responses are yielded lazily:
+
+```python
+# The broker returns a generator
+for chunk in broker.replay(request):
+    print(f"Received chunk: {len(chunk.data)} bytes")
+```
+
+### Error Handling
+
+If a matching interaction is not found, the broker raises `InteractionNotFoundError`:
+
+```python
+from interposition import InteractionNotFoundError
+
+try:
+    broker.replay(unknown_request)
+except InteractionNotFoundError as e:
+    print(f"Not recorded: {e.request.target}")
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) (recommended)
+
+### Setup & Testing
+
+```bash
+# Clone and install
+git clone https://github.com/osoekawaitlab/interposition.git
+cd interposition
+uv pip install -e . --group=dev
+
+# Run tests
+nox -s tests
+```
+
+## License
+
+MIT

interposition-0.1.0/pyproject.toml

@@ -0,0 +1,130 @@
+[project]
+name = "interposition"
+dynamic = ["version"]
+description = "Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "osoken" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0,<3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/osoekawaitlab/interposition"
+Repository = "https://github.com/osoekawaitlab/interposition"
+
+[build-system]
+requires = ["setuptools>=70.1"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {attr = "interposition._version.__version__"}
+
+[dependency-groups]
+dev = [
+    "getgauge>=0.5.0",
+    "mypy>=1.18.2",
+    "nox>=2025.11.12",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+    "pytest-randomly>=4.0.1",
+    "ruff>=0.14.5",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-awesome-nav>=3.2.0",
+    "mkdocs-material>=9.7.0",
+    "mkdocstrings>=0.30.1",
+    "mkdocstrings-python>=1.19.0",
+]
+
+[tool.ruff]
+indent-width = 4
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # trailing-comma-missing (conflicts with formatter)
+    "ISC001",  # single-line-implicit-string-concatenation (conflicts with formatter)
+    "D203",    # one-blank-line-before-class (conflicts with D211)
+    "D213",    # multi-line-summary-second-line (conflicts with D212)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",    # assert-used (pytest uses asserts)
+]
+"e2e/**/*.py" = [
+    "S101",  # assert-used (E2E tests use asserts)
+    "S607",  # start-process-with-partial-path
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+check_untyped_defs = true
+disallow_any_explicit = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+show_error_codes = true
+strict_equality = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true
+mypy_path = "e2e/stubs"
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = "pydantic"
+disallow_any_explicit = false
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--doctest-modules",
+]
+markers = [
+    "unit: Unit tests (pure logic, no external dependencies)",
+    "e2e: End-to-end tests with mocked SDKs",
+]

interposition-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

interposition-0.1.0/src/interposition/__init__.py

@@ -0,0 +1,28 @@
+"""Protocol-agnostic interaction interposition with lifecycle hooks.
+
+Provides record, replay, and control capabilities.
+"""
+
+from interposition._version import __version__
+from interposition.errors import InteractionNotFoundError
+from interposition.models import (
+    Cassette,
+    Interaction,
+    InteractionRequest,
+    InteractionValidationError,
+    RequestFingerprint,
+    ResponseChunk,
+)
+from interposition.services import Broker
+
+__all__ = [
+    "Broker",
+    "Cassette",
+    "Interaction",
+    "InteractionNotFoundError",
+    "InteractionRequest",
+    "InteractionValidationError",
+    "RequestFingerprint",
+    "ResponseChunk",
+    "__version__",
+]

interposition-0.1.0/src/interposition/_version.py

@@ -0,0 +1,3 @@
+"""Version information for interposition."""
+
+__version__ = "0.1.0"

interposition-0.1.0/src/interposition/errors.py

@@ -0,0 +1,24 @@
+"""Exceptions for interposition."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from interposition.models import InteractionRequest
+
+
+class InteractionNotFoundError(Exception):
+    """Raised when no matching interaction is found in cassette."""
+
+    def __init__(self, request: InteractionRequest) -> None:
+        """Initialize with request that failed to match.
+
+        Args:
+            request: The unmatched request
+        """
+        super().__init__(
+            f"No matching interaction for {request.protocol}:"
+            f"{request.action}:{request.target}"
+        )
+        self.request: InteractionRequest = request

interposition-0.1.0/src/interposition/models.py

@@ -0,0 +1,225 @@
+"""Data models for interposition."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    PrivateAttr,
+    field_validator,
+    model_validator,
+)
+from typing_extensions import Self
+
+SHA256_HEX_LENGTH = 64
+
+# JSON serialization settings for canonical fingerprint generation
+_CANONICAL_JSON_SEPARATORS = (",", ":")
+_CANONICAL_JSON_SORT_KEYS = True
+
+
+class InteractionValidationError(ValueError):
+    """Raised when interaction validation fails."""
+
+
+class ResponseChunk(BaseModel):
+    """Discrete piece of response data.
+
+    Attributes:
+        data: Chunk payload as bytes
+        sequence: Zero-based chunk position in response stream
+        metadata: Optional chunk metadata as (key, value) string pairs.
+            Examples: timing info, encoding, content-type for this chunk.
+            Default is empty tuple.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    data: bytes
+    sequence: int
+    metadata: tuple[tuple[str, str], ...] = ()
+
+
+class InteractionRequest(BaseModel):
+    """Structured representation of a protocol-agnostic request.
+
+    Attributes:
+        protocol: Protocol identifier (e.g., "grpc", "graphql", "mqtt")
+        action: Action/method name (e.g., "ListUsers", "query", "publish")
+        target: Target resource (e.g., "users.UserService", "topic/sensors")
+        headers: Request headers as immutable sequence of key-value pairs
+        body: Request body content as bytes
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    protocol: str
+    action: str
+    target: str
+    headers: tuple[tuple[str, str], ...]
+    body: bytes
+
+    def fingerprint(self) -> RequestFingerprint:
+        """Generate stable fingerprint for efficient matching.
+
+        Returns:
+            RequestFingerprint derived from all request fields.
+        """
+        return RequestFingerprint.from_request(self)
+
+
+class RequestFingerprint(BaseModel):
+    """Stable unique identifier for request matching.
+
+    Attributes:
+        value: SHA-256 hash of canonicalized request fields
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    value: str
+
+    @field_validator("value")
+    @classmethod
+    def validate_sha256_hex(cls, v: str) -> str:
+        """Validate that value is a valid SHA-256 hex string.
+
+        Args:
+            v: The fingerprint value to validate
+
+        Returns:
+            The validated value
+
+        Raises:
+            ValueError: If value is not exactly 64 hex characters
+        """
+        if len(v) != SHA256_HEX_LENGTH:
+            msg = f"SHA-256 hex must be exactly {SHA256_HEX_LENGTH} characters"
+            raise ValueError(msg)
+        if not all(c in "0123456789abcdef" for c in v):
+            msg = "Invalid hex characters in fingerprint"
+            raise ValueError(msg)
+        return v
+
+    @classmethod
+    def from_request(cls, request: InteractionRequest) -> Self:
+        """Create fingerprint from InteractionRequest.
+
+        Args:
+            request: The request to fingerprint
+
+        Returns:
+            RequestFingerprint with SHA-256 hash value
+        """
+        # Canonical order: protocol, action, target, headers, body
+        # Preserve header ordering to avoid normalization.
+        canonical_data = [
+            request.protocol,
+            request.action,
+            request.target,
+            request.headers,
+            request.body.hex(),
+        ]
+        canonical = json.dumps(
+            canonical_data,
+            separators=_CANONICAL_JSON_SEPARATORS,
+            sort_keys=_CANONICAL_JSON_SORT_KEYS,
+        )
+        hash_value = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+        return cls(value=hash_value)
+
+
+class Interaction(BaseModel):
+    """Complete request-response pair for replay.
+
+    Attributes:
+        request: The original InteractionRequest
+        fingerprint: Precomputed request fingerprint for matching
+        response_chunks: Ordered sequence of response chunks
+        metadata: Optional interaction metadata as (key, value) pairs.
+            Examples: recording timestamp, session ID, test scenario name.
+            Useful for debugging and tracing recorded interactions.
+            Default is empty tuple.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    request: InteractionRequest
+    fingerprint: RequestFingerprint
+    response_chunks: tuple[ResponseChunk, ...]
+    metadata: tuple[tuple[str, str], ...] = ()
+
+    @model_validator(mode="after")
+    def validate_interaction(self) -> Self:
+        """Validate interaction integrity.
+
+        Raises:
+            InteractionValidationError: If fingerprint doesn't match request
+                or chunks aren't sequential
+        """
+        # Verify fingerprint matches request
+        expected_fingerprint = self.request.fingerprint()
+        if self.fingerprint != expected_fingerprint:
+            msg = (
+                f"Fingerprint does not match request: "
+                f"expected {expected_fingerprint.value}, got {self.fingerprint.value}"
+            )
+            raise InteractionValidationError(msg)
+
+        # Verify response chunks are sequentially ordered
+        if not self.response_chunks:
+            msg = "Response chunks cannot be empty"
+            raise InteractionValidationError(msg)
+
+        if self.response_chunks[0].sequence != 0:
+            msg = "Response chunks must start at sequence 0"
+            raise InteractionValidationError(msg)
+
+        for i, chunk in enumerate(self.response_chunks):
+            if chunk.sequence != i:
+                msg = "Response chunks must be sequential with no gaps"
+                raise InteractionValidationError(msg)
+
+        return self
+
+
+class Cassette(BaseModel):
+    """In-memory collection of recorded interactions.
+
+    Attributes:
+        interactions: Ordered sequence of interactions
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    interactions: tuple[Interaction, ...]
+    _index: dict[RequestFingerprint, int] = PrivateAttr(default_factory=dict)
+
+    @model_validator(mode="after")
+    def build_index(self) -> Self:
+        """Build fingerprint index for efficient lookup."""
+        index: dict[RequestFingerprint, int] = {}
+        for i, interaction in enumerate(self.interactions):
+            # Only store first occurrence of each fingerprint
+            if interaction.fingerprint not in index:
+                index[interaction.fingerprint] = i
+        # Use object.__setattr__ to modify frozen model
+        object.__setattr__(self, "_index", index)
+        return self
+
+    def find_interaction(self, fingerprint: RequestFingerprint) -> Interaction | None:
+        """Find first interaction matching fingerprint.
+
+        Args:
+            fingerprint: Request fingerprint to search for
+
+        Returns:
+            Matching Interaction or None if not found
+        """
+        position = self._index.get(fingerprint)
+        if position is None:
+            return None
+        return self.interactions[position]

interposition-0.1.0/src/interposition/services.py

@@ -0,0 +1,53 @@
+"""Domain services for interposition."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from interposition.errors import InteractionNotFoundError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from interposition.models import Cassette, InteractionRequest, ResponseChunk
+
+
+class Broker:
+    """Manages interaction replay from cassettes.
+
+    Attributes:
+        cassette: The cassette containing recorded interactions
+    """
+
+    def __init__(self, cassette: Cassette) -> None:
+        """Initialize broker with a cassette.
+
+        Args:
+            cassette: The cassette containing recorded interactions
+        """
+        self._cassette = cassette
+
+    @property
+    def cassette(self) -> Cassette:
+        """Get the cassette."""
+        return self._cassette
+
+    def replay(self, request: InteractionRequest) -> Iterator[ResponseChunk]:
+        """Replay recorded response for matching request.
+
+        Args:
+            request: The request to match and replay
+
+        Yields:
+            ResponseChunks in original recorded order
+
+        Raises:
+            InteractionNotFoundError: When no matching interaction exists
+        """
+        fingerprint = request.fingerprint()
+        interaction = self.cassette.find_interaction(fingerprint)
+
+        if interaction is None:
+            raise InteractionNotFoundError(request)
+
+        yield from interaction.response_chunks

interposition-0.1.0/src/interposition.egg-info/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: interposition
+Version: 0.1.0
+Summary: Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control.
+Author: osoken
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/osoekawaitlab/interposition
+Project-URL: Repository, https://github.com/osoekawaitlab/interposition
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Dynamic: license-file
+
+# interposition
+
+Protocol-agnostic interaction interposition with lifecycle hooks for record, replay, and control.
+
+## Overview
+
+Interposition is a Python library for replaying recorded interactions. Unlike VCRpy or other HTTP-specific tools, **Interposition does not automatically hook into network libraries**.
+
+Instead, it provides a **pure logic engine** for storage, matching, and replay. You write the adapter for your specific target (HTTP client, database driver, IoT message handler), and Interposition handles the rest.
+
+**Key Features:**
+
+- **Protocol-agnostic**: Works with any protocol (HTTP, gRPC, SQL, Pub/Sub, etc.)
+- **Type-safe**: Full mypy strict mode support with Pydantic v2
+- **Immutable**: All data structures are frozen Pydantic models
+- **Serializable**: Built-in JSON/YAML serialization for cassette persistence
+- **Memory-efficient**: O(1) lookup with fingerprint indexing
+- **Streaming**: Generator-based response delivery
+
+## Architecture
+
+Interposition sits behind your application's data access layer. You provide the "Adapter" that captures live traffic or requests replay from the Broker.
+
+```text
++-------------+      +------------------+      +---------------+
+| Application | <--> | Your Adapter     | <--> | Interposition |
++-------------+      +------------------+      +---------------+
+                            |                          |
+                       (Traps calls)              (Manages)
+                                                       |
+                                                  [Cassette]
+```
+
+## Installation
+
+```bash
+pip install interposition
+```
+
+## Practical Integration (Pytest Recipe)
+
+The most common use case is using Interposition as a test fixture. Here is a production-ready recipe for `pytest`:
+
+```python
+import pytest
+from interposition import Broker, Cassette, InteractionRequest
+
+@pytest.fixture
+def cassette_broker():
+    # Load cassette from a JSON file (or create one programmatically)
+    with open("tests/fixtures/my_cassette.json", "rb") as f:
+        cassette = Cassette.model_validate_json(f.read())
+    return Broker(cassette)
+
+def test_user_service(cassette_broker, monkeypatch):
+    # 1. Create your adapter (mocking your actual client)
+    def mock_fetch(url):
+        request = InteractionRequest(
+            protocol="http",
+            action="GET",
+            target=url,
+            headers=(),
+            body=b"",
+        )
+        # Delegate to Interposition
+        chunks = list(cassette_broker.replay(request))
+        return chunks[0].data
+
+    # 2. Inject the adapter
+    monkeypatch.setattr("my_app.client.fetch", mock_fetch)
+
+    # 3. Run your test
+    from my_app import get_user_name
+    assert get_user_name(42) == "Alice"
+```
+
+## Protocol-Agnostic Examples
+
+Interposition shines where HTTP-only tools fail.
+
+### SQL Database Query
+
+```python
+request = InteractionRequest(
+    protocol="postgres",
+    action="SELECT",
+    target="users_table",
+    headers=(),
+    body=b"SELECT id, name FROM users WHERE id = 42",
+)
+# Replay returns: b'[(42, "Alice")]'
+```
+
+### MQTT / PubSub Message
+
+```python
+request = InteractionRequest(
+    protocol="mqtt",
+    action="subscribe",
+    target="sensors/temp/room1",
+    headers=(("qos", "1"),),
+    body=b"",
+)
+# Replay returns stream of messages: b'24.5', b'24.6', ...
+```
+
+## Usage Guide
+
+### Manual Construction (Quick Start)
+
+If you need to build interactions programmatically (e.g., for seeding tests):
+
+```python
+from interposition import (
+    Broker,
+    Cassette,
+    Interaction,
+    InteractionRequest,
+    ResponseChunk,
+)
+
+# 1. Define the Request
+request = InteractionRequest(
+    protocol="api",
+    action="query",
+    target="users/42",
+    headers=(),
+    body=b"",
+)
+
+# 2. Define the Response
+chunks = (
+    ResponseChunk(data=b'{"id": 42, "name": "Alice"}', sequence=0),
+)
+
+# 3. Create Interaction & Cassette
+interaction = Interaction(
+    request=request,
+    fingerprint=request.fingerprint(),
+    response_chunks=chunks,
+)
+cassette = Cassette(interactions=(interaction,))
+
+# 4. Replay
+broker = Broker(cassette=cassette)
+response = list(broker.replay(request))
+```
+
+### Persistence & Serialization
+
+Interposition models are Pydantic v2 models, making serialization trivial.
+
+```python
+# Save to JSON
+with open("cassette.json", "w") as f:
+    f.write(cassette.model_dump_json(indent=2))
+
+# Load from JSON
+with open("cassette.json") as f:
+    cassette = Cassette.model_validate_json(f.read())
+
+# Generate JSON Schema
+schema = Cassette.model_json_schema()
+```
+
+### Streaming Responses
+
+For large files or streaming protocols, responses are yielded lazily:
+
+```python
+# The broker returns a generator
+for chunk in broker.replay(request):
+    print(f"Received chunk: {len(chunk.data)} bytes")
+```
+
+### Error Handling
+
+If a matching interaction is not found, the broker raises `InteractionNotFoundError`:
+
+```python
+from interposition import InteractionNotFoundError
+
+try:
+    broker.replay(unknown_request)
+except InteractionNotFoundError as e:
+    print(f"Not recorded: {e.request.target}")
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) (recommended)
+
+### Setup & Testing
+
+```bash
+# Clone and install
+git clone https://github.com/osoekawaitlab/interposition.git
+cd interposition
+uv pip install -e . --group=dev
+
+# Run tests
+nox -s tests
+```
+
+## License
+
+MIT

interposition-0.1.0/src/interposition.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/interposition/__init__.py
+src/interposition/_version.py
+src/interposition/errors.py
+src/interposition/models.py
+src/interposition/py.typed
+src/interposition/services.py
+src/interposition.egg-info/PKG-INFO
+src/interposition.egg-info/SOURCES.txt
+src/interposition.egg-info/dependency_links.txt
+src/interposition.egg-info/requires.txt
+src/interposition.egg-info/top_level.txt

interposition-0.1.0/src/interposition.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

interposition-0.1.0/src/interposition.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic<3.0,>=2.0

interposition-0.1.0/src/interposition.egg-info/top_level.txt

@@ -0,0 +1 @@
+interposition