millwork-solver 0.1.0__py3-none-any.whl

millwork_solver/__init__.py

@@ -0,0 +1,24 @@
+"""Public Millwork Solver Python client facade."""
+
+from .client import AsyncSolver, Solver
+from .errors import (
+    ClientClosedError,
+    FieldError,
+    NetworkError,
+    OperationBoundaryError,
+    ProblemError,
+    ProtocolError,
+)
+from .types import Page
+
+__all__ = (
+    "AsyncSolver",
+    "ClientClosedError",
+    "FieldError",
+    "NetworkError",
+    "OperationBoundaryError",
+    "Page",
+    "ProblemError",
+    "ProtocolError",
+    "Solver",
+)

millwork_solver/_contract.json

@@ -0,0 +1,292 @@
+{
+  "schema_version": 1,
+  "generated_from": {
+    "python_operation_view": "contracts/developer-experience/python-operation-view.json",
+    "operation_manifest_version": "1.0.0",
+    "openapi_sha256": "ad959a037922a16bda51221ed989d00ea0ae6b70eb86b5f2aef07eccee91d3c6",
+    "retry_fixture": "contracts/developer-experience/fixtures/retry-error-idempotency.json"
+  },
+  "operations": [
+    {
+      "operation_id": "deleteArmsByArmId",
+      "method": "DELETE",
+      "path": "/v1/arms/{armId}"
+    },
+    {
+      "operation_id": "deleteSourceConnectionsByConnectionId",
+      "method": "DELETE",
+      "path": "/v1/source-connections/{connectionId}"
+    },
+    {
+      "operation_id": "deleteVerifiersByVerifierId",
+      "method": "DELETE",
+      "path": "/v1/verifiers/{verifierId}"
+    },
+    {
+      "operation_id": "getAccount",
+      "method": "GET",
+      "path": "/v1/account"
+    },
+    {
+      "operation_id": "getApiKeys",
+      "method": "GET",
+      "path": "/v1/api-keys"
+    },
+    {
+      "operation_id": "getArms",
+      "method": "GET",
+      "path": "/v1/arms"
+    },
+    {
+      "operation_id": "getArmsByArmId",
+      "method": "GET",
+      "path": "/v1/arms/{armId}"
+    },
+    {
+      "operation_id": "getComplianceExport",
+      "method": "GET",
+      "path": "/v1/compliance-export"
+    },
+    {
+      "operation_id": "getCredentials",
+      "method": "GET",
+      "path": "/v1/credentials"
+    },
+    {
+      "operation_id": "getEvalSummary",
+      "method": "GET",
+      "path": "/v1/eval-summary"
+    },
+    {
+      "operation_id": "getExecutions",
+      "method": "GET",
+      "path": "/v1/executions"
+    },
+    {
+      "operation_id": "getExecutionsByExecutionId",
+      "method": "GET",
+      "path": "/v1/executions/{executionId}"
+    },
+    {
+      "operation_id": "getExecutionsByExecutionIdEvents",
+      "method": "GET",
+      "path": "/v1/executions/{executionId}/events"
+    },
+    {
+      "operation_id": "getExecutionsByExecutionIdResult",
+      "method": "GET",
+      "path": "/v1/executions/{executionId}/result"
+    },
+    {
+      "operation_id": "getModelCatalog",
+      "method": "GET",
+      "path": "/v1/model-catalog"
+    },
+    {
+      "operation_id": "getModelDefinitions",
+      "method": "GET",
+      "path": "/v1/model-definitions"
+    },
+    {
+      "operation_id": "getModelDeployments",
+      "method": "GET",
+      "path": "/v1/model-deployments"
+    },
+    {
+      "operation_id": "getModelDeploymentsByModelDeploymentId",
+      "method": "GET",
+      "path": "/v1/model-deployments/{modelDeploymentId}"
+    },
+    {
+      "operation_id": "getModelSourceProfiles",
+      "method": "GET",
+      "path": "/v1/model-source-profiles"
+    },
+    {
+      "operation_id": "getProposals",
+      "method": "GET",
+      "path": "/v1/proposals"
+    },
+    {
+      "operation_id": "getProposalsByProposalId",
+      "method": "GET",
+      "path": "/v1/proposals/{proposalId}"
+    },
+    {
+      "operation_id": "getReceipts",
+      "method": "GET",
+      "path": "/v1/receipts"
+    },
+    {
+      "operation_id": "getReceiptsByExecutionId",
+      "method": "GET",
+      "path": "/v1/receipts/{executionId}"
+    },
+    {
+      "operation_id": "getSourceConnections",
+      "method": "GET",
+      "path": "/v1/source-connections"
+    },
+    {
+      "operation_id": "getSourceConnectionsByConnectionId",
+      "method": "GET",
+      "path": "/v1/source-connections/{connectionId}"
+    },
+    {
+      "operation_id": "getSourceCredentialHandoffsByHandoffIntentId",
+      "method": "GET",
+      "path": "/v1/source-credential-handoffs/{handoffIntentId}"
+    },
+    {
+      "operation_id": "getUsage",
+      "method": "GET",
+      "path": "/v1/usage"
+    },
+    {
+      "operation_id": "getVerifiers",
+      "method": "GET",
+      "path": "/v1/verifiers"
+    },
+    {
+      "operation_id": "getVerifiersByVerifierId",
+      "method": "GET",
+      "path": "/v1/verifiers/{verifierId}"
+    },
+    {
+      "operation_id": "getWebhooks",
+      "method": "GET",
+      "path": "/v1/webhooks"
+    },
+    {
+      "operation_id": "getWebhooksByWebhookIdDeliveries",
+      "method": "GET",
+      "path": "/v1/webhooks/{webhookId}/deliveries"
+    },
+    {
+      "operation_id": "patchApiKeysByApiKeyId",
+      "method": "PATCH",
+      "path": "/v1/api-keys/{apiKeyId}"
+    },
+    {
+      "operation_id": "patchArmsByArmId",
+      "method": "PATCH",
+      "path": "/v1/arms/{armId}"
+    },
+    {
+      "operation_id": "patchTenantsByTenantId",
+      "method": "PATCH",
+      "path": "/v1/tenants/{tenantId}"
+    },
+    {
+      "operation_id": "patchVerifiersByVerifierId",
+      "method": "PATCH",
+      "path": "/v1/verifiers/{verifierId}"
+    },
+    {
+      "operation_id": "postApiKeys",
+      "method": "POST",
+      "path": "/v1/api-keys"
+    },
+    {
+      "operation_id": "postApiKeysByApiKeyIdRevoke",
+      "method": "POST",
+      "path": "/v1/api-keys/{apiKeyId}/revoke"
+    },
+    {
+      "operation_id": "postArms",
+      "method": "POST",
+      "path": "/v1/arms"
+    },
+    {
+      "operation_id": "postCredentials",
+      "method": "POST",
+      "path": "/v1/credentials"
+    },
+    {
+      "operation_id": "postExecutions",
+      "method": "POST",
+      "path": "/v1/executions"
+    },
+    {
+      "operation_id": "postExecutionsByExecutionIdCancel",
+      "method": "POST",
+      "path": "/v1/executions/{executionId}/cancel"
+    },
+    {
+      "operation_id": "postProposalsByProposalIdApprove",
+      "method": "POST",
+      "path": "/v1/proposals/{proposalId}/approve"
+    },
+    {
+      "operation_id": "postProposalsByProposalIdReject",
+      "method": "POST",
+      "path": "/v1/proposals/{proposalId}/reject"
+    },
+    {
+      "operation_id": "postSourceConnections",
+      "method": "POST",
+      "path": "/v1/source-connections"
+    },
+    {
+      "operation_id": "postSourceConnectionsByConnectionIdDeploymentsSync",
+      "method": "POST",
+      "path": "/v1/source-connections/{connectionId}/deployments/sync"
+    },
+    {
+      "operation_id": "postSourceConnectionsByConnectionIdRotate",
+      "method": "POST",
+      "path": "/v1/source-connections/{connectionId}/rotate"
+    },
+    {
+      "operation_id": "postSourceConnectionsByConnectionIdTest",
+      "method": "POST",
+      "path": "/v1/source-connections/{connectionId}/test"
+    },
+    {
+      "operation_id": "postSourceCredentialHandoffs",
+      "method": "POST",
+      "path": "/v1/source-credential-handoffs"
+    },
+    {
+      "operation_id": "postTenants",
+      "method": "POST",
+      "path": "/v1/tenants"
+    },
+    {
+      "operation_id": "postVerifiers",
+      "method": "POST",
+      "path": "/v1/verifiers"
+    },
+    {
+      "operation_id": "postVerifiersByVerifierIdTest",
+      "method": "POST",
+      "path": "/v1/verifiers/{verifierId}/test"
+    },
+    {
+      "operation_id": "postWebhooks",
+      "method": "POST",
+      "path": "/v1/webhooks"
+    },
+    {
+      "operation_id": "postWebhooksByWebhookIdRotateSecret",
+      "method": "POST",
+      "path": "/v1/webhooks/{webhookId}/rotate-secret"
+    },
+    {
+      "operation_id": "postWebhooksDeliveriesByDeliveryIdReplay",
+      "method": "POST",
+      "path": "/v1/webhooks/deliveries/{deliveryId}/replay"
+    }
+  ],
+  "retry_policy": {
+    "safe_methods": [
+      "GET",
+      "HEAD"
+    ],
+    "retryable_failures": [
+      "network_error",
+      "http_5xx"
+    ],
+    "maximum_retries": 2
+  }
+}

