storage

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 14 Imported by: 0

README

gas/storage

Test Go Reference Go Version License

Part of the Gas monorepo · Documentation · All modules

Object storage for the Gas framework, with backends that keep one contract, Amazon S3's rules, checked before any I/O: Amazon S3 or a server that speaks its API, a directory on a local disk, and an in-memory store for tests and local development.

Defines storage.Provider and storage.Presigner.

go get github.com/gasmod/gas/storage
gas.WithSingletonService[storage.Provider](memory.New()),

Each backend is a gas.Service, needs gas.ConfigProvider and gas.Logger, and reads the storage section.

Package Provides
storage The Provider and Presigner contract, its input rules, limits and sentinel errors
storage/s3 Amazon S3 and S3-compatible services
storage/dir A directory on local disk, through an os.Root
storage/memory In-process store with S3's rules, for tests and local development
storage/storagetest Recording mocks of storage.Provider and storage.Presigner

Documentation

The full documentation is on the docs site. This README is deliberately a signpost: keeping a second copy here is how the docs drifted before.

License

MIT

Documentation

Overview

Package storage defines what every object store of the module promises: the buckets and objects of Provider, the presigned URLs of Presigner, the rules their inputs keep, how they honor a context, their lifecycle, and the errors they return.

The rules are Amazon S3's, checked before any I/O on every backend, so that code tested against one backend runs on another. The backends implement Provider, gas.Service and gas.ReadyReporter, and each lives in its own package:

  • gas/storage/s3: Amazon S3, or a server that speaks its API; it is also a Presigner.
  • gas/storage/dir: a directory on a local disk, for a single host.
  • gas/storage/memory: a store in the process's memory, for tests and local development.
  • gas/storage/storagetest: mocks of Provider and Presigner, for tests.

Usage

Each backend's New returns a constructor in the shape the gas container expects, so a backend is registered as storage.Provider:

gas.WithSingletonService[storage.Provider](memory.New())

A Provider then writes and reads objects of a bucket:

err := store.CreateBucket(ctx, &storage.CreateBucketInput{Bucket: "photos"})

_, err = store.PutObject(ctx, &storage.PutObjectInput{
	Bucket:        &bucket,
	Key:           "cats/tom.jpg",
	Body:          bytes.NewReader(jpeg),
	ContentLength: &size,
	ContentType:   &contentType,
	Metadata:      map[string]string{"Author": "Ann"},
})

obj, err := store.GetObject(ctx, &storage.GetObjectInput{Bucket: &bucket, Key: "cats/tom.jpg"})
defer obj.Body.Close()

After this, with bucket `photos` and contentType `image/jpeg`:

  • obj.Body yields the bytes of jpeg.
  • obj.ContentType is `image/jpeg`.
  • obj.Metadata holds `author`, in lower case.

The fields of the embedded BaseObjectInput, ObjectHeaders and WriteCondition are set as the input's own.

Contract

Every backend, and any Provider that wants to be one, keeps the rules below. The module's conformance tests run every backend through them, with identical expectations; a rule a backend cannot keep is listed in its package documentation.

A method checks these, in this order, and returns the first failure before any I/O:

  1. Its arguments: a nil input is ErrNilInput.
  2. The backend's state and the context.
  3. The input's rules, in the order the sections below give.

The state comes before the rules because the configured bucket is part of the configuration.

The other rules:

  • Every method returns the context's error, wrapped, when its context has ended before it starts, and honors the context during the call. PutObject checks its context between reads of the body, so a body whose Read blocks holds the call until it returns. Close is the exception: it always closes.
  • A write is whole or nothing. PutObject stores the object once its body is read to the end and its condition holds, and CopyObject once it has read the source whole. A failed write leaves the object under the key, if any, as it was.
  • A read sees an object as one write stored it.
  • A backend never changes the caller's input, and keeps none of its maps. What it returns is the caller's own copy.
  • A constructor refuses, in this order, a nil logger (ErrNilLogger), a nil option (ErrNilOption) and a nil configuration given to its WithConfig (ErrNilConfig).

Lifecycle

A backend's methods answer according to its Init and Close:

  • Before its first successful Init, every method but Init, Close and Name returns ErrNotInitialized, and so does a nil backend.
  • Init on an initialized backend returns ErrAlreadyInitialized and changes nothing.
  • After Close, until Init succeeds again, every method but Init, Close and Name returns ErrClosed.
  • Close on a backend that is not initialized returns nil.
  • Close then Init restarts the backend. The buckets and objects outlive a restart.

Close refuses new calls at once, and returns once every call in flight has returned. When its context ends first, it cancels the calls in flight, which return ErrClosed, and returns an error wrapping the context's error. The backend stays closed.

A Body that GetObject returned is not a call in flight: it stays readable after Close, until it is closed.

Buckets

A bucket name keeps S3's rules for a general purpose bucket. CheckBucket checks them, in this order, and a broken rule is ErrInvalidBucket:

  1. MinBucketLength, 3, to MaxBucketLength, 63, bytes.
  2. Only lower case letters, digits, dots and hyphens.
  3. A letter or a digit first and last.
  4. No two dots in a row.
  5. Not four runs of digits joined by dots, as an IPv4 address is.

S3's reserved starts and ends, such as `xn--` and `-s3alias`, are not checked: S3 refuses them itself, and the other backends accept them.

An object's input names its bucket in BaseObjectInput.Bucket:

  • A nil Bucket is the backend's configured bucket, the `storage.bucket` setting. With none configured it is ErrInvalidBucket, as ResolveBucket returns.
  • A pointer to an empty name is an empty name, not the configured bucket.

The inputs of the bucket methods name their bucket, with no default.

The bucket methods answer:

  • CreateBucket of a bucket the caller owns already is not an error. ErrBucketExists means another owner has the name, which only a shared namespace, such as S3's, can report.
  • HeadBucket of a missing bucket, and DeleteBucket of one, are ErrBucketNotFound.
  • DeleteBucket of a bucket that holds an object is ErrBucketNotEmpty.
  • HeadBucket returns the name and the region. ListBuckets also returns the creation date.

Keys

An object key keeps these rules. CheckKey checks them, in this order, and a broken rule is ErrInvalidKey:

  1. It is 1 to MaxKeyLength, 1024, bytes.
  2. It is valid UTF-8.
  3. It holds no control character: a byte below 0x20, the tab included, or DEL.
  4. Its last element, with `/` as the only separator on every platform, is not `.`, and it does not clean to `.`. So `a/.`, `./` and `.` are refused, and `a\.` is not.

The key is checked before the bucket.

Objects

PutObject reads Body to its end:

  • A nil Body is an empty object.
  • With ContentLength set, Body must yield exactly that many bytes, as CheckLength holds it. One more or one fewer is ErrContentLengthMismatch.
  • A negative ContentLength is ErrInvalidArgument.
  • An error of Body's Read is returned wrapped, after `read body: `, and errors.Is finds it.

