s3

Documentation

Overview

Package s3 contains an implementation of the `gokv.Store` interface for Amazon S3 and other S3-compatible services.

Index

• Variables
• type Client
  • func NewClient(options Options) (Client, error)
  • func (c Client) Close() error
  • func (c Client) Delete(k string) error
  • func (c Client) Get(k string, v any) (found bool, err error)
  • func (c Client) Set(k string, v any) error
• type Options

Variables

var DefaultOptions = Options{
	Codec: encoding.JSON,
}

DefaultOptions is an Options object with default values. Region: "" (use shared config file or environment variable), AWSaccessKeyID: "" (use shared credentials file or environment variable), AWSsecretAccessKey: "" (use shared credentials file or environment variable), CustomEndpoint: "", UsePathStyleAddressing: false, Codec: encoding.JSON

Types

type Client

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

Client is a gokv.Store implementation for S3.

func NewClient

func NewClient(options Options) (Client, error)

NewClient creates a new S3 client.

Credentials can be set in the options, but it's recommended to either use the shared credentials file (Linux: "~/.aws/credentials", Windows: "%UserProfile%\.aws\credentials") or environment variables (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY). See https://github.com/awsdocs/aws-go-developer-guide/blob/0ae5712d120d43867cf81de875cb7505f62f2d71/doc_source/configuring-sdk.rst#specifying-credentials.

func (Client) Close

func (c Client) Close() error

Close closes the client. In the S3 implementation this doesn't have any effect.

func (Client) Delete

func (c Client) Delete(k string) error

Delete deletes the stored value for the given key. Deleting a non-existing key-value pair does NOT lead to an error. The key must not be "".

func (Client) Get

func (c Client) Get(k string, v any) (found bool, err error)

Get retrieves the stored value for the given key. You need to pass a pointer to the value, so in case of a struct the automatic unmarshalling can populate the fields of the object that v points to with the values of the retrieved object's values. If no value is found it returns (false, nil). The key must not be "" and the pointer must not be nil.

func (Client) Set

func (c Client) Set(k string, v any) error

Set stores the given value for the given key. Values are automatically marshalled to JSON or gob (depending on the configuration). The key must not be "" and the value must not be nil.

type Options

type Options struct {
	// Name of the S3 bucket.
	// The bucket is automatically created if it doesn't exist yet.
	BucketName string
	// Region of the S3 service you want to use.
	// Valid values: https://docs.aws.amazon.com/general/latest/gr/rande.html#ddb_region.
	// E.g. "us-west-2".
	// Optional (read from shared config file or environment variable if not set).
	// Environment variable: "AWS_REGION".
	//
	// Note: A region is also required when using an S3-compatible cloud service and even when using a self-hosted solution.
	// Example for Google Cloud Storage: "EUROPE-WEST3".
	// Example for Alibaba Cloud Object Storage Service (OSS): "oss-ap-southeast-1".
	// Example for Scaleway Object Storage: "nl-ams".
	// Example for a locally running Minio server: "foo" (any value works).
	Region string
	// AWS access key ID (part of the credentials).
	// Optional (read from shared credentials file or environment variable if not set).
	// Environment variable: "AWS_ACCESS_KEY_ID".
	AWSaccessKeyID string
	// AWS secret access key (part of the credentials).
	// Optional (read from shared credentials file or environment variable if not set).
	// Environment variable: "AWS_SECRET_ACCESS_KEY".
	AWSsecretAccessKey string
	// CustomEndpoint allows you to set a custom S3 service endpoint.
	// This must be set if you want to use a different S3-compatible cloud service or self-hosted solution.
	// Example for Google Cloud Storage: "storage.googleapis.com".
	// Example for Alibaba Cloud Object Storage Service (OSS): "oss-ap-southeast-1.aliyuncs.com" (depending on the region you want to use).
	// Example for Scaleway Object Storage: "s3.nl-ams.scw.cloud" (depending on the region you want to use).
	// Example for a locally running Minio server: "http://localhost:9000".
	// If you don't include "http://", then HTTPS (with TLS) will be used.
	// Optional ("" by default)
	CustomEndpoint string
	// S3 differentiates between "virtual hosted bucket addressing" and "path-style addressing".
	// Example URL for the virtual host style: http://BUCKET.s3.amazonaws.com/KEY.
	// Example UL for the path style: http://s3.amazonaws.com/BUCKET/KEY.
	// Most S3-compatible servers work with both styles,
	// but some work only with the virtual host style (e.g. Alibaba Cloud Object Storage Service (OSS))
	// and some work only with the path style (especially self-hosted services like a Minio server running on localhost).
	// Optional (false by default).
	UsePathStyleAddressing bool
	// Encoding format.
	// Optional (encoding.JSON by default).
	Codec encoding.Codec
}

Options are the options for the S3 client.