refactor(rust): return route outcomes as values and raise at one boundary

ComponentExecution.select now returns PythonRoute, NativeRoute or a
RouteFailure value. raise_route_failure maps the failure union onto the
public route errors with an exhaustive match.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
Yujong Lee 2026-09-15 05:04:55 +00:00
parent e80785605d
commit 35d77fb88e
2 changed files with 98 additions and 27 deletions

View file

@ -2,7 +2,9 @@ from __future__ import annotations
from collections.abc import Callable
from dataclasses import dataclass
from typing import Final, Generic, TypeVar
from typing import Final, Generic, NoReturn, TypeAlias, TypeVar
from typing_extensions import assert_never
from litellm.rust_bridge.bindings import NativeBinding
from litellm.rust_bridge.configuration import (
@ -23,25 +25,68 @@ class ComponentBinding(Generic[BindingT]):
native: NativeBinding[BindingT]
@dataclass(frozen=True, slots=True)
class PythonRoute:
pass
@dataclass(frozen=True, slots=True)
class NativeRoute(Generic[BindingT]):
native: BindingT
@dataclass(frozen=True, slots=True)
class RouteUnsupported:
component: ComponentName
@dataclass(frozen=True, slots=True)
class RouteUnavailable:
component: ComponentName
@dataclass(frozen=True, slots=True)
class RouteMismatch:
component: ComponentName
binding: ComponentName
RouteFailure: TypeAlias = RouteUnsupported | RouteUnavailable | RouteMismatch
def raise_route_failure(failure: RouteFailure) -> NoReturn:
match failure:
case RouteUnsupported(component):
raise RustRouteUnsupportedError(f"No Python or Rust implementation for {component.value}")
case RouteUnavailable(component):
raise RustRouteUnavailableError(f"Rust {component.value} bridge is unavailable")
case RouteMismatch(component, binding):
raise ValueError(f"{binding.value} binding cannot serve a {component.value} route")
case _:
assert_never(failure)
@dataclass(frozen=True, slots=True)
class ComponentExecution:
component: ComponentName
decision: ExecutionDecision
def require_supported(self) -> None:
if self.decision is ExecutionDecision.UNSUPPORTED:
raise RustRouteUnsupportedError(f"No Python or Rust implementation for {self.component.value}")
def select(self, binding: ComponentBinding[BindingT]) -> BindingT | None:
def select(self, binding: ComponentBinding[BindingT]) -> PythonRoute | NativeRoute[BindingT] | RouteFailure:
if binding.component is not self.component:
raise ValueError(f"{binding.component.value} binding cannot serve a {self.component.value} route")
self.require_supported()
if self.decision is ExecutionDecision.PYTHON:
return None
selected: Final = binding.native.load()
if selected is None and self.decision is ExecutionDecision.RUST_REQUIRED:
raise RustRouteUnavailableError(f"Rust {self.component.value} bridge is unavailable")
return selected
return RouteMismatch(component=self.component, binding=binding.component)
match self.decision:
case ExecutionDecision.UNSUPPORTED:
return RouteUnsupported(self.component)
case ExecutionDecision.PYTHON:
return PythonRoute()
case ExecutionDecision.RUST_WITH_FALLBACK:
native: Final = binding.native.load()
return PythonRoute() if native is None else NativeRoute(native)
case ExecutionDecision.RUST_REQUIRED:
required: Final = binding.native.load()
return RouteUnavailable(self.component) if required is None else NativeRoute(required)
case _:
assert_never(self.decision)
@dataclass(frozen=True, slots=True)

View file

@ -17,7 +17,18 @@ from litellm.rust_bridge.configuration import (
RustImplementationState,
)
from litellm.rust_bridge.errors import RustRouteUnavailableError, RustRouteUnsupportedError
from litellm.rust_bridge.route import ComponentBinding, ComponentExecution, NativeComponent
from litellm.rust_bridge.route import (
ComponentBinding,
ComponentExecution,
NativeComponent,
NativeRoute,
PythonRoute,
RouteFailure,
RouteMismatch,
RouteUnavailable,
RouteUnsupported,
raise_route_failure,
)
OPT_IN: Final = CapabilityDefinition(
rust=RustImplementationState.EXPERIMENTAL, python_available=True, rollout=RolloutPolicy.RUST_OPT_IN
@ -49,6 +60,11 @@ def _binding(monkeypatch: pytest.MonkeyPatch, name: ComponentName, native: objec
return _component(name).bind("route", validate=lambda value: value)
def _failure(route: PythonRoute | NativeRoute[object] | RouteFailure) -> RouteFailure:
assert not isinstance(route, PythonRoute | NativeRoute)
return route
def test_resolve_applies_process_override_to_optional_component() -> None:
component: Final = _component(ComponentName.CHAT_COMPLETIONS)
@ -72,54 +88,64 @@ def test_resolve_passes_context_to_capability_resolver() -> None:
)
def test_select_returns_none_for_python_without_loading_native(monkeypatch: pytest.MonkeyPatch) -> None:
def test_select_returns_python_route_without_loading_native(monkeypatch: pytest.MonkeyPatch) -> None:
execution: Final = ComponentExecution(component=ComponentName.OCR, decision=ExecutionDecision.PYTHON)
binding: Final = _binding(monkeypatch, ComponentName.OCR, None)
monkeypatch.setattr(bindings, "get_native_bridge", lambda: pytest.fail("native must not be loaded"))
assert execution.select(binding) is None
assert execution.select(binding) == PythonRoute()
@pytest.mark.parametrize("decision", [ExecutionDecision.RUST_WITH_FALLBACK, ExecutionDecision.RUST_REQUIRED])
def test_select_returns_native_export(monkeypatch: pytest.MonkeyPatch, decision: ExecutionDecision) -> None:
def test_select_returns_native_route(monkeypatch: pytest.MonkeyPatch, decision: ExecutionDecision) -> None:
export: Final = object()
execution: Final = ComponentExecution(component=ComponentName.OCR, decision=decision)
assert execution.select(_binding(monkeypatch, ComponentName.OCR, SimpleNamespace(route=export))) is export
assert execution.select(_binding(monkeypatch, ComponentName.OCR, SimpleNamespace(route=export))) == NativeRoute(
export
)
def test_select_falls_back_to_python_when_native_is_missing(monkeypatch: pytest.MonkeyPatch) -> None:
execution: Final = ComponentExecution(component=ComponentName.OCR, decision=ExecutionDecision.RUST_WITH_FALLBACK)
assert execution.select(_binding(monkeypatch, ComponentName.OCR, None)) is None
assert execution.select(_binding(monkeypatch, ComponentName.OCR, None)) == PythonRoute()
def test_select_raises_when_required_native_is_missing(monkeypatch: pytest.MonkeyPatch) -> None:
def test_select_reports_unavailable_when_required_native_is_missing(monkeypatch: pytest.MonkeyPatch) -> None:
execution: Final = ComponentExecution(
component=ComponentName.TRANSCRIPTION, decision=ExecutionDecision.RUST_REQUIRED
)
failure: Final = execution.select(_binding(monkeypatch, ComponentName.TRANSCRIPTION, None))
assert failure == RouteUnavailable(ComponentName.TRANSCRIPTION)
with pytest.raises(RustRouteUnavailableError, match="transcription"):
execution.select(_binding(monkeypatch, ComponentName.TRANSCRIPTION, None))
raise_route_failure(_failure(failure))
def test_select_rejects_a_binding_owned_by_another_component(monkeypatch: pytest.MonkeyPatch) -> None:
execution: Final = ComponentExecution(component=ComponentName.OCR, decision=ExecutionDecision.RUST_WITH_FALLBACK)
binding: Final = _binding(monkeypatch, ComponentName.MESSAGES, SimpleNamespace(route=object()))
monkeypatch.setattr(bindings, "get_native_bridge", lambda: pytest.fail("native must not be loaded"))
failure: Final = execution.select(binding)
assert failure == RouteMismatch(component=ComponentName.OCR, binding=ComponentName.MESSAGES)
with pytest.raises(ValueError, match=r"messages.*ocr"):
execution.select(binding)
raise_route_failure(_failure(failure))
def test_unsupported_execution_raises_before_loading_native(monkeypatch: pytest.MonkeyPatch) -> None:
def test_select_reports_unsupported_without_loading_native(monkeypatch: pytest.MonkeyPatch) -> None:
execution: Final = ComponentExecution(component=ComponentName.RESPONSES, decision=ExecutionDecision.UNSUPPORTED)
binding: Final = _binding(monkeypatch, ComponentName.RESPONSES, None)
monkeypatch.setattr(bindings, "get_native_bridge", lambda: pytest.fail("native must not be loaded"))
failure: Final = execution.select(binding)
assert failure == RouteUnsupported(ComponentName.RESPONSES)
with pytest.raises(RustRouteUnsupportedError, match="responses"):
execution.require_supported()
with pytest.raises(RustRouteUnsupportedError, match="responses"):
execution.select(binding)
raise_route_failure(_failure(failure))
def test_bind_only_allows_declared_exports(monkeypatch: pytest.MonkeyPatch) -> None: