app

package
v0.0.22 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ProbeRespectBusinessPolicy = tunnel.ProbeRespectBusinessPolicy
	ProbeBypassBusinessPolicy  = tunnel.ProbeBypassBusinessPolicy
)
View Source
const (
	WebSocketMessageStartEvent  = tunnel.WebSocketMessageStartEvent
	WebSocketMessageDataEvent   = tunnel.WebSocketMessageDataEvent
	WebSocketMessageEndEvent    = tunnel.WebSocketMessageEndEvent
	WebSocketPingEvent          = tunnel.WebSocketPingEvent
	WebSocketPongEvent          = tunnel.WebSocketPongEvent
	WebSocketCloseEvent         = tunnel.WebSocketCloseEvent
	WebSocketTextMessage        = tunnel.WebSocketTextMessage
	WebSocketBinaryMessage      = tunnel.WebSocketBinaryMessage
	WebSocketCloseProtocolError = tunnel.WebSocketCloseProtocolError
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIOpen added in v0.0.16

type APIOpen struct {
	TargetAgentID string
	RouteID       uint
	RequestID     string
	Method        string
	Path          string
	Header        http.Header
	BodyLength    int64
	Remaining     time.Duration
	Hop           uint8
	API           apiattempt.APIAttemptMeta
}

type APIResponseEvent added in v0.0.16

type APIResponseEvent struct {
	Kind     APIResponseEventKind
	Headers  *tunnel.Headers
	Data     []byte
	Trailers *tunnel.Trailers
	Result   *apiattempt.APIExecutionResult
}

type APIResponseEventKind added in v0.0.16

type APIResponseEventKind uint8
const (
	APIResponseHeaders APIResponseEventKind = iota + 1
	APIResponseData
	APIResponseEnd
	APIResponseResult
)

type AgentAddress added in v0.0.13

type AgentAddress = protocol.Address

AgentAddress is the shared address value used at application boundaries.

type AgentApplication

type AgentApplication interface {
	GetCache() AgentCache
	GetBodyStore() BodyStore
	GetLogger() *zap.Logger
	GetConfig() *config.AgentRuntimeConfig
	GetTransportPool() TransportPool
	RelayTimeout() time.Duration // 非流式请求的总超时;0 表示不限
}

AgentApplication 是 agent 端专用服务容器,跟 Application 并列存在于 RelayContext。 Relay pipeline 通过此接口拿到 cache / logger / config / transport pool, 避免把整个 *Handler 当参数到处传,方便测试时 stub 单个依赖。

type AgentCache

type AgentCache interface {
	Store
	FindTokenRoute(tokenID uint, realModel string) *models.AgentRoute
	FindAdminChannelRoute(channelID uint, realModel string) *models.AgentRoute
	EffectiveRequestLimiters(userID, groupID uint) []*models.RequestLimiter
	EffectiveAttemptLimiters(userID, groupID uint, src string, channelID uint) []*models.RequestLimiter
}

AgentCache 在 Store 基础上加 relay 需要的 route 查询能力。 嵌入 Store 是为了让 relay 路径既能查 Token / Channel / ModelConfig, 也能查 AgentRoute,不必持有两个对象。

type AgentRuntime

type AgentRuntime struct {
	Uptime            int64 `json:"uptime"`
	CachedTokens      int   `json:"cached_tokens"`
	CachedChannels    int   `json:"cached_channels"`
	CachedModels      int   `json:"cached_models"`
	ActiveConnections int   `json:"active_connections"`
	Version           int64 `json:"version"`
	MasterVersion     int64 `json:"master_version"`
}

AgentRuntime Agent 运行时信息 包含 Agent 的缓存状态、连接数、版本等运行时数据

type AgentSelector added in v0.0.13

type AgentSelector struct {
	AgentID  string
	AgentTag string
}

AgentSelector identifies exactly one agent or one agent tag.

type AgentServer

type AgentServer interface {
	Run() error
	RunBackground(ctx context.Context)
	Shutdown(ctx context.Context) error
	MountRoutes(router *gin.Engine)
	GetRelayLink() RelayLink
}

AgentServer Agent 数据面服务器 负责请求中继、配置缓存同步、指标上报等数据面功能

type Application

type Application interface {
	GetCoreDB() *gorm.DB
	SetCoreDB(*gorm.DB)
	GetLogDB() *gorm.DB
	SetLogDB(*gorm.DB)
	GetDatabaseLayoutMode() DatabaseLayoutMode
	SetDatabaseLayoutMode(DatabaseLayoutMode)
	GetMasterSettings() *MasterSettingsSnapshot
	GetMasterServer() MasterServer
	SetMasterServer(MasterServer)
	GetHub() Hub
	SetHub(Hub)
	GetPublisher() Publisher
	SetPublisher(Publisher)
	GetSettler() Settler
	SetSettler(Settler)
	GetQuotaChecker() QuotaChecker
	SetQuotaChecker(QuotaChecker)
	GetAgentServer() AgentServer
	SetAgentServer(AgentServer)
	GetStore() Store
	SetStore(Store)
	GetSyncer() Syncer
	SetSyncer(Syncer)
	GetWSBridge() WSBridge
	SetWSBridge(WSBridge)
	GetRelayHandler() RelayHandler
	SetRelayHandler(RelayHandler)
	GetReporter() Reporter
	SetReporter(Reporter)
	GetEventBus() EventBus
	SetEventBus(EventBus)
	GetWSClient() WSClient
	SetWSClient(WSClient)
}

Application 是整个应用的顶层容器接口 统一管理 Master 和 Agent 侧的所有组件,通过 Get/Set 方法实现依赖注入 LogDB 支持后台 connector 原子替换,MasterSettings 支持运行期原子发布; 其余依赖仅在初始化阶段 Set。

func NewApplication

func NewApplication() Application

type AttemptStream added in v0.0.14

type AttemptStream interface {
	Commit(ctx context.Context) error
	Upload(ctx context.Context, src io.Reader) error
	CopyAttemptResponse(ctx context.Context, dst http.ResponseWriter) (attemptwire.AttemptProxyResult, error)
	CommitState() tunnel.CommitState
	Cancel(cause error)
	Close() error
}

type AttemptStreamOpener added in v0.0.14

type AttemptStreamOpener interface {
	OpenAttemptStream(context.Context, AttemptStreamRequest) (AttemptStream, error)
}

type AttemptStreamRequest added in v0.0.14

type AttemptStreamRequest struct {
	TargetAgentID string
	RouteID       uint
	RequestID     string
	Method        string
	Path          string
	Header        http.Header
	BodyLength    int64
	Remaining     time.Duration
	Hop           uint8
	Attempt       attemptwire.AttemptProxyMeta
}

type BodyLimits added in v0.0.13

type BodyLimits struct {
	MemoryThreshold int64
	HardLimit       int64
}

type BodyStore added in v0.0.13

type BodyStore interface {
	Capture(ctx context.Context, src io.Reader, limits BodyLimits) (ReplayBody, error)
}

type Context

type Context struct {
	*gin.Context

	App          Application
	UserInfo     *UserInfo
	Logger       *zap.Logger
	Settings     *config.MasterRuntimeConfig
	OwnerContext context.Context
}

Context 承载请求级别的数据和全局共享服务。

func NewContext

func NewContext(c *gin.Context, settings *config.MasterRuntimeConfig, logger *zap.Logger, application Application) *Context

func (*Context) GetBus

func (c *Context) GetBus() EventBus

GetBus 从应用容器获取事件总线,App 为 nil 时返回 nil。

func (*Context) RequestContext added in v0.0.13

func (c *Context) RequestContext() context.Context

type DatabaseLayoutMode added in v0.0.14

type DatabaseLayoutMode uint32

DatabaseLayoutMode controls database routing explicitly during the split rollout. The zero value preserves the legacy single-database deployment.

const (
	DatabaseLayoutLegacySingle DatabaseLayoutMode = iota
	DatabaseLayoutSplit
)

func (DatabaseLayoutMode) Validate added in v0.0.14

func (m DatabaseLayoutMode) Validate() error

type EventBus

type EventBus interface {
	Publish(ctx context.Context, event eventbus.Event) error
	Subscribe(topic string, handler eventbus.EventHandler) (eventbus.Subscription, error)
	SubscribePattern(pattern string, handler eventbus.EventHandler) (eventbus.Subscription, error)
	Close() error
}

EventBus 事件总线接口 — 所有核心接口的规范定义位于 app 包。

type HTTPAPIProtocolError added in v0.0.16

type HTTPAPIProtocolError struct {
	Stage string
	Code  string
}

func (*HTTPAPIProtocolError) Error added in v0.0.16

func (e *HTTPAPIProtocolError) Error() string

type HTTPAPIStream added in v0.0.16

type HTTPAPIStream interface {
	Open(context.Context, APIOpen) error
	SendRequestData(context.Context, []byte) error
	EndRequest(context.Context, tunnel.Trailers) error
	Receive(context.Context) (APIResponseEvent, error)
	Cancel(cause error)
	Close() error
}

HTTPAPIStream is the Source-side consumer contract for one Generic API attempt. Open completes the Tunnel Ready/Commit handshake before request data may be sent. Receive preserves Headers/Data/End/Result wire order.

type HTTPAPIStreamOpener added in v0.0.16

type HTTPAPIStreamOpener interface {
	OpenHTTPAPIStream(context.Context, APIOpen) (HTTPAPIStream, error)
}

type Hub

type Hub interface {
	// HandleWS 处理 Agent 的 WebSocket 连接请求
	HandleWS(c *gin.Context)
	// Call 向指定 Agent 发起 RPC 调用并等待响应
	Call(agentID string, method string, params any, timeout time.Duration) (json.RawMessage, error)
	// Broadcast 向所有在线 Agent 广播通知
	Broadcast(method string, params any)
	// GetOnlineAgentIDs 获取所有在线 Agent 的 ID 列表
	GetOnlineAgentIDs() []string
	// GetRuntime 获取指定 Agent 的运行时信息(心跳、延迟等)
	GetRuntime(agentID string) *AgentRuntime
	// IsOnline 检查指定 Agent 是否在线
	IsOnline(agentID string) bool
	// GetAgentAddresses 获取 Agent 的合并地址列表(配置地址 + 自动探测地址)
	GetAgentAddresses(agentID string, dbHTTPAddrs string) []AgentAddress
	// ConnectedAgents 返回当前在线的 Agent 数量
	ConnectedAgents() int
}

Hub WebSocket 连接管理中心 Master 端用于管理所有 Agent 的 WebSocket 连接,支持 RPC 调用、广播和在线状态查询

type MasterServer

type MasterServer interface {
	Run() error
	Shutdown(ctx context.Context) error
	InitAdminUser(username, password string) error
}

MasterServer Master 控制面服务器 负责管理 API、WebSocket Hub、计费结算等控制面功能

type MasterSettingsSnapshot added in v0.0.15

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

MasterSettingsSnapshot stores master-only settings for request hot paths. Published maps are immutable; readers load one pointer without taking a lock.

func NewMasterSettingsSnapshot added in v0.0.15

func NewMasterSettingsSnapshot() *MasterSettingsSnapshot

func (*MasterSettingsSnapshot) Lookup added in v0.0.15

func (s *MasterSettingsSnapshot) Lookup(key string) (string, bool)

func (*MasterSettingsSnapshot) LookupBool added in v0.0.15

func (s *MasterSettingsSnapshot) LookupBool(key string, fallback bool) bool

func (*MasterSettingsSnapshot) Replace added in v0.0.15

func (s *MasterSettingsSnapshot) Replace(values map[string]string)

Replace atomically publishes a complete clone of values.

func (*MasterSettingsSnapshot) Update added in v0.0.15

func (s *MasterSettingsSnapshot) Update(values map[string]string)

Update atomically merges values into the current snapshot. CAS preserves disjoint updates when multiple writers publish concurrently.

type NotificationHandler

type NotificationHandler func(ctx context.Context, params json.RawMessage) (any, error)

NotificationHandler 处理 JSON-RPC 通知的回调函数。

type ProbePolicy added in v0.0.14

type ProbePolicy = tunnel.ProbePolicy

type ProbeStream added in v0.0.14

type ProbeStream interface {
	Commit(ctx context.Context) error
	Upload(ctx context.Context, src io.Reader) error
	CopyResponse(ctx context.Context, dst http.ResponseWriter) error
	CommitState() tunnel.CommitState
	Cancel(cause error)
	Close() error
}

type ProbeStreamOpener added in v0.0.14

type ProbeStreamOpener interface {
	OpenProbeStream(context.Context, ProbeStreamRequest) (ProbeStream, error)
}

type ProbeStreamRequest added in v0.0.14

type ProbeStreamRequest struct {
	TargetAgentID string
	RequestID     string
	Remaining     time.Duration
	Policy        ProbePolicy
}

type Publisher

type Publisher interface {
	// Start 启动推送监听
	Start()
}

Publisher 配置变更推送器 监听事件总线上的配置变更事件,通过 Hub 将增量更新推送给所有在线 Agent

type QuotaChecker

type QuotaChecker interface {
	Start()
}

QuotaChecker 额度检查器 定期检查用户额度使用情况,对超额用户进行处理

type RelayHandler

type RelayHandler interface {
	Relay(c *gin.Context)
}

RelayHandler 请求中继处理器 Agent 端的核心组件,负责接收客户端 API 请求,通过 Codec 转换协议后转发到上游服务商

type ReplayBody added in v0.0.13

type ReplayBody interface {
	Size() int64
	Open() (io.ReadCloser, error)
	Bytes(limit int64) ([]byte, error)
	Close() error
}

type Reporter

type Reporter interface {
	Start(ctx context.Context) error
	Stop()
	SetClient(client WSClient)
	PendingCount() int
}

Reporter 使用量指标上报器 Agent 端组件,收集 API 请求的使用量数据(token 消耗、模型、耗时等), 批量聚合后通过 WebSocket 上报给 Master

type ResourceCounts added in v0.0.13

type ResourceCounts struct {
	LifecycleWorkers int64
	HTTPHandlers     int64
	AcceptedSockets  int64
	ControlSessions  int64
	ControlHandlers  int64
	ControlSockets   int64
	RelayCandidates  int64
	RelayActive      int64
	RelayDraining    int64
	RelayStreams     int64
	CacheLoads       int64
	CacheRefreshes   int64
	ReporterWorkers  int64
	Inflight         int64
	Timers           int64
	Transports       int64
	RelaySockets     int64

	DirectOutgoingActive     int64
	DirectOutgoingCandidates int64
	DirectOutgoingDraining   int64
	DirectIncomingActive     int64
	DirectIncomingCandidates int64
	DirectIncomingDraining   int64
	DirectStreams            int64
	DirectSockets            int64
}

type RoutePath added in v0.0.13

type RoutePath string
const (
	RoutePathDirect RoutePath = "direct"
	RoutePathRelay  RoutePath = "relay"
	RoutePathLocal  RoutePath = "local"
)

type Settler

type Settler interface {
	Start()
	Settle(ctx context.Context, agentID string, logs []protocol.UsageLogEntry)
}

Settler 计费结算器 监听 Agent 上报的使用量数据,计算费用并更新用户额度

type Store

type Store interface {
	// --- Token 操作 ---
	GetToken(ctx context.Context, key string) *models.Token
	SetToken(token *models.Token)
	DeleteToken(key string)
	GetTokenByID(ctx context.Context, id uint) *models.Token
	DeleteTokenByID(id uint)
	LoadTokens(tokens []models.Token)
	TokenCount() int

	// --- Channel 操作 ---
	GetChannel(id uint) *models.Channel
	SetChannel(ch *models.Channel)
	DeleteChannel(id uint)
	LoadChannels(channels []models.Channel)
	ChannelCount() int

	// --- ModelConfig 操作 ---
	GetModelConfig(modelName string) *models.ModelConfig
	SetModelConfig(mc *models.ModelConfig)
	DeleteModelConfig(modelName string)
	LoadModelConfigs(configs []models.ModelConfig)
	ModelConfigCount() int

	// --- 模型路由 ---
	GetChannelsForModel(model string) []*models.Channel
	RebuildModelIndex()
	GetAllModelNames() []string

	// --- User 操作 ---
	GetUser(ctx context.Context, id uint) *protocol.SyncedUser
	SetUserQuota(id uint, quota int64) // 更新已缓存 user 的 Quota;不在缓存则忽略

	// --- BYOK 私有 channel ---
	GetVisiblePrivateChannelsForUser(userID uint, model string) []*protocol.SyncedPrivateChannel
	ListVisibleBYOKModelNamesForUser(userID uint) []string // 列举 user 全部 enabled BYOK channel 的 Models 并集(去重)

	// --- Agent 操作 ---
	GetAgent(agentID string) *models.Agent
	SetAgent(agent *models.Agent)
	UpdateAgentAutoAddresses(agentID string, addrs []AgentAddress)
	DeleteAgent(agentID string)
	GetAgentsByTag(tag string) []*models.Agent
	GetAllAgents() []*models.Agent
	LoadAgents(agents []models.Agent)
	AgentCount() int

	// --- 版本与设置 ---
	Version() int64
	SetVersion(v int64)
	LoadSettings(s []models.Setting)
	Settings() settings.AgentSettings
	TraceMaxBodySize() int
	FallbackSleepMs() int

	// --- 系统 Token ---
	GetSystemTestToken() *models.Token

	// --- 事件处理 ---
	HandleSyncEvent(entity, action string, data []byte)
}

Store 本地配置缓存 Agent 端用于缓存从 Master 同步的 Token、Channel、Model 等配置数据, 支持增量更新和全量加载

type Syncer

type Syncer interface {
	SetClient(client WSClient)
	FullSync(ctx context.Context) error
	SubscribeEvents() error
	StartPeriodicCheck(ctx context.Context)
}

Syncer 缓存同步器 负责与 Master 建立连接,拉取全量配置并订阅增量事件,保持本地缓存与 Master 一致

type TransportPool

type TransportPool interface {
	Get(ch *models.Channel) *http.Transport
	Invalidate(channelID uint, oldProxyURL string)
	CloseIdleConnections()
}

TransportPool 抽象 channel → *http.Transport 缓存能力。 让 relay 在多次 upstream 请求间共享连接池,避免每次 new(http.Transport)。

Invalidate 用于 channel.ProxyURL 变更时让旧 transport 失效; server.go 在装配阶段通过 Store.OnChannelChange 回调调用。

type UserInfo

type UserInfo struct {
	UserID            uint
	Username          string
	DisplayName       string // JWT claim ClaimDisplayName,SSO 注册时由 IdP 同步,可空
	AvatarURL         string // JWT claim ClaimAvatarURL,SSO 注册时由 IdP 同步,可空
	Role              int
	TokenID           uint // API Token 认证时填充,JWT 登录时为 0
	TokenName         string
	TraceEnabled      bool                  // Agent 侧:Token 是否开启 trace
	TraceMode         models.TokenTraceMode // Agent 侧:Token 成功请求的 trace 捕获范围
	BYOKOnly          bool                  // Agent 侧:Token 是否限定只用 BYOK/私有渠道
	APIRoleMode       models.APIRoleMode    // Agent 侧:Generic API 权限事实取 Token 还是 User effective RoleSet
	TokenModels       []string              // Agent 侧:Token 允许的模型列表(空表示不限)
	AllowedChannelIDs []uint                // Agent 侧:Token 允许的频道列表(空表示不限)

	// 新增:来自该用户所在 Group
	GroupID                uint
	GroupModels            []string
	GroupAllowedChannelIDs []uint
}

UserInfo 承载认证用户身份信息,在应用内流转。

type WSBridge

type WSBridge interface {
	Start()
}

WSBridge WebSocket 同步桥 监听 WebSocket 连接上的消息,将 Master 推送的增量更新转发给 Store 处理

type WSClient

type WSClient interface {
	// OnNotification 注册指定方法的通知回调处理器
	OnNotification(method string, handler NotificationHandler)
	// Call 发起 RPC 调用并等待响应
	Call(ctx context.Context, method string, params any) (json.RawMessage, error)
	// Notify 发送单向通知(不等待响应)
	Notify(method string, params any) error
	// Close 关闭 WebSocket 连接
	Close() error
	// ReadLoop 启动消息读取循环(通常在 goroutine 中运行)
	ReadLoop()
}

WSClient WebSocket 客户端 封装 WebSocket 连接,提供 JSON-RPC 风格的 Call(请求-响应)和 Notify(单向通知)能力

type WSConn

type WSConn interface {
	// SendNotification 向客户端发送 JSON-RPC 通知
	SendNotification(method string, params any) error
	// SendResponse 向客户端发送 JSON-RPC 响应
	SendResponse(resp *jsonrpc.Response) error
	// ReadMessage 读取一条消息,区分请求和响应
	ReadMessage() (*jsonrpc.Request, *jsonrpc.Response, error)
	// WriteJSON 发送任意 JSON 数据
	WriteJSON(v any) error
	// Close 关闭连接
	Close() error
	// Done 返回连接关闭的通知 channel
	Done() <-chan struct{}
}

WSConn WebSocket 服务端连接 封装单个 WebSocket 连接的服务端视角,提供消息读写和生命周期管理

type WebSocketAPIStream added in v0.0.16

type WebSocketAPIStream interface {
	Open(context.Context, WebSocketOpen) (WebSocketAccepted, error)
	ProviderAcceptance() WebSocketAccepted
	SendEvent(context.Context, WebSocketEvent) error
	ReceiveEvent(context.Context) (WebSocketEvent, error)
	ReceiveResult(context.Context) (apiattempt.APIExecutionResult, error)
	Close() error
}

WebSocketAPIStream is the source-side transport contract for one Generic API WebSocket. Events preserve message boundaries; data events may be fragmented at the negotiated tunnel data limit.

type WebSocketAPIStreamOpener added in v0.0.16

type WebSocketAPIStreamOpener interface {
	OpenWebSocketAPIStream(context.Context, WebSocketOpen) (WebSocketAPIStream, error)
}

type WebSocketAccepted added in v0.0.16

type WebSocketAccepted = tunnel.WebSocketAccepted

type WebSocketEvent added in v0.0.16

type WebSocketEvent = tunnel.WebSocketEvent

type WebSocketEventKind added in v0.0.16

type WebSocketEventKind = tunnel.WebSocketEventKind

type WebSocketExecutionError added in v0.0.16

type WebSocketExecutionError struct {
	Result apiattempt.APIExecutionResult
	Err    error
}

func (*WebSocketExecutionError) Error added in v0.0.16

func (e *WebSocketExecutionError) Error() string

func (*WebSocketExecutionError) Unwrap added in v0.0.16

func (e *WebSocketExecutionError) Unwrap() error

type WebSocketOpen added in v0.0.16

type WebSocketOpen struct {
	TargetAgentID string
	RouteID       uint
	RequestID     string
	Path          string
	Header        http.Header
	Remaining     time.Duration
	Hop           uint8
	API           apiattempt.APIAttemptMeta
}

type WebSocketRejection added in v0.0.16

type WebSocketRejection = tunnel.WebSocketRejection

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL