diff --git a/README.md b/README.md index 5b688af..0153bdc 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,21 @@ as well as to custom React-based frontends that handle message rendering themsel In order to support the streaming of responses, when the MetadataEvent `TOCK_STREAM_RESPONSE` is set to true, a message with the same responseId will be replaced with the new version of the message. +The streaming contract (metadata of a response envelope): + +| Metadata | Meaning | +|---|---| +| `TOCK_STREAM_PARTIAL=true` | Transient frame of an answer being generated. Not counted as a consumed message and not stored in the local history. | +| `TOCK_STREAM_REPLACE=` | Final response: only the message whose `actionId` matches replaces the streamed bubble, the other messages are added in order. | +| `TOCK_STREAM_DISCARD=true` | The final response has no text: the streamed bubble is removed. | +| `TOCK_REQUEST_ID` | Identifier sent by the kit as `requestId` with each question and echoed on every frame. Frames of another in-flight request are ignored. | + +By default, each streamed frame carries the whole text received so far. With the `streamMode: 'delta'` option, the kit adds `"streamMode": "delta"` to its requests; the server then sends frames flagged with the MetadataEvent `TOCK_STREAM_MODE` set to `delta`, whose text is only the end of the (already rendered) text. `TOCK_STREAM_KEEP` gives the number of characters of the current message to keep before appending it, so that the displayed text is the same as in the default mode. The final response always carries the complete text and replaces the message. Servers that do not support this option ignore it. + +Frames flagged `TOCK_STREAM_PARTIAL` do not count as messages consumed from the POST response; every other SSE frame does, so that the POST response only adds the messages not already received over SSE. A `TOCK_STREAM_DISCARD` frame carries no message and counts for none. + +Note: a delta frame received while no streamed bubble exists yet displays only its fragment until the final response replaces it. An invalid `TOCK_STREAM_KEEP` is ignored and the message waits for the final response. + ## API Reference @@ -382,6 +397,7 @@ Objects implementing this interface can be passed to `renderChat` or to `TockCon |------------------------|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `disableSse` | `boolean?` | If `true`, disables any SSE connection attempt | | `extraHeadersProvider` | `() => Promise>?` | Provides extra HTTP headers for outgoing requests | +| `streamMode` | `'delta'?` | If `'delta'`, asks the server to stream only the new fragments of a response instead of the whole text so far (see [Streamed responses](#streamed-responses)) | | `retryOnPingTimeoutMs` | `number?` | If SSE is enabled, when this duration in milliseconds elapses without receiving ping events from the backend, the SSE connection is considered to be in an error state and gets restarted | #### `RendererSettings` @@ -461,6 +477,7 @@ Contains all the properties from [`TockSettings`](#tocksettings) as well as the | `timeoutBetweenMessage` | `number?` | Timeout between message | | `widgets` | `any?` | Custom display component | | `disableSse` | `boolean?` | Disable SSE (not even trying) | +| `streamMode` | `'delta'?` | Ask the server to stream only new fragments (see [Streamed responses](#streamed-responses)) | | `accessibility` | `TockAccessibility` | Object for overriding role and label accessibility attributes | | `localStorageHistory` | `TockLocalStorage?` | Object for history local storage | diff --git a/src/TockOptions.ts b/src/TockOptions.ts index 7728637..360e493 100644 --- a/src/TockOptions.ts +++ b/src/TockOptions.ts @@ -15,6 +15,7 @@ export interface TockOptions extends TockOptionalSettings { timeoutBetweenMessage?: number; widgets?: { [id: string]: (props: unknown) => JSX.Element }; disableSse?: boolean; + streamMode?: 'delta'; accessibility?: TockAccessibility; localStorageHistory?: TockLocalStorage; } diff --git a/src/TockState.tsx b/src/TockState.tsx index d2e17c0..246bf44 100644 --- a/src/TockState.tsx +++ b/src/TockState.tsx @@ -1,6 +1,7 @@ import { Context, createContext, Dispatch, Reducer, useContext } from 'react'; import { QuickReply } from './model/buttons'; -import { Message } from './model/messages'; +import { Message, MessageType } from './model/messages'; +import { parseKeep } from './streaming'; export const TockStateContext: Context = createContext< TockState | undefined @@ -40,6 +41,7 @@ export interface TockAction { | 'SET_QUICKREPLIES' | 'ADD_MESSAGE' | 'UPDATE_MESSAGE' + | 'DISCARD_STREAMED_MESSAGE' | 'SET_METADATA' | 'SET_LOADING' | 'SET_SSE_INITIALIZING' @@ -47,6 +49,7 @@ export interface TockAction { | 'SET_ERROR'; quickReplies?: QuickReply[]; messages?: Message[]; + responseId?: string; loading?: boolean; sseInitializing?: boolean; metadata?: Record; @@ -81,28 +84,50 @@ export const tockReducer: Reducer = ( if (action.messages) { let messageAlreadyExists = false; - const newMessages = state.messages.map((message) => { + const newMessages = state.messages.map((current) => { // Search if a streamed message with the same responseId already exists - const messageExists = action.messages?.find((m) => { - const isMessageExists = - m.metadata?.RESPONSE_ID === message.metadata?.RESPONSE_ID && + const incoming = action.messages?.find((m) => { + const exists = + m.metadata?.RESPONSE_ID === current.metadata?.RESPONSE_ID && m.metadata?.TOCK_STREAM_RESPONSE === 'true' && - message.metadata?.TOCK_STREAM_RESPONSE === 'true'; + current.metadata?.TOCK_STREAM_RESPONSE === 'true'; - if (isMessageExists) { + if (exists) { messageAlreadyExists = true; } - return isMessageExists; + return exists; }); - // If the message already exists, replace with the new message - if (messageExists) { - return messageExists; + // If the message already exists, replace it with the new message, + // or append the fragment to it when the server streams deltas + if (incoming) { + if ( + incoming.metadata?.TOCK_STREAM_MODE === 'delta' && + current.type === MessageType.message && + incoming.type === MessageType.message + ) { + // Desynchronized stream: wait for the final response + if (current.metadata?.TOCK_STREAM_DESYNC === 'true') { + return current; + } + const keep = parseKeep(incoming.metadata?.TOCK_STREAM_KEEP); + if (keep === undefined || keep > current.message.length) { + return { + ...current, + metadata: { ...current.metadata, TOCK_STREAM_DESYNC: 'true' }, + }; + } + return { + ...incoming, + message: current.message.slice(0, keep) + incoming.message, + }; + } + return incoming; } // Else return the original message - return message; + return current; }); // If the message is new, add it to the messages @@ -138,6 +163,20 @@ export const tockReducer: Reducer = ( }; } break; + case 'DISCARD_STREAMED_MESSAGE': + if (action.responseId) { + return { + ...state, + messages: state.messages.filter( + (m) => + !( + m.metadata?.RESPONSE_ID === action.responseId && + m.metadata?.TOCK_STREAM_RESPONSE === 'true' + ), + ), + }; + } + break; case 'SET_LOADING': if (action.loading != undefined) { return { diff --git a/src/model/responses.ts b/src/model/responses.ts index 3aa58ed..8e1930b 100644 --- a/src/model/responses.ts +++ b/src/model/responses.ts @@ -16,6 +16,7 @@ export interface BotConnectorMessage { widget?: BotConnectorWidget; image?: BotConnectorImage; deepLink?: string; + actionId?: string; } export interface BotConnectorCard { diff --git a/src/renderChat.tsx b/src/renderChat.tsx index b12f32b..b2086ed 100644 --- a/src/renderChat.tsx +++ b/src/renderChat.tsx @@ -44,6 +44,9 @@ export const renderChat: ( if (options.disableSse) { network.disableSse = true; } + if (options.streamMode) { + network.streamMode = options.streamMode; + } if (options.extraHeadersProvider) { network.extraHeadersProvider = options.extraHeadersProvider; } diff --git a/src/settings/TockSettings.tsx b/src/settings/TockSettings.tsx index c33877e..0a75bcc 100644 --- a/src/settings/TockSettings.tsx +++ b/src/settings/TockSettings.tsx @@ -11,6 +11,7 @@ export interface LocalStorageSettings { export interface NetworkSettings { disableSse: boolean; + streamMode?: 'delta'; retryOnPingTimeoutMs: number; extraHeadersProvider?: () => Promise>; } diff --git a/src/streaming.ts b/src/streaming.ts new file mode 100644 index 0000000..7fb74d3 --- /dev/null +++ b/src/streaming.ts @@ -0,0 +1,72 @@ +import { BotConnectorResponse } from './model/responses'; + +type Metadata = Record | undefined; + +/** + * Streaming contract of the Tock web connector (metadata of a response envelope): + * - `TOCK_STREAM_RESPONSE=true`: the message replaces the one with the same `RESPONSE_ID`; + * - `TOCK_STREAM_PARTIAL=true`: transient frame of an answer being generated (never counted, never recorded); + * - `TOCK_STREAM_REPLACE=`: the final message that replaces the streamed bubble, the others are added; + * - `TOCK_STREAM_DISCARD=true`: the streamed bubble must be removed; + * - `TOCK_REQUEST_ID`: identifier sent by the client with the question, echoed on every frame. + */ +export const isPartialFrame = (metadata: Metadata): boolean => + metadata?.TOCK_STREAM_PARTIAL === 'true'; + +export const isDiscardFrame = (metadata: Metadata): boolean => + metadata?.TOCK_STREAM_DISCARD === 'true'; + +/** True for the frames of the contract that designates (or removes) the streamed bubble. */ +export const usesStreamContract = (metadata: Metadata): boolean => + isPartialFrame(metadata) || + isDiscardFrame(metadata) || + metadata?.TOCK_STREAM_REPLACE !== undefined; + +/** Metadata of a message that must not behave as the streamed bubble (stream flags removed). */ +export const withoutStreamFlags = ( + metadata: Record | undefined, +): Record | undefined => { + if (!metadata) return metadata; + const { + TOCK_STREAM_RESPONSE: _response, + TOCK_STREAM_PARTIAL: _partial, + TOCK_STREAM_REPLACE: _replace, + TOCK_STREAM_DISCARD: _discard, + TOCK_STREAM_MODE: _mode, + TOCK_STREAM_KEEP: _keep, + ...rest + } = metadata; + return rest; +}; + +/** Parses TOCK_STREAM_KEEP: a non-negative integer, otherwise undefined. */ +export const parseKeep = (value: string | undefined): number | undefined => + value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined; + +/** + * A frame is correlated to a request (`TOCK_REQUEST_ID`) that this client is not + * handling, so it must be ignored. The rule is stable for the whole lifetime of a + * stream: a correlated frame is accepted only while its request is in flight here. + * + * It is deliberately NOT gated on `inFlightRequestIds.size > 0`: otherwise an idle + * tab (no request in flight) would accept a foreign tab's partial frames, then start + * rejecting the rest the moment it sends its own question — leaving an orphan + * provisional bubble that is never finalized nor recorded. For the same reason, a late + * frame arriving after the local request completed (success or error — the id is then + * removed from the in-flight set) is treated as foreign and dropped, so it cannot + * revive a closed/errored request. + * + * Frames without a request identifier (e.g. notifications) always pass. + */ +export const isFrameOfOtherRequest = ( + botResponse: BotConnectorResponse, + inFlightRequestIds: ReadonlySet, +): boolean => { + const requestId = botResponse.metadata?.TOCK_REQUEST_ID; + return !!requestId && !inFlightRequestIds.has(requestId); +}; + +export const newRequestId = (): string => + typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function' + ? crypto.randomUUID() + : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`; diff --git a/src/useTock.ts b/src/useTock.ts index 59546d7..a46806e 100644 --- a/src/useTock.ts +++ b/src/useTock.ts @@ -36,6 +36,14 @@ import { } from './model/responses'; import TockSettings from './settings/TockSettings'; import { TockEventSource } from './network/TockEventSource'; +import { + isDiscardFrame, + isFrameOfOtherRequest, + isPartialFrame, + newRequestId, + usesStreamContract, + withoutStreamFlags, +} from './streaming'; export interface UseTock { messages: Message[]; @@ -164,8 +172,10 @@ export const useTock0: ( const localStoragePrefix = localStorageSettings.prefix; const disableSse = disableSseArg ?? networkSettings.disableSse; const retryOnPingTimeoutMs = networkSettings.retryOnPingTimeoutMs; + const streamMode = networkSettings.streamMode; const { clearMessages }: UseLocalTools = useLocalTools(localStorageEnabled); const handledResponses = useRef>({}); + const inFlightRequestIds = useRef>(new Set()); const afterInit = useRef(() => {}); const afterInitPromise = useRef( new Promise((resolve) => { @@ -206,10 +216,31 @@ export const useTock0: ( } else { history = JSON.parse(savedHistory); } - if (history.length >= localStorageMaxMessages) { - history.splice(0, history.length - localStorageMaxMessages + 1); + let streamedIndex = -1; + if ( + message.metadata?.TOCK_STREAM_RESPONSE === 'true' && + message.metadata?.RESPONSE_ID + ) { + for (let i = history.length - 1; i >= 0; i--) { + const m = history[i].metadata; + if ( + m?.TOCK_STREAM_RESPONSE === 'true' && + m?.RESPONSE_ID === message.metadata.RESPONSE_ID + ) { + streamedIndex = i; + break; + } + } + } + if (streamedIndex >= 0) { + // A new version of an already recorded streamed message replaces it + history[streamedIndex] = message; + } else { + history.push(message); + } + if (history.length > localStorageMaxMessages) { + history.splice(0, history.length - localStorageMaxMessages); } - history.push(message); window.localStorage.setItem( messageHistoryLSKeyName, JSON.stringify(history), @@ -227,6 +258,13 @@ export const useTock0: ( metadata: metadata || {}, }); + if (isDiscardFrame(metadata)) { + dispatch({ + type: 'DISCARD_STREAMED_MESSAGE', + responseId: metadata?.RESPONSE_ID, + }); + } + if (Array.isArray(responses) && responses.length > 0) { const lastMessage = responses[responses.length - 1]; const quickReplies = (lastMessage.buttons || []) @@ -248,50 +286,73 @@ export const useTock0: ( ); } - dispatch({ - type: - metadata?.TOCK_STREAM_RESPONSE === 'true' - ? 'UPDATE_MESSAGE' - : 'ADD_MESSAGE', - messages: responses.flatMap((response) => { - const { text, card, carousel, widget, image, buttons } = response; - let message: Message; - if (widget) { - message = { - widgetData: widget, - type: MessageType.widget, - } as Widget; - } else if (text !== undefined) { - message = { - author: 'bot', - message: text, - type: MessageType.message, - buttons: (buttons || []) - .filter((button) => button.type !== 'quick_reply') - .map(mapButton), - } as TextMessage; - } else if (card) { - message = mapCard(card); - } else if (image) { - message = mapImage(image); - } else if (carousel) { - message = { - cards: carousel.cards.map(mapCard), - type: MessageType.carousel, - } as Carousel; - } else { - console.error('Unsupported bot response', response); - return []; - } - - message.metadata = metadata; - - if (localStorageEnabled) { - recordResponseToLocalSession(message); - } - return [message]; - }), + const contract = usesStreamContract(metadata); + const partial = isPartialFrame(metadata); + const replaceId = metadata?.TOCK_STREAM_REPLACE; + const legacyStreamed = + !contract && metadata?.TOCK_STREAM_RESPONSE === 'true'; + const updates: Message[] = []; + const additions: Message[] = []; + + responses.forEach((response) => { + const { text, card, carousel, widget, image, buttons } = response; + let message: Message; + if (widget) { + message = { + widgetData: widget, + type: MessageType.widget, + } as Widget; + } else if (text !== undefined) { + message = { + author: 'bot', + message: text, + type: MessageType.message, + buttons: (buttons || []) + .filter((button) => button.type !== 'quick_reply') + .map(mapButton), + } as TextMessage; + } else if (card) { + message = mapCard(card); + } else if (image) { + message = mapImage(image); + } else if (carousel) { + message = { + cards: carousel.cards.map(mapCard), + type: MessageType.carousel, + } as Carousel; + } else { + console.error('Unsupported bot response', response); + return; + } + + // Only the designated entry replaces the streamed bubble: the other + // messages of the response are ordinary messages + const replacesBubble = + partial || + legacyStreamed || + (replaceId !== undefined && response.actionId === replaceId); + message.metadata = + contract && !replacesBubble + ? withoutStreamFlags(metadata) + : metadata; + + // Partial frames are transient: only the final response is recorded + if ( + localStorageEnabled && + !partial && + metadata?.TOCK_STREAM_MODE !== 'delta' + ) { + recordResponseToLocalSession(message); + } + (replacesBubble ? updates : additions).push(message); }); + + if (updates.length > 0) { + dispatch({ type: 'UPDATE_MESSAGE', messages: updates }); + } + if (additions.length > 0) { + dispatch({ type: 'ADD_MESSAGE', messages: additions }); + } } }, [dispatch], @@ -352,10 +413,19 @@ export const useTock0: ( const handleSseBotResponse: (botResponse: BotConnectorResponse) => void = ( botResponse, ) => { + if (isFrameOfOtherRequest(botResponse, inFlightRequestIds.current)) { + return; + } const responseId = botResponse.metadata?.['RESPONSE_ID']; if (!responseId) { // no identifier -> always handle with SSE handleBotResponse(botResponse); + } else if (isPartialFrame(botResponse.metadata)) { + // A partial frame is a transient version of the answer, replaced by the next frame: + // it does not count as a message consumed from the POST response + if ((handledResponses.current[responseId] ?? 0) >= 0) { + handleBotResponse(botResponse); + } } else { const processedMessageCount = handledResponses.current[responseId] ?? 0; if (processedMessageCount >= 0) { @@ -444,17 +514,15 @@ export const useTock0: ( }); } startLoading(); - const body = payload - ? { - payload, - userId, - locale, - } - : { - query: message, - userId, - locale, - }; + const requestId = newRequestId(); + inFlightRequestIds.current.add(requestId); + const body = { + ...(payload ? { payload } : { query: message }), + userId, + locale, + requestId, + ...(streamMode ? { streamMode } : {}), + }; return fetch(tockEndPoint, { body: JSON.stringify(body), @@ -466,9 +534,12 @@ export const useTock0: ( }) .then((res) => res.json()) .then(handlePostBotResponse, handleError) - .finally(stopLoading); + .finally(() => { + inFlightRequestIds.current.delete(requestId); + stopLoading(); + }); }, - [locale], + [locale, streamMode], ); const sendReferralParameter: (referralParameter: string) => Promise =