PutObject returns the ETag, the size and, on a backend that keeps versions, the version it wrote.

ObjectInfo.ETag identifies the contents, without quotes. On the memory and dir backends, and on S3 for an object written in one part without SSE-KMS, it is the hex MD5 of the contents; compare it only for equality. LastModified and CreationDate are in UTC, to the second.

A missing object or bucket:

  • HeadObject and GetObject of a key that holds no object are ErrObjectNotFound. When the backend can tell that the bucket is missing, the error wraps ErrBucketNotFound too.
  • DeleteObject of such a key is not an error.
  • DeleteObject, PutObject and ListObjects of a missing bucket are ErrBucketNotFound.

Versions and parts:

  • A Version that is set must not be empty, and a PartNumber is 1 to MaxPartNumber, 10000, and not set with a Range (ErrInvalidArgument).
  • On a backend that keeps no versions, or no parts, a Version or a PartNumber is ErrNotSupported, after the rules and before any I/O.
  • On a backend that keeps versions, a version that does not exist is ErrVersionNotFound with ErrObjectNotFound.

Header fields

ObjectHeaders sets the Content-Type, Cache-Control, Content-Disposition, Content-Encoding, Content-Language and Expires of an object, and a read returns each in HeaderValues as it was written. A nil ContentType is DefaultContentType, `application/octet-stream`; any other nil field is not stored, and reads back empty.

A value that is set keeps these rules:

  • It is not empty.
  • It holds only printable ASCII, space and tab, so never a CR or an LF.
  • It neither starts nor ends with a space or a tab, as an HTTP field value would lose them.
  • It holds at most MaxHeaderSize, 1024, bytes.
  • Expires is also an IMF-fixdate exactly as http.TimeFormat writes it, such as `Wed, 21 Oct 2015 07:28:00 GMT`, as ParseExpires reads it.

Text that is not ASCII must be encoded by the caller, such as with mime.QEncoding or RFC 8187 for a file name.

CheckHeaders checks the fields in the order ContentType, CacheControl, ContentDisposition, ContentEncoding, ContentLanguage, Expires. A broken rule is ErrInvalidHeader, whose error names the field, never its value. The header fields are checked after the ContentLength.

Metadata

ObjectHeaders.Metadata is the user metadata, which S3 sends as `x-amz-meta-` header fields. Every backend keeps to S3's rules:

  • A name is an HTTP token, one or more letters, digits and “!#$%&'*+-.^_`|~“. It is stored and returned in lower case, so two names that differ only in case are refused.
  • A value keeps the rules of a header field's value, but for the IMF-fixdate.
  • The names and values hold at most MaxMetadataSize, 2048, bytes together, as S3's 2 KB.

A value that is not ASCII is refused, never encoded: encode it before, such as with mime.QEncoding, and decode it after.

CheckMetadata checks each entry in the sorted order of the names, the name then the value; then the case, then the size. A broken rule is ErrInvalidMetadata, whose error quotes no name or value. The metadata is checked after the header fields.

Conditions

PutObjectInput.WriteCondition makes a write depend on the object it would replace, as CheckCondition checks it:

  • IfNoneMatch, which must be `*`, writes only when no object is stored under the key.
  • IfMatch, an ETag quoted or not, writes only over an object with that ETag, and is ErrObjectNotFound when there is none.

A condition that does not hold is ErrPreconditionFailed, and nothing is written. The condition is evaluated when the write commits, after the body is read, so of two writes with IfNoneMatch that race, one wins.

These are ErrInvalidCondition, checked after the metadata:

  • IfNoneMatch and IfMatch both set.
  • An IfNoneMatch other than `*`.
  • An IfMatch that is empty, `*`, or not one entity tag.

An optimistic update is a HeadObject, then a PutObject with IfMatch set to the ETag it returned.

Copies

CopyObject copies an object, as S3's CopyObject does. The embedded BaseObjectInput of CopyObjectInput names the destination, and Source the source. Each takes a nil Bucket as the configured bucket, so a copy may go to another bucket.

What the destination gets depends on Replace:

  • By default, it gets the source's contents, header fields and metadata. Every field of the embedded ObjectHeaders must be nil, and Metadata empty.
  • With Replace set, it gets the header fields and metadata of ObjectHeaders instead, as S3's REPLACE metadata directive does. They keep the rules of PutObject's, a nil ContentType as DefaultContentType.

A copy of an object onto itself, the same bucket and key, is refused without Replace, as S3 refuses it. With Replace it replaces the object's header fields and metadata and keeps its contents.

_, err := store.CopyObject(ctx, &storage.CopyObjectInput{
	Bucket: &archive,
	Key:    "cats/tom.jpg",
	Source: storage.BaseObjectInput{Key: "cats/tom.jpg"},
})

After this, with the bucket `photos` configured and `archive` set to `archive`, the bucket `archive` holds a copy of `cats/tom.jpg` of `photos`, with its header fields and metadata.

CheckCopy checks these, in this order, all before any I/O:

  1. The source's key and bucket, its errors after `source: `.
  2. The destination's, its errors after `destination: `.
  3. With Replace, the header fields and the metadata. Without it, that none is set and that the source is not the destination (ErrInvalidArgument).

CopyObject then looks up the source, then the destination's bucket:

  • A missing source is ErrObjectNotFound, and a source in a missing bucket ErrObjectNotFound and ErrBucketNotFound, as GetObject reports them.
  • A missing destination bucket is ErrBucketNotFound, as PutObject reports it.
  • A source longer than MaxCopySize, 5 GiB, the most one S3 CopyObject copies, is ErrInvalidArgument, as CheckCopySize returns it, and nothing is written.

There is no copy in parts and no conditional copy. The copy is written whole or not at all. CopyObject returns its ETag, its size and, on a backend that keeps versions, its version, as PutObject does; its LastModified is when it was written.

Ranges

HeadObjectInput.Range and GetObjectInput's select a range of the object's bytes. The value is that of an HTTP Range header that holds one byte range, as ParseRange reads it: `bytes=first-last`, `bytes=first-` or `bytes=-suffix`, with spaces and tabs around it and the unit in any case.

Anything else, such as another unit, two ranges or a last byte before the first, is ErrInvalidRange rather than ignored. It is checked after the bucket, before any I/O.

Against the object's size:

  • A last byte past the end is the end.
  • A suffix longer than the object is the whole of it.
  • A first byte at or past the end, and `bytes=-0`, are ErrRangeNotSatisfiable.
  • On an empty object, every first-last range is ErrRangeNotSatisfiable too, and a suffix of one byte or more selects nothing.

With a Range, ObjectInfo.Size is the length of the bytes selected.

Listing

ListObjects and ListBuckets return a page at a time, as S3's ListObjectsV2 and ListBuckets do, in the byte order of the keys or the names:

  • A page of objects holds at most MaxKeys objects and common prefixes together, 1 to MaxListKeys, 1000, which is the default.
  • A page of buckets holds at most MaxBuckets, 1 to MaxListBuckets, 10000, the default.

