fix: bounded retries for Subsonic connection failures (TASK-170)

jvgomg · claude · jvgomg · commit e1b0fbc679dc · 2026-03-19T21:26:54.000Z
When a Subsonic server is unreachable (DNS failure, connection refused,
timeout), the adapter now retries 3 times with exponential backoff
(1s, 2s, 4s) then throws a SubsonicConnectionError with a clear
message including the URL and Docker-specific diagnostic hints.

Non-connection errors (HTTP 401/403, bad requests) fail immediately
without retrying.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/fix-subsonic-connection-retry.md b/.changeset/fix-subsonic-connection-retry.md
@@ -0,0 +1,5 @@
+---
+"@podkit/core": patch
+---
+
+Fix Subsonic connection failures hanging indefinitely instead of failing with a clear error message
diff --git a/packages/podkit-core/src/adapters/index.ts b/packages/podkit-core/src/adapters/index.ts
@@ -21,6 +21,6 @@ export { DirectoryAdapter, createDirectoryAdapter } from './directory.js';
 export type { DirectoryAdapterConfig, ScanProgress } from './directory.js';
 
 // Subsonic adapter
-export { SubsonicAdapter, createSubsonicAdapter } from './subsonic.js';
+export { SubsonicAdapter, createSubsonicAdapter, SubsonicConnectionError } from './subsonic.js';
 
 export type { SubsonicAdapterConfig } from './subsonic.js';
diff --git a/packages/podkit-core/src/adapters/subsonic.test.ts b/packages/podkit-core/src/adapters/subsonic.test.ts
@@ -4,8 +4,8 @@
  * Tests use manual mocking of the SubsonicAPI to avoid real network calls.
  */
 
-import { describe, it, expect } from 'bun:test';
-import { SubsonicAdapter } from './subsonic.js';
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { SubsonicAdapter, SubsonicConnectionError } from './subsonic.js';
 import type { SubsonicAdapterConfig } from './subsonic.js';
 import type { Child, AlbumWithSongsID3 } from 'subsonic-api';
 import { replayGainToSoundcheck } from '../sync/soundcheck.js';
@@ -522,3 +522,178 @@ describe('SubsonicAdapter artwork presence detection', () => {
     expect(t2.hasArtwork).toBe(false);
   });
 });
