fileblob

Documentation

Overview

Package fileblob provides a blob.Bucket driver implementation.

NB! To minimize breaking changes with older PocketBase releases, the driver is a stripped down and adapted version of the previously used gocloud.dev/blob/fileblob, hence many of the below doc comments, struct options and interface implementations are the same.

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 either case, absent any stored metadata many `blob.Attributes` fields will be set to default values.

The blob abstraction supports all UTF-8 strings; to make this work with services lacking full UTF-8 support, strings must be escaped (during writes) and unescaped (during reads). The following escapes are performed for fileblob:

• Blob keys: ASCII characters 0-31 are escaped to "__0x<hex>__". If os.PathSeparator != "/", it is also escaped. Additionally, the "/" in "../", the trailing "/" in "//", and a trailing "/" is key names are escaped in the same way. On Windows, the characters "<>:"|?*" are also escaped.

Example:

drv, _ := fileblob.New("/path/to/dir", nil)
bucket := blob.NewBucket(drv)

Index

• Constants
• func New(dir string, opts *Options) (blob.Driver, error)
• type Options

Constants

const (
	// Metadata gets written to a separate file.
	MetadataInSidecar metadataOption = ""

	// Writes won't carry metadata, as per the package docstring.
	MetadataDontWrite metadataOption = "skip"
)

Settings for Options.Metadata.

Functions

func New

func New(dir string, opts *Options) (blob.Driver, error)

New creates a new instance of the fileblob driver backed by the filesystem and rooted at dir, which must exist.

Types

type Options

type Options struct {
	// Refers to the strategy for how to deal with metadata (such as blob.Attributes).
	// For supported values please see the Metadata* constants.
	// If left unchanged, 'MetadataInSidecar' will be used.
	Metadata metadataOption

	// The FileMode to use when creating directories for the top-level directory
	// backing the bucket (when CreateDir is true), and for subdirectories for keys.
	// Defaults to 0777.
	DirFileMode os.FileMode

	// If true, create the directory backing the Bucket if it does not exist
	// (using os.MkdirAll).
	CreateDir bool

	// If true, don't use os.TempDir for temporary files, but instead place them
	// next to the actual files. This may result in "stranded" temporary files
	// (e.g., if the application is killed before the file cleanup runs).
	//
	// If your bucket directory is on a different mount than os.TempDir, you will
	// need to set this to true, as os.Rename will fail across mount points.
	NoTempDir bool
}

Options sets options for constructing a *blob.Bucket backed by fileblob.