NextContinuationToken resumes the listing after its page, and is empty on the last page, and only there; ListObjects also reports IsTruncated. A listing is not a snapshot: an object written between two pages may or may not be listed.

in := &storage.ListObjectsInput{Prefix: &prefix}
for {
	out, err := store.ListObjects(ctx, in)
	if err != nil {
		return err
	}
	// use out.Objects and out.CommonPrefixes
	if !out.IsTruncated {
		break
	}
	in.ContinuationToken = &out.NextContinuationToken
}

The inputs narrow the listing:

  • Prefix limits the listing to the keys, or names, that start with it.
  • StartAfter starts it after a key, which need not exist.
  • A Delimiter rolls up each key that holds it after Prefix into the common prefix that ends with its first Delimiter after Prefix. StartAfter applies to the keys before they are rolled up, and each common prefix is listed once across the pages, in the place of its first key.

Prefix, Delimiter and StartAfter are valid UTF-8 of at most MaxKeyLength bytes, and a Delimiter that is set is not empty (ErrInvalidArgument).

A token is opaque, tells nothing of a key, and belongs to the backend and the listing that issued it. One that is empty, changed, or from another listing, is ErrInvalidToken.

The checks run in this order:

Presigning

A Presigner signs a request that a client sends to the backend without credentials, until PresignURLResponse.Expires: a PUT that uploads one object, or a GET that downloads one. The client sends the Method, the URL and every field of SignedHeader, unchanged; the backend refuses a request that differs, such as a body of another length.

The inputs keep the rules of PutObject and GetObject, as CheckPresignUpload and CheckPresignDownload check them, then:

  • An upload needs its ContentLength, 0 to MaxPresignUploadSize, 5 GiB, the most one S3 PUT takes, so that a URL never lets a client store more than was signed for (ErrInvalidArgument). It is checked after the bucket.
  • A download may set ResponseHeaders, which its response carries instead of the object's, such as a ResponseContentDisposition that names the file a browser saves. They keep the rules of the header fields, and are checked after the Version.
  • The TTL is DefaultPresignTTL, 15 minutes, when it is nil or 0, and else MinPresignTTL, 1 second, to MaxPresignTTL, 7 days, truncated to a whole second (ErrInvalidArgument), as CheckPresignTTL returns it. It is checked last.

Signing does no I/O, so a presigned request for a missing object or bucket fails only when the client sends it.

A URL is a credential until it expires: anyone who holds it may send its request. A URL signed with temporary credentials holds their session token, and stops being valid when they expire, whatever its TTL.

Security

Keys, metadata, header values and bodies are application data, often personal, and bucket names can name a customer.

No error a backend returns and no log it writes holds any of them, nor a path, an endpoint, a URL, a credential or a continuation token. The errors name the operation, the field and the rule instead. A backend never quotes an error of a third party that may hold them.

Concurrency

Every backend is safe for concurrent use, as each backend's package describes. The mocks are too, but for setting their fields while they are called.

The functions of this package are safe for concurrent use; a reader CheckLength returns is not.

Errors

Every error a backend returns is made of:

  1. Its service name, such as `gas/storage/memory`.
  2. The operation: `init`, `ready`, `close`, `create bucket`, `head bucket`, `delete bucket`, `list buckets`, `head object`, `put object`, `get object`, `delete object`, `list objects`, `copy object`, `presign upload` or `presign download`.
  3. What failed.

It wraps one of these sentinels, to be tested with errors.Is:

The errors of this package's checks, as returned, before a backend adds its service name and the operation:

invalid key: empty
invalid key: longer than 1024 bytes
invalid key: not valid UTF-8
invalid key: holds a control character
invalid key: its last path element is "."
invalid bucket: none given and none configured
invalid bucket: not 3 to 63 bytes
invalid bucket: holds a character other than a-z, 0-9, . and -
invalid bucket: does not start and end with a letter or a digit
invalid bucket: holds two dots in a row
invalid bucket: shaped like an IPv4 address
invalid argument: ContentLength is negative
invalid argument: ContentLength is required
invalid argument: ContentLength is not 0 to 5368709120
invalid header: ContentType is empty
invalid header: CacheControl holds a character other than printable ASCII, space and tab
invalid header: ContentLanguage starts or ends with a space or a tab
invalid header: ContentDisposition is longer than 1024 bytes
invalid header: Expires is not an IMF-fixdate
invalid header: ResponseContentDisposition holds a character other than printable ASCII, space and tab
invalid metadata: a name is not an HTTP token
invalid metadata: a value is empty
invalid metadata: a value holds a character other than printable ASCII, space and tab
invalid metadata: a value starts or ends with a space or a tab
invalid metadata: two names differ only in case
invalid metadata: 2049 bytes, more than 2048
invalid condition: IfMatch and IfNoneMatch are both set
invalid condition: IfNoneMatch is not "*"
invalid condition: IfMatch is not one entity tag
invalid range: not one byte range
invalid argument: PartNumber is not 1 to 10000
invalid argument: PartNumber and Range are both set
invalid argument: Version is empty
invalid argument: MaxKeys is not 1 to 1000
invalid argument: MaxBuckets is not 1 to 10000
invalid argument: Prefix is not valid UTF-8 of at most 1024 bytes
invalid argument: Delimiter is empty
invalid argument: TTL is not 1s to 168h0m0s
source: invalid key: empty
destination: invalid bucket: none given and none configured
invalid argument: header fields or metadata set without Replace
invalid argument: copies an object onto itself without Replace
invalid argument: source is longer than 5368709120 bytes
invalid continuation token: empty
content length mismatch: body has 3 bytes, ContentLength is 5
content length mismatch: body is longer than ContentLength 5
read body: Read returned an invalid count
read body: multiple Read calls return no data or error
range not satisfiable

A backend that lists from its own store, as memory and dir do, refuses a token it did not issue for the listing with:

invalid continuation token: not one this backend issued for this listing

Index

Constants

