agent

type Client interface {
	// Register 负责把当前服务注册到本机 sidecar-agent。
	Register(ctx context.Context, request RegisterRequest) error
	// Drain 负责把当前服务切换到摘流状态。
	Drain(ctx context.Context, request DrainRequest) error
	// Deregister 负责把当前服务从本机 sidecar-agent 注销。
	Deregister(ctx context.Context, request DeregisterRequest) error
}

type ConnectionEvent struct {
	// Type 表示事件类型，例如 connected、heartbeat、disconnected。
	Type string
	// Connected 表示当前事件是否意味着连接已建立。
	Connected bool
	// EventId 表示服务端 SSE 事件 ID，便于后续排障与协议增强。
	EventId string
	// Message 保存服务端事件说明文本。
	Message string
	// Service 表示当前发出 watch 事件的服务名。
	Service string
	// Status 表示 sidecar 当前运行态摘要，例如 ready、starting、degraded。
	Status string
	// LifecycleState 表示 sidecar 当前生命周期阶段。
	LifecycleState string
	// Ready 表示 sidecar 主链当前是否 ready；nil 表示服务端未提供该信息。
	Ready *bool
	// GeneratedAt 表示该事件在服务端生成的时间。
	GeneratedAt *time.Time
	// Err 保存连接断开或处理失败时的上下文错误。
	Err error
}

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

type DeregisterRequest struct {
	// Name 表示逻辑服务名。
	Name string `json:"name"`
	// Port 表示业务服务监听端口。
	Port int `json:"port"`
}

type DescriptorProvider interface {
	// BuildRegisterRequest 返回当前业务服务完整注册描述。
	BuildRegisterRequest(ctx context.Context) (RegisterRequest, error)
}

type DrainRequest struct {
	// Name 表示逻辑服务名。
	Name string `json:"name"`
	// Port 表示业务服务监听端口。
	Port int `json:"port"`
	// GracePeriod 表示摘流宽限期。
	GracePeriod string `json:"grace_period"`
}

type ErrorHandler func(context.Context, error)

type EventSource interface {
	// Subscribe 返回一个持续输出连接事件的只读通道。
	Subscribe(ctx context.Context) (<-chan ConnectionEvent, error)
}

type GRPCDescriptorOptions struct {
	// AppID 表示应用标识。
	AppId string
	// AppName 表示应用名称；为空时回退到 ServiceName。
	AppName string
	// ServiceName 表示逻辑服务名。
	ServiceName string
	// Namespace 表示命名空间。
	Namespace string
	// DNS 表示统一服务域名。
	DNS string
	// Env 表示运行环境。
	Env string
	// Port 表示业务监听端口。
	Port int
	// Protocol 表示业务协议。
	Protocol string
	// Version 表示业务版本号。
	Version string
	// ServiceOptions 表示业务服务当前的裸机接入配置。
	ServiceOptions *ServiceOptions
	// RawServices 表示业务已注册的 gRPC ServiceDesc 集合。
	RawServices []*grpc.ServiceDesc
}

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

type KernelInfo struct {
	// Language 表示业务服务使用的开发语言。
	Language string `json:"language"`
	// Version 表示业务服务运行时或框架版本。
	Version string `json:"version"`
}

type LifecycleHookOptions struct {
	// Lifecycle 表示已经组装完成的业务生命周期桥接对象。
	Lifecycle *ServiceLifecycle
	// OnError 用于处理后台 watch 与 register 重放阶段的异步错误。
	OnError ErrorHandler
}

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

type LifecycleOptions struct {
	// Runtime 表示已经组装完成的本地 agent 运行时。
	Runtime *LocalRuntime
	// GracePeriod 表示业务服务优雅下线时使用的默认摘流宽限期。
	GracePeriod string
}

type LifecycleRunError struct {
	// Err 表示底层运行失败原因。
	Err error
}

type LocalRuntime struct {
	// Client 负责发起 register / drain / deregister 请求。
	Client *JSONHTTPClient
	// Source 负责把本地 `/watch` 连接转换成连接事件流。
	Source *WatchSource
	// Controller 负责缓存注册描述并在连接恢复时重放 register。
	Controller *Controller
	// Runner 负责驱动事件流与 register 重放过程。
	Runner *Runner
}

type LocalRuntimeOptions struct {
	// BaseURL 表示本机 sidecar-agent 管理接口前缀。
	BaseURL string
	// WatchURL 表示本机 sidecar-agent 的长连接 watch 地址。
	WatchURL string
	// RequestTimeout 表示 register / drain / deregister 请求超时。
	RequestTimeout time.Duration
	// ReconnectInterval 表示 watch 断开后的重连间隔。
	ReconnectInterval time.Duration
	// OnError 用于统一处理 watch 与 register 重放过程中的错误。
	OnError ErrorHandler
}

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

type ManagedServerOptions struct {
	// Lifecycle 表示 sidecar-agent 生命周期桥接对象。
	Lifecycle *ServiceLifecycle
	// Serve 表示业务服务真正的阻塞运行入口。
	Serve ServeFunc
	// Shutdown 表示业务服务优雅关闭入口；可为空。
	Shutdown ShutdownFunc
}

