Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(web): renew expired signed URLs when native media chips reopen (#19300)

Tobias Wochingerb1e2305740d0
diff --git a/web/src/__tests__/server/external-media-storage-trpc.servertest.ts b/web/src/__tests__/server/external-media-storage-trpc.servertest.ts
index 81b1f14593..e0b1eaf5f7 100644
--- a/web/src/__tests__/server/external-media-storage-trpc.servertest.ts
+++ b/web/src/__tests__/server/external-media-storage-trpc.servertest.ts
@@ -288,7 +288,10 @@ describe("externalMediaStorage tRPC", () => {
projectId: project.id,
uri: `s3://${integration.bucketName}/customer/image.png`,
}),
- ).resolves.toMatchObject({ url: "https://signed.example" });
+ ).resolves.toMatchObject({
+ url: "https://signed.example",
+ urlTtlSeconds: 300,
+ });
expect(getSignedUrl).toHaveBeenCalledWith(
"customer/image.png",
300,
diff --git a/web/src/components/ui/LangfuseMediaView.clienttest.tsx b/web/src/components/ui/LangfuseMediaView.clienttest.tsx
index cc6a7d70dc..2d6931a490 100644
--- a/web/src/components/ui/LangfuseMediaView.clienttest.tsx
+++ b/web/src/components/ui/LangfuseMediaView.clienttest.tsx
@@ -18,7 +18,11 @@ vi.mock("@/src/utils/api", () => ({
}));
vi.mock("./media/useResolvedMedia", () => ({
- useResolvedMedia: () => ({ status: "idle", url: undefined }),
+ useResolvedMedia: () => ({
+ status: "idle",
+ url: undefined,
+ refreshIfNeeded: async () => undefined,
+ }),
}));
describe("LangfuseMediaView", () => {
diff --git a/web/src/components/ui/LangfuseMediaView.tsx b/web/src/components/ui/LangfuseMediaView.tsx
index f30f42a7d8..569602e90d 100644
--- a/web/src/components/ui/LangfuseMediaView.tsx
+++ b/web/src/components/ui/LangfuseMediaView.tsx
@@ -13,6 +13,7 @@ import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
import {
type MediaContentType,
type MediaReturnType,
+ mediaUrlQueryOptions,
} from "@/src/features/media";
import { MediaReferenceTag } from "@/src/components/ui/media/MediaReferenceTag";
import { MediaFileView } from "@/src/components/ui/media/MediaFileView";
@@ -99,11 +100,7 @@ export const LangfuseMediaView = ({
},
{
enabled: Boolean(projectId) && !isOversizedField,
- meta: { silentHttpCodes: [404] },
- refetchOnWindowFocus: false,
- refetchOnMount: false,
- refetchOnReconnect: false,
- staleTime: 55 * 60 * 1000, // 55 minutes, s3 links expire after 1 hour
+ ...mediaUrlQueryOptions,
},
);
diff --git a/web/src/components/ui/media/MediaReferenceTag.clienttest.tsx b/web/src/components/ui/media/MediaReferenceTag.clienttest.tsx
index ff8637e3be..33bf9b6c17 100644
--- a/web/src/components/ui/media/MediaReferenceTag.clienttest.tsx
+++ b/web/src/components/ui/media/MediaReferenceTag.clienttest.tsx
@@ -10,6 +10,7 @@ vi.mock("./useResolvedMedia", () => ({
status: "ready",
url: "data:text/plain,original%20oversized%20field",
contentLength: 2.5 * 1024 * 1024,
+ refreshIfNeeded: async () => undefined,
}),
}));
diff --git a/web/src/components/ui/media/MediaReferenceTag.tsx b/web/src/components/ui/media/MediaReferenceTag.tsx
index 52f2b90a05..b36092f1ae 100644
--- a/web/src/components/ui/media/MediaReferenceTag.tsx
+++ b/web/src/components/ui/media/MediaReferenceTag.tsx
@@ -1,5 +1,4 @@
/* eslint-disable @typescript-eslint/no-use-before-define */
-import { useState } from "react";
import { MediaTag, type MediaTagProps } from "../../MediaTag/MediaTag";
import { useResolvedMedia } from "./useResolvedMedia";
import { useResolvedExternalMedia } from "./useResolvedExternalMedia";
@@ -7,14 +6,16 @@ import { type MediaDescriptor } from "./mediaUtils";
import { OBSERVATION_FIELD_SIZE_LIMIT_MEDIA_SOURCE } from "@langfuse/shared";
import { useIsFeatureEnabled } from "@/src/features/feature-flags";
import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
+import { useMediaPeek } from "@/src/features/media";
type LangfuseRefDescriptor = Extract<MediaDescriptor, { kind: "langfuseRef" }>;
type S3Descriptor = Extract<MediaDescriptor, { kind: "s3" }>;
/**
* Container that connects a classified media value to the pure `MediaTag`: it
- * arms the lazy fetch the first time the peek opens (hover/focus) and keeps it
- * armed so re-hovers read from the query cache instead of re-fetching.
+ * arms the lazy fetch the first time the peek opens (hover/focus), serves
+ * re-hovers from the query cache, and renews the URL on an open once it nears
+ * expiry.
*/
export function MediaReferenceTag({
descriptor,
@@ -57,23 +58,13 @@ function S3MediaTag({
enableForAdmins: false,
projectId,
});
- const [armed, setArmed] = useState(false);
- const [open, setOpen] = useState(false);
+ const peek = useMediaPeek();
const { status, url, refreshIfNeeded } = useResolvedExternalMedia(
descriptor,
- {
- enabled: isFeatureEnabled && armed,
- },
+ { enabled: isFeatureEnabled && peek.armed },
);
- const handleOpenChange = (nextOpen: boolean) => {
- setOpen(nextOpen);
- if (!nextOpen) return;
-
- if (armed) {
- refreshIfNeeded().catch(() => undefined);
- }
- setArmed(true);
- };
+ const handleOpenChange = (open: boolean) =>
+ peek.onOpenChange(open, refreshIfNeeded);
if (!isFeatureEnabled) {
return (
@@ -94,7 +85,7 @@ function S3MediaTag({
status={status}
url={url}
errorDetail={descriptor.uri}
- open={open}
+ open={peek.open}
onOpenChange={handleOpenChange}
/>
);
@@ -107,17 +98,15 @@ function LangfuseRefMediaTag({
descriptor: LangfuseRefDescriptor;
size?: MediaTagProps["size"];
}) {
- const [armed, setArmed] = useState(false);
- const [open, setOpen] = useState(false);
- const { status, url, contentLength } = useResolvedMedia(descriptor, {
- enabled: armed,
- });
+ const peek = useMediaPeek();
+ const { status, url, contentLength, refreshIfNeeded } = useResolvedMedia(
+ descriptor,
+ { enabled: peek.armed },
+ );
+ const handleOpenChange = (open: boolean) =>
+ peek.onOpenChange(open, refreshIfNeeded);
const isOversizedField =
descriptor.source === OBSERVATION_FIELD_SIZE_LIMIT_MEDIA_SOURCE;
- const handleOpenChange = (nextOpen: boolean) => {
- setOpen(nextOpen);
- if (nextOpen) setArmed(true);
- };
return (
<MediaTag
@@ -134,7 +123,7 @@ function LangfuseRefMediaTag({
}
openActionLabel={isOversizedField ? "Open original" : undefined}
intent={isOversizedField ? "attachment" : undefined}
- open={open}
+ open={peek.open}
onOpenChange={handleOpenChange}
/>
);
diff --git a/web/src/components/ui/media/useResolvedExternalMedia.clienttest.ts b/web/src/components/ui/media/useResolvedExternalMedia.clienttest.ts
index be36cf389d..0772cc86e4 100644
--- a/web/src/components/ui/media/useResolvedExternalMedia.clienttest.ts
+++ b/web/src/components/ui/media/useResolvedExternalMedia.clienttest.ts
@@ -6,8 +6,9 @@ const { queryState, refetchMock } = vi.hoisted(() => ({
queryState: {
data: {
url: "https://signed.example.com/photo.jpeg",
- expiresAt: new Date("2026-10-09T14:05:00.000Z"),
+ urlTtlSeconds: 60,
},
+ dataUpdatedAt: new Date("2026-10-09T14:04:00.000Z").getTime(),
isError: false,
isFetching: false,
},
@@ -45,14 +46,25 @@ describe("useResolvedExternalMedia", () => {
vi.useRealTimers();
});
- it("refreshes a cached signed URL when it expires before the next open", async () => {
+ it("resolves as soon as it is enabled, for views without a peek", () => {
const { result } = renderHook(() =>
useResolvedExternalMedia(descriptor, { enabled: true }),
);
expect(result.current.status).toBe("ready");
+ expect(result.current.url).toBe(queryState.data.url);
+ });
+
+ it("refreshes a cached signed URL when it expires before the next open", async () => {
+ const { result, rerender } = renderHook(() =>
+ useResolvedExternalMedia(descriptor, { enabled: true }),
+ );
+ await act(result.current.refreshIfNeeded);
+ expect(refetchMock).not.toHaveBeenCalled();
vi.setSystemTime(new Date("2026-10-09T14:06:00.000Z"));
+ rerender();
+ expect(result.current.url).toBeUndefined();
await act(result.current.refreshIfNeeded);
expect(refetchMock).toHaveBeenCalledOnce();
diff --git a/web/src/components/ui/media/useResolvedExternalMedia.ts b/web/src/components/ui/media/useResolvedExternalMedia.ts
index 2733664b46..f6b5619639 100644
--- a/web/src/components/ui/media/useResolvedExternalMedia.ts
+++ b/web/src/components/ui/media/useResolvedExternalMedia.ts
@@ -1,18 +1,12 @@
-/* eslint-disable @typescript-eslint/no-use-before-define */
import { api } from "@/src/utils/api";
import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
-import { type MediaTagStatus } from "../../MediaTag/MediaTag";
+import { getSignedUrlState } from "@/src/features/media";
import { type MediaDescriptor } from "./mediaUtils";
export function useResolvedExternalMedia(
descriptor: S3MediaDescriptor,
{ enabled }: { enabled: boolean },
-): {
- status: MediaTagStatus;
- url?: string;
- contentLength?: number;
- refreshIfNeeded: () => Promise<void>;
-} {
+) {
const projectId = useProjectIdFromURL();
const query = api.media.resolveExternalMedia.useQuery(
{ projectId: projectId ?? "", uri: descriptor.uri },
@@ -26,36 +20,8 @@ export function useResolvedExternalMedia(
staleTime: 4 * 60 * 1000,
},
);
- const refreshIfNeeded = async () => {
- if (!query.isError && !isExpired(query.data?.expiresAt)) return;
- await query.refetch();
- };
- if (!enabled || !projectId) {
- return { status: "idle", refreshIfNeeded };
- }
- if (query.isError) {
- return { status: "error", refreshIfNeeded };
- }
- if (isExpired(query.data?.expiresAt)) {
- return {
- status: query.isFetching ? "loading" : "error",
- refreshIfNeeded,
- };
- }
- if (query.data?.url) {
- return {
- status: "ready",
- url: query.data.url,
- contentLength: query.data.contentLength,
- refreshIfNeeded,
- };
- }
- return { status: "loading", refreshIfNeeded };
-}
-
-function isExpired(expiresAt?: Date) {
- return expiresAt !== undefined && expiresAt.getTime() <= Date.now();
+ return getSignedUrlState(query, { enabled, projectId });
}
type S3MediaDescriptor = Extract<MediaDescriptor, { kind: "s3" }>;
diff --git a/web/src/components/ui/media/useResolvedMedia.clienttest.tsx b/web/src/components/ui/media/useResolvedMedia.clienttest.tsx
new file mode 100644
index 0000000000..2b38c448da
--- /dev/null
+++ b/web/src/components/ui/media/useResolvedMedia.clienttest.tsx
@@ -0,0 +1,199 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import {
+ QueryClient,
+ QueryClientProvider,
+ useQuery,
+ type UseQueryOptions,
+} from "@tanstack/react-query";
+import { type PropsWithChildren } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useResolvedMedia } from "./useResolvedMedia";
+import { useMediaPeek } from "@/src/features/media";
+import { type RouterOutputs } from "@/src/utils/api";
+
+type MediaResponse = RouterOutputs["media"]["getById"];
+
+const { getMedia } = vi.hoisted(() => ({
+ getMedia: vi.fn<() => Promise<MediaResponse>>(),
+}));
+
+vi.mock("@/src/hooks/useProjectIdFromURL", () => ({
+ default: () => "project-1",
+}));
+
+vi.mock("@/src/utils/api", () => ({
+ api: {
+ media: {
+ getById: {
+ useQuery: (
+ input: { projectId: string; mediaId: string },
+ options: Omit<UseQueryOptions<MediaResponse>, "queryKey" | "queryFn">,
+ ) =>
+ useQuery({
+ ...options,
+ queryKey: ["media.getById", input.projectId, input.mediaId],
+ queryFn: getMedia,
+ }),
+ },
+ },
+ },
+}));
+
+const descriptor = {
+ kind: "langfuseRef",
+ contentType: "application/pdf",
+ mediaId: "document-1",
+ source: "bytes",
+ referenceString:
+ "@@@langfuseMedia:type=application/pdf|id=document-1|source=bytes@@@",
+} as const;
+
+const queryKey = ["media.getById", "project-1", descriptor.mediaId];
+// Received at 09:00:00 (the fake clock below), valid for 60s.
+const cachedMedia: MediaResponse = {
+ mediaId: descriptor.mediaId,
+ contentType: descriptor.contentType,
+ url: "https://signed.example.com/document.pdf?signature=old",
+ urlExpiry: "2026-10-22T09:01:00.000Z",
+ urlTtlSeconds: 60,
+ contentLength: 1024,
+};
+const refreshedMedia: MediaResponse = {
+ ...cachedMedia,
+ url: "https://signed.example.com/document.pdf?signature=new",
+ urlExpiry: "2026-10-22T09:03:00.000Z",
+};
+
+describe("useResolvedMedia", () => {
+ let queryClient: QueryClient;
+
+ beforeEach(() => {
+ vi.useFakeTimers({ toFake: ["Date"] });
+ vi.setSystemTime(new Date("2026-10-22T09:00:00.000Z"));
+ getMedia.mockReset();
+ queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false, gcTime: Infinity } },
+ });
+ queryClient.setQueryData(queryKey, cachedMedia);
+ });
+
+ afterEach(() => {
+ queryClient.clear();
+ vi.useRealTimers();
+ });
+
+ const wrapper = ({ children }: PropsWithChildren) => (
+ <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+ );
+ // Wires the peek to the resolver the way `MediaReferenceTag` does.
+ const renderMediaHook = () =>
+ renderHook(
+ () => {
+ const peek = useMediaPeek();
+ const media = useResolvedMedia(descriptor, { enabled: peek.armed });
+ const onOpenChange = (open: boolean) =>
+ peek.onOpenChange(open, media.refreshIfNeeded);
+ return { ...media, open: peek.open, onOpenChange };
+ },
+ { wrapper },
+ );
+ const reopenAt = (
+ result: ReturnType<typeof renderMediaHook>["result"],
+ time: string,
+ ) => {
+ act(() => result.current.onOpenChange(false));
+ vi.setSystemTime(new Date(time));
+ act(() => result.current.onOpenChange(true));
+ };
+
+ it("fetches nothing until the peek first opens", async () => {
+ queryClient.removeQueries({ queryKey });
+ getMedia.mockResolvedValue(refreshedMedia);
+ const { result } = renderMediaHook();
+
+ expect(result.current.status).toBe("idle");
+ expect(getMedia).not.toHaveBeenCalled();
+
+ act(() => result.current.onOpenChange(true));
+ expect(result.current.open).toBe(true);
+ await waitFor(() => expect(result.current.status).toBe("ready"));
+ expect(result.current.url).toBe(refreshedMedia.url);
+ expect(getMedia).toHaveBeenCalledTimes(1);
+ });
+
+ it("reuses the URL early in its lifetime and renews it on reopen shortly before expiry", async () => {
+ getMedia.mockResolvedValue(refreshedMedia);
+ const { result } = renderMediaHook();
+
+ act(() => result.current.onOpenChange(true));
+ expect(result.current.url).toBe(cachedMedia.url);
+
+ reopenAt(result, "2026-10-22T09:00:30.000Z");
+ expect(result.current.url).toBe(cachedMedia.url);
+ expect(getMedia).not.toHaveBeenCalled();
+
+ reopenAt(result, "2026-10-22T09:00:50.000Z");
+ expect(result.current.url).toBeUndefined();
+ await waitFor(() => expect(result.current.url).toBe(refreshedMedia.url));
+ expect(result.current.status).toBe("ready");
+ expect(getMedia).toHaveBeenCalledTimes(1);
+ });
+
+ it("renews a URL that expired in the cache before the first open", async () => {
+ getMedia.mockResolvedValue(refreshedMedia);
+ vi.setSystemTime(new Date("2026-10-22T09:02:00.000Z"));
+ const { result } = renderMediaHook();
+
+ act(() => result.current.onOpenChange(true));
+ expect(result.current.url).toBeUndefined();
+ await waitFor(() => expect(result.current.url).toBe(refreshedMedia.url));
+ expect(getMedia).toHaveBeenCalledTimes(1);
+ });
+
+ it("measures the URL lifetime on the browser clock, even when it disagrees with the server", () => {
+ queryClient.setQueryData(queryKey, {
+ ...cachedMedia,
+ urlExpiry: "2026-10-22T07:01:00.000Z",
+ });
+ vi.setSystemTime(new Date("2026-10-22T09:00:10.000Z"));
+ const { result } = renderMediaHook();
+
+ act(() => result.current.onOpenChange(true));
+ expect(result.current.status).toBe("ready");
+ expect(result.current.url).toBe(cachedMedia.url);
+ expect(getMedia).not.toHaveBeenCalled();
+ });
+
+ it("hides the expired URL while renewing and shares one request across quick reopens", async () => {
+ const signing = Promise.withResolvers<MediaResponse>();
+ getMedia.mockReturnValue(signing.promise);
+ const { result } = renderMediaHook();
+ act(() => result.current.onOpenChange(true));
+
+ reopenAt(result, "2026-10-22T09:01:00.000Z");
+ reopenAt(result, "2026-10-22T09:01:01.000Z");
+ expect(result.current.status).toBe("loading");
+ expect(result.current.url).toBeUndefined();
+ expect(getMedia).toHaveBeenCalledTimes(1);
+
+ await act(async () => signing.resolve(refreshedMedia));
+ await waitFor(() => expect(result.current.url).toBe(refreshedMedia.url));
+ });
+
+ it("retries a failed fetch on the next open", async () => {
+ queryClient.removeQueries({ queryKey });
+ getMedia
+ .mockRejectedValueOnce(new Error("signing failed"))
+ .mockResolvedValue(refreshedMedia);
+ const { result } = renderMediaHook();
+
+ act(() => result.current.onOpenChange(true));
+ await waitFor(() => expect(result.current.status).toBe("error"));
+
+ reopenAt(result, "2026-10-22T09:00:05.000Z");
+ await waitFor(() => expect(result.current.status).toBe("ready"));
+ expect(result.current.url).toBe(refreshedMedia.url);
+ expect(getMedia).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/web/src/components/ui/media/useResolvedMedia.ts b/web/src/components/ui/media/useResolvedMedia.ts
index 82317ce876..6750136260 100644
--- a/web/src/components/ui/media/useResolvedMedia.ts
+++ b/web/src/components/ui/media/useResolvedMedia.ts
@@ -1,25 +1,22 @@
import { api } from "@/src/utils/api";
import useProjectIdFromURL from "@/src/hooks/useProjectIdFromURL";
+import { getSignedUrlState, mediaUrlQueryOptions } from "@/src/features/media";
import { type MediaDescriptor } from "./mediaUtils";
-import { type MediaTagStatus } from "../../MediaTag/MediaTag";
type LangfuseRefDescriptor = Extract<MediaDescriptor, { kind: "langfuseRef" }>;
/**
- * Resolves the previewable URL for a media descriptor.
+ * Resolves the previewable URL for a native media reference once `enabled`.
*
- * - Langfuse refs fetch a presigned S3 URL via tRPC, but only once `enabled`
- * flips true (the peek opens) — this is what keeps a JSON view with N media
- * leaves from firing N `getById` requests on render. Query config mirrors
- * `LangfuseMediaView` (55-min staleTime ≈ S3 link TTL), so re-hovers are
- * served from cache.
+ * Chips enable it when their peek first opens (`useMediaPeek`), so a JSON view
+ * with N media leaves does not fetch N URLs on render. Cached URLs are reused
+ * until shortly before they expire; `refreshIfNeeded` fetches a new one.
*/
export function useResolvedMedia(
descriptor: LangfuseRefDescriptor,
{ enabled }: { enabled: boolean },
-): { status: MediaTagStatus; url?: string; contentLength?: number } {
+) {
const projectId = useProjectIdFromURL();
-
const query = api.media.getById.useQuery(
{
mediaId: descriptor.mediaId,
@@ -27,21 +24,9 @@ export function useResolvedMedia(
},
{
enabled: enabled && Boolean(projectId),
- meta: { silentHttpCodes: [404] },
- refetchOnWindowFocus: false,
- refetchOnMount: false,
- refetchOnReconnect: false,
- staleTime: 55 * 60 * 1000, // S3 links expire after 1 hour
+ ...mediaUrlQueryOptions,
},
);
- if (!enabled || !projectId) return { status: "idle" };
- if (query.isError) return { status: "error" };
- if (query.data?.url)
- return {
- status: "ready",
- url: query.data.url,
- contentLength: query.data.contentLength,
- };
- return { status: "loading" };
+ return getSignedUrlState(query, { enabled, projectId });
}
diff --git a/web/src/features/external-media-storage/server/service.ts b/web/src/features/external-media-storage/server/service.ts
index ac2452a44c..a0934863ad 100644
--- a/web/src/features/external-media-storage/server/service.ts
+++ b/web/src/features/external-media-storage/server/service.ts
@@ -247,7 +247,7 @@ export function createExternalMediaStorageService(prisma: PrismaClient) {
return {
url,
contentLength,
- expiresAt: new Date(Date.now() + EXTERNAL_MEDIA_URL_TTL_SECONDS * 1000),
+ urlTtlSeconds: EXTERNAL_MEDIA_URL_TTL_SECONDS,
};
},
diff --git a/web/src/features/media/constants/mediaUrlQueryOptions.ts b/web/src/features/media/constants/mediaUrlQueryOptions.ts
new file mode 100644
index 0000000000..969d60468c
--- /dev/null
+++ b/web/src/features/media/constants/mediaUrlQueryOptions.ts
@@ -0,0 +1,12 @@
+/**
+ * Options every `media.getById` observer shares. Its observers read one cache
+ * entry, and React Query applies the options of whichever observer rendered
+ * last to it, so per-observer differences (retry, error toasts) would leak.
+ */
+export const mediaUrlQueryOptions = {
+ meta: { silentHttpCodes: [404] },
+ refetchOnWindowFocus: false,
+ refetchOnMount: false,
+ refetchOnReconnect: false,
+ staleTime: 55 * 60 * 1000,
+};
diff --git a/web/src/features/media/fns/getSignedUrlState.ts b/web/src/features/media/fns/getSignedUrlState.ts
new file mode 100644
index 0000000000..9e80f6b692
--- /dev/null
+++ b/web/src/features/media/fns/getSignedUrlState.ts
@@ -0,0 +1,65 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type MediaTagStatus } from "@/src/components/MediaTag/MediaTag";
+
+const RENEWAL_MARGIN_FRACTION = 0.25;
+const MAX_RENEWAL_MARGIN_MS = 30_000;
+
+/**
+ * Turns a signed-URL query into what a media view renders: the status, the URL
+ * while it is still usable, and `refreshIfNeeded`, which fetches a new URL only
+ * when the cached one is about to expire or the last fetch failed.
+ *
+ * Expiry is measured on the browser clock from `dataUpdatedAt` plus the
+ * server-reported lifetime, so server/browser clock skew cannot flip it. The
+ * early margin absorbs network latency and leaves time to click the link.
+ */
+export function getSignedUrlState(
+ query: SignedUrlQuery,
+ { enabled, projectId }: { enabled: boolean; projectId?: string | null },
+): {
+ status: MediaTagStatus;
+ url?: string;
+ contentLength?: number;
+ refreshIfNeeded: () => Promise<void>;
+} {
+ const isUnusable = () => {
+ if (query.isError) return true;
+ const urlTtlSeconds = query.data?.urlTtlSeconds;
+ if (urlTtlSeconds === undefined) return false;
+ const lifetime = urlTtlSeconds * 1000;
+ const margin = Math.min(
+ MAX_RENEWAL_MARGIN_MS,
+ lifetime * RENEWAL_MARGIN_FRACTION,
+ );
+ return query.dataUpdatedAt + lifetime - margin <= Date.now();
+ };
+ const refreshIfNeeded = async () => {
+ if (!projectId || !isUnusable()) return;
+ await query.refetch({ cancelRefetch: false });
+ };
+
+ if (!enabled || !projectId) return { status: "idle", refreshIfNeeded };
+ if (isUnusable()) {
+ return {
+ status: query.isFetching ? "loading" : "error",
+ refreshIfNeeded,
+ };
+ }
+ if (query.data?.url) {
+ return {
+ status: "ready",
+ url: query.data.url,
+ contentLength: query.data.contentLength,
+ refreshIfNeeded,
+ };
+ }
+ return { status: "loading", refreshIfNeeded };
+}
+
+type SignedUrlQuery = Pick<
+ UseQueryResult<
+ { url: string; contentLength?: number; urlTtlSeconds: number },
+ unknown
+ >,
+ "data" | "dataUpdatedAt" | "isError" | "isFetching" | "refetch"
+>;
diff --git a/web/src/features/media/hooks/useMediaPeek.ts b/web/src/features/media/hooks/useMediaPeek.ts
new file mode 100644
index 0000000000..0363840749
--- /dev/null
+++ b/web/src/features/media/hooks/useMediaPeek.ts
@@ -0,0 +1,24 @@
+import { useState } from "react";
+
+/**
+ * Open state of a media chip's peek. `armed` turns true on the first open and
+ * stays true, so the URL is fetched lazily once and re-hovers read the cache;
+ * every open also asks the resolver to renew an expiring or failed URL.
+ */
+export function useMediaPeek() {
+ const [armed, setArmed] = useState(false);
+ const [open, setOpen] = useState(false);
+
+ const onOpenChange = (
+ nextOpen: boolean,
+ refreshIfNeeded: () => Promise<void>,
+ ) => {
+ setOpen(nextOpen);
+ if (!nextOpen) return;
+
+ setArmed(true);
+ refreshIfNeeded().catch(() => undefined);
+ };
+
+ return { armed, open, onOpenChange };
+}
diff --git a/web/src/features/media/index.ts b/web/src/features/media/index.ts
index b1841cfb98..ab5d34d926 100644
--- a/web/src/features/media/index.ts
+++ b/web/src/features/media/index.ts
@@ -9,3 +9,6 @@ export {
MediaContentType,
type MediaReturnType,
} from "@/src/features/media/validation";
+export { getSignedUrlState } from "@/src/features/media/fns/getSignedUrlState";
+export { mediaUrlQueryOptions } from "@/src/features/media/constants/mediaUrlQueryOptions";
+export { useMediaPeek } from "@/src/features/media/hooks/useMediaPeek";
diff --git a/web/src/features/traces/components/AdvancedJsonViewer/components/MediaButtonGroup.tsx b/web/src/features/traces/components/AdvancedJsonViewer/components/MediaButtonGroup.tsx
index 0606ef8c90..dd20fd74ff 100644
--- a/web/src/features/traces/components/AdvancedJsonViewer/components/MediaButtonGroup.tsx
+++ b/web/src/features/traces/components/AdvancedJsonViewer/components/MediaButtonGroup.tsx
@@ -1,6 +1,9 @@
/* eslint-disable @repo/no-null-render */
import { useMemo, useState, useRef } from "react";
-import { type MediaReturnType } from "@/src/features/media";
+import {
+ mediaUrlQueryOptions,
+ type MediaReturnType,
+} from "@/src/features/media";
import { File, Image as ImageIcon, Volume2, Video } from "@langfuse/icons";
import { LangfuseMediaView } from "@/src/components/ui/LangfuseMediaView";
import {
@@ -90,11 +93,7 @@ function MediaPreview({ mediaItem }: { mediaItem: MediaReturnType }) {
},
{
enabled: Boolean(projectId),
- meta: { silentHttpCodes: [404] },
- refetchOnWindowFocus: false,
- refetchOnMount: false,
- refetchOnReconnect: false,
- staleTime: 55 * 60 * 1000, // 55 minutes, s3 links expire after 1 hour
+ ...mediaUrlQueryOptions,
},
);
diff --git a/web/src/features/traces/components/IOPreview/components/ChatMessage.clienttest.tsx b/web/src/features/traces/components/IOPreview/components/ChatMessage.clienttest.tsx
index 12da928e29..9d7f02697e 100644
--- a/web/src/features/traces/components/IOPreview/components/ChatMessage.clienttest.tsx
+++ b/web/src/features/traces/components/IOPreview/components/ChatMessage.clienttest.tsx
@@ -12,7 +12,11 @@ vi.mock("@/src/utils/clipboard", () => ({ copyTextToClipboard }));
// path's media tag resolves too — stub its project/URL lookups.
vi.mock("@/src/hooks/useProjectIdFromURL", () => ({ default: () => "p1" }));
vi.mock("@/src/components/ui/media/useResolvedMedia", () => ({
- useResolvedMedia: () => ({ status: "idle", url: undefined }),
+ useResolvedMedia: () => ({
+ status: "idle",
+ url: undefined,
+ refreshIfNeeded: async () => undefined,
+ }),
}));
// Stands in for the real media renderer (it needs a session + signed-URL
diff --git a/web/src/server/api/routers/media.ts b/web/src/server/api/routers/media.ts
index 8d2f2ff580..4b30ee2279 100644
--- a/web/src/server/api/routers/media.ts
+++ b/web/src/server/api/routers/media.ts
@@ -94,6 +94,7 @@ export const mediaRouter = createTRPCRouter({
contentLength: Number(media.contentLength),
url,
urlExpiry,
+ urlTtlSeconds: ttlSeconds,
};
}),
getByTraceOrObservationId: protectedProjectProcedure