View Source
const (
	// MaxKeyLength is the most bytes an object key holds, and the most a
	// Prefix, a Delimiter or a StartAfter of a listing holds.
	MaxKeyLength = 1024
	// MinBucketLength is the fewest bytes a bucket name holds.
	MinBucketLength = 3
	// MaxBucketLength is the most bytes a bucket name holds.
	MaxBucketLength = 63
	// MaxMetadataSize is the most bytes the names and values of the user
	// metadata of an object hold together: 2 KB, as on S3.
	MaxMetadataSize = 2048
	// MaxHeaderSize is the most bytes the value of a header field holds,
	// for each of the fields of ObjectHeaders and ResponseHeaders.
	MaxHeaderSize = 1024
	// MaxPartNumber is the highest PartNumber, as on S3.
	MaxPartNumber = 10000
	// MaxListKeys is the most objects and common prefixes a page of
	// ListObjects holds, and its default.
	MaxListKeys = 1000
	// MaxListBuckets is the most buckets a page of ListBuckets holds, and
	// its default.
	MaxListBuckets = 10000
	// DefaultContentType is the Content-Type of an object written without
	// one.
	DefaultContentType = "application/octet-stream"
	// DefaultPresignTTL is how long a presigned URL is valid when its TTL
	// is nil or 0.
	DefaultPresignTTL = 15 * time.Minute
	// MinPresignTTL is the shortest TTL of a presigned URL.
	MinPresignTTL = time.Second
	// MaxPresignTTL is the longest TTL of a presigned URL: seven days, as
	// on S3.
	MaxPresignTTL = 7 * 24 * time.Hour
	// MaxPresignUploadSize is the largest ContentLength of a presigned
	// upload: 5 GiB, the most one S3 PUT takes.
	MaxPresignUploadSize = 5 << 30
	// MaxCopySize is the longest source CopyObject copies: 5 GiB, the
	// most one S3 CopyObject copies.
	MaxCopySize = 5 << 30
)

The limits of the rules, as described in the package documentation.

Variables

View Source
var (
	// ErrNilInput indicates that a method was given a nil input.
	ErrNilInput = errors.New("input is nil")
	// ErrInvalidKey indicates that an object key breaks the key rules.
	ErrInvalidKey = errors.New("invalid key")
	// ErrInvalidBucket indicates that a bucket name breaks the bucket
	// rules, or that an input names no bucket and none is configured.
	ErrInvalidBucket = errors.New("invalid bucket")
	// ErrInvalidMetadata indicates that the user metadata of a write breaks
	// the metadata rules.
	ErrInvalidMetadata = errors.New("invalid metadata")
	// ErrInvalidHeader indicates that a header field of a write, or a
	// response header of a presigned download, breaks the header rules.
	ErrInvalidHeader = errors.New("invalid header")
	// ErrInvalidCondition indicates that a WriteCondition cannot be
	// evaluated.
	ErrInvalidCondition = errors.New("invalid condition")
	// ErrInvalidRange indicates that a Range is not one byte range.
	ErrInvalidRange = errors.New("invalid range")
	// ErrInvalidArgument indicates that a limit, a length, a part number, a
	// version, a listing argument or a presign TTL is out of its bounds.
	ErrInvalidArgument = errors.New("invalid argument")
	// ErrInvalidToken indicates that a continuation token is empty, or is
	// not one the backend issued for the same listing.
	ErrInvalidToken = errors.New("invalid continuation token")
	// ErrContentLengthMismatch indicates that a body yielded more or fewer
	// bytes than its ContentLength.
	ErrContentLengthMismatch = errors.New("content length mismatch")
	// ErrNotSupported indicates that an input asks for a feature the
	// backend does not have, such as a Version on a backend that does not
	// version objects.
	ErrNotSupported = errors.New("not supported")
	// ErrObjectNotFound indicates that no object is stored under the key,
	// or that its bucket does not exist.
	ErrObjectNotFound = errors.New("object not found")
	// ErrVersionNotFound indicates that the object exists but not the
	// version asked for. It comes with ErrObjectNotFound.
	ErrVersionNotFound = errors.New("version not found")
	// ErrBucketNotFound indicates that the bucket does not exist.
	ErrBucketNotFound = errors.New("bucket not found")
	// ErrBucketNotEmpty indicates that DeleteBucket found the bucket
	// holding objects.
	ErrBucketNotEmpty = errors.New("bucket not empty")
	// ErrBucketExists indicates that CreateBucket found the name taken by
	// another owner.
	ErrBucketExists = errors.New("bucket exists")
	// ErrAccessDenied indicates that the backend refused the credentials,
	// or their permission for the request.
	ErrAccessDenied = errors.New("access denied")
	// ErrPreconditionFailed indicates that a WriteCondition did not hold
	// when the write would have committed.
	ErrPreconditionFailed = errors.New("precondition failed")
	// ErrRangeNotSatisfiable indicates that a Range selects no byte of the
	// object.
	ErrRangeNotSatisfiable = errors.New("range not satisfiable")
	// ErrBackend indicates that the backend failed for a reason no other
	// sentinel names, such as an I/O error or a request that got no reply.
	ErrBackend = errors.New("backend failed")
	// ErrNotInitialized indicates that a method was called before the
	// backend's first successful Init.
	ErrNotInitialized = errors.New("service not initialized")
	// ErrAlreadyInitialized indicates that Init was called on a backend
	// that is initialized.
	ErrAlreadyInitialized = errors.New("service already initialized")
	// ErrClosed indicates that a method was called after Close, before
	// Init succeeded again, or that Close ended the call.
	ErrClosed = errors.New("service closed")
	// ErrNilLogger indicates that a backend's constructor was given a nil
	// logger.
	ErrNilLogger = errors.New("logger is nil")
	// ErrNilOption indicates that a backend's constructor was given a nil
	// option.
	ErrNilOption = errors.New("option is nil")
	// ErrNilConfig indicates that WithConfig was given a nil
	// configuration.
	ErrNilConfig = errors.New("config is nil")
	// ErrNoConfigProvider indicates that there is neither a configuration
	// given to WithConfig nor a ConfigProvider to bind one from.
	ErrNoConfigProvider = errors.New("no config provider")
	// ErrInvalidConfig indicates that the configuration failed to bind,
	// failed its validate tags, or broke one of the backend's rules.
	ErrInvalidConfig = errors.New("invalid config")
)

The sentinel errors every backend of the module shares, as described in the package documentation. A backend's errors start with its own service name and the operation, and wrap one of these.

Functions

func CheckBucket added in v0.6.0

func CheckBucket(name string) error

CheckBucket returns an error wrapping ErrInvalidBucket when name breaks the bucket rules of the package documentation, and nil otherwise. The error never quotes the name.

func CheckCondition added in v0.6.0

func CheckCondition(c *WriteCondition) (ifMatch string, ifNoneMatch bool, err error)

CheckCondition checks c, as described in the package documentation, and returns the ETag of IfMatch without its quotes, empty when IfMatch is not set, and whether IfNoneMatch is set.

func CheckCopySize added in v0.6.0

func CheckCopySize(size int64) error

CheckCopySize returns an error wrapping ErrInvalidArgument when size, the length of the source of a copy, is longer than MaxCopySize, and nil otherwise.

func CheckKey added in v0.6.0

func CheckKey(key string) error

CheckKey returns an error wrapping ErrInvalidKey when key breaks the key rules of the package documentation, and nil otherwise. The error never quotes the key.

func CheckLength added in v0.6.0

func CheckLength(body io.Reader, n *int64) (io.Reader, error)

CheckLength holds body to the declared length n, as described in the package documentation, and returns a reader of body's bytes. A nil body is an empty one, and a nil n a length that is not known. A negative n is an error wrapping ErrInvalidArgument. With n set, the reader fails with an error wrapping ErrContentLengthMismatch once body proves shorter or longer than n.