type ManagedServerRunError struct {
	// Stage 表示失败发生阶段。
	Stage string
	// Err 表示底层错误。
	Err error
}

type RegisterReplayError struct {
	// ServiceName 表示当前重放失败的服务名。
	ServiceName string
	// ServicePort 表示当前重放失败的服务端口。
	ServicePort int
	// Err 表示底层 register 调用失败原因。
	Err error
}

type RegisterRequest struct {
	// AppID 表示应用标识。
	AppID string `json:"app_id"`
	// AppName 表示应用名称。
	AppName string `json:"app_name"`
	// Name 表示逻辑服务名。
	Name string `json:"name"`
	// Namespace 表示命名空间。
	Namespace string `json:"namespace"`
	// Port 表示业务服务监听端口。
	Port int `json:"port"`
	// DNS 表示业务服务统一域名。
	DNS string `json:"dns"`
	// Env 表示业务服务所属环境。
	Env string `json:"env"`
	// Weight 表示实例权重。
	Weight int `json:"weight"`
	// Protocol 表示服务协议。
	Protocol string `json:"protocol"`
	// Kernel 表示业务服务运行时信息。
	Kernel KernelInfo `json:"kernel"`
	// Methods 表示业务服务暴露的方法列表。
	Methods []string `json:"methods"`
	// Version 表示业务版本号。
	Version string `json:"version"`
}

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

type ServeFunc func(context.Context) error

type ServiceKernel struct {
	Language string `json:"language"`
	Version  string `json:"version"`
}

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

type ServiceMeta struct {
	AppId      string `json:"app_id"`
	InstanceId string `json:"instance_id"`
	Version    string `json:"version"`
	Env        string `json:"env"`
}

type ServiceNode struct {
	ProtoCount int             `json:"proto_count"`
	Weight     int             `json:"weight"`
	RunDate    string          `json:"run_date"`
	Methods    map[string]bool `json:"methods"`
	Kernel     *ServiceKernel  `json:"kernel"`
	Meta       *ServiceMeta    `json:"meta"`
}

type ServiceOptions struct {
	InstanceId string         `json:"instance_id"`
	Namespace  string         `json:"namespace"`
	Kernel     *ServiceKernel `json:"kernel"`
	MaxRetry   uint32         `json:"max_retry"`
	TTL        uint32         `json:"ttl"`
	Weight     int            `json:"weight"`
}

type ServiceRegistration struct {
	// AppId 表示应用标识；为空时优先回退到 Node.Meta.AppID。
	AppId string
	// AppName 表示应用名称；为空时回退到 ServiceName。
	AppName string
	// ServiceName 表示逻辑服务名。
	ServiceName string
	// Namespace 表示命名空间。
	Namespace string
	// DNS 表示统一服务域名。
	DNS string
	// Env 表示运行环境。
	Env string
	// Port 表示业务监听端口。
	Port int
	// Protocol 表示当前服务协议。
	Protocol string
	// Version 表示业务版本号。
	Version string
	// Weight 表示实例权重；为空时优先回退到 Node.Weight。
	Weight int
	// Node 表示业务服务当前的注册节点信息。
	Node *ServiceNode
}

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

type ShutdownFunc func(context.Context) error

type Status struct {
	// Connected 表示当前是否与本机 sidecar-agent 保持连接。
	Connected bool
	// Registered 表示最近一次 register 是否成功完成。
	Registered bool
	// LastServiceName 表示最近一次成功注册的服务名。
	LastServiceName string
	// LastServicePort 表示最近一次成功注册的服务端口。
	LastServicePort int
	// LastEventType 表示最近一次收到的 watch 事件类型。
	LastEventType string
	// LastEventId 表示最近一次收到的 SSE 事件 ID。
	LastEventId string
	// LastEventAt 表示最近一次事件的观测时间。
	LastEventAt string
	// LastConnectedAt 表示最近一次成功建立或恢复连接的时间。
	LastConnectedAt string
	// LastDisconnectedAt 表示最近一次断连的时间。
	LastDisconnectedAt string
	// DisconnectCount 表示运行期间累计收到的断连次数。
	DisconnectCount int
	// RegisterReplayCount 表示累计成功重放 register 的次数。
	RegisterReplayCount int
	// RegisterReplayFailureCount 表示累计 register 重放失败次数。
	RegisterReplayFailureCount int
	// LastErrorKind 表示最近一次错误的分类。
	LastErrorKind string
	// LastError 表示最近一次错误文本。
	LastError string
	// LastErrorAt 表示最近一次错误发生时间。
	LastErrorAt string
}

type WatchEventParseError struct {
	// EventType 表示解析失败的事件类型。
	EventType string
	// EventId 表示服务端 SSE 事件 ID。
	EventId string
	// Payload 表示原始 data 内容，便于调试坏帧。
	Payload string
	// Err 表示底层 JSON 解析错误。
	Err error
}

type WatchHTTPStatusError struct {
	// StatusCode 表示 HTTP 状态码。
	StatusCode int
	// Status 表示原始 HTTP 状态文本。
	Status string
}

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