+
+// =============================================================================
+// Connection Retry Tests
+// =============================================================================
+
+describe('SubsonicAdapter connection retries', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  /**
+   * Create an adapter with a mocked globalThis.fetch.
+   * The mock must be installed BEFORE creating the adapter because
+   * createRetryFetch captures globalThis.fetch at construction time.
+   */
+  function createAdapterWithMockedFetch(mockFetch: typeof globalThis.fetch) {
+    globalThis.fetch = mockFetch;
+    return new SubsonicAdapter({
+      url: 'https://music.example.com',
+      username: 'testuser',
+      password: 'testpass',
+    });
+  }
+
+  it('retries connection errors up to 3 times then throws SubsonicConnectionError', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      throw new TypeError('fetch failed');
+    });
+
+    const error = await adapter.connect().catch((e) => e);
+    expect(error).toBeInstanceOf(SubsonicConnectionError);
+    expect(fetchCount).toBe(3);
+  });
+
+  it('error message includes the server URL', async () => {
+    const adapter = createAdapterWithMockedFetch(async () => {
+      throw new TypeError('fetch failed');
+    });
+
+    const error = await adapter.connect().catch((e) => e);
+    expect(error.message).toContain('https://music.example.com');
+  });
+
+  it('error message includes retry count and diagnostic hints', async () => {
+    const adapter = createAdapterWithMockedFetch(async () => {
+      throw new TypeError('fetch failed');
+    });
+
+    const error = await adapter.connect().catch((e) => e);
+    expect(error.message).toContain('after 3 attempts');
+    expect(error.message).toContain('Check that the server is running');
+    expect(error.message).toContain('Docker');
+  });
+
+  it('SubsonicConnectionError has url property', async () => {
+    const adapter = createAdapterWithMockedFetch(async () => {
+      throw new TypeError('fetch failed');
+    });
+
+    const error = await adapter.connect().catch((e) => e);
+    expect(error).toBeInstanceOf(SubsonicConnectionError);
+    expect(error.url).toBe('https://music.example.com');
+  });
+
+  it('retries on DNS resolution failure (ENOTFOUND)', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      const err = new Error('getaddrinfo ENOTFOUND music.example.com');
+      throw err;
+    });
+
+    await expect(adapter.connect()).rejects.toBeInstanceOf(SubsonicConnectionError);
+    expect(fetchCount).toBe(3);
+  });
+
+  it('retries on connection refused (ECONNREFUSED)', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      throw new Error('connect ECONNREFUSED 192.168.1.100:4533');
+    });
+
+    await expect(adapter.connect()).rejects.toBeInstanceOf(SubsonicConnectionError);
+    expect(fetchCount).toBe(3);
+  });
+
+  it('retries on timeout (ETIMEDOUT)', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      throw new Error('connect ETIMEDOUT 10.0.0.1:443');
+    });
+
+    await expect(adapter.connect()).rejects.toBeInstanceOf(SubsonicConnectionError);
+    expect(fetchCount).toBe(3);
+  });
+
+  it('succeeds on retry after transient connection failure', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      if (fetchCount < 3) {
+        throw new TypeError('fetch failed');
+      }
+      // Return a successful Subsonic ping response
+      return new Response(
+        JSON.stringify({
+          'subsonic-response': { status: 'ok', version: '1.16.1' },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } }
+      );
+    });
+
+    // Should not throw — succeeds on 3rd attempt
+    await adapter.connect();
+    expect(fetchCount).toBe(3);
+  });
+
+  it('does not retry on non-connection errors', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      // A non-connection error (e.g., thrown by middleware)
+      throw new Error('some other error');
+    });
+
+    // Should fail immediately without retrying
+    // The error wrapping in connect() catches it as a generic connection failure
+    await expect(adapter.connect()).rejects.toThrow(/Failed to connect/);
+    expect(fetchCount).toBe(1);
+  });
+
+  it('does not retry when server returns HTTP 401 (authentication failure)', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      // HTTP 401 is returned as a Response, not thrown — fetch() resolves for HTTP errors.
+      // The subsonic-api library parses the response and may throw its own error,
+      // but the fetch layer itself succeeds. We verify fetch is called only once.
+      return new Response(
+        JSON.stringify({
+          'subsonic-response': {
+            status: 'failed',
+            error: { code: 40, message: 'Wrong username or password' },
+          },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } }
+      );
+    });
+
+    // The adapter wraps the "status: failed" response into an error
+    await expect(adapter.connect()).rejects.toThrow(/Failed to connect/);
+    // fetch was called exactly once — no retries for auth failures
+    expect(fetchCount).toBe(1);
+  });
+
+  it('does not retry when server returns HTTP 403 (forbidden)', async () => {
+    let fetchCount = 0;
+    const adapter = createAdapterWithMockedFetch(async () => {
+      fetchCount++;
+      return new Response('Forbidden', {
+        status: 403,
+        headers: { 'content-type': 'text/plain' },
+      });
+    });
+
+    await expect(adapter.connect()).rejects.toThrow(/Failed to connect/);
+    expect(fetchCount).toBe(1);
+  });
+});
diff --git a/packages/podkit-core/src/adapters/subsonic.ts b/packages/podkit-core/src/adapters/subsonic.ts
@@ -37,6 +37,130 @@ export interface SubsonicAdapterConfig {
  */
 const MIN_ARTWORK_BYTES = 100;
 
+/**
+ * Maximum number of retry attempts for connection-level failures
+ * (DNS resolution, connection refused, timeout).
+ */
+const MAX_RETRIES = 3;
+
+/**
+ * Timeout per request in milliseconds (30 seconds).
+ * Prevents indefinite hangs on unresponsive servers.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * Base delay for exponential backoff between retries (in milliseconds).
+ * Retry 1: 1s, Retry 2: 2s, Retry 3: 4s
+ */
+const RETRY_BASE_DELAY_MS = 1_000;
+
+/**
+ * Check if an error is a connection-level failure that should be retried.
+ *
+ * Connection errors from fetch() are thrown as TypeError (per the Fetch spec).
+ * This includes DNS resolution failures, connection refused, network unreachable,
+ * and AbortError from our timeout signal. HTTP errors (4xx, 5xx) are NOT retried
+ * because they indicate the server received the request — retrying won't help for
+ * auth failures (401/403), bad requests (400), or server errors (500).
+ */
+function isConnectionError(error: unknown): boolean {
+  if (error instanceof TypeError) return true;
+  if (error instanceof DOMException && error.name === 'AbortError') return true;
+  // Node.js fetch may throw non-TypeError for connection issues
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    return (
+      msg.includes('econnrefused') ||
+      msg.includes('enotfound') ||
+      msg.includes('etimedout') ||
+      msg.includes('econnreset') ||
+      msg.includes('enetunreach') ||
+      msg.includes('ehostunreach') ||
+      msg.includes('fetch failed') ||
+      msg.includes('dns') ||
+      msg.includes('abort')
+    );
+  }
+  return false;
+}
+
+/**
+ * Create a fetch wrapper that adds a per-request timeout and retries
+ * on connection-level failures with exponential backoff.
+ *
+ * This prevents the Subsonic adapter from spinning indefinitely when
+ * the server is unreachable (DNS failure, connection refused, timeout).
+ *
+ * @param serverUrl - The server URL, included in error messages for diagnostics
+ * @param timeoutMs - Per-request timeout in milliseconds
+ */
+function createRetryFetch(serverUrl: string, timeoutMs: number = REQUEST_TIMEOUT_MS) {
+  const retryFetch = async (
+    input: string | URL | Request,
+    init?: RequestInit
+  ): Promise<Response> => {
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+        try {
+          const response = await globalThis.fetch(input, {
+            ...init,
+            signal: controller.signal,
+          });
+          clearTimeout(timeoutId);
+          return response;
+        } catch (error) {
+          clearTimeout(timeoutId);
+          throw error;
+        }
+      } catch (error) {
+        lastError = error;
+
+        if (!isConnectionError(error)) {
+          // Not a connection error — don't retry (e.g., HTTP errors thrown by middleware)
+          throw error;
+        }
+
+        if (attempt < MAX_RETRIES) {
+          // Exponential backoff: 1s, 2s, 4s
+          const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+    }
+
+    // All retries exhausted — throw a descriptive error
+    const reason = lastError instanceof Error ? lastError.message : String(lastError);
+    throw new SubsonicConnectionError(serverUrl, reason);
+  };
+  return retryFetch as typeof fetch;
+}
+
+/**
+ * Error thrown when the Subsonic server cannot be reached after all retry attempts.
+ * Includes the server URL and a helpful diagnostic message for Docker/network users.
+ */
+export class SubsonicConnectionError extends Error {
+  readonly url: string;
+
+  constructor(url: string, reason: string) {
+    super(
+      `Failed to connect to Subsonic server at ${url} after ${MAX_RETRIES} attempts. ` +
+        `${reason}. ` +
+        `Check that the server is running and the URL is correct. ` +
+        `If running in Docker, ensure the container can reach the server ` +
+        `(check DNS, network mode, and firewall settings).`
+    );
+    this.name = 'SubsonicConnectionError';
+    this.url = url;
+  }
+}
+
 /**
  * Map file suffix to AudioFileType
  */
