2 files changed, 187 insertions, 0 deletions
diff --git a/modules/tempdir/tempdir.go b/modules/tempdir/tempdir.go
new file mode 100644
index 0000000000..22c2e4ea16
--- /dev/null
+++ b/modules/tempdir/tempdir.go
@@ -0,0 +1,112 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package tempdir
+
+import (
+	"os"
+	"path/filepath"
+	"time"
+
+	"code.gitea.io/gitea/modules/log"
+	"code.gitea.io/gitea/modules/util"
+)
+
+type TempDir struct {
+	// base is the base directory for temporary files, it must exist before accessing and won't be created automatically.
+	// for example: base="/system-tmpdir", sub="gitea-tmp"
+	base, sub string
+}
+
+func (td *TempDir) JoinPath(elems ...string) string {
+	return filepath.Join(append([]string{td.base, td.sub}, elems...)...)
+}
+
+// MkdirAllSub works like os.MkdirAll, but the base directory must exist
+func (td *TempDir) MkdirAllSub(dir string) (string, error) {
+	if _, err := os.Stat(td.base); err != nil {
+		return "", err
+	}
+	full := filepath.Join(td.base, td.sub, dir)
+	if err := os.MkdirAll(full, os.ModePerm); err != nil {
+		return "", err
+	}
+	return full, nil
+}
+
+func (td *TempDir) prepareDirWithPattern(elems ...string) (dir, pattern string, err error) {
+	if _, err = os.Stat(td.base); err != nil {
+		return "", "", err
+	}
+	dir, pattern = filepath.Split(filepath.Join(append([]string{td.base, td.sub}, elems...)...))
+	if err = os.MkdirAll(dir, os.ModePerm); err != nil {
+		return "", "", err
+	}
+	return dir, pattern, nil
+}
+
+// MkdirTempRandom works like os.MkdirTemp, the last path field is the "pattern"
+func (td *TempDir) MkdirTempRandom(elems ...string) (string, func(), error) {
+	dir, pattern, err := td.prepareDirWithPattern(elems...)
+	if err != nil {
+		return "", nil, err
+	}
+	dir, err = os.MkdirTemp(dir, pattern)
+	if err != nil {
+		return "", nil, err
+	}
+	return dir, func() {
+		if err := util.RemoveAll(dir); err != nil {
+			log.Error("Failed to remove temp directory %s: %v", dir, err)
+		}
+	}, nil
+}
+
+// CreateTempFileRandom works like os.CreateTemp, the last path field is the "pattern"
+func (td *TempDir) CreateTempFileRandom(elems ...string) (*os.File, func(), error) {
+	dir, pattern, err := td.prepareDirWithPattern(elems...)
+	if err != nil {
+		return nil, nil, err
+	}
+	f, err := os.CreateTemp(dir, pattern)
+	if err != nil {
+		return nil, nil, err
+	}
+	filename := f.Name()
+	return f, func() {
+		_ = f.Close()
+		if err := util.Remove(filename); err != nil {
+			log.Error("Unable to remove temporary file: %s: Error: %v", filename, err)
+		}
+	}, err
+}
+
+func (td *TempDir) RemoveOutdated(d time.Duration) {
+	var remove func(path string)
+	remove = func(path string) {
+		entries, _ := os.ReadDir(path)
+		for _, entry := range entries {
+			full := filepath.Join(path, entry.Name())
+			if entry.IsDir() {
+				remove(full)
+				_ = os.Remove(full)
+				continue
+			}
+			info, err := entry.Info()
+			if err == nil && time.Since(info.ModTime()) > d {
+				_ = os.Remove(full)
+			}
+		}
+	}
+	remove(td.JoinPath(""))
+}
+
+// New create a new TempDir instance, "base" must be an existing directory,
+// "sub" could be a multi-level directory and will be created if not exist
+func New(base, sub string) *TempDir {
+	return &TempDir{base: base, sub: sub}
+}
+
+func OsTempDir(sub string) *TempDir {
+	return New(os.TempDir(), sub)
+}
diff --git a/modules/tempdir/tempdir_test.go b/modules/tempdir/tempdir_test.go
new file mode 100644
index 0000000000..d6afcb7bed
--- /dev/null
+++ b/modules/tempdir/tempdir_test.go
@@ -0,0 +1,75 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package tempdir
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestTempDir(t *testing.T) {
+	base := t.TempDir()
+
+	t.Run("Create", func(t *testing.T) {
+		td := New(base, "sub1/sub2") // make sure the sub dir supports "/" in the path
+		assert.Equal(t, filepath.Join(base, "sub1", "sub2"), td.JoinPath())
+		assert.Equal(t, filepath.Join(base, "sub1", "sub2/test"), td.JoinPath("test"))
+
+		t.Run("MkdirTempRandom", func(t *testing.T) {
+			s, cleanup, err := td.MkdirTempRandom("foo")
+			assert.NoError(t, err)
+			assert.True(t, strings.HasPrefix(s, filepath.Join(base, "sub1/sub2", "foo")))
+
+			_, err = os.Stat(s)
+			assert.NoError(t, err)
+			cleanup()
+			_, err = os.Stat(s)
+			assert.ErrorIs(t, err, os.ErrNotExist)
+		})
+
+		t.Run("CreateTempFileRandom", func(t *testing.T) {
+			f, cleanup, err := td.CreateTempFileRandom("foo", "bar")
+			filename := f.Name()
+			assert.NoError(t, err)
+			assert.True(t, strings.HasPrefix(filename, filepath.Join(base, "sub1/sub2", "foo", "bar")))
+			_, err = os.Stat(filename)
+			assert.NoError(t, err)
+			cleanup()
+			_, err = os.Stat(filename)
+			assert.ErrorIs(t, err, os.ErrNotExist)
+		})
+
+		t.Run("RemoveOutDated", func(t *testing.T) {
+			fa1, _, err := td.CreateTempFileRandom("dir-a", "f1")
+			assert.NoError(t, err)
+			fa2, _, err := td.CreateTempFileRandom("dir-a", "f2")
+			assert.NoError(t, err)
+			_ = os.Chtimes(fa2.Name(), time.Now().Add(-time.Hour), time.Now().Add(-time.Hour))
+			fb1, _, err := td.CreateTempFileRandom("dir-b", "f1")
+			assert.NoError(t, err)
+			_ = os.Chtimes(fb1.Name(), time.Now().Add(-time.Hour), time.Now().Add(-time.Hour))
+			_, _, _ = fa1.Close(), fa2.Close(), fb1.Close()
+
+			td.RemoveOutdated(time.Minute)
+
+			_, err = os.Stat(fa1.Name())
+			assert.NoError(t, err)
+			_, err = os.Stat(fa2.Name())
+			assert.ErrorIs(t, err, os.ErrNotExist)
+			_, err = os.Stat(fb1.Name())
+			assert.ErrorIs(t, err, os.ErrNotExist)
+		})
+	})
+
+	t.Run("BaseNotExist", func(t *testing.T) {
+		td := New(filepath.Join(base, "not-exist"), "sub")
+		_, _, err := td.MkdirTempRandom("foo")
+		assert.ErrorIs(t, err, os.ErrNotExist)
+	})
+}