GoFakeS3

https://pkg.go.dev/github.com/johannesboyne/gofakes3@latest
Admin
GoFakeS3 is an AWS S3 fake server and testing library that provides comprehensive S3 integration...
Tokens:29,418
Snippets:244
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initialize gofakes3 with AWS SDK v2

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Sets up an in-memory S3 backend, starts a test server, and configures an AWS SDK v2 client to interact with it.

```go
import (
	"context"
	"crypto/tls"
	"net"
	"net/http"
	"net/http/httptest"
	"net/url"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/credentials"
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"github.com/johannesboyne/gofakes3"
	"github.com/johannesboyne/gofakes3/backend/s3mem"
)

// Set up gofakes3 server
backend := s3mem.New()
faker := gofakes3.New(backend)
ts := httptest.NewServer(faker.Server())
defer ts.Close()

// Setup AWS SDK v2 config
cfg, err := config.LoadDefaultConfig(
	context.TODO(),
	config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("ACCESS_KEY", "SECRET_KEY", "")),
	config.WithHTTPClient(&http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
		},
	}),
	config.WithEndpointResolverWithOptions(
		aws.EndpointResolverWithOptionsFunc(func(_, _ string, _ ...interface{}) (aws.Endpoint, error) {
			return aws.Endpoint{URL: ts.URL}, nil
		}),
	),
)
if err != nil {
	panic(err)
}

// Create an Amazon S3 v2 client, important to use o.UsePathStyle
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
	o.UsePathStyle = true
})

// Create a new bucket
_, err = client.CreateBucket(context.TODO(), &s3.CreateBucketInput{
	Bucket: aws.String("newbucket"),
})
if err != nil {
	panic(err)
}

// Upload an object
_, err = client.PutObject(context.TODO(), &s3.PutObjectInput{
	Body:   strings.NewReader(`{"configuration": {"main_color": "#333"}, "screens": []}`),
	Bucket: aws.String("newbucket"),
	Key:    aws.String("test.txt"),
})
if err != nil {
	panic(err)
}

// ... accessing of test.txt through any S3 client would now be possible
```

--------------------------------

### HTML Form Upload Example

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Demonstrates a multipart/form-data upload to an S3-compatible endpoint using hidden fields for authentication and metadata.

```html
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  </head>
  <body>

  <form action="http://localhost:9000/<bucket-name>/" method="post" enctype="multipart/form-data">
    Key to upload:
    <input type="input"  name="key" value="user/user1/test/<filename>" /><br />
    <input type="hidden" name="acl" value="public-read" />
    <input type="hidden" name="x-amz-meta-uuid" value="14365123651274" />
    <input type="hidden" name="x-amz-server-side-encryption" value="AES256" />
    <input type="text"   name="X-Amz-Credential" value="AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request" />
    <input type="text"   name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
    <input type="text"   name="X-Amz-Date" value="20151229T000000Z" />

    Tags for File:
    <input type="input"  name="x-amz-meta-tag" value="" /><br />
    <input type="hidden" name="Policy" value='<Base64-encoded policy string>' />
    <input type="hidden" name="X-Amz-Signature" value="<signature-value>" />
    File:
    <input type="file"   name="file" /> <br />
    <!-- The elements after this will be ignored -->
    <input type="submit" name="submit" value="Upload to Amazon S3" />
  </form>
</html>
```

--------------------------------

### Define UploadListMarker structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Used for pagination in ListMultipartUploads, specifying the starting point based on object key and upload ID.

```go
type UploadListMarker struct {
	// Represents the key-marker query parameter. Together with 'uploadID',
	// this parameter specifies the multipart upload after which listing should
	// begin.
	//
	// If 'uploadID' is not specified, only the keys lexicographically greater
	// than the specified key-marker will be included in the list.
	//
	// If 'uploadID' is specified, any multipart uploads for a key equal to
	// 'object'  might also be included, provided those multipart uploads have
	// upload IDs lexicographically greater than the specified uploadID.
	Object string

	// Represents the upload-id-marker query parameter to the
	// ListMultipartUploads operation. Together with 'object', specifies the
	// multipart upload after which listing should begin. If 'object' is not
	// specified, the 'uploadID' parameter is ignored.
	UploadID UploadID
}
```

--------------------------------

### Standard Log Implementation

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Returns a Logger that logs messages to a standard Go log.Logger. Use levels to filter messages. This allows integration with existing logging setups.

```go
func StdLog(log *log.Logger, levels ...LogLevel) Logger
```

--------------------------------

### UploadListMarker Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Used to seek to the start of a page in a ListMultipartUploads operation.

```APIDOC
## UploadListMarker

### Description
Used to specify the multipart upload after which listing should begin.

### Fields
- **Object** (string) - Required - The key-marker query parameter.
- **UploadID** (UploadID) - Required - The upload-id-marker query parameter.
```

--------------------------------

### Get HTTP Handler for GoFakeS3 Server

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Retrieve the http.Handler for the GoFakeS3 server. This handler can be used to integrate the fake S3 server into an existing HTTP application or for testing purposes.

```go
func (g *GoFakeS3) Server() http.Handler
```

--------------------------------

### Define ListBucketResultV2 Struct

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Extends ListBucketResultBase for S3 API version 2, adding fields for continuation tokens and start-after to manage paginated results and specific starting points for listings.

