httpapi

Documentation

Overview

Package httpapi exposes only framework-level Vulcan Model Core endpoints. httpapi 包仅暴露 Vulcan Model Core 的框架级端点。

Index

• Variables
• type APIKeyManager
• type AccessDiagnostics
• type AntigravityOAuthFlows
• type ClaudeOAuthFlows
• type CodexDeviceFlows
• type CodexOAuthFlows
• type ControlPlane
• type CredentialPlanManagement
• type CustomCatalogOperations
• type ExecutionDiagnostics
• type ExecutionSelector
• type ExecutionService
• type InputPlanService
• type KeyAuthenticator
• type KimiDeviceFlows
• type ManagementCommands
• type ManagementQuery
• type MiniMaxDeviceFlows
• type ModelAccessCommands
• type ModelToolAvailability
• type OpenRouterCatalogRefresh
• type PrincipalAuthenticator
• type ProtocolProfileQuery
• type ProviderCatalog
• type ProviderCredentialMetadataRefresh
• type ProviderMetadataRefresh
• type ProviderMetadataRefreshScheduler
• type ResourceDiagnostics
• type ResourceGateway
• type Server
  • func New(catalog ProviderCatalog) (*Server, error)
  • func NewWithControlPlane(catalog ProviderCatalog, control ControlPlane) (*Server, error)
  • func (s *Server) Handler() http.Handler
• type TargetAvailability
• type UsagePreflightService
• type XAIDeviceFlows

Variables

var (
	// ErrProviderCatalogRequired identifies a missing provider metadata source.
	// ErrProviderCatalogRequired 标识缺失的供应商元数据来源。
	ErrProviderCatalogRequired = errors.New("provider catalog is required")
)

Types

type APIKeyManager

type APIKeyManager interface {
	// ListAPIKeys returns management-visible plaintext API keys.
	// ListAPIKeys 返回管理面可见的明文 API 密钥。
	ListAPIKeys() []runtimeconfig.APIKey
	// CreateAPIKey persists one caller-supplied API key.
	// CreateAPIKey 持久化一个调用方提供的 API 密钥。
	CreateAPIKey(runtimeconfig.APIKeyInput) (runtimeconfig.APIKey, error)
	// UpdateAPIKey replaces one API key by its immutable identifier.
	// UpdateAPIKey 按不可变标识替换一个 API 密钥。
	UpdateAPIKey(string, runtimeconfig.APIKeyInput) (runtimeconfig.APIKey, error)
	// DeleteAPIKey removes one API key by its immutable identifier.
	// DeleteAPIKey 按不可变标识删除一个 API 密钥。
	DeleteAPIKey(string) error
}

APIKeyManager exposes management-only call-plane API key lifecycle operations. APIKeyManager 暴露仅限管理面的调用面 API 密钥生命周期操作。

type AccessDiagnostics

type AccessDiagnostics interface {
	// Audit returns a bounded isolated audit snapshot.
	// Audit 返回有界且隔离的审计快照。
	Audit() []access.AuditEvent
	// Metrics returns aggregate content-free request metrics.
	// Metrics 返回不含内容的聚合请求指标。
	Metrics() access.Snapshot
}

AccessDiagnostics exposes only bounded redacted audit entries and aggregate request metrics. AccessDiagnostics 仅暴露有界脱敏审计条目与聚合请求指标。

type AntigravityOAuthFlows

