[#114] Images fallback to other servers if they fail to load

changelog: enhancement

Author: markharding

apps/polycentric/src/common/components/Avatar/ProfileAvatar.tsx

@@ -5,18 +5,17 @@ import {
   pickImageVariant,
   usePolycentric,
 } from '../../lib/polycentric-hooks';
+import { useFallbackUri } from '@/src/common/components/Image';
 import { useProfile } from '@/src/features/profile/hooks/useProfile';
 
 type ProfileAvatarProps = {
   identityKey: string;
 } & Omit<ComponentProps<typeof Avatar>, 'source'>;
 
 /**
- * Avatar bound to a Polycentric identity. Picks the best-fitting
- * variant from the profile's `avatar` ImageSet and serves it from the
- * server's reported blob CDN (see `ServerService.GetInfo`). Falls back
- * to a Dicebear identicon when no avatar is set or the CDN hasn't
- * been resolved yet.
+ * Avatar bound to a Polycentric identity. Picks the best-fitting variant
+ * from the profile's `avatar` ImageSet, trying each server in turn and
+ * falling back to a Dicebear identicon if none serve it.
  */
 export function ProfileAvatar({
   identityKey,
@@ -27,14 +26,23 @@ export function ProfileAvatar({
   const client = usePolycentric();
   const pixelSize = resolveAvatarSize(size);
 
-  const uri = useMemo(() => {
+  const candidates = useMemo(() => {
     const variant = pickImageVariant(profile.avatar, pixelSize);
-    if (variant?.blob?.digest) {
-      const url = client.blobUrl(variant.blob.digest);
-      if (url) return url;
-    }
-    return identiconUrl(identityKey, pixelSize);
+    const blobUris = variant?.blob?.digest
+      ? client.blobUrls(variant.blob.digest)
+      : [];
+    return [...blobUris, identiconUrl(identityKey, pixelSize)];
   }, [profile.avatar, client, identityKey, pixelSize]);
 
-  return <Avatar {...rest} size={size} source={{ uri }} />;
+  const { uri, onError } = useFallbackUri(candidates);
+
+  return (
+    <Avatar
+      {...rest}
+      size={size}
+      source={{ uri }}
+      recyclingKey={candidates[0]}
+      onError={onError}
+    />
+  );
 }

apps/polycentric/src/common/components/Avatar/ProfileEditAvatar.tsx

@@ -14,9 +14,9 @@ type ProfileEditAvatarProps = {
 
 /**
  * Edit-mode counterpart to {@link ProfileAvatar}: seeds the image picker with
- * the identity's current avatar (resolved the same way — best-fitting variant
- * from the profile's `avatar` ImageSet via the blob CDN, falling back to a
- * Dicebear identicon) before the user chooses a replacement.
+ * the identity's current avatar (best-fitting variant from the profile's
+ * `avatar` ImageSet, falling back to a Dicebear identicon) before the user
+ * chooses a replacement.
  */
 export function ProfileEditAvatar({
   identityKey,

apps/polycentric/src/common/components/Image/Image.test.tsx

@@ -0,0 +1,52 @@
+import { act, render } from '@testing-library/react-native';
+import { Image } from './Image';
+
+// expo-image normalizes `source={{ uri }}` into an array of sources, so read
+// the first entry's uri to learn which candidate is currently showing.
+const shownUri = (node: { props: { source?: { uri?: string }[] } }) =>
+  node.props.source?.[0]?.uri;
+
+// Simulate a failed load by invoking the rendered image's onError, the same
+// way expo-image calls it on the native side.
+const fail = (node: { props: { onError?: (e: unknown) => void } }) =>
+  act(() => node.props.onError?.({ nativeEvent: { error: 'boom' } }));
+
+describe('Image', () => {
+  it('shows the first candidate', async () => {
+    const { getByTestId } = await render(
+      <Image testID="img" uris={['a://1', 'b://1']} />,
+    );
+    expect(shownUri(getByTestId('img'))).toBe('a://1');
+  });
+
+  it('falls through to the next candidate when one fails to load', async () => {
+    const { getByTestId } = await render(
+      <Image testID="img" uris={['a://1', 'b://1']} />,
+    );
+
+    await fail(getByTestId('img'));
+    expect(shownUri(getByTestId('img'))).toBe('b://1');
+  });
+
+  it('stops at the last candidate once all have failed', async () => {
+    const { getByTestId } = await render(
+      <Image testID="img" uris={['a://1', 'b://1']} />,
+    );
+
+    await fail(getByTestId('img'));
+    await fail(getByTestId('img'));
+    await fail(getByTestId('img'));
+    expect(shownUri(getByTestId('img'))).toBe('b://1');
+  });
+
+  it('keeps a stable recyclingKey across fallbacks', async () => {
+    const { getByTestId } = await render(
+      <Image testID="img" uris={['a://1', 'b://1']} />,
+    );
+    const before = getByTestId('img').props.recyclingKey;
+
+    await fail(getByTestId('img'));
+    expect(getByTestId('img').props.recyclingKey).toBe(before);
+    expect(before).toBe('a://1');
+  });
+});

apps/polycentric/src/common/components/Image/Image.tsx

@@ -0,0 +1,22 @@
+import { Image as ExpoImage, type ImageProps } from 'expo-image';
+import { useFallbackUri } from './useFallbackUri';
+
+export type { ImageProps };
+
+type Props = Omit<ImageProps, 'source' | 'onError'> & {
+  /** URLs tried in order; falls through to the next on load failure. */
+  uris: string[];
+};
+
+/** expo-image that retries the next URL when one fails to load. */
+export function Image({ uris, recyclingKey, ...rest }: Props) {
+  const { uri, onError } = useFallbackUri(uris);
+  return (
+    <ExpoImage
+      {...rest}
+      source={uri ? { uri } : undefined}
+      recyclingKey={recyclingKey ?? uris[0]}
+      onError={onError}
+    />
+  );
+}

apps/polycentric/src/common/components/Image/index.ts

@@ -0,0 +1,2 @@
+export { Image, type ImageProps } from './Image';
+export { useFallbackUri } from './useFallbackUri';

apps/polycentric/src/common/components/Image/useFallbackUri.test.tsx

@@ -0,0 +1,75 @@
+import { act } from 'react';
+import TestRenderer from 'react-test-renderer';
+import { useFallbackUri } from './useFallbackUri';
+
+type Api = ReturnType<typeof useFallbackUri>;
+
+/** Render the hook in a probe; `result.current` tracks the latest value. */
+function renderHook(initial: string[]) {
+  const result: { current: Api } = { current: null as never };
+  function Probe({ uris }: { uris: string[] }) {
+    result.current = useFallbackUri(uris);
+    return null;
+  }
+  let renderer!: TestRenderer.ReactTestRenderer;
+  act(() => {
+    renderer = TestRenderer.create(<Probe uris={initial} />);
+  });
+  const rerender = (uris: string[]) =>
+    act(() => {
+      renderer.update(<Probe uris={uris} />);
+    });
+  return { result, rerender };
+}
+
+describe('useFallbackUri', () => {
+  it('starts on the first candidate', () => {
+    const { result } = renderHook(['a', 'b', 'c']);
+    expect(result.current.uri).toBe('a');
+  });
+
+  it('advances to the next candidate on error', () => {
+    const { result } = renderHook(['a', 'b', 'c']);
+
+    act(() => result.current.onError());
+    expect(result.current.uri).toBe('b');
+
+    act(() => result.current.onError());
+    expect(result.current.uri).toBe('c');
+  });
+
+  it('stays on the last candidate once every one has failed', () => {
+    const { result } = renderHook(['a', 'b']);
+
+    act(() => result.current.onError());
+    act(() => result.current.onError());
+    act(() => result.current.onError());
+    expect(result.current.uri).toBe('b');
+  });
+
+  it('resets to the first candidate when the list changes', () => {
+    const { result, rerender } = renderHook(['a', 'b']);
+
+    act(() => result.current.onError());
+    expect(result.current.uri).toBe('b');
+
+    rerender(['x', 'y']);
+    expect(result.current.uri).toBe('x');
+  });
+
+  it('keeps its position when the same list is passed again', () => {
+    const { result, rerender } = renderHook(['a', 'b']);
+
+    act(() => result.current.onError());
+    rerender(['a', 'b']);
+    expect(result.current.uri).toBe('b');
+  });
+
+  it('yields undefined for an empty list', () => {
+    const { result } = renderHook([]);
+    expect(result.current.uri).toBeUndefined();
+    // Erroring on nothing is a no-op, not a crash.
+    act(() => result.current.onError());
+    expect(result.current.uri).toBeUndefined();
+  });
+});

apps/polycentric/src/common/components/Image/useFallbackUri.ts

@@ -0,0 +1,22 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * Walk a list of candidate URLs, advancing to the next when one fails to
+ * load. Lets a blob be retried across servers. Resets when the list changes.
+ * Returns the current `uri` and an `onError` to wire into the image.
+ */
+export function useFallbackUri(candidates: string[]): {
+  uri: string | undefined;
+  onError: () => void;
+} {
+  const key = candidates.join('\n');
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => setIndex(0), [key]);
+
+  const onError = useCallback(() => {
+    setIndex((i) => (i + 1 < candidates.length ? i + 1 : i));
+  }, [candidates.length]);
+
+  return { uri: candidates[index], onError };
+}

apps/polycentric/src/common/components/ImageViewer/ImageViewer.tsx

@@ -5,7 +5,7 @@ import Icon from '@/src/common/components/Icon';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { resolveImageSources } from './resolveImageSources';
 import { ImageViewerInput } from './useImageViewerStore';
-import { Image } from 'expo-image';
+import { Image } from '@/src/common/components/Image';
 import {
   Platform,
   Pressable,
@@ -58,7 +58,7 @@ export function ImageViewer({
   const insets = useSafeAreaInsets();
 
   const sources = useMemo(
-    () => resolveImageSources(images, (digest) => client.blobUrl(digest)),
+    () => resolveImageSources(images, (digest) => client.blobUrls(digest)),
     [client, images],
   );
 
@@ -269,8 +269,7 @@ export function ImageViewer({
               ]}
             >
               <Image
-                source={{ uri: current.uri }}
-                recyclingKey={current.uri}
+                uris={current.uris}
                 contentFit="contain"
                 style={[Atoms.w_full, Atoms.h_full]}
               />

apps/polycentric/src/common/components/ImageViewer/resolveImageSources.test.ts

@@ -5,9 +5,9 @@ import type { ImageViewerInput } from './useImageViewerStore';
 // real (native-backed) package out of the test.
 jest.mock('@polycentric/react-native', () => ({ v2: {} }));
 
-type BlobUrl = Parameters<typeof resolveImageSources>[1];
+type BlobUrls = Parameters<typeof resolveImageSources>[1];
 
-// Fake ImageSet variants use string digests so blobUrl results are easy
+// Fake ImageSet variants use string digests so blobUrls results are easy
 // to assert against.
 const variant = (width: number, height: number, digest?: string) => ({
   width,
@@ -19,17 +19,21 @@ const imageSet = (
   ...variants: ReturnType<typeof variant>[]
 ): ImageViewerInput => ({ images: variants }) as unknown as ImageViewerInput;
 
-const blobUrl: BlobUrl = (digest) => `blob://${digest}`;
+const blobUrls: BlobUrls = (digest) => [`blob://${digest}`];
 
 describe('resolveImageSources', () => {
-  it('passes plain-uri sources through unchanged', () => {
+  it('wraps plain-uri sources in a single-candidate list', () => {
     const plain = { uri: 'https://example.com/identicon.png' };
-    expect(resolveImageSources([plain], blobUrl)).toEqual([plain]);
+    expect(resolveImageSources([plain], blobUrls)).toEqual([
+      { uris: ['https://example.com/identicon.png'], aspectRatio: undefined },
+    ]);
   });
 
   it('keeps an explicit aspect ratio on plain sources', () => {
     const plain = { uri: 'https://example.com/banner.png', aspectRatio: 3 };
-    expect(resolveImageSources([plain], blobUrl)).toEqual([plain]);
+    expect(resolveImageSources([plain], blobUrls)).toEqual([
+      { uris: ['https://example.com/banner.png'], aspectRatio: 3 },
+    ]);
   });
 
   it('resolves an ImageSet to the smallest variant at or above the target', () => {
@@ -38,38 +42,46 @@ describe('resolveImageSources', () => {
       variant(VIEWER_TARGET, 1024, 'fit'),
       variant(4096, 2048, 'huge'),
     );
-    expect(resolveImageSources([set], blobUrl)).toEqual([
-      { uri: 'blob://fit', aspectRatio: 2 },
+    expect(resolveImageSources([set], blobUrls)).toEqual([
+      { uris: ['blob://fit'], aspectRatio: 2 },
     ]);
   });
 
   it('falls back to the largest variant when none reach the target', () => {
     const set = imageSet(variant(512, 512, 'small'), variant(1024, 512, 'big'));
-    expect(resolveImageSources([set], blobUrl)).toEqual([
-      { uri: 'blob://big', aspectRatio: 2 },
+    expect(resolveImageSources([set], blobUrls)).toEqual([
+      { uris: ['blob://big'], aspectRatio: 2 },
+    ]);
+  });
+
+  it('keeps one candidate uri per server', () => {
+    const set = imageSet(variant(2048, 1024, 'x'));
+    const multi: BlobUrls = (digest) => [`a://${digest}`, `b://${digest}`];
+    expect(resolveImageSources([set], multi)).toEqual([
+      { uris: ['a://x', 'b://x'], aspectRatio: 2 },
     ]);
   });
 
   it('defaults zero dimensions instead of dividing by zero', () => {
     const set = imageSet(variant(0, 0, 'broken'));
-    expect(resolveImageSources([set], blobUrl)).toEqual([
-      { uri: 'blob://broken', aspectRatio: 1 },
+    expect(resolveImageSources([set], blobUrls)).toEqual([
+      { uris: ['blob://broken'], aspectRatio: 1 },
     ]);
   });
 
   it('drops a set whose chosen variant has no digest', () => {
     expect(
-      resolveImageSources([imageSet(variant(2048, 1024))], blobUrl),
+      resolveImageSources([imageSet(variant(2048, 1024))], blobUrls),
     ).toEqual([]);
   });
 
-  it('drops a set when the blob CDN is not known yet', () => {
+  it('drops a set when no server can serve it', () => {
     const set = imageSet(variant(2048, 1024, 'x'));
-    expect(resolveImageSources([set], () => null)).toEqual([]);
+    expect(resolveImageSources([set], () => [])).toEqual([]);
   });
 
   it('drops empty image sets', () => {
-    expect(resolveImageSources([imageSet()], blobUrl)).toEqual([]);
+    expect(resolveImageSources([imageSet()], blobUrls)).toEqual([]);
   });
 
   it('preserves order across mixed inputs and skips unresolvable ones', () => {
@@ -80,9 +92,9 @@ describe('resolveImageSources', () => {
         imageSet(), // unresolvable
         { uri: 'plain://third', aspectRatio: 0.5 },
       ],
-      blobUrl,
+      blobUrls,
     );
-    expect(sources.map((s) => s.uri)).toEqual([
+    expect(sources.map((s) => s.uris[0])).toEqual([
       'plain://first',
       'blob://second',
       'plain://third',