```go
type ListBucketResultV2 struct {
	ListBucketResultBase

	// If ContinuationToken was sent with the request, it is included in the
	// response.
	ContinuationToken string `xml:"ContinuationToken,omitempty"`

	// Returns the number of keys included in the response. The value is always
	// less than or equal to the MaxKeys value.
	KeyCount int64 `xml:"KeyCount,omitempty"`

	// If the response is truncated, Amazon S3 returns this parameter with a
	// continuation token. You can specify the token as the continuation-token
	// in your next request to retrieve the next set of keys.
	NextContinuationToken string `xml:"NextContinuationToken,omitempty"`

	// If StartAfter was sent with the request, it is included in the response.
	StartAfter string `xml:"StartAfter,omitempty"`
}
```

--------------------------------

### GoFakeS3 Server Initialization

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Demonstrates how to create a new GoFakeS3 server instance with a specified backend and options.

```APIDOC
## GoFakeS3 Server Initialization

### Description
Initializes a new GoFakeS3 server with a given backend and optional configurations.

### Method
`New`

### Parameters
- **backend** (Backend) - Required - The storage backend to use for the S3 service.
- **options** (...Option) - Optional - A variadic list of options to configure the server.

### Request Example
```go
backend := NewMemoryBackend()
server := GoFakeS3.New(backend, GoFakeS3.WithHostBucket(true))
```

### Response
- **GoFakeS3** (*GoFakeS3) - A pointer to the initialized GoFakeS3 server.
- **error** (error) - An error if initialization fails.
```

--------------------------------

### New GoFakeS3 Server Instance

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Instantiate a new GoFakeS3 server with a specified backend and optional configuration settings. Use options to customize behavior like auto-bucket creation or logger.

```go
func New(backend Backend, options ...Option) *GoFakeS3
```

--------------------------------

### Enable Auto Bucket Creation Option

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Option to enable automatic creation of buckets when they are first accessed. Defaults to false.

```go
func WithAutoBucket(enabled bool) Option
```

--------------------------------

### InitiateMultipartUploadResult Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

InitiateMultipartUploadResult contains the Bucket, Key, and UploadID for a multipart upload initiation.

```go
type InitiateMultipartUploadResult struct {
	Bucket   string   `xml:"Bucket"`
	Key      string   `xml:"Key"`
	UploadID UploadID `xml:"UploadId"`
}
```

--------------------------------

### Constructor for ListBucketVersionsResult

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Provides a constructor function for creating a new ListBucketVersionsResult.

```go
func NewListBucketVersionsResult(
	bucketName string,
	prefix *Prefix,
	page *ListBucketVersionsPage,
) *ListBucketVersionsResult
```

--------------------------------

### Go Integration with AWS SDK v1

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Configures an in-memory GoFakeS3 server and uses the AWS SDK v1 to perform bucket creation and object upload.

```go
// fake s3
backend := s3mem.New()
faker := gofakes3.New(backend)
ts := httptest.NewServer(faker.Server())
defer ts.Close()

// configure S3 client
s3Config := &aws.Config{
	Credentials:      credentials.NewStaticCredentials("YOUR-ACCESSKEYID", "YOUR-SECRETACCESSKEY", ""),
	Endpoint:         aws.String(ts.URL),
	Region:           aws.String("eu-central-1"),
	DisableSSL:       aws.Bool(true),
	S3ForcePathStyle: aws.Bool(true),
}
newSession := session.New(s3Config)

s3Client := s3.New(newSession)
cparams := &s3.CreateBucketInput{
	Bucket: aws.String("newbucket"),
}

// Create a new bucket using the CreateBucket call.
_, err := s3Client.CreateBucket(cparams)
if err != nil {
	// Message from an error.
	fmt.Println(err.Error())
	return
}

// Upload a new object "testobject" with the string "Hello World!" to our "newbucket".
_, err = s3Client.PutObject(&s3.PutObjectInput{
	Body:   strings.NewReader(`{"configuration": {"main_color": "#333"}, "screens": []}`),
	Bucket: aws.String("newbucket"),
	Key:    aws.String("test.txt"),
})

// ... accessing of test.txt through any S3 client would now be possible
```

--------------------------------

### Prefix Handling

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Structures and constructors for managing object prefixes and delimiters.

```go
type Prefix struct {
	HasPrefix bool
	Prefix    string

	HasDelimiter bool
	Delimiter    string
}
```

```go
func NewFolderPrefix(prefix string) (p Prefix)
```

```go
func NewPrefix(prefix, delim *string) (p Prefix)
```

--------------------------------

### GoFakeS3 Server Creation

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

This snippet shows how to create a new GoFakeS3 instance and obtain its HTTP handler.

```APIDOC
## GoFakeS3 Server API

### Description
This section details the creation and server functionality of the GoFakeS3 struct.

### Method
- `New(backend Backend, options ...Option) *GoFakeS3`
  Creates a new GoFakeS3 instance using the supplied Backend. Backends are pluggable.

- `(*GoFakeS3) Server() http.Handler`
  Creates the AWS S3 API HTTP handler.

### Parameters
#### New Function Parameters
- **backend** (Backend) - Required - The backend implementation to use.
- **options** (...Option) - Optional - Configuration options for GoFakeS3.

#### Server Method Parameters
This method does not accept any parameters.

### Response
#### New Function Response
- `*GoFakeS3` - A pointer to the newly created GoFakeS3 instance.

#### Server Method Response
- `http.Handler` - The HTTP handler for the S3 API.
```

