Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix([issue-11665]): require POST for model weight downloads (#11689)

[._.]/831e4a9096cc
diff --git a/client/src/components/media/VideoUpscaleDrawer.jsx b/client/src/components/media/VideoUpscaleDrawer.jsx
index c50e12d12e..70bd529f9d 100644
--- a/client/src/components/media/VideoUpscaleDrawer.jsx
+++ b/client/src/components/media/VideoUpscaleDrawer.jsx
@@ -30,17 +30,19 @@ export default function VideoUpscaleDrawer({ item, onClose, onUpscaled }) {
const [planLoading, setPlanLoading] = useState(false);
const [planError, setPlanError] = useState(null);
const [submitting, setSubmitting] = useState(false);
- const [downloading, setDownloading] = useState(false);
+ const [downloadItemId, setDownloadItemId] = useState(null);
+ const downloading = open && downloadItemId === itemId;
+ const planRequestRef = useRef(0);
// Fresh state per open (and per item, in case a second card is picked
// before the drawer fully unmounts) so a stale method/plan never carries
// over onto a different clip.
useEffect(() => {
- if (!open) return;
+ ++planRequestRef.current;
setMethod('lanczos');
setPlan(null);
setPlanError(null);
- setDownloading(false);
+ setDownloadItemId(null);
}, [open, itemId]);
// The generative plan drives the radio's disabled state AND its disclosure
@@ -96,12 +98,10 @@ export default function VideoUpscaleDrawer({ item, onClose, onUpscaled }) {
// separate models page, since no such page manages this non-remix weight.
const adapterKey = plan?.adapter?.key || null;
const downloadUrl = downloading ? upscaleAdapterDownloadUrl(adapterKey) : null;
- const dl = useSseProgress(downloadUrl, { enabled: !!downloadUrl });
+ const dl = useSseProgress(downloadUrl, { enabled: !!downloadUrl, method: 'POST' });
- // Supersession token for the post-download plan re-probe below.
- const planRequestRef = useRef(0);
useEffect(() => {
- if (!downloading || !dl.latest) return;
+ if (!downloading || !dl.closed || !dl.latest) return;
// A request-generation ref, not a `let active` flag: `downloading` is in this
// effect's own dependency array, so the write below re-runs the effect
// immediately and a lifetime-scoped flag would be flipped by its own
@@ -110,14 +110,14 @@ export default function VideoUpscaleDrawer({ item, onClose, onUpscaled }) {
// newer one supersedes it.
if (dl.latest.type === 'complete') {
const req = ++planRequestRef.current;
- setDownloading(false);
+ setDownloadItemId(null);
// Re-probe so `adapter.cached` flips and the option re-enables.
getUpscalePlan(itemId, 'ltx').then((res) => { if (req === planRequestRef.current) setPlan(res?.plan || null); }).catch(() => {});
} else if (dl.latest.type === 'error') {
- setDownloading(false);
+ setDownloadItemId(null);
toast.error(dl.latest.message || 'Adapter download failed');
}
- }, [dl.latest, downloading, itemId]);
+ }, [dl.closed, dl.latest, downloading, itemId]);
const handleSubmit = useCallback(async () => {
if (!itemId || submitting) return;
@@ -209,7 +209,7 @@ export default function VideoUpscaleDrawer({ item, onClose, onUpscaled }) {
) : (
<button
type="button"
- onClick={() => setDownloading(true)}
+ onClick={() => setDownloadItemId(itemId)}
className="text-port-accent hover:text-white underline"
>
Download adapter{plan.adapter?.sizeBytes ? ` (${formatBytes(plan.adapter.sizeBytes)})` : ''}
diff --git a/client/src/components/media/VideoUpscaleDrawer.test.jsx b/client/src/components/media/VideoUpscaleDrawer.test.jsx
index 0ade186480..dd7003b56a 100644
--- a/client/src/components/media/VideoUpscaleDrawer.test.jsx
+++ b/client/src/components/media/VideoUpscaleDrawer.test.jsx
@@ -1,7 +1,7 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
import VideoUpscaleDrawer from './VideoUpscaleDrawer';
-import { upscaleVideo, getUpscalePlan } from '../../services/apiImageVideo';
+import { upscaleVideo, getUpscalePlan, upscaleAdapterDownloadUrl } from '../../services/apiImageVideo';
vi.mock('../../services/apiImageVideo', () => ({
upscaleVideo: vi.fn(),
@@ -70,7 +70,56 @@ beforeEach(() => {
upscaleVideo.mockResolvedValue({ ok: true, video: { id: 'video-2', upscaledFrom: 'video-1' } });
});
+afterEach(() => vi.unstubAllGlobals());
+
describe('VideoUpscaleDrawer', () => {
+ it('downloads the adapter through POST and allows an explicit retry after a dropped stream', async () => {
+ getUpscalePlan.mockResolvedValue({ plan: missingAdapterPlan() });
+ upscaleAdapterDownloadUrl.mockReturnValue('/api/video-gen/ic-loras/pixel-upscale/download');
+ const fetchMock = vi.fn(async () => new Response(new ReadableStream({ start(controller) { controller.close(); } })));
+ vi.stubGlobal('fetch', fetchMock);
+ render(<VideoUpscaleDrawer item={ITEM} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ fireEvent.click(await screen.findByText(/^Download adapter/));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+ await screen.findByText(/^Download adapter/);
+ expect(fetchMock.mock.calls[0][1].method).toBe('POST');
+ fireEvent.click(screen.getByText(/^Download adapter/));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ await screen.findByText(/^Download adapter/);
+ });
+ it('closing the mounted drawer aborts its download and does not restart for another item', async () => {
+ getUpscalePlan.mockResolvedValue({ plan: missingAdapterPlan() });
+ upscaleAdapterDownloadUrl.mockReturnValue('/api/video-gen/ic-loras/pixel-upscale/download');
+ const fetchMock = vi.fn(async () => new Response(new ReadableStream({ start() {} })));
+ vi.stubGlobal('fetch', fetchMock);
+ const view = render(<VideoUpscaleDrawer item={ITEM} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ fireEvent.click(await screen.findByText(/^Download adapter/));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+ view.rerender(<VideoUpscaleDrawer item={null} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ expect(fetchMock.mock.calls[0][1].signal.aborted).toBe(true);
+ view.rerender(<VideoUpscaleDrawer item={{ id: 'video-other' }} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ await screen.findByText(/^Download adapter/);
+ expect(fetchMock).toHaveBeenCalledOnce();
+ });
+
+ it('ignores an old download completion plan response after the item changes', async () => {
+ let finishOldPlan;
+ getUpscalePlan.mockResolvedValueOnce({ plan: missingAdapterPlan() })
+ .mockImplementationOnce(() => new Promise(resolve => { finishOldPlan = resolve; }))
+ .mockResolvedValueOnce({ plan: READY_PLAN });
+ upscaleAdapterDownloadUrl.mockReturnValue('/api/video-gen/ic-loras/pixel-upscale/download');
+ vi.stubGlobal('fetch', vi.fn(async () => new Response('data: {"type":"complete"}\n\n')));
+ const view = render(<VideoUpscaleDrawer item={ITEM} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ fireEvent.click(await screen.findByText(/^Download adapter/));
+ await waitFor(() => expect(getUpscalePlan).toHaveBeenCalledTimes(2));
+ view.rerender(<VideoUpscaleDrawer item={{ id: 'video-other' }} onClose={vi.fn()} onUpscaled={vi.fn()} />);
+ const radio = screen.getByRole('radio', { name: /LTX-2.5 generative/ });
+ await waitFor(() => expect(radio).not.toBeDisabled());
+ await act(async () => finishOldPlan({ plan: missingAdapterPlan() }));
+ expect(radio).not.toBeDisabled();
+ expect(screen.queryByText(/^Download adapter/)).toBeNull();
+ });
+
it('opening the drawer fetches the plan but queues no mutation', async () => {
render(<VideoUpscaleDrawer item={ITEM} onClose={vi.fn()} onUpscaled={vi.fn()} />);
diff --git a/client/src/hooks/README.md b/client/src/hooks/README.md
index 431c3b324c..841c4d6895 100644
--- a/client/src/hooks/README.md
+++ b/client/src/hooks/README.md
@@ -42,10 +42,10 @@ grep -i "what you want to do" client/src/hooks/README.md
|---|---|---|
| `useGoogleAutoConfigProgress` | Request-correlated Google OAuth setup progress with HTTP settlement and listener cleanup. | Calendar and Messages automated setup. |
| `useQuotaUpdates` | Reconcile quota cards on scrape completion, reconnect and tab show; the caller owns the entry read. | Usage, Subscriptions and Quota Burn quota cards. |
-| `useSseProgress` | Generic JSON-frame EventSource subscriber. | New SSE progress stream — start here, build on top. |
+| `useSseProgress` | Generic JSON-frame SSE subscriber: EventSource for GET, one abortable fetch stream for `method: 'POST'` without retry. | New SSE progress stream — start here, build on top. |
| `useSseJobSlot` | Generic single-slot SSE job: captured target from preparation through completion, terminal-frame handling (`complete`/`error`/`canceled`), and `sse.closed`-without-terminal-frame recovery in one place. Returns `{ active, pending, jobId, percent, stage, context, start, attach, cancel }` (`attach(jobId, context)` adopts a job another request already started into the idle slot); reserves synchronously, exposes context during kickoff and ignores unmounted responses. Optional `readPercent` adapts other progress scales; `connected` distinguishes a live stream from reconnecting, and `onSettled(reason, context)` refreshes persisted state after completion, failure, cancellation or a terminal disconnect. Pass `startRequest`/`eventsUrl`/`cancelRequest` + per-feature toast copy. | Any "kick off a job → stream SSE → settle on terminal frame" hook. The reference-audio/YouTube/video-download/MIDI/music-video-render hooks all wrap this — don't re-roll the terminal-frame + lost-connection dance. |
| `useInstallStream` | BYO-runtime install-log stream lifecycle: `stage`/`log`/`complete`/`error` frame dispatch, capped + optionally-debounced log accumulation, "connection lost" handling, ref-stashed `onComplete`, auto-scroll. `method: 'GET'` uses EventSource; `method: 'POST'` reads one fetch stream for a non-idempotent install. | A streamed install/setup modal that shows live SSE log lines (FLUX.2, video runtimes, OpenCode). Don't re-roll the teardown/onComplete-ref dance. |
-| `useModelDownloadStatus` | Image/video model cache-status + SSE pre-download. `useDownloadableAssets(descriptors, options)` shares readiness and independent integrity dismissals across asset roles. `start(id)` commands a pull; `startWhenIdle(id)` requests one — it waits for the cache verdict, skips an already-resident repo, and queues behind whatever owns the single EventSource lane (`queuedModelId` while it waits, falsy id to retract). | Surfacing "Available" vs "Download" badge inline in the gen form; `startWhenIdle` for a picker where choosing an option IS the request for its weights. |
+| `useModelDownloadStatus` | Image/video model cache-status + SSE pre-download. `useDownloadableAssets(descriptors, options)` shares readiness and independent integrity dismissals across asset roles. `start(id)` commands a pull; `startWhenIdle(id)` requests one — it waits for the cache verdict, skips an already-resident repo, and queues behind whatever owns the single download lane (`queuedModelId` while it waits, falsy id to retract). | Surfacing "Available" vs "Download" badge inline in the gen form; `startWhenIdle` for a picker where choosing an option IS the request for its weights. |
| `useModelInputPreview` | `useModelInputPreview(fetchPreview, body, { enabled })` — the server's preview of what a render would send to its model (#11317), refreshed 500 ms after the form stops changing; superseded responses dropped, a refusal returned as `error`. | Showing the exact prompt and its additions beside a render form before Generate. |
| `useAgyModels` | Live `agy models` probe (the AGENT models `--model` accepts) with `models`/`error`/`loading`/`refresh`; opt-in via an `enabled` flag so it never spawns for a disabled backend. | Any Agy model picker — the Settings default or the per-render override. Don't hardcode a model list: agy exits non-zero on an id outside this catalog. |
| `useSpritePendingRenders` | Sprite render map reconciled on scoped queue events, entry, reconnect and tab show; submitting sentinel, terminal-before-response recovery and 404-only release. | Queue-backed sprite reference/walk renders; persisted assets reconcile separately on `sprites:changed`. |
diff --git a/client/src/hooks/useModelDownloadStatus.js b/client/src/hooks/useModelDownloadStatus.js
index 0a9461fd95..9af6a86beb 100644
--- a/client/src/hooks/useModelDownloadStatus.js
+++ b/client/src/hooks/useModelDownloadStatus.js
@@ -64,7 +64,7 @@ export const buildDownloadUrl = (kind, modelId, force = false) => {
// "Download (~8 GB)" badge next to the image/video gen model picker.
//
// `kind` selects the endpoint family ('image' | 'video'). `start(modelId)`
-// opens an EventSource against the download endpoint. When the stream
+// opens a POST stream against the download endpoint. When the stream
// emits a terminal frame we automatically refetch /models/status so the
// badge flips to "Available" without the caller wiring that up.
//
@@ -114,10 +114,10 @@ export function useModelDownloadStatus({ kind = 'image' } = {}) {
useEffect(() => { fetchStatuses(); }, [fetchStatuses]);
- // EventSource for the active download. `null` URL = idle (useSseProgress's
+ // POST stream for the active download. `null` URL = idle (useSseProgress's
// `enabled: false` cleanup tears the connection down on cancel).
const downloadUrl = buildDownloadUrl(kind, activeModelId, forceDownload);
- const sse = useSseProgress(downloadUrl, { enabled: !!downloadUrl });
+ const sse = useSseProgress(downloadUrl, { enabled: !!downloadUrl, method: 'POST' });
// Refetch on natural stream close. useSseProgress flips `closed:true` once
// per subscription and resets to false when the URL changes; that single
@@ -256,7 +256,7 @@ export function useModelDownloadStatus({ kind = 'image' } = {}) {
// Download click. Lives here rather than in the caller because both things it
// has to wait on are this hook's: the cache verdict (`statuses` may still be
// loading, and starting on an unknown verdict would re-pull a resident
- // multi-GB repo) and the single EventSource lane (`start` would otherwise
+ // multi-GB repo) and the single download lane (`start` would otherwise
// hijack a download already in flight).
//
// Passing a falsy id clears a queued intent, so a caller whose selection moved
diff --git a/client/src/hooks/useModelDownloadStatus.stream.test.jsx b/client/src/hooks/useModelDownloadStatus.stream.test.jsx
new file mode 100644
index 0000000000..007e3e24fe
--- /dev/null
+++ b/client/src/hooks/useModelDownloadStatus.stream.test.jsx
@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { useModelDownloadStatus } from './useModelDownloadStatus';
+
+vi.mock('../services/apiImageVideo.js', () => ({
+ getImageModelStatuses: vi.fn(async () => [{ id: 'example', cached: false }]),
+ getVideoModelStatuses: vi.fn(async () => ({ models: [{ id: 'example', cached: false }] })),
+ verifyImageModels: vi.fn(), verifyVideoModels: vi.fn(),
+ repairImageModel: vi.fn(), repairVideoModel: vi.fn(),
+ repairTextEncoder: vi.fn(), repairTextEncoderOption: vi.fn(), repairIcLora: vi.fn(),
+}));
+vi.mock('../components/ui/Toast', () => ({ default: { error: vi.fn() } }));
+afterEach(() => vi.unstubAllGlobals());
+
+describe('model picker download transport', () => {
+ it.each(['image', 'video'])('%s picker uses one POST, surfaces disconnect, and permits explicit retry', async (kind) => {
+ let stream;
+ const fetchMock = vi.fn(async () => new Response(new ReadableStream({ start(controller) { stream = controller; } })));
+ vi.stubGlobal('fetch', fetchMock);
+ const { result } = renderHook(() => useModelDownloadStatus({ kind }));
+ await waitFor(() => expect(result.current.statuses).toHaveLength(1));
+ act(() => result.current.start('example', { force: true }));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledOnce());
+ expect(fetchMock.mock.calls[0]).toEqual([
+ `/api/${kind}-gen/models/example/download?force=1`, expect.objectContaining({ method: 'POST' }),
+ ]);
+ act(() => stream.enqueue(new TextEncoder().encode('data: {"type":"progress","downloaded":10}\n\n')));
+ await waitFor(() => expect(result.current.progress).toMatchObject({ type: 'progress', downloaded: 10 }));
+ act(() => stream.error(new Error('Network lost')));
+ await waitFor(() => expect(result.current.downloading).toBe(false));
+ expect(result.current.lastError).toMatchObject({ modelId: 'example', message: 'Network lost' });
+ expect(fetchMock).toHaveBeenCalledOnce();
+ act(() => result.current.start('example'));
+ await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2));
+ await act(async () => result.current.cancel());
+ expect(fetchMock.mock.calls[1][1].signal.aborted).toBe(true);
+ });
+});
diff --git a/client/src/hooks/useSseProgress.js b/client/src/hooks/useSseProgress.js
index d78e9033f4..d2ad25b80f 100644
--- a/client/src/hooks/useSseProgress.js
+++ b/client/src/hooks/useSseProgress.js
@@ -1,4 +1,5 @@
import { useEffect, useRef, useState } from 'react';
+import { maybeRedirectToLogin } from '../services/apiCore';
// Both cancel spellings are terminal. Every emitter normalizes on `canceled`
// (single l); `cancelled` stays tolerated defensively so a stream from an
@@ -13,7 +14,8 @@ const TERMINAL_TYPES = new Set(['complete', 'canceled', 'cancelled', 'error', 'p
export const isTerminalSseFrame = (frame) => TERMINAL_TYPES.has(frame?.type);
/**
- * Subscribe to a server-side EventSource stream of JSON-payload progress
+ * GET uses EventSource reconnects; POST reads one fetch stream without retry.
+ * Subscribe to a server-side SSE stream of JSON-payload progress
* frames. Used by both the per-issue auto-runner and the per-volume
* beat-sheet runner — any new SSE-job hook should wrap this rather than
* re-implement the lifecycle.
@@ -22,7 +24,7 @@ export const isTerminalSseFrame = (frame) => TERMINAL_TYPES.has(frame?.type);
* flips false, or when a terminal frame (type === 'complete' / 'canceled'
* / 'error') arrives.
*/
-export function useSseProgress(url, { enabled = true } = {}) {
+export function useSseProgress(url, { enabled = true, method = 'GET' } = {}) {
const [frames, setFrames] = useState([]);
const [latest, setLatest] = useState(null);
const [latestUrl, setLatestUrl] = useState(null);
@@ -52,6 +54,74 @@ export function useSseProgress(url, { enabled = true } = {}) {
setIsOpen(false);
setClosed(false);
+ // A mutation stream gets exactly one request. Defer setup one tick so
+ // React StrictMode's setup/cleanup probe cannot start the mutation twice.
+ if (method === 'POST') {
+ const controller = new AbortController();
+ const connection = { close: () => controller.abort() };
+ esRef.current = connection;
+ const isCurrent = () => esRef.current === connection && !controller.signal.aborted;
+ const receive = (data) => {
+ if (!isCurrent()) return;
+ setFrames(previous => [...previous, data]);
+ setLatest(data);
+ setLatestUrl(url);
+ if (isTerminalSseFrame(data)) {
+ setIsOpen(false);
+ setClosed(true);
+ connection.close();
+ }
+ };
+ const run = async () => {
+ let reader;
+ try {
+ const response = await fetch(url, { method: 'POST', signal: controller.signal });
+ if (!isCurrent()) return;
+ if (!response.ok || !response.body?.getReader) {
+ const error = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+ maybeRedirectToLogin(response, error);
+ throw new Error(error.error || `HTTP ${response.status}`);
+ }
+ setIsOpen(true);
+ reader = response.body.getReader();
+ const decoder = new TextDecoder();
+ let buffer = '';
+ const consume = (frame) => {
+ const json = frame.split(/\r?\n/).filter(line => line.startsWith('data:'))
+ .map(line => line.slice(5).trimStart()).join('\n');
+ if (!json) return;
+ let data;
+ try { data = JSON.parse(json); } catch { return; }
+ receive(data);
+ };
+ while (isCurrent()) {
+ const { done, value } = await reader.read();
+ if (!isCurrent()) break;
+ if (done) {
+ buffer += decoder.decode();
+ if (buffer.trim()) consume(buffer);
+ break;
+ }
+ buffer += decoder.decode(value, { stream: true });
+ const frames = buffer.split(/\r?\n\r?\n/);
+ buffer = frames.pop() || '';
+ for (const frame of frames) consume(frame);
+ }
+ if (isCurrent()) receive({ type: 'error', message: 'Download connection lost. Try again.', kind: 'connection_lost' });
+ } catch (error) {
+ if (isCurrent()) receive({ type: 'error', message: error.message || 'Download connection lost. Try again.', kind: 'connection_lost' });
+ } finally {
+ if (reader) await reader.cancel().catch(() => {});
+ }
+ };
+ const startTimer = setTimeout(run, 0);
+ return () => {
+ clearTimeout(startTimer);
+ connection.close();
+ if (esRef.current === connection) esRef.current = null;
+ };
+ }
+
const es = new EventSource(url);
esRef.current = es;
@@ -87,7 +157,7 @@ export function useSseProgress(url, { enabled = true } = {}) {
es.close();
esRef.current = null;
};
- }, [url, enabled]);
+ }, [url, enabled, method]);
return { frames, latest, latestUrl, isOpen, closed, close: () => esRef.current?.close() };
}
diff --git a/client/src/hooks/useSseProgress.test.jsx b/client/src/hooks/useSseProgress.test.jsx
index d83e084c21..70ab1d9a85 100644
--- a/client/src/hooks/useSseProgress.test.jsx
+++ b/client/src/hooks/useSseProgress.test.jsx
@@ -1,5 +1,6 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { renderHook, act } from '@testing-library/react';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { StrictMode } from 'react';
+import { renderHook, act, waitFor } from '@testing-library/react';
import { useSseProgress, isTerminalSseFrame } from './useSseProgress';
import { MockEventSource, lastEventSource as last } from '../test/mockEventSource';
@@ -10,6 +11,7 @@ beforeEach(() => {
afterEach(() => {
delete global.EventSource;
+ vi.unstubAllGlobals();
});
describe('useSseProgress', () => {
@@ -99,3 +101,62 @@ it('reports a transient outage and recovers without ending the job stream', () =
act(() => last().onopen());
expect(result.current.isOpen).toBe(true);
});
+
+describe('POST progress streams', () => {
+ it('starts once in StrictMode, decodes split frames and closes at completion', async () => {
+ const encoder = new TextEncoder();
+ const bytes = encoder.encode('data: {"type":"stage","message":"pulling"}\r\n\r\ndata: {"type":"progress","message":"café"}\n\ndata: {"type":"complete"}\n\n');
+ const split = bytes.indexOf(0xc3) + 1;
+ const fetchMock = vi.fn(async () => new Response(new ReadableStream({ start(controller) {
+ controller.enqueue(bytes.slice(0, split));
+ controller.enqueue(bytes.slice(split));
+ controller.close();
+ } })));
+ vi.stubGlobal('fetch', fetchMock);
+ const { result } = renderHook(() => useSseProgress('/download', { method: 'POST' }), { wrapper: StrictMode });
+ await waitFor(() => expect(result.current.closed).toBe(true));
+ expect(result.current.frames).toEqual([
+ { type: 'stage', message: 'pulling' }, { type: 'progress', message: 'café' }, { type: 'complete' },
+ ]);
+ expect(result.current.latestUrl).toBe('/download');
+ expect(result.current.isOpen).toBe(false);
+ expect(fetchMock).toHaveBeenCalledOnce();
+ expect(fetchMock.mock.calls[0]).toEqual(['/download', expect.objectContaining({ method: 'POST' })]);
+ expect(MockEventSource.instances).toHaveLength(0);
+ });
+
+ it.each(['disconnect', 'eof', 'http'])('ends a %s failure visibly without retrying', async (failure) => {
+ const fetchMock = vi.fn(async () => failure === 'http'
+ ? new Response(JSON.stringify({ error: 'Unknown model' }), { status: 404 })
+ : new Response(new ReadableStream({ start(controller) {
+ if (failure === 'disconnect') controller.error(new Error('Network lost'));
+ else controller.close();
+ } })));
+ vi.stubGlobal('fetch', fetchMock);
+ const { result, rerender } = renderHook(() => useSseProgress('/download', { method: 'POST' }));
+ await waitFor(() => expect(result.current.closed).toBe(true));
+ expect(result.current.latest).toMatchObject({ type: 'error', message: expect.any(String) });
+ if (failure === 'http') expect(result.current.latest.message).toBe('Unknown model');
+ rerender();
+ expect(fetchMock).toHaveBeenCalledOnce();
+ expect(MockEventSource.instances).toHaveLength(0);
+ });
+
+ it('aborts on cancel, supersession and unmount, ignoring a stale response', async () => {
+ const requests = [];
+ vi.stubGlobal('fetch', vi.fn((url, { signal }) => new Promise(resolve => requests.push({ url, signal, resolve }))));
+ const { result, rerender, unmount } = renderHook(({ url }) => useSseProgress(url, { method: 'POST' }), { initialProps: { url: '/a' } });
+ await waitFor(() => expect(requests).toHaveLength(1));
+ rerender({ url: '/b' });
+ await waitFor(() => expect(requests).toHaveLength(2));
+ expect(requests[0].signal.aborted).toBe(true);
+ await act(async () => requests[0].resolve(new Response('data: {"type":"complete"}\n\n')));
+ expect(result.current.latest).toBeNull();
+ act(() => result.current.close());
+ expect(requests[1].signal.aborted).toBe(true);
+ rerender({ url: '/c' });
+ await waitFor(() => expect(requests).toHaveLength(3));
+ unmount();
+ expect(requests[2].signal.aborted).toBe(true);
+ });
+});
diff --git a/server/lib/validation.js b/server/lib/validation.js
index 4e53b17bc1..baffdaa305 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -2859,3 +2859,11 @@ export const providerFallbackEntrySchema = z.object({
export const providerFallbackChainBodySchema = z.object({
entries: z.array(providerFallbackEntrySchema).max(50),
});
+
+// Model-cache reads and explicit download streams share the same URL contract.
+export const modelDownloadQuerySchema = z.object({
+ force: z.enum(['0', '1']).optional().transform(value => value === '1'),
+});
+export const modelDownloadParamsSchema = z.object({ modelId: z.string().min(1).max(256) });
+export const icLoraDownloadParamsSchema = z.object({ mode: z.string().min(1).max(256) });
+export const textEncoderDownloadParamsSchema = z.object({ id: z.string().min(1).max(256) });
diff --git a/server/routeValidationConventions.test.js b/server/routeValidationConventions.test.js
index f521db2389..50743f410f 100644
--- a/server/routeValidationConventions.test.js
+++ b/server/routeValidationConventions.test.js
@@ -249,7 +249,6 @@ const UNVALIDATED_QUERY_BASELINE = [
'routes/harnesses.js POST /action',
'routes/harnesses.js POST /models/refresh',
'routes/identity.js GET /goals/:id/calendar-events',
- 'routes/imageGen.js GET /models/:modelId/download',
'routes/imageGen.js GET /regen/availability',
'routes/imageGen.js GET /status',
'routes/imageGenSetup.js POST /install',
@@ -317,10 +316,6 @@ const UNVALIDATED_QUERY_BASELINE = [
'routes/uploads.js DELETE /',
'routes/usage.js GET /claude-code',
'routes/videoDownload.js GET /downloads',
- 'routes/videoGen.js GET /ic-loras/:mode/download',
- 'routes/videoGen.js GET /models/:modelId/download',
- 'routes/videoGen.js GET /text-encoder/download',
- 'routes/videoGen.js GET /text-encoders/:id/download',
'routes/videoGen.js POST /setup/runtime-install',
'routes/videoTimeline.js GET /projects',
'routes/voice.js GET /voices',
diff --git a/server/routes/apiDocs.test.js b/server/routes/apiDocs.test.js
index f851c81826..9d83cafe70 100644
--- a/server/routes/apiDocs.test.js
+++ b/server/routes/apiDocs.test.js
@@ -61,6 +61,19 @@ describe('GET /api/api-docs/openapi.json', () => {
expect(res.body.externallyExposableApis.map((entry) => entry.id)).toEqual(['voice', 'sdapi']);
});
+ it('documents weight downloads as POST mutations alongside read-only GET status', async () => {
+ const res = await request(buildApp()).get('/api/api-docs/catalog.json');
+ for (const path of [
+ '/api/image-gen/models/:modelId/download', '/api/video-gen/models/:modelId/download',
+ '/api/video-gen/ic-loras/:mode/download', '/api/video-gen/text-encoders/:id/download',
+ '/api/video-gen/text-encoder/download',
+ ]) {
+ const operations = res.body.operations.filter(operation => operation.path === path);
+ expect(operations.find(operation => operation.method === 'GET')).toMatchObject({ sideEffect: 'read' });
+ expect(operations.find(operation => operation.method === 'POST')).toMatchObject({ sideEffect: 'write' });
+ }
+ });
+
it('serves the generated Socket.IO catalog and AsyncAPI 3 document', async () => {
const events = await request(buildApp()).get('/api/api-docs/events.json');
expect(events.status).toBe(200);
diff --git a/server/routes/imageGen.integrity.test.js b/server/routes/imageGen.integrity.test.js
index 0b8353d6a1..95bddf5886 100644
--- a/server/routes/imageGen.integrity.test.js
+++ b/server/routes/imageGen.integrity.test.js
@@ -1,6 +1,6 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
-import { request } from '../lib/testHelper.js';
+import { request, startLoopbackServer, closeLoopbackServer } from '../lib/testHelper.js';
import { errorMiddleware } from '../lib/errorHandler.js';
// Integrity / repair routes (issue #1324). Mocks mediaModels + hfCache so the
@@ -61,6 +61,14 @@ vi.mock('../lib/pythonSetup.js', async (importOriginal) => ({
resolveFlux2Python: vi.fn(() => null),
}));
+vi.mock('../services/hfDownloadStream.js', async (importOriginal) => {
+ const actual = await importOriginal();
+ return { ...actual, startHfDownloadStream: vi.fn(actual.startHfDownloadStream) };
+});
+vi.mock('../services/hfDownload.js', () => ({ downloadHfRepo: vi.fn() }));
+vi.mock('../services/modelManifest.js', () => ({ recordModelInstall: vi.fn(async () => null) }));
+import { startHfDownloadStream } from '../services/hfDownloadStream.js';
+import { downloadHfRepo } from '../services/hfDownload.js';
import imageGenRoutes from './imageGen.js';
import { verifyModelCache, repairModelCache } from '../lib/hfCache.js';
@@ -74,6 +82,65 @@ describe('Image Gen integrity routes', () => {
vi.clearAllMocks();
});
+ it('GET download is a read-only cache entry even with force=1', async () => {
+ const collection = await request(app).get('/api/image-gen/models/status');
+ const response = await request(app).get('/api/image-gen/models/flux2/download?force=1');
+ expect(response.status).toBe(200);
+ expect(response.headers['content-type']).toMatch(/application\/json/);
+ expect(response.body).toEqual(collection.body[0]);
+ expect(startHfDownloadStream).not.toHaveBeenCalled();
+ expect(downloadHfRepo).not.toHaveBeenCalled();
+ });
+
+ it('POST streams progress and completion, and returns JSON errors before opening SSE', async () => {
+ downloadHfRepo.mockImplementation(({ onEvent }) => {
+ onEvent({ type: 'stage', stage: 'download' });
+ onEvent({ type: 'progress', downloaded: 10, total: 10 });
+ return { promise: Promise.resolve({ ok: true, sizeBytes: 10 }), kill: vi.fn() };
+ });
+ const response = await request(app).post('/api/image-gen/models/flux2/download?force=1').send({});
+ expect(response.headers['content-type']).toMatch(/text\/event-stream/);
+ const frames = response.text.trim().split('\n\n').map(line => JSON.parse(line.slice(6)));
+ expect(frames.map(frame => frame.type)).toEqual(['stage', 'progress', 'complete']);
+ for (const [path, status] of [['flux2/download?force=yes', 400], ['flux2/download?force=1&force=0', 400], ['unknown/download', 404]]) {
+ const failure = await request(app).post(`/api/image-gen/models/${path}`);
+ expect(failure.status).toBe(status);
+ expect(failure.headers['content-type']).toMatch(/application\/json/);
+ expect(failure.body).toMatchObject({ error: expect.any(String), code: expect.any(String), timestamp: expect.any(Number) });
+ }
+ expect(downloadHfRepo).toHaveBeenCalledTimes(1);
+ });
+
+ it('POST download errors keep their SSE frame and a disconnect kills the active child', async () => {
+ downloadHfRepo.mockImplementationOnce(() => ({
+ promise: Promise.resolve({ ok: false, errorKind: 'gated_repo', errorMessage: 'Accept the license' }), kill: vi.fn(),
+ }));
+ const failed = await request(app).post('/api/image-gen/models/flux2/download?force=1');
+ expect(failed.text).toContain('"type":"error"');
+ expect(failed.text).toContain('gated_repo');
+ let finish;
+ const kill = vi.fn(() => finish({ ok: false, errorKind: 'cancelled' }));
+ downloadHfRepo.mockImplementationOnce(({ onEvent }) => {
+ onEvent({ type: 'stage', stage: 'download' });
+ return { promise: new Promise(resolve => { finish = resolve; }), kill };
+ });
+ const server = await startLoopbackServer(app);
+ const controller = new AbortController();
+ try {
+ const response = await fetch(`http://127.0.0.1:${server.address().port}/api/image-gen/models/flux2/download?force=1`, {
+ method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}', signal: controller.signal,
+ });
+ expect(response.status).toBe(200);
+ expect(kill).not.toHaveBeenCalled();
+ controller.abort();
+ await vi.waitFor(() => expect(kill).toHaveBeenCalledOnce());
+ } finally {
+ controller.abort();
+ finish?.({ ok: false, errorKind: 'cancelled' });
+ await closeLoopbackServer(server);
+ }
+ });
+
it('GET /models/status surfaces an integrity block for cached models', async () => {
const res = await request(app).get('/api/image-gen/models/status');
expect(res.status).toBe(200);
diff --git a/server/routes/imageGen.js b/server/routes/imageGen.js
index 18fe0a54e6..fc84951705 100644
--- a/server/routes/imageGen.js
+++ b/server/routes/imageGen.js
@@ -14,7 +14,7 @@ import { Router } from 'express';
import { z } from 'zod';
import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.js';
import {
- validateRequest, imageCancelBodySchema, imageVisibilityBodySchema, imageEdgeSchema, refineImagePixelCap, PIXEL_CAP_MESSAGE,
+ validateRequest, modelDownloadQuerySchema, modelDownloadParamsSchema, imageCancelBodySchema, imageVisibilityBodySchema, imageEdgeSchema, refineImagePixelCap, PIXEL_CAP_MESSAGE,
} from '../lib/validation.js';
import { optionalUploadFields, optionalUpload } from '../lib/multipart.js';
import * as imageGen from '../services/imageGen/index.js';
@@ -785,25 +785,26 @@ router.get('/models', (_req, res) => {
// entries with `runner: 'mflux'` and a non-default name) report
// `cached: null` so the UI can render "unknown" rather than a misleading
// "not downloaded" state. Lazy generation still works regardless of badge.
+const imageModelCacheStatus = async (m) => {
+ const required = requiredReposForModel(m);
+ if (!required) return { id: m.id, repo: null, cached: null, sizeBytes: 0 };
+ // Inspect every required repo (main + any aux text encoders). The badge
+ // is `cached: true` only when ALL are cached; sizeBytes is the sum. The
+ // `pendingRepos` field lets the UI explain WHICH repos still need a pull
+ // so the user isn't surprised when clicking "Download" triggers >1 fetch.
+ const inspections = await Promise.all(required.map((r) => inspectModelCache(r)));
+ const cached = inspections.every((i) => i.cached);
+ const sizeBytes = inspections.reduce((sum, i) => sum + (i.sizeBytes || 0), 0);
+ const pendingRepos = required.filter((_, i) => !inspections[i].cached);
+ // Integrity is only meaningful for repos that finished downloading — run
+ // the cheap structural check across every cached required repo and report
+ // the worst result, so a corrupt aux encoder still surfaces a Repair state.
+ const integrity = cached ? aggregateVerifies(await Promise.all(required.map((r) => verifyModelCache(r)))) : null;
+ return { id: m.id, repo: required[0], cached, sizeBytes, requiredRepos: required, pendingRepos, integrity };
+};
+
router.get('/models/status', asyncHandler(async (_req, res) => {
- const statuses = await Promise.all(getImageModels().map(async (m) => {
- const required = requiredReposForModel(m);
- if (!required) return { id: m.id, repo: null, cached: null, sizeBytes: 0 };
- // Inspect every required repo (main + any aux text encoders). The badge
- // is `cached: true` only when ALL are cached; sizeBytes is the sum. The
- // `pendingRepos` field lets the UI explain WHICH repos still need a pull
- // so the user isn't surprised when clicking "Download" triggers >1 fetch.
- const inspections = await Promise.all(required.map((r) => inspectModelCache(r)));
- const cached = inspections.every((i) => i.cached);
- const sizeBytes = inspections.reduce((sum, i) => sum + (i.sizeBytes || 0), 0);
- const pendingRepos = required.filter((_, i) => !inspections[i].cached);
- // Integrity is only meaningful for repos that finished downloading — run
- // the cheap structural check across every cached required repo and report
- // the worst result, so a corrupt aux encoder still surfaces a Repair state.
- const integrity = cached ? aggregateVerifies(await Promise.all(required.map((r) => verifyModelCache(r)))) : null;
- return { id: m.id, repo: required[0], cached, sizeBytes, requiredRepos: required, pendingRepos, integrity };
- }));
- res.json(statuses);
+ res.json(await Promise.all(getImageModels().map(imageModelCacheStatus)));
}));
// POST /models/verify — on-demand integrity re-scan. `deep:true` adds the
@@ -852,11 +853,21 @@ router.post('/models/:modelId/repair', asyncHandler(async (req, res) => {
// disconnects mid-download; cross-route in-flight dedupe lives in
// startHfDownloadStream so a FLUX repo shared with video gen can't spawn
// two concurrent children.
+const downloadableImageModel = (req) => {
+ const { modelId } = validateRequest(modelDownloadParamsSchema, req.params);
+ const model = getImageModels().find((m) => m.id === modelId);
+ if (!model) throw new ServerError(`Unknown model id: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
+ return model;
+};
+
router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
- const model = getImageModels().find((m) => m.id === req.params.modelId);
- if (!model) {
- throw new ServerError(`Unknown model id: ${req.params.modelId}`, { status: 404 });
- }
+ validateRequest(modelDownloadQuerySchema, req.query);
+ res.json(await imageModelCacheStatus(downloadableImageModel(req)));
+}));
+
+router.post('/models/:modelId/download', asyncHandler(async (req, res) => {
+ const { force } = validateRequest(modelDownloadQuerySchema, req.query);
+ const model = downloadableImageModel(req);
const repos = requiredReposForModel(model);
if (!repos) {
throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file — cannot pre-download.`, {
@@ -868,7 +879,7 @@ router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
// HiDream). The SSE stream tags each event with `repo` so the client can
// show per-repo progress / log lines. `?force=1` (repair-initiated) re-fetches
// even when the repo still looks cached, so a deleted shard isn't skipped.
- await startHfDownloadStream({ req, res, repos, force: req.query.force === '1' });
+ await startHfDownloadStream({ req, res, repos, force });
}));
router.get('/loras', asyncHandler(async (_req, res) => {
diff --git a/server/routes/videoGen.integrity.test.js b/server/routes/videoGen.integrity.test.js
index cfa258620e..489f1c56f4 100644
--- a/server/routes/videoGen.integrity.test.js
+++ b/server/routes/videoGen.integrity.test.js
@@ -131,6 +131,55 @@ describe('Video Gen integrity routes', () => {
});
});
+ it('keeps all four GET download paths read-only and equal to their collection status', async () => {
+ const collection = (await request(app).get('/api/video-gen/models/status')).body;
+ const cases = [
+ ['models/ltx2_unified', collection.models[0]],
+ ['text-encoder', collection.textEncoder],
+ [`text-encoders/${collection.textEncoderOptions[0].id}`, collection.textEncoderOptions[0]],
+ [`ic-loras/${collection.icLoras[0].id}`, collection.icLoras[0]],
+ ];
+ for (const [path, entry] of cases) {
+ const response = await request(app).get(`/api/video-gen/${path}/download?force=1`);
+ expect(response.status).toBe(200);
+ expect(response.headers['content-type']).toMatch(/application\/json/);
+ expect(response.body).toEqual(entry);
+ const invalid = await request(app).post(`/api/video-gen/${path}/download?force=true`);
+ expect(invalid.status).toBe(400);
+ expect(invalid.headers['content-type']).toMatch(/application\/json/);
+ expect(invalid.body).toMatchObject({ code: 'VALIDATION_ERROR', error: expect.any(String), timestamp: expect.any(Number) });
+ }
+ expect(sseDownload.start).not.toHaveBeenCalled();
+ });
+
+ it('rejects unknown POST targets with JSON before opening a stream', async () => {
+ for (const path of ['models/unknown', 'text-encoders/unknown', 'ic-loras/unknown']) {
+ const response = await request(app).post(`/api/video-gen/${path}/download`);
+ expect(response.status).toBe(404);
+ expect(response.headers['content-type']).toMatch(/application\/json/);
+ expect(response.body).toMatchObject({ error: expect.any(String), code: expect.any(String), timestamp: expect.any(Number) });
+ }
+ expect(sseDownload.start).not.toHaveBeenCalled();
+ });
+
+ it('POST downloads the shared encoder while local-path GET status stays available', async () => {
+ const response = await request(app).post('/api/video-gen/text-encoder/download?force=1');
+ expect(response.status).toBe(200);
+ expect(response.headers['content-type']).toMatch(/text\/event-stream/);
+ expect(response.text).toContain('"type":"complete"');
+ expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({ repo: 'org/text-encoder', force: true }));
+ sseDownload.start.mockClear();
+ vi.mocked(isHfRepoId).mockReturnValueOnce(false);
+ const status = await request(app).get('/api/video-gen/text-encoder/download');
+ expect(status.body).toMatchObject({ cached: true, integrity: null });
+ vi.mocked(isHfRepoId).mockReturnValueOnce(false);
+ const failure = await request(app).post('/api/video-gen/text-encoder/download');
+ expect(failure.status).toBe(400);
+ expect(failure.body.code).toBe('NOT_DOWNLOADABLE');
+ expect(failure.headers['content-type']).toMatch(/application\/json/);
+ expect(sseDownload.start).not.toHaveBeenCalled();
+ });
+
it('GET /models/status surfaces integrity for cached models + text encoder', async () => {
const res = await request(app).get('/api/video-gen/models/status');
expect(res.status).toBe(200);
@@ -179,7 +228,7 @@ describe('Video Gen integrity routes', () => {
});
it('downloads the pinned base snapshot plus both exact Lightning files', async () => {
- const res = await request(app).get('/api/video-gen/models/wan_lightning/download');
+ const res = await request(app).post('/api/video-gen/models/wan_lightning/download');
expect(res.status).toBe(200);
expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({
repos: [
@@ -259,8 +308,8 @@ describe('Video Gen integrity routes', () => {
);
});
- it('GET /text-encoders/:id/download pulls only the pinned file at its pinned revision', async () => {
- const res = await request(app).get(`/api/video-gen/text-encoders/${encoder().id}/download`);
+ it('POST /text-encoders/:id/download pulls only the pinned file at its pinned revision', async () => {
+ const res = await request(app).post(`/api/video-gen/text-encoders/${encoder().id}/download`);
expect(res.status).toBe(200);
expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({
repos: [{ repo: encoder().repo, revision: encoder().revision, only: encoder().files }],
@@ -268,8 +317,8 @@ describe('Video Gen integrity routes', () => {
}));
});
- it('GET /text-encoders/:id/download threads force=1 for a repair re-fetch', async () => {
- const res = await request(app).get(`/api/video-gen/text-encoders/${encoder().id}/download?force=1`);
+ it('POST /text-encoders/:id/download threads force=1 for a repair re-fetch', async () => {
+ const res = await request(app).post(`/api/video-gen/text-encoders/${encoder().id}/download?force=1`);
expect(res.status).toBe(200);
expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({ force: true }));
});
@@ -286,7 +335,7 @@ describe('Video Gen integrity routes', () => {
it.each(['download', 'repair'])('404s an unknown encoder id on /%s', async (action) => {
const res = action === 'download'
- ? await request(app).get('/api/video-gen/text-encoders/nope/download')
+ ? await request(app).post('/api/video-gen/text-encoders/nope/download')
: await request(app).post('/api/video-gen/text-encoders/nope/repair').send({});
expect(res.status).toBe(404);
expect(res.body.code).toBe('VIDEO_TEXT_ENCODER_UNKNOWN');
@@ -296,7 +345,7 @@ describe('Video Gen integrity routes', () => {
// so it must never reach this lane — otherwise the UI could offer a Download
// button for something that isn't separately downloadable.
it('404s the built-in stock option', async () => {
- const res = await request(app).get('/api/video-gen/text-encoders/stock/download');
+ const res = await request(app).post('/api/video-gen/text-encoders/stock/download');
expect(res.status).toBe(404);
});
diff --git a/server/routes/videoGen.js b/server/routes/videoGen.js
index dda07b593a..13f30eedfd 100644
--- a/server/routes/videoGen.js
+++ b/server/routes/videoGen.js
@@ -15,7 +15,8 @@ import { asyncHandler, ServerError, failValidation } from '../lib/errorHandler.j
import { createVideoHistoryItemRead, historyRecordIdSchema } from './videoHistoryRead.js';
import { uploadFields, optionalUpload } from '../lib/multipart.js';
import {
- validateRequest, videoCancelBodySchema, videoModelTermsSchema,
+ validateRequest, modelDownloadQuerySchema, modelDownloadParamsSchema,
+ icLoraDownloadParamsSchema, textEncoderDownloadParamsSchema, videoCancelBodySchema, videoModelTermsSchema,
} from '../lib/validation.js';
import { grokVideoDurationSchema } from '../lib/sharedSchemas.js';
import {
@@ -695,81 +696,87 @@ router.get('/model-context', asyncHandler(async (_req, res) => {
res.json(await videoModelContext());
}));
+const sharedTextEncoderCacheStatus = async () => {
+ const repo = getTextEncoderRepo();
+ if (!isHfRepoId(repo)) return { repo, cached: true, sizeBytes: 0, integrity: null };
+ return { repo, ...await repoCacheStatus(repo) };
+};
+
+const textEncoderCacheStatus = async (entry, target = textEncoderDownloadTarget(entry)) => {
+ // Through the shared target verifier, so the badge, the integrity scan
+ // and the repair route can't drift on how a pinned single-file target is
+ // checked.
+ const verify = await verifyDownloadTarget(target);
+ const cached = verify.status === 'ok';
+ return {
+ ...publicTextEncoderOption(entry),
+ estimatedBytes: entry.sizeBytes,
+ cached,
+ sizeBytes: verify.sizeBytes || 0,
+ // Same rule as repoCacheStatus: a not-yet-downloaded file gets the
+ // Download badge, not a Repair banner.
+ integrity: cached ? summarizeVerify(verify) : null,
+ };
+};
+
+const icLoraCacheStatus = async (spec) => {
+ // A spec that must be located by its exact file can't use the repo-wide
+ // verdict. Two reasons, both fatal to it: a mirrored spec (Ingredients)
+ // has a 708 GB aggregate mirror that reports `cached` off any unrelated
+ // weight, and a revision-pinned spec would accept a DIFFERENT commit's
+ // snapshot. Probe the ONE file across the candidates instead, and skip the
+ // integrity walk (which would stat/hash every sibling weight in a mirror).
+ if (icLoraProbesExactFile(spec)) {
+ const found = await findCachedIcLoraWeight(spec);
+ return {
+ id: icLoraWeightKey(spec), repo: spec.repo, label: spec.label,
+ baseModel: spec.baseModel, revision: spec.revision || null,
+ requiresPreDownload: !!spec.requiresPreDownload,
+ estimatedBytes: spec.sizeBytes,
+ gated: !!spec.gated, mirrorRepo: spec.mirrorRepo || null,
+ cached: !!found,
+ resolvedRepo: found?.repo || null,
+ // The badge falls back to `estimatedBytes` when sizeBytes is 0, and the
+ // real number would cost a stat on a path we already proved resident —
+ // so report 0 and let the estimate speak.
+ sizeBytes: 0,
+ integrity: null,
+ };
+ }
+ return {
+ id: icLoraWeightKey(spec), repo: spec.repo, label: spec.label,
+ baseModel: spec.baseModel, revision: spec.revision || null,
+ requiresPreDownload: !!spec.requiresPreDownload,
+ estimatedBytes: spec.sizeBytes,
+ gated: !!spec.gated,
+ ...await repoCacheStatus(spec.repo),
+ };
+};
+
router.get('/models/status', asyncHandler(async (_req, res) => {
// Text encoder is shared across all video renders. A registry entry with
// `localPath` (e.g. an LM Studio install) trumps the HF cache check, so
// surface both the repo-cache status and the resolved local path so the UI
// can distinguish "not downloaded" from "served from LM Studio".
- const encoderRepo = getTextEncoderRepo();
const verifyCache = new Map();
const [models, textEncoder, textEncoderOptions, icLoras] = await Promise.all([
Promise.all(listVideoModels().map(async (m) => {
return { id: m.id, ...await modelCacheStatus(m, verifyCache) };
})),
- (async () => {
- if (!isHfRepoId(encoderRepo)) return { repo: encoderRepo, cached: true, sizeBytes: 0, integrity: null };
- return { repo: encoderRepo, ...await repoCacheStatus(encoderRepo) };
- })(),
+ sharedTextEncoderCacheStatus(),
// Substitutable prompt conditioners (lib/videoTextEncoders.js) — the same
// `{ id, repo, cached, sizeBytes, integrity }` badge shape as the models and
// the IC weights, so the video form renders their Download button and
// Repair banner with the existing components. Scoped to the ONE pinned file
// (never the repo) for the reason in textEncoderDownloadTargets.
- Promise.all(textEncoderDownloadTargets().map(async ({ entry, target }) => {
- // Through the shared target verifier, so the badge, the integrity scan
- // and the repair route can't drift on how a pinned single-file target is
- // checked.
- const verify = await verifyDownloadTarget(target);
- const cached = verify.status === 'ok';
- return {
- ...publicTextEncoderOption(entry),
- estimatedBytes: entry.sizeBytes,
- cached,
- sizeBytes: verify.sizeBytes || 0,
- // Same rule as repoCacheStatus: a not-yet-downloaded file gets the
- // Download badge, not a Repair banner.
- integrity: cached ? summarizeVerify(verify) : null,
- };
- })),
+ Promise.all(textEncoderDownloadTargets().map(({ entry, target }) => textEncoderCacheStatus(entry, target))),
// IC-LoRA weights (issue #3100). Each is a separate several-hundred-MB pull,
// so they get the same cached/size/integrity shape as the models — that's
// what lets the mode panel render a Download badge and a Repair banner with
// the existing components. This is the PROVISIONING list, so it spans weights
// that are not remix modes (the LTX-2.5 upscale adapter, #6502) and reports
// each by its `icLoraWeightKey` rather than assuming a `mode` value exists.
- Promise.all(listIcLoraWeights().map(async (spec) => {
- // A spec that must be located by its exact file can't use the repo-wide
- // verdict. Two reasons, both fatal to it: a mirrored spec (Ingredients)
- // has a 708 GB aggregate mirror that reports `cached` off any unrelated
- // weight, and a revision-pinned spec would accept a DIFFERENT commit's
- // snapshot. Probe the ONE file across the candidates instead, and skip the
- // integrity walk (which would stat/hash every sibling weight in a mirror).
- if (icLoraProbesExactFile(spec)) {
- const found = await findCachedIcLoraWeight(spec);
- return {
- id: icLoraWeightKey(spec), repo: spec.repo, label: spec.label,
- baseModel: spec.baseModel, revision: spec.revision || null,
- requiresPreDownload: !!spec.requiresPreDownload,
- estimatedBytes: spec.sizeBytes,
- gated: !!spec.gated, mirrorRepo: spec.mirrorRepo || null,
- cached: !!found,
- resolvedRepo: found?.repo || null,
- // The badge falls back to `estimatedBytes` when sizeBytes is 0, and the
- // real number would cost a stat on a path we already proved resident —
- // so report 0 and let the estimate speak.
- sizeBytes: 0,
- integrity: null,
- };
- }
- return {
- id: icLoraWeightKey(spec), repo: spec.repo, label: spec.label,
- baseModel: spec.baseModel, revision: spec.revision || null,
- requiresPreDownload: !!spec.requiresPreDownload,
- estimatedBytes: spec.sizeBytes,
- gated: !!spec.gated,
- ...await repoCacheStatus(spec.repo),
- };
- })),
+ Promise.all(listIcLoraWeights().map(icLoraCacheStatus)),
]);
res.json({ models, textEncoder, textEncoderOptions, icLoras });
}));
@@ -815,8 +822,18 @@ router.post('/models/:modelId/repair', asyncHandler(async (req, res) => {
}));
router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
- const model = listVideoModels().find((m) => m.id === req.params.modelId);
- if (!model) throw new ServerError(`Unknown video model: ${req.params.modelId}`, { status: 404 });
+ validateRequest(modelDownloadQuerySchema, req.query);
+ const { modelId } = validateRequest(modelDownloadParamsSchema, req.params);
+ const model = listVideoModels().find((m) => m.id === modelId);
+ if (!model) throw new ServerError(`Unknown video model: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
+ res.json({ id: model.id, ...await modelCacheStatus(model) });
+}));
+
+router.post('/models/:modelId/download', asyncHandler(async (req, res) => {
+ const { force } = validateRequest(modelDownloadQuerySchema, req.query);
+ const { modelId } = validateRequest(modelDownloadParamsSchema, req.params);
+ const model = listVideoModels().find((m) => m.id === modelId);
+ if (!model) throw new ServerError(`Unknown video model: ${modelId}`, { status: 404, code: 'UNKNOWN_MODEL' });
const repos = modelDownloadTargets(model);
if (repos.length === 0) throw new ServerError(`Model "${model.id}" has no HuggingFace repo on file.`, { status: 400, code: 'NO_REPO_FOR_MODEL' });
const runtimeInfo = BYOV_RUNTIME_INFO[model.runtime];
@@ -824,7 +841,7 @@ router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
&& await isByovRuntimeReady(model.runtime)
? runtimeInfo.venvPython
: null;
- await startHfDownloadStream({ req, res, repos, pythonPath, force: req.query.force === '1' });
+ await startHfDownloadStream({ req, res, repos, pythonPath, force });
}));
// IC-LoRA remix weights (issue #3100) get their own download/repair pair for
@@ -846,8 +863,15 @@ router.get('/models/:modelId/download', asyncHandler(async (req, res) => {
// candidate: a gated failure surfaces with its actionable "accept the license"
// message rather than being downgraded on the way to a fallback that isn't there.
router.get('/ic-loras/:mode/download', asyncHandler(async (req, res) => {
- const spec = icLoraSpecFromParam(req.params.mode);
- const force = req.query.force === '1';
+ validateRequest(modelDownloadQuerySchema, req.query);
+ const { mode } = validateRequest(icLoraDownloadParamsSchema, req.params);
+ res.json(await icLoraCacheStatus(icLoraSpecFromParam(mode)));
+}));
+
+router.post('/ic-loras/:mode/download', asyncHandler(async (req, res) => {
+ const { force } = validateRequest(modelDownloadQuerySchema, req.query);
+ const { mode } = validateRequest(icLoraDownloadParamsSchema, req.params);
+ const spec = icLoraSpecFromParam(mode);
if (!icLoraProbesExactFile(spec)) {
await startHfDownloadStream({ req, res, repo: spec.repo, force });
return;
@@ -899,12 +923,20 @@ router.post('/ic-loras/:mode/repair', asyncHandler(async (req, res) => {
// in an upstream checkpoint — so a repo-wide pull would cost ~130 GB for ~48 GB
// of usable weights.
router.get('/text-encoders/:id/download', asyncHandler(async (req, res) => {
- const entry = textEncoderFromParam(req.params.id);
+ validateRequest(modelDownloadQuerySchema, req.query);
+ const { id } = validateRequest(textEncoderDownloadParamsSchema, req.params);
+ res.json(await textEncoderCacheStatus(textEncoderFromParam(id)));
+}));
+
+router.post('/text-encoders/:id/download', asyncHandler(async (req, res) => {
+ const { force } = validateRequest(modelDownloadQuerySchema, req.query);
+ const { id } = validateRequest(textEncoderDownloadParamsSchema, req.params);
+ const entry = textEncoderFromParam(id);
await startHfDownloadStream({
req,
res,
repos: [textEncoderDownloadTarget(entry)],
- force: req.query.force === '1',
+ force,
});
}));
@@ -943,6 +975,12 @@ router.post('/text-encoder/repair', asyncHandler(async (req, res) => {
// Text encoder pre-fetch. The Gemma encoder is a separate ~7-25 GB pull from
// the video model itself, so it gets its own button on the video form.
router.get('/text-encoder/download', asyncHandler(async (req, res) => {
+ validateRequest(modelDownloadQuerySchema, req.query);
+ res.json(await sharedTextEncoderCacheStatus());
+}));
+
+router.post('/text-encoder/download', asyncHandler(async (req, res) => {
+ const { force } = validateRequest(modelDownloadQuerySchema, req.query);
const repo = getTextEncoderRepo();
// Local-path encoders (LM Studio) are not downloadable — they're served
// off disk and the status endpoint already reports cached: true for them.
@@ -952,7 +990,7 @@ router.get('/text-encoder/download', asyncHandler(async (req, res) => {
// `?force=1` (sent by the repair-initiated re-download) re-fetches even when
// the repo still looks cached — a deleted shard from a multi-file encoder
// would otherwise be skipped.
- await startHfDownloadStream({ req, res, repo, force: req.query.force === '1' });
+ await startHfDownloadStream({ req, res, repo, force });
}));
// What Generate would send to the model, built by the render's own code (#11317).
diff --git a/server/routes/videoGen.test.js b/server/routes/videoGen.test.js
index be55f5d4f9..3773f4723a 100644
--- a/server/routes/videoGen.test.js
+++ b/server/routes/videoGen.test.js
@@ -724,7 +724,7 @@ describe('videoGen routes', () => {
});
});
- describe('GET /models/:modelId/download — restricted terms', () => {
+ describe('POST /models/:modelId/download — restricted terms', () => {
const h3CheckpointFiles = ['LICENSE', 'FL2VA/model_index.json', 'FL2VA/video_vae/source/model.safetensors'];
const h3 = {
id: 'minimax_h3_8bit',
@@ -752,7 +752,7 @@ describe('videoGen routes', () => {
it('downloads both exact snapshots without a recorded acknowledgement', async () => {
videoGenService.listVideoModels.mockReturnValueOnce([h3]);
- const accepted = await request(app).get('/api/video-gen/models/minimax_h3_8bit/download');
+ const accepted = await request(app).post('/api/video-gen/models/minimax_h3_8bit/download');
expect(accepted.status).toBe(200);
expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({
repos: [
@@ -781,7 +781,7 @@ describe('videoGen routes', () => {
};
videoGenService.listVideoModels.mockReturnValueOnce([ref2va]);
- const accepted = await request(app).get(`/api/video-gen/models/${ref2va.id}/download`);
+ const accepted = await request(app).post(`/api/video-gen/models/${ref2va.id}/download`);
expect(accepted.status).toBe(200);
expect(sseDownload.start).toHaveBeenCalledWith(expect.objectContaining({
@@ -3522,7 +3522,7 @@ describe('videoGen routes', () => {
const upscaler = IC_LORA_MODES['pixel-upscale'];
it('downloads a pinned weight single-file, at its pinned revision', async () => {
- const res = await request(app).get(`/api/video-gen/ic-loras/${icLoraWeightKey(upscaler)}/download`);
+ const res = await request(app).post(`/api/video-gen/ic-loras/${icLoraWeightKey(upscaler)}/download`);
expect(res.status).toBe(200);
const [{ fallbacks, repo }] = sseDownload.start.mock.calls[0];
// Never a whole-repo snapshot: the pin names one commit and one file, and
@@ -3536,7 +3536,7 @@ describe('videoGen routes', () => {
});
it('keeps an unpinned, un-mirrored weight on the cheap whole-repo path', async () => {
- const res = await request(app).get('/api/video-gen/ic-loras/ic-control/download');
+ const res = await request(app).post('/api/video-gen/ic-loras/ic-control/download');
expect(res.status).toBe(200);
const [args] = sseDownload.start.mock.calls[0];
expect(args.repo).toBe(IC_LORA_MODES.control.repo);
@@ -3544,7 +3544,7 @@ describe('videoGen routes', () => {
});
it('404s an unknown weight key and names the real ones', async () => {
- const res = await request(app).get('/api/video-gen/ic-loras/not-a-weight/download');
+ const res = await request(app).post('/api/video-gen/ic-loras/not-a-weight/download');
expect(res.status).toBe(404);
expect(res.body.error).toMatch(/pixel-upscale/);
expect(res.body.error).toMatch(/ic-control/);
diff --git a/server/services/hfDownloadStream.js b/server/services/hfDownloadStream.js
index 27572dc64c..435c057973 100644
--- a/server/services/hfDownloadStream.js
+++ b/server/services/hfDownloadStream.js
@@ -1,5 +1,5 @@
// SSE driver for HuggingFace repo pre-download endpoints. Image gen and video
-// gen both expose `GET /…/models/:id/download` (and video also a separate
+// gen both expose `POST /…/models/:id/download` (and video also a separate
// `/text-encoder/download`); without this helper each route open-codes the
// same `writeHead → send → cache-check → in-flight check → spawn → cleanup`
// flow. A single in-flight Map keyed by repo also dedupes across routes: