Merge pull request 'Upload failures tell the sender a reason and a next step' (#159) from void/upload-failure-reasons into dev
Some checks failed
Rat dev preview / Build dev preview (push) Has been cancelled
Build pull request / Build pull request (pull_request) Has been cancelled

This commit is contained in:
Void 2026-11-14 01:53:57 +00:00
commit 38b2c064b2
9 changed files with 289 additions and 22 deletions

View file

@ -6,6 +6,7 @@ import { useMatrixClient } from '../../hooks/useMatrixClient';
import { TUploadContent } from '../../utils/matrix';
import { bytesToSize, getFileTypeIcon } from '../../utils/common';
import { useMediaConfig } from '../../hooks/useMediaConfig';
import { UploadFailureNote } from './UploadFailureNote';
import { PhoneHitSpread28 } from '../../styles/PhoneHit.css';
type CompactUploadCardRendererProps = {
@ -93,7 +94,7 @@ export function CompactUploadCardRenderer({
)}
{upload.status === UploadStatus.Error && (
<UploadCardError>
<Text size="T200">{upload.error.message}</Text>
<UploadFailureNote error={upload.error} />
</UploadCardError>
)}
{upload.status === UploadStatus.Idle && fileSizeExceeded && (

View file

@ -12,6 +12,7 @@ import {
} from '../../state/room/roomInputDrafts';
import { useObjectURL } from '../../hooks/useObjectURL';
import { useMediaConfig } from '../../hooks/useMediaConfig';
import { UploadFailureNote } from './UploadFailureNote';
import { PhoneHitSpread28 } from '../../styles/PhoneHit.css';
type PreviewImageProps = {
@ -192,7 +193,7 @@ export function UploadCardRenderer({
)}
{upload.status === UploadStatus.Error && (
<UploadCardError>
<Text size="T200">{upload.error.message}</Text>
<UploadFailureNote error={upload.error} />
</UploadCardError>
)}
{upload.status === UploadStatus.Idle && fileSizeExceeded && (

View file

@ -0,0 +1,33 @@
import React from 'react';
import { renderToStaticMarkup } from 'react-dom/server';
import { describe, expect, it } from 'vitest';
import { uploadFailure } from '../../utils/matrix';
import { UploadFailureNote } from './UploadFailureNote';
const text = (html: string) =>
html
.replace(/<[^>]*>/g, ' ')
.replace(/\s+/g, ' ')
.trim();
describe('the failed upload card', () => {
it('leads with the reason and the next step, and keeps the diagnostics behind Details', async () => {
const error = await uploadFailure(new DOMException('', 'AbortError'), new Blob(['abcd']), {
startedAt: Date.now(),
});
const html = renderToStaticMarkup(<UploadFailureNote error={error} />);
const before = html.slice(0, html.indexOf('<details'));
expect(text(before)).toBe(
'Upload failed: the connection dropped before the file started. Send again.'
);
expect(before).not.toContain('bytes');
expect(html).toMatch(/<details[^>]*>.*Details.*<\/details>/s);
expect(text(html.slice(html.indexOf('<details')))).toContain('4 bytes');
});
it('an error nobody classified still shows a sentence, not a blank card', () => {
const html = renderToStaticMarkup(<UploadFailureNote error={new Error('boom')} />);
expect(text(html)).toContain('Upload failed. Send again');
expect(text(html)).toContain('boom');
});
});

View file

@ -0,0 +1,22 @@
import React from 'react';
import { Text } from 'folds';
import { uploadFailureText } from '../../utils/uploadReason';
/** A failed upload as the card shows it: the reason and what to do, the diagnostic text one tap away. */
export function UploadFailureNote({ error }: { error: Error }) {
return (
<>
<Text size="T200">{uploadFailureText(error)}</Text>
<details style={{ flex: 1, minWidth: 0 }}>
<summary style={{ minHeight: 44, display: 'flex', alignItems: 'center' }}>
<Text as="span" size="T200">
Details
</Text>
</summary>
<Text size="T200" style={{ wordBreak: 'break-word' }}>
{error.message}
</Text>
</details>
</>
);
}

View file

@ -215,6 +215,22 @@ describe('refusals', () => {
);
});
it('a failure the client saw, not the server, is named too', async () => {
const dropped: SharePort<ShareFile> = {
send: async () => '$e',
contentOf: async () => {
throw Object.assign(new Error('x'), {
errcode: 'AbortError',
info: { aborted: true, progressed: true },
});
},
};
const res = await sendShareSet(dropped, 't', clips.slice(0, 1));
expect(resultNote(res)).toBe(
'Nothing was shared. Not sent: a.ogg (the connection dropped partway through)'
);
});
it('an unnamed failure lists the bare name', async () => {
const res = await sendShareSet(refuse('M_UNKNOWN'), 't', clips.slice(0, 1));
expect(resultNote(res)).toBe('Nothing was shared. Not sent: a.ogg');

View file

@ -3,6 +3,8 @@
// are the same thing to every viewer. Ports are injected so the order and the failure rules are
// testable without a homeserver. See docs/file-zone.md, "Share a set".
import { uploadReason } from '../../utils/uploadReason';
export type ShareFile = { name: string; mimeType: string };
/** What sendShareSet needs from the outside world. */
@ -45,17 +47,8 @@ export const freshest = (album: ExistingAlbum, events: ThreadEvent[]): ExistingA
export const CANCELLED = 'stopped';
const REFUSALS: Record<string, string> = {
M_TOO_LARGE: 'too large for this server',
M_FORBIDDEN: 'not allowed to upload here',
M_LIMIT_EXCEEDED: 'uploading too fast, try again shortly',
};
/** The sentence for a homeserver refusal we know, from the error's Matrix errcode. */
export const refusalOf = (e: unknown): string | undefined => {
const code = (e as { errcode?: unknown } | null)?.errcode;
return typeof code === 'string' && Object.hasOwn(REFUSALS, code) ? REFUSALS[code] : undefined;
};
/** The short reason for a failure we can name (the homeserver's refusal or what the client saw), else undefined. */
export const refusalOf = (e: unknown): string | undefined => uploadReason(e)?.cause;
/** The reply relation Matrix clients expect for a thread message: root, with the last event as fallback reply. */
export const threadRelation = (rootId: string, lastId: string) => ({

View file

@ -18,6 +18,7 @@ import { IImageInfo, IThumbnailContent, IVideoInfo } from '../../types/matrix/co
import { AccountDataEvent } from '../../types/matrix/accountData';
import { getStateEvent } from './room';
import { Membership, StateEvent } from '../../types/matrix/room';
import { NO_INFO, UploadFailureInfo } from './uploadReason';
const DOMAIN_REGEX = /\b(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}\b/;
@ -392,8 +393,19 @@ export const uploadFailure = async (
if (trace.previous) parts.push(`retried (attempt 1: ${trace.previous})`);
}
const error = `Upload failed: ${message ? `${name}: ${message}` : name} (${parts.join(', ')})`;
const err = new MatrixError({ error, errcode: name });
// A homeserver refusal keeps its own errcode (M_TOO_LARGE ...), which is what names it to the sender.
const errcode = typeof e?.errcode === 'string' && e.errcode.startsWith('M_') ? e.errcode : name;
const err = new MatrixError({ error, errcode });
(err as any).cause = e;
const info: UploadFailureInfo = {
unreadable: readable !== 'file readable',
offline: typeof navigator !== 'undefined' && navigator.onLine === false,
hidden: typeof document !== 'undefined' && document?.visibilityState === 'hidden',
aborted: name === 'AbortError',
progressed: trace?.firstProgressAt !== undefined,
stopped: trace?.signalAborted === true,
};
(err as any).info = info;
return err;
};
@ -435,14 +447,14 @@ export const uploadContent = async (
body = await copyInMemory(file);
} catch (readErr: any) {
const errcode = readErr?.name || 'Error';
onError(
new MatrixError({
error: `Upload failed: file unreadable before upload (${errcode}) (${file.size} bytes, ${
file.type || 'unknown type'
})`,
errcode,
})
);
const unreadable = new MatrixError({
error: `Upload failed: file unreadable before upload (${errcode}) (${file.size} bytes, ${
file.type || 'unknown type'
})`,
errcode,
});
(unreadable as any).info = { ...NO_INFO, unreadable: true };
onError(unreadable);
return;
}
const probe = startAbortProbe();

View file

@ -0,0 +1,111 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import { uploadContent, uploadFailure } from './matrix';
import { uploadFailureText, uploadReason } from './uploadReason';
// What a person reads, from failures built the way the app builds them: through uploadFailure and
// uploadContent, not by hand-made info objects.
const abort = () => new DOMException('', 'AbortError');
const blob = new Blob(['abcd'], { type: 'image/jpeg' });
const textOf = async (e: unknown, trace = { startedAt: Date.now() } as any, file: Blob = blob) =>
uploadFailureText(await uploadFailure(e, file, trace));
afterEach(() => {
vi.unstubAllGlobals();
});
describe('what the sender is told when an upload fails', () => {
it('a drop before any byte left says the file never started, and to send again', async () => {
expect(await textOf(abort())).toBe(
'Upload failed: the connection dropped before the file started. Send again.'
);
});
it('a drop after progress says partway through and points at Wi-Fi', async () => {
const text = await textOf(abort(), { startedAt: 1, firstProgressAt: 5, loaded: 2, total: 4 });
expect(text).toContain('dropped partway through');
expect(text).toContain('Wi-Fi');
});
it('a drop with the tab in the background says to keep the tab open', async () => {
vi.stubGlobal('document', { visibilityState: 'hidden' });
const text = await textOf(abort());
expect(text).toContain('(this tab was in the background)');
expect(text).toContain('Keep this tab open');
});
it('offline outranks the drop it caused', async () => {
vi.stubGlobal('navigator', { onLine: false });
expect(await textOf(abort())).toBe('Upload failed: you are offline. Reconnect and send again.');
});
it('offline is not blamed for a failure that was not a dropped request', async () => {
vi.stubGlobal('navigator', { onLine: false });
expect(await textOf(new Error('Bad Gateway'))).toContain('Upload failed. Send again;');
});
it('a file the browser can no longer read says to pick it again', async () => {
const gone = new Blob(['x']);
(gone as any).arrayBuffer = () => Promise.reject(new DOMException('gone', 'NotReadableError'));
expect(await textOf(abort(), undefined, gone)).toContain('can no longer read the file');
});
it('a stopped upload says stopped, not that the connection failed', async () => {
const text = await textOf(abort(), { startedAt: 1, signalAborted: true });
expect(text).toBe('Upload failed: stopped. Send it again when you are ready.');
});
it('a homeserver refusal says what the server said in words, with what to do', () => {
expect(uploadFailureText({ errcode: 'M_TOO_LARGE' })).toBe(
'Upload failed: too large for this server. Pick a smaller file.'
);
expect(uploadFailureText({ errcode: 'M_FORBIDDEN' })).toContain('Ask a steward');
expect(uploadFailureText({ errcode: 'M_LIMIT_EXCEEDED' })).toContain('Wait a moment');
});
it('a failure we cannot name stays generic and sends the sender to the details', async () => {
const text = await textOf(new Error('Timeout'));
expect(text).toBe(
'Upload failed. Send again; if it keeps failing, show the details below to a steward.'
);
expect(uploadReason({ errcode: 'constructor' })).toBeUndefined();
expect(uploadReason(null)).toBeUndefined();
});
it('the long diagnostic text is still on the error for the details', async () => {
const err = await uploadFailure(abort(), blob, { startedAt: Date.now() });
expect(err.message).toContain('4 bytes');
expect(err.message).toContain('no progress');
});
});
describe('through uploadContent, as the composer and the share panel call it', () => {
it('an unreadable picked file is named before any request', async () => {
const bad = new Blob(['x']);
(bad as any).arrayBuffer = () => Promise.reject(new DOMException('gone', 'NotReadableError'));
const mx = { uploadContent: vi.fn() } as any;
const onError = vi.fn();
await uploadContent(mx, bad, { onSuccess: vi.fn(), onError });
expect(mx.uploadContent).not.toHaveBeenCalled();
expect(uploadFailureText(onError.mock.calls[0][0])).toContain('can no longer read the file');
});
it('a request that dies is told as a drop', async () => {
const mx = { uploadContent: () => Promise.reject(abort()) } as any;
const onError = vi.fn();
await uploadContent(mx, blob, { onSuccess: vi.fn(), onError });
expect(uploadFailureText(onError.mock.calls[0][0])).toContain('the connection dropped');
});
it('a server that refuses keeps its errcode and is told in words', async () => {
const mx = {
uploadContent: () =>
Promise.reject(Object.assign(new Error('x'), { errcode: 'M_TOO_LARGE' })),
} as any;
const onError = vi.fn();
await uploadContent(mx, blob, { onSuccess: vi.fn(), onError });
expect(onError.mock.calls[0][0].errcode).toBe('M_TOO_LARGE');
expect(uploadFailureText(onError.mock.calls[0][0])).toBe(
'Upload failed: too large for this server. Pick a smaller file.'
);
});
});

View file

@ -0,0 +1,78 @@
// What a person is told when an upload fails: a cause they can name and the thing to do next.
// uploadFailure (matrix.ts) attaches the facts the client observed as `info`; the homeserver's
// refusals arrive as Matrix errcodes. The long diagnostic text stays on the error's message.
/** What the client observed at the moment an upload died. */
export type UploadFailureInfo = {
/** The browser could not read the picked file back. */
unreadable: boolean;
/** navigator.onLine was false. */
offline: boolean;
/** The tab was in the background. */
hidden: boolean;
/** The request was aborted (the SDK reports a dropped XHR as an AbortError). */
aborted: boolean;
/** At least one progress event arrived before it died. */
progressed: boolean;
/** The sender pressed Stop. */
stopped: boolean;
};
export const NO_INFO: UploadFailureInfo = {
unreadable: false,
offline: false,
hidden: false,
aborted: false,
progressed: false,
stopped: false,
};
export type UploadReason = { cause: string; action: string };
const REFUSALS: Record<string, UploadReason> = {
M_TOO_LARGE: { cause: 'too large for this server', action: 'Pick a smaller file.' },
M_FORBIDDEN: {
cause: 'not allowed to upload here',
action: 'Ask a steward if you should be able to.',
},
M_LIMIT_EXCEEDED: {
cause: 'uploading too fast, try again shortly',
action: 'Wait a moment and send again.',
},
};
/** The reason for a failure we can name, or undefined when we cannot: then the text stays generic. */
export const uploadReason = (e: unknown): UploadReason | undefined => {
const code = (e as { errcode?: unknown } | null)?.errcode;
if (typeof code === 'string' && Object.hasOwn(REFUSALS, code)) return REFUSALS[code];
const info = (e as { info?: Partial<UploadFailureInfo> } | null)?.info;
if (!info) return undefined;
if (info.stopped) return { cause: 'stopped', action: 'Send it again when you are ready.' };
if (info.unreadable)
return {
cause: 'this device can no longer read the file',
action: 'Pick it again; if it came from another app, save a copy first.',
};
// Offline and hidden-tab are only read as the cause of a dropped request, not of any failure.
if (!info.aborted) return undefined;
if (info.offline) return { cause: 'you are offline', action: 'Reconnect and send again.' };
if (info.hidden)
return {
cause: 'the connection dropped (this tab was in the background)',
action: 'Keep this tab open while it uploads, and send again.',
};
return info.progressed
? {
cause: 'the connection dropped partway through',
action: 'Send again; a large file is safer on Wi-Fi.',
}
: { cause: 'the connection dropped before the file started', action: 'Send again.' };
};
/** The line the upload card shows: the reason when there is one, else a generic line. */
export const uploadFailureText = (e: unknown): string => {
const reason = uploadReason(e);
return reason
? `Upload failed: ${reason.cause}. ${reason.action}`
: 'Upload failed. Send again; if it keeps failing, show the details below to a steward.';
};