--------------------------------

### NewFolderPrefix Function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Creates a new Prefix representing a folder. This is used for organizing objects within a bucket.

```go
func NewFolderPrefix(prefix string) (p Prefix)
```

--------------------------------

### GoFakeS3 Configuration Options

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Functional options for configuring the GoFakeS3 server instance.

```go
type Option func(g *GoFakeS3)
```

```go
func WithAutoBucket(enabled bool) Option
```

```go
func WithGlobalLog() Option
```

```go
func WithHostBucket(enabled bool) Option
```

```go
func WithHostBucketBase(hosts ...string) Option
```

```go
func WithInsecureCORS() Option
```

```go
func WithIntegrityCheck(check bool) Option
```

```go
func WithLogger(logger Logger) Option
```

```go
func WithMetadataSizeLimit(size int) Option
```

```go
func WithRequestID(id uint64) Option
```

```go
func WithTimeSkewLimit(skew time.Duration) Option
```

```go
func WithTimeSource(timeSource TimeSource) Option
```

```go
func WithUnimplementedPageError() Option
```

```go
func WithoutVersioning() Option
```

--------------------------------

### FilePrefix Method for Prefix

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Extracts the file prefix and remaining path from a Prefix. Useful for parsing object keys.

```go
func (p Prefix) FilePrefix() (path, remaining string, ok bool)
```

--------------------------------

### String Method for Prefix

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Returns the string representation of the Prefix. Useful for debugging and logging.

```go
func (p Prefix) String() string
```

--------------------------------

### Configure Virtual-Hosted Style Addressing

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Configures the client for virtual-hosted style addressing, where the bucket name is part of the hostname. Requires local DNS mapping.

```text
http://mybucket.localhost:9000/myobject
```

```text
127.0.0.1 mybucket.localhost
```

```go
client := s3.NewFromConfig(cfg)
```

--------------------------------

### Define ListBucketVersionsPage Struct

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Defines the structure for paginating through bucket versions, specifying key and version ID markers, and the maximum number of keys to return per page.

```go
type ListBucketVersionsPage struct {
	// Specifies the key in the bucket that you want to start listing from.
	// If HasKeyMarker is true, this must be non-empty.
	KeyMarker    string
	HasKeyMarker bool

	// Specifies the object version you want to start listing from. If
	// HasVersionIDMarker is true, this must be non-empty.
	VersionIDMarker    VersionID
	HasVersionIDMarker bool

	// Sets the maximum number of keys returned in the response body. The
	// response might contain fewer keys, but will never contain more. If
	// additional keys satisfy the search criteria, but were not returned
	// because max-keys was exceeded, the response contains
	// <isTruncated>true</isTruncated>. To return the additional keys, see
	// key-marker and version-id-marker.
	//
	// MaxKeys MUST be > 0, otherwise it is ignored.
	MaxKeys int64
}
```

--------------------------------

### NewPrefix Function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Creates a new Prefix with a specified prefix string and delimiter. This is used for defining object paths and filtering.

```go
func NewPrefix(prefix, delim *string) (p Prefix)
```

--------------------------------

### ObjectList Structure and Methods

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Structures and methods for managing lists of objects in S3.

```go
type ObjectList struct {
	CommonPrefixes []CommonPrefix
	Contents       []*Content
	IsTruncated    bool
	NextMarker     string
	// contains filtered or unexported fields
}
```

```go
func NewObjectList() *ObjectList
```

```go
func (b *ObjectList) Add(item *Content)
```

```go
func (b *ObjectList) AddPrefix(prefix string)
```

--------------------------------

### ListBucketPage Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

ListBucketPage defines parameters for listing bucket contents, including Marker, HasMarker, and MaxKeys. MaxKeys must be greater than 0 to be effective.

```go
type ListBucketPage struct {
	// Specifies the key in the bucket that represents the last item in
	// the previous page. The first key in the returned page will be the
	// next lexicographically (UTF-8 binary) sorted key after Marker.
	// If HasMarker is true, this must be non-empty.
	Marker    string
	HasMarker bool

	// Sets the maximum number of keys returned in the response body. The
	// response might contain fewer keys, but will never contain more. If
	// additional keys satisfy the search criteria, but were not returned
	// because max-keys was exceeded, the response contains
	// <isTruncated>true</isTruncated>. To return the additional keys, see
	// key-marker and version-id-marker.
	//
	// MaxKeys MUST be > 0, otherwise it is ignored.
	MaxKeys int64
}
```

--------------------------------

### VersioningConfiguration Struct

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents the versioning configuration for an S3 bucket, including its status and MFA delete settings.

```go
type VersioningConfiguration struct {
	XMLName xml.Name `xml:"VersioningConfiguration"`

	Status VersioningStatus `xml:"Status"`

	// When enabled, the bucket owner must include the x-amz-mfa request header
	// in requests to change the versioning state of a bucket and to
	// permanently delete a versioned object.
	MFADelete MFADeleteStatus `xml:"MfaDelete"`
}
```

--------------------------------

### Implement Names Method for Buckets

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Provides a deterministic and sorted list of bucket names from a Buckets slice. This is a convenience function.