millwork_solver/_core/__init__.py

@@ -0,0 +1,3 @@
+"""Repository-internal PY2 core. No public import surface is selected here."""
+
+__all__: tuple[str, ...] = ()

millwork_solver/_core/boundary.py

@@ -0,0 +1,110 @@
+"""The sole name-neutral seam for a future PY0-selected public API.
+
+This repository-internal module deliberately exposes no distribution, import,
+public client-class, environment-variable, runtime-support, or lifecycle name.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+import httpx
+
+from .catalog import _OperationCatalog
+from .clients import _AsyncClient, _SyncClient
+from .transport import _AsyncTransport, _SyncTransport, _TransportPolicy
+
+
+def _create_sync_client(
+    *,
+    repository_root: Path | None = None,
+    snapshot_path: Path | None = None,
+    credential: str,
+    base_url: str,
+    timeout: float | httpx.Timeout,
+    maximum_retries: int | None = None,
+    backoff_seconds: float = 0.0,
+    transport: httpx.BaseTransport | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> _SyncClient:
+    if (repository_root is None) == (snapshot_path is None):
+        raise ValueError("exactly one of repository_root or snapshot_path is required")
+    if repository_root is not None:
+        catalog = _OperationCatalog.from_repository(repository_root)
+        policy = _TransportPolicy.from_repository(
+            repository_root,
+            backoff_seconds=backoff_seconds,
+            maximum_retries=maximum_retries,
+        )
+    else:
+        assert snapshot_path is not None
+        catalog = _OperationCatalog.from_snapshot(snapshot_path)
+        policy = _TransportPolicy.from_snapshot(
+            snapshot_path,
+            backoff_seconds=backoff_seconds,
+            maximum_retries=maximum_retries,
+        )
+    http_client = httpx.Client(
+        base_url=base_url,
+        headers={"authorization": f"Bearer {credential}"},
+        timeout=timeout,
+        transport=transport,
+        follow_redirects=False,
+        trust_env=False,
+    )
+    return _SyncClient(
+        catalog,
+        policy,
+        _SyncTransport(http_client, policy, sleep),
+        close_transport=http_client.close,
+        sleep=sleep,
+    )
+
+
+def _create_async_client(
+    *,
+    repository_root: Path | None = None,
+    snapshot_path: Path | None = None,
+    credential: str,
+    base_url: str,
+    timeout: float | httpx.Timeout,
+    maximum_retries: int | None = None,
+    backoff_seconds: float = 0.0,
+    transport: httpx.AsyncBaseTransport | None = None,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> _AsyncClient:
+    if (repository_root is None) == (snapshot_path is None):
+        raise ValueError("exactly one of repository_root or snapshot_path is required")
+    if repository_root is not None:
+        catalog = _OperationCatalog.from_repository(repository_root)
+        policy = _TransportPolicy.from_repository(
+            repository_root,
+            backoff_seconds=backoff_seconds,
+            maximum_retries=maximum_retries,
+        )
+    else:
+        assert snapshot_path is not None
+        catalog = _OperationCatalog.from_snapshot(snapshot_path)
+        policy = _TransportPolicy.from_snapshot(
+            snapshot_path,
+            backoff_seconds=backoff_seconds,
+            maximum_retries=maximum_retries,
+        )
+    http_client = httpx.AsyncClient(
+        base_url=base_url,
+        headers={"authorization": f"Bearer {credential}"},
+        timeout=timeout,
+        transport=transport,
+        follow_redirects=False,
+        trust_env=False,
+    )
+    return _AsyncClient(
+        catalog,
+        policy,
+        _AsyncTransport(http_client, policy, sleep),
+        close_transport=http_client.aclose,
+        sleep=sleep,
+    )

millwork_solver/_core/catalog.py

@@ -0,0 +1,218 @@
+"""Resolve the reachable wire operations through PY1's pointers into F1."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Mapping
+from urllib.parse import quote, unquote
+
+from .errors import _OperationBoundaryError
+
+
+_HTTP_METHODS = frozenset({"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"})
+_PATH_PARAMETER = re.compile(r"\{([^{}]+)\}")
+
+
+@dataclass(frozen=True)
+class _Operation:
+    operation_id: str
+    method: str
+    path_template: str
+
+    def bind_path(self, path_parameters: Mapping[str, object] | None) -> str:
+        parameters = dict(path_parameters or {})
+        expected = set(_PATH_PARAMETER.findall(self.path_template))
+        if set(parameters) != expected:
+            raise _OperationBoundaryError(
+                f"{self.operation_id} path parameters must be exactly {sorted(expected)}"
+            )
+        return _PATH_PARAMETER.sub(
+            lambda match: quote(str(parameters[match.group(1)]), safe=""),
+            self.path_template,
+        )
+
+    def match_path(self, concrete_path: str) -> Mapping[str, str] | None:
+        names: list[str] = []
+        pieces: list[str] = []
+        position = 0
+        for parameter in _PATH_PARAMETER.finditer(self.path_template):
+            pieces.append(re.escape(self.path_template[position : parameter.start()]))
+            pieces.append(r"([^/]+)")
+            names.append(parameter.group(1))
+            position = parameter.end()
+        pieces.append(re.escape(self.path_template[position:]))
+        expression = "^" + "".join(pieces) + "$"
+        matched = re.match(expression, concrete_path)
+        if matched is None:
+            return None
+        return MappingProxyType({name: unquote(value) for name, value in zip(names, matched.groups())})
+
+
+def _load_json(path: Path) -> Any:
+    with path.open("r", encoding="utf-8") as file:
+        return json.load(file)
+
+
+def _resolve_pointer(repository_root: Path, source: str) -> Any:
+    relative_file, separator, fragment = source.partition("#")
+    if separator != "#" or not fragment.startswith("/"):
+        raise _OperationBoundaryError(f"PY1 source is not a JSON pointer: {source}")
+    absolute_file = (repository_root / relative_file).resolve()
+    try:
+        absolute_file.relative_to(repository_root.resolve())
+    except ValueError as error:
+        raise _OperationBoundaryError("PY1 source escapes the repository root") from error
+    value = _load_json(absolute_file)
+    for encoded_token in fragment.removeprefix("/").split("/"):
+        token = encoded_token.replace("~1", "/").replace("~0", "~")
+        if isinstance(value, list):
+            value = value[int(token)]
+        else:
+            value = value[token]
+    return value
+
+
+class _OperationCatalog:
+    def __init__(self, operations: Mapping[str, _Operation], event_operation_id: str) -> None:
+        self._operations = MappingProxyType(dict(operations))
+        self.event_operation_id = event_operation_id
+
+    @classmethod
+    def from_repository(cls, repository_root: Path) -> "_OperationCatalog":
+        repository_root = repository_root.resolve()
+        view_path = repository_root / "contracts/developer-experience/python-operation-view.json"
+        view = _load_json(view_path)
+        sources = view.get("sources")
+        expected_counts = view.get("expected_counts")
+        if not isinstance(sources, dict) or expected_counts != {
+            "operations": 70,
+            "included": 54,
+            "excluded": 16,
+        }:
+            raise _OperationBoundaryError("PY1 pointer/count contract drifted")
+
+        included_ids = _resolve_pointer(repository_root, sources["included_operation_ids"])
+        classifications = _resolve_pointer(repository_root, sources["operation_classifications"])
+        wire_paths = _resolve_pointer(repository_root, sources["wire_contract"])
+        if not isinstance(included_ids, list) or not isinstance(classifications, list):
+            raise _OperationBoundaryError("PY1/F1 operation pointers must resolve to arrays")
+
+        wire_operations: dict[str, tuple[str, str]] = {}
+        for path, path_item in wire_paths.items():
+            for method, operation in path_item.items():
+                normalized_method = method.upper()
+                if normalized_method not in _HTTP_METHODS:
+                    continue
+                operation_id = operation.get("operationId")
+                if not isinstance(operation_id, str) or operation_id in wire_operations:
+                    raise _OperationBoundaryError("OpenAPI operation IDs must be present and unique")
+                wire_operations[operation_id] = (normalized_method, path)
+
+        classification_by_id: dict[str, Mapping[str, Any]] = {}
+        for classification in classifications:
+            operation_id = classification.get("operation_id")
+            if not isinstance(operation_id, str) or operation_id in classification_by_id:
+                raise _OperationBoundaryError("F1 operation IDs must be present and unique")
+            classification_by_id[operation_id] = classification
+
+        included_set = set(included_ids)
+        f1_included = {
+            operation_id
+            for operation_id, classification in classification_by_id.items()
+            if classification.get("disposition") == "include"
+        }
+        f1_excluded = {
+            operation_id
+            for operation_id, classification in classification_by_id.items()
+            if classification.get("disposition") == "exclude"
+        }
+        if len(wire_operations) != 70 or len(f1_included) != 54 or len(f1_excluded) != 16:
+            raise _OperationBoundaryError("F1 54/16 operation partition drifted")
+        if included_set != f1_included or len(included_ids) != len(included_set):
+            raise _OperationBoundaryError("PY1 pointer does not resolve exactly to F1's 54 includes")
+        if set(classification_by_id) != set(wire_operations):
+            raise _OperationBoundaryError("F1 classifications do not cover OpenAPI exactly")
+
+        allowed: dict[str, _Operation] = {}
+        for operation_id in included_ids:
+            classification = classification_by_id[operation_id]
+            method_and_path = wire_operations.get(operation_id)
+            if method_and_path != (classification.get("method"), classification.get("path")):
+                raise _OperationBoundaryError(f"{operation_id} F1/OpenAPI mapping drifted")
+            allowed[operation_id] = _Operation(operation_id, *method_and_path)
+
+        event_operations = [
+            operation.operation_id
+            for operation in allowed.values()
+            if operation.method == "GET" and operation.path_template.endswith("/events")
+        ]
+        if len(event_operations) != 1:
+            raise _OperationBoundaryError("F1 must expose exactly one execution-events operation")
+        return cls(allowed, event_operations[0])
+
+    @classmethod
+    def from_snapshot(cls, snapshot_path: Path) -> "_OperationCatalog":
+        """Load the generated, F1-derived catalog bundled in an installed artifact."""
+
+        snapshot = _load_json(snapshot_path)
+        if snapshot.get("schema_version") != 1:
+            raise _OperationBoundaryError("installed Python wire snapshot version drifted")
+        operations = snapshot.get("operations")
+        if not isinstance(operations, list) or len(operations) != 54:
+            raise _OperationBoundaryError("installed Python wire snapshot must contain 54 operations")
+
+        allowed: dict[str, _Operation] = {}
+        for item in operations:
+            if not isinstance(item, dict) or set(item) != {"operation_id", "method", "path"}:
+                raise _OperationBoundaryError("installed Python wire snapshot operation shape drifted")
+            operation_id = item.get("operation_id")
+            method = item.get("method")
+            path = item.get("path")
+            if (
+                not isinstance(operation_id, str)
+                or not isinstance(method, str)
+                or method not in _HTTP_METHODS
+                or not isinstance(path, str)
+                or operation_id in allowed
+            ):
+                raise _OperationBoundaryError("installed Python wire snapshot operation is invalid")
+            allowed[operation_id] = _Operation(operation_id, method, path)
+
+        event_operations = [
+            operation.operation_id
+            for operation in allowed.values()
+            if operation.method == "GET" and operation.path_template.endswith("/events")
+        ]
+        if len(event_operations) != 1:
+            raise _OperationBoundaryError(
+                "installed Python wire snapshot must expose one execution-events operation"
+            )
+        return cls(allowed, event_operations[0])
+
+    @property
+    def operation_ids(self) -> frozenset[str]:
+        return frozenset(self._operations)
+
+    def operation(self, operation_id: str) -> _Operation:
+        operation = self._operations.get(operation_id)
+        if operation is None:
+            raise _OperationBoundaryError(f"operation is outside the F1 Python boundary: {operation_id}")
+        return operation
+
+    def match_fixture_request(self, method: str, concrete_path: str) -> tuple[str, Mapping[str, str]]:
+        matches: list[tuple[str, Mapping[str, str]]] = []
+        for operation in self._operations.values():
+            if operation.method != method:
+                continue
+            path_parameters = operation.match_path(concrete_path)
+            if path_parameters is not None:
+                matches.append((operation.operation_id, path_parameters))
+        if len(matches) != 1:
+            raise _OperationBoundaryError(
+                f"fixture request must match exactly one included operation: {method} {concrete_path}"
+            )
+        return matches[0]