s3

package
v0.27.1 Latest Latest
Warning

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

 Go to latest Published: Apr 24, 2025 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package s3 implements a lightweight client for interacting with the REST APIs of any S3 compatible service.

It implements only the minimal functionality required by PocketBase such as objects list, get, copy, delete and upload.

For more details why we don't use the official aws-sdk-go-v2, you could check https://github.com/alvarolm/pocketbase/discussions/6562.

Example: 

client := &s3.S3{
	Endpoint:     "example.com",
	Region:       "us-east-1",
	Bucket:       "test",
	AccessKey:    "...",
	SecretKey:    "...",
	UsePathStyle: true,
}
resp, err := client.GetObject(context.Background(), "abc.txt")

Index

Constants

This section is empty.

Variables

View Source 
var ErrUsedUploader = errors.New("the Uploader has been already used")

Functions

This section is empty.

Types

type CopyObjectResponse 

type CopyObjectResponse struct {
	CopyObjectResult  xml.Name  `json:"copyObjectResult" xml:"CopyObjectResult"`
	ETag              string    `json:"etag" xml:"ETag"`
	LastModified      time.Time `json:"lastModified" xml:"LastModified"`
	ChecksumType      string    `json:"checksumType" xml:"ChecksumType"`
	ChecksumCRC32     string    `json:"checksumCRC32" xml:"ChecksumCRC32"`
	ChecksumCRC32C    string    `json:"checksumCRC32C" xml:"ChecksumCRC32C"`
	ChecksumCRC64NVME string    `json:"checksumCRC64NVME" xml:"ChecksumCRC64NVME"`
	ChecksumSHA1      string    `json:"checksumSHA1" xml:"ChecksumSHA1"`
	ChecksumSHA256    string    `json:"checksumSHA256" xml:"ChecksumSHA256"`
}

https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html#API_CopyObject_ResponseSyntax

type GetObjectResponse 

type GetObjectResponse struct {
	Body io.ReadCloser `json:"-" xml:"-"`

	HeadObjectResponse
}

https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html#API_GetObject_ResponseElements

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

type HeadObjectResponse 

type HeadObjectResponse struct {
	// Metadata is the extra data that is stored with the S3 object (aka. the "x-amz-meta-*" header values).
	//
	// The map keys are normalized to lower-case.
	Metadata map[string]string `json:"metadata"`

	// LastModified date and time when the object was last modified.
	LastModified time.Time `json:"lastModified"`

	// CacheControl specifies caching behavior along the request/reply chain.
	CacheControl string `json:"cacheControl"`

	// ContentDisposition specifies presentational information for the object.
	ContentDisposition string `json:"contentDisposition"`

	// ContentEncoding indicates what content encodings have been applied to the object
	// and thus what decoding mechanisms must be applied to obtain the
	// media-type referenced by the Content-Type header field.
	ContentEncoding string `json:"contentEncoding"`

	// ContentLanguage indicates the language the content is in.
	ContentLanguage string `json:"contentLanguage"`

	// ContentType is a standard MIME type describing the format of the object data.
	ContentType string `json:"contentType"`

	// ContentRange is the portion of the object usually returned in the response for a GET request.
	ContentRange string `json:"contentRange"`

	// ETag is an opaque identifier assigned by a web
	// server to a specific version of a resource found at a URL.
	ETag string `json:"etag"`

	// ContentLength is size of the body in bytes.
	ContentLength int64 `json:"contentLength"`
}

https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html#API_HeadObject_ResponseElements

type ListObjectCommonPrefix 

type ListObjectCommonPrefix struct {
	Prefix string `json:"prefix" xml:"Prefix"`
}

type ListObjectContent 