```go
func (b Buckets) Names() []string
```

--------------------------------

### Enable Host Bucket Option

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Option to enable host bucket functionality. When enabled, the bucket name is derived from the host header of the request.

```go
func WithHostBucket(enabled bool) Option
```

--------------------------------

### Enable Global Log Option

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Option to use the global logger. This is a convenience option that is equivalent to WithLogger(GlobalLog()).

```go
func WithGlobalLog() Option
```

--------------------------------

### Create Bucket Not Found Error

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Generates a standard error for a bucket that was not found.

```go
func BucketNotFound(bucket string) error
```

--------------------------------

### Match Method for Prefix

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Checks if a given key matches the Prefix criteria. Used for filtering objects based on their keys.

```go
func (p Prefix) Match(key string, match *PrefixMatch) (ok bool)
```

--------------------------------

### Backend Interface Methods

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

This section details the methods available in the Backend interface for managing S3 buckets and objects.

```APIDOC
## Backend Interface

This interface defines the contract for S3 storage backends.

### Methods

#### ListBuckets

**Description**: Returns a list of all buckets owned by the authenticated sender of the request.

**Endpoint**: `GET /` (Implicit, as it lists all buckets)

**Reference**: https://docs.aws.amazon.com/AmazonS3/latest/API/RESTServiceGET.html

#### ListBucket

**Description**: Returns the contents of a bucket, optionally filtered by a prefix and paginated.

**Endpoint**: `GET /{bucketName}`

**Parameters**:

*   **Path Parameters**:
    *   `name` (string) - Required - The name of the bucket.
*   **Query Parameters**:
    *   `prefix` (*Prefix) - Optional - Used to limit the contents of the bucket.
    *   `page` (ListBucketPage) - Optional - Pagination information.

**Returns**: `*ObjectList` - A list of objects and common prefixes in the bucket.

**Errors**: `gofakes3.ErrNoSuchBucket` if the bucket does not exist.

#### CreateBucket

**Description**: Creates a bucket if it does not already exist.

**Endpoint**: `PUT /{bucketName}`

**Parameters**:

*   **Path Parameters**:
    *   `name` (string) - Required - The name of the bucket to create.

**Errors**: `gofakes3.ResourceError` with `gofakes3.ErrBucketAlreadyExists` if the bucket already exists.

#### BucketExists

**Description**: Checks if a bucket exists.

**Endpoint**: (Internal check, not a direct HTTP endpoint)

**Parameters**:

*   `name` (string) - Required - The name of the bucket to check.

**Returns**: `bool` - True if the bucket exists, false otherwise.

**Errors**: An error if the backend is unable to determine existence.

#### DeleteBucket

**Description**: Deletes a bucket if and only if it is empty.

**Endpoint**: `DELETE /{bucketName}`

**Parameters**:

*   **Path Parameters**:
    *   `name` (string) - Required - The name of the bucket to delete.

**Errors**:

*   `gofakes3.ResourceError` with `gofakes3.ErrBucketNotEmpty` if the bucket is not empty.
*   `gofakes3.ErrNoSuchBucket` if the bucket does not exist.

#### ForceDeleteBucket

**Description**: Deletes a bucket and all its contents, regardless of whether the bucket is empty.

**Endpoint**: (Custom endpoint, not standard S3)

**Parameters**:

*   **Path Parameters**:
    *   `name` (string) - Required - The name of the bucket to force delete.

#### GetObject

**Description**: Retrieves an object from a bucket.

**Endpoint**: `GET /{bucketName}/{objectName}`

**Parameters**:

*   **Path Parameters**:
    *   `bucketName` (string) - Required - The name of the bucket.
    *   `objectName` (string) - Required - The name of the object.
*   **Query Parameters**:
    *   `rangeRequest` (*ObjectRangeRequest) - Optional - Specifies a byte range for the object.

**Returns**: `*Object` - The object data and metadata.

**Errors**: `gofakes3.ErrNoSuchKey` if the object does not exist. `ErrNotImplemented` if range requests are not supported.

**Resource Management**: The caller MUST call `Object.Contents.Close()` on the returned object.

#### HeadObject

**Description**: Fetches the metadata of an object without retrieving its content.

**Endpoint**: `HEAD /{bucketName}/{objectName}`

**Parameters**:

*   **Path Parameters**:
    *   `bucketName` (string) - Required - The name of the bucket.
    *   `objectName` (string) - Required - The name of the object.

**Returns**: `*Object` - The object metadata.

**Errors**: `NotFound()` error if the object does not exist.

**Resource Management**: The caller MUST call `Object.Contents.Close()` on the returned object.

#### DeleteObject

**Description**: Deletes an object from a bucket. If versioning is enabled, it introduces a delete marker.

**Endpoint**: `DELETE /{bucketName}/{objectName}`

**Parameters**:

*   **Path Parameters**:
    *   `bucketName` (string) - Required - The name of the bucket.
    *   `objectName` (string) - Required - The name of the object to delete.

**Returns**: `ObjectDeleteResult` - Result of the delete operation.

**Errors**: `gofakes3.ErrNoSuchBucket` if the bucket does not exist. Does not return an error if the object does not exist.

#### PutObject

**Description**: Uploads an object to a bucket.

**Endpoint**: `PUT /{bucketName}/{objectName}`

**Parameters**:

*   **Path Parameters**:
    *   `bucketName` (string) - Required - The name of the bucket.
    *   `objectName` (string) - Required - The name of the object.
*   **Request Body**:
    *   `reader` (io.Reader) - Required - The content of the object.
    *   `size` (int64) - Optional - The size of the object content.
    *   `meta` (map[string]string) - Optional - Metadata for the object.
    *   `conditions` (*PutObjectConditions) - Optional - Conditions for the put operation.

**Usage Note**: Use `gofakes3.ReadAll()` for reading the entire reader if the backend needs to.

```

