s3blob

Documentation

Overview

Example (OpenBucketFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/blob"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/blob/s3blob"
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// blob.OpenBucket creates a *blob.Bucket from a URL.
	bucket, err := blob.OpenBucket(ctx, "s3://my-bucket?region=us-west-1")
	if err != nil {
		log.Fatal(err)
	}
	defer bucket.Close()
}

Index

• Constants
• Variables
• func Dial(cfg aws.Config) *s3.Client
• func OpenBucket(ctx context.Context, client *s3.Client, bucketName string, opts *Options) (*blob.Bucket, error)
• type Options
• type URLOpener
  • func (o *URLOpener) OpenBucketURL(ctx context.Context, u *url.URL) (*blob.Bucket, error)

Examples

• Package (OpenBucketFromURL)
• OpenBucket

Constants

const Scheme = "s3"

Scheme is the URL scheme s3blob registers its URLOpener under on blob.DefaultMux.

Variables

var OpenBucketV2 = OpenBucket

var Set = wire.NewSet(
	Dial,
)

Set holds Wire providers for this package.

Functions

func Dial

func Dial(cfg aws.Config) *s3.Client

Dial gets an AWS S3 service client using the AWS SDK V2.

func OpenBucket

func OpenBucket(ctx context.Context, client *s3.Client, bucketName string, opts *Options) (*blob.Bucket, error)

OpenBucket returns a *blob.Bucket backed by S3, using AWS SDK v2.

Example

package main

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"gocloud.dev/blob/s3blob"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// Establish a AWS Config.
	// See https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/ for more info.
	cfg, err := config.LoadDefaultConfig(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// Create a *blob.Bucket.
	client := s3.NewFromConfig(cfg)
	bucket, err := s3blob.OpenBucket(ctx, client, "my-bucket", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer bucket.Close()
}

Types

type Options

type Options struct {
	// UseLegacyList forces the use of ListObjects instead of ListObjectsV2.
	// Some S3-compatible services (like CEPH) do not currently support
	// ListObjectsV2.
	UseLegacyList bool

	// EncryptionType sets the encryption type headers when making write or
	// copy calls. This is required if the bucket has a restrictive bucket
	// policy that enforces a specific encryption type
	EncryptionType types.ServerSideEncryption

	// KMSEncryptionID sets the kms key id header for write or copy calls.
	// This is required when a bucket policy enforces the use of a specific
	// KMS key for uploads
	KMSEncryptionID string
}

Options sets options for constructing a *blob.Bucket backed by fileblob.

type URLOpener

type URLOpener struct {
	// Options specifies the options to pass to OpenBucket.
	Options Options
}

URLOpener opens S3 URLs like "s3://mybucket".

The URL host is used as the bucket name.

See https://pkg.go.dev/gocloud.dev/aws#V2ConfigFromURLParams.

The following S3-specific query options are also supported:

• ssetype: The type of server side encryption used (AES256, aws:kms, aws:kms:dsse)
• kmskeyid: The KMS key ID for server side encryption
• accelerate: A value of "true" uses the S3 Transfer Accleration endpoints
• use_path_style: A value of true sets the UsePathStyle option.
• s3ForcePathStyle: Same as use_path_style, for backwards compatibility with V1.
• disable_https: A value of true disables HTTPS in the Endpoint options.

func (*URLOpener) OpenBucketURL

func (o *URLOpener) OpenBucketURL(ctx context.Context, u *url.URL) (*blob.Bucket, error)

OpenBucketURL opens a blob.Bucket based on u.