type ListObjectContent struct {
	Owner struct {
		DisplayName string `json:"displayName" xml:"DisplayName"`
		ID          string `json:"id" xml:"ID"`
	} `json:"owner" xml:"Owner"`

	ChecksumAlgorithm string    `json:"checksumAlgorithm" xml:"ChecksumAlgorithm"`
	ETag              string    `json:"etag" xml:"ETag"`
	Key               string    `json:"key" xml:"Key"`
	StorageClass      string    `json:"storageClass" xml:"StorageClass"`
	LastModified      time.Time `json:"lastModified" xml:"LastModified"`

	RestoreStatus struct {
		RestoreExpiryDate   time.Time `json:"restoreExpiryDate" xml:"RestoreExpiryDate"`
		IsRestoreInProgress bool      `json:"isRestoreInProgress" xml:"IsRestoreInProgress"`
	} `json:"restoreStatus" xml:"RestoreStatus"`

	Size int64 `json:"size" xml:"Size"`
}

type ListObjectsResponse 

type ListObjectsResponse struct {
	XMLName               xml.Name `json:"-" xml:"ListBucketResult"`
	EncodingType          string   `json:"encodingType" xml:"EncodingType"`
	Name                  string   `json:"name" xml:"Name"`
	Prefix                string   `json:"prefix" xml:"Prefix"`
	Delimiter             string   `json:"delimiter" xml:"Delimiter"`
	ContinuationToken     string   `json:"continuationToken" xml:"ContinuationToken"`
	NextContinuationToken string   `json:"nextContinuationToken" xml:"NextContinuationToken"`
	StartAfter            string   `json:"startAfter" xml:"StartAfter"`

	CommonPrefixes []*ListObjectCommonPrefix `json:"commonPrefixes" xml:"CommonPrefixes"`

	Contents []*ListObjectContent `json:"contents" xml:"Contents"`

	KeyCount    int  `json:"keyCount" xml:"KeyCount"`
	MaxKeys     int  `json:"maxKeys" xml:"MaxKeys"`
	IsTruncated bool `json:"isTruncated" xml:"IsTruncated"`
}

https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html#API_ListObjectsV2_ResponseSyntax

type ListParams 

type ListParams struct {
	// ContinuationToken indicates that the list is being continued on this bucket with a token.
	// ContinuationToken is obfuscated and is not a real key.
	// You can use this ContinuationToken for pagination of the list results.
	ContinuationToken string `json:"continuationToken"`

	// Delimiter is a character that you use to group keys.
	//
	// For directory buckets, "/" is the only supported delimiter.
	Delimiter string `json:"delimiter"`

	// Prefix limits the response to keys that begin with the specified prefix.
	Prefix string `json:"prefix"`

	// Encoding type is used to encode the object keys in the response.
	// Responses are encoded only in UTF-8.
	// An object key can contain any Unicode character.
	// However, the XML 1.0 parser can't parse certain characters,
	// such as characters with an ASCII value from 0 to 10.
	// For characters that aren't supported in XML 1.0, you can add
	// this parameter to request that S3 encode the keys in the response.
	//
	// Valid Values: url
	EncodingType string `json:"encodingType"`

	// StartAfter is where you want S3 to start listing from.
	// S3 starts listing after this specified key.
	// StartAfter can be any key in the bucket.
	//
	// This functionality is not supported for directory buckets.
	StartAfter string `json:"startAfter"`

	// MaxKeys Sets the maximum number of keys returned in the response.
	// By default, the action returns up to 1,000 key names.
	// The response might contain fewer keys but will never contain more.
	MaxKeys int `json:"maxKeys"`

	// FetchOwner returns the owner field with each key in the result.
	FetchOwner bool `json:"fetchOwner"`
}

ListParams defines optional parameters for the ListObject request.

func (*ListParams) Encode 

func (l *ListParams) Encode() string

Encode encodes the parameters in a properly formatted query string.

type ResponseError 

type ResponseError struct {
	XMLName   xml.Name `json:"-" xml:"Error"`
	Code      string   `json:"code" xml:"Code"`
	Message   string   `json:"message" xml:"Message"`
	RequestId string   `json:"requestId" xml:"RequestId"`
	Resource  string   `json:"resource" xml:"Resource"`
	Raw       []byte   `json:"-" xml:"-"`
	Status    int      `json:"status" xml:"Status"`
}