--------------------------------

### Create Key Not Found Error

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Generates a standard error for a key (object) that was not found.

```go
func KeyNotFound(key string) error
```

--------------------------------

### NewListBucketVersionsResult Function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Creates a new ListBucketVersionsResult. This is used to return versioned object listings for a bucket.

```go
func NewListBucketVersionsResult(bucketName string, prefix *Prefix, page *ListBucketVersionsPage) *ListBucketVersionsResult
```

--------------------------------

### GoFakeS3 Options

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

This section details the various functional options that can be passed to configure the GoFakeS3 server.

```APIDOC
## GoFakeS3 Options

This section details the various functional options that can be passed to configure the GoFakeS3 server.

### WithAutoBucket

```go
func WithAutoBucket(enabled bool) Option
```

Instructs GoFakeS3 to create buckets that don't exist on first use, rather than returning ErrNoSuchBucket.

### WithGlobalLog

```go
func WithGlobalLog() Option
```

Configures gofakes3 to use GlobalLog() for logging, which uses the standard library's log.Println() call to log messages.

### WithHostBucket

```go
func WithHostBucket(enabled bool) Option
```

Enables or disables bucket rewriting in the router. If active, the URL 'http://mybucket.localhost/object' will be routed as if the URL path was '/mybucket/object'. This will apply to all requests. If you want to be more specific, provide WithHostBucketBase. See https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html for details.

### WithHostBucketBase

```go
func WithHostBucketBase(hosts ...string) Option
```

Enables or disables bucket rewriting in the router, but only if the host is a subdomain of the base. If set to 'example.com', the URL 'http://mybucket.example.com/object' will be routed as if the URL path was '/mybucket/object', but 'http://example.com/bucket/object' will use path-based bucket routing instead. You may pass multiple bases, they are tested in order. See https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingBucket.html for details.

### WithInsecureCORS

```go
func WithInsecureCORS() Option
```

Responds with * for all Access-Control-Allow headers.

### WithIntegrityCheck

```go
func WithIntegrityCheck(check bool) Option
```

Enables or disables Content-MD5 validation when putting an Object.

### WithLogger

```go
func WithLogger(logger Logger) Option
```

Allows you to supply a logger to GoFakeS3 for debugging/tracing. logger may be nil.

### WithMetadataSizeLimit

```go
func WithMetadataSizeLimit(size int) Option
```

Allows you to reconfigure the maximum allowed metadata size. See DefaultMetadataSizeLimit for the starting value, set to '0' to disable.

### WithRequestID

```go
func WithRequestID(id uint64) Option
```

Sets the starting ID used to generate the "x-amz-request-id" header.

### WithTimeSkewLimit

```go
func WithTimeSkewLimit(skew time.Duration) Option
```

Allows you to reconfigure the allowed skew between the client's clock and the server's clock. The AWS client SDKs will send the "x-amz-date" header containing the time at the client, which is used to calculate the skew. See DefaultSkewLimit for the starting value, set to '0' to disable.

### WithTimeSource

```go
func WithTimeSource(timeSource TimeSource) Option
```

Allows you to substitute the behaviour of time.Now() and time.Since() within GoFakeS3. This can be used to trigger time skew errors, or to ensure the output of the commands is deterministic. See gofakes3.FixedTimeSource(), gofakes3.LocalTimeSource(tz).

### WithUnimplementedPageError

```go
func WithUnimplementedPageError() Option
```

Allows you to enable or disable the error that occurs if the Backend does not implement paging. By default, GoFakeS3 will simply retry a request for a page of objects without the page if the Backend does not implement pagination. This can be used to enable an error in that condition instead.

### WithoutVersioning

```go
func WithoutVersioning() Option
```

Disables versioning on the passed backend, if it supported it.
```

--------------------------------

### Set Time Source Option

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Option to provide a custom time source. This allows for deterministic testing by controlling the time returned by the server.

```go
func WithTimeSource(timeSource TimeSource) Option
```

--------------------------------

### Check if Resource Already Exists

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Asserts if an error indicates that a resource already exists, similar to os.IsExist.

```go
func IsAlreadyExists(err error) bool
```

--------------------------------

### MultipartBackend Interface

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Interface for supporting S3 multipart uploads. Optional for backends; GoFakeS3 provides an in-memory fallback.

```go
type MultipartBackend interface {
	CreateMultipartUpload(bucket, object string, meta map[string]string) (UploadID, error)
	UploadPart(bucket, object string, id UploadID, partNumber int, contentLength int64, input io.Reader) (etag string, err error)

	ListMultipartUploads(bucket string, marker *UploadListMarker, prefix Prefix, limit int64) (*ListMultipartUploadsResult, error)
	ListParts(bucket, object string, uploadID UploadID, marker int, limit int64) (*ListMultipartUploadPartsResult, error)

	AbortMultipartUpload(bucket, object string, id UploadID) error
	CompleteMultipartUpload(bucket, object string, id UploadID, input *CompleteMultipartUploadRequest) (versionID VersionID, etag string, err error)
}
```