type AntigravityOAuthFlows interface {
	// Start creates one management-safe browser authorization session.
	// Start 创建一个管理安全的浏览器授权会话。
	Start(context.Context) (providergoogle.AntigravityOAuthFlow, error)
	// Complete validates one pasted callback and performs bounded provider exchanges.
	// Complete 校验一个粘贴回调并执行有界供应商交换。
	Complete(context.Context, string, string) (providergoogle.AntigravityToken, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local authorization session.
	// Cancel 消费一个未完成或已完成的本地授权会话。
	Cancel(string)
}

AntigravityOAuthFlows owns transient Google consent state without exposing provider tokens. AntigravityOAuthFlows 管理临时 Google 同意授权状态且不暴露供应商 Token。

type ClaudeOAuthFlows

type ClaudeOAuthFlows interface {
	// Start creates one management-safe Claude browser authorization session.
	// Start 创建一个管理安全的 Claude 浏览器授权会话。
	Start(context.Context) (provideranthropic.ClaudeOAuthFlow, error)
	// Complete validates one callback or code#state value and performs the provider exchange.
	// Complete 校验一个回调或 code#state 值并执行供应商交换。
	Complete(context.Context, string, string) (provideranthropic.ClaudeToken, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local Claude authorization session.
	// Cancel 消费一个未完成或已完成的本地 Claude 授权会话。
	Cancel(string)
}

ClaudeOAuthFlows owns transient Claude PKCE and consent state without exposing provider tokens. ClaudeOAuthFlows 管理临时 Claude PKCE 与同意授权状态且不暴露供应商 Token。

type CodexDeviceFlows

type CodexDeviceFlows interface {
	// Start creates one management-safe Codex verification session.
	// Start 创建一个管理安全的 Codex 验证会话。
	Start(context.Context) (provideropenai.CodexDeviceFlow, error)
	// Poll performs one bounded Codex token exchange.
	// Poll 执行一次有界 Codex Token 交换。
	Poll(context.Context, string) (provideropenai.CodexToken, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local authorization session.
	// Cancel 消费一个未完成或已完成的本地授权会话。
	Cancel(string)
}

CodexDeviceFlows owns transient Codex account authorization sessions without exposing provider tokens. CodexDeviceFlows 管理临时 Codex 账号授权会话且不暴露供应商 Token。

type CodexOAuthFlows

type CodexOAuthFlows interface {
	// Start creates one management-safe Codex browser authorization session.
	// Start 创建一个管理安全的 Codex 浏览器授权会话。
	Start(context.Context) (provideropenai.CodexOAuthFlow, error)
	// Complete validates one pasted localhost callback and performs the provider exchange.
	// Complete 校验一个粘贴的 localhost 回调并执行供应商交换。
	Complete(context.Context, string, string) (provideropenai.CodexToken, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local authorization session.
	// Cancel 消费一个未完成或已完成的本地授权会话。
	Cancel(string)
}

CodexOAuthFlows owns transient Codex browser PKCE state without exposing provider tokens. CodexOAuthFlows 管理临时 Codex 浏览器 PKCE 状态且不暴露供应商 Token。

type ControlPlane

type ControlPlane struct {
	// Query supplies redacted configuration and catalog views.
	// Query 提供脱敏配置和目录视图。
	Query ManagementQuery
	// Commands applies provider configuration mutations.
	// Commands 应用供应商配置变更。
	Commands ManagementCommands
	// ModelAccess applies instance-level model policies.
	// ModelAccess 应用实例级模型策略。
	ModelAccess ModelAccessCommands
	// CustomCatalogs reads and writes user-declared model metadata for custom providers only.
	// CustomCatalogs 仅为自定义供应商读取和写入用户声明模型元数据。
	CustomCatalogs CustomCatalogOperations
	// MetadataRefresh refreshes provider-native account metadata and provider-usable resources through trusted readers.
	// MetadataRefresh 通过受信任读取器刷新供应商原生账号元数据与供应商可用资源。
	MetadataRefresh ProviderMetadataRefresh
	// OpenRouterCatalogs optionally refreshes public OpenRouter discovery facts independently from account metadata.
	// OpenRouterCatalogs 可选地独立于账号元数据刷新 OpenRouter 公共发现事实。
	OpenRouterCatalogs OpenRouterCatalogRefresh
	// CredentialPlans optionally exposes manual commercial-plan settings.
	// CredentialPlans 可选暴露人工商业套餐设置。
	CredentialPlans CredentialPlanManagement
	// RouterTools optionally owns explicit standard-tool backend bindings.
	// RouterTools 可选地管理显式标准工具后端绑定。
	RouterTools routertool.Store
	// ModelToolAvailability optionally evaluates scoped Router bindings for call-plane model discovery.
	// ModelToolAvailability 可选地为调用面模型发现评估范围匹配的 Router 绑定。
	ModelToolAvailability ModelToolAvailability
	// Protocols exposes custom-provider-selectable protocol metadata.
	// Protocols 暴露可供自定义供应商选择的协议元数据。
	Protocols ProtocolProfileQuery
	// APIKeys owns plaintext call-plane key lifecycle operations.
	// APIKeys 管理明文调用面密钥生命周期操作。
	APIKeys APIKeyManager
	// Auth verifies route-scoped bearer values.
	// Auth 校验路由作用域 Bearer 值。
	Auth KeyAuthenticator
	// Access optionally enforces tenant authorization, rate limits, concurrency, audit, and metrics.
	// Access 可选地强制执行租户授权、限流、并发、审计和指标。
	Access access.Controller
	// CallIdentityVerifier optionally accepts external OIDC identities on call-plane routes.
	// CallIdentityVerifier 可选地在调用面路由接受外部 OIDC 身份。
	CallIdentityVerifier access.IdentityVerifier
	// AccessDiagnostics optionally exposes bounded redacted access audit and aggregate metrics to management routes.
	// AccessDiagnostics 可选地向管理路由暴露有界脱敏访问审计与聚合指标。
	AccessDiagnostics AccessDiagnostics
	// Resources owns authenticated Router resource ingestion and lifecycle operations.
	// Resources 拥有已认证 Router 资源接收与生命周期操作。
	Resources ResourceGateway
	// InputPlans owns authenticated conditional media planning.
	// InputPlans 拥有已认证条件媒体规划。
	InputPlans InputPlanService
	// Executions owns authenticated durable execution lifecycle operations.
	// Executions 拥有已认证持久化执行生命周期操作。
	Executions ExecutionService
	// Preflight optionally exposes side-effect-free provider accounting.
	// Preflight 可选暴露无副作用供应商计量。
	Preflight UsagePreflightService
	// ResourceDiagnostics optionally exposes management-safe resource metadata without call-plane owner secrets.
	// ResourceDiagnostics 可选暴露不含调用面所有者秘密的管理安全资源元数据。
	ResourceDiagnostics ResourceDiagnostics
	// ExecutionDiagnostics optionally exposes management-safe execution lifecycle snapshots.
	// ExecutionDiagnostics 可选暴露管理安全执行生命周期快照。
	ExecutionDiagnostics ExecutionDiagnostics
	// CatalogChanges optionally exposes globally ordered catalog invalidations to the call plane.
	// CatalogChanges 可选地向调用面暴露全局有序目录失效事实。
	CatalogChanges catalog.ChangeStore
	// ProviderFileDiagnostics optionally exposes credential-scoped upstream file metadata.
	// ProviderFileDiagnostics 可选暴露凭据作用域的上游文件元数据。
	ProviderFileDiagnostics provider.ProviderFileDiagnosticsReader
	// Targets verifies that discovery profiles are currently executable.
	// Targets 校验发现规格当前可执行。
	Targets TargetAvailability
	// KimiDeviceFlows optionally enables server-owned Coding Plan device authorization routes.
	// KimiDeviceFlows 可选启用服务端拥有的 Coding Plan 设备授权路由。
	KimiDeviceFlows KimiDeviceFlows
	// MiniMaxDeviceFlows optionally enables region-explicit MiniMax device authorization routes.
	// MiniMaxDeviceFlows 可选启用显式区域的 MiniMax 设备授权路由。
	MiniMaxDeviceFlows MiniMaxDeviceFlows
	// XAIDeviceFlows optionally enables server-owned xAI device authorization routes.
	// XAIDeviceFlows 可选启用服务端拥有的 xAI 设备授权路由。
	XAIDeviceFlows XAIDeviceFlows
	// CodexDeviceFlows optionally enables server-owned Codex device authorization routes.
	// CodexDeviceFlows 可选启用服务端拥有的 Codex 设备授权路由。
	CodexDeviceFlows CodexDeviceFlows
	// CodexOAuthFlows optionally enables server-owned Codex browser authorization routes.
	// CodexOAuthFlows 可选启用服务端拥有的 Codex 浏览器授权路由。
	CodexOAuthFlows CodexOAuthFlows
	// ClaudeOAuthFlows optionally enables server-owned Claude Code consent routes.
	// ClaudeOAuthFlows 可选启用服务端拥有的 Claude Code 同意授权路由。
	ClaudeOAuthFlows ClaudeOAuthFlows
	// AntigravityOAuthFlows optionally enables server-owned Google consent routes.
	// AntigravityOAuthFlows 可选启用服务端拥有的 Google 同意授权路由。
	AntigravityOAuthFlows AntigravityOAuthFlows
}

ControlPlane groups every dependency required by authenticated management and call-plane routes. ControlPlane 聚合认证管理和调用面路由所需的全部依赖。

type CredentialPlanManagement

type CredentialPlanManagement interface {
	// SetCredentialPlan replaces one manual plan and exact entitlement matrix.
	// SetCredentialPlan 替换一个人工套餐与精确权益矩阵。
	SetCredentialPlan(context.Context, string, string, string) (providerconfig.Credential, error)
}

CredentialPlanManagement exposes manual commercial-plan mutations. CredentialPlanManagement 暴露人工商业套餐变更。

type CustomCatalogOperations

type CustomCatalogOperations interface {
	// GetCustomCatalog returns the current catalog only for a custom provider instance.
	// GetCustomCatalog 仅为自定义供应商实例返回当前目录。
	GetCustomCatalog(context.Context, string) (catalog.Snapshot, error)
	// SaveCustomCatalog replaces one complete custom-provider catalog revision.
	// SaveCustomCatalog 替换一份完整的自定义供应商目录修订。
	SaveCustomCatalog(context.Context, management.SaveCustomCatalogInput) (catalog.Snapshot, error)
}

CustomCatalogOperations exposes complete user-declared catalog read and write operations. CustomCatalogOperations 暴露完整用户声明目录的读写操作。

type ExecutionDiagnostics

type ExecutionDiagnostics interface {
	// ListDiagnostics returns newest execution snapshots in stable order.
	// ListDiagnostics 以稳定顺序返回最新执行快照。
	ListDiagnostics(context.Context, int) ([]execution.Record, error)
}

ExecutionDiagnostics lists management-safe lifecycle snapshots without private provider affinity. ExecutionDiagnostics 列出不含私有供应商亲和性的管理安全生命周期快照。

type ExecutionSelector

type ExecutionSelector interface {
	// Select validates an exact caller-selected provider, account, and model-or-service target without exposing endpoint identity.
	// Select 返回一个不暴露凭据或入口身份的精确模型选择。
	Select(context.Context, vcp.ExecutionSelectionRequest, time.Time) (vcp.ExecutionSelection, error)
}

ExecutionSelector chooses one safe exact model target inside a caller-fixed provider instance. ExecutionSelector 在调用方固定的供应商实例内选择一个安全精确模型 Target。

type ExecutionService

type ExecutionService interface {
	// Create admits and executes one VCP request or returns an idempotent replay.
	// Create 接收并执行一个 VCP 请求或返回幂等重放。
	Create(context.Context, string, vcp.ExecutionRequest) (execution.Record, bool, error)
	// Get returns one owner-scoped execution.
	// Get 返回一个所有者作用域执行。
	Get(context.Context, string, string) (execution.Record, error)
	// Events returns durable events after one sequence.
	// Events 返回指定序号之后的持久化事件。
	Events(context.Context, string, string, uint64) ([]execution.Event, error)
	// Cancel requests one deterministic cancellation.
	// Cancel 请求一次确定性取消。
	Cancel(context.Context, string, string) (execution.Record, error)
}

ExecutionService owns durable owner-scoped execution lifecycle operations. ExecutionService 拥有持久化所有者作用域执行生命周期操作。

type InputPlanService

type InputPlanService interface {
	// Create resolves and persists one exact input plan.
	// Create 解析并持久化一个精确输入方案。
	CreateInputPlan(context.Context, inputplan.Request) (inputplan.Plan, error)
}

InputPlanService creates immutable owner-scoped conditional media plans. InputPlanService 创建不可变所有者作用域条件媒体方案。

type KeyAuthenticator

type KeyAuthenticator interface {
	// AuthenticateManagementKey verifies one management-plane bearer value.
	// AuthenticateManagementKey 校验一个管理面 Bearer 值。
	AuthenticateManagementKey(string) bool
	// AuthenticateAPIKey verifies one call-plane bearer value.
	// AuthenticateAPIKey 校验一个调用面 Bearer 值。
	AuthenticateAPIKey(string) bool
	// AuthenticateAPIKeyID verifies one call-plane bearer and returns its non-secret identifier.
	// AuthenticateAPIKeyID 校验一个调用面 Bearer 并返回其非秘密标识。
	AuthenticateAPIKeyID(string) (string, bool)
}

KeyAuthenticator verifies bearer credentials independently for management and call-plane routes. KeyAuthenticator 分别为管理和调用面路由校验 Bearer 凭据。

type KimiDeviceFlows

type KimiDeviceFlows interface {
	// Start creates one management-safe provider verification session.
	// Start 创建一个管理安全的供应商验证会话。
	Start(context.Context) (providerkimi.Flow, error)
	// Poll performs one bounded provider token exchange.
	// Poll 执行一次有界供应商令牌交换。
	Poll(context.Context, string) (providerkimi.Token, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local authorization session.
	// Cancel 消费一个未完成或已完成的本地授权会话。
	Cancel(string)
}

KimiDeviceFlows owns transient Coding Plan authorization sessions without exposing provider tokens. KimiDeviceFlows 管理临时 Coding Plan 授权会话且不暴露供应商令牌。

type ManagementCommands

type ManagementCommands interface {
	// OnboardSystemProvider atomically creates one complete system-provider access path.
	// OnboardSystemProvider 原子创建一条完整系统供应商访问路径。
	OnboardSystemProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardKimiDeviceProvider accepts only a server-acquired and validated Kimi device credential.
	// OnboardKimiDeviceProvider 仅接受由服务端获取并校验的 Kimi 设备凭据。
	OnboardKimiDeviceProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardMiniMaxDeviceProvider accepts only a server-acquired region-bound MiniMax credential.
	// OnboardMiniMaxDeviceProvider 仅接受服务端获取且绑定区域的 MiniMax 凭据。
	OnboardMiniMaxDeviceProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardXAIDeviceProvider accepts only a server-acquired and validated xAI device credential.
	// OnboardXAIDeviceProvider 仅接受由服务端获取并校验的 xAI 设备凭据。
	OnboardXAIDeviceProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardCodexDeviceProvider accepts only a server-acquired and validated Codex device credential.
	// OnboardCodexDeviceProvider 仅接受由服务端获取并校验的 Codex 设备凭据。
	OnboardCodexDeviceProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardCodexOAuthProvider accepts only a server-acquired and validated Codex browser OAuth credential.
	// OnboardCodexOAuthProvider 仅接受由服务端获取并校验的 Codex 浏览器 OAuth 凭据。
	OnboardCodexOAuthProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardClaudeOAuthProvider accepts only a server-acquired and validated Claude Code OAuth credential.
	// OnboardClaudeOAuthProvider 仅接受由服务端获取并校验的 Claude Code OAuth 凭据。
	OnboardClaudeOAuthProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardAntigravityOAuthProvider accepts only a server-acquired and validated Antigravity OAuth credential.
	// OnboardAntigravityOAuthProvider 仅接受由服务端获取并校验的 Antigravity OAuth 凭据。
	OnboardAntigravityOAuthProvider(context.Context, management.OnboardSystemProviderInput) (providerconfig.SystemOnboarding, error)
	// OnboardVertexServiceAccountProvider accepts only a normalized Google service-account document and location.
	// OnboardVertexServiceAccountProvider 仅接受规范化的 Google 服务账号文档与区域。
	OnboardVertexServiceAccountProvider(context.Context, management.OnboardSystemProviderInput, string) (providerconfig.SystemOnboarding, error)
	// OnboardCustomProvider atomically creates one executable custom compatibility provider and initial model.
	// OnboardCustomProvider 原子创建一个可执行自定义兼容供应商与初始模型。
	OnboardCustomProvider(context.Context, management.OnboardCustomProviderInput) (management.CustomProviderOnboardingResult, error)
	// CreateCustomDefinition creates one user-owned provider definition.
	// CreateCustomDefinition 创建一个用户拥有的供应商定义。
	CreateCustomDefinition(context.Context, management.CreateCustomDefinitionInput) (providerconfig.ProviderDefinition, error)
	// UpdateCustomDefinition replaces one user-owned provider definition.
	// UpdateCustomDefinition 替换一个用户拥有的供应商定义。
	UpdateCustomDefinition(context.Context, management.UpdateCustomDefinitionInput) (providerconfig.ProviderDefinition, error)
	// DeleteCustomDefinition removes one user-owned provider definition and optionally its complete credential graph.
	// DeleteCustomDefinition 删除一个用户拥有的供应商定义，并可选择删除其完整凭据图。
	DeleteCustomDefinition(context.Context, string, bool) error
	// ConfigureProvider creates one credential-independent provider configuration and catalog.
	// ConfigureProvider 创建一个独立于凭据的供应商配置与目录。
	ConfigureProvider(context.Context, management.ConfigureProviderInput) (management.ProviderConfigurationResult, error)
	// DeleteProviderConfiguration removes one credential-free provider configuration.
	// DeleteProviderConfiguration 删除一个不含凭据的供应商配置。
	DeleteProviderConfiguration(context.Context, string) error
	// SaveCustomProviderModels replaces one custom provider's simplified model catalog.
	// SaveCustomProviderModels 替换一个自定义供应商的简化模型目录。
	SaveCustomProviderModels(context.Context, string, []management.InitialProviderModelInput) (catalog.Snapshot, error)
	// SaveCustomProviderAdditionalParameters replaces provider-wide additional request rules for one custom provider.
	// SaveCustomProviderAdditionalParameters 替换一个自定义供应商的供应商级附加请求规则。
	SaveCustomProviderAdditionalParameters(context.Context, string, catalog.AdditionalPayloadProjection) (catalog.Snapshot, error)
	// CreateInstance creates one provider instance.
	// CreateInstance 创建一个供应商实例。
	CreateInstance(context.Context, management.CreateInstanceInput) (providerconfig.ProviderInstance, error)
	// UpdateInstance replaces editable provider instance identity fields.
	// UpdateInstance 替换可编辑供应商实例身份字段。
	UpdateInstance(context.Context, management.UpdateInstanceInput) (providerconfig.ProviderInstance, error)
	// SetInstanceEnabled changes local instance availability.
	// SetInstanceEnabled 更改本地实例可用性。
	SetInstanceEnabled(context.Context, string, bool) (providerconfig.ProviderInstance, error)
	// AddEndpoint creates one upstream endpoint.
	// AddEndpoint 创建一个上游端点。
	AddEndpoint(context.Context, management.AddEndpointInput) (providerconfig.Endpoint, error)
	// UpdateEndpoint replaces one upstream endpoint.
	// UpdateEndpoint 替换一个上游端点。
	UpdateEndpoint(context.Context, management.UpdateEndpointInput) (providerconfig.Endpoint, error)
	// AddCredential creates one provider credential from transient secret bytes.
	// AddCredential 根据临时 Secret 字节创建一个供应商凭据。
	AddCredential(context.Context, management.AddCredentialInput) (providerconfig.Credential, error)
	// AttachCredential creates one credential, closes its access bindings, and activates the provider configuration.
	// AttachCredential 创建一个凭据、闭合其访问绑定并激活供应商配置。
	AttachCredential(context.Context, management.AddCredentialInput) (management.CredentialAttachment, error)
	// AttachAcquiredCredential attaches one server-acquired provider credential to an existing configuration.
	// AttachAcquiredCredential 将一个服务端获取的供应商凭据附加到既有配置。
	AttachAcquiredCredential(context.Context, management.AttachAcquiredCredentialInput) (management.CredentialAttachment, error)
	// UpdateCredential replaces one credential's non-secret metadata.
	// UpdateCredential 替换一个凭据的非秘密元数据。
	UpdateCredential(context.Context, management.UpdateCredentialInput) (providerconfig.Credential, error)
	// RotateCredentialSecret replaces one credential's protected secret bytes.
	// RotateCredentialSecret 替换一个凭据的受保护 Secret 字节。
	RotateCredentialSecret(context.Context, management.RotateCredentialSecretInput) (providerconfig.Credential, error)
	// ReauthorizeCredential replaces one provider-owned token after exact account validation.
	// ReauthorizeCredential 在精确账号校验后替换一个供应商拥有的 Token。
	ReauthorizeCredential(context.Context, management.ReauthorizeCredentialInput) (providerconfig.Credential, error)
	// DeleteCredential removes one credential graph while retaining its provider configuration.
	// DeleteCredential 删除一个凭据图，同时保留其供应商配置。
	DeleteCredential(context.Context, string, string) (providerconfig.CredentialDeletion, error)
	// SetCredentialStatus changes one credential lifecycle state.
	// SetCredentialStatus 更改一个凭据生命周期状态。
	SetCredentialStatus(context.Context, management.SetCredentialStatusInput) (providerconfig.Credential, error)
	// AddBinding creates one credential-to-endpoint access binding.
	// AddBinding 创建一个凭据到端点的访问绑定。
	AddBinding(context.Context, management.AddBindingInput) (providerconfig.AccessBinding, error)
	// UpdateBinding replaces one credential-to-endpoint access binding.
	// UpdateBinding 替换一个凭据到端点的访问绑定。
	UpdateBinding(context.Context, management.UpdateBindingInput) (providerconfig.AccessBinding, error)
}

ManagementCommands exposes typed provider configuration mutations to the management HTTP boundary. ManagementCommands 向管理 HTTP 边界暴露类型化供应商配置变更。

type ManagementQuery

type ManagementQuery interface {
	// ListProviderGroups returns management-only system provider groups and exact selectable definitions.
	// ListProviderGroups 返回仅供管理使用的系统供应商分组及精确可选定义。
	ListProviderGroups(context.Context) ([]management.ProviderGroupView, error)
	// ListDefinitions returns visible system and custom provider definitions.
	// ListDefinitions 返回可见系统与自定义供应商定义。
	ListDefinitions(context.Context) ([]management.ProviderDefinitionView, error)
	// ListInstances returns safe aggregate provider instance views.
	// ListInstances 返回安全的供应商实例聚合视图。
	ListInstances(context.Context) ([]management.ProviderInstanceView, error)
	// GetInstance returns one safe provider instance aggregate.
	// GetInstance 返回一个安全供应商实例聚合。
	GetInstance(context.Context, string) (management.ProviderInstanceView, error)
	// GetCatalog returns one safe atomic provider model catalog.
	// GetCatalog 返回一个安全原子供应商模型目录。
	GetCatalog(context.Context, string) (management.CatalogView, error)
	// ListCapabilityContracts returns complete exact-target contracts selected by provider-owned identifiers.
	// ListCapabilityContracts 返回按供应商所属标识选择的完整精确目标契约。
	ListCapabilityContracts(context.Context, string, string, string, string) ([]management.CapabilityContractView, error)
	// GetCatalogAudit returns complete internal model facts and publication decisions for management review.
	// GetCatalogAudit 返回供管理审核使用的完整内部模型事实与发布决策。
	GetCatalogAudit(context.Context, string) (management.CatalogAuditView, error)
	// GetModelContexts returns exact model context profiles and their concrete authorized accounts.
	// GetModelContexts 返回精确模型上下文规格及其具体已授权账号。
	GetModelContexts(context.Context, string, string) (management.ModelContextsView, error)
	// GetModelCredentialUsage returns usage applicable to one exact model-account pair.
	// GetModelCredentialUsage 返回适用于一个精确模型账号组合的用量。
	GetModelCredentialUsage(context.Context, string, string, string) (management.ModelCredentialUsageView, error)
	// GetServiceAccounts returns exact service execution profiles and their concrete authorized accounts.
	// GetServiceAccounts 返回精确服务执行规格及其具体已授权账号。
	GetServiceAccounts(context.Context, string, string) (management.ServiceAccountsView, error)
	// GetServiceCredentialUsage returns usage applicable to one exact service-account pair.
	// GetServiceCredentialUsage 返回适用于一个精确服务账号组合的用量。
	GetServiceCredentialUsage(context.Context, string, string, string) (management.ServiceCredentialUsageView, error)
	// ListEndpoints returns management-safe endpoint records.
	// ListEndpoints 返回管理安全端点记录。
	ListEndpoints(context.Context, string) ([]management.EndpointView, error)
	// ListCredentials returns management-safe non-secret credential records.
	// ListCredentials 返回管理安全的非秘密凭据记录。
	ListCredentials(context.Context, string) ([]management.CredentialView, error)
	// ListBindings returns management-safe access binding records.
	// ListBindings 返回管理安全访问绑定记录。
	ListBindings(context.Context, string) ([]management.BindingView, error)
}

ManagementQuery exposes client-safe configuration, catalog, and management-detail views. ManagementQuery 暴露客户端安全的配置、目录和管理详情视图。

type MiniMaxDeviceFlows

type MiniMaxDeviceFlows interface {
	// Start creates one verification session in exactly global or cn.
	// Start 仅在 global 或 cn 精确区域创建一个验证会话。
	Start(context.Context, string) (providerminimax.Flow, error)
	// Poll performs one bounded exchange against the flow-owned regional Origin.
	// Poll 针对流程拥有的区域 Origin 执行一次有界交换。
	Poll(context.Context, string) (providerminimax.Token, error)
	// Release returns one completed token lease after downstream failure.
	// Release 在下游失败后归还一个已完成 Token 租约。
	Release(string)
	// Cancel consumes one local authorization flow.
	// Cancel 消费一个本地授权流程。
	Cancel(string)
}

MiniMaxDeviceFlows owns transient region-explicit MiniMax authorization sessions without exposing tokens. MiniMaxDeviceFlows 管理临时且显式指定区域的 MiniMax 授权会话，且不暴露 Token。

type ModelAccessCommands

type ModelAccessCommands interface {
	// SetModelEnabled updates one exact provider model policy.
	// SetModelEnabled 更新一个精确供应商模型策略。
	SetModelEnabled(context.Context, management.SetModelEnabledInput) (providerconfig.ProviderInstance, error)
	// SetModelPublicationMode atomically replaces one instance model publication policy.
	// SetModelPublicationMode 原子替换一个实例模型发布策略。
	SetModelPublicationMode(context.Context, management.SetModelPublicationModeInput) (providerconfig.ProviderInstance, error)
}

ModelAccessCommands exposes typed instance model enablement operations. ModelAccessCommands 暴露类型化实例模型启停操作。

type ModelToolAvailability

type ModelToolAvailability interface {
	// Options lists exact standard-tool bindings without selecting one.
	// Options 列出精确标准工具绑定且不代替调用方选择。
	Options(context.Context, resolve.Target, vcp.StandardModelToolKind, time.Time) ([]routertool.BindingOption, error)
	// OptionsExtension lists exact enhancement bindings without selecting one.
	// OptionsExtension 列出精确增强能力绑定且不代替调用方选择。
	OptionsExtension(context.Context, resolve.Target, vcp.RouterExtensionKind, time.Time) ([]routertool.BindingOption, error)
	// ProbeBinding tests one exact persisted Router binding without exposing its selected credential.
	// ProbeBinding 测试一个精确持久化 Router 绑定且不暴露其选定凭据。
	ProbeBinding(context.Context, string, time.Time) (routertool.BindingProbe, error)
}

ModelToolAvailability exposes caller-selectable Router bindings and exact non-secret account readiness. ModelToolAvailability 公开可由调用方选择的 Router 绑定及精确非秘密账号就绪状态。

type OpenRouterCatalogRefresh

type OpenRouterCatalogRefresh interface {
	// Refresh fetches, validates, caches, and publishes one exact OpenRouter instance catalog.
	// Refresh 获取、校验、缓存并发布一个精确 OpenRouter 实例目录。
	Refresh(context.Context, string) (catalog.Snapshot, error)
	// PrepareModel refreshes the full catalog and validates endpoint details for one selected model.
	// PrepareModel 刷新完整目录并校验一个已选模型的 Endpoint 详情。
	PrepareModel(context.Context, string, string) (catalog.Snapshot, error)
	// ManagementCatalog returns the complete verified OpenRouter inventory with local publication decisions.
	// ManagementCatalog 返回带本地发布决策的完整已校验 OpenRouter 清单。
	ManagementCatalog(context.Context, string) (management.OpenRouterManagementCatalogView, error)
	// InspectModelEndpoints explicitly loads current serving Endpoint facts for one exact model.
	// InspectModelEndpoints 显式加载一个精确模型当前的服务 Endpoint 事实。
	InspectModelEndpoints(context.Context, string, string) (management.OpenRouterModelEndpointDetailsView, error)
}

OpenRouterCatalogRefresh refreshes one complete public OpenRouter model catalog. OpenRouterCatalogRefresh 刷新一个完整的 OpenRouter 公共模型目录。

type PrincipalAuthenticator

type PrincipalAuthenticator interface {
	// AuthenticateAPIPrincipal verifies one bearer and returns no raw credential material.
	// AuthenticateAPIPrincipal 校验一个 Bearer 且不返回原始凭据材料。
	AuthenticateAPIPrincipal(string) (access.Principal, bool)
}

PrincipalAuthenticator returns a validated tenant-scoped identity for an enabled call-plane key. PrincipalAuthenticator 为启用的调用面密钥返回经过验证的租户作用域身份。

type ProtocolProfileQuery

type ProtocolProfileQuery interface {
	// List returns an isolated stable snapshot of registered protocol profiles.
	// List 返回已注册协议 Profile 的隔离稳定快照。
	List() []providerconfig.ProtocolProfile
}

ProtocolProfileQuery exposes immutable process-owned protocol metadata to the management surface. ProtocolProfileQuery 向管理接口面暴露不可变的进程拥有协议元数据。

type ProviderCatalog

type ProviderCatalog interface {
	// ProviderIDs returns stable provider identifiers without exposing adapters.
	// ProviderIDs 返回稳定的供应商标识且不暴露适配器。
	ProviderIDs() []string
}

ProviderCatalog exposes the registered provider snapshot needed by HTTP metadata endpoints. ProviderCatalog 暴露 HTTP 元数据端点所需的已注册供应商快照。

type ProviderCredentialMetadataRefresh

type ProviderCredentialMetadataRefresh interface {
	// RefreshCredentialAllowances performs only the declared allowance or balance read and preserves every unrelated metadata slice.
	// RefreshCredentialAllowances 仅执行声明的额度或余额读取，并保留所有无关元数据切片。
	RefreshCredentialAllowances(context.Context, string, string, time.Time) (catalog.Snapshot, error)
	// RefreshCredentialMetadata performs one provider read and one atomic catalog replacement.
	// RefreshCredentialMetadata 执行一次供应商读取与一次原子目录替换。
	RefreshCredentialMetadata(context.Context, string, string, time.Time) (catalog.Snapshot, error)
}

ProviderCredentialMetadataRefresh replaces every supported account metadata slice for one exact credential. ProviderCredentialMetadataRefresh 替换一个精确凭据支持的全部账号元数据切片。

type ProviderMetadataRefresh

type ProviderMetadataRefresh interface {
	// Refresh atomically replaces metadata for one exact provider instance.
	// Refresh 原子替换一个精确供应商实例的元数据。
	Refresh(context.Context, string, time.Time) (catalog.Snapshot, error)
}

ProviderMetadataRefresh refreshes provider-native plan, entitlement, and allowance snapshots. ProviderMetadataRefresh 刷新供应商原生套餐、授权与额度快照。

type ProviderMetadataRefreshScheduler

type ProviderMetadataRefreshScheduler interface {
	// Trigger queues one provider instance unless it is already pending.
	// Trigger 将一个供应商实例入队，除非它已经待处理。
	Trigger(string) bool
}

ProviderMetadataRefreshScheduler accepts deduplicated immediate refresh triggers. ProviderMetadataRefreshScheduler 接收去重后的即时刷新触发。

type ResourceDiagnostics

type ResourceDiagnostics interface {
	// ListDiagnostics returns newest resource metadata in stable order.
	// ListDiagnostics 以稳定顺序返回最新资源元数据。
	ListDiagnostics(context.Context, int) ([]resource.Resource, error)
}

ResourceDiagnostics lists management-safe metadata without resource content or private ownership fields. ResourceDiagnostics 列出不含资源正文或私有所有权字段的管理安全元数据。

type ResourceGateway

type ResourceGateway interface {
	// MaximumObjectBytes returns the decoded object ceiling used to bound request bodies.
	// MaximumObjectBytes 返回用于限制请求正文的解码对象上限。
	MaximumObjectBytes() int64
	// Create ingests one already-authorized byte stream.
	// Create 接收一个已授权字节流。
	Create(context.Context, resource.CreateInput) (resource.Resource, error)
	// ImportURL imports one validated public URL.
	// ImportURL 导入一个已校验公网 URL。
	ImportURL(context.Context, resource.URLImportInput) (resource.Resource, error)
	// ImportBase64 imports one bounded typed Base64 payload.
	// ImportBase64 导入一个受限类型化 Base64 Payload。
	ImportBase64(context.Context, resource.Base64ImportInput) (resource.Resource, error)
	// Get returns owner-scoped resource metadata.
	// Get 返回所有者作用域资源元数据。
	Get(context.Context, string, string) (resource.Resource, error)
	// OpenContent opens owner-scoped resource content.
	// OpenContent 打开所有者作用域资源内容。
	OpenContent(context.Context, string, string) (resource.Resource, io.ReadCloser, error)
	// Delete deletes one owner-scoped resource.
	// Delete 删除一个所有者作用域资源。
	Delete(context.Context, string, string) error
}

ResourceGateway is the complete authenticated resource boundary required by the HTTP server. ResourceGateway 是 HTTP 服务所需的完整已认证资源边界。

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server owns the minimal Vulcan Model Core HTTP surface. Server 管理最小化的 Vulcan Model Core HTTP 接口面。

func New

func New(catalog ProviderCatalog) (*Server, error)

New creates the minimal HTTP API without legacy protocol routes. New 创建不含旧协议路由的最小 HTTP API。

func NewWithControlPlane

func NewWithControlPlane(catalog ProviderCatalog, control ControlPlane) (*Server, error)

NewWithControlPlane creates the authenticated local management and call-plane HTTP surface. NewWithControlPlane 创建认证的本地管理和调用面 HTTP 接口面。

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns the immutable HTTP handler. Handler 返回不可变的 HTTP 处理器。

type TargetAvailability

type TargetAvailability interface {
	// Resolve returns one same-provider target or an explicit ineligibility error.
	// Resolve 返回一个同供应商 Target 或明确不合格错误。
	Resolve(context.Context, resolve.Request) (resolve.Target, resolve.Diagnostics, error)
}

TargetAvailability resolves one exact current execution destination for discovery filtering. TargetAvailability 为发现过滤解析一个精确当前执行目的地。

type UsagePreflightService

type UsagePreflightService interface {
	// Preflight returns provider-exact, Router-estimated, or explicitly unknown usage facts.
	// Preflight 返回供应商精确、Router 估算或明确未知的用量事实。
	Preflight(context.Context, string, vcp.UsagePreflightRequest) (vcp.UsagePreflightResponse, error)
}

UsagePreflightService owns side-effect-free accounting for one exact call-plane target. UsagePreflightService 拥有一个精确调用面 Target 的无副作用计量。

type XAIDeviceFlows

type XAIDeviceFlows interface {
	// Start creates one management-safe xAI verification session.
	// Start 创建一个管理安全的 xAI 验证会话。
	Start(context.Context) (providerxai.Flow, error)
	// Poll performs one bounded xAI token exchange.
	// Poll 执行一次有界 xAI Token 交换。
	Poll(context.Context, string) (providerxai.Token, error)
	// Release returns a delivered token lease when atomic onboarding fails.
	// Release 在原子录入失败时归还已交付的 Token 租约。
	Release(string)
	// Cancel consumes one incomplete or completed local authorization session.
	// Cancel 消费一个未完成或已完成的本地授权会话。
	Cancel(string)
}

XAIDeviceFlows owns transient xAI account authorization sessions without exposing provider tokens. XAIDeviceFlows 管理临时 xAI 账号授权会话且不暴露供应商 Token。