protocol

package
v0.0.10 Latest Latest
Warning

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

Go to latest
Published: Jun 28, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

internal/pkg/protocol/sync_routing.go

internal/pkg/protocol/sync_user.go

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CacheEntityStats

type CacheEntityStats struct {
	Kind          string           `json:"kind,omitempty"` // "lru" | "index";旧 agent 上报空串,前端按 lru 兜底
	Hits          int64            `json:"hits"`
	Misses        int64            `json:"misses"`
	Evictions     int64            `json:"evictions"`
	NegativeHits  int64            `json:"negative_hits"`
	LoadErrors    int64            `json:"load_errors"`
	Invalidations int64            `json:"invalidations"`
	Size          int              `json:"size"`
	Capacity      int              `json:"capacity"`
	Extra         map[string]int64 `json:"extra,omitempty"` // 索引细分,如 {"limiters":12,"bindings":30}
}

CacheEntityStats 是单个实体缓存的运行统计。 LRU 模式实体上报全字段;Full 模式实体仅 Size 有意义、其他字段为 0。

type FetchEntityRequest

type FetchEntityRequest struct {
	Entity string `json:"entity"`
	Key    string `json:"key"`
}

FetchEntityRequest 是 sync.fetchEntity 的入参。 Entity 取 events.Entity* 常量;Key 由各实体 handler 解读 (token: API key 字符串;user: id 字符串)。

type FetchEntityResponse

type FetchEntityResponse struct {
	Found bool            `json:"found"`
	Data  json.RawMessage `json:"data,omitempty"`
	Side  json.RawMessage `json:"side,omitempty"`
}

FetchEntityResponse 是 sync.fetchEntity 的响应。 Found=false 表示 master 也未查到;调用方应进入负缓存。 Side 是可选旁路负载(如 token 响应附带的 SyncedUser),由 agent 端 fetcher 解读。

type ForceFullSyncResponse

type ForceFullSyncResponse struct {
	Version    int64 `json:"version"`
	DurationMs int64 `json:"duration_ms"`
}

type FullSyncRequest

type FullSyncRequest struct {
	Entity   string `json:"entity"`
	Page     int    `json:"page"`
	PageSize int    `json:"page_size"`
}

type FullSyncResponse

type FullSyncResponse struct {
	Items   []byte `json:"items"`
	Total   int64  `json:"total"`
	Page    int    `json:"page"`
	HasMore bool   `json:"has_more"`
	Version int64  `json:"version"`
}

type GetVersionResponse

type GetVersionResponse struct {
	Version int64 `json:"version"`
}

type HeartbeatParams

type HeartbeatParams struct {
	Uptime               int64 `json:"uptime"`
	CachedTokens         int   `json:"cached_tokens"`
	CachedChannels       int   `json:"cached_channels"`
	CachedModels         int   `json:"cached_models"`
	CachedGlobalRoutings int   `json:"cached_global_routings"`
	CachedUserRoutings   int   `json:"cached_user_routings"`
	ActiveConnections    int   `json:"active_connections"`
	Version              int64 `json:"version"`

	HTTPAddresses json.RawMessage `json:"http_addresses,omitempty"`
	Tags          string          `json:"tags,omitempty"`
	ProxyURL      string          `json:"proxy_url,omitempty"`
	ListenPort    int             `json:"listen_port,omitempty"`

	CacheStats map[string]CacheEntityStats `json:"cache_stats,omitempty"`
}

type LimiterBucketStat added in v0.0.8

type LimiterBucketStat struct {
	LimiterID   uint   `json:"limiter_id"`
	Name        string `json:"name"`
	Bucket      string `json:"bucket"`
	Metric      string `json:"metric"` // concurrency | rate
	KeyBy       string `json:"key_by"`
	Occupied    int64  `json:"occupied"` // 并发:当前占用; 速率:当前窗口已用
	Capacity    int64  `json:"capacity"`
	Waiters     int64  `json:"waiters"`
	WindowEndMs int64  `json:"window_end_ms"` // 速率桶本窗口复位时刻(unix ms);并发为 0
}