The reader never reads past n but to probe for one byte more, which it does as soon as n bytes are read, so a body that is too long is caught even by a caller that stops reading at n bytes. A body that blocks after n bytes without ending blocks the probe. An error of body's Read is returned wrapped, after `read body: `; so are a count below 0 or above the buffer's length, and 100 reads in a row of no byte and no error, as io.ErrNoProgress. Every error is returned again by every later Read.

func CheckMetadata added in v0.6.0

func CheckMetadata(md map[string]string) (map[string]string, error)

CheckMetadata checks md, as described in the package documentation, and returns a copy of it with the names in lower case, or nil for an empty md. The names are checked in their sorted order, each name then its value, then names that differ only in case, then the size. A broken rule is an error wrapping ErrInvalidMetadata that quotes no name or value.

func CheckPresignTTL added in v0.6.0

func CheckPresignTTL(ttl *time.Duration) (time.Duration, error)

CheckPresignTTL returns the TTL a presigned URL is signed for: DefaultPresignTTL for a nil or 0 ttl, else ttl truncated to a whole second. A ttl below MinPresignTTL or above MaxPresignTTL, a negative one included, is an error wrapping ErrInvalidArgument.

func ParseExpires added in v0.6.0

func ParseExpires(s string) (time.Time, error)

ParseExpires reads s as an Expires header field and returns the time it holds. s must be an IMF-fixdate exactly as http.TimeFormat writes it, such as `Wed, 21 Oct 2015 07:28:00 GMT`, with the right weekday, so that every backend stores and returns it unchanged. Anything else, including the obsolete RFC 850 and asctime forms, is an error that never quotes s.

func ResolveBucket added in v0.6.0

func ResolveBucket(given *string, configured string) (string, error)

ResolveBucket returns the bucket an input names: given, when it is not nil, else configured, the backend's configured bucket, which is empty when none is. The bucket chosen must keep the bucket rules; an empty configured one is an error wrapping ErrInvalidBucket.

Types

type BaseObjectInput added in v0.5.5

type BaseObjectInput struct {
	// Bucket is the bucket of the object. Nil is the configured bucket; a
	// pointer to an empty name is not.
	Bucket *string
	// Key is the key of the object.
	Key string
}

BaseObjectInput names an object. Every object operation's input embeds it.

type Bucket added in v0.6.0

type Bucket struct {
	// CreationDate is when the bucket was created, in UTC to the second.
	// ListBuckets sets it; HeadBucket leaves it zero.
	CreationDate time.Time
	// Name is the name of the bucket.
	Name string
	// Region is the region the bucket is in, or empty on a backend that has
	// no regions.
	Region string
}

Bucket describes a bucket.

type ByteRange added in v0.6.0

type ByteRange struct {
	// contains filtered or unexported fields
}

ByteRange is one byte range of an HTTP Range header, as ParseRange reads it. The zero ByteRange is `bytes=0-0`, the first byte.

func ParseRange added in v0.6.0

func ParseRange(s string) (ByteRange, error)

ParseRange reads s as an HTTP Range header that holds one byte range, as described in the package documentation: `bytes=first-last`, `bytes=first-` or `bytes=-suffix`, where first, last and suffix are decimal digits and first is at most last. Spaces and tabs around s are ignored, and the unit is matched in any case. A number too large for an int64 is read as math.MaxInt64, which is past the end of any object. Anything else, such as another unit, a list of ranges or a sign, is ErrInvalidRange, and the error never quotes s.

func (ByteRange) Resolve added in v0.6.0

func (r ByteRange) Resolve(size int64) (offset, length int64, err error)

Resolve returns the offset and the length of the bytes r selects from an object of size bytes, as described in the package documentation: a last byte past the end is the end, and a suffix longer than the object is the whole object. A range whose first byte is at or past the end, and the suffix `bytes=-0`, select nothing and are ErrRangeNotSatisfiable; on an empty object only a suffix of at least one byte is satisfiable, and selects nothing. size must not be negative.

func (ByteRange) String added in v0.6.0

func (r ByteRange) String() string

String returns r as the value of an HTTP Range header, such as `bytes=0-99`, in the form ParseRange reads.

type CopyObjectInput added in v0.6.0

type CopyObjectInput struct {
	BaseObjectInput
	ObjectHeaders

	// Source names the object copied, as BaseObjectInput does: a nil
	// Bucket is the configured bucket.
	Source BaseObjectInput
	// Replace gives the destination the header fields and metadata of
	// ObjectHeaders, nil ContentType as DefaultContentType, instead of the
	// source's, as S3's REPLACE metadata directive does. Without it every
	// field of ObjectHeaders must be nil, and Metadata empty.
	Replace bool
}

CopyObjectInput names the object CopyObject copies and the object it writes, as S3's CopyObject does: the embedded BaseObjectInput names the destination, and Source the source. By default the copy keeps the source's header fields and metadata; with Replace set it gets those of the embedded ObjectHeaders instead, as PutObject would store them.

type CopyObjectOutput added in v0.6.0

type CopyObjectOutput struct {
	// ETag identifies the contents written, as ObjectInfo.ETag.
	ETag string
	// Version identifies the version written, or is empty on a backend
	// that does not keep versions.
	Version string
	// Size is the length of the contents written, in bytes.
	Size int64
}

CopyObjectOutput is what CopyObject reports of the object it wrote, as PutObjectOutput does.

type CopyRequest added in v0.6.0

type CopyRequest struct {
	// HeaderValues are the header fields the destination gets when
	// Replace is set, ContentType DefaultContentType for a nil one, and
	// else empty.
	HeaderValues

	// Source is the object copied.
	Source ObjectRef
	// Destination is the object written.
	Destination ObjectRef
	// Metadata is a copy of the user metadata the destination gets when
	// Replace is set, with the names in lower case, or nil when there is
	// none or Replace is not set.
	Metadata map[string]string
	// Replace reports whether the destination gets HeaderValues and
	// Metadata rather than the source's.
	Replace bool
}

CopyRequest is a CopyObjectInput that the rules have checked.

func CheckCopy added in v0.6.0

func CheckCopy(in *CopyObjectInput, configured string) (CopyRequest, error)

CheckCopy checks in as described in the package documentation: the source's key and bucket, after `source: `, the destination's, after `destination: `, then, with Replace, the header fields and the metadata, and without it, that none is set and that the source is not the destination.

type CreateBucketInput added in v0.5.5

type CreateBucketInput struct {
	// Bucket is the name of the bucket. The configured bucket is not a
	// default.
	Bucket string
}

CreateBucketInput names the bucket CreateBucket creates.

type DeleteBucketInput added in v0.6.0

type DeleteBucketInput struct {
	// Bucket is the name of the bucket. The configured bucket is not a
	// default.
	Bucket string
}

DeleteBucketInput names the bucket DeleteBucket deletes.

type DeleteObjectInput added in v0.5.5

