feat(session): add recording and replay (#1049)

src/ui/api/session-log-api.ts

@@ -11,6 +11,9 @@ export type SessionLogRecord = {
   hostName: string | null;
   hostIp: string | null;
   sizeBytes: number | null;
+  protocol: "ssh" | "rdp" | "vnc" | "telnet";
+  format: "text" | "asciicast" | "guacamole";
+  username: string | null;
 };
 
 export async function getSessionLogs(): Promise<SessionLogRecord[]> {
@@ -22,6 +25,36 @@ export async function getSessionLogs(): Promise<SessionLogRecord[]> {
   }
 }
 
+export async function getSessionLogBlob(id: number): Promise<Blob> {
+  try {
+    const response = await authApi.get(`/session_logs/${id}/content`, {
+      responseType: "blob",
+    });
+    return response.data;
+  } catch (error) {
+    throw handleApiError(error, "fetch session recording");
+  }
+}
+
+export async function getSessionRecordingRetention(): Promise<number> {
+  try {
+    const response = await authApi.get("/session_logs/retention");
+    return response.data.retentionDays;
+  } catch (error) {
+    throw handleApiError(error, "fetch session recording retention");
+  }
+}
+
+export async function setSessionRecordingRetention(
+  retentionDays: number,
+): Promise<void> {
+  try {
+    await authApi.put("/session_logs/retention", { retentionDays });
+  } catch (error) {
+    throw handleApiError(error, "update session recording retention");
+  }
+}
+
 export async function getSessionLogContent(id: number): Promise<string> {
   try {
     const response = await authApi.get(`/session_logs/${id}/content`, {

src/ui/features/session-recording/SessionRecordingPlayer.tsx

@@ -0,0 +1,293 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Pause, Play } from "lucide-react";
+import { Terminal } from "@xterm/xterm";
+import { FitAddon } from "@xterm/addon-fit";
+import Guacamole from "guacamole-common-js";
+import type { SessionLogRecord } from "@/api/session-log-api";
+import { parseAsciicast, type Asciicast } from "./asciicast";
+import "@xterm/xterm/css/xterm.css";
+
+const SPEEDS = [0.5, 1, 2, 4];
+
+function formatPosition(seconds: number) {
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`;
+}
+
+function PlaybackControls({
+  playing,
+  position,
+  duration,
+  speed,
+  onToggle,
+  onSeek,
+  onSpeed,
+}: {
+  playing: boolean;
+  position: number;
+  duration: number;
+  speed: number;
+  onToggle: () => void;
+  onSeek: (position: number) => void;
+  onSpeed: (speed: number) => void;
+}) {
+  return (
+    <div className="flex items-center gap-2 border-t border-border/60 bg-muted/20 px-3 py-2">
+      <button
+        type="button"
+        onClick={onToggle}
+        className="flex size-7 items-center justify-center hover:bg-muted"
+        aria-label={playing ? "Pause recording" : "Play recording"}
+      >
+        {playing ? (
+          <Pause className="size-3.5" />
+        ) : (
+          <Play className="size-3.5" />
+        )}
+      </button>
+      <span className="w-10 text-[10px] tabular-nums text-muted-foreground">
+        {formatPosition(position)}
+      </span>
+      <input
+        type="range"
+        min={0}
+        max={Math.max(duration, 0.01)}
+        step={0.01}
+        value={Math.min(position, duration)}
+        onChange={(event) => onSeek(Number(event.target.value))}
+        className="min-w-0 flex-1 accent-primary"
+        aria-label="Recording timeline"
+      />
+      <span className="w-10 text-right text-[10px] tabular-nums text-muted-foreground">
+        {formatPosition(duration)}
+      </span>
+      <select
+        value={speed}
+        onChange={(event) => onSpeed(Number(event.target.value))}
+        className="h-7 border border-border bg-background px-1 text-[10px]"
+        aria-label="Playback speed"
+      >
+        {SPEEDS.map((value) => (
+          <option key={value} value={value}>
+            {value}×
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+
+function AsciicastPlayer({ blob }: { blob: Blob }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const terminalRef = useRef<Terminal | null>(null);
+  const recordingRef = useRef<Asciicast | null>(null);
+  const positionRef = useRef(0);
+  const eventIndexRef = useRef(0);
+  const [position, setPosition] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [speed, setSpeed] = useState(1);
+  const [playing, setPlaying] = useState(false);
+  const [error, setError] = useState("");
+
+  const renderAt = useCallback((nextPosition: number) => {
+    const terminal = terminalRef.current;
+    const recording = recordingRef.current;
+    if (!terminal || !recording) return;
+    if (nextPosition < positionRef.current) {
+      terminal.reset();
+      terminal.resize(recording.width, recording.height);
+      eventIndexRef.current = 0;
+    }
+    while (eventIndexRef.current < recording.events.length) {
+      const [time, type, data] = recording.events[eventIndexRef.current];
+      if (time > nextPosition) break;
+      if (type === "o") terminal.write(data);
+      if (type === "r") {
+        const [cols, rows] = data.split("x").map(Number);
+        if (cols > 0 && rows > 0) terminal.resize(cols, rows);
+      }
+      eventIndexRef.current++;
+    }
+    positionRef.current = nextPosition;
+    setPosition(nextPosition);
+  }, []);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const terminal = new Terminal({
+      cursorBlink: false,
+      disableStdin: true,
+      convertEol: false,
+      fontSize: 12,
+      theme: { background: "#09090b" },
+    });
+    const fitAddon = new FitAddon();
+    terminal.loadAddon(fitAddon);
+    terminal.open(containerRef.current);
+    terminalRef.current = terminal;
+    const observer = new ResizeObserver(() => fitAddon.fit());
+    observer.observe(containerRef.current);
+    fitAddon.fit();
+
+    blob
+      .text()
+      .then((source) => {
+        const recording = parseAsciicast(source);
+        recordingRef.current = recording;
+        setDuration(recording.duration);
+        terminal.resize(recording.width, recording.height);
+        renderAt(0);
+      })
+      .catch((reason) =>
+        setError(reason instanceof Error ? reason.message : String(reason)),
+      );
+
+    return () => {
+      observer.disconnect();
+      terminal.dispose();
+      terminalRef.current = null;
+    };
+  }, [blob, renderAt]);
+
+  useEffect(() => {
+    if (!playing || !recordingRef.current) return;
+    let frame = 0;
+    let previous = performance.now();
+    const tick = (now: number) => {
+      const next = Math.min(
+        duration,
+        positionRef.current + ((now - previous) / 1000) * speed,
+      );
+      previous = now;
+      renderAt(next);
+      if (next >= duration) setPlaying(false);
+      else frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [duration, playing, renderAt, speed]);
+
+  if (error) return <div className="p-4 text-xs text-destructive">{error}</div>;
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <div ref={containerRef} className="min-h-0 flex-1 bg-[#09090b] p-2" />
+      <PlaybackControls
+        playing={playing}
+        position={position}
+        duration={duration}
+        speed={speed}
+        onToggle={() => {
+          if (!playing && position >= duration) renderAt(0);
+          setPlaying((value) => !value);
+        }}
+        onSeek={renderAt}
+        onSpeed={setSpeed}
+      />
+    </div>
+  );
+}
+
+function GuacamolePlayer({ blob }: { blob: Blob }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const recordingRef = useRef<Guacamole.SessionRecording | null>(null);
+  const positionRef = useRef(0);
+  const [position, setPosition] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [speed, setSpeed] = useState(1);
+  const [playing, setPlaying] = useState(false);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const recording = new Guacamole.SessionRecording(blob, 100);
+    recordingRef.current = recording;
+    const display = recording.getDisplay();
+    const element = display.getElement();
+    containerRef.current.replaceChildren(element);
+    const fit = () => {
+      const width = display.getWidth();
+      if (width && containerRef.current) {
+        display.scale(containerRef.current.clientWidth / width);
+      }
+    };
+    const observer = new ResizeObserver(fit);
+    observer.observe(containerRef.current);
+    recording.onload = () => {
+      setDuration(recording.getDuration() / 1000);
+      fit();
+    };
+    recording.onprogress = (nextDuration) => setDuration(nextDuration / 1000);
+    recording.onseek = (nextPosition) => {
+      positionRef.current = nextPosition / 1000;
+      setPosition(positionRef.current);
+    };
+    recording.onerror = setError;
+
+    return () => {
+      observer.disconnect();
+      recording.abort();
+      recordingRef.current = null;
+    };
+  }, [blob]);
+
+  useEffect(() => {
+    const recording = recordingRef.current;
+    if (!recording || !playing) return;
+    recording.pause();
+    let previous = performance.now();
+    let nextPosition = positionRef.current;
+    const interval = window.setInterval(() => {
+      const now = performance.now();
+      nextPosition = Math.min(
+        duration,
+        nextPosition + ((now - previous) / 1000) * speed,
+      );
+      previous = now;
+      recording.seek(nextPosition * 1000);
+      if (nextPosition >= duration) setPlaying(false);
+    }, 100);
+    return () => clearInterval(interval);
+  }, [duration, playing, speed]);
+
+  if (error) return <div className="p-4 text-xs text-destructive">{error}</div>;
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <div
+        ref={containerRef}
+        className="min-h-0 flex-1 overflow-hidden bg-black"
+      />
+      <PlaybackControls
+        playing={playing}
+        position={position}
+        duration={duration}
+        speed={speed}
+        onToggle={() => {
+          const recording = recordingRef.current;
+          if (!recording) return;
+          if (!playing && position >= duration) recording.seek(0);
+          setPlaying((value) => !value);
+        }}
+        onSeek={(nextPosition) => {
+          recordingRef.current?.seek(nextPosition * 1000);
+          positionRef.current = nextPosition;
+          setPosition(nextPosition);
+        }}
+        onSpeed={setSpeed}
+      />
+    </div>
+  );
+}
+
+export function SessionRecordingPlayer({
+  log,
+  blob,
+}: {
+  log: SessionLogRecord;
+  blob: Blob;
+}) {
+  return log.format === "guacamole" ? (
+    <GuacamolePlayer blob={blob} />
+  ) : (
+    <AsciicastPlayer blob={blob} />
+  );
+}

src/ui/features/session-recording/asciicast.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { parseAsciicast } from "./asciicast";
+
+describe("parseAsciicast", () => {
+  it("parses terminal dimensions and timed input/output", () => {
+    const recording = parseAsciicast(
+      '{"version":2,"width":120,"height":30}\n[0.1,"o","hello"]\n[1.5,"i","ls\\r"]\n[2,"r","100x40"]\n',
+    );
+    expect(recording.width).toBe(120);
+    expect(recording.height).toBe(30);
+    expect(recording.duration).toBe(2);
+    expect(recording.events).toHaveLength(3);
+  });
+
+  it("rejects unsupported recording versions", () => {
+    expect(() => parseAsciicast('{"version":1}\n')).toThrow(
+      "Unsupported asciicast version",
+    );
+  });
+});

src/ui/features/session-recording/asciicast.ts

@@ -0,0 +1,39 @@
+export type AsciicastEvent = [
+  time: number,
+  type: "i" | "o" | "r",
+  data: string,
+];
+
+export type Asciicast = {
+  width: number;
+  height: number;
+  duration: number;
+  events: AsciicastEvent[];
+};
+
+export function parseAsciicast(source: string): Asciicast {
+  const lines = source.trim().split("\n");
+  const header = JSON.parse(lines.shift() || "{}") as {
+    version?: number;
+    width?: number;
+    height?: number;
+  };
+  if (header.version !== 2) throw new Error("Unsupported asciicast version");
+
+  const events = lines
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as AsciicastEvent)
+    .filter(
+      ([time, type, data]) =>
+        Number.isFinite(time) &&
+        (type === "i" || type === "o" || type === "r") &&
+        typeof data === "string",
+    );
+
+  return {
+    width: header.width || 80,
+    height: header.height || 24,
+    duration: events.at(-1)?.[0] || 0,
+    events,
+  };
+}

src/ui/sidebar/SessionLogsPanel.tsx

@@ -15,6 +15,7 @@ import {
   Download,
   Eye,
   Loader2,
+  Save,
   ScrollText,
   Search,
   X,
@@ -23,9 +24,13 @@ import { toast } from "sonner";
 import {
   getSessionLogs,
   getSessionLogContent,
+  getSessionLogBlob,
+  getSessionRecordingRetention,
+  setSessionRecordingRetention,
   deleteSessionLog,
   type SessionLogRecord,
 } from "@/api/session-log-api";
+import { SessionRecordingPlayer } from "@/features/session-recording/SessionRecordingPlayer";
 
 function formatDuration(seconds: number | null): string {
   if (seconds == null) return "--";
@@ -63,7 +68,13 @@ function buildFilename(log: SessionLogRecord): string {
   const h = String(d.getHours()).padStart(2, "0");
   const min = String(d.getMinutes()).padStart(2, "0");
   const s = String(d.getSeconds()).padStart(2, "0");
-  return `${host}_${y}-${m}-${day}_${h}-${min}-${s}.log`;
+  const extension =
+    log.format === "guacamole"
+      ? "guac"
+      : log.format === "asciicast"
+        ? "cast"
+        : "log";
+  return `${host}_${y}-${m}-${day}_${h}-${min}-${s}.${extension}`;
 }
 
 function SectionHeader({ label, count }: { label: string; count: number }) {
@@ -105,6 +116,9 @@ function LogRow({
         <span className="text-[10px] text-muted-foreground/60 truncate">
           {formatDate(log.startedAt)}
           {" · "}
+          {log.protocol.toUpperCase()}
+          {log.username ? ` · ${log.username}` : ""}
+          {" · "}
           {formatDuration(log.duration)}
           {" · "}
           {formatBytes(log.sizeBytes)}
@@ -159,12 +173,15 @@ export function SessionLogsPanel() {
   const [filter, setFilter] = useState("");
   const [viewLog, setViewLog] = useState<SessionLogRecord | null>(null);
   const [viewContent, setViewContent] = useState<string>("");
+  const [viewBlob, setViewBlob] = useState<Blob | null>(null);
   const [viewLoading, setViewLoading] = useState(false);
   const [deleteTarget, setDeleteTarget] = useState<SessionLogRecord | null>(
     null,
   );
   const [deleting, setDeleting] = useState(false);
   const [copied, setCopied] = useState(false);
+  const [retentionDays, setRetentionDays] = useState<number | null>(null);
+  const [savingRetention, setSavingRetention] = useState(false);
 
   const load = useCallback(
     (initial = false) => {
@@ -192,6 +209,9 @@ export function SessionLogsPanel() {
 
   useEffect(() => {
     load(true);
+    getSessionRecordingRetention()
+      .then(setRetentionDays)
+      .catch(() => setRetentionDays(null));
     const interval = setInterval(() => load(false), 5000);
     return () => clearInterval(interval);
   }, [load]);
@@ -199,17 +219,23 @@ export function SessionLogsPanel() {
   const q = filter.trim().toLowerCase();
   const filtered = q
     ? logs.filter((l) =>
-        (l.hostName ?? l.hostIp ?? "").toLowerCase().includes(q),
+        `${l.hostName ?? ""} ${l.hostIp ?? ""} ${l.username ?? ""} ${l.protocol}`
+          .toLowerCase()
+          .includes(q),
       )
     : logs;
 
   const handleView = async (log: SessionLogRecord) => {
     setViewLog(log);
     setViewContent("");
+    setViewBlob(null);
     setViewLoading(true);
     try {
-      const content = await getSessionLogContent(log.id);
-      setViewContent(content);
+      if (log.format === "text") {
+        setViewContent(await getSessionLogContent(log.id));
+      } else {
+        setViewBlob(await getSessionLogBlob(log.id));
+      }
     } catch {
       toast.error(t("sessionLogs.loadError"));
     } finally {
@@ -219,8 +245,7 @@ export function SessionLogsPanel() {
 
   const handleDownload = async (log: SessionLogRecord) => {
     try {
-      const content = await getSessionLogContent(log.id);
-      const blob = new Blob([content], { type: "text/plain" });
+      const blob = await getSessionLogBlob(log.id);
       const url = URL.createObjectURL(blob);
       const a = document.createElement("a");
       a.href = url;
@@ -285,6 +310,7 @@ export function SessionLogsPanel() {
             </span>
             <span className="text-[10px] text-muted-foreground/50">
               {formatDate(viewLog.startedAt)}
+              {` · ${viewLog.protocol.toUpperCase()}`}
               {viewLog.duration != null
                 ? ` · ${formatDuration(viewLog.duration)}`
                 : ""}
@@ -294,25 +320,27 @@ export function SessionLogsPanel() {
           </div>
           <TooltipProvider>
             <div className="flex items-center gap-0.5 shrink-0">
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <button
-                    onClick={handleCopy}
-                    className="size-6 flex items-center justify-center text-muted-foreground/50 hover:text-foreground hover:bg-muted/60 transition-colors"
-                  >
-                    {copied ? (
-                      <Check className="size-3 text-green-500" />
-                    ) : (
-                      <Copy className="size-3" />
-                    )}
-                  </button>
-                </TooltipTrigger>
-                <TooltipContent side="left">
-                  {copied
-                    ? t("sessionLogs.copied")
-                    : t("sessionLogs.copyContent")}
-                </TooltipContent>
-              </Tooltip>
+              {viewLog.format === "text" && (
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <button
+                      onClick={handleCopy}
+                      className="size-6 flex items-center justify-center text-muted-foreground/50 hover:text-foreground hover:bg-muted/60 transition-colors"
+                    >
+                      {copied ? (
+                        <Check className="size-3 text-green-500" />
+                      ) : (
+                        <Copy className="size-3" />
+                      )}
+                    </button>
+                  </TooltipTrigger>
+                  <TooltipContent side="left">
+                    {copied
+                      ? t("sessionLogs.copied")
+                      : t("sessionLogs.copyContent")}
+                  </TooltipContent>
+                </Tooltip>
+              )}
               <Tooltip>
                 <TooltipTrigger asChild>
                   <button
@@ -336,6 +364,8 @@ export function SessionLogsPanel() {
             <div className="flex items-center justify-center py-16">
               <Loader2 className="size-4 animate-spin text-muted-foreground" />
             </div>
+          ) : viewBlob ? (
+            <SessionRecordingPlayer log={viewLog} blob={viewBlob} />
           ) : (
             <pre className="p-3 text-[11px] font-mono whitespace-pre-wrap break-all text-foreground/80 leading-relaxed">
               {viewContent || "(empty)"}
@@ -349,6 +379,44 @@ export function SessionLogsPanel() {
   return (
     <div className="flex flex-col flex-1 min-h-0">
       <div className="flex-1 overflow-y-auto">
+        {retentionDays != null && (
+          <div className="flex items-center gap-2 border-b border-border/60 px-3 py-2 text-[10px] text-muted-foreground">
+            <span className="flex-1">Recording retention</span>
+            <Input
+              type="number"
+              min={1}
+              max={3650}
+              value={retentionDays}
+              onChange={(event) => setRetentionDays(Number(event.target.value))}
+              className="h-7 w-20 text-xs"
+              aria-label="Recording retention days"
+            />
+            <span>days</span>
+            <button
+              type="button"
+              disabled={savingRetention}
+              onClick={async () => {
+                setSavingRetention(true);
+                try {
+                  await setSessionRecordingRetention(retentionDays);
+                  toast.success("Recording retention updated");
+                } catch {
+                  toast.error("Failed to update recording retention");
+                } finally {
+                  setSavingRetention(false);
+                }
+              }}
+              className="flex size-7 items-center justify-center hover:bg-muted disabled:opacity-50"
+              aria-label="Save recording retention"
+            >
+              {savingRetention ? (
+                <Loader2 className="size-3 animate-spin" />
+              ) : (
+                <Save className="size-3" />
+              )}
+            </button>
+          </div>
+        )}
         {logs.length === 0 ? (
           <div className="flex flex-col items-center justify-center flex-1 gap-3 p-6 text-center py-16">
             <div className="size-10 bg-muted/40 flex items-center justify-center">