LimiterBucketStat 是一个 (限流器,桶) 的实时仪表读数。agent 采样 + join 规则元数据后上报。

type PrivateChannelInvalidatePayload added in v0.0.2

type PrivateChannelInvalidatePayload struct {
	Action          string `json:"action"` // "invalidate"
	AffectedUserIDs []uint `json:"affected_user_ids"`
}

PrivateChannelInvalidatePayload is the WS push notification fired after CRUD / share changes. Master expands (owner ∪ share.targets) into the affected_user_ids list; agent only sees the post-expansion user list and invalidates each user's cache block (no incremental merge).

type RoutingMember

type RoutingMember struct {
	Ref      string `json:"ref"`
	Priority int    `json:"priority"`
	Weight   int    `json:"weight"`
}

RoutingMember 与 models.RoutingMember 字段一致。protocol 包独立定义避免反向依赖 models 包。

type SyncPushParams

type SyncPushParams struct {
	Entity  string `json:"entity"`
	Action  string `json:"action"`
	Data    []byte `json:"data"`
	Version int64  `json:"version"`
}

type SyncedPrivateChannel added in v0.0.2

type SyncedPrivateChannel struct {
	models.ChannelCore

	OwnerID      uint              `json:"owner_id"`
	KeyPlaintext string            `json:"key"`
	Models       []string          `json:"models"`
	ModelMapping map[string]string `json:"model_mapping"`
}

SyncedPrivateChannel is the projection of a PrivateChannel that master pushes to agent over WS sync. KeyPlaintext is the master-decrypted key; agent never holds the KEK. HeaderOverride / ProxyURL never appear here (PrivateChannel schema does not include those columns).

Scalar fields shared with models.PrivateChannel come from the embedded ChannelCore. BYOK-projection-only fields (KeyPlaintext, OwnerID, plus the downstream-friendly Models / ModelMapping types) stay on the outer struct.

type SyncedRouting

type SyncedRouting struct {
	ID      uint            `json:"id"`
	Name    string          `json:"name"`
	Scope   string          `json:"scope"`
	UserID  uint            `json:"user_id"`
	Members []RoutingMember `json:"members"`
	Enabled bool            `json:"enabled"`
}

SyncedRouting 是 master 推送给 agent 的 ModelRouting 投影。 与 models.ModelRouting 保持字段对等,但脱离 GORM 依赖(agent 端不需要持久化)。

type SyncedUser

type SyncedUser struct {
	ID      uint  `json:"id"`
	GroupID uint  `json:"group_id"`
	Quota   int64 `json:"quota"`
}

SyncedUser 是 master 推送给 agent 的精简 User 投影。 只包含鉴权和配额所需字段,不暴露 Password / Username。

type UsageLogEntry