--------------------------------

### Define ListBucketVersionsResult Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Defines the structure for the result of listing bucket versions, including XML tags and fields for pagination and versioning.

```go
type ListBucketVersionsResult struct {
	XMLName        xml.Name       `xml:"ListBucketVersionsResult"`
	Xmlns          string         `xml:"xmlns,attr"`
	Name           string         `xml:"Name"`
	Delimiter      string         `xml:"Delimiter,omitempty"`
	Prefix         string         `xml:"Prefix,omitempty"`
	CommonPrefixes []CommonPrefix `xml:"CommonPrefixes,omitempty"`
	IsTruncated    bool           `xml:"IsTruncated"`
	MaxKeys        int64          `xml:"MaxKeys"`

	// Marks the last Key returned in a truncated response.
	KeyMarker string `xml:"KeyMarker,omitempty"`

	// When the number of responses exceeds the value of MaxKeys, NextKeyMarker
	// specifies the first key not returned that satisfies the search criteria.
	// Use this value for the key-marker request parameter in a subsequent
	// request.
	NextKeyMarker string `xml:"NextKeyMarker,omitempty"`

	// Marks the last version of the Key returned in a truncated response.
	VersionIDMarker VersionID `xml:"VersionIdMarker,omitempty"`

	// When the number of responses exceeds the value of MaxKeys,
	// NextVersionIdMarker specifies the first object version not returned that
	// satisfies the search criteria. Use this value for the version-id-marker
	// request parameter in a subsequent request.
	NextVersionIDMarker VersionID `xml:"NextVersionIdMarker,omitempty"`

	// AWS responds with a list of either <Version> or <DeleteMarker> objects. The order
	// needs to be preserved and they need to be direct of ListBucketVersionsResult:
	//	<ListBucketVersionsResult>
	//		<DeleteMarker ... />
	//		<Version ... />
	//		<DeleteMarker ... />
	//		<Version ... />
	//	</ListBucketVersionsResult>
	Versions []VersionItem
	// contains filtered or unexported fields
}
```

--------------------------------

### List Bucket Operations

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Documentation for the ListBucketPage type and its methods.

```APIDOC
## List Bucket Operations API

### Description
This section covers the `ListBucketPage` type, which is used for paginating results when listing bucket contents.

### Type
#### `ListBucketPage`
`type ListBucketPage struct {
	Marker    string
	HasMarker bool
	MaxKeys   int64
}`
Defines parameters for paginating list bucket operations. It includes a marker for the previous page's last item, a flag indicating if a marker is used, and the maximum number of keys to return per page.

### Methods
#### `(ListBucketPage) IsEmpty() bool`
Checks if the `ListBucketPage` is empty or has no effective parameters set.
```

--------------------------------

### Implement CopyObject Helper Function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

A helper function to implement CopyObject using GetObject and PutObject. It's not the most efficient method and should be used when performance is not critical.

```go
func CopyObject(db Backend, srcBucket, srcKey, dstBucket, dstKey string, meta map[string]string) (result CopyObjectResult, err error)
```

--------------------------------

### IsEmpty Method for ListBucketPage

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Checks if the ListBucketPage is empty. Returns true if there are no objects or versions in the page.

```go
func (p ListBucketPage) IsEmpty() bool
```

--------------------------------

### Define Storage structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents the result of listing all buckets, including owner information and a list of buckets.

```go
type Storage struct {
	XMLName xml.Name  `xml:"ListAllMyBucketsResult"`
	Xmlns   string    `xml:"xmlns,attr"`
	Owner   *UserInfo `xml:"Owner,omitempty"`
	Buckets Buckets   `xml:"Buckets>Bucket"`
}
```

--------------------------------

### NewObjectList Function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Creates a new, empty ObjectList. ObjectList is used to hold a collection of Content objects.

```go
func NewObjectList() *ObjectList
```

--------------------------------

### Define BucketInfo Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents a single bucket, including its name and creation date. The CreationDate is mandatory for compatibility with tools like boto.

```go
type BucketInfo struct {
	Name string `xml:"Name"`

	// CreationDate is required; without it, boto returns the error "('String
	// does not contain a date:', ”)"
	CreationDate ContentTime `xml:"CreationDate"`
}
```

--------------------------------

### Define LogLevel Constants

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Defines constants for different log levels: Error, Warning, Info, and Debug.

```go
const (
	LogErr   LogLevel = "ERR"
	LogWarn  LogLevel = "WARN"
	LogInfo  LogLevel = "INFO"
	LogDebug LogLevel = "DEBUG"
)
```

--------------------------------

### Define UserInfo structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents user information, including ID and DisplayName, typically used in S3 responses.

```go
type UserInfo struct {
	ID          string `xml:"ID"`
	DisplayName string `xml:"DisplayName"`
}
```

--------------------------------

### AddPrefix Method for ObjectList

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Adds a prefix to the ObjectList. Prefixes are used to group objects by common paths in the listing.

```go
func (b *ObjectList) AddPrefix(prefix string)
```

