fix(search): name the proxy when a gateway cuts a search off (#1522)

A reverse proxy whose read timeout is shorter than the release search
budget
(nginx defaults to 60s) answers a slow search with its own 504 page.
describeSearchFailure found no server message there and fell back to
"Unable to reach download source. Network may be restricted or mirrors
blocked.", which sent users off changing mirrors (discussion #1520).

- 504 and Cloudflare's 524 now say the proxy stopped waiting and that
its
  read timeout should be at least the release search timeout.
- A 502/503 with a non-JSON body keeps fetchJSON's "Server unavailable"
  wording instead of the mirrors line.
- docs: the root-path nginx example sets proxy_read_timeout and
  proxy_send_timeout like the subpath ones, and a new troubleshooting
  section covers searches that time out behind a proxy.

docs/reverse-proxy.md

@@ -30,10 +30,14 @@ server {
         proxy_set_header X-Forwarded-Host $http_host;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 86400;
+        proxy_send_timeout 86400;
     }
 }
 ```
 
+Keep the read timeout at least as high as `RELEASE_SEARCH_TIMEOUT` (300 seconds by default). Nginx's own default is 60 seconds, which cuts off any release search that has to solve a protection challenge first. See [Searches that time out behind a proxy](#searches-that-time-out-behind-a-proxy).
+
 ## Subpath setup
 
 Running Shelfmark under a subpath like `/shelfmark` is supported without extra rewrite rules.
@@ -164,6 +168,14 @@ If login, settings saves, or downloads appear to fail in the browser but the act
 
 This is especially relevant for Nginx Proxy Manager or custom advanced config snippets that add websocket headers globally.
 
+## Searches that time out behind a proxy
+
+A release search can legitimately take minutes. When a source's protection cookies expire, the next search has to solve a browser challenge before it can run. Shelfmark gives a search up to `RELEASE_SEARCH_TIMEOUT` seconds (300 by default) and says why when it gives up, but a proxy with a shorter read timeout cuts the request off first. The search then fails with a message about the reverse proxy, or, on older versions, with "Unable to reach download source. Network may be restricted or mirrors blocked." A retry often works because the solve finished on the server after the proxy stopped waiting.
+
+- Set the proxy's read timeout to at least `RELEASE_SEARCH_TIMEOUT`. In Nginx and Nginx Proxy Manager (the **Advanced** tab of the proxy host), add the `proxy_read_timeout` and `proxy_send_timeout` lines from the examples above.
+- Cloudflare's proxy gives up after 100 seconds with a `524` error, and only Enterprise plans can raise that. If searches outlast it, reach Shelfmark without going through Cloudflare's proxy, for example on your LAN or over a VPN.
+- To confirm the proxy is the cause, run the same search against Shelfmark directly at `http://<host>:8084`. If it succeeds there, or fails with a specific reason, the proxy was cutting it off.
+
 ---
 
 ## Health checks

src/frontend/src/tests/searchFailureMessage.test.ts

@@ -4,6 +4,7 @@ import { searchBooks } from '../services/api';
 import {
   describeSearchFailure,
   CLIENT_TIMEOUT_MESSAGE,
+  PROXY_TIMEOUT_MESSAGE,
   UNREACHABLE_SOURCE_MESSAGE,
 } from '../utils/searchFailureMessage';
 
@@ -22,6 +23,14 @@ const jsonResponse = (body: unknown, status: number): Response =>
     headers: { 'Content-Type': 'application/json' },
   });
 
