protocol

package
v0.0.15 Latest Latest
Warning

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

Go to latest
Published: Aug 2, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

internal/pkg/protocol/sync_routing.go

internal/pkg/protocol/sync_user.go

Index

Constants

View Source
const (
	ProbeRespectBusinessPolicy = wire.ProbeRespectBusinessPolicy
	ProbeBypassBusinessPolicy  = wire.ProbeBypassBusinessPolicy
)
View Source
const (
	FullSyncMaxPageSize             = 500
	AgentFullSyncSnapshotContractV1 = "agent_full_sync_v1"
	AgentCapabilitiesMaxCount       = 32
	AgentCapabilityMaxLength        = 64
	AgentAuthSigningKeysMaxCount    = 8
	AgentAuthKeyIDMaxLength         = 128
	AgentAuthAlgorithmEdDSA         = "EdDSA"
	AgentCapabilityTunnelV2         = "agent_tunnel_v2"
	AgentCapabilityForwardV1        = "agent_forward_ticket_v1"
	AgentCapabilityDirectTunnelV1   = "agent_direct_tunnel_v1"
	AgentCapabilityRelayHTTPPingV1  = "agent_relay_http_ping_v1"
	AgentCapabilityTokenRoutingV1   = "agent_token_routing_v1"
)
View Source
const TokenFetchSideSchemaV1 = 1

Variables

This section is empty.

Functions

func NormalizeAgentCapabilities added in v0.0.13

func NormalizeAgentCapabilities(capabilities []string) []string

Types

type Address added in v0.0.13

type Address struct {
	URL string `json:"url"`
	Tag string `json:"tag"`
}

Address is the shared agent HTTP address value used by probe and routing APIs.

type AgentCapabilitiesUpdate added in v0.0.13

type AgentCapabilitiesUpdate struct {
	AgentID      string   `json:"agent_id"`
	Capabilities []string `json:"capabilities"`
}

type AgentDirectAddressesUpdate added in v0.0.13

type AgentDirectAddressesUpdate struct {
	MasterInstanceID  string    `json:"master_instance_id"`
	AgentID           string    `json:"agent_id"`
	SessionGeneration uint64    `json:"session_generation"`
	Sequence          uint64    `json:"sequence"`
	HTTPAddresses     []Address `json:"http_addresses"`
}

AgentDirectAddressesUpdate carries one ordered auto-detected address change. Manual addresses remain part of the authoritative Agent configuration.

type AuthBootstrapResponse added in v0.0.13

type AuthBootstrapResponse struct {
	MasterInstanceID string                `json:"master_instance_id"`
	Capabilities     []string              `json:"capabilities"`
	SigningKeys      []agentauth.PublicKey `json:"signing_keys"`
}

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 DirectProbeResult added in v0.0.13

type DirectProbeResult struct {
	TargetAgentID      string      `json:"target_agent_id"`
	AddressFingerprint string      `json:"address_fingerprint"`
	Network            string      `json:"network"`
	Identity           string      `json:"identity"`
	Eligible           bool        `json:"eligible"`
	LatencyMS          int64       `json:"latency_ms"`
	CheckedAt          int64       `json:"checked_at"`
	ReasonCode         string      `json:"reason_code,omitempty"`
	Stage              string      `json:"stage,omitempty"`
	Policy             ProbePolicy `json:"policy"`
	PolicyDisabled     bool        `json:"policy_disabled"`
	PolicyReasonCode   string      `json:"policy_reason_code,omitempty"`
}

type DirectProbeTarget added in v0.0.13

type DirectProbeTarget struct {
	TargetAgentID      string      `json:"target_agent_id"`
	Addresses          []Address   `json:"addresses"`
	EffectiveProxy     string      `json:"effective_proxy"`
	AddressFingerprint string      `json:"address_fingerprint"`
	TargetGeneration   uint64      `json:"target_generation"`
	Policy             ProbePolicy `json:"policy"`
}

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,omitempty"`
	PageSize      int    `json:"page_size"`
	AfterID       uint   `json:"after_id,omitempty"`
	SnapshotMaxID uint   `json:"snapshot_max_id,omitempty"`
	BaseVersion   int64  `json:"base_version,omitempty"`
}

type FullSyncResponse

type FullSyncResponse struct {
	Items            []byte `json:"items"`
	Total            int64  `json:"total"`
	Page             int    `json:"page,omitempty"`
	HasMore          bool   `json:"has_more"`
	Version          int64  `json:"version"`
	Keyset           bool   `json:"keyset,omitempty"`
	LastID           uint   `json:"last_id,omitempty"`
	SnapshotMaxID    uint   `json:"snapshot_max_id,omitempty"`
	BaseVersion      int64  `json:"base_version,omitempty"`
	SnapshotContract string `json:"snapshot_contract,omitempty"`
}

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"`
	PendingUsage         int           `json:"pending_usage,omitempty"`
	Capabilities         []string      `json:"capabilities,omitempty"`
	Relay                *RelayRuntime `json:"relay,omitempty"`

	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 ManualProbeProgress added in v0.0.13