--------------------------------

### Define Backend Interface for S3 Storage

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

This interface defines the core operations for an S3-compatible storage backend. Implement this interface to provide custom storage solutions for gofakes3.

```go
type Backend interface {
	// ListBuckets returns a list of all buckets owned by the authenticated
	// sender of the request.
	// https://docs.aws.amazon.com/AmazonS3/latest/API/RESTServiceGET.html
	ListBuckets() ([]BucketInfo, error)

	// ListBucket returns the contents of a bucket. Backends should use the
	// supplied prefix to limit the contents of the bucket and to sort the
	// matched items into the Contents and CommonPrefixes fields.
	//
	// ListBucket must return a gofakes3.ErrNoSuchBucket error if the bucket
	// does not exist. See gofakes3.BucketNotFound() for a convenient way to create one.
	//
	// The prefix MUST be correctly handled for the backend to be valid. Each
	// item you consider returning should be checked using prefix.Match(name),
	// even if the prefix is empty. The Backend MUST treat a nil prefix
	// identically to a zero prefix.
	//
	// At this stage, implementers MAY return gofakes3.ErrInternalPageNotImplemented
	// if the page argument is non-empty. In this case, gofakes3 may or may
	// not, depending on how it was configured, retry the same request with no page.
	// We have observed (though not yet confirmed) that simple clients tend to
	// work fine if you ignore the pagination request, but this may not suit
	// your application. Not all backends bundled with gofakes3 correctly
	// support this pagination yet, but that will change.
	ListBucket(name string, prefix *Prefix, page ListBucketPage) (*ObjectList, error)

	// CreateBucket creates the bucket if it does not already exist. The name
	// should be assumed to be a valid name.
	//
	// If the bucket already exists, a gofakes3.ResourceError with
	gofakes3.ErrBucketAlreadyExists MUST be returned.
	CreateBucket(name string) error

	// BucketExists should return a boolean indicating the bucket existence, or
	// an error if the backend was unable to determine existence.
	BucketExists(name string) (exists bool, err error)

	// DeleteBucket deletes a bucket if and only if it is empty.
	//
	// If the bucket is not empty, gofakes3.ResourceError with
	gofakes3.ErrBucketNotEmpty MUST be returned.
	//
	// If the bucket does not exist, gofakes3.ErrNoSuchBucket MUST be returned.
	//
	// AWS does not validate the bucket's name for anything other than existence.
	DeleteBucket(name string) error

	// ForceDeleteBucket must delete a bucket and all its contents, regardless of
	// whether the bucket is empty or not. This is useful for testing purposes
	// where you need to clean up after yourself.
	ForceDeleteBucket(name string) error

	// GetObject must return a gofakes3.ErrNoSuchKey error if the object does
	// not exist. See gofakes3.KeyNotFound() for a convenient way to create
	// one.
	//
	// If the returned Object is not nil, you MUST call Object.Contents.Close(),
	// otherwise you will leak resources. Implementers should return a no-op
	// implementation of io.ReadCloser.
	//
	// If rnge is nil, it is assumed you want the entire object. If rnge is not
	// nil, but the underlying backend does not support range requests,
	// implementers MUST return ErrNotImplemented.
	//
	// If the backend is a VersionedBackend, GetObject retrieves the latest version.
	GetObject(bucketName, objectName string, rangeRequest *ObjectRangeRequest) (*Object, error)

	// HeadObject fetches the Object from the backend, but reading the Contents
	// will return io.EOF immediately.
	//
	// If the returned Object is not nil, you MUST call Object.Contents.Close(),
	// otherwise you will leak resources. Implementers should return a no-op
	// implementation of io.ReadCloser.
	//
	// HeadObject should return a NotFound() error if the object does not
	// exist.
	HeadObject(bucketName, objectName string) (*Object, error)

	// DeleteObject deletes an object from the bucket.
	//
	// If the backend is a VersionedBackend and versioning is enabled, this
	// should introduce a delete marker rather than actually delete the object.
	//
	// DeleteObject must return a gofakes3.ErrNoSuchBucket error if the bucket
	// does not exist. See gofakes3.BucketNotFound() for a convenient way to create one.
	// FIXME: confirm with S3 whether this is the correct behaviour.
	//
	// DeleteObject must not return an error if the object does not exist. Source:
	// https://docs.aws.amazon.com/sdk-for-go/api/service/s3/#S3.DeleteObject:
	//
	//	Removes the null version (if there is one) of an object and inserts a
	//	delete marker, which becomes the latest version of the object. If there
	//	isn't a null version, Amazon S3 does not remove any objects.
	//
	DeleteObject(bucketName, objectName string) (ObjectDeleteResult, error)

	// PutObject should assume that the key is valid. The map containing meta
	// may be nil.
	//
	// The size can be used if the backend needs to read the whole reader; use
	gofakes3.ReadAll() for this job rather than ioutil.ReadAll().
	//
	// If conditions is not nil, the backend should check the conditions before

```

--------------------------------

### Multi Log Implementation

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Combines multiple Logger instances into a single Logger. All messages will be sent to each of the provided loggers. Useful for sending logs to different destinations simultaneously.

```go
func MultiLog(loggers ...Logger) Logger
```

--------------------------------

### AddPrefix Method for ListBucketVersionsResult

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Adds a prefix to the ListBucketVersionsResult. Prefixes are used to group objects by common paths.