+/** A reverse proxy's own error page: HTML, so there is no JSON for the client to read. */
+const proxyErrorPage = (status: number, statusText: string): Response =>
+  new Response(`<html><body><h1>${status} ${statusText}</h1></body></html>`, {
+    status,
+    statusText,
+    headers: { 'Content-Type': 'text/html' },
+  });
+
 /** Drive a real searchBooks() failure so the error is the one the hook actually sees. */
 const failedSearch = async (respond: () => Promise<Response>): Promise<unknown> => {
   vi.stubGlobal('fetch', vi.fn(respond));
@@ -51,6 +60,30 @@ describe('describeSearchFailure', () => {
     expect(describeSearchFailure(error)).not.toContain('mirrors');
   });
 
+  it("blames the proxy's read timeout when a gateway gave up on the search", async () => {
+    // Discussion #1520: nginx's 60s default cut off every search that needed a
+    // protection solve, and the mirrors line sent the user off changing mirrors.
+    const error = await failedSearch(() =>
+      Promise.resolve(proxyErrorPage(504, 'Gateway Time-out')),
+    );
+
+    expect(describeSearchFailure(error)).toBe(PROXY_TIMEOUT_MESSAGE);
+    expect(describeSearchFailure(error)).not.toContain('mirrors');
+  });
+
+  it("treats Cloudflare's origin timeout as the proxy's too", async () => {
+    const error = await failedSearch(() => Promise.resolve(proxyErrorPage(524, '')));
+
+    expect(describeSearchFailure(error)).toBe(PROXY_TIMEOUT_MESSAGE);
+  });
+
+  it("keeps the gateway's own wording when the proxy could not reach Shelfmark", async () => {
+    const error = await failedSearch(() => Promise.resolve(proxyErrorPage(502, 'Bad Gateway')));
+
+    expect(describeSearchFailure(error)).toContain('Server unavailable (502)');
+    expect(describeSearchFailure(error)).not.toBe(UNREACHABLE_SOURCE_MESSAGE);
+  });
+
   it('falls back to the mirrors line only when nothing explained itself', async () => {
     const error = await failedSearch(() => Promise.resolve(jsonResponse({}, 503)));
 

src/frontend/src/utils/searchFailureMessage.ts

@@ -12,14 +12,29 @@ export const CLIENT_TIMEOUT_MESSAGE =
   'The search took longer than the server said it would. Raise the release search ' +
   'timeout if your setup is simply slow.';
 
+// Shown when a gateway in front of Shelfmark gave up waiting on the search. Shelfmark
+// never sends these statuses itself - a search it cannot finish ends in a 503 that says
+// why - so the proxy's read timeout is shorter than the search budget. See discussion
+// #1520, where nginx's 60s default cut off every search that needed a protection solve.
+export const PROXY_TIMEOUT_MESSAGE =
+  'A reverse proxy in front of Shelfmark stopped waiting before the search finished. ' +
+  "Raise the proxy's read timeout to at least the release search timeout.";
+
+// 504 Gateway Timeout, and Cloudflare's 524 for an origin that answered too slowly.
+const PROXY_TIMEOUT_STATUSES = new Set([504, 524]);
+
+// Statuses fetchJSON already words as the server or its proxy being unavailable.
+const GATEWAY_UNAVAILABLE_STATUSES = new Set([502, 503]);
+
 /**
  * The sentence to show for a failed direct-mode search.
  *
  * The server knows why a search failed - a spent search budget, an unsolved protection
  * challenge - and blanket-replacing that with the mirrors line told users their network
  * was broken when it was not. So: the server's own words when it explained itself, the
- * timeout line when we gave up before it answered, and the mirrors line only when
- * neither applies. See issue #1285.
+ * timeout line when we gave up before it answered, the proxy's part when a gateway
+ * answered instead of Shelfmark, and the mirrors line only when none of those applies.
+ * See issue #1285 and discussion #1520.
  */
 export const describeSearchFailure = (error: unknown): string => {
   if (isTimeoutError(error)) {
@@ -30,6 +45,17 @@ export const describeSearchFailure = (error: unknown): string => {
     return error.serverMessage;
   }
 
+  if (isApiResponseError(error)) {
+    if (PROXY_TIMEOUT_STATUSES.has(error.status)) {
+      return PROXY_TIMEOUT_MESSAGE;
+    }
+    // A 502/503 without a JSON body is a proxy's error page, not Shelfmark's API: the
+    // upstream is down or restarting, which says nothing about mirrors either.
+    if (GATEWAY_UNAVAILABLE_STATUSES.has(error.status) && !error.payload) {
+      return error.message;
+    }
+  }
+
   const message = error instanceof Error ? error.message : '';
   if (message.includes('Network restricted') || message.includes('Unable to reach')) {
     return message;