Module adcp.server.version_policy

Per-server selection of installed AdCP wire contracts.

Functions

def enforce_selected_version(operation: str,
payload: dict[str, Any],
supported_versions: tuple[str, ...] | None,
*,
default: str | None) ‑> str | None
Expand source code
def enforce_selected_version(
    operation: str,
    payload: dict[str, Any],
    supported_versions: tuple[str, ...] | None,
    *,
    default: str | None,
) -> str | None:
    """Gate SDK tools which dispatch outside the general task caller."""
    if supported_versions is None:
        return None
    from adcp._version import resolve_adcp_version
    from adcp.exceptions import ADCPTaskError
    from adcp.types import Error
    from adcp.validation.envelope import UnsupportedVersionError, detect_wire_version

    try:
        version = detect_wire_version(payload, supported=supported_versions)
        version = version or default or resolve_adcp_version(None)
        version = resolve_adcp_version_alias(normalize_to_release_precision(version))
        if version not in {resolve_adcp_version_alias(value) for value in supported_versions}:
            raise UnsupportedVersionError(version, supported_versions)
    except UnsupportedVersionError as exc:
        raise ADCPTaskError(
            operation=operation,
            errors=[
                Error(
                    code="VERSION_UNSUPPORTED",
                    message=str(exc),
                    details={
                        "claimed_version": exc.wire_value,
                        "supported_versions": list(exc.supported),
                    },
                )
            ],
        ) from exc
    return version

Gate SDK tools which dispatch outside the general task caller.

def project_supported_versions(response: dict[str, Any], supported_versions: tuple[str, ...] | None) ‑> dict[str, typing.Any]
Expand source code
def project_supported_versions(
    response: dict[str, Any], supported_versions: tuple[str, ...] | None
) -> dict[str, Any]:
    """Copy capability metadata to match this server's accepted wire versions."""
    if supported_versions is None:
        return response
    projected = dict(response)
    adcp = dict(response.get("adcp") or {})
    adcp["supported_versions"] = list(supported_versions)
    adcp["major_versions"] = sorted(
        {int(version.split(".", 1)[0]) for version in supported_versions}
    )
    projected["adcp"] = adcp
    return projected

Copy capability metadata to match this server's accepted wire versions.

def resolve_supported_versions(supported_versions: Sequence[str] | None,
*,
handler: Any = None,
adcp_version: str | None = None) ‑> tuple[str, ...] | None
Expand source code
def resolve_supported_versions(
    supported_versions: Sequence[str] | None,
    *,
    handler: Any = None,
    adcp_version: str | None = None,
) -> tuple[str, ...] | None:
    """Freeze an explicit selection, checking routing, bundles and trusted pin.

    A handler created by Decisioning composition carries its selection to
    subsequent transport factories. Ordinary handlers retain the SDK defaults
    when no selection is supplied. The handler is never mutated here.
    """
    if supported_versions is None:
        supported_versions = getattr(handler, "_supported_adcp_versions", None)
    if supported_versions is None:
        return None
    if isinstance(supported_versions, (str, bytes)) or not isinstance(supported_versions, Sequence):
        raise ConfigurationError("supported_versions must be a non-empty sequence of wire versions")
    versions = tuple(supported_versions)
    if not versions or any(not isinstance(version, str) for version in versions):
        raise ConfigurationError("supported_versions must be a non-empty sequence of wire versions")
    versions = tuple(dict.fromkeys(versions))
    unsupported = [version for version in versions if version not in SUPPORTED_WIRE_VERSIONS]
    if unsupported:
        raise ConfigurationError(
            f"supported_versions contains unsupported wire versions {unsupported!r}; "
            f"choose from {list(SUPPORTED_WIRE_VERSIONS)!r}"
        )
    unavailable = []
    for version in versions:
        keys = list_validator_keys(version=version)
        if not any(key.endswith("::request") for key in keys) or not any(
            key.endswith("::sync") for key in keys
        ):
            unavailable.append(version)
    if unavailable:
        raise ConfigurationError(
            f"supported_versions requires installed schema bundles for {unavailable!r}"
        )
    if adcp_version is not None:
        try:
            pin = resolve_adcp_version_alias(normalize_to_release_precision(adcp_version))
        except ValueError as exc:
            raise ConfigurationError(
                f"adcp_version={adcp_version!r} is not a valid version"
            ) from exc
        if pin not in {resolve_adcp_version_alias(version) for version in versions}:
            raise ConfigurationError(
                f"adcp_version={adcp_version!r} is outside supported_versions={list(versions)!r}"
            )
    return versions

Freeze an explicit selection, checking routing, bundles and trusted pin.

A handler created by Decisioning composition carries its selection to subsequent transport factories. Ordinary handlers retain the SDK defaults when no selection is supplied. The handler is never mutated here.