OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
fix: live chunk-settings validation and stop clobbering unsaved edits (#2430)
Nathan Bakareb632faf8e811
diff --git a/frontend/app/settings/_components/ingest-settings-section.test.tsx b/frontend/app/settings/_components/ingest-settings-section.test.tsxnew file mode 100644index 000000000..7bf10d04d--- /dev/null+++ b/frontend/app/settings/_components/ingest-settings-section.test.tsx@@ -0,0 +1,376 @@+import type { RequestHandler } from "msw";+import { HttpResponse, http } from "msw";+import { describe, expect, it, vi } from "vitest";+import { IngestSettingsSection } from "@/app/settings/_components/ingest-settings-section";+import { authPresets } from "@/test-utils/fixtures/auth";+import { makeSettings } from "@/test-utils/fixtures/settings";+import { server } from "@/test-utils/msw/server";+import {+ act,+ fireEvent,+ renderWithProviders,+ screen,+ waitFor,+} from "@/test-utils/render";++// ── Global mocks ─────────────────────────────────────────────────────────────++vi.mock("@/lib/analytics", () => ({ trackButton: vi.fn() }));++// Avoid BrandProvider needing its own auth bootstrap; the component only reads+// isCloudBrand to conditionally show one UI branch.+vi.mock("@/contexts/brand-context", async (importOriginal) => ({+ ...(await importOriginal<typeof import("@/contexts/brand-context")>()),+ useIsCloudBrand: () => false,+}));++// Suppress toasts — we're not asserting on them here and they can leak into+// unrelated assertions through aria-live regions.+vi.mock("sonner", () => ({ toast: { success: vi.fn(), error: vi.fn() } }));++// ── Helpers ───────────────────────────────────────────────────────────────────++/**+ * Default GET handlers for every test.+ * - /api/settings → 1024 / 50 chunk settings, VLM disabled so the auto-select+ * effect never fires an extra /api/models/catalog request.+ * - /api/models/catalog → empty provider list; prevents unhandled-request error+ * from useGetModelCatalogQuery (always enabled for authed users).+ */+function baseHandlers(+ knowledge: { chunk_size: number; chunk_overlap: number } = {+ chunk_size: 1024,+ chunk_overlap: 50,+ },+): RequestHandler[] {+ return [+ http.get("/api/settings", () =>+ HttpResponse.json(+ makeSettings({+ knowledge,+ show_vlm_settings: false,+ }),+ ),+ ),+ http.get("/api/models/catalog", () => HttpResponse.json({ providers: [] })),+ ];+}++function renderSection(+ extraHandlers: RequestHandler[] = [],+ knowledge?: { chunk_size: number; chunk_overlap: number },+) {+ return renderWithProviders(<IngestSettingsSection />, {+ providers: ["tooltip", "auth", "unsavedChanges"],+ auth: authPresets.admin,+ handlers: [...baseHandlers(knowledge), ...extraHandlers],+ });+}++// ── Tests ─────────────────────────────────────────────────────────────────────++describe("IngestSettingsSection", () => {+ // ── Baseline ──────────────────────────────────────────────────────────────++ describe("initial load", () => {+ it("populates chunk size and overlap from server", async () => {+ // Use server values that differ from the component defaults (1024 / 50)+ // so this test fails if server→form synchronization stops working.+ renderSection([], { chunk_size: 768, chunk_overlap: 128 });++ expect(+ await screen.findByRole("spinbutton", { name: /chunk size/i }),+ ).toHaveValue(768);+ expect(+ screen.getByRole("spinbutton", { name: /chunk overlap/i }),+ ).toHaveValue(128);+ });+ });++ // ── Group 1: Validation error display ─────────────────────────────────────++ describe("validation error display", () => {+ it("shows no error on load with valid settings", async () => {+ renderSection();++ // Wait for the form to fully render after auth + settings load.+ await screen.findByRole("spinbutton", { name: /chunk size/i });+ expect(screen.queryByRole("alert")).not.toBeInTheDocument();+ });++ it("shows 'Chunk size must be at least 1' when chunk size is set to 0", async () => {+ renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ fireEvent.change(input, { target: { value: "0" } });++ expect(await screen.findByRole("alert")).toHaveTextContent(+ "Chunk size must be at least 1",+ );+ });++ it("shows 'Chunk overlap must be less than chunk size' when overlap equals chunk size", async () => {+ renderSection();++ await screen.findByRole("spinbutton", { name: /chunk size/i });+ const overlapInput = screen.getByRole("spinbutton", {+ name: /chunk overlap/i,+ });+ fireEvent.change(overlapInput, { target: { value: "1024" } });++ expect(await screen.findByRole("alert")).toHaveTextContent(+ "Chunk overlap must be less than chunk size",+ );+ });++ it("clears the error when the user corrects invalid values", async () => {+ renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });++ // Introduce error.+ fireEvent.change(input, { target: { value: "0" } });+ expect(await screen.findByRole("alert")).toBeInTheDocument();++ // Fix it.+ fireEvent.change(input, { target: { value: "512" } });+ await waitFor(() => {+ expect(screen.queryByRole("alert")).not.toBeInTheDocument();+ });+ });+ });++ // ── Group 2: Save button disabled state ───────────────────────────────────++ describe("save button disabled state", () => {+ it("is disabled when chunk size is 0", async () => {+ renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ fireEvent.change(input, { target: { value: "0" } });++ expect(+ screen.getByRole("button", { name: /save ingest settings/i }),+ ).toBeDisabled();+ });++ it("is disabled when overlap equals chunk size", async () => {+ renderSection();++ await screen.findByRole("spinbutton", { name: /chunk size/i });+ const overlapInput = screen.getByRole("spinbutton", {+ name: /chunk overlap/i,+ });+ fireEvent.change(overlapInput, { target: { value: "1024" } });++ expect(+ screen.getByRole("button", { name: /save ingest settings/i }),+ ).toBeDisabled();+ });++ it("is enabled when settings are valid and dirty (user changed a value)", async () => {+ renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ fireEvent.change(input, { target: { value: "512" } });++ await waitFor(() => {+ expect(+ screen.getByRole("button", { name: /save ingest settings/i }),+ ).toBeEnabled();+ });+ });++ it("is disabled when form is clean (server values match state)", async () => {+ renderSection();++ // Wait for settings to load — state now matches server (1024 / 50).+ await screen.findByRole("spinbutton", { name: /chunk size/i });++ expect(+ screen.getByRole("button", { name: /save ingest settings/i }),+ ).toBeDisabled();+ });+ });++ // ── Group 3: Save handler blocked ─────────────────────────────────────────++ describe("save handler blocked", () => {+ it("does not POST /api/settings when chunk size is 0 (button is disabled)", async () => {+ let postCalled = false;+ server.use(+ http.post("/api/settings", () => {+ postCalled = true;+ return HttpResponse.json({+ message: "ok",+ settings: makeSettings({ show_vlm_settings: false }),+ });+ }),+ );++ renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ fireEvent.change(input, { target: { value: "0" } });++ const saveButton = screen.getByRole("button", {+ name: /save ingest settings/i,+ });+ expect(saveButton).toBeDisabled();+ expect(postCalled).toBe(false);+ });+ });++ // ── Group 4: userEdited ref prevents background sync overwrite ─────────────++ describe("userEdited ref / background sync", () => {+ it("background refetch does NOT overwrite user-entered chunk size", async () => {+ const { queryClient } = renderSection();++ // Wait for initial load.+ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ expect(input).toHaveValue(1024);++ // User edits the field → userEdited = true.+ fireEvent.change(input, { target: { value: "512" } });+ expect(input).toHaveValue(512);++ // Simulate a background refetch that returns a DIFFERENT valid server+ // value (999). Returning the same 1024 would let TanStack Query preserve+ // the settings.knowledge reference via structural sharing, so the guarded+ // sync effect might never run and the assertion could pass trivially.+ let refetchCompleted = false;+ server.use(+ http.get("/api/settings", () => {+ refetchCompleted = true;+ return HttpResponse.json(+ makeSettings({+ knowledge: { chunk_size: 999, chunk_overlap: 50 },+ show_vlm_settings: false,+ }),+ );+ }),+ );++ await act(async () => {+ await queryClient.invalidateQueries({ queryKey: ["settings"] });+ });++ // The refetch really happened and returned new data...+ expect(refetchCompleted).toBe(true);+ // ...yet the user's edit must be preserved (not overwritten by 999): the+ // sync effect should have been short-circuited by+ // userEditedRef.current === true.+ expect(+ screen.getByRole("spinbutton", { name: /chunk size/i }),+ ).toHaveValue(512);+ });++ it("resumes background sync after the user reverts an edit back to the saved value", async () => {+ // Regression test for the sticky-userEdited bug: editing a value and then+ // changing it back leaves the form clean, so a later server change must+ // be adopted rather than skipped (which would show stale values and let+ // Save submit them).+ const { queryClient } = renderSection();++ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ expect(input).toHaveValue(1024);++ // Edit, then revert back to the saved value — form is clean again.+ fireEvent.change(input, { target: { value: "512" } });+ expect(input).toHaveValue(512);+ fireEvent.change(input, { target: { value: "1024" } });+ expect(input).toHaveValue(1024);++ // The server value genuinely changes underneath the (clean) form.+ let refetchCompleted = false;+ server.use(+ http.get("/api/settings", () => {+ refetchCompleted = true;+ return HttpResponse.json(+ makeSettings({+ knowledge: { chunk_size: 2048, chunk_overlap: 50 },+ show_vlm_settings: false,+ }),+ );+ }),+ );++ await act(async () => {+ await queryClient.invalidateQueries({ queryKey: ["settings"] });+ });++ expect(refetchCompleted).toBe(true);+ // Because the form was clean, the resync must adopt the new server value+ // (2048) instead of leaving the stale 1024.+ await waitFor(() => {+ expect(+ screen.getByRole("spinbutton", { name: /chunk size/i }),+ ).toHaveValue(2048);+ });+ });++ it("background sync resumes after a successful save", async () => {+ renderSection();++ // Wait for initial load.+ const input = await screen.findByRole("spinbutton", {+ name: /chunk size/i,+ });+ expect(input).toHaveValue(1024);++ // User edits.+ fireEvent.change(input, { target: { value: "512" } });++ // Override handlers: POST succeeds, then GET returns a different server+ // value (999) to prove sync has resumed after the save.+ server.use(+ http.post("/api/settings", () =>+ HttpResponse.json({+ message: "ok",+ settings: makeSettings({+ knowledge: { chunk_size: 512, chunk_overlap: 50 },+ show_vlm_settings: false,+ }),+ }),+ ),+ http.get("/api/settings", () =>+ HttpResponse.json(+ makeSettings({+ knowledge: { chunk_size: 999, chunk_overlap: 50 },+ show_vlm_settings: false,+ }),+ ),+ ),+ );++ // Trigger the save.+ fireEvent.click(+ screen.getByRole("button", { name: /save ingest settings/i }),+ );++ // After the POST succeeds, userEdited resets to false. The mutation's+ // own invalidateQueries then fires another GET, which returns 999. The+ // sync effect (no longer blocked) must update the input.+ await waitFor(() => {+ expect(+ screen.getByRole("spinbutton", { name: /chunk size/i }),+ ).toHaveValue(999);+ });+ });+ });+});diff --git a/frontend/app/settings/_components/ingest-settings-section.tsx b/frontend/app/settings/_components/ingest-settings-section.tsxindex 0a4e80ec5..84799571c 100644--- a/frontend/app/settings/_components/ingest-settings-section.tsx+++ b/frontend/app/settings/_components/ingest-settings-section.tsx@@ -9,6 +9,7 @@ import {useGetOllamaModelsQuery,} from "@/app/api/queries/useGetModelsQuery";import { useGetSettingsQuery } from "@/app/api/queries/useGetSettingsQuery";+import { getChunkSettingsError } from "@/components/cloud-picker/types";import { ConfirmationDialog } from "@/components/confirmation-dialog";import { LabelWrapper } from "@/components/label-wrapper";import {@@ -80,9 +81,10 @@ export function IngestSettingsSection() {const [chunkSize, setChunkSize] = useState<number>(1024);const [chunkOverlap, setChunkOverlap] = useState<number>(50);- const [chunkValidationError, setChunkValidationError] = useState<- string | null- >(null);+ const chunkValidationError = getChunkSettingsError({+ chunkSize,+ chunkOverlap,+ });const [tableStructure, setTableStructure] = useState<boolean>(true);const [ocr, setOcr] = useState<boolean>(false);const [pictureDescriptions, setPictureDescriptions] =@@ -321,7 +323,19 @@ export function IngestSettingsSection() {handleEmbeddingModelChange,]);+ const userEditedRef = useRef(userEdited);+ userEditedRef.current = userEdited;+useEffect(() => {+ // Skip resync while the user has an unsaved edit in progress — otherwise+ // a background refetch of settings.knowledge silently overwrites what+ // they're typing before they've had a chance to save it. Read via a ref+ // (rather than depending on userEdited directly) so this effect doesn't+ // re-fire against stale, pre-refetch data the instant a save flips+ // userEdited back to false. userEdited is cleared as soon as the form+ // matches the server again (see the effect below useRegisterDirty), so a+ // value the user edited and then reverted no longer blocks this resync.+ if (userEditedRef.current) return;const k = settings.knowledge;if (!k) return;if (k.chunk_size !== undefined) setChunkSize(k.chunk_size);@@ -434,6 +448,18 @@ export function IngestSettingsSection() {useRegisterDirty("ingest-settings", userEdited && knowledgeIngestDirty);+ // Keep `userEdited` honest. It is set on every edit but, left alone, would+ // stay sticky until the next successful save. If the user edits a value and+ // then reverts it back to what the server has, the form is clean again — but+ // a sticky flag would (a) permanently skip the resync effect above, so a+ // genuine later server change is never picked up (stale form), and (b) let+ // the Save button re-enable and submit that stale value. Clearing the flag+ // the moment the form matches the server gates the resync on an *actual*+ // unsaved difference rather than a one-way "has ever edited" flag.+ useEffect(() => {+ if (userEdited && !knowledgeIngestDirty) setUserEdited(false);+ }, [userEdited, knowledgeIngestDirty]);+// Resolve through the same map that builds the groups: the catalogue now// contributes custom LiteLLM providers, so a hard-coded chain would report// OpenAI's state for any provider outside the four legacy keys.@@ -451,13 +477,11 @@ export function IngestSettingsSection() {const handleChunkSizeChange = (value: string) => {setUserEdited(true);setChunkSize(Math.max(0, Number.parseInt(value, 10) || 0));- setChunkValidationError(null);};const handleChunkOverlapChange = (value: string) => {setUserEdited(true);setChunkOverlap(Math.max(0, Number.parseInt(value, 10) || 0));- setChunkValidationError(null);};const handleKnowledgeIngestSave = () => {@@ -493,16 +517,10 @@ export function IngestSettingsSection() {},});- if (chunkSize < 1) {- const msg = "Chunk size must be at least 1";- setChunkValidationError(msg);- toast.error("Could not save ingest settings", { description: msg });- return;- }- if (chunkOverlap >= chunkSize) {- const msg = "Chunk overlap must be less than chunk size";- setChunkValidationError(msg);- toast.error("Could not save ingest settings", { description: msg });+ if (chunkValidationError) {+ toast.error("Could not save ingest settings", {+ description: chunkValidationError,+ });return;}@@ -534,7 +552,6 @@ export function IngestSettingsSection() {},{onSuccess: () => {- setChunkValidationError(null);setValidationError(null);setUserEdited(false);},@@ -589,7 +606,6 @@ export function IngestSettingsSection() {setOcr(DEFAULT_KNOWLEDGE_SETTINGS.ocr);setPictureDescriptions(DEFAULT_KNOWLEDGE_SETTINGS.picture_descriptions);setDisableIngestWithLangflow(false);- setChunkValidationError(null);setUserEdited(false);toast.success("Default ingest flow settings restored successfully");closeDialog();@@ -1093,7 +1109,8 @@ export function IngestSettingsSection() {disabled={updateSettingsMutation.isPending ||!knowledgeIngestDirty ||- vlmModelPending+ vlmModelPending ||+ !!chunkValidationError}className="min-w-[120px]"size="sm"diff --git a/frontend/components/cloud-picker/types.test.ts b/frontend/components/cloud-picker/types.test.tsindex 4d8312071..8bc049d07 100644--- a/frontend/components/cloud-picker/types.test.ts+++ b/frontend/components/cloud-picker/types.test.ts@@ -1,6 +1,6 @@import assert from "node:assert/strict";-import { describe, it } from "vitest";-import { getIngestChunkSettingsError } from "./types";+import { describe, expect, it } from "vitest";+import { getChunkSettingsError, getIngestChunkSettingsError } from "./types";const validSettings = {embeddingModel: "prod-embed",@@ -32,3 +32,57 @@ describe("getIngestChunkSettingsError", () => {assert.equal(getIngestChunkSettingsError(validSettings), null);});});++describe("getChunkSettingsError", () => {+ it("returns null for valid settings", () => {+ expect(+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 50 }),+ ).toBeNull();+ });++ it("returns null when overlap is 0", () => {+ expect(+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 0 }),+ ).toBeNull();+ });++ it("returns null when overlap is exactly chunkSize - 1 (boundary)", () => {+ expect(+ getChunkSettingsError({ chunkSize: 1024, chunkOverlap: 1023 }),+ ).toBeNull();+ });++ it("returns chunk size error when chunkSize is 0", () => {+ expect(getChunkSettingsError({ chunkSize: 0, chunkOverlap: 0 })).toBe(+ "Chunk size must be at least 1",+ );+ });++ it("returns chunk size error when chunkSize is negative", () => {+ expect(getChunkSettingsError({ chunkSize: -5, chunkOverlap: 0 })).toBe(+ "Chunk size must be at least 1",+ );+ });++ it("returns overlap error when chunkOverlap equals chunkSize", () => {+ expect(getChunkSettingsError({ chunkSize: 100, chunkOverlap: 100 })).toBe(+ "Chunk overlap must be less than chunk size",+ );+ });++ it("returns overlap error when chunkOverlap exceeds chunkSize", () => {+ expect(getChunkSettingsError({ chunkSize: 100, chunkOverlap: 200 })).toBe(+ "Chunk overlap must be less than chunk size",+ );+ });++ it("chunk size error takes priority when both would fire (size=0, overlap=999)", () => {+ expect(getChunkSettingsError({ chunkSize: 0, chunkOverlap: 999 })).toBe(+ "Chunk size must be at least 1",+ );+ });++ it("returns null for minimum valid config (chunkSize: 1, chunkOverlap: 0)", () => {+ expect(getChunkSettingsError({ chunkSize: 1, chunkOverlap: 0 })).toBeNull();+ });+});diff --git a/frontend/components/cloud-picker/types.ts b/frontend/components/cloud-picker/types.tsindex f93c63faa..1ff837083 100644--- a/frontend/components/cloud-picker/types.ts+++ b/frontend/components/cloud-picker/types.ts@@ -127,6 +127,13 @@ export function getIngestChunkSettingsError(if (!settings.embeddingModel.trim()) {return "Select an embedding model in Settings before ingesting files";}+ return getChunkSettingsError(settings);+}++/** Inline error message if chunk settings are invalid; otherwise null. */+export function getChunkSettingsError(+ settings: Pick<IngestSettings, "chunkSize" | "chunkOverlap">,+): string | null {if (settings.chunkSize < 1) {return "Chunk size must be at least 1";}