storage

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2023 License: MIT Imports: 31 Imported by: 0

README

storage

Go Reference

Inspired by ActiveStorage from Rails.

Service

  • Disk
  • AWS S3
  • Google Cloud Storage
  • MicroSoft Azure Storage

TODO

  • Public URL
  • Private URL (Signed URL)
  • Direct upload URL

Documentation

Usage

Use Service to manipulate files.

import (
  "bytes"
  "context"
  "log"

  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/bastengao/go-storage"
)

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
  log.Fatal(err)
}

service, err := storage.NewS3(cfg, "bucket", "https://bucket.us-east-1.s3.amazonaws.com")
if err != nil {
  log.Fatal(err)
}

err = service.Upload(context.TODO(), "test/abc.txt", bytes.NewReader([]byte("hello world")))
if err != nil {
  log.Fatal(err)
}

err = service.Delete(context.TODO(), "test/abc.txt")
if err != nil {
  log.Fatal(err)
}
Transforming Images
store = storage.New(service, nil)

// transform image "sample.jpg" to a new jpeg with quality 75 and size 100x100 
options := storage.VariantOptions{}.
  SetFormat("jpeg").
  SetSize(100).
  SetQuality(75)
variant := store.Variant("sample.jpg", options)
err = variant.Process() // generate variant automatically if variant not exits
if err != nil {
  log.Fatal(err)
}
key := variant.Key()
// variants/sample-9c1aec99c27e6c66d895519f9ef831da.jpeg
Serve files and variants

server.Handler will redirect to the actual service endpoint. This indirection decouples the service URL from the actual one.

server := storage.NewServer("http://127.0.0.1:8080/storage/redirect", store, nil, nil)
url := server.URL("sample.jpg", nil)
// http://127.0.0.1:8080/storage/redirect?key=sample.jpg
variantURL := server.URL("sample.jpg", options)
// http://127.0.0.1:8080/storage/redirect?key=sample.jpg&format=jpeg&size=100&quality=75
// accessing variantURL will generate variant automatically if variant not exits

http.Handle("/storage/redirect", server.Handler())
err = http.ListenAndServe(":8080", nil)
if err != nil {
  panic(err)
}

Documentation

Index

Constants

View Source 
const (
	CtxS3ACL         contextKey = "s3_acl"
	CtxS3ContentType contextKey = "s3_contentType"
)
View Source 
const (
	Ctx_GCS_ACL contextKey = "gcs_acl"
)

Variables

This section is empty.

Functions

func MimeTypeByExtension 

func MimeTypeByExtension(ext string) string

func RedirectURL 

func RedirectURL(endpoint string, key string, options VariantOptions) string

RedirectURL returns serving URL of the variant. Deprecated: out of date.

func ServeDisk 

func ServeDisk(routePath string, dir string) http.Handler

ServeDisk serves files from the given directory.

func URL 

func URL(endpoint, p string) string

func WithGcsACL 

func WithGcsACL(ctx context.Context, entity gstorage.ACLEntity, role gstorage.ACLRole) context.Context

func WithGcsAllUsersRead 

func WithGcsAllUsersRead(ctx context.Context) context.Context

func WithS3ContentType 

func WithS3ContentType(ctx context.Context, contentType string) context.Context

WithS3ContentType set s3 object content-type for upload and copy.

func WithS3Private 

func WithS3Private(ctx context.Context) context.Context

WithS3Private set s3 object acl to private for upload and copy.

func WithS3PublicRead 

func WithS3PublicRead(ctx context.Context) context.Context

WithS3PublicRead set s3 object acl to public-read for upload and copy.

Types

type NewVariantFunc 

type NewVariantFunc func(service Service, originKey string, options VariantOptions) Variant

func (NewVariantFunc) NewVariant 

func (f NewVariantFunc) NewVariant(service Service, originPath string, options VariantOptions) Variant

type NullService 

type NullService struct{}

func (NullService) Copy 

func (NullService) Copy(ctx context.Context, src string, dst string) error

func (NullService) Delete 

func (NullService) Delete(ctx context.Context, key string) error

func (NullService) DeleteBatch 

func (NullService) DeleteBatch(ctx context.Context, keys []string) error

func (NullService) DeletePrefixed 

func (NullService) DeletePrefixed(ctx context.Context, prefix string) error

func (NullService) Download 

func (NullService) Download(ctx context.Context, key string) (io.ReadCloser, error)

func (NullService) Exist 

func (NullService) Exist(ctx context.Context, key string) (bool, error)

func (NullService) SignURL added in v0.2.0 

func (NullService) SignURL(ctx context.Context, key string, method string, expiresIn time.Duration) (string, http.Header, error)

func (NullService) URL 

func (NullService) URL(key string) string

func (NullService) Upload 

func (NullService) Upload(ctx context.Context, key string, reader io.Reader) error

type S3Options 

type S3Options struct {
	// config upload or copy ACL. Default is private
	ACL *types.ObjectCannedACL
}

type Server 

type Server interface {
	Handler() http.Handler
	URL(key string, options VariantOptions, urlOptions ...URLOption) string
}

func NewServer 

func NewServer(endpoint string, storage Storage, options ...ServerOption) Server

NewServer creates a new server. keyEncoder and keyDecoder are optional.

