From 13cb984ef99f3135fc267ada4ef53cc09e9aff3d Mon Sep 17 00:00:00 2001
From: Hank Donnay <hdonnay@redhat.com>
Date: Tue, 19 Mar 2024 13:15:24 -0500
Subject: [PATCH] libindex: update and document file placement logic

Signed-off-by: Hank Donnay <hdonnay@redhat.com>
---
 libindex/fetcher.go       | 26 ++++++++++++++++++++++++++
 libindex/tempdir_other.go |  6 ++++++
 libindex/tempdir_unix.go  | 19 +++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 libindex/tempdir_other.go
 create mode 100644 libindex/tempdir_unix.go

diff --git a/libindex/fetcher.go b/libindex/fetcher.go
index 93dfbfeda..ca470137f 100644
--- a/libindex/fetcher.go
+++ b/libindex/fetcher.go
@@ -48,7 +48,33 @@ type RemoteFetchArena struct {
 }
 
 // NewRemoteFetchArena returns an initialized RemoteFetchArena.
+//
+// If the "root" parameter is "", the advice in [file-hierarchy(7)] and ["Using
+// /tmp/ and /var/tmp/ Safely"] is followed. Specifically, "/var/tmp" is used
+// unless "TMPDIR" is set in the environment, in which case the contents of that
+// variable are interpreted as a path and used.
+//
+// The RemoteFetchArena attempts to use [O_TMPFILE] and falls back to
+// [os.CreateTemp] if that seems to not work. If the filesystem backing "root"
+// does not support O_TMPFILE, files may linger in the event of a process
+// crashing or an unclean shutdown. Operators should either use a different
+// filesystem or arrange for periodic cleanup via [systemd-tmpfiles(8)] or
+// similar.
+//
+// In a containerized environment, operators may need to mount a directory or
+// filesystem on "/var/tmp".
+//
+// On OSX, temporary files are not unlinked from the filesystem upon creation,
+// because an equivalent to Linux's "/proc/self/fd" doesn't seem to exist.
+//
+// On UNIX-unlike systems, none of the above logic takes place.
+//
+// [file-hierarchy(7)]: https://www.freedesktop.org/software/systemd/man/latest/file-hierarchy.html
+// ["Using /tmp/ and /var/tmp/ Safely"]: https://systemd.io/TEMPORARY_DIRECTORIES/
+// [O_TMPFILE]: https://man7.org/linux/man-pages/man2/open.2.html
+// [systemd-tmpfiles(8)]: https://www.freedesktop.org/software/systemd/man/latest/systemd-tmpfiles.html
 func NewRemoteFetchArena(wc *http.Client, root string) *RemoteFetchArena {
+	fixTemp(&root)
 	return &RemoteFetchArena{
 		wc:   wc,
 		sf:   &singleflight.Group{},
diff --git a/libindex/tempdir_other.go b/libindex/tempdir_other.go
new file mode 100644
index 000000000..0bfd7bbd4
--- /dev/null
+++ b/libindex/tempdir_other.go
@@ -0,0 +1,6 @@
+//go:build !unix
+
+package libindex
+
+// FixTemp is a no-op.
+func fixTemp(_ *string) {}
diff --git a/libindex/tempdir_unix.go b/libindex/tempdir_unix.go
new file mode 100644
index 000000000..76906f822
--- /dev/null
+++ b/libindex/tempdir_unix.go
@@ -0,0 +1,19 @@
+package libindex
+
+import (
+	"os"
+)
+
+// FixTemp modifies "dir" according to the documented defaults.
+//
+// See [NewRemoteFetchArena].
+func fixTemp(dir *string) {
+	if *dir != "" {
+		return
+	}
+	if d, ok := os.LookupEnv("TMPDIR"); ok && d != "" {
+		*dir = d
+		return
+	}
+	*dir = "/var/tmp"
+}