/**
|
* SSE 客户端封装。
|
*
|
* ## 为什么用 fetch 而不是浏览器原生 EventSource
|
*
|
* 文档最初设想用 EventSource,但 EventSource 有两个无法绕开的限制:
|
*
|
* 1. **不能自定义请求头**。它无法携带 `Authorization: Bearer`,
|
* 只能靠 URL query 传 token,而 URL 会进入 nginx access log、
|
* 浏览器历史与 Referer,是实打实的凭据泄露面。
|
* 2. **无法主动中断**。只有 `close()`,无法区分「用户点了停止」和
|
* 「网络断开」,也拿不到 HTTP 状态码与错误响应体 —— 后端返回的
|
* 「Ollama 未启动」这类有价值提示会被静默吞掉。
|
*
|
* `fetch` + `ReadableStream` 手动解析 SSE 能同时解决这两点,
|
* 且服务端协议完全不变(依然是 `text/event-stream` + `event:`/`data:` 帧),
|
* 后端不需要为前端实现方式做任何妥协。
|
*
|
* 若你确实需要用原生 EventSource,见文件末尾的 `streamChatViaEventSource`。
|
*/
|
|
const SSE_DATA_PREFIX = 'data:'
|
const SSE_EVENT_PREFIX = 'event:'
|
|
/**
|
* 建立 SSE 连接并流式消费事件。
|
*
|
* @param {object} options
|
* @param {string} options.url 请求地址(相对 /api 路径)
|
* @param {string} options.token JWT,放入 Authorization 头
|
* @param {(event: string, data: object) => void} options.onEvent 事件回调
|
* @param {(error: Error) => void} [options.onError] 错误回调
|
* @param {() => void} [options.onClose] 流正常结束回调
|
* @returns {{ abort: () => void }} 控制器,调用 abort() 中断连接
|
*/
|
export function streamChat({ url, token, onEvent, onError, onClose }) {
|
const controller = new AbortController()
|
// 用户主动中断的标志:用于在 catch 里区分「主动停止」与「真的出错」
|
let abortedByUser = false
|
|
/**
|
* 终止回调只允许触发一次。
|
*
|
* 这是修一个真实 bug 的关键:`abort()` 主动中断时,`reader.read()` 是否
|
* 会 reject 一个 AbortError 在不同浏览器/不同时刻表现并不一致 ——
|
* 有时它只是安静地返回 { done: true },于是 onClose 永远不触发,
|
* 调用方的 `streaming` 标志就卡在 true:发送按钮**永久变灰**,
|
* 必须刷新页面才能恢复。
|
*
|
* 因此不再依赖「异常是否抛出」来决定收尾,而是显式收口:
|
* abort() 立即结算,流自然结束也结算,谁先到算谁,只结算一次。
|
*/
|
let settled = false
|
|
const settle = (fn) => {
|
if (settled) return
|
settled = true
|
fn?.()
|
}
|
|
const run = async () => {
|
let response
|
try {
|
response = await fetch(url, {
|
method: 'GET',
|
headers: {
|
Accept: 'text/event-stream',
|
Authorization: `Bearer ${token}`
|
},
|
signal: controller.signal,
|
// 不使用 Cookie 认证,避免 CSRF 面
|
credentials: 'omit'
|
})
|
} catch (err) {
|
// 主动中断由 abort() 负责结算,这里直接返回,避免重复回调
|
if (abortedByUser || err.name === 'AbortError') {
|
return
|
}
|
settle(() => onError?.(new Error('无法建立连接,请确认后端服务已启动')))
|
return
|
}
|
|
// 后端在流开始前返回错误(如 401、404、400),此时是普通 JSON 响应
|
if (!response.ok) {
|
let message = `请求失败 (HTTP ${response.status})`
|
try {
|
const body = await response.json()
|
if (body?.msg) message = body.msg
|
} catch {
|
// 响应体不是 JSON,沿用默认提示
|
}
|
settle(() => onError?.(new Error(message)))
|
return
|
}
|
|
if (!response.body) {
|
settle(() => onError?.(new Error('当前浏览器不支持流式响应(ReadableStream 不可用)')))
|
return
|
}
|
|
const reader = response.body.getReader()
|
const decoder = new TextDecoder('utf-8')
|
// 跨 chunk 的残留数据:一个 SSE 帧可能被 TCP 分片切开
|
let buffer = ''
|
|
try {
|
while (true) {
|
const { done, value } = await reader.read()
|
if (done) break
|
|
buffer += decoder.decode(value, { stream: true })
|
|
// SSE 帧以空行分隔。把完整帧逐个取出来处理,剩余部分留回 buffer。
|
let separatorIndex
|
while ((separatorIndex = findFrameEnd(buffer)) !== -1) {
|
const rawFrame = buffer.slice(0, separatorIndex)
|
buffer = buffer.slice(separatorIndex).replace(/^(\r?\n){2}/, '')
|
handleFrame(rawFrame, onEvent)
|
}
|
}
|
|
// 处理最后一个可能没有以空行结尾的帧
|
if (buffer.trim()) {
|
handleFrame(buffer, onEvent)
|
}
|
|
settle(onClose)
|
} catch (err) {
|
// 主动中断已由 abort() 结算,这里静默返回
|
if (abortedByUser || err.name === 'AbortError') {
|
return
|
}
|
settle(() => onError?.(new Error(`读取流数据失败: ${err.message}`)))
|
} finally {
|
try {
|
reader.releaseLock()
|
} catch {
|
// 流已关闭,忽略
|
}
|
}
|
}
|
|
run()
|
|
return {
|
abort() {
|
abortedByUser = true
|
// 先中断网络请求,再立即结算 —— 不等待 reader.read() 抛错,
|
// 否则异常语义在浏览器间不一致时会漏掉收尾,导致 loading 卡死
|
controller.abort()
|
settle(onClose)
|
}
|
}
|
}
|
|
/**
|
* 找到第一个完整 SSE 帧的结束位置。
|
*
|
* 兼容 `\n\n` 与 `\r\n\r\n` 两种换行风格 ——
|
* 不同代理(nginx / 某些网关)会改写换行符。
|
*/
|
function findFrameEnd(text) {
|
const lf = text.indexOf('\n\n')
|
const crlf = text.indexOf('\r\n\r\n')
|
if (lf === -1) return crlf
|
if (crlf === -1) return lf
|
return Math.min(lf, crlf)
|
}
|
|
/**
|
* 解析单个 SSE 帧并触发回调。
|
*
|
* 帧格式:
|
* event: delta
|
* data: {"type":"delta","delta":"你"}
|
*
|
* 以 `:` 开头的行是注释(常用于心跳),直接忽略。
|
*/
|
function handleFrame(rawFrame, onEvent) {
|
let eventName = 'message'
|
const dataLines = []
|
|
for (const line of rawFrame.split(/\r?\n/)) {
|
if (!line || line.startsWith(':')) continue
|
|
if (line.startsWith(SSE_EVENT_PREFIX)) {
|
eventName = line.slice(SSE_EVENT_PREFIX.length).trim()
|
} else if (line.startsWith(SSE_DATA_PREFIX)) {
|
// 去掉前缀后的一个空格(规范允许 `data:foo` 与 `data: foo`)
|
dataLines.push(line.slice(SSE_DATA_PREFIX.length).replace(/^ /, ''))
|
}
|
}
|
|
if (dataLines.length === 0) return
|
|
const payload = dataLines.join('\n')
|
let parsed
|
try {
|
parsed = JSON.parse(payload)
|
} catch {
|
// 非 JSON 载荷(理论上本项目的后端不会这样发)按纯文本处理
|
parsed = { type: eventName, delta: payload }
|
}
|
|
onEvent?.(eventName, parsed)
|
}
|
|
/**
|
* 原生 EventSource 备用实现。
|
*
|
* **仅在你愿意接受 token 出现在 URL 中时使用。**
|
* 服务端已支持 `?token=` 认证(见 JwtAuthenticationFilter),
|
* 因此这个实现在功能上可用,但请务必:
|
* - 生产环境通过 nginx 关闭该路径 query 的日志记录
|
* - 强制 HTTPS,避免 token 明文传输
|
*
|
* @param {object} options
|
* @param {string} options.baseUrl 后端地址,如 'http://localhost:8080'
|
* @param {number} options.chatId
|
* @param {string} options.token
|
* @param {object} options.params query 参数:content/parentId/model/useRag
|
* @param {(event: string, data: object) => void} options.onEvent
|
* @param {(error: Error) => void} [options.onError]
|
*/
|
export function streamChatViaEventSource({
|
baseUrl = '',
|
chatId,
|
token,
|
params,
|
onEvent,
|
onError
|
}) {
|
const query = new URLSearchParams({
|
...params,
|
token
|
})
|
const url = `${baseUrl}/api/chats/${chatId}/stream?${query.toString()}`
|
|
const source = new EventSource(url)
|
|
// 逐个注册后端约定的事件类型。
|
// EventSource 不提供「监听所有事件」的能力,必须显式列出。
|
for (const eventName of ['start', 'delta', 'title', 'done', 'error']) {
|
source.addEventListener(eventName, (event) => {
|
try {
|
onEvent?.(eventName, JSON.parse(event.data))
|
} catch (err) {
|
onError?.(new Error(`解析 ${eventName} 事件失败: ${err.message}`))
|
}
|
// done / error 之后流已结束,主动关闭以释放后端 SseEmitter
|
if (eventName === 'done' || eventName === 'error') {
|
source.close()
|
}
|
})
|
}
|
|
source.onerror = () => {
|
// EventSource 会自动重连,但对话流不该重连(会重复生成)。
|
// 因此这里直接关闭并把控制权交给上层。
|
source.close()
|
onError?.(new Error('SSE 连接中断'))
|
}
|
|
return {
|
abort() {
|
source.close()
|
}
|
}
|
}
|