Documentation
¶
Overview ¶
Package serverkit 是 HTTP / gRPC / debug 三个 server 适配器共享规则的 唯一归属：健康检查执行、有界优雅关停、请求标识传播与生命周期事件。 根级 internal：对 server/* 与 debug 同时可见，不进入公开 API。
Index ¶
- Constants
- func AttrsFromValues(requestID, userID string) []slog.Attr
- func PropagateOutbound(ctx context.Context, set func(key, value string) bool) bool
- func RequestIDFrom(ctx context.Context) string
- func ResolveInbound(requestID, userID string) (string, []slog.Attr)
- func RunHealthChecks(checkers lynx.HealthCheckersFunc, timeout time.Duration) error
- func Shutdown(ctx context.Context, timeout time.Duration, logger *slog.Logger, name string, ...) error
- func ShutdownHTTP(ctx context.Context, timeout time.Duration, logger *slog.Logger, name string, ...) error
- func ValidPropagationValue(v string) bool
- type Lifecycle
- func (l *Lifecycle) AbortStart()
- func (l *Lifecycle) BeginStart() error
- func (l *Lifecycle) BeginStop()
- func (l *Lifecycle) Bind(logger *slog.Logger, bus eventbus.Bus)
- func (l *Lifecycle) Listening(addr, advertiseAddr string)
- func (l *Lifecycle) MarkReady()
- func (l *Lifecycle) Ready() <-chan struct{}
- func (l *Lifecycle) ResetForInit()
- func (l *Lifecycle) StopRequested() bool
- func (l *Lifecycle) Stopped()
- func (l *Lifecycle) Stopping(addr, advertiseAddr string)
Constants ¶
const ( // RequestIDKey / UserIDKey 是 request_id / user_id 的共享 wire 键。 RequestIDKey = propagation.RequestIDHeader UserIDKey = propagation.UserIDHeader // MaxPropagationValueLength 是入站传播值的最大长度（SC-22）。 MaxPropagationValueLength = propagation.MaxValueLength )
wire 键与校验规则的中性归属是 internal/propagation（server 适配器、 客户端与 eventbus 共用）；serverkit 只做面向 server 的转发与入站解析。
const DefaultHealthCheckTimeout = 3 * time.Second
DefaultHealthCheckTimeout 是单个 checker 的执行上限（SC-03）： CheckHealth 接口无 ctx 参数，挂死的 checker 只能被"放弃等待"。
Variables ¶
This section is empty.
Functions ¶
func AttrsFromValues ¶
AttrsFromValues 构造传播日志属性（request_id / user_id）：值为空或非法 时跳过对应字段（不注入日志）。
func PropagateOutbound ¶ added in v1.16.0
PropagateOutbound 把 ctx 中待传播的请求标识经 set 写入出站载体（委托 internal/propagation.Outbound）：键为共享 wire 键，已存在不覆盖。
func RequestIDFrom ¶
RequestIDFrom 返回 ctx 中的 request_id，未设置时返回空字符串。
func ResolveInbound ¶ added in v1.16.0
ResolveInbound 解析入站请求标识（HTTP 中间件与 gRPC 拦截器共用）： 合法值沿用；request_id 缺失/非法时生成新 UUID（返回给调用方回写响应 头/metadata）；user_id 非法时丢弃（没有可生成的语义）。返回解析后的 request_id 与日志属性。
func RunHealthChecks ¶
func RunHealthChecks(checkers lynx.HealthCheckersFunc, timeout time.Duration) error
RunHealthChecks 并发执行 checkers 并整体限时 timeout：任一失败立即返回 其错误；超时返回超时错误（视为不健康）。lynx.Checker 接口无 ctx 参数 （API 冻结），挂死的 checker 无法被打断，只能被"放弃等待"——结果 channel 带缓冲，最终返回的 checker goroutine 写入后自行退出，不阻塞 探测方。固有边界（放弃等待模式的残余代价）：永不返回的 checker（死锁 类）其 goroutine 无法回收，会随每次探测累积泄漏，只能修复 checker 本身或重启进程消除。 timeout <= 0 表示不限时：退化为顺序执行（保持旧行为的逃生口）。
func Shutdown ¶
func Shutdown(ctx context.Context, timeout time.Duration, logger *slog.Logger, name string, graceful func(context.Context) error, force func() error) error
Shutdown 执行有界优雅关停（三个 server 适配器的唯一规则）：
- timeout > 0：配置上限与调用方 deadline 取较小者（context 自动继承 父 ctx 的更早 deadline）；timeout == 0：无配置上限，仅以调用方为准；
- graceful 在独立 goroutine 执行；ctx 结束后先调用 force 解除其阻塞 （http.Server.Shutdown 等待连接排空、grpc.Server.GracefulStop 等待 在途 RPC 都不会自行返回），再等 graceful 退出，避免与内部清理交错；
- graceful 先返回且错误为 context.Canceled / DeadlineExceeded 时同样 归类超时并强制关闭；其他错误原样返回；正常返回即成功。
超时路径统一返回 "<name> graceful shutdown timed out: %w"。
func ShutdownHTTP ¶ added in v1.16.0
func ShutdownHTTP(ctx context.Context, timeout time.Duration, logger *slog.Logger, name string, srv *http.Server) error
ShutdownHTTP 执行 *http.Server 的有界优雅关停（HTTP 与 debug 适配器 共用）：graceful 归一化 http.ErrServerClosed（正常关停不是失败），超时 强制 Close。有界规则见 Shutdown。
func ValidPropagationValue ¶
ValidPropagationValue 判定入站传播值是否可安全沿用。
Types ¶
type Lifecycle ¶ added in v1.16.0
type Lifecycle struct {
// contains filtered or unexported fields
}
Lifecycle 是 HTTP / gRPC / debug 三个 server 适配器共享的生命周期状态机 （唯一归属）：Start 重入守卫、停止请求标志、就绪信号与生命周期事件发布。 适配器保留传输细节（listener/server 创建、Serve/GracefulStop、地址策略、 健康轮询与启动期交错处理），只把状态迁移委托到这里。
语义：
- BeginStart 二次调用返回错误（带 service 名）；Init 经 ResetForInit 复位守卫与停止标志（ready 一旦关闭无法复位，重启语义仅部分）； Listen/端点配置失败经 AbortStart 复位守卫，允许修正后重试。
- BeginStop 置位停止请求（幂等）；StopRequested 供 Start 的启动期 交错检查（Stop 先于 Start 到达时不进入 Serve）。
- MarkReady 关闭就绪信号（once）；Ready 返回只读 channel。
- Listening/Stopping/Stopped 发布 lynx.server.* 事件（bus 为 nil 时 no-op，发布失败仅 Debug 日志）。
func NewLifecycle ¶ added in v1.16.0
NewLifecycle 创建生命周期状态机；service 是事件里的 ServerEvent.Service （"http" / "grpc" / "debug"），也用于重入错误文案。
func (*Lifecycle) AbortStart ¶ added in v1.16.0
func (l *Lifecycle) AbortStart()
AbortStart 复位守卫：Listen/端点配置等启动失败不算已启动，允许修正后 重试（与 BeginStart 的成功路径对称）。
func (*Lifecycle) BeginStart ¶ added in v1.16.0
BeginStart 是 Start 的重入守卫：二次 Start 返回错误（会覆盖 listener/ server 并泄漏旧实例）。
func (*Lifecycle) BeginStop ¶ added in v1.16.0
func (l *Lifecycle) BeginStop()
BeginStop 置位停止请求（幂等）。
func (*Lifecycle) Bind ¶ added in v1.16.0
Bind 注入日志与总线（适配器 Init 时调用；bus 可为 nil——脱离框架单用时 事件发布 no-op）。Bind 可重复调用（重新 Init 场景）。
func (*Lifecycle) MarkReady ¶ added in v1.16.0
func (l *Lifecycle) MarkReady()
MarkReady 关闭就绪信号（幂等：once 语义）。
func (*Lifecycle) Ready ¶ added in v1.16.0
func (l *Lifecycle) Ready() <-chan struct{}
Ready 返回就绪信号：MarkReady 之后关闭。
func (*Lifecycle) ResetForInit ¶ added in v1.16.0
func (l *Lifecycle) ResetForInit()
ResetForInit 复位守卫与停止标志（适配器 Init 调用）：允许重新 Init 后 再次 Start。ready 一旦关闭无法复位——重启语义仅部分（就绪信号不重置）， 与既有 HTTP/gRPC 语义一致。
func (*Lifecycle) StopRequested ¶ added in v1.16.0
StopRequested 报告 Stop 是否已请求：Start 在进入 Serve 之前检查——已 中断后不再 Serve，避免「Stop 见 server 为 nil 先返回、Start 随后监听并 永久运行」的启动期交错。
Source Files