feat(share): measure local sharing outcomes (#7138)

This commit is contained in:
terencecho
2026-11-09 16:10:32 -08:00
committed by Terence Cho
parent 9cc2bcdfa2
commit 8d86e2cdcd
6 changed files with 381 additions and 11 deletions
+120 -1
View File
@@ -11,6 +11,8 @@ const mocks = vi.hoisted(() => ({
add: vi.fn(),
pending: vi.fn(),
refresh: vi.fn(),
event: vi.fn(),
access: vi.fn(),
}));
vi.mock("@hyperframes/share", () => ({
reviewClient: () => ({ project: mocks.project, spaces: mocks.spaces, reviewFlags: mocks.flags }),
@@ -33,7 +35,7 @@ vi.mock("@hyperframes/share", () => ({
},
}));
vi.mock("./auth.js", () => ({
createShareAccess: () => ({ access: vi.fn() }),
createShareAccess: () => ({ access: mocks.access }),
shareSite: () => "https://hyperframes.dev",
}));
vi.mock("./host.js", () => ({
@@ -41,6 +43,11 @@ vi.mock("./host.js", () => ({
bindCliShareProject: (path: string) => path,
}));
vi.mock("./render.js", () => ({ prepareShareRender: mocks.render }));
vi.mock("../telemetry/client.js", () => ({
trackEvent: mocks.event,
resetTelemetryPostureCache: vi.fn(),
}));
vi.mock("../telemetry/config.js", () => ({ readConfigFresh: vi.fn() }));
import { createShareService } from "./service.js";
const shared = {
projectId: "project",
@@ -269,3 +276,115 @@ describe("asynchronous share recovery", () => {
});
});
});
describe("share rollout signals", () => {
const events = () => mocks.event.mock.calls.map(([name]) => name);
it("records a completed video even when its review link is disabled", async () => {
mocks.status.mockResolvedValue({ ...shared, url: null });
mocks.add.mockImplementation(async (request) => request.onAdded());
const result = await createShareService("/secret").run({ action: "update" });
expect(result.state).toBe("link_off");
expect(events()).toContain("share_video_ready");
expect(events()).not.toContain("share_mutation_processing");
});
it("records the allowlisted missing-audience usage reason", async () => {
await expect(createShareService("/secret").run({ action: "share" })).rejects.toMatchObject({
code: "audience_required",
});
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ reason: "audience_required" });
});
it("records recovery before refreshing a completed pending upload clears its state", async () => {
mocks.status.mockResolvedValue(shared);
mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" });
mocks.refresh.mockImplementation(async () => mocks.pending.mockResolvedValue(null));
await createShareService("/secret").run({ action: "share" });
expect(events()).toContain("share_recovery_attempted");
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true });
expect(events()).not.toContain("share_video_ready");
expect(mocks.add).not.toHaveBeenCalled();
});
it("records only verified upload admission and ready, attributed to local Studio", async () => {
mocks.status.mockResolvedValue(shared);
mocks.add.mockImplementation(async (request) => {
request.onProgress({ step: "preparing", sent: 0, total: 0 });
request.onProgress({ step: "uploading", sent: 1, total: 2 });
request.onProgress({ step: "processing", sent: 2, total: 2 });
request.onAdded();
});
await createShareService("/private/project", undefined, { surface: "local_studio" }).run({
action: "update",
});
expect(events()).toEqual([
"share_mutation_attempted",
"share_mutation_authenticated",
"share_mutation_admitted",
"share_video_ready",
]);
expect(mocks.event.mock.calls.every(([, data]) => data.client_surface === "local_studio")).toBe(
true,
);
expect(new Set(mocks.event.mock.calls.map(([, data]) => data.attempt_id)).size).toBe(1);
});
it("counts quota refusal without admission, rendering, or raw error details", async () => {
mocks.spaces.mockResolvedValue([
{
space_id: "space",
bound: true,
can_create_review: true,
review_entitlements: { can_register_project: false },
},
]);
await expect(
createShareService("/secret").run({ action: "share", audience: "public" }),
).rejects.toBeDefined();
expect(events()).toEqual([
"share_mutation_attempted",
"share_mutation_authenticated",
"share_mutation_failed",
]);
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({
reason: "review_project_limit_reached",
});
expect(mocks.render).not.toHaveBeenCalled();
});
it("records pending recovery without labeling the prior ready version new", async () => {
mocks.status.mockResolvedValue(shared);
mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" });
mocks.add.mockResolvedValue(null);
mocks.version.mockResolvedValue({ last: { current: false }, source: "ready" });
await createShareService("/secret").run({ action: "update" });
expect(events()).toContain("share_recovery_attempted");
expect(events()).toContain("share_mutation_processing");
expect(events()).not.toContain("share_video_ready");
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true });
});
it("existing-link retrieval and polling never count as a new video or copied link", async () => {
mocks.status.mockResolvedValue(shared);
const service = createShareService("/secret");
await service.run({ action: "status" });
expect(events()).toEqual([]);
await service.run({ action: "share" });
expect(events()).toEqual([
"share_mutation_attempted",
"share_mutation_authenticated",
"share_existing_link_returned",
]);
});
it("stops entry creation on authoritative rollback while keeping existing links readable", async () => {
mocks.flags.mockResolvedValue({ versionSharing: false });
await expect(
createShareService("/secret").run({ action: "share", audience: "public" }),
).rejects.toMatchObject({ reason: "feature_unavailable" });
expect(mocks.render).not.toHaveBeenCalled();
expect(mocks.create).not.toHaveBeenCalled();
mocks.status.mockResolvedValue(shared);
expect((await createShareService("/secret").run({ action: "share" })).ready).toBe(true);
});
});
it("link reactivation cannot bypass the first-share rollout gate", async () => {
mocks.flags.mockResolvedValue({ versionSharing: false });
await expect(createShareService("/secret").linkOn()).rejects.toMatchObject({
reason: "not_shared",
});
expect(mocks.create).not.toHaveBeenCalled();
});
+48 -10
View File
@@ -21,6 +21,7 @@ import { createShareAccess, shareSite } from "./auth.js";
import { assertReviewUploadStorage, bindCliShareProject } from "./host.js";
import { prepareShareRender } from "./render.js";
import { prepareCliShareSource, uncheckedSource, type PreparedShareSource } from "./sources.js";
import { observeShareMutation, type ShareAttempt, type ShareSurface } from "./telemetry.js";
export interface ShareAction {
action: "share" | "update" | "status" | "manage";
@@ -34,10 +35,25 @@ function linkState(share: ReviewShare | null, ready: boolean): string {
if (!share.url) return "link_off";
return ready ? "ready" : "processing";
}
async function readStatus(dir: string, client: ReviewClient, expectedProjectId?: string) {
async function refreshShare(
dir: string,
client: ReviewClient,
expectedProjectId?: string,
onRecovery?: (pending: boolean) => void,
) {
const share = await reviewStatus({ projectPath: dir, client });
if (expectedProjectId) assertUploadProject(share, expectedProjectId);
if (onRecovery) onRecovery(isProcessing(await pendingReviewExport(dir), share));
if (share) await refreshReviewExport(dir, client);
return share;
}
async function readStatus(
dir: string,
client: ReviewClient,
expectedProjectId?: string,
onRecovery?: (pending: boolean) => void,
) {
const share = await refreshShare(dir, client, expectedProjectId, onRecovery);
const project = await readProject(share, client);
const latest = project?.latest_ready_version_id ?? null;
const version = await reviewVersion(dir, { latestReadyVersionId: latest });
@@ -142,6 +158,7 @@ function assertResumeSource(current: ShareState, input: ShareAction) {
export function createShareService(
projectPath: string,
progress: (value: ReviewExportProgress | null) => void = () => {},
options: { surface?: ShareSurface } = {},
) {
const dir = bindCliShareProject(projectPath);
const auth = createShareAccess();
@@ -150,7 +167,12 @@ export function createShareService(
await auth.access();
return readStatus(dir, client, expectedProjectId);
};
const upload = async (input: ShareAction, projectId: string, sources: PreparedShareSource) => {
const upload = async (
input: ShareAction,
projectId: string,
sources: PreparedShareSource,
attempt: ShareAttempt,
) => {
const end = Date.now() + (input.waitSeconds ?? 300) * 1000;
let added = false;
const failure = await addVersion({
@@ -158,7 +180,10 @@ export function createShareService(
projectId,
title: basename(dir),
client,
onProgress: progress,
onProgress: (value) => {
attempt.progress(value);
progress(value);
},
allowPending: true,
...(sources.filesForExport && { filesForExport: sources.filesForExport }),
requireSource: sources.requireSource,
@@ -171,8 +196,11 @@ export function createShareService(
if (failure) throw new Error(failure);
const result = { ...(await status(projectId)), source: sources.source };
if (result.version.failure) throw new Error(result.version.failure);
if (!added && !result.version.last?.current)
if (!added && !result.version.last?.current) {
attempt.complete(false, added);
return { ...result, state: "processing", ready: false, url: null };
}
attempt.complete(result.ready, added);
return result;
};
const uploadTarget = async (current: ReviewShare | null, input: ShareAction, space?: string) => {
@@ -204,11 +232,15 @@ export function createShareService(
audience: target.audience,
});
};
const run = async (input: ShareAction) => {
const current = await status();
if (input.action === "status" || input.action === "manage") return current;
const mutate = async (input: ShareAction, attempt: ShareAttempt) => {
await auth.access();
attempt.authenticated();
const current = await readStatus(dir, client, undefined, attempt.recover);
assertExistingIntent(current.share, input);
if (retrievesExisting(current, input)) return current;
if (retrievesExisting(current, input)) {
attempt.retrieved();
return current;
}
const flags = await client.reviewFlags();
if (!flags.versionSharing) throw new ReviewFailed(403, "feature_unavailable");
const space = current.share
@@ -223,11 +255,16 @@ export function createShareService(
shareFiles: flags.shareFiles,
});
if (sources.requireSource) await checkPreparedTarget(target);
return upload(input, target.projectId, sources);
return upload(input, target.projectId, sources, attempt);
};
return {
status,
run,
run: (input: ShareAction) =>
input.action === "status" || input.action === "manage"
? status()
: observeShareMutation(input.action, options.surface ?? "cli", (attempt) =>
mutate(input, attempt),
),
capabilities: () => client.reviewFlags(),
spaces: () => client.spaces(),
setAccess: async (access: AccessMode) => {
@@ -239,6 +276,7 @@ export function createShareService(
return status();
},
linkOn: async () => {
if (!(await status()).share) throw new ReviewFailed(404, "not_shared");
await shareForReview({ projectPath: dir, title: basename(dir), client });
return status();
},
@@ -0,0 +1,61 @@
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({ enqueue: vi.fn() }));
vi.mock("../telemetry/transport.js", () => ({
enqueue: mocks.enqueue,
flush: vi.fn(),
flushSync: vi.fn(),
}));
vi.mock("../utils/env.js", () => ({ isDevMode: () => false }));
vi.mock("../telemetry/system.js", () => ({ getSystemMeta: () => ({}) }));
vi.mock("../telemetry/canary.js", () => ({ canaryEventProperties: () => ({}) }));
vi.mock("../telemetry/signedInUser.js", () => ({ signedInHeygenUsername: () => undefined }));
import { observeShareMutation, trackShareInteraction } from "./telemetry.js";
let folder: string;
function preference(enabled: boolean) {
writeFileSync(
join(folder, "config.json"),
JSON.stringify({ anonymousId: "test", bucketSeed: "test", telemetryEnabled: enabled }),
);
}
beforeEach(() => {
mocks.enqueue.mockClear();
folder = mkdtempSync(join(tmpdir(), "hf-share-opt-out-"));
vi.stubEnv("HYPERFRAMES_CONFIG_DIR", folder);
vi.stubEnv("HYPERFRAMES_NO_TELEMETRY", "");
vi.stubEnv("DO_NOT_TRACK", "");
preference(true);
});
afterEach(() => {
vi.unstubAllEnvs();
rmSync(folder, { recursive: true, force: true });
});
it("stops queueing events after a separate process changes the persisted preference", async () => {
trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio");
expect(mocks.enqueue).toHaveBeenCalledOnce();
preference(false);
mocks.enqueue.mockClear();
trackShareInteraction({ event: "share_link_copied", via: "copy" }, "local_studio");
await observeShareMutation("update", "local_studio", async (attempt) => {
attempt.authenticated();
attempt.complete(true, true);
});
expect(mocks.enqueue).not.toHaveBeenCalled();
});
it.each(["HYPERFRAMES_NO_TELEMETRY", "DO_NOT_TRACK"])(
"honors %s even after a previous event enabled the client cache",
async (name) => {
trackShareInteraction({ event: "share_opened", link: "none" });
expect(mocks.enqueue).toHaveBeenCalledOnce();
vi.stubEnv(name, "1");
mocks.enqueue.mockClear();
await observeShareMutation("share", "cli", async (attempt) => attempt.complete(true, true));
expect(mocks.enqueue).not.toHaveBeenCalled();
},
);
+49
View File
@@ -0,0 +1,49 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({ track: vi.fn(), fresh: vi.fn(), reset: vi.fn() }));
vi.mock("../telemetry/client.js", () => ({
trackEvent: mocks.track,
resetTelemetryPostureCache: mocks.reset,
}));
vi.mock("../telemetry/config.js", () => ({ readConfigFresh: mocks.fresh }));
import { observeShareMutation, trackShareInteraction } from "./telemetry.js";
beforeEach(() => vi.resetAllMocks());
describe("share telemetry privacy boundary", () => {
it("only forwards the declared interaction fields, never links or project data", () => {
const input = {
event: "share_link_copied" as const,
via: "copy" as const,
url: "https://private/token",
project: "/example/project",
};
trackShareInteraction(input, "local_studio");
expect(mocks.track).toHaveBeenCalledExactlyOnceWith("share_link_copied", {
client_surface: "local_studio",
via: "copy",
});
});
it("refreshes persisted opt-out posture at each event in a long-lived preview", () => {
trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio");
trackShareInteraction({ event: "share_link_copied", via: "publish" }, "local_studio");
expect(mocks.fresh).toHaveBeenCalledTimes(2);
expect(mocks.reset).toHaveBeenCalledTimes(2);
});
it("drops unknown failure reasons and never sends raw messages", async () => {
const error = Object.assign(new Error("secret email@example.com"), {
reason: "/secret/project",
});
await expect(
observeShareMutation("update", "cli", async () => {
throw error;
}),
).rejects.toBe(error);
expect(mocks.track.mock.lastCall?.[1]).toMatchObject({ reason: "other" });
expect(JSON.stringify(mocks.track.mock.calls)).not.toContain("secret");
});
it("telemetry configuration errors cannot block sharing or change its failure", async () => {
mocks.fresh.mockImplementation(() => {
throw new Error("EACCES");
});
expect(await observeShareMutation("share", "cli", async () => "done")).toBe("done");
expect(mocks.track).not.toHaveBeenCalled();
});
});
+96
View File
@@ -0,0 +1,96 @@
import { randomUUID } from "node:crypto";
import { AuthError } from "../auth/errors.js";
import { CliUsageError } from "../utils/commandResult.js";
import { readConfigFresh } from "../telemetry/config.js";
import { resetTelemetryPostureCache, trackEvent } from "../telemetry/client.js";
import type { ReviewExportProgress } from "@hyperframes/share";
export type ShareSurface = "cli" | "local_studio";
export type ShareInteraction =
| { event: "share_opened"; link: "none" | "live" | "changed" }
| { event: "share_link_copied"; via: "copy" | "publish" | "update" };
const REASONS = new Set([
"feature_unavailable",
"audience_required",
"workspace_cannot_share",
"workspace_mismatch",
"manage_existing_audience",
"review_project_limit_reached",
"review_subscription_required",
"review_entitlement_unavailable",
"review_public_consent_required",
"moderation_hold",
"review_operation_busy",
"not_shared",
"offline",
"signed_out",
]);
function failureReason(error: unknown): string {
if (error instanceof AuthError) return "authentication";
if (error instanceof CliUsageError && REASONS.has(error.code)) return error.code;
if (typeof error === "object" && error !== null && "reason" in error) {
const reason = error.reason;
if (typeof reason === "string" && REASONS.has(reason)) return reason;
}
return "other";
}
function emit(event: string, properties: Record<string, string | boolean>): void {
try {
// A preview process can outlive an opt-out made from another terminal.
readConfigFresh();
resetTelemetryPostureCache();
trackEvent(event, properties);
} catch {
// Telemetry must not alter whether a share succeeds or fails.
}
}
export function trackShareInteraction(input: ShareInteraction, surface: ShareSurface = "cli") {
if (input.event === "share_opened")
emit(input.event, { client_surface: surface, link: input.link });
else emit(input.event, { client_surface: surface, via: input.via });
}
function shareAttempt(action: "share" | "update", surface: ShareSurface) {
const base = { client_surface: surface, action, attempt_id: randomUUID() };
let admitted = false;
let recovery = false;
const track = (event: string, extra: Record<string, string | boolean> = {}) =>
emit(event, { ...base, recovery, ...extra });
const admit = () => {
if (admitted) return;
admitted = true;
track("share_mutation_admitted");
};
track("share_mutation_attempted");
return {
authenticated: () => track("share_mutation_authenticated"),
recover: (pending: boolean) => {
recovery = pending;
if (pending) track("share_recovery_attempted");
},
progress: (value: ReviewExportProgress | null) => {
if (value && value.step !== "preparing") admit();
},
retrieved: () => track("share_existing_link_returned"),
complete: (ready: boolean, added: boolean) => {
if (!added)
return track(ready ? "share_existing_link_returned" : "share_mutation_processing");
admit();
track("share_video_ready");
},
failed: (error: unknown) => track("share_mutation_failed", { reason: failureReason(error) }),
};
}
export type ShareAttempt = ReturnType<typeof shareAttempt>;
export async function observeShareMutation<T>(
action: "share" | "update",
surface: ShareSurface,
run: (attempt: ShareAttempt) => Promise<T>,
): Promise<T> {
const attempt = shareAttempt(action, surface);
try {
return await run(attempt);
} catch (error) {
attempt.failed(error);
throw error;
}
}