type DeleteObjectInput struct {
	BaseObjectInput

	// Version deletes one version of the object, on a backend that keeps
	// versions, instead of the latest.
	Version *string
}

DeleteObjectInput names the object DeleteObject deletes.

type GetObjectInput added in v0.5.5

type GetObjectInput struct {
	HeadObjectInput
}

GetObjectInput names the object GetObject returns, and what part of it, as HeadObjectInput does.

type HeadBucketInput added in v0.6.0

type HeadBucketInput struct {
	// Bucket is the name of the bucket. The configured bucket is not a
	// default.
	Bucket string
}

HeadBucketInput names the bucket HeadBucket describes.

type HeadObjectInput added in v0.5.5

type HeadObjectInput struct {
	BaseObjectInput

	// PartNumber selects one part of an object uploaded in parts, from 1,
	// on a backend that stores parts.
	PartNumber *int32
	// Range selects a range of the object's bytes, as the value of an HTTP
	// Range header holding one byte range.
	Range *string
	// Version selects a version of the object, on a backend that keeps
	// versions, instead of the latest.
	Version *string
}

HeadObjectInput names the object HeadObject describes, and what part of it.

type HeaderValues added in v0.6.0

type HeaderValues struct {
	// CacheControl is the object's Cache-Control.
	CacheControl string
	// ContentDisposition is the object's Content-Disposition.
	ContentDisposition string
	// ContentEncoding is the object's Content-Encoding.
	ContentEncoding string
	// ContentLanguage is the object's Content-Language.
	ContentLanguage string
	// ContentType is the object's Content-Type.
	ContentType string
	// Expires is the object's Expires, an IMF-fixdate.
	Expires string
}

HeaderValues are the header fields stored with an object, each empty when it is not stored.

func CheckHeaders added in v0.6.0

func CheckHeaders(h *ObjectHeaders) (HeaderValues, error)

CheckHeaders checks the header fields of h, in the order ContentType, CacheControl, ContentDisposition, ContentEncoding, ContentLanguage, Expires, as described in the package documentation, and returns their values: ContentType is DefaultContentType when it is nil. A field that breaks a rule is an error wrapping ErrInvalidHeader that names the field, never its value.

func CheckResponseHeaders added in v0.6.0

func CheckResponseHeaders(h *ResponseHeaders) (HeaderValues, error)

CheckResponseHeaders checks the fields of h as CheckHeaders checks those of an ObjectHeaders, in the same order, and returns their values, each empty when its field is nil.

type ListBucketsInput added in v0.5.6

type ListBucketsInput struct {
	// ContinuationToken resumes a listing after the page whose
	// NextContinuationToken it is. Nil starts at the first bucket.
	ContinuationToken *string
	// MaxBuckets is the most buckets the page holds, 1 to MaxListBuckets.
	// Nil is MaxListBuckets.
	MaxBuckets *int32
	// Prefix limits the listing to the buckets whose names start with it.
	Prefix *string
}

ListBucketsInput selects the page of buckets ListBuckets returns. The zero value selects the first page of every bucket.

type ListBucketsOutput added in v0.5.6

type ListBucketsOutput struct {
	// NextContinuationToken resumes the listing after this page. It is
	// empty on the last page, and only there.
	NextContinuationToken string
	// Buckets are the buckets of the page, in the byte order of their
	// names.
	Buckets []Bucket
}

ListBucketsOutput is one page of buckets.

type ListBucketsRequest added in v0.6.0

type ListBucketsRequest struct {
	// Prefix is the prefix every name listed starts with.
	Prefix string
	// ContinuationToken is the token to resume after, or empty for the
	// first page.
	ContinuationToken string
	// MaxBuckets is the most buckets of the page.
	MaxBuckets int
}

ListBucketsRequest is a ListBucketsInput that the rules have checked, with every nil field empty.

func CheckListBuckets added in v0.6.0

func CheckListBuckets(in *ListBucketsInput) (ListBucketsRequest, error)

CheckListBuckets checks in, as described in the package documentation: MaxBuckets, Prefix, then the ContinuationToken, which must not be empty.

type ListObjectsInput added in v0.5.6

type ListObjectsInput struct {
	// Bucket is the bucket to list. Nil is the configured bucket, as in
	// BaseObjectInput.
	Bucket *string
	// ContinuationToken resumes a listing after the page whose
	// NextContinuationToken it is. Nil starts at the first key.
	ContinuationToken *string
	// Delimiter rolls up the keys that hold it after Prefix into common
	// prefixes.
	Delimiter *string
	// MaxKeys is the most objects and common prefixes the page holds
	// together, 1 to MaxListKeys. Nil is MaxListKeys.
	MaxKeys *int32
	// Prefix limits the listing to the keys that start with it.
	Prefix *string
	// StartAfter starts the listing after this key, which need not exist.
	StartAfter *string
}

ListObjectsInput selects the page of objects ListObjects returns, as S3's ListObjectsV2 does. Every field is optional.

type ListObjectsOutput added in v0.5.6

type ListObjectsOutput struct {
	// NextContinuationToken resumes the listing after this page. It is
	// empty on the last page, and only there.
	NextContinuationToken string
	// Objects are the objects of the page, in the byte order of their
	// keys.
	Objects []ObjectSummary
	// CommonPrefixes are the prefixes Delimiter rolled keys up into, in
	// byte order. Each is listed once across the pages of a listing.
	CommonPrefixes []string
	// IsTruncated reports whether another page follows.
	IsTruncated bool
}

ListObjectsOutput is one page of objects.

type ListObjectsRequest added in v0.6.0

type ListObjectsRequest struct {
	// Bucket is the bucket to list.
	Bucket string
	// Prefix is the prefix every key listed starts with.
	Prefix string
	// Delimiter rolls up keys into common prefixes, or is empty for none.
	Delimiter string
	// StartAfter is the key the listing starts after.
	StartAfter string
	// ContinuationToken is the token to resume after, or empty for the
	// first page.
	ContinuationToken string
	// MaxKeys is the most entries of the page.
	MaxKeys int
}

ListObjectsRequest is a ListObjectsInput that the rules have checked, with every nil field empty.

func CheckListObjects added in v0.6.0

func CheckListObjects(in *ListObjectsInput, configured string) (ListObjectsRequest, error)

CheckListObjects checks in, as described in the package documentation: the bucket, MaxKeys, Prefix, Delimiter, StartAfter, then the ContinuationToken, which must not be empty. It does not tell whether the backend issued the token.

type Object added in v0.5.5

type Object struct {
	ObjectInfo

	// Body yields the bytes selected. The caller closes it, which frees the
	// file or the connection behind it.
	Body io.ReadCloser
}

Object is an object GetObject returns: its description and a reader of the bytes selected.

type ObjectHeaders added in v0.6.0

