File size: 8,013 Bytes
e48a2d8 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 | package server
import (
"context"
"encoding/json"
"net/http"
"sync"
"sync/atomic"
"time"
)
// headKeepaliveWriter 在「已建连但上游首帧还没到」的空窗里向客户端补 SSE 注释帧。
//
// 为什么需要:StreamHint 是「首帧否决」设计——上游第一个有效帧到达前一个字节都不写
// (internal/upstream/sse.go 的 headOpen 窗口),好处是首帧就是错误时可以静默换号,
// 代价是客户端从建连起零字节干等,等满整个 TTFB。大上下文把这个空窗拉到秒级:
// 线上实测 160–320k 档 TTFB 中位 2.6s / P90 4.8s,320k+ 档 P90 6.1s,而
// 「零内容 + client_gone」的中断全部落在 3.46~4.09s 这个带上。
//
// 注释帧(": " 开头的行)是 SSE 规范定义的 no-op:客户端解析器忽略它,唯一作用是
// 让连接上「一直有数据流动」,使「等首字节」的计时器不会触发。
//
// 三条不变量:
// - 与真实写共用一把锁:注释帧绝不插进写了一半的事件帧中间。
// - 首个真实字节写出后立即停手(started),正常流一条注释都不多写。
// - 停手是终态:之后的空窗不再补注释(流中静默由 continueReader.maybeKeepalive 负责,
// 两处不叠加,否则同一条流会出现两套节奏)。
//
// 代价(注释帧会提前提交响应头,这件事是不可逆的):
// - 之后的 w.Header().Set(...) 一律失效,所以 arm() 必须在「账号已选定、成功头
// (X-Wb-Account / X-Accel-Buffering)已写完」之后才调用。
// - 全号失败时不能再回 503 + JSON,只能 200 + 协议内 error 帧 + [DONE]
// (见 writeSSEErrorFrame)。
type headKeepaliveWriter struct {
http.ResponseWriter
every time.Duration
started atomic.Bool // 已写出真实帧(终态:停手)
committed atomic.Bool // 已写出任何字节(响应头已提交)
ticks atomic.Int64 // 实际发出的注释帧数(测试与观测用)
mu sync.Mutex
closeOnce sync.Once
cancel context.CancelFunc
done chan struct{}
// firstFrame 在首个真实帧写出时关闭:心跳协程据此立刻退出,而不是等下一次
// tick 才发现(否则首个慢流在 every 窗口内的所有写都还要过锁)。
firstFrame chan struct{}
}
// newHeadKeepaliveWriter 包装 w 并立即起心跳协程。every<=0 时返回 nil(调用方据此跳过)。
// ctx 结束或调用 stop() 时协程退出。
func newHeadKeepaliveWriter(ctx context.Context, w http.ResponseWriter, every time.Duration) *headKeepaliveWriter {
if every <= 0 {
return nil
}
cctx, cancel := context.WithCancel(ctx)
k := &headKeepaliveWriter{
ResponseWriter: w, every: every, cancel: cancel,
done: make(chan struct{}), firstFrame: make(chan struct{}),
}
go k.loop(cctx)
return k
}
// markStarted 记录「首个真实帧已写出」,并让心跳协程立刻退出(只第一次生效)。
func (k *headKeepaliveWriter) markStarted() {
k.committed.Store(true)
if k.started.CompareAndSwap(false, true) {
k.closeOnce.Do(func() { close(k.firstFrame) })
}
}
// loop 只在「还没有任何真实帧」时补注释;一旦 started 就退出。
func (k *headKeepaliveWriter) loop(ctx context.Context) {
defer close(k.done)
t := time.NewTicker(k.every)
defer t.Stop()
for {
select {
case <-ctx.Done():
return
case <-k.firstFrame:
// 真实帧已写出:心跳使命完成,协程立刻退出(长流里有上万个 tick,
// 留着空转只是白唤醒,而且会让热路径继续过锁)。
return
case <-t.C:
if k.started.Load() {
return
}
k.writeComment()
}
}
}
// writeComment 写一条注释帧。首次写前必须把 SSE 响应头补齐——注释帧会提交响应头,
// 之后再 Set 全部无效(Content-Type 会变成空,反代也可能开始缓冲)。
func (k *headKeepaliveWriter) writeComment() {
k.mu.Lock()
defer k.mu.Unlock()
if k.started.Load() { // 抢锁期间真实帧可能已经写出去
return
}
if !k.committed.Load() {
h := k.ResponseWriter.Header()
h.Set("Content-Type", "text/event-stream")
h.Set("Cache-Control", "no-cache")
h.Set("Connection", "keep-alive")
// 反代/网关(Caddy、EdgeOne、Cloudflare)按这个头决定不缓冲,缺了会让
// 注释帧攒在中间层,等于没发。
h.Set("X-Accel-Buffering", "no")
}
if _, err := k.ResponseWriter.Write([]byte(": keepalive\n\n")); err != nil {
return
}
k.committed.Store(true)
k.ticks.Add(1)
if f, ok := k.ResponseWriter.(http.Flusher); ok {
f.Flush()
}
}
// heartbeatOver 报告心跳协程是否已彻底退出。退出之后再也不可能有人写注释帧,
// 于是热路径可以完全跳过互斥锁(单请求上万帧时这是主要的包装开销)。
//
// 为什么不能直接用 started 判断:注释协程可能在「通过 in-lock 检查」之后、
// 「真正写出」之前被抢占,此时 started 已是 true,拿它当「可以免锁」的依据
// 会让两条 goroutine 同时进入底层 Write。done 只在协程 return 之后关闭,
// 语义上等价于「不会再有注释帧」,是唯一安全的无锁判据。
func (k *headKeepaliveWriter) heartbeatOver() bool {
select {
case <-k.done:
return true
default:
return false
}
}
// Write 真实数据帧:先进 started 再抢锁,保证注释帧不会插进这一帧的中间。
func (k *headKeepaliveWriter) Write(p []byte) (int, error) {
k.markStarted()
if k.heartbeatOver() {
return k.ResponseWriter.Write(p)
}
k.mu.Lock()
defer k.mu.Unlock()
return k.ResponseWriter.Write(p)
}
// Flush 透传 http.Flusher —— 不实现它 StreamHint 就拿不到 flusher,流式会被整段缓冲。
func (k *headKeepaliveWriter) Flush() {
f, ok := k.ResponseWriter.(http.Flusher)
if !ok {
return
}
if k.heartbeatOver() {
f.Flush()
return
}
k.mu.Lock()
defer k.mu.Unlock()
f.Flush()
}
// Unwrap 供 http.ResponseController 追到底层 writer(Go 1.20+ 的 Flush 探测路径)。
func (k *headKeepaliveWriter) Unwrap() http.ResponseWriter { return k.ResponseWriter }
// Committed 报告响应头是否已提交(= 已经写过字节,不能再回非 200 + JSON)。
func (k *headKeepaliveWriter) Committed() bool { return k.committed.Load() }
// Ticks 返回已发出的注释帧数。
func (k *headKeepaliveWriter) Ticks() int64 { return k.ticks.Load() }
// stop 结束心跳协程(幂等;正常路径也靠 ctx 结束,这里只是让测试可确定)。
func (k *headKeepaliveWriter) stop() {
if k == nil {
return
}
k.cancel()
<-k.done
}
// writeErrorFrame 在响应头已提交(注释帧已写出)时把失败收敛成协议内错误:
// 一条 error 帧 + 一条 [DONE],与 StreamHint「已开流只能 200」的兜底同形态。
// 调用方(writeOpenAIError*)据此不再写 JSON —— 往已提交的 SSE 流里塞 JSON
// 会让客户端收到既非帧也非 JSON 的脏数据。
func (k *headKeepaliveWriter) writeErrorFrame(status int, typ, code, msg, hint string) {
k.writeErrorFrameExtra(status, typ, code, msg, hint, nil)
}
// writeErrorFrameExtra 同 writeErrorFrame,另在 error 对象里附加 extra 字段。
// 响应头已提交后不能再改 HTTP 状态码,而有些客户端(ZCode)只按状态码/业务码
// 判「能不能重试」——把 statusCode=429 这类信号塞进协议内错误体,客户端才能
// 按可重试处理,而不是把整轮对话判死。
func (k *headKeepaliveWriter) writeErrorFrameExtra(status int, typ, code, msg, hint string, extra map[string]any) {
e := map[string]any{"message": msg, "type": typ, "code": code}
if hint != "" {
e["gateway_hint"] = hint
}
for key, v := range extra {
if _, exists := e[key]; !exists {
e[key] = v
}
}
body, err := json.Marshal(map[string]any{"error": e})
if err != nil {
return
}
_, _ = k.Write([]byte("data: " + string(body) + "\n\ndata: [DONE]\n\n"))
}
|