type UsageLogEntry struct {
	RequestID        string `json:"request_id"`
	UserID           uint   `json:"user_id"`
	TokenID          uint   `json:"token_id"`
	ChannelID        uint   `json:"channel_id"`
	PrivateChannelID uint   `json:"private_channel_id"`
	OwnerType        string `json:"owner_type"`
	ModelName        string `json:"model_name"`
	PromptTokens     int    `json:"prompt_tokens"`
	CompletionTokens int    `json:"completion_tokens"`
	IsStream         bool   `json:"is_stream"`
	Duration         int    `json:"duration"`
	ClientIP         string `json:"client_ip"`
	Timestamp        int64  `json:"timestamp"`

	// Enhanced logging fields
	TokenName        string `json:"token_name"`
	UpstreamModel    string `json:"upstream_model"`
	FirstResponseMs  int    `json:"first_response_ms"`
	CacheReadTokens  int    `json:"cache_read_tokens"`
	CacheWriteTokens int    `json:"cache_write_tokens"`
	InboundProtocol  string `json:"inbound_protocol"`
	OutboundProtocol string `json:"outbound_protocol"`
	UseLegacy        bool   `json:"use_legacy"`
	Status           int    `json:"status"`
	ErrorMessage     string `json:"error_message,omitempty"`
	TraceData        string `json:"trace_data,omitempty"`
	Other            string `json:"other"`
	TokenSource      string `json:"token_source,omitempty"`
	RoutingName      string `json:"routing_name,omitempty"`

	// Channel affinity(渠道缓存粘性)
	AffinityStatus   string `json:"affinity_status,omitempty"` // "hit" | "fallback" | "none" | ""
	AffinityRecorded bool   `json:"affinity_recorded,omitempty"`

	ErrorStage         string `json:"error_stage,omitempty"`
	InboundDecodeMs    int    `json:"inbound_decode_ms,omitempty"`
	OutboundEncodeMs   int    `json:"outbound_encode_ms,omitempty"`
	UpstreamDispatchMs int    `json:"upstream_dispatch_ms,omitempty"`
	UpstreamDecodeMs   int    `json:"upstream_decode_ms,omitempty"`
	ClientEncodeMs     int    `json:"client_encode_ms,omitempty"`

	// PriceRatio 是 relay 选中的公共 channel 在请求时刻的计费倍率快照。
	// 零值 0(旧 agent 未发 / channel 未配)= 原价,settler 归一到 1.0。
	PriceRatio float64 `json:"price_ratio,omitempty"`

	// Free 是 relay 选中的公共 channel 在请求时刻的"免费渠道"标记快照。
	// private 行不填,保持 false。settler 见 true 则四桶成本清零。
	Free bool `json:"free,omitempty"`

	// FallbackChain 是本次请求的候选链路(每候选一条);空表示无链路信息。
	FallbackChain []models.AttemptRecord `json:"fallback_chain,omitempty"`
	// AttemptTraces 是逐候选 mask 过的 header/body trace,index 对应 FallbackChain 的 Seq-1。
	// AttemptIndex assigned by settler from slice order until Task 5 adds the field.
	AttemptTraces []models.UsageLogTrace `json:"attempt_traces,omitempty"`

	// 限流决策(请求级 limiter):Decision/WaitMs/Reason 标量 + Hits 命中明细。
	// 无命中时全为零值/空,omitempty 不上报。
	RateLimitDecision string                `json:"rate_limit_decision,omitempty"`
	RateLimitWaitMs   int                   `json:"rate_limit_wait_ms,omitempty"`
	RateLimitReason   string                `json:"rate_limit_reason,omitempty"`
	RateLimitHits     []models.RateLimitHit `json:"rate_limit_hits,omitempty"`
}

type UsageReport

type UsageReport struct {
	AgentID string          `json:"agent_id"`
	Logs    []UsageLogEntry `json:"logs"`
}

type UserQuotaSync added in v0.0.8

type UserQuotaSync struct {
	AgentID string       `json:"agent_id"`
	Users   []SyncedUser `json:"users"`
}

UserQuotaSync 是 master 结算后定向回送给来源 agent 的余额更新。

type UserRoutingMap

type UserRoutingMap struct {
	Routings map[string]*SyncedRouting `json:"routings"`
}

UserRoutingMap 是单个用户的 routing 集合(name → routing), 按用户整体存取,避免每条 user routing 单独缓存。 放在 protocol 包是因为 loaders 与 cache 都需要引用此类型, 而 loaders 包不能反向 import cache。

type VisiblePrivateChannelSet added in v0.0.2

type VisiblePrivateChannelSet struct {
	UserID   uint                   `json:"user_id"`
	Channels []SyncedPrivateChannel `json:"channels"`
}

VisiblePrivateChannelSet is the entire block returned to agent on LRU miss: all private channels visible to the requesting user, with plaintext keys injected.

Jump to

Keyboard shortcuts

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