type ManualProbeProgress struct {
	ProbeID     string `json:"probe_id"`
	State       string `json:"state"`
	TargetTotal int    `json:"target_total"`
	Remaining   int    `json:"remaining"`
	StartedAt   int64  `json:"started_at,omitempty"`
	CompletedAt int64  `json:"completed_at,omitempty"`
}

type OperationAck added in v0.0.13

type OperationAck struct {
	OperationID string `json:"operation_id"`
	State       string `json:"state"`
	SnapshotSeq uint64 `json:"snapshot_seq"`
}

type OperationRequest added in v0.0.13

type OperationRequest struct {
	AgentID                   string `json:"agent_id"`
	Operation                 string `json:"operation"`
	TargetAgentID             string `json:"target_agent_id,omitempty"`
	RequestID                 string `json:"request_id,omitempty"`
	ExpectedEpoch             string `json:"expected_epoch"`
	ExpectedControlGeneration uint64 `json:"expected_control_generation,omitempty"`
	ExpectedRelayGeneration   uint64 `json:"expected_relay_generation,omitempty"`
}

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 ProbeAck added in v0.0.13

type ProbeAck struct {
	ProbeID         string     `json:"probe_id"`
	ProbeGeneration uint64     `json:"probe_generation"`
	Scope           ProbeScope `json:"scope"`
	State           string     `json:"state"`
	TargetTotal     int        `json:"target_total"`
	SnapshotSeq     uint64     `json:"snapshot_seq"`
}

type ProbePolicy added in v0.0.14

type ProbePolicy = wire.ProbePolicy

type ProbeScope added in v0.0.13

type ProbeScope struct {
	Kind           string   `json:"kind"`
	Tag            string   `json:"tag,omitempty"`
	TargetAgentIDs []string `json:"target_agent_ids,omitempty"`
}

type PublicRouteError added in v0.0.13

type PublicRouteError struct {
	Code      string `json:"code"`
	Stage     string `json:"stage"`
	RequestID string `json:"request_id"`
	Message   string `json:"message"`
}

func NewPublicRouteError added in v0.0.13

func NewPublicRouteError(code, stage, requestID string) PublicRouteError

func (PublicRouteError) Error added in v0.0.13

func (e PublicRouteError) Error() string

type RelayActiveRuntime added in v0.0.13

type RelayActiveRuntime struct {
	URI               string `json:"uri"`
	ActiveGeneration  uint64 `json:"active_generation"`
	SessionGeneration uint64 `json:"session_generation"`
	ConnectedAt       int64  `json:"connected_at"`
	Streams           int    `json:"streams"`
	RetryAt           int64  `json:"retry_at"`
}

type RelayDesiredRuntime added in v0.0.13

type RelayDesiredRuntime struct {
	Mode              string `json:"mode"`
	ConfiguredURI     string `json:"configured_uri"`
	EffectiveURI      string `json:"effective_uri"`
	DesiredGeneration uint64 `json:"desired_generation"`
}

type RelayProbeResult added in v0.0.13

type RelayProbeResult struct {
	TargetAgentID    string          `json:"target_agent_id"`
	State            RelayProbeState `json:"state"`
	Stage            RelayProbeStage `json:"stage,omitempty"`
	LatencyMS        int64           `json:"latency_ms"`
	CheckedAt        int64           `json:"checked_at"`
	ReasonCode       string          `json:"reason_code,omitempty"`
	Policy           ProbePolicy     `json:"policy"`
	PolicyDisabled   bool            `json:"policy_disabled"`
	PolicyReasonCode string          `json:"policy_reason_code,omitempty"`
}

type RelayProbeStage added in v0.0.13

type RelayProbeStage string
const (
	RelayProbeStageOpen     RelayProbeStage = "open"
	RelayProbeStageCommit   RelayProbeStage = "commit"
	RelayProbeStageResponse RelayProbeStage = "response"
)

type RelayProbeState added in v0.0.13

type RelayProbeState string
const (
	RelayProbeReachable   RelayProbeState = "reachable"
	RelayProbeUnreachable RelayProbeState = "unreachable"
	RelayProbeUnavailable RelayProbeState = "unavailable"
	RelayProbeUnknown     RelayProbeState = "unknown"
)

type RelayProbeTarget added in v0.0.13