Default key will keep unchanged in query, such as "key=sample.jpg". keyEncoder and keyDecoder can be used to encode/decode key.

type ServerOption added in v0.3.0 

type ServerOption func(o *ServerOptions)

type ServerOptions added in v0.3.0 

type ServerOptions struct {
	KeyEncoder func(key string) string
	KeyDecoder func(encodedKey string) string
	// URLResolver is used to resolve the URL of the variant or origin file.
	// Default will use Service.URL(key) method
	URLResolver func(key string) string
	// Will sign serving URL to prevent somebody to change serving URL
	SigningKey []byte
	// Expire duration for signed serving URL
	SigningExpires time.Duration
}

type Service 

type Service interface {
	Upload(ctx context.Context, key string, reader io.Reader) error
	Download(ctx context.Context, key string) (io.ReadCloser, error)
	Copy(ctx context.Context, src string, dst string) error
	Delete(ctx context.Context, key string) error
	DeleteBatch(ctx context.Context, keys []string) error
	DeletePrefixed(ctx context.Context, prefix string) error
	Exist(ctx context.Context, key string) (bool, error)
	URL(key string) string
	// SignURL returns a signed URL for the given key.
	//
	// method must be one of "GET", "PUT", "HEAD", "DELETE".
	SignURL(ctx context.Context, key string, method string, expiresIn time.Duration) (string, http.Header, error)
}

func NewDiskService 

func NewDiskService(dir string, endpoint string) (Service, error)

NewDiskService creates a new disk service. dir is the directory to store the files.

func NewGCSService 

func NewGCSService(bucket string, endpoint string) (Service, error)

func NewGCSServiceWithClient 

func NewGCSServiceWithClient(bucket string, endpoint string, client *gstorage.Client) Service

func NewNullService 

func NewNullService() Service

func NewS3 

func NewS3(cfg aws.Config, bucket string, endpoint string, options ...S3Options) (Service, error)

type Storage 

type Storage interface {
	// TODO: Service
	Service() Service
	Variant(key string, options VariantOptions) Variant
}

func New 

func New(service Service, variantFactory VariantFactory) Storage

New creates a new storage. If variantFactory is nil, NewVariantFactory(NewTransformer()) will be used.

type Transformer 

type Transformer interface {
	Transform(ctx context.Context, options VariantOptions, format string, source io.Reader, writer io.Writer) error
}

func NewTransformer 

func NewTransformer() Transformer

type URLOption added in v0.5.0 

type URLOption func(o *URLOptions)

func WithURLExpires added in v0.5.0 

func WithURLExpires(expires time.Duration) URLOption

WithURLExpires sets the expires of the serving URL. 0 means never expires.

func (URLOption) Apply added in v0.5.0 

func (o URLOption) Apply(options *URLOptions)

type URLOptions added in v0.5.0 

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

type URLSigner added in v0.4.0 

type URLSigner interface {
	// exp will be ignored if exp is 0.
	Sign(url string, exp time.Duration) (string, error)
	// return error if invalid
	Validate(signedUrl string) error
}

func NewHmacURLSigner added in v0.4.0 

func NewHmacURLSigner(key []byte) URLSigner

type Variant 

type Variant interface {
	Process() error
	Key() string
	URL() string
}

func NewVariant 

func NewVariant(service Service, originKey string, options VariantOptions, transformer Transformer) Variant

type VariantFactory 

type VariantFactory interface {
	NewVariant(service Service, originPath string, options VariantOptions) Variant
}

func NewVariantFactory 

func NewVariantFactory(transformer Transformer) VariantFactory

type VariantOptions 

type VariantOptions map[string]any

func ParseVariantOptions 

func ParseVariantOptions(query url.Values) (VariantOptions, error)

func (VariantOptions) Format 

func (o VariantOptions) Format() string

func (VariantOptions) Get added in v0.4.0 

func (o VariantOptions) Get(key string) any

func (VariantOptions) Quality 

func (o VariantOptions) Quality() int

func (VariantOptions) ResizeToFill 

func (o VariantOptions) ResizeToFill() ([2]int, bool)

func (VariantOptions) Set added in v0.4.0 

func (o VariantOptions) Set(key string, value any) VariantOptions

func (VariantOptions) SetFormat 

func (o VariantOptions) SetFormat(format string) VariantOptions

SetFormat sets the format of the variant. Must be one of "jpg", "png".

func (VariantOptions) SetQuality 

func (o VariantOptions) SetQuality(quality int) VariantOptions

SetQuality sets the quality of the variant. Must be between 1 and 100. Default is 80.

func (VariantOptions) SetResizeToFill 

func (o VariantOptions) SetResizeToFill(size [2]int) VariantOptions

SetResizeToFill sets the with and height of the variant. Cut the image to a rectangle from the center and resize it to the given size.

func (VariantOptions) SetSize 

func (o VariantOptions) SetSize(size int) VariantOptions

SetSize sets the size of the variant. Cut the image to a square from the center and resize it to the given size.

func (VariantOptions) Size 

func (o VariantOptions) Size() int

func (VariantOptions) URLQuery 

func (o VariantOptions) URLQuery() map[string]string

Source Files

View all Source files

Directories

Path Synopsis
example
disk
s3

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.