@@ -160,6 +284,7 @@ export class SubsonicAdapter implements CollectionAdapter {
         username: config.username,
         password: config.password,
       },
+      fetch: createRetryFetch(config.url),
     });
   }
 
@@ -174,6 +299,10 @@ export class SubsonicAdapter implements CollectionAdapter {
       }
       this.connected = true;
     } catch (error) {
+      // Re-throw SubsonicConnectionError directly (already has a descriptive message)
+      if (error instanceof SubsonicConnectionError) {
+        throw error;
+      }
       const message = error instanceof Error ? error.message : String(error);
       throw new Error(`Failed to connect to Subsonic server at ${this.config.url}: ${message}`);
     }
diff --git a/packages/podkit-core/src/index.ts b/packages/podkit-core/src/index.ts
@@ -27,7 +27,11 @@ export { DirectoryAdapter, createDirectoryAdapter } from './adapters/directory.j
 export type { DirectoryAdapterConfig, ScanProgress, ScanWarning } from './adapters/directory.js';
 
 // Subsonic adapter
-export { SubsonicAdapter, createSubsonicAdapter } from './adapters/subsonic.js';
+export {
+  SubsonicAdapter,
+  createSubsonicAdapter,
+  SubsonicConnectionError,
+} from './adapters/subsonic.js';
 
 export type { SubsonicAdapterConfig } from './adapters/subsonic.js';
 

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@podkit/core": patch
 +---
++
 +Fix Subsonic connection failures hanging indefinitely instead of failing with a clear error message