type RelayProbeTarget struct {
	TargetAgentID         string      `json:"target_agent_id"`
	SourceRelayGeneration uint64      `json:"source_relay_generation"`
	TargetRelayGeneration uint64      `json:"target_relay_generation"`
	Policy                ProbePolicy `json:"policy"`
}

type RelayRecentError added in v0.0.13

type RelayRecentError struct {
	Code       string `json:"code"`
	Stage      string `json:"stage"`
	Message    string `json:"message"`
	OccurredAt int64  `json:"occurred_at"`
	Count      uint64 `json:"count"`
}

type RelayRuntime added in v0.0.13

type RelayRuntime struct {
	Support             string              `json:"support"`
	Config              string              `json:"config"`
	Availability        string              `json:"availability"`
	AcceptingNewStreams bool                `json:"accepting_new_streams"`
	Convergence         string              `json:"convergence"`
	Desired             RelayDesiredRuntime `json:"desired"`
	Active              RelayActiveRuntime  `json:"active"`
	LastError           string              `json:"last_error,omitempty"`
	RecentErrors        []RelayRecentError  `json:"recent_errors,omitempty"`
}

type RelayTicketRequest added in v0.0.13

type RelayTicketRequest struct {
	DesiredGeneration uint64 `json:"desired_generation"`
}

type RouteEdgeDigest added in v0.0.13

type RouteEdgeDigest struct {
	Generation     uint64              `json:"generation"`
	Edges          []RouteEdgeSnapshot `json:"edges"`
	CoveredThrough uint64              `json:"covered_through,omitempty"`
}

type RouteEdgeSnapshot added in v0.0.13

type RouteEdgeSnapshot struct {
	TargetAgentID      string `json:"target_agent_id"`
	RouteID            uint   `json:"route_id"`
	SelectorKind       string `json:"selector_kind"`
	LastUsedAt         int64  `json:"last_used_at"`
	LastDirectResult   string `json:"last_direct_result"`
	AddressFingerprint string `json:"address_fingerprint"`
	SuccessCount       uint64 `json:"success_count"`
	LatencyTotalMS     uint64 `json:"latency_total_ms"`
}

type RouteEvent added in v0.0.13

type RouteEvent struct {
	RequestID          string                    `json:"request_id,omitempty"`
	TargetAgentID      string                    `json:"target_agent_id"`
	RouteID            uint                      `json:"route_id"`
	SelectorKind       string                    `json:"selector_kind"`
	PathKind           string                    `json:"path_kind"`
	Result             string                    `json:"result"`
	Stage              string                    `json:"stage"`
	ReasonCode         string                    `json:"reason_code"`
	CommitState        string                    `json:"commit_state"`
	AddressFingerprint string                    `json:"address_fingerprint"`
	DurationMS         int64                     `json:"duration_ms"`
	ObservedAt         int64                     `json:"observed_at"`
	Sequence           uint64                    `json:"sequence,omitempty"`
	Failures           []RouteFailureObservation `json:"failures,omitempty"`
}

type RouteFailureObservation added in v0.0.13

type RouteFailureObservation struct {
	PathKind    string `json:"path_kind"`
	Stage       string `json:"stage"`
	CommitState string `json:"commit_state"`
	ReasonCode  string `json:"reason_code"`
}

RouteFailureObservation describes one failed transport attempt without changing the final route event fields used by connectivity edge summaries.

type RouteTelemetryBatch added in v0.0.13

type RouteTelemetryBatch struct {
	Generation uint64       `json:"generation"`
	Events     []RouteEvent `json:"events"`
}

type RoutingMember

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

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

type RoutingOwner added in v0.0.13

type RoutingOwner struct {
	UserID  uint
	TokenID uint
}

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"`
	TokenID uint            `json:"token_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 TicketResponse added in v0.0.13

type TicketResponse struct {
	Token     string `json:"token"`
	ExpiresAt int64  `json:"expires_at"`
}

type TokenFetchSide added in v0.0.13

type TokenFetchSide struct {
	SchemaVersion int              `json:"schema_version"`
	User          *SyncedUser      `json:"user,omitempty"`
	TokenRoutings *TokenRoutingMap `json:"token_routings,omitempty"`
}

type TokenRoutingMap added in v0.0.13

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

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"`
	ExecutionAgentID   *string `json:"execution_agent_id,omitempty"`
	RouteSourceAgentID string  `json:"route_source_agent_id,omitempty"`
	AgentRouteID       uint    `json:"agent_route_id,omitempty"`
	AgentRoutePath     string  `json:"agent_route_path,omitempty"`

	// 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"`

	// AutoDisableTriggers is internal Agent-to-Master transport state.
	AutoDisableTriggers []attemptproxy.ChannelAutoDisableTrigger `json:"auto_disable_triggers,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