sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/hosted_workflow.py

@@ -0,0 +1,451 @@
+"""Explicit adapter for native exact-revision hosted PR submissions.
+
+No service is contacted during construction, registration or resolution. Local
+admission validates a request, not remote permission or executable source bytes.
+The configured owner API must authorize and verify its records. This adapter
+checks their linkage and preserves native trust; it does not supply isolation,
+read protected cases, or promote historical service notes into live authority.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from .client import Client, Experiment, HostedClientError, HostedEvaluation, HostedRun, _retry_key
+from .evals import describe_eval, resolve_eval
+from .hosted.registry import BASELINE_ID, PUBLIC_SUITE_ID, REGISTERED_MAIN_BASELINE_ID, SUITE_ID
+from .hosted.revisions import require_commit_sha
+from .hosted.submission import pr_identity
+from .workflow_async import GradingSnapshot, SubmissionError, SubmissionIntent, SubmissionSnapshot
+from .workflow_contracts import (
+    AdmissionBinding, BackendDescriptor, Criterion, EvaluatorDefinition, MetricSpec,
+    PlanBinding, ReferenceBinding, ResolvedBinding, SuiteDefinition,
+    WorkflowContractError, _object, _text, _thaw, contract_digest,
+)
+from .workflow_registry import WorkflowRegistry
+
+HOSTED_BACKEND_ID = "sphynx.hosted.pr"
+_SUITES = (SUITE_ID, PUBLIC_SUITE_ID)
+_METHOD = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z")
+_RESULTS = {SUITE_ID: "sphynx.hosted.result.v1", PUBLIC_SUITE_ID: "sphynx.hosted.public-rerank.result.v1"}
+
+
+@dataclass(frozen=True)
+class PullRequestCandidate:
+    """Strict PR request; legacy Client.submit still permits an omitted SHA guard."""
+
+    candidate_pr: str
+    expected_head_sha: str
+    candidate_method: str | None = None
+    baseline: str = BASELINE_ID
+    expected_baseline_sha: str | None = None
+
+    def __post_init__(self) -> None:
+        pr_identity(self.candidate_pr)
+        object.__setattr__(self, "expected_head_sha", require_commit_sha(self.expected_head_sha))
+        if self.candidate_method is not None and (type(self.candidate_method) is not str
+                                                  or not _METHOD.fullmatch(self.candidate_method)):
+            raise WorkflowContractError("candidate_method must be a bounded ASCII method ID")
+        if self.baseline not in (BASELINE_ID, REGISTERED_MAIN_BASELINE_ID):
+            raise WorkflowContractError("baseline is not supported by the native hosted adapter")
+        if self.expected_baseline_sha is not None:
+            if self.baseline != REGISTERED_MAIN_BASELINE_ID:
+                raise WorkflowContractError("expected_baseline_sha requires the registered main baseline")
+            object.__setattr__(self, "expected_baseline_sha", require_commit_sha(self.expected_baseline_sha))
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {"candidate_pr": self.candidate_pr, "expected_head_sha": self.expected_head_sha,
+                  "baseline": self.baseline}
+        if self.candidate_method is not None:
+            result["candidate_method"] = self.candidate_method
+        if self.expected_baseline_sha is not None:
+            result["expected_baseline_sha"] = self.expected_baseline_sha
+        return result
+
+
+@dataclass(frozen=True)
+class _Submission:
+    handle: Experiment = field(repr=False, compare=False)
+    request_identity: Mapping[str, Any]
+    idempotency_key: str
+    owner: Any = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class _Run:
+    handle: HostedRun = field(repr=False, compare=False)
+    submission: _Submission = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class _Grading:
+    handle: HostedEvaluation = field(repr=False, compare=False)
+    run: _Run = field(repr=False, compare=False)
+    idempotency_key: str
+    request_identity: Mapping[str, Any]
+
+
+@dataclass(frozen=True)
+class _CompletedGrading:
+    pending: _Grading = field(repr=False, compare=False)
+    payload: Mapping[str, Any] = field(repr=False)
+
+
+@dataclass(frozen=True)
+class _Projection:
+    payload: Mapping[str, Any] = field(repr=False)
+
+    def to_dict(self) -> dict[str, Any]:
+        return _thaw(self.payload)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, allow_nan=False, sort_keys=True)
+
+    def to_markdown(self) -> str:
+        summary = self.payload.get("summary")
+        if not isinstance(summary, str):
+            raise WorkflowContractError("native hosted report has no readable summary")
+        return summary
+
+
+class HostedComparison:
+    """Native saved comparison handle with explicit result projection.
+
+    Pending retrieval remains pending; obtaining this handle never runs or grades
+    candidates. The native comparison ID remains available after a read error.
+    """
+
+    def __init__(self, backend, native_ref, evaluation_a, evaluation_b):
+        self._backend, self.native_ref = backend, native_ref
+        self.evaluation_a, self.evaluation_b = evaluation_a, evaluation_b
+
+    @property
+    def status(self):
+        return self.native_ref.status
+
+    def refresh(self):
+        self._backend._origin()
+        return HostedComparison(self._backend, self._backend.client.get_comparison(self.native_ref.id),
+                                self.evaluation_a, self.evaluation_b)
+
+    def to_dict(self):
+        self._backend._origin()
+        payload = self.native_ref.result().to_dict()
+        if payload.get("evaluation_a") != self.evaluation_a or payload.get("evaluation_b") != self.evaluation_b:
+            raise WorkflowContractError("hosted comparison refers to different grading passes")
+        return payload
+
+    def to_json(self):
+        return json.dumps(self.to_dict(), ensure_ascii=False, allow_nan=False, sort_keys=True)
+
+    def to_markdown(self):
+        return _Projection(_object(self.to_dict(), "comparison")).to_markdown()
+
+
+class HostedWorkflowBackend:
+    """Operator-enabled native hosted adapter; no service checkout is bundled."""
+
+    def __init__(self, client: Client, *, suite_ids: tuple[str, ...] = (SUITE_ID,)):
+        if not isinstance(client, Client):
+            raise WorkflowContractError("hosted backend requires an explicitly configured Client")
+        if not isinstance(suite_ids, tuple) or not suite_ids or len(set(suite_ids)) != len(suite_ids):
+            raise WorkflowContractError("suite_ids must be a nonempty unique tuple")
+        if any(identifier not in _SUITES for identifier in suite_ids):
+            raise WorkflowContractError("no native hosted adapter for the selected suite")
+        self.client, self._owner = client, object()
+        self._descriptor = BackendDescriptor(
+            HOSTED_BACKEND_ID, "v1", "sphynx.hosted.pr-adapter.v1",
+            capabilities=("sphynx.async-submission.v1", "sphynx.async-grading.v1",
+                          "sphynx.saved-assessment.v1", "sphynx.native-report.v1",
+                          "sphynx.paired-comparison.v1"),
+            supported_scopes=("component",), supported_modes=("hosted",), suite_ids=suite_ids,
+            metadata={"api_origin": client.api_url, "remote_admission": "server_owned",
+                      "case_access": "not_exposed", "case_assessments": "not_exposed",
+                      "live_service_verified": False},
+        )
+
+    @property
+    def descriptor(self):
+        return self._descriptor
+
+    def describe(self, suite_id):
+        if suite_id not in self.descriptor.suite_ids:
+            raise WorkflowContractError("suite is not enabled in this hosted backend")
+        native = describe_eval(suite_id)
+        ids = tuple(f"{suite_id}/{metric}" for metric in native["metric_ids"])
+        return SuiteDefinition(suite_id, native["version"], self.descriptor.backend_id,
+            native["title"], criterion_ids=ids, metric_ids=ids, evaluator_ids=(suite_id + "/grader",),
+            required_capabilities=("sphynx.async-submission.v1", "sphynx.async-grading.v1"),
+            metadata={"native_definition": native, "native_metric_mapping": dict(zip(ids, native["metric_ids"])),
+                      "native_report_layout": "metrics.candidate and metrics.baseline",
+                      "remote_admission": "pending_server_submission", "case_access": "not_exposed"})
+
+    def cases(self, suite):
+        raise WorkflowContractError("hosted case access is not exposed by this API")
+
+    def _plan(self, plan):
+        if not isinstance(plan, PlanBinding) or not isinstance(plan.candidate, PullRequestCandidate):
+            raise WorkflowContractError("hosted PR plans require PullRequestCandidate")
+        if plan.suite.definition_digest != self.describe(plan.suite.suite_id).definition_digest:
+            raise WorkflowContractError("hosted suite definition changed")
+        if plan.scope != "component" or plan.mode != "hosted" or plan.runtime:
+            raise WorkflowContractError("hosted adapter supports component/hosted with native parameter runtime only")
+        self._origin()
+
+    def _origin(self):
+        if self.client.api_url != self.descriptor.metadata["api_origin"]:
+            raise WorkflowContractError("configured hosted origin changed")
+
+    def resolve(self, plan):
+        self._plan(plan)
+        invocation = resolve_eval(plan.suite.suite_id, plan.parameters)
+        request = {**plan.candidate.to_dict(), "suite": plan.suite.suite_id,
+                   "parameters": _thaw(invocation.parameters)}
+        return ResolvedBinding(identity={"backend": self.descriptor.to_dict(),
+            "suite_id": plan.suite.suite_id, "suite_digest": plan.suite.definition_digest,
+            "scope": plan.scope, "mode": plan.mode, "request": request,
+            "native_invocation": invocation.to_dict()}, native_ref=invocation)
+
+    def _resolution(self, plan, resolved):
+        if not isinstance(resolved, ResolvedBinding) or self.resolve(plan).resolution_digest != resolved.resolution_digest:
+            raise WorkflowContractError("hosted request identity changed; resolve again")
+
+    def admit(self, plan, resolved):
+        self._resolution(plan, resolved)
+        return AdmissionBinding(resolved.resolution_digest,
+            {"request_digest": contract_digest(resolved.identity),
+             "remote_admission": "pending_server_submission", "api_origin": self.client.api_url},
+            "unverified", False, False)
+
+    def recheck(self, plan, resolved, admission):
+        expected = self.admit(plan, resolved)
+        if not isinstance(admission, AdmissionBinding) or admission.to_dict() != expected.to_dict():
+            raise WorkflowContractError("hosted admission or request identity changed")
+
+    def execute(self, plan, resolved, admission, output_dir):
+        raise WorkflowContractError("hosted execution is asynchronous; use Plan.submit()")
+
+    def assess(self, native_run):
+        raise WorkflowContractError("hosted grading is asynchronous; use Run.start_grading()")
+
+    def submit(self, plan, resolved, admission, idempotency_key):
+        self.recheck(plan, resolved, admission)
+        key = _retry_key(idempotency_key)
+        intent = SubmissionIntent(key, resolved.identity)
+        try:
+            handle = self.client.submit(**_thaw(resolved.identity["request"]), idempotency_key=key)
+        except HostedClientError as exc:
+            raise SubmissionError("hosted submission did not return a handle; retain this intent for recovery",
+                                  intent=intent, code=exc.code) from None
+        ref = _Submission(handle, _object(resolved.identity, "request_identity"), key, self._owner)
+        self._submission(ref)
+        return ref
+
+    def _submission(self, ref):
+        self._origin()
+        if not isinstance(ref, _Submission) or ref.owner is not self._owner:
+            raise WorkflowContractError("submission belongs to another backend binding")
+        data, request = ref.handle.to_dict(), ref.request_identity["request"]
+        if data.get("id") != ref.handle.id:
+            raise WorkflowContractError("native submission identity changed")
+        if data.get("head_sha") is not None and data["head_sha"] != request["expected_head_sha"]:
+            raise WorkflowContractError("hosted submission head differs from expected revision")
+        if "request" in data and contract_digest(data["request"]) != contract_digest(request):
+            raise WorkflowContractError("server submission request differs from the selected request")
+        _text(data.get("status"), "native submission status")
+        return data
+
+    def refresh_submission(self, native_ref):
+        self._submission(native_ref)
+        native_ref.handle.refresh()
+        self._submission(native_ref)
+        return native_ref
+
+    def _manifest(self, manifest, identity):
+        request = identity["request"]
+        if not isinstance(manifest, Mapping):
+            raise WorkflowContractError("hosted record has no pinned manifest")
+        if (manifest.get("head_sha") != request["expected_head_sha"]
+                or manifest.get("candidate_pr") != request["candidate_pr"]
+                or not isinstance(manifest.get("suite"), Mapping)
+                or manifest["suite"].get("id") != request["suite"]
+                or not isinstance(manifest.get("baseline"), Mapping)
+                or manifest["baseline"].get("id") != request["baseline"]
+                or manifest.get("candidate_method") != request.get("candidate_method")):
+            raise WorkflowContractError("hosted manifest differs from pinned head, method, suite or baseline")
+        family = manifest.get("candidate_family")
+        if family is not None and (not isinstance(family, Mapping)
+                                   or family.get("method") != request.get("candidate_method")):
+            raise WorkflowContractError("hosted family selection differs from the requested method")
+        if request.get("expected_baseline_sha") is not None:
+            baseline = manifest["baseline"].get("registered_component", {})
+            source = baseline.get("source_revision", {}) if isinstance(baseline, Mapping) else {}
+            if source.get("head_sha") != request["expected_baseline_sha"]:
+                raise WorkflowContractError("hosted baseline differs from its expected revision")
+
+    def _run(self, ref):
+        if not isinstance(ref, _Run):
+            raise WorkflowContractError("expected a completed native hosted run")
+        self._submission(ref.submission)
+        current = self.client.get_run(ref.handle.id)
+        record = current.to_dict()
+        if record.get("status") not in ("completed", "captured"):
+            raise WorkflowContractError("native hosted capture is not complete")
+        if record.get("experiment_id") != ref.submission.handle.id:
+            raise WorkflowContractError("native run belongs to another submission")
+        self._manifest(record.get("manifest"), ref.submission.request_identity)
+        return record
+
+    def submission_snapshot(self, native_ref):
+        data = self._submission(native_ref)
+        status = data["status"]
+        run = grading = None
+        if data.get("run_id") is not None:
+            handle = self.client.get_run(data["run_id"])
+            if handle.status in ("completed", "captured"):
+                run = _Run(handle, native_ref)
+                self._run(run)
+        if status == "completed":
+            if run is None or data.get("evaluation_id") is None:
+                raise WorkflowContractError("completed submission has no complete native run/grading linkage")
+            pending = _Grading(self.client.get_evaluation(data["evaluation_id"]), run,
+                               native_ref.idempotency_key, native_ref.request_identity)
+            grading = self.grading_snapshot(pending).completed_ref
+            if grading is None:
+                raise WorkflowContractError("completed submission has a pending grading pass")
+        error = data.get("error") if isinstance(data.get("error"), dict) else {}
+        return SubmissionSnapshot(native_ref.handle.id, status, native_ref.idempotency_key,
+            native_ref.request_identity, native_ref, run_id=data.get("run_id"),
+            grading_id=data.get("evaluation_id"), native_run=run, native_grading=grading,
+            complete=status == "completed", failed=status == "failed",
+            error_code=error.get("code") if isinstance(error.get("code"), str) else None,
+            reason="hosted submission failed; inspect its owned native status" if status == "failed" else None,
+            trust_tier=grading.payload.get("trust_tier", "unverified") if grading else "unverified")
+
+    def start_grading(self, native_run, idempotency_key):
+        self._run(native_run)
+        key = _retry_key(idempotency_key)
+        identity = _object({"run_id": native_run.handle.id,
+            "submission_request_digest": contract_digest(native_run.submission.request_identity),
+            "operation": "saved_grading"}, "grading request")
+        try:
+            handle = self.client.grade(native_run.handle.id, idempotency_key=key)
+        except HostedClientError as exc:
+            raise SubmissionError("hosted grading did not return a handle; retain this intent for recovery",
+                                  intent=SubmissionIntent(key, identity), code=exc.code) from None
+        return _Grading(handle, native_run, key, identity)
+
+    def _grading(self, ref):
+        if not isinstance(ref, _Grading):
+            raise WorkflowContractError("expected a native pending grading handle")
+        self._run(ref.run)
+        data = ref.handle.to_dict()
+        if data.get("run_id") != ref.run.handle.id:
+            raise WorkflowContractError("hosted grading refers to another run")
+        if data.get("experiment_id") is not None and data["experiment_id"] != ref.run.submission.handle.id:
+            raise WorkflowContractError("hosted grading belongs to another submission")
+        _text(data.get("status"), "native grading status")
+        return data
+
+    def refresh_grading(self, native_ref):
+        self._grading(native_ref)
+        native_ref.handle.refresh()
+        self._grading(native_ref)
+        return native_ref
+
+    def grading_snapshot(self, native_ref):
+        data = self._grading(native_ref)
+        status, completed = data["status"], None
+        trust = "unverified"
+        if status == "completed":
+            payload = self.client._request("GET", f"/v1/evaluations/{native_ref.handle.id}/result")
+            request = native_ref.run.submission.request_identity["request"]
+            if (payload.get("schema_version") != _RESULTS[request["suite"]]
+                    or payload.get("experiment_id") != native_ref.run.submission.handle.id):
+                raise WorkflowContractError("hosted report has an unsupported schema or submission identity")
+            for key, expected in (("run_id", native_ref.run.handle.id), ("evaluation_id", native_ref.handle.id)):
+                if key in payload and payload[key] != expected:
+                    raise WorkflowContractError("hosted report has a different native record identity")
+            self._manifest(payload.get("manifest"), native_ref.run.submission.request_identity)
+            capture_manifest = self._run(native_ref.run)["manifest"]
+            fields = ("head_sha", "tree_sha", "candidate_pr", "suite", "baseline", "candidate_method",
+                      "candidate_family", "configuration_digest", "source_bundle_digest")
+            if contract_digest({key: capture_manifest.get(key) for key in fields}) != contract_digest(
+                    {key: payload["manifest"].get(key) for key in fields}):
+                raise WorkflowContractError("hosted report differs from the captured source/cohort identity")
+            _text(payload.get("summary"), "native report summary")
+            trust = payload.get("trust_tier", "unverified")
+            _text(trust, "native trust_tier")
+            completed = _CompletedGrading(native_ref, _object(payload, "native report"))
+        error = data.get("error") if isinstance(data.get("error"), dict) else {}
+        return GradingSnapshot(ReferenceBinding(native_ref.handle.id, status, trust,
+                run_id=native_ref.run.handle.id), native_ref.idempotency_key,
+            native_ref.request_identity, native_ref, completed_ref=completed,
+            complete=status == "completed", failed=status == "failed",
+            error_code=error.get("code") if isinstance(error.get("code"), str) else None,
+            reason="hosted grading failed; inspect its owned native status" if status == "failed" else None)
+
+    def accepts_reference(self, native_ref, kind):
+        if kind == "run":
+            return isinstance(native_ref, _Run) and native_ref.submission.owner is self._owner
+        if kind == "grading":
+            return isinstance(native_ref, _CompletedGrading) and native_ref.pending.run.submission.owner is self._owner
+        return False
+
+    def reference(self, native_ref, kind):
+        if not self.accepts_reference(native_ref, kind):
+            raise WorkflowContractError("native hosted reference belongs to another backend or is pending")
+        if kind == "run":
+            record = self._run(native_ref)
+            return ReferenceBinding(native_ref.handle.id, record["status"], record.get("trust_tier", "unverified"),
+                                    run_id=native_ref.handle.id,
+                                    metadata={"submission_id": native_ref.submission.handle.id})
+        pending = native_ref.pending
+        pending.handle.refresh()
+        fresh = self.grading_snapshot(pending)
+        if not fresh.complete or contract_digest(fresh.completed_ref.payload) != contract_digest(native_ref.payload):
+            raise WorkflowContractError("saved hosted report changed or is no longer available")
+        return fresh.reference
+
+    def report(self, native_grading):
+        self.reference(native_grading, "grading")
+        return _Projection(native_grading.payload)
+
+    def assessments(self, native_grading, case_id=None):
+        self.reference(native_grading, "grading")
+        raise WorkflowContractError("typed hosted case assessments are not exposed; inspect the native report")
+
+    def compare(self, baseline_grading, candidate_grading):
+        a, b = self.reference(baseline_grading, "grading"), self.reference(candidate_grading, "grading")
+        handle = self.client.compare_saved(a.record_id, b.record_id)
+        return HostedComparison(self, handle, a.record_id, b.record_id)
+
+
+def build_hosted_registry(client: Client, *, suite_ids: tuple[str, ...] = (SUITE_ID,)) -> WorkflowRegistry:
+    """Enable selected native suites in a separate, explicit hosted registry.
+
+    The same suite ID can remain bound to the local backend in another registry.
+    This performs no HTTP request and does not grant hosted execution permission.
+    """
+    backend = HostedWorkflowBackend(client, suite_ids=suite_ids)
+    registry = WorkflowRegistry()
+    registry.register_backend(backend)
+    for suite_id in suite_ids:
+        suite = backend.describe(suite_id)
+        native = suite.metadata["native_definition"]
+        for identifier, metric in suite.metadata["native_metric_mapping"].items():
+            registry.register_criterion(Criterion(identifier, native["version"], metric,
+                configuration={"native_metric_mapping": True}))
+            registry.register_metric(MetricSpec(identifier, native["implementation"]["metrics"],
+                "ms" if metric == "runner_latency_ms" else "ratio",
+                "lower" if metric in ("runner_latency_ms", "candidate_failure_rate") else "higher",
+                metadata={"native_metric_id": metric, "native_report_layout": "candidate/baseline lanes",
+                          "aggregation": "server_owned", "comparison": "server_owned"}))
+        registry.register_evaluator(EvaluatorDefinition(suite_id + "/grader", native["version"],
+            native["implementation"]["grader"], criterion_ids=suite.criterion_ids,
+            metric_ids=suite.metric_ids, required_capabilities=("sphynx.async-grading.v1",),
+            configuration={"execution": "server_owned", "case_assessments": "not_exposed"}))
+        registry.register_suite(suite)
+    return registry

sphynx/http_transport.py

@@ -0,0 +1,86 @@
+"""HTTP opening policy for SDK requests that may carry credentials."""
+
+from __future__ import annotations
+
+import ipaddress
+import urllib.request
+from urllib.parse import urlsplit
+
+
+class NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Reject redirects so urllib never forwards credentials to another URL."""
+
+    def redirect_request(self, request, fp, code, msg, headers, newurl):
+        return None
+
+
+def validate_private_connect_proxy(proxy_url: str) -> str:
+    """Accept only an explicit RFC1918 IPv4 CONNECT relay on port 3128."""
+    try:
+        if not isinstance(proxy_url, str):
+            raise ValueError()
+        parsed = urlsplit(proxy_url)
+        address = ipaddress.IPv4Address(parsed.hostname)
+        private_ranges = (ipaddress.IPv4Network("10.0.0.0/8"),
+                          ipaddress.IPv4Network("172.16.0.0/12"),
+                          ipaddress.IPv4Network("192.168.0.0/16"))
+        canonical = f"http://{address}:3128"
+        if (proxy_url != canonical or parsed.scheme != "http" or parsed.port != 3128
+                or parsed.username or parsed.password or parsed.path or parsed.query or parsed.fragment
+                or not any(address in network for network in private_ranges)):
+            raise ValueError()
+        return canonical
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError("CONNECT proxy must be an RFC1918 IPv4 HTTP origin on port 3128") from None
+
+
+def _https_origin(value: str, *, origin_only: bool = False):
+    try:
+        parsed = urlsplit(value)
+        if (parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password
+                or parsed.fragment or origin_only and (parsed.path not in ("", "/") or parsed.query)):
+            raise ValueError()
+        return parsed.hostname.casefold(), parsed.port or 443
+    except (ValueError, TypeError, AttributeError):
+        raise ValueError("CONNECT proxy target must be the configured HTTPS origin") from None
+
+
+class _OriginConnectProxyHandler(urllib.request.ProxyHandler):
+    """Explicit per-opener relay, confined to one TLS origin, ignoring NO_PROXY."""
+
+    def __init__(self, proxy_url: str, origin: str):
+        self.proxy_url = validate_private_connect_proxy(proxy_url)
+        self.origin = _https_origin(origin, origin_only=True)
+        self.authority = urlsplit(self.proxy_url).netloc
+        super().__init__({"https": self.proxy_url})
+
+    def proxy_open(self, request, proxy, type):
+        if (type != "https" or request.type != "https"
+                or _https_origin(request.full_url) != self.origin):
+            raise ValueError("CONNECT proxy request is outside its configured HTTPS origin")
+        if request._tunnel_host is None:
+            request.set_proxy(self.authority, "http")
+        elif (request.host != self.authority
+                or request._tunnel_host != urlsplit(request.full_url).netloc):
+            raise ValueError("CONNECT proxy request has an unexpected tunnel destination")
+        # HTTPSHandler establishes CONNECT, then validates TLS for _tunnel_host.
+        # Never send the origin Authorization header as a proxy authorization.
+        return None
+
+
+def open_no_redirect(request: urllib.request.Request, *, timeout: float,
+                     proxy_url: str | None = None, proxy_origin: str | None = None):
+    """Open without redirects; an optional private relay is bound to one origin.
+
+    No process-wide opener/proxy setting is changed. The normal HTTPS handler
+    retains certificate and hostname verification for the origin behind CONNECT.
+    """
+    handlers = [NoRedirectHandler()]
+    if proxy_url is not None:
+        handler = _OriginConnectProxyHandler(proxy_url, proxy_origin)
+        if request.type != "https" or _https_origin(request.full_url) != handler.origin:
+            raise ValueError("CONNECT proxy request is outside its configured HTTPS origin")
+        handlers.append(handler)
+    elif proxy_origin is not None:
+        raise ValueError("CONNECT proxy origin requires an explicit proxy")
+    return urllib.request.build_opener(*handlers).open(request, timeout=timeout)