Provider connections

Connect one explicit upstream capability to a Workspace and understand how its immutable UUID selects requests.

Outcome

你可以解释一条 ProviderConnection 保存什么、如何被显式选择，以及为什么 Connection ID、模型名和 Provider Secret 具有不同职责。

One connection, one explicit upstream capability

ProviderConnection 属于一个 Workspace，并包含：

Field or fact	Contract
`id`	Nexus 服务生成、创建后不可修改的 UUID。
`baseUrl`	管理端保存的上游 Origin 与基础路径；请求不能覆盖它。
`protocolProfile`	Transport 与 Usage 兼容性配置。
Provider Secret	创建或轮换时写入，随后只保存加密值并返回脱敏 Preview。
`status`	`ACTIVE`、`SUSPENDED` 或 `ARCHIVED`；Gateway 只解析可用连接。
`gatewayBaseUrl`	Nexus 根据部署 Gateway Origin 和 Connection UUID 计算的只读 Base URL。

How the Gateway resolves a connection

Inference Key
→ ApiKeyBinding → WorkspaceAccess → Workspace

Gateway Base URL
→ /providers/{providerConnectionId}

(workspaceId, providerConnectionId)
→ one ACTIVE ProviderConnection

Connection ID 必须属于认证 Key 所解析的 Workspace。相同 UUID 不能跨 Workspace 命中，客户端也不能在 URL、Header 或 Body 中提供另一个上游 Host。

Path and payload behavior

Nexus Base URL
https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca

SDK path
/chat/completions

ProviderConnection baseUrl
https://openrouter.ai/api/v1

Upstream target
https://openrouter.ai/api/v1/chat/completions

Gateway 保留剩余 Path、Query、Method 和 Body。model 是 Provider 定义的 Payload 字段，Nexus 不解析或重命名。

Multiple connections stay explicit

一个 Workspace 可以保存多条 ACTIVE ProviderConnection。同一 WorkspaceAccess 默认可使用该 Workspace 的全部 ACTIVE Connection，并共享同一 Access Quota；每次请求仍由 Base URL 中的 UUID 明确选择一条连接。

切换 Connection 时，客户端必须使用目标 Provider 接受的原始模型名。Nexus 不保证两个 Provider 使用同一模型标识。

Transport is not metering

安全的路径透传不等于该 Endpoint 已具备 Quota 计量。需要 Token Quota 的 Endpoint 还必须有匹配的 Usage Inspector；不支持的路径默认返回稳定的 metering_unsupported 类错误，而不是在无法结算时放行。

Lifecycle and secret safety

Verify 检查连接可用性，并记录 lastVerifiedAt；它不会把 Secret 返回给客户端。
Rotate secret 更新加密 Provider Secret，不改变 Connection UUID、用户 Access 或 Inference Key。
Suspend or archive 阻止新请求选择该连接；历史 Invocation、Usage 和 Audit 保留。