SegmentStream connections runtime

segmentstream-connections-runtime is the private Cloud Run host for custom OAuth 2.0 definitions authored with the SegmentStream SDK. It loads the workspace's connections/definitions.py, resolves customer-owned secret references, and performs authorization-code and refresh-token exchanges. Token responses are written directly to a pre-created, per-connection Google Secret Manager secret; the HTTP API returns credential metadata and never token values.

The runtime is an infrastructure component, not a public user-facing API. Its Cloud Run service must require IAM authentication.

python -m segmentstream_connections_runtime inspect manifest.json
python -m segmentstream_connections_runtime serve

The server listens on PORT, defaulting to 8080. A declaration such as secret_ref("google-oauth-client-id") is resolved from SEGMENTSTREAM_CONNECTION_SECRET_GOOGLE_OAUTH_CLIENT_ID in the isolated runtime environment. Client secrets use the same mapping convention.

Serving also requires SEGMENTSTREAM_GOOGLE_CLOUD_PROJECT and Cloud Run's automatically injected K_REVISION. The Cloud Run service identity obtains a short-lived access token from the Google metadata server and must have secretmanager.versions.add and secretmanager.versions.access only for each managed ss-oauth-<connection-id> secret. The control plane creates the secret and its IAM policy before starting OAuth authorization.

Every authorization, exchange, and refresh request includes the deployment's runtimeRevision. The runtime compares it with K_REVISION before resolving secrets or calling an OAuth provider and returns 409 runtime_revision_mismatch if Cloud Run routed the stable service URL to a different revision. POST /internal/v1/connections/{key}/token/exchange also accepts a connection ID, authorization-attempt ID, deterministic credential secret ID, authorization code, redirect URI, and PKCE verifier. POST .../token/refresh accepts the connection ID, credential secret ID, and exact stored version. Both token operations return only credentialVersion, tokenType, expiresAt, scopes, and hasRefreshToken.

A deterministic token response that is malformed, omits a required refresh token, or grants fewer scopes than the selected definition is rejected as 400 oauth_token_response_invalid before a credential version is written. OAuth provider HTTP and transport failures remain 502 oauth_provider_unavailable.

Releases

Releases use the version in pyproject.toml and are published from the connections-runtime-v<version> Git tag by the protected connections-runtime-release.yml workflow. PyPI releases are immutable, so the package version must be incremented before creating another release tag.