diff --git a/core/application/application.go b/core/application/application.go index 77162af9b..2efe929fb 100644 --- a/core/application/application.go +++ b/core/application/application.go @@ -15,6 +15,7 @@ import ( mcpTools "github.com/mudler/LocalAI/core/http/endpoints/mcp" "github.com/mudler/LocalAI/core/services/advisorylock" "github.com/mudler/LocalAI/core/services/agentpool" + "github.com/mudler/LocalAI/core/services/chathistory" "github.com/mudler/LocalAI/core/services/cloudproxy/mitm" "github.com/mudler/LocalAI/core/services/facerecognition" "github.com/mudler/LocalAI/core/services/failover" @@ -69,6 +70,7 @@ type Application struct { faceRegistry facerecognition.Registry voiceRegistry voicerecognition.Registry voiceProfileStore *voiceprofile.Store + chatHistoryStore *chathistory.Store authDB *gorm.DB metricsService *monitoring.LocalAIMetricsService statsRecorder *billing.Recorder @@ -291,6 +293,13 @@ func (a *Application) VoiceProfileStore() *voiceprofile.Store { return a.voiceProfileStore } +// ChatHistoryStore returns the server-side WebUI chat history store, or nil +// when the feature is disabled (LOCALAI_DISABLE_WEBUI=true or persistence +// path could not be resolved). +func (a *Application) ChatHistoryStore() *chathistory.Store { + return a.chatHistoryStore +} + // AuthDB returns the auth database connection, or nil if auth is not enabled. func (a *Application) AuthDB() *gorm.DB { return a.authDB @@ -667,6 +676,21 @@ func (a *Application) start() error { a.agentJobService = agentJobService + // Initialize chat history store for the WebUI (issue #9432). Reuses the + // shared auth database so per-user chat history sits alongside agent + // configs and jobs in one place — mudler's review on #9902 called out + // the file-based store as inconsistent with the rest of LocalAI's + // per-user state. When auth is disabled the store stays nil and the + // React UI falls back to localStorage. + if !a.applicationConfig.DisableWebUI && a.authDB != nil { + store, err := chathistory.New(a.authDB) + if err != nil { + xlog.Warn("Chat history persistence disabled: failed to initialise store", "error", err) + } else { + a.chatHistoryStore = store + } + } + return nil } diff --git a/core/http/app.go b/core/http/app.go index f4eca97b8..93afede12 100644 --- a/core/http/app.go +++ b/core/http/app.go @@ -193,6 +193,8 @@ func setModelLoadingRetryAfter(loadErr *nodes.ModelLoadingError, c echo.Context) // @tag.description Document reranking // @tag.name instructions // @tag.description API instruction discovery — browse instruction areas and get endpoint guides +// @tag.name chat-history +// @tag.description Server-side persistence of WebUI chat conversations func API(application *application.Application) (*echo.Echo, error) { e := echo.New() @@ -512,7 +514,8 @@ func API(application *application.Application) (*echo.Echo, error) { } mcpMw := auth.RequireFeature(application.AuthDB(), auth.FeatureMCP) - routes.RegisterLocalAIRoutes(e, requestExtractor, application.ModelConfigLoader(), application.ModelLoader(), application.ApplicationConfig(), application.GalleryService(), opcache, application.TemplatesEvaluator(), application, adminMiddleware, mcpJobsMw, mcpMw) + chatHistoryMw := auth.RequireFeature(application.AuthDB(), auth.FeatureChatHistory) + routes.RegisterLocalAIRoutes(e, requestExtractor, application.ModelConfigLoader(), application.ModelLoader(), application.ApplicationConfig(), application.GalleryService(), opcache, application.TemplatesEvaluator(), application, adminMiddleware, mcpJobsMw, mcpMw, chatHistoryMw) routes.RegisterAgentPoolRoutes(e, application, agentsMw, skillsMw, collectionsMw) // Fine-tuning routes fineTuningMw := auth.RequireFeature(application.AuthDB(), auth.FeatureFineTuning) diff --git a/core/http/auth/features.go b/core/http/auth/features.go index 4ed5f9aed..9788e3982 100644 --- a/core/http/auth/features.go +++ b/core/http/auth/features.go @@ -158,6 +158,15 @@ var RouteFeatureRegistry = []RouteFeature{ {"POST", "/api/pii/analyze", FeaturePIIFilter}, {"POST", "/api/pii/redact", FeaturePIIFilter}, + // Chat History (server-side persistence of WebUI conversations, #9432) + {"GET", "/api/conversations", FeatureChatHistory}, + {"DELETE", "/api/conversations", FeatureChatHistory}, + {"POST", "/api/conversations", FeatureChatHistory}, + {"PUT", "/api/conversations/bulk", FeatureChatHistory}, + {"GET", "/api/conversations/:id", FeatureChatHistory}, + {"PUT", "/api/conversations/:id", FeatureChatHistory}, + {"DELETE", "/api/conversations/:id", FeatureChatHistory}, + // Quantization {"POST", "/api/quantization/jobs", FeatureQuantization}, {"GET", "/api/quantization/jobs", FeatureQuantization}, @@ -222,5 +231,6 @@ func APIFeatureMetas() []FeatureMeta { {FeatureAudioTransform, "Audio Transform", true}, {FeaturePIIFilter, "PII Analyze / Redact", true}, {FeatureDecisions, "Decisions", true}, + {FeatureChatHistory, "Chat History", true}, } } diff --git a/core/http/auth/permissions.go b/core/http/auth/permissions.go index 58ccaaa85..e65474c0d 100644 --- a/core/http/auth/permissions.go +++ b/core/http/auth/permissions.go @@ -64,7 +64,8 @@ const ( // FeaturePIIFilter gates the synchronous PII analyze/redact service // (POST /api/pii/{analyze,redact}). Default ON like the other API // features; the admin-only events log is gated separately in-handler. - FeaturePIIFilter = "pii_filter" + FeaturePIIFilter = "pii_filter" + FeatureChatHistory = "chat_history" ) // AgentFeatures lists agent-related features (default OFF). @@ -81,6 +82,7 @@ var APIFeatures = []string{ FeatureRealtime, FeatureModeration, FeatureRerank, FeatureTokenize, FeatureMCP, FeatureStores, FeatureFaceRecognition, FeatureVoiceRecognition, FeatureAudioTransform, FeaturePIIFilter, FeatureDecisions, + FeatureChatHistory, } // AllFeatures lists all known features (used by UI and validation). diff --git a/core/http/endpoints/localai/api_instructions.go b/core/http/endpoints/localai/api_instructions.go index a84119d90..6d657641a 100644 --- a/core/http/endpoints/localai/api_instructions.go +++ b/core/http/endpoints/localai/api_instructions.go @@ -149,6 +149,12 @@ var instructionDefs = []instructionDef{ Tags: []string{"router"}, Intro: "Add a `router:` block to a ModelConfig to turn it into a routing model. The block declares a classifier (`score` — a small model ranks each policy label, Arch-Router-style; `colbert` — a reranker scores policy descriptions against the prompt; `knn` — similarity-weighted vote over a curated corpus of labelled example prompts), `policies` (the label vocabulary), `candidates` (downstream model + labels it serves; first candidate whose labels cover the active set wins, so order small → large), and a `fallback`. The knn classifier needs a `knn: { embedding_model }` block instead of a classifier_model, and reads a persisted corpus seeded via POST /api/router/{name}/corpus with `{entries: [{text, labels}]}` (admin-only; texts are embedded server-side, persisted under the state dir, and NEVER returned by any endpoint — GET /api/router/{name}/corpus/stats reports label counts only, DELETE /api/router/{name}/corpus wipes it). knn routes to the fallback whenever the prompt is less similar than knn.similarity_threshold to every corpus entry — out-of-corpus prompts are treated as undecidable rather than guessed. When a client addresses the routing model, the RouteModel middleware invokes the classifier, picks a candidate, and rewrites input.Model — the standard model-resolution path then runs ACL, disabled-state, and per-model PII against the chosen target. Depth-1 invariant: candidates must NOT themselves carry a `router:` block; runtime check returns 500 on violation. Decisions are logged to GET /api/router/decisions and surfaced in the /app/middleware Routing tab. POST /api/router/decide is the programmatic decision-oracle: external routers (e.g. an organisation-wide router service) send `{router, input}` and receive the classifier's label set + candidate model WITHOUT LocalAI rewriting, forwarding, or recording the call. Shares the classifier cache with the in-band path so warm-up costs are paid once.", }, + { + Name: "chat-history", + Description: "Server-side persistence of WebUI chat conversations", + Tags: []string{"chat-history"}, + Intro: "Per-user CRUD over chat conversations; only registered when user auth is enabled, and gated by the `chat_history` feature. POST /api/conversations and PUT /api/conversations/{id} upsert and return the conversation with a server-assigned `version` (1 on the first save, +1 per write). createdAt/updatedAt are client Unix milliseconds stored as sent, so clients compare updatedAt to pick the newer copy. Deletes are final: DELETE leaves a tombstone (idempotent, also for ids never saved), any later write of that id returns 410 Gone, and GET /api/conversations returns tombstones under `deleted` so a client drops stale local copies instead of re-uploading them. PUT /api/conversations/bulk makes the payload the live set (others are tombstoned) and reports refused deleted ids in `skipped`.", + }, } // swaggerState holds parsed swagger spec data, initialised once. diff --git a/core/http/endpoints/localai/api_instructions_test.go b/core/http/endpoints/localai/api_instructions_test.go index 54ed7c21e..719a8c91f 100644 --- a/core/http/endpoints/localai/api_instructions_test.go +++ b/core/http/endpoints/localai/api_instructions_test.go @@ -39,7 +39,7 @@ var _ = Describe("API Instructions Endpoints", func() { instructions, ok := resp["instructions"].([]any) Expect(ok).To(BeTrue()) - Expect(instructions).To(HaveLen(22)) + Expect(instructions).To(HaveLen(23)) // Verify each instruction has required fields and correct URL format for _, s := range instructions { @@ -83,6 +83,7 @@ var _ = Describe("API Instructions Endpoints", func() { "3d", "failover", "decisions", + "chat-history", "motion", )) }) diff --git a/core/http/endpoints/localai/chat_history.go b/core/http/endpoints/localai/chat_history.go new file mode 100644 index 000000000..f407f5e2d --- /dev/null +++ b/core/http/endpoints/localai/chat_history.go @@ -0,0 +1,189 @@ +package localai + +import ( + "errors" + "net/http" + + "github.com/labstack/echo/v4" + "github.com/mudler/LocalAI/core/schema" + "github.com/mudler/LocalAI/core/services/chathistory" +) + +// chatHistoryError maps store errors onto HTTP status codes. A deleted +// conversation is 410 Gone, so a client holding a stale copy can tell it +// apart from a transient failure and drop the copy instead of retrying. +func chatHistoryError(c echo.Context, err error) error { + switch { + case errors.Is(err, chathistory.ErrInvalidID), errors.Is(err, chathistory.ErrInvalidUserID): + return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()}) + case errors.Is(err, chathistory.ErrNotFound): + return c.JSON(http.StatusNotFound, map[string]string{"error": err.Error()}) + case errors.Is(err, chathistory.ErrDeleted): + return c.JSON(http.StatusGone, map[string]string{"error": err.Error()}) + case errors.Is(err, chathistory.ErrConflict): + return c.JSON(http.StatusConflict, map[string]string{"error": err.Error()}) + default: + return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()}) + } +} + +// ListConversationsEndpoint lists the current user's conversations, plus the +// ids of conversations the user deleted (tombstones). +// +// @Summary List chat conversations +// @Description Returns the live conversations, newest first, and in `deleted` the conversations the user deleted. A client must drop any local copy whose id appears in `deleted` instead of uploading it again. +// @Tags chat-history +// @Produce json +// @Success 200 {object} schema.ConversationList +// @Router /api/conversations [get] +func ListConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + userID := getUserID(c) + convs, err := store.List(userID) + if err != nil { + return chatHistoryError(c, err) + } + deleted, err := store.Tombstones(userID) + if err != nil { + return chatHistoryError(c, err) + } + return c.JSON(http.StatusOK, schema.ConversationList{Conversations: convs, Deleted: deleted}) + } +} + +// GetConversationEndpoint returns a single conversation by ID. +// +// @Summary Get a chat conversation +// @Tags chat-history +// @Produce json +// @Param id path string true "Conversation ID" +// @Success 200 {object} schema.Conversation +// @Failure 404 {object} map[string]string "Never existed" +// @Failure 410 {object} map[string]string "Deleted" +// @Router /api/conversations/{id} [get] +func GetConversationEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + conv, err := store.Get(getUserID(c), c.Param("id")) + if err != nil { + return chatHistoryError(c, err) + } + return c.JSON(http.StatusOK, conv) + } +} + +// SaveConversationEndpoint upserts a conversation. The body's id field is the +// canonical identifier; a path id is also accepted and overrides the body +// when both are present (so PUT /api/conversations/ works as expected). +// +// @Summary Save a chat conversation (upsert) +// @Description Stores the conversation and returns it with its new server-assigned `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back. +// @Tags chat-history +// @Accept json +// @Produce json +// @Param body body schema.Conversation true "Conversation payload" +// @Success 200 {object} schema.Conversation +// @Failure 400 {object} map[string]string "Invalid id or body" +// @Failure 410 {object} map[string]string "Deleted" +// @Router /api/conversations [post] +func SaveConversationEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + var conv schema.Conversation + if err := c.Bind(&conv); err != nil { + return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()}) + } + if pathID := c.Param("id"); pathID != "" { + conv.ID = pathID + } + saved, err := store.Save(getUserID(c), conv) + if err != nil { + return chatHistoryError(c, err) + } + return c.JSON(http.StatusOK, saved) + } +} + +// SaveConversationByIDEndpoint is SaveConversationEndpoint under its own +// name so the PUT route gets its own swagger entry. +// +// @Summary Save a chat conversation by id (upsert) +// @Tags chat-history +// @Accept json +// @Produce json +// @Param id path string true "Conversation ID (overrides the body id)" +// @Param body body schema.Conversation true "Conversation payload" +// @Success 200 {object} schema.Conversation +// @Failure 400 {object} map[string]string "Invalid id or body" +// @Failure 410 {object} map[string]string "Deleted" +// @Router /api/conversations/{id} [put] +func SaveConversationByIDEndpoint(store *chathistory.Store) echo.HandlerFunc { + return SaveConversationEndpoint(store) +} + +// BulkReplaceConversationsEndpoint replaces the user's live conversation set +// in one transaction. +// +// @Summary Replace all chat conversations +// @Description Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in `skipped`. +// @Tags chat-history +// @Accept json +// @Produce json +// @Param body body schema.ConversationBulkRequest true "Conversations" +// @Success 200 {object} schema.ConversationBulkResponse +// @Failure 400 {object} map[string]string "Invalid id or body" +// @Router /api/conversations/bulk [put] +func BulkReplaceConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + var payload schema.ConversationBulkRequest + if err := c.Bind(&payload); err != nil { + return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()}) + } + skipped, err := store.ReplaceAll(getUserID(c), payload.Conversations) + if err != nil { + return chatHistoryError(c, err) + } + if skipped == nil { + skipped = []string{} + } + return c.JSON(http.StatusOK, schema.ConversationBulkResponse{ + Status: "ok", + Count: len(payload.Conversations) - len(skipped), + Skipped: skipped, + }) + } +} + +// DeleteConversationEndpoint deletes a single conversation, leaving a +// tombstone. Idempotent. +// +// @Summary Delete a chat conversation +// @Description Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds. +// @Tags chat-history +// @Produce json +// @Param id path string true "Conversation ID" +// @Success 200 {object} map[string]string +// @Failure 400 {object} map[string]string "Invalid id" +// @Router /api/conversations/{id} [delete] +func DeleteConversationEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + if err := store.Delete(getUserID(c), c.Param("id")); err != nil { + return chatHistoryError(c, err) + } + return c.JSON(http.StatusOK, map[string]string{"status": "ok"}) + } +} + +// DeleteAllConversationsEndpoint deletes the user's entire chat history. +// +// @Summary Delete all chat conversations for the current user +// @Tags chat-history +// @Produce json +// @Success 200 {object} map[string]string +// @Router /api/conversations [delete] +func DeleteAllConversationsEndpoint(store *chathistory.Store) echo.HandlerFunc { + return func(c echo.Context) error { + if err := store.DeleteAll(getUserID(c)); err != nil { + return chatHistoryError(c, err) + } + return c.JSON(http.StatusOK, map[string]string{"status": "ok"}) + } +} diff --git a/core/http/react-ui/e2e/chat-history-sync.spec.js b/core/http/react-ui/e2e/chat-history-sync.spec.js new file mode 100644 index 000000000..d6f0f3cbd --- /dev/null +++ b/core/http/react-ui/e2e/chat-history-sync.spec.js @@ -0,0 +1,505 @@ +import { test, expect } from './coverage-fixtures.js' +import { mockChat, chatOf, pair, answerWith, CHATS_KEY } from './chat-fixtures.js' + +// Server-side chat history (see docs/content/features/chat-history.md). The +// server keeps a tombstone for every deleted conversation and refuses to +// write it again; these specs pin the client half: a stale browser must drop +// what the server deleted, and must not lose what it typed while the list +// was loading. + +const T0 = new Date('2026-10-09T12:00:00Z').getTime() + +// A stand-in for /api/conversations with the server's contract: tombstones +// in the list, 410 for a write of a deleted id, versions on every write. +// `hiddenDeleted` are tombstones the list does not report yet (deleted on +// another device after this tab loaded the list). `holdList` keeps the list +// request pending until release() is called. +async function fakeHistoryServer(page, { conversations = [], deleted = [], hiddenDeleted = [], holdList = false } = {}) { + const live = new Map(conversations.map(c => [c.id, c])) + const tombs = new Map(deleted.map(id => [id, { id, version: 9, deletedAt: T0 }])) + const hidden = new Set(hiddenDeleted) + const requests = [] + let release = () => {} + const listGate = holdList ? new Promise(resolve => { release = resolve }) : Promise.resolve() + + let down = false + + await page.route(/\/api\/conversations(\/[^?]*)?(\?.*)?$/, async (route) => { + if (down) return route.abort('internetdisconnected') + const req = route.request() + const path = new URL(req.url()).pathname + const rest = path.slice(path.indexOf('/api/conversations') + '/api/conversations'.length) + const id = rest.startsWith('/') ? decodeURIComponent(rest.slice(1)) : null + const method = req.method() + const body = method === 'PUT' || method === 'POST' ? req.postDataJSON() : null + requests.push({ method, id, body }) + + if (method === 'GET' && !id) { + await listGate + return route.fulfill({ json: { conversations: [...live.values()], deleted: [...tombs.values()] } }) + } + if (method === 'PUT' && id && id !== 'bulk') { + if (tombs.has(id) || hidden.has(id)) { + return route.fulfill({ status: 410, json: { error: 'conversation was deleted' } }) + } + const saved = { ...body, id, version: (live.get(id)?.version || 0) + 1 } + live.set(id, saved) + return route.fulfill({ json: saved }) + } + if (method === 'DELETE' && id) { + live.delete(id) + tombs.set(id, { id, version: 9, deletedAt: T0 }) + return route.fulfill({ json: { status: 'ok' } }) + } + if (method === 'DELETE' && !id) { + for (const liveId of live.keys()) tombs.set(liveId, { id: liveId, version: 9, deletedAt: T0 }) + live.clear() + return route.fulfill({ json: { status: 'ok' } }) + } + return route.fulfill({ status: 404, json: { error: 'not found' } }) + }) + + return { + release: () => release(), + setDown: (value) => { down = value }, + liveIds: () => [...live.keys()].sort(), + saves: (id) => requests.filter(r => r.method === 'PUT' && (id === undefined || r.id === id)), + deletes: (id) => requests.filter(r => r.method === 'DELETE' && r.id === id), + deleteAlls: () => requests.filter(r => r.method === 'DELETE' && !r.id), + bulk: () => requests.filter(r => r.id === 'bulk'), + } +} + +// Signs the browser in as `who()`, read on every request so a spec can sign +// one account out and another in on the same browser. +async function signedInAs(page, who) { + await page.route('**/api/auth/status', route => route.fulfill({ + json: { authEnabled: true, staticApiKeyRequired: false, providers: ['local'], hasUsers: true, user: who() }, + })) +} + +const ALICE = { id: 'u-alice', name: 'Alice', email: 'alice@example.com', role: 'admin', permissions: {} } +const BOB = { id: 'u-bob', name: 'Bob', email: 'bob@example.com', role: 'admin', permissions: {} } + +// Each account has its own browser cache (src/utils/chatStore.js). +const keyOf = (user) => `${CHATS_KEY}:${user.id}` + +const storedChats = (page, user = ALICE) => + page.evaluate((key) => JSON.parse(localStorage.getItem(key) || '{}'), keyOf(user)) + +// Open Chat signed in as Alice with these conversations in her cache. +async function openChat(page, chats, active = chats[0]?.id) { + await page.addInitScript(([key, data]) => { + if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data)) + }, [keyOf(ALICE), { chats, activeChatId: active, lastSaved: Date.now() }]) + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() +} + +// The server half per account: the session decides whose conversations a +// request reads and writes. Saves for an account in `failSaves` answer 500, +// as a first save that does not get through. +async function fakeAccountServer(page, who, { failSaves = [] } = {}) { + const accounts = new Map() + const failing = new Set(failSaves) + const requests = [] + const of = (userId) => { + if (!accounts.has(userId)) accounts.set(userId, new Map()) + return accounts.get(userId) + } + await page.route(/\/api\/conversations(\/[^?]*)?(\?.*)?$/, async (route) => { + const req = route.request() + const user = who().id + const live = of(user) + const path = new URL(req.url()).pathname + const rest = path.slice(path.indexOf('/api/conversations') + '/api/conversations'.length) + const id = rest.startsWith('/') ? decodeURIComponent(rest.slice(1)) : null + const method = req.method() + const body = method === 'PUT' ? req.postDataJSON() : null + requests.push({ user, method, id, body }) + if (method === 'GET' && !id) return route.fulfill({ json: { conversations: [...live.values()], deleted: [] } }) + if (method === 'PUT' && id) { + if (failing.has(user)) return route.fulfill({ status: 500, json: { error: 'database is locked' } }) + const saved = { ...body, id, version: (live.get(id)?.version || 0) + 1 } + live.set(id, saved) + return route.fulfill({ json: saved }) + } + return route.fulfill({ status: 404, json: { error: 'not found' } }) + }) + return { + recover: (userId) => failing.delete(userId), + saves: (userId) => requests.filter(r => r.user === userId && r.method === 'PUT'), + liveTexts: (userId) => [...of(userId).values()].map(c => JSON.stringify(c.history)), + } +} + +const storedIds = async (page) => (await storedChats(page)).chats.map(c => c.id) + +async function openMenu(page) { + await page.keyboard.press('Control+k') + await expect(page.getByTestId('chats-menu')).toBeVisible() +} + +test.describe('Chat history sync with the server', () => { + test.beforeEach(async ({ page }) => { + await mockChat(page) + await signedInAs(page, () => ALICE) + }) + + test('a stale client drops a chat deleted on another device instead of uploading it again', async ({ page }) => { + const server = await fakeHistoryServer(page, { + conversations: [chatOf('kept', 'Kept on the server', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0)], + deleted: ['gone'], + }) + await openChat(page, [ + chatOf('gone', 'Deleted on the laptop', 'qwen3-8b', pair('old q', 'old a'), { version: 2 }, T0 + 5_000), + chatOf('kept', 'Kept on the server', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0), + chatOf('draft', 'Never synced draft', 'qwen3-8b', pair('draft q', 'draft a'), {}, T0 - 5_000), + ], 'gone') + + // The draft is uploaded: that is the save pass the deleted chat must not be in. + await expect.poll(() => server.saves('draft').length).toBe(1) + expect(server.saves('gone')).toHaveLength(0) + await expect.poll(() => storedIds(page)).toEqual(['kept', 'draft']) + + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Deleted on the laptop' })).toHaveCount(0) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Never synced draft' })).toHaveCount(1) + }) + + test('a synced chat the server no longer has is dropped, not resurrected', async ({ page }) => { + // Another account signed in on this browser, or an admin purge: the chat + // has a version, so it was on the server, and the server does not list it. + const server = await fakeHistoryServer(page, { conversations: [] }) + await openChat(page, [ + chatOf('synced', 'Synced earlier', 'qwen3-8b', pair('q', 'a'), { version: 3 }, T0), + chatOf('draft', 'Fresh draft', 'qwen3-8b', pair('q', 'a'), {}, T0 - 1_000), + ]) + await expect.poll(() => server.saves('draft').length).toBe(1) + expect(server.saves('synced')).toHaveLength(0) + // An empty server list is no reason to replace the server's set with + // this browser's cache. + expect(server.bulk()).toHaveLength(0) + await expect.poll(() => storedIds(page)).toEqual(['draft']) + }) + + test('a 410 on save drops the chat locally', async ({ page }) => { + // Deleted on another device after this tab loaded the list. + const server = await fakeHistoryServer(page, { hiddenDeleted: ['late'] }) + await openChat(page, [ + chatOf('late', 'Deleted meanwhile', 'qwen3-8b', pair('q', 'a'), {}, T0), + chatOf('other', 'Still here', 'qwen3-8b', pair('q', 'a'), {}, T0 - 1_000), + ]) + await expect.poll(() => server.saves('late').length).toBe(1) + await expect.poll(() => storedIds(page)).toEqual(['other']) + // Dropped, not retried. + await page.waitForTimeout(1_000) + expect(server.saves('late')).toHaveLength(1) + }) + + test('a message sent while the list is loading survives the older server copy', async ({ page }) => { + const server = await fakeHistoryServer(page, { + holdList: true, + conversations: [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)], + }) + await answerWith(page, 'Answer written during the probe') + await openChat(page, [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)]) + + await page.getByTestId('chat-input').fill('Question typed while loading') + await page.getByTestId('chat-input').press('Enter') + await expect(page.getByText('Answer written during the probe')).toBeVisible() + + server.release() + // The newer local copy wins and is uploaded with the new turn in it. + await expect.poll(() => server.saves('x').map(r => JSON.stringify(r.body.history)).join('\n')) + .toContain('Question typed while loading') + await expect(page.getByText('Question typed while loading')).toBeVisible() + await expect(page.getByText('Answer written during the probe')).toBeVisible() + }) + + test('a newer copy from the server replaces the older local one', async ({ page }) => { + const remote = chatOf('x', 'Release notes', 'qwen3-8b', + [...pair('first question', 'first answer'), ...pair('asked on the phone', 'answered on the phone')], { version: 5 }, T0 + 60_000) + const server = await fakeHistoryServer(page, { conversations: [remote] }) + await openChat(page, [chatOf('x', 'Release notes', 'qwen3-8b', pair('first question', 'first answer'), { version: 4 }, T0)]) + + await expect(page.getByText('answered on the phone')).toBeVisible() + // Adopting the server copy is not a change to send back. + await page.waitForTimeout(1_000) + expect(server.saves('x')).toHaveLength(0) + }) + + test('a delete made while the list is loading reaches the server and wins', async ({ page }) => { + const server = await fakeHistoryServer(page, { + holdList: true, + conversations: [ + chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0), + chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000), + ], + }) + await openChat(page, [ + chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0), + chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000), + ]) + + await openMenu(page) + const row = page.getByTestId('chats-row').filter({ hasText: 'Delete me' }) + await row.hover() + await row.getByTitle('Delete chat').click() + const toast = page.getByTestId('chat-undo-toast') + await toast.getByRole('button', { name: 'Dismiss' }).click() + await expect(toast).toHaveCount(0) + + server.release() + await expect.poll(() => server.deletes('b').length).toBe(1) + // The server still listed it when the answer left; the local delete wins. + await expect.poll(() => storedIds(page)).toEqual(['a']) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + expect(server.saves('b')).toHaveLength(0) + }) + + test('the LocalAI Assistant toggle survives the trip to the server and back', async ({ page }) => { + const server = await fakeHistoryServer(page, { + conversations: [chatOf('remote', 'Assistant on the phone', 'qwen3-8b', pair('q', 'a'), { version: 1, localaiAssistant: true }, T0)], + }) + await openChat(page, [chatOf('local', 'Assistant draft', 'qwen3-8b', pair('q', 'a'), { localaiAssistant: true }, T0 + 1_000)]) + + await expect.poll(() => server.saves('local').length).toBe(1) + expect(server.saves('local')[0].body.localaiAssistant).toBe(true) + await expect.poll(async () => (await storedChats(page)).chats.map(c => [c.id, !!c.localaiAssistant])) + .toEqual([['local', true], ['remote', true]]) + }) +}) + +test.describe('Chat history belongs to the signed-in account', () => { + test.beforeEach(async ({ page }) => { + await mockChat(page) + }) + + test('a draft one account could not save is not uploaded into the next account on this browser', async ({ page }) => { + let who = ALICE + await signedInAs(page, () => who) + const server = await fakeAccountServer(page, () => who, { failSaves: [ALICE.id] }) + await answerWith(page, 'Answer meant for Alice') + + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await page.getByTestId('chat-input').fill('Alice private question') + await page.getByTestId('chat-input').press('Enter') + await expect(page.getByText('Answer meant for Alice')).toBeVisible() + // The first save of Alice's chat does not get through. + await expect.poll(() => server.saves(ALICE.id).some(r => JSON.stringify(r.body).includes('Alice private question'))).toBe(true) + + // Alice signs out, Bob signs in on the same browser. His list is empty. + who = BOB + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + + // Bob's first save pass is the one Alice's draft must not be part of. + await expect.poll(() => server.saves(BOB.id).length).toBeGreaterThan(0) + await page.waitForTimeout(1_000) + expect(server.saves(BOB.id).filter(r => JSON.stringify(r.body).includes('Alice private'))).toHaveLength(0) + expect(server.liveTexts(BOB.id).join('\n')).not.toContain('Alice private') + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Alice private question' })).toHaveCount(0) + }) + + test('the same account still gets its unsaved draft back and uploads it', async ({ page }) => { + let who = ALICE + await signedInAs(page, () => who) + const server = await fakeAccountServer(page, () => who, { failSaves: [ALICE.id] }) + await answerWith(page, 'Answer meant for Alice') + + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await page.getByTestId('chat-input').fill('Alice private question') + await page.getByTestId('chat-input').press('Enter') + await expect(page.getByText('Answer meant for Alice')).toBeVisible() + await expect.poll(() => server.saves(ALICE.id).length).toBeGreaterThan(0) + + // Bob uses the browser in between; then Alice signs in again and the + // server takes writes again. + who = BOB + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await expect.poll(() => server.saves(BOB.id).length).toBeGreaterThan(0) + + who = ALICE + server.recover(ALICE.id) + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await expect.poll(() => server.liveTexts(ALICE.id).join('\n')).toContain('Alice private question') + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Alice private question' })).toHaveCount(1) + }) +}) + +test.describe('Deletes stay pending until the server confirms them', () => { + const remote = () => [ + chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'a'), { version: 1 }, T0), + chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'b'), { version: 1 }, T0 - 1_000), + ] + + test.beforeEach(async ({ page }) => { + await mockChat(page) + await signedInAs(page, () => ALICE) + }) + + // Opens Chat with nothing in the browser and waits until the list has been + // reconciled: the empty chat Chat starts with is uploaded only after that. + async function openSynced(page, server) { + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await expect.poll(() => server.saves().length).toBeGreaterThan(0) + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(1) + } + + async function deleteRow(page, name) { + const row = page.getByTestId('chats-row').filter({ hasText: name }) + await row.hover() + await row.getByTitle('Delete chat').click() + const toast = page.getByTestId('chat-undo-toast') + await toast.getByRole('button', { name: 'Dismiss' }).click() + await expect(toast).toHaveCount(0) + } + + async function reopen(page) { + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await openMenu(page) + } + + test('a delete made while the server is unreachable is sent later and the chat does not come back', async ({ page, context }) => { + const server = await fakeHistoryServer(page, { conversations: remote() }) + await openSynced(page, server) + + server.setDown(true) + await context.setOffline(true) + await deleteRow(page, 'Delete me') + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + await page.waitForTimeout(500) + + server.setDown(false) + await context.setOffline(false) + await reopen(page) + await expect.poll(() => server.liveIds().filter(id => id === 'a' || id === 'b')).toEqual(['a']) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + }) + + test('"clear all" made while the server is unreachable is sent later and nothing comes back', async ({ page, context }) => { + const server = await fakeHistoryServer(page, { conversations: remote() }) + await openSynced(page, server) + + server.setDown(true) + await context.setOffline(true) + await page.getByRole('button', { name: 'Clear all' }).click() + await page.getByRole('button', { name: 'Delete all' }).click() + await page.waitForTimeout(500) + + server.setDown(false) + await context.setOffline(false) + await reopen(page) + await expect.poll(() => server.liveIds().filter(id => id === 'a' || id === 'b')).toEqual([]) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(0) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + }) + + test('clear all persists before navigation can cancel the debounced save', async ({ page }) => { + const server = await fakeHistoryServer(page) + server.setDown(true) + // Two chats: with a single chat the menu offers no Clear all. + await openChat(page, [ + chatOf('draft', 'Unsynced draft', 'qwen3-8b', pair('private draft', 'answer'), {}, T0), + chatOf('other', 'Other draft', 'qwen3-8b', pair('second draft', 'answer'), {}, T0 - 1000), + ]) + await openMenu(page) + // Freeze the debounce: assert the cache produced by the delete itself. + await page.clock.install() + await page.clock.pauseAt(new Date()) + await page.getByRole('button', { name: 'Clear all' }).click() + await page.getByRole('button', { name: 'Delete all' }).click() + const stored = await storedChats(page) + expect(stored.chats.map(c => c.id)).not.toContain('draft') + expect(stored.chats.map(c => c.id)).not.toContain('other') + expect(stored.pendingDeletes).toEqual(['*']) + + await page.clock.resume() + server.setDown(false) + await reopen(page) + await expect.poll(() => server.deleteAlls().length).toBe(1) + await page.waitForTimeout(1_000) + expect(server.saves('draft')).toHaveLength(0) + expect(server.saves('other')).toHaveLength(0) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Unsynced draft' })).toHaveCount(0) + }) + + test('a delete the server confirmed is not sent again and does not come back', async ({ page }) => { + const server = await fakeHistoryServer(page, { conversations: remote() }) + await openSynced(page, server) + + await deleteRow(page, 'Delete me') + await expect.poll(() => server.deletes('b').length).toBe(1) + expect(server.liveIds()).not.toContain('b') + // The server has the request; wait until the page has its answer too. + // Reopening earlier leaves the delete unconfirmed, and it is rightly sent again. + await expect.poll(async () => (await storedChats(page)).pendingDeletes).toEqual([]) + + await reopen(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + await page.waitForTimeout(1_000) + expect(server.deletes('b')).toHaveLength(1) + }) +}) + +test.describe('Chat history from Home and without an account', () => { + test('a delete on the Home page reaches the server through Chat', async ({ page }) => { + await mockChat(page) + await signedInAs(page, () => ALICE) + const server = await fakeHistoryServer(page, { + conversations: [ + chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'kept answer'), { version: 1 }, T0), + chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'deleted answer'), { version: 1 }, T0 - 1_000), + ], + }) + await page.addInitScript(([key, data]) => { + if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data)) + }, [keyOf(ALICE), { + chats: [ + chatOf('a', 'Keep me', 'qwen3-8b', pair('q', 'kept answer'), { version: 1 }, Date.now()), + chatOf('b', 'Delete me', 'qwen3-8b', pair('q', 'deleted answer'), { version: 1 }, Date.now() - 1_000), + ], + activeChatId: 'a', + }]) + + await page.goto('/app') + const row = page.getByTestId('home-conversation').filter({ hasText: 'Delete me' }) + await row.hover() + await row.getByRole('button', { name: /delete conversation/i }).click() + await expect(page.getByTestId('home-undo-toast')).toBeVisible() + // Resuming another chat makes the delete final and opens Chat. + await page.getByTestId('home-conversation').filter({ hasText: 'Keep me' }).locator('.home-row__open').click() + await expect(page).toHaveURL(/\/app\/chat/) + + await expect.poll(() => server.deletes('b').length).toBe(1) + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Keep me' })).toHaveCount(1) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Delete me' })).toHaveCount(0) + }) + + test('nobody signed in: chats stay in the browser and nothing is sent', async ({ page }) => { + await mockChat(page) + const server = await fakeHistoryServer(page, {}) + await page.addInitScript(([key, data]) => { + if (!localStorage.getItem(key)) localStorage.setItem(key, JSON.stringify(data)) + }, [CHATS_KEY, { chats: [chatOf('local', 'Browser only', 'qwen3-8b', pair('q', 'a'), {}, T0)], activeChatId: 'local' }]) + await page.goto('/app/chat') + await page.getByTestId('chat-composer').waitFor() + await openMenu(page) + await expect(page.getByTestId('chats-row').filter({ hasText: 'Browser only' })).toHaveCount(1) + await page.waitForTimeout(1_000) + expect(server.saves()).toHaveLength(0) + }) +}) diff --git a/core/http/react-ui/src/hooks/useChat.js b/core/http/react-ui/src/hooks/useChat.js index 842d8a373..19c6040f4 100644 --- a/core/http/react-ui/src/hooks/useChat.js +++ b/core/http/react-ui/src/hooks/useChat.js @@ -1,8 +1,11 @@ -import { useState, useCallback, useRef } from 'react' +import { useState, useCallback, useRef, useEffect } from 'react' import { API_CONFIG } from '../utils/config' import { apiUrl } from '../utils/basePath' import { effectiveSystemPrompt } from '../utils/systemPrompt' import { useDebouncedEffect } from './useDebounce' +import { chatHistoryApi } from '../utils/api' +import { useAuth } from '../context/AuthContext' +import { chatsStorageKey, readChatStore, writeChatStore } from '../utils/chatStore' const thinkingTagRegex = /([\s\S]*?)<\/thinking>|([\s\S]*?)<\/think>|<\|channel>thought([\s\S]*?)/g const openThinkTagRegex = /||<\|channel>thought/ @@ -96,58 +99,75 @@ function extractThinking(text) { import { generateId } from '../utils/format' -const CHATS_STORAGE_KEY = 'localai_chats_data' - -function loadChats() { - try { - const stored = localStorage.getItem(CHATS_STORAGE_KEY) - if (stored) { - const data = JSON.parse(stored) - if (data && Array.isArray(data.chats)) { - // Older chats stored a separate reasoningOff flag. It now means - // reasoning_effort 'none'. - data.chats = data.chats.map(({ reasoningOff, ...chat }) => ( - reasoningOff ? { ...chat, reasoningEffort: 'none' } : chat - )) - return data - } - } - } catch (_e) { - localStorage.removeItem(CHATS_STORAGE_KEY) +// serializeChat strips React-only state (streaming flags, transient UI bits) +// before persistence. This is what goes to the server; `version` is the +// server's and is never sent back. +function serializeChat(chat) { + return { + id: chat.id, + name: chat.name, + model: chat.model, + history: chat.history, + systemPrompt: chat.systemPrompt, + mcpMode: chat.mcpMode, + mcpServers: chat.mcpServers, + mcpResources: chat.mcpResources, + clientMCPServers: chat.clientMCPServers, + localaiAssistant: chat.localaiAssistant, + temperature: chat.temperature, + topP: chat.topP, + topK: chat.topK, + reasoningEffort: chat.reasoningEffort, + tokenUsage: chat.tokenUsage, + contextSize: chat.contextSize, + createdAt: chat.createdAt, + updatedAt: chat.updatedAt, } - return null } -function saveChats(chats, activeChatId) { - try { - const data = { - chats: chats.map(chat => ({ - id: chat.id, - name: chat.name, - model: chat.model, - history: chat.history, - systemPrompt: chat.systemPrompt, - mcpMode: chat.mcpMode, - mcpServers: chat.mcpServers, - clientMCPServers: chat.clientMCPServers, - temperature: chat.temperature, - topP: chat.topP, - topK: chat.topK, - reasoningEffort: chat.reasoningEffort, - tokenUsage: chat.tokenUsage, - contextSize: chat.contextSize, - createdAt: chat.createdAt, - updatedAt: chat.updatedAt, - })), - activeChatId, - lastSaved: Date.now(), - } - localStorage.setItem(CHATS_STORAGE_KEY, JSON.stringify(data)) - } catch (err) { - if (err.name === 'QuotaExceededError' || err.code === 22) { - console.warn('localStorage quota exceeded') +function saveChats(key, chats, activeChatId, pendingDeletes) { + writeChatStore(key, { + // The local cache keeps the server version: it is how the next load + // tells a chat the server has seen from a never-synced draft. + chats: chats.map(chat => ({ ...serializeChat(chat), version: chat.version })), + activeChatId, + pendingDeletes: [...pendingDeletes], + }) +} + +// The server omits empty fields; the UI expects a history array. +function fromServer(conv) { + return { ...conv, history: Array.isArray(conv.history) ? conv.history : [] } +} + +// reconcileWithServer merges the server's list into the chats this tab +// already has (from localStorage, plus anything typed while the list was +// loading). The server is authoritative about deletions: +// - a chat the server lists as deleted is dropped, whatever this tab has; +// - a chat on both sides keeps the copy with the newer updatedAt, so an +// edit made during the load is not overwritten by the older server copy; +// - a chat only here is kept when it was never synced (no version) and +// uploaded afterwards. With a version the server has seen it and no +// longer has it, so it is dropped rather than resurrected; +// - a chat only on the server is added. +function reconcileWithServer(remote, deleted, local) { + const gone = new Set(deleted.map(t => t.id)) + const remoteById = new Map(remote.map(c => [c.id, fromServer(c)])) + const out = [] + for (const c of local) { + if (gone.has(c.id)) continue + const r = remoteById.get(c.id) + if (r) { + remoteById.delete(c.id) + out.push((c.updatedAt || 0) > (r.updatedAt || 0) ? { ...c, version: r.version } : r) + } else if (!c.version) { + out.push(c) } } + for (const r of remoteById.values()) { + if (!gone.has(r.id)) out.push(r) + } + return out.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0)) } function createNewChat(model = '', systemPrompt = '', mcpMode = false) { @@ -178,17 +198,33 @@ function createNewChat(model = '', systemPrompt = '', mcpMode = false) { } export function useChat(initialModel = '') { + // The cache and the server sync belong to the signed-in account. Chat + // remounts this hook when the account changes, so the key is fixed for the + // hook's lifetime. Without an account there is no server history and the + // chats stay in the browser only. + const { user } = useAuth() + const accountId = user?.id || '' + const storageKey = chatsStorageKey(accountId) + const storedRef = useRef(undefined) + if (storedRef.current === undefined) storedRef.current = readChatStore(storageKey) + + // Deletes the server has not confirmed yet ('*' = delete all). They are + // persisted with the cache and sent again until the server answers, so a + // delete made while the server is unreachable is not undone by the next + // list. + const pendingDeletesRef = useRef(null) + if (pendingDeletesRef.current === null) { + pendingDeletesRef.current = new Set(accountId ? (storedRef.current?.pendingDeletes || []) : []) + } + const [chats, setChats] = useState(() => { - const stored = loadChats() - if (stored && stored.chats.length > 0) return stored.chats + const pending = pendingDeletesRef.current + const stored = (storedRef.current?.chats || []).filter(c => !pending.has(c.id)) + if (stored.length > 0) return stored return [createNewChat(initialModel)] }) - const [activeChatId, setActiveChatId] = useState(() => { - const stored = loadChats() - if (stored && stored.activeChatId) return stored.activeChatId - return chats[0]?.id - }) + const [activeChatId, setActiveChatId] = useState(() => storedRef.current?.activeChatId || chats[0]?.id) const [isStreaming, setIsStreaming] = useState(false) const [streamingChatId, setStreamingChatId] = useState(null) @@ -208,7 +244,145 @@ export function useChat(initialModel = '') { const activeChat = chats.find(c => c.id === activeChatId) || chats[0] - useDebouncedEffect(() => saveChats(chats, activeChatId), [chats, activeChatId]) + // Server-side persistence. serverEnabledRef is null while we are still + // probing, true once a successful list arrives, false on any error + // (feature disabled, auth off, denied, network down) and when nobody is + // signed in. serializedSentRef caches the JSON last pushed (or received) + // per chat so unchanged chats are not written again. deletesInFlightRef + // holds the pending deletes with a request on the way; deleteAllSeqRef + // counts "delete all" requests, so the answer to an older one does not + // clear a newer one. + const serverEnabledRef = useRef(null) + const serializedSentRef = useRef(new Map()) + const deletesInFlightRef = useRef(new Set()) + const deleteAllSeqRef = useRef(0) + // Bumped when a confirmed "delete all" lets the held-back saves go out. + const [syncTick, setSyncTick] = useState(0) + + const persistPending = useCallback(() => { + const data = readChatStore(storageKey) || { chats: [], activeChatId: null } + writeChatStore(storageKey, { ...data, pendingDeletes: [...pendingDeletesRef.current] }) + }, [storageKey]) + + // flushPendingDeletes sends every pending delete that has no request on the + // way. A delete leaves the queue only when the server confirms it (DELETE + // is idempotent server-side); on any other outcome it stays and is sent + // again with the next change, when the browser comes back online, or on + // the next load. + const flushPendingDeletes = useCallback(() => { + if (serverEnabledRef.current !== true) return + const inFlight = deletesInFlightRef.current + for (const id of pendingDeletesRef.current) { + if (inFlight.has(id)) continue + inFlight.add(id) + const seq = deleteAllSeqRef.current + const request = id === '*' ? chatHistoryApi.deleteAll() : chatHistoryApi.delete(id) + request + .then(() => true, err => err?.status === 400) // 400: an id the server never accepts + .then(done => { + inFlight.delete(id) + if (!done) return + if (id === '*' && seq !== deleteAllSeqRef.current) { + flushPendingDeletes() + return + } + pendingDeletesRef.current.delete(id) + persistPending() + if (id === '*') setSyncTick(t => t + 1) + }) + } + }, [persistPending]) + + // Every path that empties the list must leave one chat to show. + const nonEmpty = useCallback((list) => (list.length > 0 ? list : [createNewChat(initialModel)]), [initialModel]) + + const dropChatLocally = useCallback((chatId) => { + serializedSentRef.current.delete(chatId) + setChats(prev => (prev.some(c => c.id === chatId) ? nonEmpty(prev.filter(c => c.id !== chatId)) : prev)) + }, [nonEmpty]) + + useEffect(() => { + if (!accountId) { + serverEnabledRef.current = false + return + } + let cancelled = false + chatHistoryApi.list() + .then(resp => { + if (cancelled) return + const remote = Array.isArray(resp?.conversations) ? resp.conversations : [] + const deleted = Array.isArray(resp?.deleted) ? [...resp.deleted] : [] + // A pending delete wins over the list: the server may still have the + // chat because the delete has not reached it yet. + const pending = pendingDeletesRef.current + if (pending.has('*')) { + for (const c of remote) deleted.push({ id: c.id }) + } + for (const id of pending) { + if (id !== '*') deleted.push({ id }) + } + // What the server holds counts as sent, so adopting a server copy + // does not echo it straight back. + for (const c of remote) { + serializedSentRef.current.set(c.id, JSON.stringify(serializeChat(fromServer(c)))) + } + serverEnabledRef.current = true + setChats(prev => nonEmpty(reconcileWithServer(remote, deleted, prev))) + flushPendingDeletes() + }) + .catch(() => { + if (!cancelled) serverEnabledRef.current = false + }) + return () => { cancelled = true } + // eslint-disable-next-line react-hooks/exhaustive-deps + }, []) + + useEffect(() => { + window.addEventListener('online', flushPendingDeletes) + return () => window.removeEventListener('online', flushPendingDeletes) + }, [flushPendingDeletes]) + + // The reconcile can remove the open chat. + useEffect(() => { + if (chats.length > 0 && !chats.some(c => c.id === activeChatId)) { + setActiveChatId(chats[0].id) + } + }, [chats, activeChatId]) + + useDebouncedEffect(() => { + saveChats(storageKey, chats, activeChatId, pendingDeletesRef.current) + if (serverEnabledRef.current !== true) return + flushPendingDeletes() + // Until a "delete all" is confirmed, a chat saved now would be caught by + // it when it lands. The confirmation bumps syncTick and the saves follow. + if (pendingDeletesRef.current.has('*')) return + for (const chat of chats) { + if (pendingDeletesRef.current.has(chat.id)) continue + const serialized = serializeChat(chat) + const json = JSON.stringify(serialized) + if (serializedSentRef.current.get(chat.id) === json) continue + serializedSentRef.current.set(chat.id, json) + chatHistoryApi.save(serialized) + .then(saved => { + if (!saved?.version) return + setChats(prev => { + if (!prev.some(c => c.id === saved.id && c.version !== saved.version)) return prev + return prev.map(c => (c.id === saved.id ? { ...c, version: saved.version } : c)) + }) + }) + .catch(err => { + if (err?.status === 410) { + // Deleted on another device: the server keeps it deleted, so + // drop this copy instead of retrying it forever. + dropChatLocally(chat.id) + return + } + // Keep localStorage as the copy on transient server failures; + // the next change retries. + serializedSentRef.current.delete(chat.id) + }) + } + }, [chats, activeChatId, syncTick]) const addChat = useCallback((model = '', systemPrompt = '', mcpMode = false) => { const chat = createNewChat(model, systemPrompt, mcpMode) @@ -253,7 +427,12 @@ export function useChat(initialModel = '') { } return filtered }) - }, [activeChatId]) + serializedSentRef.current.delete(chatId) + if (!accountId) return + pendingDeletesRef.current.add(chatId) + persistPending() + flushPendingDeletes() + }, [activeChatId, accountId, persistPending, flushPendingDeletes]) const deleteAllChats = useCallback(() => { const chat = createNewChat(activeChat?.model || '') @@ -264,7 +443,16 @@ export function useChat(initialModel = '') { setStreamingToolCalls([]) setTokensPerSecond(null) setMaxTokensPerSecond(null) - }, [activeChat?.model]) + serializedSentRef.current.clear() + if (!accountId) return + // Covers every delete still pending before it. + pendingDeletesRef.current = new Set(['*']) + deleteAllSeqRef.current += 1 + // Navigation cancels the debounced save; persist the cleared list with + // its delete intent so an unsynced draft cannot return on the next load. + saveChats(storageKey, [chat], chat.id, pendingDeletesRef.current) + flushPendingDeletes() + }, [activeChat?.model, accountId, storageKey, flushPendingDeletes]) const renameChat = useCallback((chatId, name) => { setChats(prev => prev.map(c => diff --git a/core/http/react-ui/src/pages/Chat.jsx b/core/http/react-ui/src/pages/Chat.jsx index c135da6e4..ecaa5ab8c 100644 --- a/core/http/react-ui/src/pages/Chat.jsx +++ b/core/http/react-ui/src/pages/Chat.jsx @@ -98,7 +98,16 @@ function formatLoadEta(seconds) { return `${Math.floor(minutes / 60)}h ${minutes % 60}m` } +// One chat state per account: useChat binds its browser cache and its server +// sync to the signed-in account, so a different account gets a fresh mount +// instead of the previous account's chats. export default function Chat() { + const { user } = useAuth() + return +} + +// eslint-disable-next-line no-unused-vars -- used as JSX above +function ChatPage() { const { model: urlModel } = useParams() const { addToast } = useOutletContext() const navigate = useNavigate() diff --git a/core/http/react-ui/src/pages/Home.jsx b/core/http/react-ui/src/pages/Home.jsx index f9554c9a2..3d743b2cf 100644 --- a/core/http/react-ui/src/pages/Home.jsx +++ b/core/http/react-ui/src/pages/Home.jsx @@ -32,6 +32,7 @@ import { greetingKey } from '../utils/greeting' import { listConversations, setActiveConversation, removeConversation, } from '../utils/homeConversations' +import { chatsStorageKey } from '../utils/chatStore' // eslint-disable-next-line no-unused-vars import Skeleton from '../components/Skeleton' import { staggerStyle } from '../hooks/useStagger' @@ -56,7 +57,9 @@ export default function Home() { const navigate = useNavigate() const { addToast } = useOutletContext() const { t, i18n } = useTranslation('home') - const { isAdmin } = useAuth() + const { isAdmin, user } = useAuth() + // The signed-in account's own chat cache (see chatStore). + const chatsKey = chatsStorageKey(user?.id) const branding = useBranding() const { resources } = useResources() const { operations } = useOperations() @@ -92,7 +95,7 @@ export default function Home() { const [distributedMode, setDistributedMode] = useState(false) const [clusterData, setClusterData] = useState(null) const [stripOpen, setStripOpen] = useState(false) - const [conversations, setConversations] = useState(() => listConversations()) + const [conversations, setConversations] = useState(() => listConversations(chatsKey)) const [leavingId, setLeavingId] = useState(null) const [pendingDelete, setPendingDelete] = useState(null) const textareaRef = useRef(null) @@ -366,19 +369,19 @@ export default function Home() { // ----- Conversations ----------------------------------------------------- - const refreshConversations = useCallback(() => setConversations(listConversations()), []) + const refreshConversations = useCallback(() => setConversations(listConversations(chatsKey)), [chatsKey]) // Another tab can write chats, and Chat writes them after a short delay. Read // again when the tab changes or comes back into focus. useEffect(() => { - const onStorage = (e) => { if (!e.key || e.key === 'localai_chats_data') refreshConversations() } + const onStorage = (e) => { if (!e.key || e.key === chatsKey) refreshConversations() } window.addEventListener('storage', onStorage) window.addEventListener('focus', refreshConversations) return () => { window.removeEventListener('storage', onStorage) window.removeEventListener('focus', refreshConversations) } - }, [refreshConversations]) + }, [chatsKey, refreshConversations]) // A delete is final when its undo time ends. Until then the chat stays in // storage and only the row is hidden. @@ -386,10 +389,10 @@ export default function Home() { const id = pendingRef.current if (!id) return pendingRef.current = null - removeConversation(id) + removeConversation(id, chatsKey) setPendingDelete(null) refreshConversations() - }, [refreshConversations]) + }, [chatsKey, refreshConversations]) const commitRef = useRef(commitDelete) commitRef.current = commitDelete @@ -421,9 +424,9 @@ export default function Home() { const resumeConversation = useCallback((conv) => { commitDelete() - if (setActiveConversation(conv.id)) navigate('/app/chat') + if (setActiveConversation(conv.id, chatsKey)) navigate('/app/chat') else refreshConversations() - }, [commitDelete, navigate, refreshConversations]) + }, [chatsKey, commitDelete, navigate, refreshConversations]) const visibleConversations = useMemo( () => conversations.filter(c => c.id !== pendingDelete?.id), diff --git a/core/http/react-ui/src/utils/api.js b/core/http/react-ui/src/utils/api.js index 49297933a..739ad5aa8 100644 --- a/core/http/react-ui/src/utils/api.js +++ b/core/http/react-ui/src/utils/api.js @@ -157,6 +157,25 @@ export const chatApi = { mcpComplete: (body) => postJSON(API_CONFIG.endpoints.mcpChatCompletions, body), } +// Chat History API — server-side conversation persistence (#9432). +// Endpoints return 404 when the WebUI's chat history feature is disabled, so +// every call here is best-effort: callers should fall back to localStorage on +// failure rather than surfacing a user-visible error. +export const chatHistoryApi = { + list: () => fetchJSON(API_CONFIG.endpoints.conversations), + get: (id) => fetchJSON(API_CONFIG.endpoints.conversation(id)), + save: (conv) => fetchJSON(API_CONFIG.endpoints.conversation(conv.id), { + method: 'PUT', + body: JSON.stringify(conv), + }), + bulkReplace: (conversations) => fetchJSON(API_CONFIG.endpoints.conversationsBulk, { + method: 'PUT', + body: JSON.stringify({ conversations }), + }), + delete: (id) => fetchJSON(API_CONFIG.endpoints.conversation(id), { method: 'DELETE' }), + deleteAll: () => fetchJSON(API_CONFIG.endpoints.conversations, { method: 'DELETE' }), +} + // MCP API export const mcpApi = { listServers: (model) => fetchJSON(API_CONFIG.endpoints.mcpServers(model)), diff --git a/core/http/react-ui/src/utils/chatStore.js b/core/http/react-ui/src/utils/chatStore.js new file mode 100644 index 000000000..636de9fc7 --- /dev/null +++ b/core/http/react-ui/src/utils/chatStore.js @@ -0,0 +1,50 @@ +// The browser cache of the Chat page's conversations. Chat writes it, Home +// reads it. +// +// Signed in, every account has its own entry: a draft one account could not +// upload must never be found, and uploaded, by the next account that signs in +// on the same browser. Without an account (auth disabled) the original key is +// used, so existing browser-only histories keep working. +// +// Besides the chats the entry holds `pendingDeletes`: ids the user deleted +// that the server has not confirmed yet ('*' = delete all). They survive a +// reload and are sent again until the server answers. + +export const CHATS_STORAGE_KEY = 'localai_chats_data' + +export function chatsStorageKey(accountId) { + return accountId ? `${CHATS_STORAGE_KEY}:${accountId}` : CHATS_STORAGE_KEY +} + +export function isChatsStorageKey(key) { + return key === CHATS_STORAGE_KEY || (typeof key === 'string' && key.startsWith(`${CHATS_STORAGE_KEY}:`)) +} + +export function readChatStore(key) { + try { + const raw = localStorage.getItem(key) + if (!raw) return null + const data = JSON.parse(raw) + if (!data || !Array.isArray(data.chats)) return null + // Older chats stored a separate reasoningOff flag. It now means + // reasoning_effort 'none'. + const chats = data.chats.map(({ reasoningOff, ...chat }) => ( + reasoningOff ? { ...chat, reasoningEffort: 'none' } : chat + )) + return { ...data, chats, pendingDeletes: Array.isArray(data.pendingDeletes) ? data.pendingDeletes : [] } + } catch { + return null + } +} + +export function writeChatStore(key, data) { + try { + localStorage.setItem(key, JSON.stringify({ ...data, lastSaved: Date.now() })) + return true + } catch (err) { + if (err?.name === 'QuotaExceededError' || err?.code === 22) { + console.warn('localStorage quota exceeded') + } + return false + } +} diff --git a/core/http/react-ui/src/utils/config.js b/core/http/react-ui/src/utils/config.js index c2702ed30..5442e23fa 100644 --- a/core/http/react-ui/src/utils/config.js +++ b/core/http/react-ui/src/utils/config.js @@ -57,6 +57,11 @@ export const API_CONFIG = { p2pStats: '/api/p2p/stats', p2pToken: '/api/p2p/token', + // Chat history (server-side persistence, #9432) + conversations: '/api/conversations', + conversation: (id) => `/api/conversations/${encodeURIComponent(id)}`, + conversationsBulk: '/api/conversations/bulk', + // Agent jobs agentTasks: '/api/agent/tasks', agentTask: (id) => `/api/agent/tasks/${id}`, diff --git a/core/http/react-ui/src/utils/homeConversations.js b/core/http/react-ui/src/utils/homeConversations.js index 099a13ad1..8e8e14893 100644 --- a/core/http/react-ui/src/utils/homeConversations.js +++ b/core/http/react-ui/src/utils/homeConversations.js @@ -1,33 +1,15 @@ // Conversations on the Home page: read from the same browser storage the Chat -// page writes (see useChat), grouped by day for the "Jump back in" list. +// page writes (see useChat and chatStore), grouped by day for the "Jump back +// in" list. Every function takes the storage key of the signed-in account +// (chatsStorageKey); without one it reads the browser-only key. // // Home only reads, resumes and deletes. It never writes a chat's content, so a // stored conversation keeps the exact shape Chat expects. -export const CHATS_STORAGE_KEY = 'localai_chats_data' +import { CHATS_STORAGE_KEY, readChatStore, writeChatStore } from './chatStore' const DAY_MS = 24 * 60 * 60 * 1000 -function readStore() { - try { - const raw = localStorage.getItem(CHATS_STORAGE_KEY) - if (!raw) return null - const data = JSON.parse(raw) - return data && Array.isArray(data.chats) ? data : null - } catch { - return null - } -} - -function writeStore(data) { - try { - localStorage.setItem(CHATS_STORAGE_KEY, JSON.stringify({ ...data, lastSaved: Date.now() })) - return true - } catch { - return false - } -} - // A message body is a string, or a list of blocks ({type:'text'|'image_url'|...}). function messageText(message) { const content = message?.content @@ -94,8 +76,8 @@ export function conversationsFromChats(chats) { } // Chats that hold at least one message, newest first. -export function listConversations() { - const data = readStore() +export function listConversations(key = CHATS_STORAGE_KEY) { + const data = readChatStore(key) return data ? conversationsFromChats(data.chats) : [] } @@ -130,19 +112,23 @@ export function groupConversations(items, now = Date.now()) { } // Make a stored chat the one Chat opens on. -export function setActiveConversation(id) { - const data = readStore() +export function setActiveConversation(id, key = CHATS_STORAGE_KEY) { + const data = readChatStore(key) if (!data || !data.chats.some(c => c.id === id)) return false - return writeStore({ ...data, activeChatId: id }) + return writeChatStore(key, { ...data, activeChatId: id }) } // Remove a chat from storage. Home keeps the chat until its undo time ends -// and calls this only then, so there is nothing to put back afterwards. -export function removeConversation(id) { - const data = readStore() +// and calls this only then, so there is nothing to put back afterwards. The +// id is queued as a pending delete: Home does not talk to the server, so the +// Chat page sends the delete the next time it syncs. Without that a synced +// chat removed here would come straight back from the server. +export function removeConversation(id, key = CHATS_STORAGE_KEY) { + const data = readChatStore(key) if (!data || !data.chats.some(c => c.id === id)) return false const chats = data.chats.filter(c => c.id !== id) let activeChatId = data.activeChatId if (activeChatId === id) activeChatId = chats[0]?.id - return writeStore({ ...data, chats, activeChatId }) + const pendingDeletes = data.pendingDeletes.includes(id) ? data.pendingDeletes : [...data.pendingDeletes, id] + return writeChatStore(key, { ...data, chats, activeChatId, pendingDeletes }) } diff --git a/core/http/routes/chat_history_auth_test.go b/core/http/routes/chat_history_auth_test.go new file mode 100644 index 000000000..f6f03ebbc --- /dev/null +++ b/core/http/routes/chat_history_auth_test.go @@ -0,0 +1,287 @@ +// SPDX-License-Identifier: MIT +//go:build auth + +package routes_test + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + + "github.com/labstack/echo/v4" + "github.com/mudler/LocalAI/core/config" + "github.com/mudler/LocalAI/core/http/auth" + "github.com/mudler/LocalAI/core/http/routes" + "github.com/mudler/LocalAI/core/services/chathistory" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "gorm.io/gorm" +) + +// chatHistoryServer drives the conversation endpoints through the same +// registration function and middleware chain the real server uses, against +// an in-memory SQLite auth database. +type chatHistoryServer struct { + e *echo.Echo + db *gorm.DB + sessions map[string]string +} + +func newChatHistoryServer() *chatHistoryServer { + db, err := auth.InitDB(":memory:") + Expect(err).NotTo(HaveOccurred()) + sqlDB, err := db.DB() + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(sqlDB.Close) + + store, err := chathistory.New(db) + Expect(err).NotTo(HaveOccurred()) + + s := &chatHistoryServer{e: echo.New(), db: db, sessions: map[string]string{}} + for _, id := range []string{"alice", "bob", "carol"} { + user := &auth.User{ID: id, Email: id + "@example.test", Name: id, Role: auth.RoleUser, Status: auth.StatusActive, Provider: auth.ProviderLocal} + Expect(db.Create(user).Error).To(Succeed()) + session, err := auth.CreateSession(db, id, "") + Expect(err).NotTo(HaveOccurred()) + s.sessions[id] = session + } + // carol had the default-on feature revoked by an admin. + Expect(auth.UpdateUserPermissions(db, "carol", auth.PermissionMap{auth.FeatureChatHistory: false})).To(Succeed()) + + s.e.Use(auth.Middleware(db, config.NewApplicationConfig())) + routes.RegisterChatHistoryRoutes(s.e, store, auth.RequireFeature(db, auth.FeatureChatHistory)) + return s +} + +// do sends a request as user (empty = unauthenticated) and returns the +// recorder; body may be nil. +func (s *chatHistoryServer) do(user, method, path string, body any) *httptest.ResponseRecorder { + var payload *strings.Reader + if body == nil { + payload = strings.NewReader("") + } else if raw, ok := body.(string); ok { + payload = strings.NewReader(raw) + } else { + data, err := json.Marshal(body) + Expect(err).NotTo(HaveOccurred()) + payload = strings.NewReader(string(data)) + } + req := httptest.NewRequest(method, path, payload) + req.Header.Set(echo.HeaderContentType, echo.MIMEApplicationJSON) + if user != "" { + req.AddCookie(&http.Cookie{Name: "session", Value: s.sessions[user]}) + } + rec := httptest.NewRecorder() + s.e.ServeHTTP(rec, req) + return rec +} + +func decodeJSON(rec *httptest.ResponseRecorder) map[string]any { + var out map[string]any + Expect(json.Unmarshal(rec.Body.Bytes(), &out)).To(Succeed(), rec.Body.String()) + return out +} + +func listedIDs(rec *httptest.ResponseRecorder) []string { + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + ids := []string{} + for _, c := range decodeJSON(rec)["conversations"].([]any) { + ids = append(ids, c.(map[string]any)["id"].(string)) + } + return ids +} + +func conversationBody(id, name string) map[string]any { + return map[string]any{ + "id": id, + "name": name, + "model": "test-model", + "history": []map[string]any{{"role": "user", "content": "hi"}}, + } +} + +var _ = Describe("Chat history endpoints", func() { + var s *chatHistoryServer + + BeforeEach(func() { + s = newChatHistoryServer() + }) + + DescribeTable("require authentication on every route", + func(method, path string) { + Expect(s.do("", method, path, nil).Code).To(Equal(http.StatusUnauthorized)) + }, + Entry("list", http.MethodGet, "/api/conversations"), + Entry("create", http.MethodPost, "/api/conversations"), + Entry("delete all", http.MethodDelete, "/api/conversations"), + Entry("bulk", http.MethodPut, "/api/conversations/bulk"), + Entry("get", http.MethodGet, "/api/conversations/c1"), + Entry("save", http.MethodPut, "/api/conversations/c1"), + Entry("delete", http.MethodDelete, "/api/conversations/c1"), + ) + + DescribeTable("honour a revoked chat_history permission", + func(method, path string) { + Expect(s.do("carol", method, path, nil).Code).To(Equal(http.StatusForbidden)) + }, + Entry("list", http.MethodGet, "/api/conversations"), + Entry("save", http.MethodPut, "/api/conversations/c1"), + Entry("bulk", http.MethodPut, "/api/conversations/bulk"), + ) + + It("registers nothing without a store, so the UI falls back to localStorage", func() { + e := echo.New() + routes.RegisterChatHistoryRoutes(e, nil, auth.NoopMiddleware()) + req := httptest.NewRequest(http.MethodGet, "/api/conversations", nil) + rec := httptest.NewRecorder() + e.ServeHTTP(rec, req) + Expect(rec.Code).To(Equal(http.StatusNotFound)) + }) + + It("saves, lists, gets and deletes a conversation", func() { + rec := s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "First")) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + saved := decodeJSON(rec) + Expect(saved["createdAt"]).NotTo(BeZero()) + Expect(saved["updatedAt"]).NotTo(BeZero()) + + rec = s.do("alice", http.MethodPost, "/api/conversations", conversationBody("c2", "Second")) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("c1", "c2")) + + rec = s.do("alice", http.MethodGet, "/api/conversations/c1", nil) + Expect(rec.Code).To(Equal(http.StatusOK)) + got := decodeJSON(rec) + Expect(got["name"]).To(Equal("First")) + Expect(got["history"]).To(HaveLen(1)) + + Expect(s.do("alice", http.MethodDelete, "/api/conversations/c1", nil).Code).To(Equal(http.StatusOK)) + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("c2")) + }) + + It("round-trips every field the UI stores on a chat", func() { + body := conversationBody("c1", "Assistant chat") + body["localaiAssistant"] = true + body["mcpMode"] = true + body["mcpServers"] = []string{"github"} + body["mcpResources"] = []string{"res://a"} + body["clientMCPServers"] = []map[string]any{{"id": "local", "url": "http://localhost:9000"}} + body["systemPrompt"] = "be brief" + body["temperature"] = 0.2 + body["contextSize"] = 8192 + body["reasoningEffort"] = "low" + Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", body).Code).To(Equal(http.StatusOK)) + + rec := s.do("alice", http.MethodGet, "/api/conversations/c1", nil) + Expect(rec.Code).To(Equal(http.StatusOK)) + got := decodeJSON(rec) + for _, key := range []string{"localaiAssistant", "mcpMode", "mcpServers", "mcpResources", "clientMCPServers", "systemPrompt", "temperature", "contextSize", "reasoningEffort"} { + Expect(got).To(HaveKey(key), "field %q was dropped", key) + } + Expect(got["localaiAssistant"]).To(BeTrue()) + Expect(got["reasoningEffort"]).To(Equal("low")) + }) + + It("takes the id from the path over the body", func() { + rec := s.do("alice", http.MethodPut, "/api/conversations/from-path", conversationBody("from-body", "x")) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("from-path")) + }) + + It("returns 404 for an unknown conversation", func() { + Expect(s.do("alice", http.MethodGet, "/api/conversations/nope", nil).Code).To(Equal(http.StatusNotFound)) + }) + + It("rejects malformed ids and bodies with 400", func() { + Expect(s.do("alice", http.MethodPut, "/api/conversations/bad!id", conversationBody("x", "x")).Code).To(Equal(http.StatusBadRequest)) + Expect(s.do("alice", http.MethodGet, "/api/conversations/bad!id", nil).Code).To(Equal(http.StatusBadRequest)) + Expect(s.do("alice", http.MethodDelete, "/api/conversations/bad!id", nil).Code).To(Equal(http.StatusBadRequest)) + Expect(s.do("alice", http.MethodPost, "/api/conversations", `{"id":`).Code).To(Equal(http.StatusBadRequest)) + Expect(s.do("alice", http.MethodPut, "/api/conversations/bulk", `{"conversations":`).Code).To(Equal(http.StatusBadRequest)) + Expect(s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{ + "conversations": []any{conversationBody("ok", "ok"), conversationBody("bad id", "x")}, + }).Code).To(Equal(http.StatusBadRequest)) + }) + + It("keeps users apart", func() { + Expect(s.do("alice", http.MethodPut, "/api/conversations/a1", conversationBody("a1", "alice")).Code).To(Equal(http.StatusOK)) + Expect(listedIDs(s.do("bob", http.MethodGet, "/api/conversations", nil))).To(BeEmpty()) + Expect(s.do("bob", http.MethodGet, "/api/conversations/a1", nil).Code).To(Equal(http.StatusNotFound)) + }) + + It("replaces the whole set in bulk and wipes it on delete-all", func() { + Expect(s.do("alice", http.MethodPut, "/api/conversations/old", conversationBody("old", "old")).Code).To(Equal(http.StatusOK)) + + rec := s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{ + "conversations": []any{conversationBody("n1", "n1"), conversationBody("n2", "n2")}, + }) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + Expect(decodeJSON(rec)["count"]).To(BeNumerically("==", 2)) + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("n1", "n2")) + + Expect(s.do("alice", http.MethodDelete, "/api/conversations", nil).Code).To(Equal(http.StatusOK)) + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(BeEmpty()) + }) + + // Review on #9902: a conversation deleted on device A must not come back + // when device B, holding a stale copy, reconnects and writes it again. + Context("a stale client reconnecting after a remote deletion", func() { + It("gets 410 for the write, and the deletion stays visible to everyone", func() { + // Device A and device B both have c1. + Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "shared")).Code).To(Equal(http.StatusOK)) + // Device A deletes it. + Expect(s.do("alice", http.MethodDelete, "/api/conversations/c1", nil).Code).To(Equal(http.StatusOK)) + + // Device B comes back with its stale copy and pushes it. + rec := s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "stale copy")) + Expect(rec.Code).To(Equal(http.StatusGone), rec.Body.String()) + rec = s.do("alice", http.MethodPost, "/api/conversations", conversationBody("c1", "stale copy")) + Expect(rec.Code).To(Equal(http.StatusGone), rec.Body.String()) + + // The list keeps it out and tells B why, so B can drop its copy + // instead of treating it as an unsynced draft. + rec = s.do("alice", http.MethodGet, "/api/conversations", nil) + Expect(listedIDs(rec)).To(BeEmpty()) + deleted := decodeJSON(rec)["deleted"].([]any) + Expect(deleted).To(HaveLen(1)) + tomb := deleted[0].(map[string]any) + Expect(tomb["id"]).To(Equal("c1")) + Expect(tomb["deletedAt"]).To(BeNumerically(">", 0)) + Expect(tomb["version"]).To(BeNumerically("==", 2)) + + Expect(s.do("alice", http.MethodGet, "/api/conversations/c1", nil).Code).To(Equal(http.StatusGone)) + }) + + It("is not undone by a bulk upload either", func() { + Expect(s.do("alice", http.MethodPut, "/api/conversations/c1", conversationBody("c1", "shared")).Code).To(Equal(http.StatusOK)) + Expect(s.do("alice", http.MethodDelete, "/api/conversations", nil).Code).To(Equal(http.StatusOK)) + + rec := s.do("alice", http.MethodPut, "/api/conversations/bulk", map[string]any{ + "conversations": []any{conversationBody("c1", "stale"), conversationBody("fresh", "new")}, + }) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + body := decodeJSON(rec) + Expect(body["count"]).To(BeNumerically("==", 1)) + Expect(body["skipped"]).To(ConsistOf("c1")) + Expect(listedIDs(s.do("alice", http.MethodGet, "/api/conversations", nil))).To(ConsistOf("fresh")) + }) + + It("holds even when the delete reached the server before the first save", func() { + Expect(s.do("alice", http.MethodDelete, "/api/conversations/never-saved", nil).Code).To(Equal(http.StatusOK)) + Expect(s.do("alice", http.MethodPut, "/api/conversations/never-saved", conversationBody("never-saved", "late")).Code).To(Equal(http.StatusGone)) + }) + + It("leaves a genuinely new conversation alone", func() { + Expect(s.do("alice", http.MethodPut, "/api/conversations/gone", conversationBody("gone", "x")).Code).To(Equal(http.StatusOK)) + Expect(s.do("alice", http.MethodDelete, "/api/conversations/gone", nil).Code).To(Equal(http.StatusOK)) + + rec := s.do("alice", http.MethodPut, "/api/conversations/draft", conversationBody("draft", "new draft")) + Expect(rec.Code).To(Equal(http.StatusOK), rec.Body.String()) + Expect(decodeJSON(rec)["version"]).To(BeNumerically("==", 1)) + // A tombstone is per user: bob may use the same id. + Expect(s.do("bob", http.MethodPut, "/api/conversations/gone", conversationBody("gone", "bob")).Code).To(Equal(http.StatusOK)) + }) + }) +}) diff --git a/core/http/routes/localai.go b/core/http/routes/localai.go index ddf0cb3bd..142e75593 100644 --- a/core/http/routes/localai.go +++ b/core/http/routes/localai.go @@ -9,6 +9,7 @@ import ( mcpTools "github.com/mudler/LocalAI/core/http/endpoints/mcp" "github.com/mudler/LocalAI/core/http/middleware" "github.com/mudler/LocalAI/core/schema" + "github.com/mudler/LocalAI/core/services/chathistory" compressionservice "github.com/mudler/LocalAI/core/services/compression" "github.com/mudler/LocalAI/core/services/galleryop" "github.com/mudler/LocalAI/core/services/monitoring" @@ -33,7 +34,8 @@ func RegisterLocalAIRoutes(router *echo.Echo, app *application.Application, adminMiddleware echo.MiddlewareFunc, mcpJobsMw echo.MiddlewareFunc, - mcpMw echo.MiddlewareFunc) { + mcpMw echo.MiddlewareFunc, + chatHistoryMw echo.MiddlewareFunc) { // Themed index first, then the library's wildcard for its own assets. RegisterSwaggerTheme(router) @@ -572,4 +574,25 @@ func RegisterLocalAIRoutes(router *echo.Echo, router.POST("/api/agent/tasks/:name/execute", localai.ExecuteTaskByNameEndpoint(app), mcpJobsMw) } + // Chat history persistence (#9432). Skipped entirely when the store is + // nil (WebUI disabled or no auth database) — registering routes that + // could only ever fail adds surface area for nothing. + if app != nil { + RegisterChatHistoryRoutes(router, app.ChatHistoryStore(), chatHistoryMw) + } +} + +// RegisterChatHistoryRoutes wires the per-user conversation endpoints. A nil +// store registers nothing, so the React UI sees 404 and stays on localStorage. +func RegisterChatHistoryRoutes(router *echo.Echo, store *chathistory.Store, chatHistoryMw echo.MiddlewareFunc) { + if store == nil { + return + } + router.GET("/api/conversations", localai.ListConversationsEndpoint(store), chatHistoryMw) + router.POST("/api/conversations", localai.SaveConversationEndpoint(store), chatHistoryMw) + router.DELETE("/api/conversations", localai.DeleteAllConversationsEndpoint(store), chatHistoryMw) + router.PUT("/api/conversations/bulk", localai.BulkReplaceConversationsEndpoint(store), chatHistoryMw) + router.GET("/api/conversations/:id", localai.GetConversationEndpoint(store), chatHistoryMw) + router.PUT("/api/conversations/:id", localai.SaveConversationByIDEndpoint(store), chatHistoryMw) + router.DELETE("/api/conversations/:id", localai.DeleteConversationEndpoint(store), chatHistoryMw) } diff --git a/core/schema/chat_conversation.go b/core/schema/chat_conversation.go new file mode 100644 index 000000000..05d7b2456 --- /dev/null +++ b/core/schema/chat_conversation.go @@ -0,0 +1,78 @@ +package schema + +import ( + "encoding/json" +) + +// Conversation represents a chat conversation persisted server-side. +// Issue #9432: enables chat history to survive browser refresh / device switch. +// +// The History field is intentionally json.RawMessage so the server stays +// agnostic to message shape — the React UI mixes user / assistant / thinking / +// tool_call / tool_result entries with text, image_url, audio_url, and file +// attachments, and storing them opaquely avoids lossy round-trips. +type Conversation struct { + ID string `json:"id"` + Name string `json:"name"` + Model string `json:"model,omitempty"` + History json.RawMessage `json:"history,omitempty" swaggertype:"array,object"` + SystemPrompt string `json:"systemPrompt,omitempty"` + MCPMode bool `json:"mcpMode,omitempty"` + MCPServers []string `json:"mcpServers,omitempty"` + MCPResources []string `json:"mcpResources,omitempty"` + ClientMCPServers json.RawMessage `json:"clientMCPServers,omitempty" swaggertype:"array,object"` + // LocalAIAssistant wires the chat to the in-process admin MCP server + // (the LocalAI Assistant mode of the Chat page). + LocalAIAssistant bool `json:"localaiAssistant,omitempty"` + Temperature *float64 `json:"temperature,omitempty"` + TopP *float64 `json:"topP,omitempty"` + TopK *float64 `json:"topK,omitempty"` + // ReasoningEffort is the chat's reasoning_effort choice ('' = model config, + // 'none' also hides reasoning traces). + ReasoningEffort string `json:"reasoningEffort,omitempty"` + TokenUsage *ConvTokenUsage `json:"tokenUsage,omitempty"` + ContextSize *int `json:"contextSize,omitempty"` + Metadata map[string]string `json:"metadata,omitempty"` + CreatedAt int64 `json:"createdAt"` + UpdatedAt int64 `json:"updatedAt"` + // Version is assigned by the server: 1 on the first save, +1 on every + // later write including the delete. Clients use a non-zero version to + // tell a conversation the server has seen from a never-synced draft. + // Ignored on input. + Version int64 `json:"version,omitempty"` +} + +// ConversationTombstone marks a conversation the user deleted. The server +// keeps it (without content) so a client holding a stale copy can learn the +// conversation is gone instead of uploading it again. +type ConversationTombstone struct { + ID string `json:"id"` + Version int64 `json:"version"` + DeletedAt int64 `json:"deletedAt"` // Unix milliseconds +} + +// ConversationList is the GET /api/conversations response. +type ConversationList struct { + Conversations []Conversation `json:"conversations"` + Deleted []ConversationTombstone `json:"deleted"` +} + +// ConversationBulkRequest is the PUT /api/conversations/bulk payload. +type ConversationBulkRequest struct { + Conversations []Conversation `json:"conversations"` +} + +// ConversationBulkResponse reports how many conversations a bulk replace +// stored and which ids it refused because they had been deleted. +type ConversationBulkResponse struct { + Status string `json:"status"` + Count int `json:"count"` + Skipped []string `json:"skipped"` +} + +// ConvTokenUsage mirrors the React UI's tokenUsage object on each chat. +type ConvTokenUsage struct { + Prompt int `json:"prompt"` + Completion int `json:"completion"` + Total int `json:"total"` +} diff --git a/core/schema/chat_conversation_ui_test.go b/core/schema/chat_conversation_ui_test.go new file mode 100644 index 000000000..567864e94 --- /dev/null +++ b/core/schema/chat_conversation_ui_test.go @@ -0,0 +1,38 @@ +// SPDX-License-Identifier: MIT +package schema_test + +import ( + "os" + "reflect" + "regexp" + "strings" + + "github.com/mudler/LocalAI/core/schema" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +// Every key serializeChat sends needs a JSON field so persistence cannot +// silently discard a chat setting. +var _ = Describe("Conversation UI schema", func() { + It("keeps every field the UI sends", func() { + src, err := os.ReadFile("../http/react-ui/src/hooks/useChat.js") + Expect(err).NotTo(HaveOccurred(), "read useChat.js") + body := regexp.MustCompile(`(?s)function serializeChat\(chat\) \{\s*return \{(.*?)\n \}`).FindSubmatch(src) + Expect(body).NotTo(BeNil(), "serializeChat not found in useChat.js") + sent := regexp.MustCompile(`(?m)^\s*(\w+):`).FindAllSubmatch(body[1], -1) + Expect(len(sent)).To(BeNumerically(">=", 10), "the serializeChat pattern no longer matches") + + known := map[string]bool{} + ty := reflect.TypeOf(schema.Conversation{}) + for i := 0; i < ty.NumField(); i++ { + if name := strings.Split(ty.Field(i).Tag.Get("json"), ",")[0]; name != "" { + known[name] = true + } + } + for _, m := range sent { + key := string(m[1]) + Expect(known).To(HaveKey(key), "serializeChat sends %q but schema.Conversation has no field for it; the server drops it", key) + } + }) +}) diff --git a/core/services/chathistory/chathistory_suite_test.go b/core/services/chathistory/chathistory_suite_test.go new file mode 100644 index 000000000..b5ff2961f --- /dev/null +++ b/core/services/chathistory/chathistory_suite_test.go @@ -0,0 +1,13 @@ +package chathistory_test + +import ( + "testing" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +func TestChatHistory(t *testing.T) { + RegisterFailHandler(Fail) + RunSpecs(t, "ChatHistory test suite") +} diff --git a/core/services/chathistory/store.go b/core/services/chathistory/store.go new file mode 100644 index 000000000..cd6f71702 --- /dev/null +++ b/core/services/chathistory/store.go @@ -0,0 +1,432 @@ +// Package chathistory implements server-side persistence of WebUI chat +// conversations (GitHub issue #9432). Conversations live in the same +// GORM-backed database as the rest of the per-user state (AgentStore, +// JobStore): the store reuses Application.authDB so chat history, +// agent configs and jobs land in one place. When auth is disabled the +// store is not initialised and the React UI transparently falls back to +// localStorage. +package chathistory + +import ( + "encoding/json" + "errors" + "fmt" + "regexp" + "time" + + "gorm.io/gorm" + "gorm.io/gorm/clause" + + "github.com/mudler/LocalAI/core/schema" +) + +var ( + // ErrNotFound is returned when a conversation does not exist. + ErrNotFound = errors.New("conversation not found") + // ErrInvalidID is returned for malformed conversation IDs. + ErrInvalidID = errors.New("invalid conversation id") + // ErrInvalidUserID is returned for malformed user IDs. + ErrInvalidUserID = errors.New("invalid user id") + // ErrDeleted is returned when a conversation was deleted. Its tombstone + // stays so a client with a stale copy cannot write it back. + ErrDeleted = errors.New("conversation was deleted") + // ErrConflict is returned when concurrent writers kept racing on the + // same conversation and the write could not be settled. + ErrConflict = errors.New("conversation changed concurrently, retry") + + // errRaced makes a transaction start over: another writer created the + // row between our lookup and our insert. + errRaced = errors.New("chathistory: raced with a concurrent create") +) + +// maxTxAttempts bounds the retry loop for errRaced. One retry settles the +// only race we expect (two first writes of the same id); the rest is margin. +const maxTxAttempts = 3 + +// idRegex constrains conversation IDs so they fit into the conv_id column +// (size 128) and cannot smuggle whitespace or control characters into log +// lines / responses. The React UI uses crypto-random IDs +// (utils/format.generateId) which fit comfortably inside this class. +var idRegex = regexp.MustCompile(`^[A-Za-z0-9._-]{1,128}$`) + +// userIDMaxLen caps the user ID length to match the user_id column size. +// We don't constrain the character class because the auth subsystem chooses +// the shape (UUID, OAuth subject, etc.) and SQL parameter binding already +// prevents injection. +const userIDMaxLen = 128 + +// ConversationRecord is the GORM row representation of a chat conversation. +// +// The primary key is (UserID, ConvID): React mints conversation IDs locally +// with no global coordination so they're only unique per user. A composite +// key makes per-user partitioning fall out naturally — anonymous users +// (UserID == "") get their own slice with no special-case code path. +// +// A row with DeletedAt set is a tombstone: the user deleted the conversation, +// Content is emptied, and the row only stays so that no later write can +// bring the conversation back. Version counts every write to the row. +type ConversationRecord struct { + UserID string `gorm:"primaryKey;size:128;column:user_id"` + ConvID string `gorm:"primaryKey;size:128;column:conv_id"` + Content string `gorm:"type:text;column:content"` + Version int64 `gorm:"not null;default:0;column:version"` + CreatedAt time.Time `gorm:"column:created_at"` + UpdatedAt time.Time `gorm:"index;column:updated_at"` + DeletedAt gorm.DeletedAt `gorm:"index;column:deleted_at"` +} + +// TableName returns the database table name for ConversationRecord. +func (ConversationRecord) TableName() string { return "chat_conversations" } + +// Store persists conversations to a GORM-backed database, partitioned by +// userID. The empty string is treated as the anonymous (no-auth) user. +type Store struct { + db *gorm.DB +} + +// New creates a new Store backed by db and auto-migrates the schema. The +// caller is expected to pass the shared authDB so chat history sits in +// the same database as the other per-user state in LocalAI. +func New(db *gorm.DB) (*Store, error) { + if db == nil { + return nil, errors.New("chathistory: nil *gorm.DB") + } + if err := db.AutoMigrate(&ConversationRecord{}); err != nil { + return nil, fmt.Errorf("chathistory: auto-migrate: %w", err) + } + return &Store{db: db}, nil +} + +func validateID(id string) error { + if !idRegex.MatchString(id) { + return ErrInvalidID + } + return nil +} + +func validateUserID(id string) error { + if len(id) > userIDMaxLen { + return ErrInvalidUserID + } + return nil +} + +// List returns the live conversations for userID, sorted newest-updated first. +// Deleted conversations are reported by Tombstones instead. +func (s *Store) List(userID string) ([]schema.Conversation, error) { + if err := validateUserID(userID); err != nil { + return nil, err + } + var rows []ConversationRecord + if err := s.db. + Where("user_id = ?", userID). + Order("updated_at DESC"). + Find(&rows).Error; err != nil { + return nil, fmt.Errorf("chathistory: list: %w", err) + } + out := make([]schema.Conversation, 0, len(rows)) + for _, r := range rows { + c, err := decodeRecord(r) + if err != nil { + return nil, err + } + out = append(out, *c) + } + return out, nil +} + +// Tombstones returns the conversations userID deleted, newest deletion first. +func (s *Store) Tombstones(userID string) ([]schema.ConversationTombstone, error) { + if err := validateUserID(userID); err != nil { + return nil, err + } + var rows []ConversationRecord + if err := s.db.Unscoped(). + Select("conv_id", "version", "deleted_at"). + Where("user_id = ? AND deleted_at IS NOT NULL", userID). + Order("deleted_at DESC"). + Find(&rows).Error; err != nil { + return nil, fmt.Errorf("chathistory: tombstones: %w", err) + } + out := make([]schema.ConversationTombstone, 0, len(rows)) + for _, r := range rows { + out = append(out, schema.ConversationTombstone{ + ID: r.ConvID, + Version: r.Version, + DeletedAt: r.DeletedAt.Time.UnixMilli(), + }) + } + return out, nil +} + +// Get returns a single conversation: ErrNotFound if it never existed, +// ErrDeleted if the user deleted it. +func (s *Store) Get(userID, id string) (*schema.Conversation, error) { + if err := validateUserID(userID); err != nil { + return nil, err + } + if err := validateID(id); err != nil { + return nil, err + } + row, err := lookup(s.db, userID, id) + if err != nil { + return nil, err + } + if row == nil { + return nil, ErrNotFound + } + if row.DeletedAt.Valid { + return nil, ErrDeleted + } + return decodeRecord(*row) +} + +// Save upserts a conversation and returns it with its new Version. A +// conversation the user deleted is never written again: Save returns +// ErrDeleted, so a client holding a stale copy cannot resurrect it. +// +// CreatedAt and UpdatedAt are client-managed Unix milliseconds and are +// stored as sent; the UI compares UpdatedAt across devices, so the server +// clock must not replace it. Zero values are stamped with the current time, +// and a zero CreatedAt on an update keeps the stored one. +func (s *Store) Save(userID string, conv schema.Conversation) (*schema.Conversation, error) { + if err := validateUserID(userID); err != nil { + return nil, err + } + if err := validateID(conv.ID); err != nil { + return nil, err + } + var saved *schema.Conversation + err := s.transaction(func(tx *gorm.DB) error { + var err error + saved, err = saveInTx(tx, userID, conv) + return err + }) + if err != nil { + return nil, err + } + return saved, nil +} + +// saveInTx does the lookup and the write in the caller's transaction. The +// version bump is a single UPDATE ... SET version = version + 1 guarded by +// deleted_at IS NULL, so concurrent writers each count, and a delete that +// commits between the lookup and the write still wins. +func saveInTx(tx *gorm.DB, userID string, conv schema.Conversation) (*schema.Conversation, error) { + existing, err := lookup(tx, userID, conv.ID) + if err != nil { + return nil, err + } + if existing != nil && existing.DeletedAt.Valid { + return nil, ErrDeleted + } + + now := time.Now().UnixMilli() + if conv.CreatedAt == 0 { + conv.CreatedAt = now + if existing != nil { + // Best-effort: a malformed previous row just gets a fresh stamp. + if prev, derr := decodeRecord(*existing); derr == nil && prev.CreatedAt != 0 { + conv.CreatedAt = prev.CreatedAt + } + } + } + if conv.UpdatedAt == 0 { + conv.UpdatedAt = now + } + // The version lives in its own column; keep it out of the stored JSON. + conv.Version = 0 + data, err := json.Marshal(conv) + if err != nil { + return nil, fmt.Errorf("chathistory: marshal: %w", err) + } + + if existing == nil { + res := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&ConversationRecord{ + UserID: userID, + ConvID: conv.ID, + Content: string(data), + Version: 1, + }) + if res.Error != nil { + return nil, fmt.Errorf("chathistory: insert: %w", res.Error) + } + if res.RowsAffected == 0 { + return nil, errRaced + } + conv.Version = 1 + return &conv, nil + } + + // The default scope adds deleted_at IS NULL. + res := tx.Model(&ConversationRecord{}). + Where("user_id = ? AND conv_id = ?", userID, conv.ID). + Updates(map[string]any{ + "content": string(data), + "version": gorm.Expr("version + 1"), + }) + if res.Error != nil { + return nil, fmt.Errorf("chathistory: update: %w", res.Error) + } + if res.RowsAffected == 0 { + return nil, ErrDeleted + } + var version int64 + if err := tx.Model(&ConversationRecord{}). + Select("version"). + Where("user_id = ? AND conv_id = ?", userID, conv.ID). + Scan(&version).Error; err != nil { + return nil, fmt.Errorf("chathistory: read version: %w", err) + } + conv.Version = version + return &conv, nil +} + +// ReplaceAll makes convs the user's live conversation set in one +// transaction: each one is upserted, and every other live conversation is +// deleted (tombstoned, so the deletion reaches other devices too). Ids the +// user already deleted are not written and are returned in skipped. +func (s *Store) ReplaceAll(userID string, convs []schema.Conversation) (skipped []string, err error) { + if err := validateUserID(userID); err != nil { + return nil, err + } + for _, c := range convs { + if err := validateID(c.ID); err != nil { + return nil, err + } + } + + err = s.transaction(func(tx *gorm.DB) error { + skipped = skipped[:0] + keep := make(map[string]struct{}, len(convs)) + for _, c := range convs { + keep[c.ID] = struct{}{} + if _, err := saveInTx(tx, userID, c); err != nil { + if errors.Is(err, ErrDeleted) { + skipped = append(skipped, c.ID) + continue + } + return err + } + } + + var live []string + if err := tx.Model(&ConversationRecord{}). + Where("user_id = ?", userID). + Pluck("conv_id", &live).Error; err != nil { + return fmt.Errorf("chathistory: replace list: %w", err) + } + var drop []string + for _, id := range live { + if _, ok := keep[id]; !ok { + drop = append(drop, id) + } + } + if len(drop) == 0 { + return nil + } + return tombstone(tx.Where("conv_id IN ?", drop), userID) + }) + if err != nil { + return nil, err + } + return skipped, nil +} + +// Delete deletes a conversation by turning it into a tombstone. Deleting is +// idempotent, and deleting an id the server has not seen yet still records +// a tombstone: the UI deletes immediately while a debounced save of the same +// conversation may still be in flight, and that save must not win. +func (s *Store) Delete(userID, id string) error { + if err := validateUserID(userID); err != nil { + return err + } + if err := validateID(id); err != nil { + return err + } + return s.transaction(func(tx *gorm.DB) error { + existing, err := lookup(tx, userID, id) + if err != nil { + return err + } + if existing == nil { + res := tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&ConversationRecord{ + UserID: userID, + ConvID: id, + Version: 1, + DeletedAt: gorm.DeletedAt{Time: time.Now(), Valid: true}, + }) + if res.Error != nil { + return fmt.Errorf("chathistory: delete: %w", res.Error) + } + if res.RowsAffected == 0 { + return errRaced + } + return nil + } + if existing.DeletedAt.Valid { + return nil + } + return tombstone(tx.Where("conv_id = ?", id), userID) + }) +} + +// DeleteAll deletes every conversation of a user, leaving tombstones so the +// deletion reaches the user's other devices. +func (s *Store) DeleteAll(userID string) error { + if err := validateUserID(userID); err != nil { + return err + } + return tombstone(s.db, userID) +} + +// tombstone turns the user's live rows matched by scope into tombstones: +// content dropped, version bumped, deleted_at set. +func tombstone(scope *gorm.DB, userID string) error { + err := scope.Unscoped(). + Model(&ConversationRecord{}). + Where("user_id = ? AND deleted_at IS NULL", userID). + Updates(map[string]any{ + "content": "", + "version": gorm.Expr("version + 1"), + "deleted_at": time.Now(), + }).Error + if err != nil { + return fmt.Errorf("chathistory: delete: %w", err) + } + return nil +} + +// transaction runs fn in a transaction and starts over when it lost a race +// with a concurrent first write of the same id. +func (s *Store) transaction(fn func(tx *gorm.DB) error) error { + for range maxTxAttempts { + err := s.db.Transaction(fn) + if !errors.Is(err, errRaced) { + return err + } + } + return ErrConflict +} + +// lookup returns the row for (userID, id) including tombstones, or nil. +func lookup(db *gorm.DB, userID, id string) (*ConversationRecord, error) { + var row ConversationRecord + err := db.Unscoped().Where("user_id = ? AND conv_id = ?", userID, id).Take(&row).Error + if errors.Is(err, gorm.ErrRecordNotFound) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("chathistory: lookup: %w", err) + } + return &row, nil +} + +func decodeRecord(r ConversationRecord) (*schema.Conversation, error) { + var c schema.Conversation + if err := json.Unmarshal([]byte(r.Content), &c); err != nil { + return nil, fmt.Errorf("chathistory: unmarshal %q/%q: %w", r.UserID, r.ConvID, err) + } + c.Version = r.Version + return &c, nil +} diff --git a/core/services/chathistory/store_sqlite_test.go b/core/services/chathistory/store_sqlite_test.go new file mode 100644 index 000000000..bf77a8f7f --- /dev/null +++ b/core/services/chathistory/store_sqlite_test.go @@ -0,0 +1,27 @@ +// SPDX-License-Identifier: MIT +//go:build auth + +package chathistory_test + +import ( + "path/filepath" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + "gorm.io/gorm" + + "github.com/mudler/LocalAI/core/http/auth" +) + +// SQLite is the default auth database. Opening it through auth.InitDB keeps +// the production DSN (busy timeout, immediate transactions). +var _ = Describe("Store on SQLite", func() { + describeStore(func() *gorm.DB { + db, err := auth.InitDB(filepath.Join(GinkgoT().TempDir(), "auth.db")) + Expect(err).NotTo(HaveOccurred()) + sqlDB, err := db.DB() + Expect(err).NotTo(HaveOccurred()) + DeferCleanup(sqlDB.Close) + return db + }) +}) diff --git a/core/services/chathistory/store_test.go b/core/services/chathistory/store_test.go new file mode 100644 index 000000000..42da7fa16 --- /dev/null +++ b/core/services/chathistory/store_test.go @@ -0,0 +1,365 @@ +package chathistory_test + +import ( + "encoding/json" + + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" + + "gorm.io/gorm" + + "github.com/mudler/LocalAI/core/schema" + "github.com/mudler/LocalAI/core/services/chathistory" + "github.com/mudler/LocalAI/core/services/testutil" +) + +func newConv(id, name string) schema.Conversation { + history, _ := json.Marshal([]map[string]any{ + {"role": "user", "content": "hi"}, + {"role": "assistant", "content": "hello"}, + }) + return schema.Conversation{ + ID: id, + Name: name, + Model: "test-model", + History: history, + } +} + +// The store runs on whichever database backs auth: SQLite by default, +// PostgreSQL in distributed setups. Every spec runs against both so the +// tombstone and version SQL cannot drift into one dialect. +var _ = Describe("Store on PostgreSQL", func() { + describeStore(testutil.SetupTestDB) +}) + +func describeStore(openDB func() *gorm.DB) { + var ( + db *gorm.DB + store *chathistory.Store + ) + + BeforeEach(func() { + db = openDB() + var err error + store, err = chathistory.New(db) + Expect(err).NotTo(HaveOccurred()) + }) + + Context("basic CRUD", func() { + const userID = "alice" + + It("saves, lists, gets, and deletes a conversation", func() { + _, err := store.Save(userID, newConv("c1", "First")) + Expect(err).NotTo(HaveOccurred()) + _, err = store.Save(userID, newConv("c2", "Second")) + Expect(err).NotTo(HaveOccurred()) + + list, err := store.List(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(list).To(HaveLen(2)) + + got, err := store.Get(userID, "c1") + Expect(err).NotTo(HaveOccurred()) + Expect(got.Name).To(Equal("First")) + Expect(got.CreatedAt).NotTo(BeZero(), "Save should populate CreatedAt") + Expect(got.UpdatedAt).NotTo(BeZero(), "Save should populate UpdatedAt") + + Expect(store.Delete(userID, "c1")).To(Succeed()) + _, err = store.Get(userID, "c1") + Expect(err).To(MatchError(chathistory.ErrDeleted)) + }) + }) + + Context("persistence across Store instances", func() { + // Two Stores sharing the same *gorm.DB simulate a process restart: + // no shared in-memory state, so the second must read what the first + // wrote for the round-trip to succeed. + It("loads conversations written by a previous instance", func() { + first, err := chathistory.New(db) + Expect(err).NotTo(HaveOccurred()) + _, err = first.Save("bob", newConv("x", "Hi")) + Expect(err).NotTo(HaveOccurred()) + + second, err := chathistory.New(db) + Expect(err).NotTo(HaveOccurred()) + got, err := second.Get("bob", "x") + Expect(err).NotTo(HaveOccurred()) + Expect(got.Name).To(Equal("Hi")) + }) + }) + + Context("user isolation", func() { + It("never leaks one user's data to another", func() { + _, err := store.Save("alice", newConv("a1", "alice's chat")) + Expect(err).NotTo(HaveOccurred()) + _, err = store.Save("bob", newConv("b1", "bob's chat")) + Expect(err).NotTo(HaveOccurred()) + + bobList, err := store.List("bob") + Expect(err).NotTo(HaveOccurred()) + Expect(bobList).To(HaveLen(1)) + Expect(bobList[0].ID).To(Equal("b1")) + + _, err = store.Get("bob", "a1") + Expect(err).To(MatchError(chathistory.ErrNotFound)) + }) + }) + + Context("malformed IDs", func() { + // The DB-backed store no longer needs to defend against path + // traversal, but idRegex still rejects whitespace / control + // characters so IDs stay safe in logs and HTTP responses. The + // same payloads exercise the empty-string and over-length cases. + DescribeTable("rejects", + func(badID string) { + _, err := store.Save("alice", schema.Conversation{ID: badID, Name: "x"}) + Expect(err).To(HaveOccurred()) + }, + Entry("path traversal", "../etc/passwd"), + Entry("forward slash", "a/b"), + Entry("back slash", "a\\b"), + Entry("empty id", ""), + Entry("contains spaces", "id with spaces"), + ) + }) + + Context("ReplaceAll", func() { + // Bulk migration scenario: client uploads its entire conversation + // set in one shot, the store should overwrite anything previously + // there instead of merging. + It("overwrites the entire conversation set", func() { + const userID = "alice" + for _, id := range []string{"a", "b", "c"} { + _, err := store.Save(userID, newConv(id, id)) + Expect(err).NotTo(HaveOccurred()) + } + + // Second return value (error) must be nil; the skipped list empty. + Expect(store.ReplaceAll(userID, []schema.Conversation{newConv("z", "z")})).To(BeEmpty()) + + list, err := store.List(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(list).To(HaveLen(1)) + Expect(list[0].ID).To(Equal("z")) + }) + }) + + Context("anonymous user", func() { + // UserID == "" maps to the anonymous slice. We can no longer pin a + // directory layout (the previous file-based store wrote + // anonymous/conversations.json), so the test checks the round-trip + // and the per-user isolation guarantee instead. + It("stores and retrieves conversations for an empty user ID", func() { + _, err := store.Save("", newConv("solo", "anon chat")) + Expect(err).NotTo(HaveOccurred()) + + got, err := store.Get("", "solo") + Expect(err).NotTo(HaveOccurred()) + Expect(got.Name).To(Equal("anon chat")) + + // And the conversation must NOT leak to a logged-in user. + _, err = store.Get("alice", "solo") + Expect(err).To(MatchError(chathistory.ErrNotFound)) + }) + }) + + Context("DeleteAll", func() { + It("wipes the user's entire chat history without touching others", func() { + _, err := store.Save("alice", newConv("a1", "alice 1")) + Expect(err).NotTo(HaveOccurred()) + _, err = store.Save("alice", newConv("a2", "alice 2")) + Expect(err).NotTo(HaveOccurred()) + _, err = store.Save("bob", newConv("b1", "bob 1")) + Expect(err).NotTo(HaveOccurred()) + + Expect(store.DeleteAll("alice")).To(Succeed()) + + aliceList, err := store.List("alice") + Expect(err).NotTo(HaveOccurred()) + Expect(aliceList).To(BeEmpty()) + + bobList, err := store.List("bob") + Expect(err).NotTo(HaveOccurred()) + Expect(bobList).To(HaveLen(1)) + }) + }) + // A conversation deleted on one device must stay deleted when a client + // with a stale copy writes it again (review on #9902). Deletes leave a + // tombstone the store refuses to overwrite. + Context("tombstones", func() { + const userID = "alice" + + It("rejects a save after delete instead of resurrecting the row", func() { + _, err := store.Save(userID, newConv("c1", "First")) + Expect(err).NotTo(HaveOccurred()) + Expect(store.Delete(userID, "c1")).To(Succeed()) + + _, err = store.Save(userID, newConv("c1", "stale copy")) + Expect(err).To(MatchError(chathistory.ErrDeleted)) + + list, err := store.List(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(list).To(BeEmpty()) + Expect(tombstoneIDs(store, userID)).To(ConsistOf("c1")) + _, err = store.Get(userID, "c1") + Expect(err).To(MatchError(chathistory.ErrDeleted)) + }) + + It("drops the content of a deleted conversation", func() { + _, err := store.Save(userID, newConv("c1", "secret")) + Expect(err).NotTo(HaveOccurred()) + Expect(store.Delete(userID, "c1")).To(Succeed()) + + var row chathistory.ConversationRecord + Expect(db.Unscoped().Where("user_id = ? AND conv_id = ?", userID, "c1").Take(&row).Error).To(Succeed()) + Expect(row.DeletedAt.Valid).To(BeTrue()) + Expect(row.Content).To(BeEmpty()) + }) + + It("records a delete that arrives before the conversation's first save", func() { + // The UI deletes right away while a debounced PUT may still be in + // flight; whichever lands second must not bring the chat back. + Expect(store.Delete(userID, "early")).To(Succeed()) + _, err := store.Save(userID, newConv("early", "late write")) + Expect(err).To(MatchError(chathistory.ErrDeleted)) + }) + + It("treats a repeated delete as success", func() { + _, err := store.Save(userID, newConv("c1", "First")) + Expect(err).NotTo(HaveOccurred()) + Expect(store.Delete(userID, "c1")).To(Succeed()) + Expect(store.Delete(userID, "c1")).To(Succeed()) + Expect(tombstoneIDs(store, userID)).To(ConsistOf("c1")) + }) + + It("tombstones every conversation on DeleteAll", func() { + for _, id := range []string{"a", "b"} { + _, err := store.Save(userID, newConv(id, id)) + Expect(err).NotTo(HaveOccurred()) + } + _, err := store.Save("bob", newConv("a", "bob's a")) + Expect(err).NotTo(HaveOccurred()) + + Expect(store.DeleteAll(userID)).To(Succeed()) + Expect(tombstoneIDs(store, userID)).To(ConsistOf("a", "b")) + _, err = store.Save(userID, newConv("a", "stale")) + Expect(err).To(MatchError(chathistory.ErrDeleted)) + + // bob shares the id, not the tombstone. + _, err = store.Save("bob", newConv("a", "bob again")) + Expect(err).NotTo(HaveOccurred()) + }) + + It("does not let ReplaceAll resurrect deleted ids and tombstones what it replaces", func() { + for _, id := range []string{"a", "b"} { + _, err := store.Save(userID, newConv(id, id)) + Expect(err).NotTo(HaveOccurred()) + } + Expect(store.Delete(userID, "b")).To(Succeed()) + + skipped, err := store.ReplaceAll(userID, []schema.Conversation{newConv("b", "stale b"), newConv("c", "c")}) + Expect(err).NotTo(HaveOccurred()) + Expect(skipped).To(ConsistOf("b")) + + list, err := store.List(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(list).To(HaveLen(1)) + Expect(list[0].ID).To(Equal("c")) + // "a" was replaced away: other devices must see it as deleted too. + Expect(tombstoneIDs(store, userID)).To(ConsistOf("a", "b")) + }) + }) + + Context("versions", func() { + const userID = "alice" + + It("starts at 1 and bumps on every write, including the delete", func() { + Expect(savedVersion(store, userID, newConv("c1", "v1"))).To(Equal(int64(1))) + Expect(savedVersion(store, userID, newConv("c1", "v2"))).To(Equal(int64(2))) + + list, err := store.List(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(list[0].Version).To(Equal(int64(2))) + + Expect(store.Delete(userID, "c1")).To(Succeed()) + tombs, err := store.Tombstones(userID) + Expect(err).NotTo(HaveOccurred()) + Expect(tombs).To(HaveLen(1)) + Expect(tombs[0].Version).To(Equal(int64(3))) + Expect(tombs[0].DeletedAt).NotTo(BeZero()) + }) + + It("ignores a client-supplied version", func() { + conv := newConv("c1", "x") + conv.Version = 41 + Expect(savedVersion(store, userID, conv)).To(Equal(int64(1))) + }) + + It("counts every one of many concurrent writes", func() { + Expect(savedVersion(store, userID, newConv("hot", "seed"))).To(Equal(int64(1))) + const writers = 8 + errs := make(chan error, writers) + for i := 0; i < writers; i++ { + go func() { + defer GinkgoRecover() + _, err := store.Save(userID, newConv("hot", "concurrent")) + errs <- err + }() + } + for i := 0; i < writers; i++ { + Expect(<-errs).NotTo(HaveOccurred()) + } + got, err := store.Get(userID, "hot") + Expect(err).NotTo(HaveOccurred()) + Expect(got.Version).To(Equal(int64(1 + writers))) + }) + }) + + Context("timestamps", func() { + const userID = "alice" + + // The UI decides which copy is newer by comparing updatedAt across + // devices, so the server must store the client's value rather than + // its own clock. + It("keeps the client's updatedAt and createdAt", func() { + conv := newConv("c1", "x") + conv.CreatedAt = 1000 + conv.UpdatedAt = 2000 + _, err := store.Save(userID, conv) + Expect(err).NotTo(HaveOccurred()) + got, err := store.Get(userID, "c1") + Expect(err).NotTo(HaveOccurred()) + Expect(got.CreatedAt).To(Equal(int64(1000))) + Expect(got.UpdatedAt).To(Equal(int64(2000))) + }) + + It("keeps the original createdAt when an update omits it", func() { + conv := newConv("c1", "x") + conv.CreatedAt = 1000 + _, err := store.Save(userID, conv) + Expect(err).NotTo(HaveOccurred()) + _, err = store.Save(userID, newConv("c1", "y")) + Expect(err).NotTo(HaveOccurred()) + got, err := store.Get(userID, "c1") + Expect(err).NotTo(HaveOccurred()) + Expect(got.CreatedAt).To(Equal(int64(1000))) + }) + }) +} + +func savedVersion(store *chathistory.Store, userID string, conv schema.Conversation) int64 { + saved, err := store.Save(userID, conv) + ExpectWithOffset(1, err).NotTo(HaveOccurred()) + return saved.Version +} + +func tombstoneIDs(store *chathistory.Store, userID string) []string { + tombs, err := store.Tombstones(userID) + ExpectWithOffset(1, err).NotTo(HaveOccurred()) + ids := []string{} + for _, t := range tombs { + ids = append(ids, t.ID) + } + return ids +} diff --git a/docs/content/features/api-discovery.md b/docs/content/features/api-discovery.md index 1aaf07831..555cd1ec4 100644 --- a/docs/content/features/api-discovery.md +++ b/docs/content/features/api-discovery.md @@ -119,6 +119,7 @@ Returns a compact list of instruction areas: | `mcp` | Model Context Protocol - tool-augmented chat with MCP servers | | `agents` | Agent task and job management | | `video` | Video generation from text prompts | +| `chat-history` | Server-side persistence of web UI chat conversations, with tombstones for deletions (auth only) | ### Get an instruction guide diff --git a/docs/content/features/chat-history.md b/docs/content/features/chat-history.md new file mode 100644 index 000000000..997e7f848 --- /dev/null +++ b/docs/content/features/chat-history.md @@ -0,0 +1,96 @@ ++++ +disableToc = false +title = "Chat History" +weight = 49 +url = "/features/chat-history/" ++++ + +Chat history keeps the conversations of the web UI [Chat]({{%relref "features/chat" %}}) page on the server, per user, so they survive a browser reset and follow you to another device. It is built on the [user authentication system]({{%relref "features/authentication" %}}): conversations live in the same database as users, sessions and API keys (SQLite by default, PostgreSQL when `LOCALAI_AUTH_DATABASE_URL` points at one). + +{{% notice note %}} +Chat history is only active when user authentication is enabled (`LOCALAI_AUTH=true`). Without it, or with only legacy API keys, the endpoints below are not registered and the web UI keeps conversations in the browser (`localai_chats_data` in `localStorage`), as before. With it, the browser copy is kept per account (see [One browser cache per account](#one-browser-cache-per-account)). Disabling the web UI (`LOCALAI_DISABLE_WEBUI=true`) also disables chat history. +{{% /notice %}} + +## Permission + +Access is controlled by the `chat_history` feature permission. Like the other API features it is **on by default** for new users; an admin can turn it off per user under **Settings → Users and keys**. A user without it gets `403` from every endpoint, and their web UI falls back to browser storage. + +## Deletions are final + +A deleted conversation must not come back because another device still has a copy. The server therefore keeps a **tombstone** for every deleted conversation: the row stays, its content is dropped, and it is marked deleted. + +- Writing a conversation that has a tombstone returns `410 Gone`. Nothing is written. +- `GET /api/conversations` lists tombstones under `deleted`, so a client can drop its local copies of those ids instead of uploading them again. +- `DELETE` is idempotent, and deleting an id the server has never seen still records a tombstone. A delete that overtakes an in-flight save of the same conversation therefore still wins. +- Tombstones are per user. Another user can use the same id. + +Every conversation also carries a server-assigned `version`: `1` after the first save, then one more for every write, including the delete. A client that has a non-zero version for a conversation knows the server has seen it; a conversation without one is a draft that was never uploaded. + +Within a live conversation the last write wins: there is no merge of two devices editing the same conversation at the same time. `createdAt` and `updatedAt` (Unix milliseconds) are stored as the client sends them, so clients can compare `updatedAt` to pick the newer copy; the server only fills them in when they are `0`. + +## How the web UI syncs + +On load the Chat page asks the server for the list and reconciles it with what the browser has: + +- A conversation the server reports as deleted is removed locally. +- A conversation on both sides keeps the copy with the newer `updatedAt`. A message you send while the list is still loading is kept, and uploaded afterwards. +- A conversation only in the browser is uploaded if it has never been synced (no `version`). If it has a version but the server no longer has it, it is removed locally: it was synced before, so the server dropped it (or the browser now belongs to another account). +- A conversation only on the server is added. +- A conversation you delete while the list is still loading is deleted on the server once the list arrives. + +After that, every change is saved on its own (debounced, only conversations that changed). When a save returns `410`, the UI removes that conversation locally. On any other error it keeps the browser copy and tries again with the next change. `localStorage` stays a cache of the last state either way. The web UI does not use the bulk endpoint: every upload goes through the per-conversation save, so the tombstone check applies to each one. + +### Deletes wait for the server + +A delete (one conversation, **Clear all**, or a delete on the Home page) is removed from the screen at once, and kept in the browser as a pending delete until the server confirms it. If the server cannot be reached, the delete is sent again with the next change, when the browser comes back online, and on the next load; until then the list from the server cannot bring the conversation back. While a **Clear all** is pending, no conversation is uploaded, so a chat started after it is not caught by it. + +Clearing all chats immediately updates the browser cache, including unsynced drafts. You can leave the page without waiting for the server to confirm deletion. + +### One browser cache per account + +The browser cache belongs to the signed-in account: it is stored under `localai_chats_data:`, together with that account's pending deletes. When one account signs out and another signs in on the same browser, the second account starts from its own cache and its own server list. A conversation the first account could not upload yet (for example because its first save failed) stays in the first account's cache and is uploaded when that account signs in again; it is never uploaded into another account. Signing out does not delete the cache. + +Conversations stored in the browser before chat history was enabled live under the shared key `localai_chats_data`. When you are signed in, the Chat page does not read that key and does not upload it, because the browser cannot tell which account it belongs to. Without user authentication the web UI keeps using it, as before. + +## API + +All endpoints act on the conversations of the calling user and need a session or API key. + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/conversations` | Live conversations (`conversations`, newest first) and tombstones (`deleted`) | +| `POST` | `/api/conversations` | Save (upsert) the conversation in the body | +| `PUT` | `/api/conversations/{id}` | Save (upsert); the path id overrides the body id | +| `GET` | `/api/conversations/{id}` | One conversation; `404` if it never existed, `410` if it was deleted | +| `DELETE` | `/api/conversations/{id}` | Delete, leaving a tombstone. Idempotent | +| `DELETE` | `/api/conversations` | Delete all of the user's conversations, leaving tombstones | +| `PUT` | `/api/conversations/bulk` | Make the payload the user's live set: upsert each conversation, delete (tombstone) the others. Ids that were deleted earlier are not written and come back in `skipped` | + +Status codes: `400` for a malformed id or body, `401` without credentials, `403` without the `chat_history` permission, `409` when concurrent writers kept racing on the same id (retry), `410` for a deleted conversation. + +Conversation ids are 1 to 128 characters from `A-Z a-z 0-9 . _ -`. A conversation carries what the Chat page keeps per chat: name, model, system prompt, sampling and reasoning-effort settings, MCP and LocalAI Assistant settings, token usage and context size (`schema.Conversation` in `/swagger`). The message list (`history`) is stored as sent, so every message shape the UI uses (text, images, audio, files, tool calls, thinking) survives the round trip. + +### Example + +```bash +# Save a conversation +curl -X PUT http://localhost:8080/api/conversations/3f9c2a \ + -H "Authorization: Bearer $LOCALAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"id":"3f9c2a","name":"Release notes","model":"qwen3-8b", + "history":[{"role":"user","content":"Summarise the changes"}], + "updatedAt":1760342400000}' +# -> {"id":"3f9c2a", ..., "createdAt":1760342400000, "updatedAt":1760342400000, "version":1} + +# Delete it, then try to write it again from a stale client +curl -X DELETE http://localhost:8080/api/conversations/3f9c2a -H "Authorization: Bearer $LOCALAI_API_KEY" +curl -X PUT http://localhost:8080/api/conversations/3f9c2a \ + -H "Authorization: Bearer $LOCALAI_API_KEY" -H "Content-Type: application/json" \ + -d '{"id":"3f9c2a","name":"Release notes"}' +# -> 410 {"error":"conversation was deleted"} + +curl http://localhost:8080/api/conversations -H "Authorization: Bearer $LOCALAI_API_KEY" +# -> {"conversations":[],"deleted":[{"id":"3f9c2a","version":2,"deletedAt":1760342460000}]} +``` + +The machine-readable description is under the `chat-history` tag in the [API discovery]({{%relref "features/api-discovery" %}}) instructions (`GET /api/instructions/chat-history`) and in `/swagger`. diff --git a/docs/content/features/chat.md b/docs/content/features/chat.md index cb34c775b..bdc30d495 100644 --- a/docs/content/features/chat.md +++ b/docs/content/features/chat.md @@ -54,7 +54,7 @@ The microphone button dictates: click it to record, click again to stop, and the Press `Ctrl+K` (`Cmd+K`) or **Chats** to open the list of conversations, grouped by day like **Jump back in** on Home. Type to search names and message text. Arrow keys move, `Enter` opens, `F2` renames and `Delete` removes. Each row also offers rename, duplicate, copy and export. Removing a chat hides it and shows an **Undo** toast; the chat is deleted for good when the toast goes away. The name in the header can be renamed with a click. -The history is stored in this browser (`localai_chats_data`), not on the server. +The history is stored in this browser (`localai_chats_data`). When [user authentication]({{%relref "features/authentication" %}}) is enabled it is also kept on the server for each user and follows you to other devices; see [Chat History]({{%relref "features/chat-history" %}}). ## Settings diff --git a/swagger/docs.go b/swagger/docs.go index 61d1d59f2..007d8f75d 100644 --- a/swagger/docs.go +++ b/swagger/docs.go @@ -881,6 +881,280 @@ const docTemplate = `{ } } }, + "/api/conversations": { + "get": { + "description": "Returns the live conversations, newest first, and in ` + "`" + `deleted` + "`" + ` the conversations the user deleted. A client must drop any local copy whose id appears in ` + "`" + `deleted` + "`" + ` instead of uploading it again.", + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "List chat conversations", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.ConversationList" + } + } + } + }, + "post": { + "description": "Stores the conversation and returns it with its new server-assigned ` + "`" + `version` + "`" + `. ` + "`" + `createdAt` + "`" + `/` + "`" + `updatedAt` + "`" + ` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Save a chat conversation (upsert)", + "parameters": [ + { + "description": "Conversation payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "delete": { + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Delete all chat conversations for the current user", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, + "/api/conversations/bulk": { + "put": { + "description": "Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in ` + "`" + `skipped` + "`" + `.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Replace all chat conversations", + "parameters": [ + { + "description": "Conversations", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.ConversationBulkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.ConversationBulkResponse" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, + "/api/conversations/{id}": { + "get": { + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Get a chat conversation", + "parameters": [ + { + "type": "string", + "description": "Conversation ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "404": { + "description": "Never existed", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "put": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Save a chat conversation by id (upsert)", + "parameters": [ + { + "type": "string", + "description": "Conversation ID (overrides the body id)", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Conversation payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "delete": { + "description": "Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds.", + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Delete a chat conversation", + "parameters": [ + { + "type": "string", + "description": "Conversation ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "400": { + "description": "Invalid id", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, "/api/failover": { "get": { "produces": [ @@ -6148,6 +6422,163 @@ const docTemplate = `{ } } }, + "schema.ConvTokenUsage": { + "type": "object", + "properties": { + "completion": { + "type": "integer" + }, + "prompt": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "schema.Conversation": { + "type": "object", + "properties": { + "clientMCPServers": { + "type": "array", + "items": { + "type": "object" + } + }, + "contextSize": { + "type": "integer" + }, + "createdAt": { + "type": "integer" + }, + "history": { + "type": "array", + "items": { + "type": "object" + } + }, + "id": { + "type": "string" + }, + "localaiAssistant": { + "description": "LocalAIAssistant wires the chat to the in-process admin MCP server\n(the LocalAI Assistant mode of the Chat page).", + "type": "boolean" + }, + "mcpMode": { + "type": "boolean" + }, + "mcpResources": { + "type": "array", + "items": { + "type": "string" + } + }, + "mcpServers": { + "type": "array", + "items": { + "type": "string" + } + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "model": { + "type": "string" + }, + "name": { + "type": "string" + }, + "reasoningEffort": { + "description": "ReasoningEffort is the chat's reasoning_effort choice ('' = model config,\n'none' also hides reasoning traces).", + "type": "string" + }, + "systemPrompt": { + "type": "string" + }, + "temperature": { + "type": "number" + }, + "tokenUsage": { + "$ref": "#/definitions/schema.ConvTokenUsage" + }, + "topK": { + "type": "number" + }, + "topP": { + "type": "number" + }, + "updatedAt": { + "type": "integer" + }, + "version": { + "description": "Version is assigned by the server: 1 on the first save, +1 on every\nlater write including the delete. Clients use a non-zero version to\ntell a conversation the server has seen from a never-synced draft.\nIgnored on input.", + "type": "integer" + } + } + }, + "schema.ConversationBulkRequest": { + "type": "object", + "properties": { + "conversations": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.Conversation" + } + } + } + }, + "schema.ConversationBulkResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + }, + "skipped": { + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "type": "string" + } + } + }, + "schema.ConversationList": { + "type": "object", + "properties": { + "conversations": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "deleted": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.ConversationTombstone" + } + } + } + }, + "schema.ConversationTombstone": { + "type": "object", + "properties": { + "deletedAt": { + "description": "Unix milliseconds", + "type": "integer" + }, + "id": { + "type": "string" + }, + "version": { + "type": "integer" + } + } + }, "schema.DecisionAnswer": { "type": "object", "properties": { diff --git a/swagger/swagger.json b/swagger/swagger.json index 60e0e4114..443e0e767 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -878,6 +878,280 @@ } } }, + "/api/conversations": { + "get": { + "description": "Returns the live conversations, newest first, and in `deleted` the conversations the user deleted. A client must drop any local copy whose id appears in `deleted` instead of uploading it again.", + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "List chat conversations", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.ConversationList" + } + } + } + }, + "post": { + "description": "Stores the conversation and returns it with its new server-assigned `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation the user deleted returns 410 and does not bring it back.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Save a chat conversation (upsert)", + "parameters": [ + { + "description": "Conversation payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "delete": { + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Delete all chat conversations for the current user", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, + "/api/conversations/bulk": { + "put": { + "description": "Upserts every conversation in the payload and deletes the user's other live conversations. Ids the user deleted earlier are not written and are listed in `skipped`.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Replace all chat conversations", + "parameters": [ + { + "description": "Conversations", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.ConversationBulkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.ConversationBulkResponse" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, + "/api/conversations/{id}": { + "get": { + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Get a chat conversation", + "parameters": [ + { + "type": "string", + "description": "Conversation ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "404": { + "description": "Never existed", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "put": { + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Save a chat conversation by id (upsert)", + "parameters": [ + { + "type": "string", + "description": "Conversation ID (overrides the body id)", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Conversation payload", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "400": { + "description": "Invalid id or body", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "410": { + "description": "Deleted", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "delete": { + "description": "Deletes the conversation and keeps a tombstone so no client can write it back. Deleting an unknown or already deleted id succeeds.", + "produces": [ + "application/json" + ], + "tags": [ + "chat-history" + ], + "summary": "Delete a chat conversation", + "parameters": [ + { + "type": "string", + "description": "Conversation ID", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "400": { + "description": "Invalid id", + "schema": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, "/api/failover": { "get": { "produces": [ @@ -6145,6 +6419,163 @@ } } }, + "schema.ConvTokenUsage": { + "type": "object", + "properties": { + "completion": { + "type": "integer" + }, + "prompt": { + "type": "integer" + }, + "total": { + "type": "integer" + } + } + }, + "schema.Conversation": { + "type": "object", + "properties": { + "clientMCPServers": { + "type": "array", + "items": { + "type": "object" + } + }, + "contextSize": { + "type": "integer" + }, + "createdAt": { + "type": "integer" + }, + "history": { + "type": "array", + "items": { + "type": "object" + } + }, + "id": { + "type": "string" + }, + "localaiAssistant": { + "description": "LocalAIAssistant wires the chat to the in-process admin MCP server\n(the LocalAI Assistant mode of the Chat page).", + "type": "boolean" + }, + "mcpMode": { + "type": "boolean" + }, + "mcpResources": { + "type": "array", + "items": { + "type": "string" + } + }, + "mcpServers": { + "type": "array", + "items": { + "type": "string" + } + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "model": { + "type": "string" + }, + "name": { + "type": "string" + }, + "reasoningEffort": { + "description": "ReasoningEffort is the chat's reasoning_effort choice ('' = model config,\n'none' also hides reasoning traces).", + "type": "string" + }, + "systemPrompt": { + "type": "string" + }, + "temperature": { + "type": "number" + }, + "tokenUsage": { + "$ref": "#/definitions/schema.ConvTokenUsage" + }, + "topK": { + "type": "number" + }, + "topP": { + "type": "number" + }, + "updatedAt": { + "type": "integer" + }, + "version": { + "description": "Version is assigned by the server: 1 on the first save, +1 on every\nlater write including the delete. Clients use a non-zero version to\ntell a conversation the server has seen from a never-synced draft.\nIgnored on input.", + "type": "integer" + } + } + }, + "schema.ConversationBulkRequest": { + "type": "object", + "properties": { + "conversations": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.Conversation" + } + } + } + }, + "schema.ConversationBulkResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + }, + "skipped": { + "type": "array", + "items": { + "type": "string" + } + }, + "status": { + "type": "string" + } + } + }, + "schema.ConversationList": { + "type": "object", + "properties": { + "conversations": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.Conversation" + } + }, + "deleted": { + "type": "array", + "items": { + "$ref": "#/definitions/schema.ConversationTombstone" + } + } + } + }, + "schema.ConversationTombstone": { + "type": "object", + "properties": { + "deletedAt": { + "description": "Unix milliseconds", + "type": "integer" + }, + "id": { + "type": "string" + }, + "version": { + "type": "integer" + } + } + }, "schema.DecisionAnswer": { "type": "object", "properties": { diff --git a/swagger/swagger.yaml b/swagger/swagger.yaml index 18c21154c..d990a3e72 100644 --- a/swagger/swagger.yaml +++ b/swagger/swagger.yaml @@ -1013,6 +1013,118 @@ definitions: summary_tokens: type: integer type: object + schema.ConvTokenUsage: + properties: + completion: + type: integer + prompt: + type: integer + total: + type: integer + type: object + schema.Conversation: + properties: + clientMCPServers: + items: + type: object + type: array + contextSize: + type: integer + createdAt: + type: integer + history: + items: + type: object + type: array + id: + type: string + localaiAssistant: + description: |- + LocalAIAssistant wires the chat to the in-process admin MCP server + (the LocalAI Assistant mode of the Chat page). + type: boolean + mcpMode: + type: boolean + mcpResources: + items: + type: string + type: array + mcpServers: + items: + type: string + type: array + metadata: + additionalProperties: + type: string + type: object + model: + type: string + name: + type: string + reasoningEffort: + description: |- + ReasoningEffort is the chat's reasoning_effort choice ('' = model config, + 'none' also hides reasoning traces). + type: string + systemPrompt: + type: string + temperature: + type: number + tokenUsage: + $ref: '#/definitions/schema.ConvTokenUsage' + topK: + type: number + topP: + type: number + updatedAt: + type: integer + version: + description: |- + Version is assigned by the server: 1 on the first save, +1 on every + later write including the delete. Clients use a non-zero version to + tell a conversation the server has seen from a never-synced draft. + Ignored on input. + type: integer + type: object + schema.ConversationBulkRequest: + properties: + conversations: + items: + $ref: '#/definitions/schema.Conversation' + type: array + type: object + schema.ConversationBulkResponse: + properties: + count: + type: integer + skipped: + items: + type: string + type: array + status: + type: string + type: object + schema.ConversationList: + properties: + conversations: + items: + $ref: '#/definitions/schema.Conversation' + type: array + deleted: + items: + $ref: '#/definitions/schema.ConversationTombstone' + type: array + type: object + schema.ConversationTombstone: + properties: + deletedAt: + description: Unix milliseconds + type: integer + id: + type: string + version: + type: integer + type: object schema.DecisionAnswer: properties: choice: @@ -4371,6 +4483,193 @@ paths: summary: Upload a branding asset tags: - branding + /api/conversations: + delete: + produces: + - application/json + responses: + "200": + description: OK + schema: + additionalProperties: + type: string + type: object + summary: Delete all chat conversations for the current user + tags: + - chat-history + get: + description: Returns the live conversations, newest first, and in `deleted` + the conversations the user deleted. A client must drop any local copy whose + id appears in `deleted` instead of uploading it again. + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/schema.ConversationList' + summary: List chat conversations + tags: + - chat-history + post: + consumes: + - application/json + description: Stores the conversation and returns it with its new server-assigned + `version`. `createdAt`/`updatedAt` are kept as sent (Unix ms). Writing a conversation + the user deleted returns 410 and does not bring it back. + parameters: + - description: Conversation payload + in: body + name: body + required: true + schema: + $ref: '#/definitions/schema.Conversation' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/schema.Conversation' + "400": + description: Invalid id or body + schema: + additionalProperties: + type: string + type: object + "410": + description: Deleted + schema: + additionalProperties: + type: string + type: object + summary: Save a chat conversation (upsert) + tags: + - chat-history + /api/conversations/{id}: + delete: + description: Deletes the conversation and keeps a tombstone so no client can + write it back. Deleting an unknown or already deleted id succeeds. + parameters: + - description: Conversation ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + additionalProperties: + type: string + type: object + "400": + description: Invalid id + schema: + additionalProperties: + type: string + type: object + summary: Delete a chat conversation + tags: + - chat-history + get: + parameters: + - description: Conversation ID + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/schema.Conversation' + "404": + description: Never existed + schema: + additionalProperties: + type: string + type: object + "410": + description: Deleted + schema: + additionalProperties: + type: string + type: object + summary: Get a chat conversation + tags: + - chat-history + put: + consumes: + - application/json + parameters: + - description: Conversation ID (overrides the body id) + in: path + name: id + required: true + type: string + - description: Conversation payload + in: body + name: body + required: true + schema: + $ref: '#/definitions/schema.Conversation' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/schema.Conversation' + "400": + description: Invalid id or body + schema: + additionalProperties: + type: string + type: object + "410": + description: Deleted + schema: + additionalProperties: + type: string + type: object + summary: Save a chat conversation by id (upsert) + tags: + - chat-history + /api/conversations/bulk: + put: + consumes: + - application/json + description: Upserts every conversation in the payload and deletes the user's + other live conversations. Ids the user deleted earlier are not written and + are listed in `skipped`. + parameters: + - description: Conversations + in: body + name: body + required: true + schema: + $ref: '#/definitions/schema.ConversationBulkRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/schema.ConversationBulkResponse' + "400": + description: Invalid id or body + schema: + additionalProperties: + type: string + type: object + summary: Replace all chat conversations + tags: + - chat-history /api/failover: get: produces: