Skip to content

Commit

Permalink
blob/fileblob: Add docstring about tempdirs (#3296)
Browse files Browse the repository at this point in the history
  • Loading branch information
vangent authored Aug 3, 2023
1 parent 9b62f46 commit cfe20ca
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 5 deletions.
24 changes: 19 additions & 5 deletions blob/fileblob/fileblob.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,20 @@
// Package fileblob provides a blob implementation that uses the filesystem.
// Use OpenBucket to construct a *blob.Bucket.
//
// By default fileblob stores blob metadata in 'sidecar files' under the original
// filename but an additional ".attrs" suffix.
// That behaviour can be changed via Options.Metadata;
// To avoid partial writes, fileblob writes to a temporary file and then renames
// the temporary file to the final path on Close. By default, it creates these
// temporary files in `os.TempDir`. If `os.TempDir` is on a different mount than
// your base bucket path, the `os.Rename` will fail with `invalid cross-device link`.
// To avoid this, either configure the temp dir to use by setting the environment
// variable `TMPDIR`, or set `Options.NoTempDir` to `true` (fileblob will create
// the temporary files next to the actual files instead of in a temporary directory).
//
// By default fileblob stores blob metadata in "sidecar" files under the original
// filename with an additional ".attrs" suffix.
// This behaviour can be changed via `Options.Metadata`;
// writing of those metadata files can be suppressed by setting it to
// 'MetadataDontWrite' or its equivalent "metadata=skip" in the URL for the opener.
// In any case, absent any stored metadata many blob.Attributes fields
// `MetadataDontWrite` or its equivalent "metadata=skip" in the URL for the opener.
// In either case, absent any stored metadata many `blob.Attributes` fields
// will be set to default values.
//
// # URLs
Expand Down Expand Up @@ -102,6 +110,8 @@ const Scheme = "file"
//
// - create_dir: (any non-empty value) the directory is created (using os.MkDirAll)
// if it does not already exist.
// - no_tmp_dir: (any non-empty value) temporary files are created next to the final
// path instead of in os.TempDir.
// - base_url: the base URL to use to construct signed URLs; see URLSignerHMAC
// - secret_key_path: path to read for the secret key used to construct signed URLs;
// see URLSignerHMAC
Expand Down Expand Up @@ -149,6 +159,7 @@ var recognizedParams = map[string]bool{
"base_url": true,
"secret_key_path": true,
"metadata": true,
"no_tmp_dir": true,
}

type metadataOption string // Not exported as subject to change.
Expand Down Expand Up @@ -187,6 +198,9 @@ func (o *URLOpener) forParams(ctx context.Context, q url.Values) (*Options, erro
if q.Get("create_dir") != "" {
opts.CreateDir = true
}
if q.Get("no_temp_dir") != "" {
opts.NoTempDir = true
}
baseURL := q.Get("base_url")
keyPath := q.Get("secret_key_path")
if (baseURL == "") != (keyPath == "") {
Expand Down
2 changes: 2 additions & 0 deletions blob/fileblob/fileblob_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,8 @@ func TestOpenBucketFromURL(t *testing.T) {
{"file://./../..", "filenotfound.txt", false, true, ""},
// OK.
{"file://" + dirpath, "myfile.txt", false, false, "hello world"},
// OK, with no_tmp_dir.
{"file://" + dirpath + "?no_tmp_dir", "myfile.txt", false, false, "hello world"},
// OK, host is ignored.
{"file://localhost" + dirpath, "myfile.txt", false, false, "hello world"},
// OK, with prefix.
Expand Down

0 comments on commit cfe20ca

Please sign in to comment.