Documentation
¶
Overview ¶
Package storage provides a URI-addressable blob store that dispatches between Google Cloud Storage (gs://bucket/key), the local filesystem (file:///abs/path), and an in-memory backend (mem://namespace/key) for tests. Callers switch backends by changing a URI; the surface never exposes backend-specific types.
The file:// backend currently targets POSIX paths. Windows file URIs of the form file:///C:/path are not handled in this version; support may be added later.
For(uri) memoizes one Store per scheme, so the GCS client — and its underlying HTTP/gRPC connection pool — is reused across calls within a process.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnsupportedScheme is returned by For when the URI's scheme has no backend. ErrUnsupportedScheme = errors.New("storage: unsupported scheme") // ErrInvalidURI is returned when a URI fails validation — missing path, // missing bucket on gs://, non-absolute file:// path, or a "." / ".." // segment in a file:// path. ErrInvalidURI = errors.New("storage: invalid uri") // ErrNotExist indicates that the addressed object does not exist. It // aliases io/fs.ErrNotExist so callers can use errors.Is with either // sentinel without importing backend-specific error types. ErrNotExist = fs.ErrNotExist )
Functions ¶
Types ¶
type Object ¶
type Object struct {
URI string
Size int64
ContentType string
Updated time.Time
// Generation and Metageneration are GCS-specific identifiers used for
// optimistic concurrency. Generation changes on every object replacement;
// Metageneration changes on every metadata update. Both are zero on the
// file:// backend.
Generation int64
Metageneration int64
}
Object describes a stored blob as returned by List.
type Store ¶
type Store interface {
// Get reads the entire object at uri into memory. Returns an error
// wrapping ErrNotExist when the object does not exist.
Get(ctx context.Context, uri string) ([]byte, error)
// PutFile uploads the contents of source to uri. The source parameter
// is a local filesystem path; callers are responsible for validating
// it when it originates from untrusted input.
PutFile(ctx context.Context, uri, source string) error
// PutBytes writes data to uri. On gs:// URIs, contentType becomes the
// object's Content-Type metadata. On file:// URIs, a <path>.meta.json
// sidecar records it; an empty contentType skips the sidecar write.
PutBytes(ctx context.Context, uri string, data []byte, contentType string) error
// Delete removes the object at uri. On file:// URIs, an adjacent
// <path>.meta.json sidecar is also removed when present. Returns an
// error wrapping ErrNotExist when the object does not exist.
Delete(ctx context.Context, uri string) error
// List returns all objects under uri, recursively, in lexicographic
// order by URI. On gs:// URIs, uri is treated as a prefix: every
// object whose name begins with the URI's key portion is returned.
// Include a trailing "/" to scope to a directory-like prefix. On
// file:// URIs, uri is a directory root.
List(ctx context.Context, uri string) ([]Object, error)
}
Store is the URI-addressable blob interface. Both backends accept the same URI forms they recognize by scheme.
Source Files