Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: capture output filenames collide within the same second, silently overwriting earlier images (PIN-050)

Luigi Agostia5157dcd9002
diff --git a/internal/handlers/binary_export.go b/internal/handlers/binary_export.go
index 1091d4f1..4f6af958 100644
--- a/internal/handlers/binary_export.go
+++ b/internal/handlers/binary_export.go
@@ -34,18 +34,81 @@ func writeRawImage(w http.ResponseWriter, buf []byte, contentType, logLabel stri
}
}
+// maxUniqueNameAttempts bounds the suffix search. A directory holding this many
+// files named for the same second is a runaway caller, not a collision to resolve.
+const maxUniqueNameAttempts = 512
+
+// createUniqueFile reserves a path under dir by CREATING it exclusively, bumping a
+// numeric suffix until the create succeeds: base+ext, then base-1+ext, base-2+ext…
+// It returns the open handle, so the name cannot be taken between the check and the
+// write — which is the whole point, and why this is not a stat-then-write.
+//
+// Every server-side auto-naming writer goes through here. They all built a name from a
+// SECOND-resolution timestamp and then wrote it unconditionally, so two outputs in the
+// same second landed on one path: the first file was destroyed while its response still
+// reported that path, its byte count and its clip rect. Widening the timestamp only
+// shrinks the window — two concurrent requests can share a millisecond — so the
+// guarantee has to come from the create call itself.
+//
+// The caller owns the base name, including its timestamp format, so this closes the
+// collision without renaming anything a user might already be globbing for.
+func createUniqueFile(dir, base, ext string) (*os.File, string, error) {
+ for attempt := 0; attempt < maxUniqueNameAttempts; attempt++ {
+ name := base + ext
+ if attempt > 0 {
+ name = fmt.Sprintf("%s-%d%s", base, attempt, ext)
+ }
+ path := filepath.Join(dir, name)
+ f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0600)
+ if err == nil {
+ return f, path, nil
+ }
+ if !os.IsExist(err) {
+ return nil, "", err
+ }
+ }
+ return nil, "", fmt.Errorf("could not find a free name for %s%s in %s after %d attempts", base, ext, dir, maxUniqueNameAttempts)
+}
+
+// writeUniqueFile creates a fresh file under dir and writes buf to it, returning the
+// path actually used — which may carry a suffix the caller did not ask for.
+func writeUniqueFile(dir, base, ext string, buf []byte) (string, error) {
+ f, path, err := createUniqueFile(dir, base, ext)
+ if err != nil {
+ return "", err
+ }
+ if _, err := f.Write(buf); err != nil {
+ _ = f.Close()
+ return "", err
+ }
+ if err := f.Close(); err != nil {
+ return "", err
+ }
+ return path, nil
+}
+
+// exportTimestamp is the second-resolution stamp every auto-named export shares. It is
+// no longer load-bearing for uniqueness — createUniqueFile is — so it stays at second
+// granularity to keep filenames readable.
+func exportTimestamp() string {
+ return time.Now().Format("20060102-150405")
+}
+
// saveBinaryToStateDir writes buf to StateDir/<subdir>/<prefix>-<ts><ext> using
// the standard binary-export modes (dir 0750, file 0600) and returns the path
// and timestamp. This is the single persistence policy shared by the PDF,
// screenshot, and capture handlers' default-location output.
+//
+// The returned path is authoritative: on a same-second collision it carries a suffix,
+// so callers must report this value rather than rebuilding the name from the timestamp.
func saveBinaryToStateDir(stateDir, subdir, prefix, ext string, buf []byte) (filePath, timestamp string, err error) {
dir := filepath.Join(stateDir, subdir)
if err := os.MkdirAll(dir, 0750); err != nil {
return "", "", err
}
- timestamp = time.Now().Format("20060102-150405")
- filePath = filepath.Join(dir, fmt.Sprintf("%s-%s%s", prefix, timestamp, ext))
- if err := os.WriteFile(filePath, buf, 0600); err != nil {
+ timestamp = exportTimestamp()
+ filePath, err = writeUniqueFile(dir, prefix+"-"+timestamp, ext, buf)
+ if err != nil {
return "", "", err
}
return filePath, timestamp, nil
diff --git a/internal/handlers/binary_export_test.go b/internal/handlers/binary_export_test.go
new file mode 100644
index 00000000..49bb9d00
--- /dev/null
+++ b/internal/handlers/binary_export_test.go
@@ -0,0 +1,285 @@
+package handlers
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/bridge/observe"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+// Two saves in immediate succession must land on different paths with both files intact.
+// The name came from a second-resolution timestamp and was written with no existence
+// check, so the first file was destroyed while its response still reported that path,
+// its byte count and its clip rect.
+func TestSavingTwiceBackToBackKeepsBothFiles(t *testing.T) {
+ stateDir := t.TempDir()
+
+ first := []byte("first capture bytes, deliberately longer than the second")
+ second := []byte("second")
+
+ firstPath, _, err := saveBinaryToStateDir(stateDir, "captures", "cap", ".png", first)
+ if err != nil {
+ t.Fatal(err)
+ }
+ secondPath, _, err := saveBinaryToStateDir(stateDir, "captures", "cap", ".png", second)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if firstPath == secondPath {
+ t.Fatalf("both saves returned %q; the second overwrote the first", firstPath)
+ }
+ // Each reported path must hold its OWN bytes: a distinct path is worthless if the
+ // content moved.
+ assertFileHolds(t, firstPath, first)
+ assertFileHolds(t, secondPath, second)
+}
+
+// Issued concurrently, not serially: a serial two-call test passes on a millisecond
+// timestamp while concurrent requests still collide, which is why the guarantee has to
+// come from an exclusive create rather than from more precision.
+func TestConcurrentSavesProduceDistinctFiles(t *testing.T) {
+ const n = 8
+ stateDir := t.TempDir()
+
+ paths := make([]string, n)
+ contents := make([][]byte, n)
+ errs := make([]error, n)
+
+ var start sync.WaitGroup
+ var done sync.WaitGroup
+ start.Add(1)
+ for i := 0; i < n; i++ {
+ // Distinct lengths so a file holding the wrong capture is detectable by size
+ // alone, which is the mismatch the card measured.
+ contents[i] = []byte(fmt.Sprintf("capture-%d%s", i, string(make([]byte, i))))
+ done.Add(1)
+ go func(i int) {
+ defer done.Done()
+ start.Wait()
+ paths[i], _, errs[i] = saveBinaryToStateDir(stateDir, "captures", "cap", ".png", contents[i])
+ }(i)
+ }
+ start.Done()
+ done.Wait()
+
+ seen := map[string]int{}
+ for i := 0; i < n; i++ {
+ if errs[i] != nil {
+ t.Fatalf("save %d: %v", i, errs[i])
+ }
+ if prev, dup := seen[paths[i]]; dup {
+ t.Errorf("saves %d and %d both returned %q", prev, i, paths[i])
+ }
+ seen[paths[i]] = i
+ assertFileHolds(t, paths[i], contents[i])
+ }
+ if len(seen) != n {
+ t.Errorf("%d distinct paths for %d concurrent saves", len(seen), n)
+ }
+
+ entries, err := os.ReadDir(filepath.Join(stateDir, "captures"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(entries) != n {
+ t.Errorf("%d files on disk for %d concurrent saves; a save was lost", len(entries), n)
+ }
+}
+
+// The reported size must match the file at that path — the mismatch a caller storing the
+// returned paths would otherwise hit.
+func assertFileHolds(t *testing.T, path string, want []byte) {
+ t.Helper()
+ got, err := os.ReadFile(path) // #nosec G304 -- path produced by the code under test.
+ if err != nil {
+ t.Fatalf("read %s: %v", path, err)
+ }
+ if len(got) != len(want) {
+ t.Errorf("%s holds %d bytes, want %d — the reported size describes a file that was replaced", path, len(got), len(want))
+ }
+ if string(got) != string(want) {
+ t.Errorf("%s holds another save's content", path)
+ }
+}
+
+// The suffix ladder is bounded, and running out is an error rather than a silent
+// overwrite: a directory with this many same-second names is a runaway caller.
+func TestCreateUniqueFileRefusesRatherThanOverwriteWhenTheLadderIsExhausted(t *testing.T) {
+ dir := t.TempDir()
+ base, ext := "cap-fixed", ".png"
+
+ occupy := func(name string) {
+ if err := os.WriteFile(filepath.Join(dir, name), []byte("held"), 0600); err != nil {
+ t.Fatal(err)
+ }
+ }
+ occupy(base + ext)
+ for i := 1; i < maxUniqueNameAttempts; i++ {
+ occupy(fmt.Sprintf("%s-%d%s", base, i, ext))
+ }
+
+ if _, _, err := createUniqueFile(dir, base, ext); err == nil {
+ t.Fatal("createUniqueFile succeeded with every name taken; it must refuse rather than overwrite")
+ }
+ // Nothing it touched may have changed.
+ assertFileHolds(t, filepath.Join(dir, base+ext), []byte("held"))
+}
+
+// createUniqueFile returns an OPEN handle on purpose: a stat-then-write leaves a window
+// where a concurrent caller takes the name between the check and the write.
+func TestCreateUniqueFileReservesTheNameItReturns(t *testing.T) {
+ dir := t.TempDir()
+
+ first, firstPath, err := createUniqueFile(dir, "rec_fixed", ".gif")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = first.Close() }()
+
+ second, secondPath, err := createUniqueFile(dir, "rec_fixed", ".gif")
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = second.Close() }()
+
+ if firstPath == secondPath {
+ t.Fatalf("the second reservation returned the same path %q, so the first was not held", firstPath)
+ }
+ if _, err := os.Stat(firstPath); err != nil {
+ t.Errorf("the first reservation does not exist on disk: %v", err)
+ }
+}
+
+// AC6, recording: recordingsOutputPath's own comment claimed the path was unique while
+// nothing checked — two stops in the same second returned one path and the encoder that
+// finished second overwrote the first recording. The path is now reserved, so a second
+// call cannot return it.
+func TestRecordingsOutputPathReservesEachPath(t *testing.T) {
+ h := Handlers{
+ Config: &config.RuntimeConfig{StateDir: t.TempDir()},
+ recorder: &recorder{},
+ }
+
+ first, err := h.recordingsOutputPath()
+ if err != nil {
+ t.Fatal(err)
+ }
+ second, err := h.recordingsOutputPath()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if first == second {
+ t.Fatalf("two stops in the same second both got %q", first)
+ }
+ for _, path := range []string{first, second} {
+ if _, err := os.Stat(path); err != nil {
+ t.Errorf("%q was returned but not reserved on disk: %v", path, err)
+ }
+ }
+}
+
+// stubExportEncoder is the smallest ExportEncoder writeExportFile will accept, so the
+// naming and overwrite policy can be driven without a browser.
+type stubExportEncoder struct {
+ w io.Writer
+ body string
+}
+
+func (s *stubExportEncoder) ContentType() string { return "application/json" }
+func (s *stubExportEncoder) FileExtension() string { return ".har" }
+func (s *stubExportEncoder) Start(w io.Writer) error {
+ s.w = w
+ _, err := io.WriteString(w, s.body)
+ return err
+}
+func (s *stubExportEncoder) Encode(observe.ExportEntry) error { return nil }
+func (s *stubExportEncoder) Finish() error { return nil }
+
+// AC6, network export: two auto-named exports in the same second used to rename onto one
+// file — and share one <path>.tmp while writing, so the loser was corrupt as well as
+// lost. AC8 in the same test: a caller ?path= still overwrites, because this fix is about
+// generated default names only.
+func TestNetworkExportAutoNamesUniquelyButHonoursAnExplicitPath(t *testing.T) {
+ stateDir := t.TempDir()
+ h := Handlers{Config: &config.RuntimeConfig{StateDir: stateDir}}
+
+ export := func(query, body string) string {
+ t.Helper()
+ req := httptest.NewRequest("GET", "/network/export?output=file"+query, nil)
+ w := httptest.NewRecorder()
+ enc := &stubExportEncoder{body: body}
+ if err := h.writeExportFile(w, req, enc, "har", func(func(observe.ExportEntry) error) error { return nil }); err != nil {
+ t.Fatalf("writeExportFile: %v", err)
+ }
+ var resp struct {
+ Path string `json:"path"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+ t.Fatalf("parse response: %v", err)
+ }
+ return resp.Path
+ }
+
+ firstAuto := export("", "first-export")
+ secondAuto := export("", "second")
+ if firstAuto == secondAuto {
+ t.Fatalf("two auto-named exports both wrote %q", firstAuto)
+ }
+ assertFileHolds(t, firstAuto, []byte("first-export"))
+ assertFileHolds(t, secondAuto, []byte("second"))
+
+ // The explicit path is the boundary this fix must not cross.
+ firstNamed := export("&path=chosen.har", "named-one")
+ secondNamed := export("&path=chosen.har", "named-two")
+ if firstNamed != secondNamed {
+ t.Errorf("an explicit ?path= produced two different files (%q then %q); a caller who names a file is entitled to replace it", firstNamed, secondNamed)
+ }
+ assertFileHolds(t, secondNamed, []byte("named-two"))
+
+ // No stray .tmp left behind by either route.
+ entries, err := os.ReadDir(filepath.Join(stateDir, "exports"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, e := range entries {
+ if strings.HasSuffix(e.Name(), ".tmp") {
+ t.Errorf("export left a temp file behind: %s", e.Name())
+ }
+ }
+}
+
+// AC6, snapshot: HandleSnapshot's file branch cannot be driven here — TopmostModalNodeID
+// needs a real CDP context, so any mocked request 500s before extraction. What IS
+// checkable without a browser is that the branch routes the generated name through the
+// collision-proof helper while the caller-supplied path still uses a plain write.
+func TestSnapshotFileBranchRoutesTheGeneratedNameThroughTheUniqueHelper(t *testing.T) {
+ raw, err := os.ReadFile("snapshot.go")
+ if err != nil {
+ t.Fatal(err)
+ }
+ src := string(raw)
+
+ if !strings.Contains(src, `writeUniqueFile(snapshotDir, "snapshot-"+timestamp, ext, content)`) {
+ t.Error("the auto-named snapshot no longer goes through writeUniqueFile, so two snapshots in one second can overwrite again")
+ }
+ if strings.Count(src, "os.WriteFile(filePath, content, 0600)") != 1 {
+ t.Errorf("expected exactly one plain write in snapshot.go — the caller-supplied path — got %d", strings.Count(src, "os.WriteFile(filePath, content, 0600)"))
+ }
+ // The plain write must sit in the outputPath branch, not the generated one.
+ explicitBranch := src[strings.Index(src, `if outputPath != "" {`):]
+ if end := strings.Index(explicitBranch, "\n\t\t} else {"); end >= 0 {
+ explicitBranch = explicitBranch[:end]
+ }
+ if !strings.Contains(explicitBranch, "os.WriteFile(filePath, content, 0600)") {
+ t.Error("the plain write is no longer inside the caller-supplied-path branch")
+ }
+}
diff --git a/internal/handlers/network_export.go b/internal/handlers/network_export.go
index 11d04e63..7d7e9b30 100644
--- a/internal/handlers/network_export.go
+++ b/internal/handlers/network_export.go
@@ -310,9 +310,23 @@ func (h *Handlers) writeExportFile(
encodeAll func(emit func(observe.ExportEntry) error) error,
) error {
userPath := r.URL.Query().Get("path")
- if userPath == "" {
- ts := time.Now().Format("20060102-150405")
- userPath = fmt.Sprintf("network-%s%s", ts, enc.FileExtension())
+ autoNamed := userPath == ""
+ if autoNamed {
+ // Reserve the generated name before resolveExportFile derives the tmp path from
+ // it. Two auto-named exports in the same second used to rename onto one file —
+ // and share one <path>.tmp while writing, so the loser was corrupt as well as
+ // lost. The reservation is a 0-byte file the final rename replaces. A caller
+ // ?path= is untouched and keeps overwriting.
+ exportDir := filepath.Join(h.Config.StateDir, "exports")
+ if err := os.MkdirAll(exportDir, 0750); err != nil {
+ return fmt.Errorf("create dir: %w", err)
+ }
+ reserved, reservedPath, err := createUniqueFile(exportDir, "network-"+exportTimestamp(), enc.FileExtension())
+ if err != nil {
+ return fmt.Errorf("reserve export name: %w", err)
+ }
+ _ = reserved.Close()
+ userPath = filepath.Base(reservedPath)
}
absPath, tmpPath, f, _, err := h.resolveExportFile(userPath)
diff --git a/internal/handlers/record_handlers.go b/internal/handlers/record_handlers.go
index e0d1aba3..228d3d32 100644
--- a/internal/handlers/record_handlers.go
+++ b/internal/handlers/record_handlers.go
@@ -152,15 +152,26 @@ func (h *Handlers) HandleRecordStop(w http.ResponseWriter, r *http.Request) {
// recordingsOutputPath returns a unique output path inside the server-controlled
// recordings directory. The caller never chooses the path — only the server does.
+//
+// "Unique" used to be an unbacked claim in this comment: the name came from a
+// second-resolution timestamp and nothing checked whether it existed, so two stops in
+// the same second returned one path and the encoder that finished second overwrote the
+// first recording. The path is now RESERVED by creating it exclusively; the encoder
+// writes over its own 0-byte placeholder afterwards.
func (h *Handlers) recordingsOutputPath() (string, error) {
dir := filepath.Join(h.Config.StateDir, "recordings")
if err := os.MkdirAll(dir, 0700); err != nil {
return "", fmt.Errorf("create recordings dir: %w", err)
}
- format := h.recorder.activeFormat()
- ext := "." + format
- name := fmt.Sprintf("rec_%s%s", time.Now().Format("20060102_150405"), ext)
- return filepath.Join(dir, name), nil
+ base := "rec_" + time.Now().Format("20060102_150405")
+ f, path, err := createUniqueFile(dir, base, "."+h.recorder.activeFormat())
+ if err != nil {
+ return "", fmt.Errorf("reserve recording path: %w", err)
+ }
+ if err := f.Close(); err != nil {
+ return "", fmt.Errorf("reserve recording path: %w", err)
+ }
+ return path, nil
}
// HandleRecordStatus returns the current recording status.
diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.go
index d649caad..c0368f00 100644
--- a/internal/handlers/snapshot.go
+++ b/internal/handlers/snapshot.go
@@ -243,19 +243,19 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
return
}
- timestamp := time.Now().Format("20060102-150405")
- var filename string
+ timestamp := exportTimestamp()
+ var ext string
var content []byte
switch format {
case "text":
- filename = fmt.Sprintf("snapshot-%s.txt", timestamp)
+ ext = ".txt"
textContent := fmt.Sprintf("# %s\n# %s\n# %d nodes\n# %s\n\n%s",
title, url, len(flat), time.Now().Format(time.RFC3339),
bridge.FormatSnapshotText(flat))
content = []byte(textContent)
case "yaml":
- filename = fmt.Sprintf("snapshot-%s.yaml", timestamp)
+ ext = ".yaml"
data := map[string]any{
"url": url,
"title": title,
@@ -283,7 +283,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
return
}
default:
- filename = fmt.Sprintf("snapshot-%s.json", timestamp)
+ ext = ".json"
data := map[string]any{
"url": url,
"title": title,
@@ -312,7 +312,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
}
}
- filePath := filepath.Join(snapshotDir, filename)
+ var filePath string
if outputPath != "" {
safe, err := httpx.SafeCreatePath(h.Config.StateDir, outputPath)
if err != nil {
@@ -330,10 +330,19 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
httpx.Error(w, 500, fmt.Errorf("create output dir: %w", err))
return
}
- }
- if err := os.WriteFile(filePath, content, 0600); err != nil {
- httpx.Error(w, 500, fmt.Errorf("write snapshot: %w", err))
- return
+ // A caller-named path keeps overwriting: this fix is about generated
+ // default names, and a caller who names a file is entitled to replace it.
+ if err := os.WriteFile(filePath, content, 0600); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("write snapshot: %w", err))
+ return
+ }
+ } else {
+ var err error
+ filePath, err = writeUniqueFile(snapshotDir, "snapshot-"+timestamp, ext, content)
+ if err != nil {
+ httpx.Error(w, 500, fmt.Errorf("write snapshot: %w", err))
+ return
+ }
}
httpx.JSON(w, 200, map[string]any{