Documentation
¶
Index ¶
- func EnrichLastSeen[T any](tracker *HeartbeatTracker, items []T, getID func(T) string, ...)
- func ExpandPrivateChannelAudience(q dao.AdminQuery, channelID uint, ownerID uint) ([]uint, error)
- func PublishPrivateChannelMutation(ctx context.Context, q dao.AdminQuery, bus app.EventBus, ...) error
- type APIFullSyncHandler
- type APIFullSyncRegistry
- type APIProjector
- type APIRoleSetFetcher
- type APISyncActions
- func (a *APISyncActions) DeleteUserGroupRoleSet(ctx context.Context, principalID uint) error
- func (a *APISyncActions) InvalidateTokenRoleSet(ctx context.Context, principalID uint) error
- func (a *APISyncActions) InvalidateUserRoleSet(ctx context.Context, principalID uint) error
- func (a *APISyncActions) PublishRole(ctx context.Context, q dao.AdminQuery, action string, roleID uint) error
- func (a *APISyncActions) PublishRoleBindingChange(ctx context.Context, q dao.AdminQuery, principalType models.APIPrincipalType, ...) error
- func (a *APISyncActions) PublishRoute(ctx context.Context, action string, route models.APIRoute) error
- func (a *APISyncActions) PublishService(ctx context.Context, action string, service models.APIService) error
- func (a *APISyncActions) PublishUpstream(ctx context.Context, action string, upstream models.APIUpstream) error
- func (a *APISyncActions) PublishUserGroupRoleSet(ctx context.Context, roleSet protocol.APIRoleSetFetchResult) error
- type AgentRuntime
- type AgentTicketSigner
- type FetchHandler
- type FetchRegistry
- type HeartbeatTracker
- func (t *HeartbeatTracker) Close(ctx context.Context) error
- func (t *HeartbeatTracker) ConfigChanged(agentID string, generation uint64, params protocol.HeartbeatParams) bool
- func (t *HeartbeatTracker) Done() <-chan struct{}
- func (t *HeartbeatTracker) Flush() error
- func (t *HeartbeatTracker) FlushContext(ctx context.Context) error
- func (t *HeartbeatTracker) Get(agentID string) (int64, bool)
- func (t *HeartbeatTracker) GetMany(ids []string) map[string]int64
- func (t *HeartbeatTracker) ResourceCounts() app.ResourceCounts
- func (t *HeartbeatTracker) SetLastSeenPersistContextFn(fn LastSeenPersistContextFn)
- func (t *HeartbeatTracker) SetLastSeenPersistFn(fn LastSeenPersistFn)
- func (t *HeartbeatTracker) Start(ctx context.Context)
- func (t *HeartbeatTracker) Stop(ctx context.Context) error
- func (t *HeartbeatTracker) Touch(agentID string, ts int64)
- type Hub
- func (h *Hub) Broadcast(method string, params any)
- func (h *Hub) Call(agentID string, method string, params any, timeout time.Duration) (json.RawMessage, error)
- func (h *Hub) CallContext(ctx context.Context, agentID, method string, params any, timeout time.Duration) (json.RawMessage, error)
- func (h *Hub) CallSession(agentID string, generation uint64, method string, params any, ...) (json.RawMessage, error)
- func (h *Hub) CallSessionContext(ctx context.Context, agentID string, generation uint64, method string, ...) (json.RawMessage, error)
- func (h *Hub) Capabilities(agentID string) []string
- func (h *Hub) Close(ctx context.Context) error
- func (h *Hub) ConnectedAgents() int
- func (h *Hub) Done() <-chan struct{}
- func (h *Hub) GetAgentAddresses(agentID string, dbHTTPAddrs string) []agentproxy.Address
- func (h *Hub) GetControlSession(agentID string) (connectivity.ControlSessionFact, bool)
- func (h *Hub) GetOnlineAgentIDs() []string
- func (h *Hub) GetRuntime(agentID string) *AgentRuntime
- func (h *Hub) HandleUsageHTTP(c *gin.Context)
- func (h *Hub) HandleWS(c *gin.Context)
- func (h *Hub) IsCurrentControlSession(agentID string, generation uint64) bool
- func (h *Hub) IsOnline(agentID string) bool
- func (h *Hub) NotifyAgent(agentID, method string, params any)
- func (h *Hub) RecordControlError(agentID string, generation uint64, event diagnostics.Event) bool
- func (h *Hub) ResourceCounts() app.ResourceCounts
- func (h *Hub) RevokeControlSession(agentID string) bool
- func (h *Hub) SetControlSessionRemoved(fn func(string, uint64))
- type HubOptions
- type LastSeenPersistContextFn
- type LastSeenPersistFn
- type Publisher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnrichLastSeen ¶ added in v0.0.2
func EnrichLastSeen[T any]( tracker *HeartbeatTracker, items []T, getID func(T) string, getLastSeen func(T) int64, setLastSeen func(*T, int64), )
EnrichLastSeen overrides each item's last_seen with the value from tracker when the in-memory value is fresher (greater) than the DB value.
Used by API handlers that read agent rows from DB but want the latest last_seen visible in the UI without waiting for the periodic batch flush.
Generic over item type T. Callers supply:
- getID: extract agent_id from the item
- getLastSeen: extract the current (DB-side) last_seen from the item
- setLastSeen: write the new last_seen back into the item
Nil tracker or empty slice is a no-op.
func ExpandPrivateChannelAudience ¶ added in v0.0.2
ExpandPrivateChannelAudience returns the deduplicated set of user IDs whose visiblePrivateChannels cache must be invalidated when a private channel is created/updated/deleted/shared:
- the owner
- users directly targeted by share rows (target_type='user')
- members of groups targeted by share rows (target_type='group')
Called by master CRUD handlers before publishing the invalidate event. channelID may not exist (e.g., for pre-delete computation); in that case only the owner is returned.
func PublishPrivateChannelMutation ¶ added in v0.0.2
func PublishPrivateChannelMutation(ctx context.Context, q dao.AdminQuery, bus app.EventBus, channelID, ownerID uint) error
PublishPrivateChannelMutation 在 Create/Update/Delete PrivateChannel 后调用, 展开受影响 user 集合(owner ∪ share→user ∪ share→group 内的 members)并发布 invalidate 事件。agent 收到事件后失效这些 user 的 visiblePrivateChannels cache。
用法:portal/admin 在写入 DB 后调用一次此函数;publish 失败仅记日志,不阻塞主流程 (调用方自行决定 log 策略)。
Types ¶
type APIFullSyncHandler ¶ added in v0.0.16
type APIFullSyncHandler interface {
FullSync(context.Context, dao.AdminQuery, protocol.FullSyncRequest) (protocol.FullSyncResponse, error)
}
type APIFullSyncRegistry ¶ added in v0.0.16
type APIFullSyncRegistry struct {
// contains filtered or unexported fields
}
func NewAPIFullSyncRegistry ¶ added in v0.0.16
func NewAPIFullSyncRegistry(cipher *byokcrypto.Cipher, getVersion func() int64) *APIFullSyncRegistry
func (*APIFullSyncRegistry) Register ¶ added in v0.0.16
func (r *APIFullSyncRegistry) Register(entity string, handler APIFullSyncHandler)
func (*APIFullSyncRegistry) Resolve ¶ added in v0.0.16
func (r *APIFullSyncRegistry) Resolve(entity string) (APIFullSyncHandler, bool)
type APIProjector ¶ added in v0.0.16
type APIProjector struct {
// contains filtered or unexported fields
}
func NewAPIProjector ¶ added in v0.0.16
func NewAPIProjector(cipher *byokcrypto.Cipher) *APIProjector
func (*APIProjector) ProjectRoute ¶ added in v0.0.16
func (p *APIProjector) ProjectRoute(route models.APIRoute) protocol.SyncedAPIRoute
func (*APIProjector) ProjectService ¶ added in v0.0.16
func (p *APIProjector) ProjectService(service models.APIService) protocol.SyncedAPIService
func (*APIProjector) ProjectUpstream ¶ added in v0.0.16
func (p *APIProjector) ProjectUpstream(upstream models.APIUpstream) (protocol.SyncedAPIUpstream, error)
type APIRoleSetFetcher ¶ added in v0.0.16
type APIRoleSetFetcher struct{}
func (APIRoleSetFetcher) FetchToken ¶ added in v0.0.16
func (APIRoleSetFetcher) FetchToken( ctx context.Context, q dao.AdminQuery, principalID uint, ) (protocol.APIRoleSetFetchResult, error)
func (APIRoleSetFetcher) FetchUser ¶ added in v0.0.16
func (APIRoleSetFetcher) FetchUser( ctx context.Context, q dao.AdminQuery, principalID uint, ) (protocol.APIRoleSetFetchResult, error)
type APISyncActions ¶ added in v0.0.16
type APISyncActions struct {
// contains filtered or unexported fields
}
func NewAPISyncActions ¶ added in v0.0.16
func NewAPISyncActions(bus app.EventBus, cipher *byokcrypto.Cipher) *APISyncActions
func (*APISyncActions) DeleteUserGroupRoleSet ¶ added in v0.0.16
func (a *APISyncActions) DeleteUserGroupRoleSet(ctx context.Context, principalID uint) error
func (*APISyncActions) InvalidateTokenRoleSet ¶ added in v0.0.16
func (a *APISyncActions) InvalidateTokenRoleSet(ctx context.Context, principalID uint) error
func (*APISyncActions) InvalidateUserRoleSet ¶ added in v0.0.16
func (a *APISyncActions) InvalidateUserRoleSet(ctx context.Context, principalID uint) error
func (*APISyncActions) PublishRole ¶ added in v0.0.16
func (a *APISyncActions) PublishRole( ctx context.Context, q dao.AdminQuery, action string, roleID uint, ) error
func (*APISyncActions) PublishRoleBindingChange ¶ added in v0.0.16
func (a *APISyncActions) PublishRoleBindingChange( ctx context.Context, q dao.AdminQuery, principalType models.APIPrincipalType, principalID uint, ) error
func (*APISyncActions) PublishRoute ¶ added in v0.0.16
func (*APISyncActions) PublishService ¶ added in v0.0.16
func (a *APISyncActions) PublishService(ctx context.Context, action string, service models.APIService) error
func (*APISyncActions) PublishUpstream ¶ added in v0.0.16
func (a *APISyncActions) PublishUpstream(ctx context.Context, action string, upstream models.APIUpstream) error
func (*APISyncActions) PublishUserGroupRoleSet ¶ added in v0.0.16
func (a *APISyncActions) PublishUserGroupRoleSet(ctx context.Context, roleSet protocol.APIRoleSetFetchResult) error
type AgentRuntime ¶
type AgentRuntime = connectivity.AgentRuntimeFact
type AgentTicketSigner ¶ added in v0.0.13
type FetchHandler ¶
type FetchHandler interface {
Fetch(ctx context.Context, q dao.AdminQuery, key string) (
data, side json.RawMessage, found bool, err error,
)
}
FetchHandler 是单实体的按需拉取处理器。 返回 (data, side, found, err):
- data 是实体本身的 JSON
- side 是可选旁路负载(如 token 响应里的 SyncedUser)
- found=false 表示 master 也未查到(调用方应让 agent 进入负缓存)
- err 仅用于真正的内部错误(DB 故障等),not-found 用 found=false 表示
type FetchRegistry ¶
type FetchRegistry struct {
// contains filtered or unexported fields
}
FetchRegistry 是实体名 → handler 的注册表。 主流程通过 Resolve 路由请求;新增实体仅需注册一次。
func NewFetchRegistry ¶
func NewFetchRegistry(cipher *byokcrypto.Cipher) *FetchRegistry
NewFetchRegistry 返回带默认实体(token / user / user_routings / private_channel)注册的 registry。 cipher 用于 private_channel 拉取时解密 key;可为 nil(仅在 BYOK 未配置的早期/测试场景), 此时 private channel handler 在被调用时返回 error。
func (*FetchRegistry) Register ¶
func (r *FetchRegistry) Register(entity string, h FetchHandler)
Register 注册或替换某实体的 handler。
func (*FetchRegistry) Resolve ¶
func (r *FetchRegistry) Resolve(entity string) (FetchHandler, bool)
Resolve 返回实体对应的 handler。
type HeartbeatTracker ¶ added in v0.0.2
type HeartbeatTracker struct {
// contains filtered or unexported fields
}
HeartbeatTracker holds the in-memory authoritative source for agent last_seen and config fingerprints. last_seen is batch-flushed to DB periodically; the config fingerprint is only used to skip mergeAgentConfig SELECTs on unchanged heartbeats.
func NewHeartbeatTracker ¶ added in v0.0.2
func NewHeartbeatTracker(app dao.AppProvider, logger *zap.Logger, flushEvery time.Duration) *HeartbeatTracker
NewHeartbeatTracker constructs a tracker. app may be nil for pure-memory tests. flushEvery <= 0 disables the background ticker.
func (*HeartbeatTracker) Close ¶ added in v0.0.13
func (t *HeartbeatTracker) Close(ctx context.Context) error
Close stops the ticker and retries the final dirty flush with bounded, context-aware backoff. Concurrent callers observe the same final error once the lifecycle worker has completed.
func (*HeartbeatTracker) ConfigChanged ¶ added in v0.0.2
func (t *HeartbeatTracker) ConfigChanged(agentID string, generation uint64, params protocol.HeartbeatParams) bool
ConfigChanged returns whether the current generation must merge params. Newer generations always merge, stale generations are ignored, and repeated fingerprints within the same generation skip mergeAgentConfig's SELECT.
func (*HeartbeatTracker) Done ¶ added in v0.0.13
func (t *HeartbeatTracker) Done() <-chan struct{}
func (*HeartbeatTracker) Flush ¶ added in v0.0.2
func (t *HeartbeatTracker) Flush() error
Flush snapshots dirty entries to DB and clears the dirty set. Persistence failures merge the snapshot IDs back into dirty; a Touch that arrives during persistence keeps its newer value in seen for the next Flush.
func (*HeartbeatTracker) FlushContext ¶ added in v0.0.13
func (t *HeartbeatTracker) FlushContext(ctx context.Context) error
func (*HeartbeatTracker) Get ¶ added in v0.0.2
func (t *HeartbeatTracker) Get(agentID string) (int64, bool)
Get returns the in-memory last_seen; (0, false) when not present.
func (*HeartbeatTracker) GetMany ¶ added in v0.0.2
func (t *HeartbeatTracker) GetMany(ids []string) map[string]int64
GetMany returns only the in-memory hits among ids.
func (*HeartbeatTracker) ResourceCounts ¶ added in v0.0.13
func (t *HeartbeatTracker) ResourceCounts() app.ResourceCounts
func (*HeartbeatTracker) SetLastSeenPersistContextFn ¶ added in v0.0.13
func (t *HeartbeatTracker) SetLastSeenPersistContextFn(fn LastSeenPersistContextFn)
func (*HeartbeatTracker) SetLastSeenPersistFn ¶ added in v0.0.2
func (t *HeartbeatTracker) SetLastSeenPersistFn(fn LastSeenPersistFn)
SetLastSeenPersistFn installs the persistence function used by Flush.
func (*HeartbeatTracker) Start ¶ added in v0.0.2
func (t *HeartbeatTracker) Start(ctx context.Context)
Start spawns a background goroutine that calls Flush every flushEvery. When ctx is canceled (or Stop is called), the goroutine exits. flushEvery <= 0 disables the ticker entirely; callers must Flush manually or rely on Stop's force-flush.
func (*HeartbeatTracker) Stop ¶ added in v0.0.2
func (t *HeartbeatTracker) Stop(ctx context.Context) error
func (*HeartbeatTracker) Touch ¶ added in v0.0.2
func (t *HeartbeatTracker) Touch(agentID string, ts int64)
Touch records a heartbeat/connect event purely in memory.
type Hub ¶
type Hub struct {
App dao.AppProvider
Logger *zap.Logger
Bus app.EventBus
GetVersion func() int64
// Heartbeat captures agent last_seen in memory + skips redundant
// mergeAgentConfig SELECTs via the ConfigChanged fingerprint. May be nil
// in tests / pre-wiring; callers must nil-check before use.
Heartbeat *HeartbeatTracker
// RouteObservations owns bounded, memory-only source-to-target edges.
RouteObservations *connectivity.Service
// SettleUsage 数据面同步结算入口;非 nil 时 HTTP 摄取只在落库成功后才 200 ——
// ack=已持久化。nil 时回退老的异步 publish 语义(兼容未接线的构造)。
SettleUsage func(ctx context.Context, agentID string, logs []protocol.UsageLogEntry) error
AcceptAPIUsage func(ctx context.Context, agentID string, entries []protocol.APIUsageEntry) error
// contains filtered or unexported fields
}
func NewHub ¶
func NewHub( application dao.AppProvider, logger *zap.Logger, bus app.EventBus, getVersion func() int64, cipher *byokcrypto.Cipher, opts HubOptions, ) *Hub
func (*Hub) Broadcast ¶
Broadcast sends a notification to all connected agents. 复制 conns snapshot 后释放 RLock,再 fan-out。 每条 conn 的 SendNotification 是非阻塞 enqueue(见 ws.Conn.SendNotification)。
func (*Hub) Call ¶
func (h *Hub) Call(agentID string, method string, params any, timeout time.Duration) (json.RawMessage, error)
Call sends an RPC request to a connected agent and waits for response.
func (*Hub) CallContext ¶ added in v0.0.27
func (h *Hub) CallContext(ctx context.Context, agentID, method string, params any, timeout time.Duration) (json.RawMessage, error)
CallContext 查询当前控制连接并在调用预算内等待响应。
func (*Hub) CallSession ¶ added in v0.0.13
func (*Hub) CallSessionContext ¶ added in v0.0.13
func (h *Hub) CallSessionContext(ctx context.Context, agentID string, generation uint64, method string, params any, timeout time.Duration) (json.RawMessage, error)
CallSessionContext 在固定连接代次上发送 RPC,并等待响应或调用取消。
func (*Hub) Capabilities ¶ added in v0.0.13
func (*Hub) ConnectedAgents ¶
ConnectedAgents returns the number of connected agents
func (*Hub) GetAgentAddresses ¶
func (h *Hub) GetAgentAddresses(agentID string, dbHTTPAddrs string) []agentproxy.Address
GetAgentAddresses returns merged addresses for an agent. Priority: manual config (DB) > auto-detected (memory).
func (*Hub) GetControlSession ¶ added in v0.0.13
func (h *Hub) GetControlSession(agentID string) (connectivity.ControlSessionFact, bool)
func (*Hub) GetOnlineAgentIDs ¶
GetOnlineAgentIDs returns IDs of currently connected agents.
func (*Hub) GetRuntime ¶
func (h *Hub) GetRuntime(agentID string) *AgentRuntime
GetRuntime returns cached runtime info for an agent, or nil if not available.
func (*Hub) HandleUsageHTTP ¶ added in v0.0.13
HandleUsageHTTP 是数据面用量摄取端点(POST /api/agents/usage)。 agent 头鉴权与 /ws/agent 同源;落库链复用 usage.reported 事件(Settler 幂等去重)。
func (*Hub) IsCurrentControlSession ¶ added in v0.0.13
func (*Hub) NotifyAgent ¶ added in v0.0.8
NotifyAgent 向指定 agent 单向推送一条通知(无响应)。agent 离线则静默丢弃。
func (*Hub) RecordControlError ¶ added in v0.0.13
func (*Hub) ResourceCounts ¶ added in v0.0.13
func (h *Hub) ResourceCounts() app.ResourceCounts
func (*Hub) RevokeControlSession ¶ added in v0.0.13
RevokeControlSession removes and closes the current authenticated control session for an Agent deleted by the management plane.
func (*Hub) SetControlSessionRemoved ¶ added in v0.0.13
type HubOptions ¶ added in v0.0.13
type HubOptions struct {
MasterInstanceID string
Capabilities []string
AgentTicketSigner AgentTicketSigner
AcceptAPIUsage func(context.Context, string, []protocol.APIUsageEntry) error
}
type LastSeenPersistContextFn ¶ added in v0.0.13
type LastSeenPersistFn ¶ added in v0.0.2
LastSeenPersistFn is the function Flush calls to persist updates. Inject the real dao.BatchUpdateLastSeen for production; nil makes Flush a no-op.
Source Files
¶
- api_projection.go
- api_sync_actions.go
- expand_audience.go
- fetch_api_role_sets.go
- fetch_handlers.go
- fetch_private_channels_visible.go
- fetch_token.go
- fetch_token_routings.go
- fetch_user.go
- fetch_user_routings.go
- full_sync_api.go
- heartbeat_enrich.go
- heartbeat_tracker.go
- hub.go
- publisher.go
- publisher_private_channel.go
- usage_http.go