Documentation
¶
Overview ¶
Package uploads provides an object storage abstraction for saving and reading files, with implementations backed by S3, GCS, Cloudflare R2, Backblaze B2, the local filesystem, and an in-memory provider (see the objectstorage subpackage).
Index ¶
- func ReadFile(ctx context.Context, m UploadManager, path string) (b []byte, err error)
- func SaveFile(ctx context.Context, m UploadManager, path string, content []byte, ...) error
- type Attributer
- type Attributes
- type Lister
- type ObjectInfo
- type RangeReader
- type SaveOption
- type SaveOptions
- type SignedURLOptions
- type URLSigner
- type UploadManager
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ReadFile ¶
ReadFile is a convenience helper that reads an entire object into memory via UploadManager.Open.
func SaveFile ¶
func SaveFile(ctx context.Context, m UploadManager, path string, content []byte, opts ...SaveOption) error
SaveFile is a convenience helper that saves a byte slice via UploadManager.Save.
Example ¶
package main
import (
"context"
"fmt"
loggingnoop "github.com/primandproper/platform-go/v3/observability/logging/noop"
metricsnoop "github.com/primandproper/platform-go/v3/observability/metrics/noop"
tracingnoop "github.com/primandproper/platform-go/v3/observability/tracing/noop"
"github.com/primandproper/platform-go/v3/uploads"
"github.com/primandproper/platform-go/v3/uploads/objectstorage"
)
func newManager() uploads.UploadManager {
m, err := objectstorage.NewUploadManager(
context.Background(),
loggingnoop.NewLogger(),
tracingnoop.NewTracerProvider(),
metricsnoop.NewMetricsProvider(),
&objectstorage.Config{BucketName: "example", Provider: objectstorage.MemoryProvider},
)
if err != nil {
panic(err)
}
return m
}
func main() {
ctx := context.Background()
mgr := newManager()
// Options set the stored metadata; without WithContentType the provider sniffs it from content.
if err := uploads.SaveFile(ctx, mgr, "note.txt", []byte("hi"),
uploads.WithContentType("text/plain"),
uploads.WithCacheControl("max-age=60"),
); err != nil {
panic(err)
}
data, err := uploads.ReadFile(ctx, mgr, "note.txt")
if err != nil {
panic(err)
}
fmt.Println(string(data))
}
Output: hi
Types ¶
type Attributer ¶
type Attributer interface {
Attributes(ctx context.Context, path string) (*Attributes, error)
}
Attributer can fetch an object's stored metadata.
type Attributes ¶
type Attributes struct {
ModTime time.Time
ContentType string
CacheControl string
ETag string
Size int64
// contains filtered or unexported fields
}
Attributes describes a stored object.
type Lister ¶
Lister can stream the objects stored under a prefix. The returned iterator yields each object lazily; a non-nil error is yielded once and terminates iteration, and the caller may stop early by breaking out of the range loop.
type ObjectInfo ¶
type ObjectInfo struct {
ModTime time.Time
Path string
Size int64
IsDir bool
// contains filtered or unexported fields
}
ObjectInfo describes a single entry returned by Lister.List.
func ListAll ¶
ListAll drains a Lister into a slice. It is a convenience for small listings; prefer ranging Lister.List directly when a prefix may contain a very large number of objects.
Example ¶
package main
import (
"context"
"fmt"
"sort"
loggingnoop "github.com/primandproper/platform-go/v3/observability/logging/noop"
metricsnoop "github.com/primandproper/platform-go/v3/observability/metrics/noop"
tracingnoop "github.com/primandproper/platform-go/v3/observability/tracing/noop"
"github.com/primandproper/platform-go/v3/uploads"
"github.com/primandproper/platform-go/v3/uploads/objectstorage"
)
func newManager() uploads.UploadManager {
m, err := objectstorage.NewUploadManager(
context.Background(),
loggingnoop.NewLogger(),
tracingnoop.NewTracerProvider(),
metricsnoop.NewMetricsProvider(),
&objectstorage.Config{BucketName: "example", Provider: objectstorage.MemoryProvider},
)
if err != nil {
panic(err)
}
return m
}
func main() {
ctx := context.Background()
mgr := newManager()
for _, name := range []string{"a.txt", "b.txt"} {
if err := uploads.SaveFile(ctx, mgr, name, []byte("x")); err != nil {
panic(err)
}
}
// ListAll drains the streaming Lister into a slice; prefer ranging List for large prefixes.
objs, err := uploads.ListAll(ctx, mgr.(uploads.Lister), "")
if err != nil {
panic(err)
}
paths := make([]string, 0, len(objs))
for i := range objs {
paths = append(paths, objs[i].Path)
}
sort.Strings(paths)
fmt.Println(paths)
}
Output: [a.txt b.txt]
type RangeReader ¶
type RangeReader interface {
// OpenRange returns a reader over length bytes of the object at path, starting at offset.
// A negative length reads to the end of the object. The caller must close the reader.
OpenRange(ctx context.Context, path string, offset, length int64) (io.ReadCloser, error)
}
RangeReader can open a byte range of an object, for partial reads such as HTTP Range requests (video) or seeking within columnar files (parquet).
type SaveOption ¶
type SaveOption func(*SaveOptions)
SaveOption customizes a Save call.
func WithCacheControl ¶
func WithCacheControl(cacheControl string) SaveOption
WithCacheControl sets the stored Cache-Control header for a saved object.
func WithContentType ¶
func WithContentType(contentType string) SaveOption
WithContentType sets the stored Content-Type for a saved object.
type SaveOptions ¶
type SaveOptions struct {
// ContentType sets the stored Content-Type. When empty, the provider sniffs it from the
// content on write.
ContentType string
// CacheControl sets the stored Cache-Control header for served objects.
CacheControl string
// contains filtered or unexported fields
}
SaveOptions are the resolved settings for a Save call. Implementations obtain one via BuildSaveOptions.
func BuildSaveOptions ¶
func BuildSaveOptions(opts ...SaveOption) SaveOptions
BuildSaveOptions resolves SaveOptions from a list of options. UploadManager implementations call this to read the requested settings.
type SignedURLOptions ¶
type SignedURLOptions struct {
// Method is the HTTP method the URL permits: "GET", "PUT", or "DELETE". Empty means "GET".
Method string
// ContentType, for PUT URLs, is the exact Content-Type the client must send.
ContentType string
// Expiry sets how long the URL is valid. Zero means the provider default.
Expiry time.Duration
// contains filtered or unexported fields
}
SignedURLOptions configures a signed URL.
type URLSigner ¶
type URLSigner interface {
SignedURL(ctx context.Context, path string, opts *SignedURLOptions) (string, error)
}
URLSigner can mint a signed URL granting temporary, direct access to an object, letting clients read or write storage without proxying bytes through the service.
type UploadManager ¶
type UploadManager interface {
// Save writes the contents of r to the object at path.
Save(ctx context.Context, path string, r io.Reader, opts ...SaveOption) error
// Open returns a reader for the object at path. The caller must close it.
Open(ctx context.Context, path string) (io.ReadCloser, error)
// Delete removes the object at path.
Delete(ctx context.Context, path string) error
// Exists reports whether an object exists at path.
Exists(ctx context.Context, path string) (bool, error)
}
UploadManager reads and writes objects in a storage provider.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package images provides small, pure helpers for validating, encoding, and thumbnailing images.
|
Package images provides small, pure helpers for validating, encoding, and thumbnailing images. |
|
Package mockuploads provides moq-generated mock implementations of the uploads package interfaces (UploadManager and the optional capability interfaces) for use in tests.
|
Package mockuploads provides moq-generated mock implementations of the uploads package interfaces (UploadManager and the optional capability interfaces) for use in tests. |