```go
func (b *ListBucketVersionsResult) AddPrefix(prefix string)
```

--------------------------------

### DefaultTimeSource function

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Returns a default TimeSource implementation.

```go
func DefaultTimeSource() TimeSource
```

--------------------------------

### VersionItem Interface

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Interface for items that have a VersionID.

```go
type VersionItem interface {
	GetVersionID() VersionID
	// contains filtered or unexported methods
}
```

--------------------------------

### Set Metadata Size Limit Option

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Option to set the maximum size for object metadata. This helps prevent excessive memory usage due to large metadata.

```go
func WithMetadataSizeLimit(size int) Option
```

--------------------------------

### ListBucketVersionsPage Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Defines parameters for paginating through S3 bucket versions, including key and version ID markers, and maximum keys.

```APIDOC
## ListBucketVersionsPage

### Description
Structure used to define pagination parameters for listing S3 bucket versions.

### Fields
- **KeyMarker** (string) - Specifies the key to start listing from. Must be non-empty if HasKeyMarker is true.
- **HasKeyMarker** (bool) - Flag indicating if KeyMarker is set.
- **VersionIDMarker** (VersionID) - Specifies the object version to start listing from. Must be non-empty if HasVersionIDMarker is true.
- **HasVersionIDMarker** (bool) - Flag indicating if VersionIDMarker is set.
- **MaxKeys** (int64) - Sets the maximum number of keys to return in the response. Must be greater than 0 to be effective.
```

--------------------------------

### Define Content Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents metadata for an object, including its key, last modified time, ETag, size, storage class, and owner.

```go
type Content struct {
	Key          string       `xml:"Key"
	LastModified ContentTime  `xml:"LastModified"
	ETag         string       `xml:"ETag"
	Size         int64        `xml:"Size"
	StorageClass StorageClass `xml:"StorageClass,omitempty"
	Owner        *UserInfo    `xml:"Owner,omitempty"
}
```

--------------------------------

### ObjectRange and Request Structures

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Structures for handling byte range requests for objects.

```go
type ObjectRange struct {
	Start, Length int64
}
```

```go
type ObjectRangeRequest struct {
	Start, End int64
	FromEnd    bool
}
```

```go
func (o *ObjectRangeRequest) Range(size int64) (*ObjectRange, error)
```

--------------------------------

### Define CommonPrefix Structure

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents a common prefix used in listing objects, often indicating a pseudo-directory structure.

```go
type CommonPrefix struct {
	Prefix string `xml:"Prefix"`
}
```

--------------------------------

### Object Struct

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Represents an object retrieved from a backend, including its metadata, size, contents, hash, and versioning information. Remember to close Contents.Close().

```go
type Object struct {
	Name     string
	Metadata map[string]string
	Size     int64
	Contents io.ReadCloser
	Hash     []byte
	Range    *ObjectRange

	// VersionID will be empty if bucket versioning has not been enabled.
	VersionID VersionID

	// If versioning is enabled for the bucket, this is true if this object version
	// is a delete marker.
	IsDeleteMarker bool
}
```

--------------------------------

### Read Data with Size Hint

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Reads all data from an io.Reader, optimized when the expected size is known. Reports S3-specific errors like ErrIncompleteBody.

```go
func ReadAll(r io.Reader, size int64) (b []byte, err error)
```

--------------------------------

### Configure Path-Style Addressing

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Configures the AWS SDK v2 client to use path-style addressing, where the bucket name is part of the URL path.

```text
http://localhost:9000/mybucket/myobject
```

```go
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UsePathStyle = true
})
```

--------------------------------

### Logging Functions

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Functions for creating and configuring loggers.

```APIDOC
## Logging Functions

### DiscardLog

#### Description
Creates a `Logger` that discards all log messages.

#### Function Signature
```go
func DiscardLog() Logger
```

### GlobalLog

#### Description
Creates a `Logger` that uses the global `log.Println()` function. By default, all log levels are reported. You can provide a whitelist of `LogLevel` values to filter messages.

#### Function Signature
```go
func GlobalLog(levels ...LogLevel) Logger
```

### MultiLog

#### Description
Creates a `Logger` that aggregates messages from multiple `Logger` instances.

#### Function Signature
```go
func MultiLog(loggers ...Logger) Logger
```

### StdLog

#### Description
Creates a `Logger` that uses the standard library's `log.Logger` type. By default, all log levels are reported. You can provide a whitelist of `LogLevel` values to filter messages.

#### Function Signature
```go
func StdLog(log *log.Logger, levels ...LogLevel) Logger
```
```

--------------------------------

### VersioningStatus Type and Constants

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Defines the possible versioning statuses (None, Enabled, Suspended) as a string type.

```go
type VersioningStatus string

const (
	VersioningNone      VersioningStatus = ""
	VersioningEnabled   VersioningStatus = "Enabled"
	VersioningSuspended VersioningStatus = "Suspended"
)
```

--------------------------------

### AsCommonPrefix Method for PrefixMatch

Source: https://pkg.go.dev/github.com/johannesboyne/gofakes3

Converts a PrefixMatch into a CommonPrefix. This is used when processing object listings.

```go
func (match *PrefixMatch) AsCommonPrefix() CommonPrefix
```
Tokens:
Raw