type ObjectHeaders struct {
	// Metadata is the user metadata, by name. Names are stored in lower
	// case.
	Metadata map[string]string
	// CacheControl is stored as the object's Cache-Control.
	CacheControl *string
	// ContentDisposition is stored as the object's Content-Disposition.
	ContentDisposition *string
	// ContentEncoding is stored as the object's Content-Encoding. The body
	// is stored as given, neither decoded nor encoded.
	ContentEncoding *string
	// ContentLanguage is stored as the object's Content-Language.
	ContentLanguage *string
	// ContentType is stored as the object's Content-Type.
	ContentType *string
	// Expires is stored as the object's Expires, an IMF-fixdate such as
	// `Wed, 21 Oct 2015 07:28:00 GMT`.
	Expires *string
}

ObjectHeaders are the header fields and the user metadata a write stores with an object, as described in the package documentation. A nil field is not stored, but for ContentType, which is then DefaultContentType.

type ObjectInfo added in v0.5.5

type ObjectInfo struct {
	HeaderValues

	// LastModified is when the object was written, in UTC to the second.
	LastModified time.Time
	// Metadata is the user metadata, with names in lower case. It is
	// empty when the object has none. It is the caller's own copy.
	Metadata map[string]string
	// ETag identifies the object's contents, without quotes. Compare it
	// only for equality: on some backends it is not a digest of the
	// contents.
	ETag string
	// Version identifies the version of the object, or is empty on a
	// backend that does not keep versions.
	Version string
	// Size is the length of the bytes selected: the object's length, or
	// that of its Range.
	Size int64
}

ObjectInfo describes a stored object, as HeadObject and GetObject return it.

type ObjectRef added in v0.6.0

type ObjectRef struct {
	// Bucket is the bucket of the object.
	Bucket string
	// Key is the key of the object.
	Key string
	// Version is the version asked for, or empty for the latest.
	Version string
}

ObjectRef is an object that the rules have checked: its bucket, with the configured one put in for a nil Bucket, its key, and the version asked for, if any.

func CheckDelete added in v0.6.0

func CheckDelete(in *DeleteObjectInput, configured string) (ObjectRef, error)

CheckDelete checks in as described in the package documentation: the key, the bucket, then the Version.

func CheckObject added in v0.6.0

func CheckObject(in *BaseObjectInput, configured string) (ObjectRef, error)

CheckObject checks the key, then the bucket, of in, as described in the package documentation, and returns the object it names.

type ObjectSummary added in v0.5.6

type ObjectSummary struct {
	// LastModified is when the object was written, in UTC to the second.
	LastModified time.Time
	// Key is the key of the object.
	Key string
	// ETag identifies the object's contents, as ObjectInfo.ETag.
	ETag string
	// Size is the length of the object, in bytes.
	Size int64
}

ObjectSummary describes an object in a page of ListObjects.

type PresignDownloadRequest added in v0.6.0

type PresignDownloadRequest struct {
	ReadRequest

	// Response holds the response header fields to send instead of the
	// object's, each empty to keep the object's.
	Response HeaderValues
	// TTL is how long the URL is valid.
	TTL time.Duration
}

PresignDownloadRequest is a PresignDownloadURLInput that the rules have checked.

func CheckPresignDownload added in v0.6.0

func CheckPresignDownload(
	in *PresignDownloadURLInput,
	configured string,
) (PresignDownloadRequest, error)

CheckPresignDownload checks in, as described in the package documentation: as CheckRead does, then the response header fields, then the TTL.

type PresignDownloadURLInput added in v0.5.5

type PresignDownloadURLInput struct {
	GetObjectInput
	// ResponseHeaders are the header fields the download's response
	// carries instead of the object's.
	ResponseHeaders

	// TTL is how long the URL is valid, as in PresignUploadURLInput.
	TTL *time.Duration
}

PresignDownloadURLInput describes the download a presigned URL allows.

type PresignURLResponse added in v0.5.5

type PresignURLResponse struct {
	// SignedHeader holds the header fields the signature covers, which the
	// client sends as they are.
	SignedHeader http.Header
	// Expires is when the URL stops being valid, at the latest.
	Expires time.Time
	// URL is the presigned URL. It is a credential until it expires.
	URL string
	// Method is the HTTP method the URL is signed for.
	Method string
}

PresignURLResponse is a presigned request: the method, the URL and the header fields the client must send with it, unchanged.

type PresignUploadRequest added in v0.6.0

type PresignUploadRequest struct {
	PutRequest

	// TTL is how long the URL is valid.
	TTL time.Duration
}

PresignUploadRequest is a PresignUploadURLInput that the rules have checked.

func CheckPresignUpload added in v0.6.0

func CheckPresignUpload(
	in *PresignUploadURLInput,
	configured string,
) (PresignUploadRequest, error)

CheckPresignUpload checks in, as described in the package documentation: the key, the bucket, the ContentLength, the header fields, the metadata, the condition, then the TTL. Body is nil.

type PresignUploadURLInput added in v0.5.5

type PresignUploadURLInput struct {
	BaseObjectInput
	ObjectHeaders
	WriteCondition

	// ContentLength is the length of the body the client must send, 0 to
	// MaxPresignUploadSize. It is required.
	ContentLength *int64
	// TTL is how long the URL is valid, MinPresignTTL to MaxPresignTTL.
	// Nil or 0 is DefaultPresignTTL.
	TTL *time.Duration
}

PresignUploadURLInput describes the upload a presigned URL allows.

type Presigner added in v0.5.5

type Presigner interface {
	// PresignUploadURL returns a request that uploads the object in.
	PresignUploadURL(ctx context.Context, in *PresignUploadURLInput) (*PresignURLResponse, error)
	// PresignDownloadURL returns a request that downloads the object in.
	PresignDownloadURL(
		ctx context.Context,
		in *PresignDownloadURLInput,
	) (*PresignURLResponse, error)
}

Presigner issues presigned URLs: URLs that let a client holding no credentials upload or download one object, directly with the backend, until they expire, as described in the package documentation.

type Provider added in v0.5.5

type Provider interface {
	// CreateBucket creates a bucket. Creating a bucket the caller owns
	// already is not an error.
	CreateBucket(ctx context.Context, in *CreateBucketInput) error
	// HeadBucket describes a bucket, or returns ErrBucketNotFound.
	HeadBucket(ctx context.Context, in *HeadBucketInput) (*Bucket, error)
	// DeleteBucket deletes an empty bucket.
	DeleteBucket(ctx context.Context, in *DeleteBucketInput) error
	// ListBuckets returns one page of the caller's buckets, in the byte
	// order of their names.
	ListBuckets(ctx context.Context, in *ListBucketsInput) (*ListBucketsOutput, error)
	// HeadObject describes an object without its contents.
	HeadObject(ctx context.Context, in *HeadObjectInput) (*ObjectInfo, error)
	// PutObject writes an object, replacing the one stored under its key,
	// if any, at once and whole.
	PutObject(ctx context.Context, in *PutObjectInput) (*PutObjectOutput, error)
	// GetObject returns an object with a reader of its contents, which the
	// caller closes.
	GetObject(ctx context.Context, in *GetObjectInput) (*Object, error)
	// DeleteObject deletes an object. Deleting a key that holds none is
	// not an error.
	DeleteObject(ctx context.Context, in *DeleteObjectInput) error
	// ListObjects returns one page of the objects of a bucket, in the byte
	// order of their keys.
	ListObjects(ctx context.Context, in *ListObjectsInput) (*ListObjectsOutput, error)
	// CopyObject copies an object, within a bucket or to another, and
	// writes the copy at once and whole, as PutObject does.
	CopyObject(ctx context.Context, in *CopyObjectInput) (*CopyObjectOutput, error)
}

