mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
fix(share): guide recovery when an export replay is refused (#7531)
This commit is contained in:
@@ -43,6 +43,8 @@ Before first registration the host must obtain explicit audience consent and pre
|
||||
|
||||
Hosts can sync a renamed project with `client.updateTitle(id, { title, expected_title })`. An optional `fromReview` hook on `addVersion` supplies feedback attribution after sign-in on each send. Pass the same hook to `recheckHeld` or `refreshReviewExport` to clear the recorded activity when a pending version becomes ready.
|
||||
|
||||
If a create request had no confirmed outcome, a later refusal keeps the original request and its idempotency key. The original request may still create a version. When the server has no more specific recovery instruction, check the review page and export a new video with different settings before adding another version.
|
||||
|
||||
Identity remains in the project’s generated review.json metadata (or the existing backend-specific filename); pending export requests remain in the generated review-export.json metadata. No bearer is stored there. A copied folder must deliberately reset sharing identity when creating a new project; a renamed folder retains it. A malformed/unreadable record fails instead of silently registering a new project. The error identifies the metadata file and asks the owner to restore a backup or contact support to reconnect the existing share; deleting the file can discard recovery state or consume another slot.
|
||||
|
||||
Metadata mutations and version uploads use separate cross-process locks under `.hyperframes`. Locks publish complete owner metadata with a hard link or, on volumes that reject hard links, an atomic rename of a directory containing the owner record. The kernel reclaims a recorded owner only when the same machine proves that process is dead. Older clients may report a filesystem error while a fallback directory is held. An empty legacy lock file still requires manual recovery after stopping all sharing processes that can access the project. Interrupted upload operations resume with their saved idempotency keys. Concurrent identical uploads re-read the completed version under the lock and do not create another version.
|
||||
|
||||
@@ -69,6 +69,8 @@ const SLOW_POLL_MS = 30_000;
|
||||
const FINAL = new Set(["export_blocked", "content_rejected", "feature_unavailable"]);
|
||||
/** Too big or too long: the same file is refused again, but a smaller or shorter export can go up. */
|
||||
const TOO_BIG = new Set(["export_too_large", "export_too_long"]);
|
||||
const UNCONFIRMED_VERSION =
|
||||
"Couldn't confirm whether the previous version was created. Check the review page. To add a new version, change the export settings and export again.";
|
||||
/** Longer than the backend's own limiter ever asks, and short enough that a laptop waking up checks again soon. */
|
||||
const MAX_WAIT_MS = 5 * 60_000;
|
||||
/** A run stops watching after this long; the video stays recorded, so the next press reads it back. */
|
||||
@@ -210,13 +212,19 @@ async function writeState(dir, state) {
|
||||
|
||||
/** @typedef {{ sentence: string, final: boolean, exportHelps: boolean, held?: boolean }} Said
|
||||
* @typedef {Said & { exportKey: string }} Failure */
|
||||
/** @param {unknown} error @returns {Said} */
|
||||
const said = (error) => ({
|
||||
sentence: versionSentence(error),
|
||||
final: error instanceof ReviewFailed && (FINAL.has(error.reason) || TOO_BIG.has(error.reason)),
|
||||
exportHelps: error instanceof ReviewFailed && TOO_BIG.has(error.reason),
|
||||
...(error instanceof ReviewFailed && error.reason === "held_for_review" && { held: true }),
|
||||
});
|
||||
/** @param {unknown} error @param {boolean} [refusedReplay] @returns {Said} */
|
||||
function said(error, refusedReplay = false) {
|
||||
const sentence = versionSentence(error, refusedReplay ? UNCONFIRMED_VERSION : undefined);
|
||||
const exportHelps =
|
||||
sentence === UNCONFIRMED_VERSION ||
|
||||
(error instanceof ReviewFailed && TOO_BIG.has(error.reason));
|
||||
return {
|
||||
sentence,
|
||||
final: exportHelps || (error instanceof ReviewFailed && FINAL.has(error.reason)),
|
||||
exportHelps,
|
||||
...(error instanceof ReviewFailed && error.reason === "held_for_review" && { held: true }),
|
||||
};
|
||||
}
|
||||
|
||||
/** A failure found here, before the server: fixing the export fixes it. @param {string} sentence @returns {Said} */
|
||||
const local = (sentence) => ({ sentence, final: false, exportHelps: false });
|
||||
@@ -234,7 +242,7 @@ const failures = new Map();
|
||||
/** Which export a failure was about: the newest export file and the project as it was rendered. @param {string} dir */
|
||||
const exportKeyOf = (dir) => {
|
||||
const latest = latestExportFile(dir);
|
||||
return latest ? `${latest.path}\n${latest.fingerprint ?? ""}` : "";
|
||||
return latest ? `${latest.id}\n${latest.path}\n${latest.fingerprint ?? ""}` : "";
|
||||
};
|
||||
|
||||
/** Whether the newest export can go up now: there is one, it is MP4, and the project has not moved past it.
|
||||
@@ -549,11 +557,8 @@ async function poll(r, id, current, until, every) {
|
||||
}
|
||||
}
|
||||
|
||||
/** A refusal the same body would get again, or a spent upload, needs a new key next time.
|
||||
* A refusal of a replay cannot settle an earlier unanswered create.
|
||||
* @param {unknown} error @param {VersionRecord["pending"]} pending */
|
||||
const spent = (error, pending) =>
|
||||
(!pending?.unanswered || pending.videoId !== null) &&
|
||||
/** @param {unknown} error */
|
||||
const permanentRefusal = (error) =>
|
||||
error instanceof ReviewFailed &&
|
||||
error.status >= 400 &&
|
||||
error.status < 500 &&
|
||||
@@ -631,12 +636,20 @@ async function sendVersion(r, report, source, id, state) {
|
||||
const done = await watch(r, id, uploaded, size, report, clock);
|
||||
return finishRun(r, state, pending, id, done, first);
|
||||
} catch (error) {
|
||||
if (spent(error, state.pending)) await writeState(r.projectPath, { ...state, pending: null });
|
||||
console.error("[review] version failed:", error);
|
||||
return said(error);
|
||||
return failedSend(r.projectPath, state, error);
|
||||
}
|
||||
}
|
||||
|
||||
/** @param {string} dir @param {VersionRecord} state @param {unknown} error */
|
||||
async function failedSend(dir, state, error) {
|
||||
const refused = permanentRefusal(error);
|
||||
// An earlier create can still be in flight when the replay is refused.
|
||||
const unansweredCreate = state.pending?.unanswered === true && state.pending.videoId === null;
|
||||
if (refused && !unansweredCreate) await writeState(dir, { ...state, pending: null });
|
||||
console.error("[review] version failed:", error);
|
||||
return said(error, refused && unansweredCreate);
|
||||
}
|
||||
|
||||
/** @param {Required<VersionRequest>} r @param {VersionRecord} state
|
||||
* @param {NonNullable<VersionRecord["pending"]>} pending @param {string} id @param {ExportDTO} done @param {boolean} first */
|
||||
async function finishRun(r, state, pending, id, done, first) {
|
||||
|
||||
@@ -24,9 +24,9 @@ const SAID = {
|
||||
held_for_review: HELD_FOR_REVIEW,
|
||||
};
|
||||
|
||||
/** @param {unknown} error */
|
||||
export function versionSentence(error) {
|
||||
if (!(error instanceof ReviewFailed)) return "Couldn't add this version. Try again.";
|
||||
/** @param {unknown} error @param {string} [fallback] */
|
||||
export function versionSentence(error, fallback = "Couldn't add this version. Try again.") {
|
||||
if (!(error instanceof ReviewFailed)) return fallback;
|
||||
const said = SAID[error.reason];
|
||||
if (said) return typeof said === "function" ? said(error) : said;
|
||||
if (error.status === 0) return "Couldn't reach HeyGen. Check your connection and try again.";
|
||||
@@ -35,7 +35,7 @@ export function versionSentence(error) {
|
||||
// written for developers, so it is never shown.
|
||||
if (error.status === 200)
|
||||
return "HyperFrames couldn't process this video. Export it again, then try again.";
|
||||
return "Couldn't add this version. Try again.";
|
||||
return fallback;
|
||||
}
|
||||
|
||||
/** "in about 3 hours", from the server's Retry-After. @param {number | undefined} ms */
|
||||
|
||||
@@ -16,6 +16,7 @@ import {
|
||||
reviewDestination,
|
||||
reviewFiles,
|
||||
reviewVersion,
|
||||
ReviewFailed,
|
||||
shareForReview,
|
||||
} from "../src/index.mjs";
|
||||
|
||||
@@ -27,7 +28,7 @@ const ready = (id) => ({
|
||||
version_id: `version-${id}`,
|
||||
exported_at: "2026-11-04T00:00:00Z",
|
||||
});
|
||||
const bind = (dir) =>
|
||||
const bind = (dir, exportId = "render") =>
|
||||
bindShareHost({
|
||||
normalize: realpathSync,
|
||||
channelSite: site,
|
||||
@@ -36,7 +37,7 @@ const bind = (dir) =>
|
||||
latestExportFile: () => ({
|
||||
path: join(dir, ".hyperframes", "video.mp4"),
|
||||
fingerprint: "rendered",
|
||||
id: "render",
|
||||
id: exportId,
|
||||
}),
|
||||
});
|
||||
const probe = async () => ({ width: 1920, height: 1080, duration: 1 });
|
||||
@@ -127,6 +128,59 @@ async function retry(dir, operationId) {
|
||||
assert.equal(await pendingReviewExport(dir), null);
|
||||
}
|
||||
|
||||
test("a refused replay keeps its original operation and offers to export a new video", async (t) => {
|
||||
const { dir, render, stateFile } = await project(t);
|
||||
const sends = [];
|
||||
const snapshot = { space_id: "space", composition_id: "comp", snapshot_id: "snap" };
|
||||
const client = {
|
||||
createExport: async (_id, body) => {
|
||||
sends.push(body);
|
||||
if (sends.length === 1) throw new ReviewFailed(503, "unavailable");
|
||||
if (sends.length < 4) throw new ReviewFailed(422, "snapshot_mismatch");
|
||||
return ready("new");
|
||||
},
|
||||
};
|
||||
const version = { ...request(dir, client), filesForExport: async () => snapshot };
|
||||
assert.match(await addVersion(version), /Try again/);
|
||||
for (let replay = 0; replay < 2; replay++) {
|
||||
assert.match(await addVersion(version), /change the export settings and export again/i);
|
||||
const failure = await reviewVersion(dir);
|
||||
assert.equal(failure.retryable, false);
|
||||
assert.equal(failure.exportHelps, true);
|
||||
assert.equal(JSON.parse(await readFile(stateFile, "utf8")).pending.unanswered, true);
|
||||
}
|
||||
assert.deepEqual(sends, [sends[0], sends[0], sends[0]]);
|
||||
assert.deepEqual(sends[0].snapshot, snapshot);
|
||||
|
||||
await writeFile(render, "new export with different settings");
|
||||
bind(dir, "re-export");
|
||||
assert.equal((await reviewVersion(dir)).failure, null);
|
||||
assert.equal(await addVersion(version), null);
|
||||
assert.notEqual(sends[3].client_operation_id, sends[0].client_operation_id);
|
||||
assert.equal(await pendingReviewExport(dir), null);
|
||||
});
|
||||
|
||||
test("a snapshot refusal on the first send still adds the video without files", async (t) => {
|
||||
const { dir } = await project(t);
|
||||
const snapshot = { space_id: "space", composition_id: "comp", snapshot_id: "snap" };
|
||||
const sends = [];
|
||||
const client = {
|
||||
createExport: async (_id, body) => {
|
||||
sends.push(body);
|
||||
if (sends.length === 1) throw new ReviewFailed(422, "snapshot_mismatch");
|
||||
return ready("fallback");
|
||||
},
|
||||
};
|
||||
assert.equal(
|
||||
await addVersion({ ...request(dir, client), filesForExport: async () => snapshot }),
|
||||
null,
|
||||
);
|
||||
assert.equal(sends.length, 2);
|
||||
assert.deepEqual(sends[0].snapshot, snapshot);
|
||||
assert.equal(sends[1].snapshot, undefined);
|
||||
assert.notEqual(sends[1].client_operation_id, sends[0].client_operation_id);
|
||||
});
|
||||
|
||||
for (const whileLocked of [true, false]) {
|
||||
test(
|
||||
`a stale held response preserves a newer export (uploader locked: ${whileLocked})`,
|
||||
|
||||
Reference in New Issue
Block a user