ResponseError defines a general S3 response error.

https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html

func (*ResponseError) Error 

func (err *ResponseError) Error() string

Error implements the std error interface.

type S3 

type S3 struct {
	// Client specifies a custom HTTP client to send the request with.
	//
	// If not explicitly set, fallbacks to http.DefaultClient.
	Client HTTPClient

	Bucket       string
	Region       string
	Endpoint     string // can be with or without the schema
	AccessKey    string
	SecretKey    string
	UsePathStyle bool
}

func (*S3) CopyObject 

func (s3 *S3) CopyObject(ctx context.Context, srcKey string, dstKey string, optReqFuncs ...func(*http.Request)) (*CopyObjectResponse, error)

CopyObject copies a single object from srcKey to dstKey destination. (both keys are expected to be operating within the same bucket).

https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html

func (*S3) DeleteObject 

func (s3 *S3) DeleteObject(ctx context.Context, key string, optFuncs ...func(*http.Request)) error

DeleteObject deletes a single object by its key.

https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html

func (*S3) GetObject 

func (s3 *S3) GetObject(ctx context.Context, key string, optFuncs ...func(*http.Request)) (*GetObjectResponse, error)

GetObject retrieves a single object by its key.

NB! Make sure to call GetObjectResponse.Body.Close() after done working with the result.

https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html

func (*S3) HeadObject 

func (s3 *S3) HeadObject(ctx context.Context, key string, optFuncs ...func(*http.Request)) (*HeadObjectResponse, error)

HeadObject sends a HEAD request for a single object to check its existence and to retrieve its metadata.

https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html

func (*S3) ListObjects 

func (s3 *S3) ListObjects(ctx context.Context, params ListParams, optReqFuncs ...func(*http.Request)) (*ListObjectsResponse, error)

ListObjects retrieves paginated objects list.

https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html

func (*S3) SignAndSend 

func (s3 *S3) SignAndSend(req *http.Request) (*http.Response, error)

SignAndSend signs the provided request per AWS Signature v4 and sends it.

It automatically normalizes all 40x/50x responses to ResponseError.

Note: Don't forget to call resp.Body.Close() after done with the result.

func (*S3) URL 

func (s3 *S3) URL(path string) string

URL constructs an S3 request URL based on the current configuration.

type Uploader 

type Uploader struct {
	// S3 is the S3 client instance performing the upload object request (required).
	S3 *S3

	// Payload is the object content to upload (required).
	Payload io.Reader

	// Key is the destination key of the uploaded object (required).
	Key string

	// Metadata specifies the optional metadata to write with the object upload.
	Metadata map[string]string

	// MaxConcurrency specifies the max number of workers to use when
	// performing chunked/multipart upload.
	//
	// If zero or negative, defaults to 5.
	//
	// This option is used only when the Payload size is > MinPartSize.
	MaxConcurrency int

	// MinPartSize specifies the min Payload size required to perform
	// chunked/multipart upload.
	//
	// If zero or negative, defaults to ~6MB.
	MinPartSize int
	// contains filtered or unexported fields
}

Uploader handles the upload of a single S3 object.

If the Payload size is less than the configured MinPartSize it sends a single (PutObject) request, otherwise performs chunked/multipart upload.

func (*Uploader) Upload 

func (u *Uploader) Upload(ctx context.Context, optReqFuncs ...func(*http.Request)) error

Upload processes the current Uploader instance.

Users can specify an optional optReqFuncs that will be passed down to all Upload internal requests (single upload, multipart init, multipart parts upload, multipart complete, multipart abort).

Note that after this call the Uploader should be discarded (aka. no longer can be used).

Source Files

View all Source files

Directories

Path Synopsis
Package tests contains various tests helpers and utilities to assist with the S3 client testing.
 Package tests contains various tests helpers and utilities to assist with the S3 client testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.