[antoinetoussaint-byte]

Summary

The host's own contract says this library cannot reach a current host, and this PR fixes that.

module-saas-starter #864 (closing #859) published module/INTERNAL_TRANSPORT.md. It says the internal tier, including WorkContextService.CheckAuthorizationRevision, is cleartext HTTP/2 (h2c) multiplexed onto accounts' private rest endpoint. In-cluster transport security belongs to the mesh. It also says: "A library that requires an explicit https:// origin, or that dials with channel credentials built from a CA bundle, cannot reach a current host." GRPCClient does both of those things.

• MeshGRPCClient(address, credential): dials the host:port Codefly resolved for accounts' rest endpoint over h2c (grpc.aio.insecure_channel), and adds no TLS of its own. It refuses a scheme, a path, a query, credentials or a zero/invalid port in the address, because the address is resolved, not configured as a URL. The check itself (one total budget including the credential refresh, no retries, x-codefly-internal-token metadata, an exact empty response, and RevisionDenied/RevisionUnavailable mapping) moved unchanged into a shared _GRPCRevision base. GRPCClient behaves exactly as before.
• WorkContextUnavailable: a WorkContextError subclass. JWKSVerifier raises it when the key set cannot be fetched, is not JSON, is oversized, or is malformed. The same contract makes the published JWKS the only key producer, so a consumer that verifies through it needs to tell "the authority is down" (retryable, 503) apart from "this capability is invalid" (401). Existing except WorkContextError handlers still catch it.

Classification: a fix, in the library the host's contract names. The earlier form refused the only transport the host serves.

Why now

The model gateway's Codefly-hosted runtime (obin-ai/module-model-gateway, PR linked from there) checks the current authorization revision on every admitted request, and verifies Work Contexts against the published JWKS. It pins this repository by commit.

Test plan

• python -m pytest -q: 165 passed.
• Every existing gRPC conformance test now runs twice: against a TLS server with GRPCClient, and against an h2c server with MeshGRPCClient. Covered: wire shape and credential refresh, typed errors with no retry, exact empty response, caller cancellation, and the total budget including the credential.
• The new address tests cover refused forms (scheme, path, query, fragment, credentials, bad or missing port, whitespace) and accepted forms (DNS name, IPv4, bracketed IPv6).
• The JWKS outage tests (boot, backoff, redirect, malformed, oversized) now assert WorkContextUnavailable. A new test asserts that a token the served keys reject is not reported as unavailable.

Not verified

• Nothing was run against a real accounts service or inside a mesh. The h2c server in the tests is a plain grpc.aio insecure port.
• Using MeshGRPCClient safely depends on the mesh enforcing mutual TLS on the hop (STRICT PeerAuthentication in the host's contract). This library cannot check that, and the docstring and README say so.

🤖 Generated with Claude Code