Provider is an object store: it creates, describes, lists and deletes buckets, and writes, reads, describes, lists and deletes the objects they hold, as described in the package documentation. Every backend of the module implements it, and is safe for concurrent use.

type PutObjectInput added in v0.5.5

type PutObjectInput struct {
	BaseObjectInput
	ObjectHeaders
	WriteCondition

	// Body yields the contents. Nil is an empty object. It may be any
	// reader, including one that cannot seek or whose length is unknown.
	Body io.Reader
	// ContentLength is the length of Body in bytes, when it is known. Nil
	// is unknown. When it is set, Body must yield exactly that many bytes.
	ContentLength *int64
}

PutObjectInput describes the object PutObject writes.

type PutObjectOutput added in v0.6.0

type PutObjectOutput struct {
	// ETag identifies the contents written, as ObjectInfo.ETag.
	ETag string
	// Version identifies the version written, or is empty on a backend
	// that does not keep versions.
	Version string
	// Size is the length of the contents written, in bytes.
	Size int64
}

PutObjectOutput is what PutObject reports of the object it wrote.

type PutRequest added in v0.6.0

type PutRequest struct {
	ObjectRef
	HeaderValues

	// Body yields the contents, held to ContentLength as CheckLength
	// holds it. It is never nil for a PutObjectInput, and always nil for a
	// presigned upload, whose client sends the body.
	Body io.Reader
	// Metadata is a copy of the user metadata with the names in lower
	// case, or nil when there is none.
	Metadata map[string]string
	// IfMatch is the ETag of IfMatch without quotes, or empty when it is
	// not set.
	IfMatch string
	// ContentLength is the declared length, or -1 when it is not known.
	ContentLength int64
	// IfNoneMatch reports whether IfNoneMatch is set.
	IfNoneMatch bool
}

PutRequest is a PutObjectInput, or a PresignUploadURLInput, that the rules have checked.

func CheckPut added in v0.6.0

func CheckPut(in *PutObjectInput, configured string) (PutRequest, error)

CheckPut checks in as described in the package documentation: the key, the bucket, the ContentLength, the header fields, the metadata, then the condition. Body is the request's body held to ContentLength by CheckLength, and never nil.

type ReadRequest added in v0.6.0

type ReadRequest struct {
	ObjectRef

	// Range is the byte range asked for, or nil for the whole object.
	Range *ByteRange
	// PartNumber is the part asked for, or 0 for none.
	PartNumber int32
}

ReadRequest is a HeadObjectInput or a GetObjectInput that the rules have checked.

func CheckRead added in v0.6.0

func CheckRead(in *HeadObjectInput, configured string) (ReadRequest, error)

CheckRead checks in as described in the package documentation: the key, the bucket, the Range, the PartNumber, then the Version.

type ResponseHeaders added in v0.6.0

type ResponseHeaders struct {
	// ResponseCacheControl is the response's Cache-Control.
	ResponseCacheControl *string
	// ResponseContentDisposition is the response's Content-Disposition.
	ResponseContentDisposition *string
	// ResponseContentEncoding is the response's Content-Encoding.
	ResponseContentEncoding *string
	// ResponseContentLanguage is the response's Content-Language.
	ResponseContentLanguage *string
	// ResponseContentType is the response's Content-Type.
	ResponseContentType *string
	// ResponseExpires is the response's Expires, an IMF-fixdate.
	ResponseExpires *string
}

ResponseHeaders override the header fields of a presigned download's response, such as a ContentDisposition that names the file a browser saves. A nil field keeps the object's. They follow the rules of ObjectHeaders.

type WriteCondition added in v0.6.0

type WriteCondition struct {
	// IfMatch writes only over an object whose ETag is this one, quoted or
	// not.
	IfMatch *string
	// IfNoneMatch writes only when no object is stored under the key. It
	// must be `*`.
	IfNoneMatch *string
}

WriteCondition makes a write depend on the object it would replace. The zero value writes whatever is stored. At most one field is set.

Directories

Path Synopsis
dir
Package dir is an object store in a directory on a local disk, as a storage.Provider.
Package dir is an object store in a directory on a local disk, as a storage.Provider.
internal/vfs
Package vfs stores the buckets and objects of the dir backend under an os.Root: the layout, the commit of a write by rename, the key index, the locks, the deletion of buckets and the sweep of crashed writes.
Package vfs stores the buckets and objects of the dir backend under an os.Root: the layout, the commit of a write by rename, the key index, the locks, the deletion of buckets and the sweep of crashed writes.
internal
configsrc
Package configsrc resolves a backend's configuration: from a copy of the one given to the backend's WithConfig option, or else by binding the backend's defaults from a gas.ConfigProvider.
Package configsrc resolves a backend's configuration: from a copy of the one given to the backend's WithConfig option, or else by binding the backend's defaults from a gas.ConfigProvider.
conformance
Package conformance holds the tests every backend of the module runs: the contract of the storage package, checked with identical expectations against a backend built by the caller.
Package conformance holds the tests every backend of the module runs: the contract of the storage package, checked with identical expectations against a backend built by the caller.
lifecycle
Package lifecycle holds the lifecycle every backend of the module shares: Init, the calls in flight, and a Close that waits for them.
Package lifecycle holds the lifecycle every backend of the module shares: Init, the calls in flight, and a Close that waits for them.
listing
Package listing holds what the backends of the module that list from their own store share: the pages of ListObjects and ListBuckets, and their continuation tokens.
Package listing holds what the backends of the module that list from their own store share: the pages of ListObjects and ListBuckets, and their continuation tokens.
Package memory is an object store held in the process's memory, as a storage.Provider.
Package memory is an object store held in the process's memory, as a storage.Provider.
Package s3 is an object store on Amazon S3, or a server that speaks its API, as a storage.Provider, with a storage.Presigner of URLs to it.
Package s3 is an object store on Amazon S3, or a server that speaks its API, as a storage.Provider, with a storage.Presigner of URLs to it.
Package storagetest holds mocks of storage.Provider, MockProvider, and of storage.Presigner, MockPresigner, for tests of code that stores objects.
Package storagetest holds mocks of storage.Provider, MockProvider, and of storage.Presigner, MockPresigner, for tests of code that stores objects.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址