https://docs.gofiber.io/assets/js/df1b2da5.1d10c4ce.js

1"use strict";(self.webpackChunkfiber_docs=self.webpackChunkfiber_docs||[]).push([["1265"],{922840(e,n,t){t.r(n),t.d(n,{metadata:()=>s,default:()=>g,frontMatter:()=>o,contentTitle:()=>a,toc:()=>c,assets:()=>l});var s=JSON.parse('{"id":"s3/s3","title":"S3","description":"Release","source":"@site/storage_versioned_docs/version-arangodb_v2.x.x/s3/README.md","sourceDirName":"s3","slug":"/s3/","permalink":"/storage/arangodb_v2.x.x/s3/","draft":false,"unlisted":false,"editUrl":"https://github.com/gofiber/storage/edit/main/s3/README.md","tags":[],"version":"arangodb_v2.x.x","lastUpdatedAt":1790279268000,"frontMatter":{"id":"s3","title":"S3"},"sidebar":"left_sidebar","previous":{"title":"Rueidis","permalink":"/storage/arangodb_v2.x.x/rueidis/"},"next":{"title":"ScyllaDb","permalink":"/storage/arangodb_v2.x.x/scylladb/"}}'),i=t(474848),r=t(28453);let o={id:"s3",title:"S3"},a,l={},c=[{value:"Table of Contents",id:"table-of-contents",level:3},{value:"Signatures",id:"signatures",level:3},{value:"Installation",id:"installation",level:3},{value:"Examples",id:"examples",level:3},{value:"Config",id:"config",level:3},{value:"Default Config",id:"default-config",level:3},{value:"Using an Existing S3 Client",id:"using-an-existing-s3-client",level:3}];function d(e){let n={a:"a",blockquote:"blockquote",code:"code",h3:"h3",img:"img",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,r.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.img,{src:"https://img.shields.io/github/v/tag/gofiber/storage?filter=s3*",alt:"Release"}),"\n",(0,i.jsx)(n.a,{href:"https://gofiber.io/discord",children:(0,i.jsx)(n.img,{src:"https://img.shields.io/discord/704680098577514527?style=flat&label=%F0%9F%92%AC%20discord&color=00ACD7",alt:"Discord"})}),"\n",(0,i.jsx)(n.img,{src:"https://img.shields.io/github/actions/workflow/status/gofiber/storage/test-s3.yml?label=Tests",alt:"Test"})]}),"\n",(0,i.jsxs)(n.p,{children:["A S3 storage driver using ",(0,i.jsx)(n.a,{href:"https://github.com/aws/aws-sdk-go-v2",children:"aws/aws-sdk-go-v2"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Note:"})," If config fields of credentials not given, credentials are using from the environment variables, ~/.aws/credentials, or EC2 instance role. If config fields of credentials given, credentials are using from config. Look at: ",(0,i.jsx)(n.a,{href:"https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials",children:"specifying credentials"})]}),"\n",(0,i.jsx)(n.h3,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"#signatures",children:"Signatures"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"#installation",children:"Installation"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"#examples",children:"Examples"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"#config",children:"Config"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"#default-config",children:"Default Config"})}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"signatures",children:"Signatures"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:"func New(config ...Config) Storage\nfunc NewFromConnection(svc *s3.Client, config ...Config) *Storage\nfunc (s *Storage) Get(key string) ([]byte, error)\nfunc (s *Storage) GetWithContext(ctx context.Context, key string) ([]byte, error)\nfunc (s *Storage) Set(key string, val []byte, exp time.Duration) error\nfunc (s *Storage) SetWithContext(ctx context.Context, key string, val []byte, exp time.Duration) error\nfunc (s *Storage) Delete(key string) error\nfunc (s *Storage) DeleteWithContext(ctx context.Context, key string) error\nfunc (s *Storage) Reset() error\nfunc (s *Storage) ResetWithContext(ctx context.Context) error\nfunc (s *Storage) Close() error\nfunc (s *Storage) Conn() *s3.Client\n\n// Additional useful methods.\nfunc (s *Storage) CreateBucket(bucket string) error\nfunc (s *Storage) DeleteBucket(bucket string) error\nfunc (s *Storage) DeleteMany(keys ...string) error\nfunc (s *Storage) SetWithChecksum(key string, val []byte, checksum map[types.ChecksumAlgorithm][]byte) error\n"})}),"\n",(0,i.jsx)(n.h3,{id:"installation",children:"Installation"}),"\n",(0,i.jsxs)(n.p,{children:["S3 is tested on the 2 last ",(0,i.jsx)(n.a,{href:"https://golang.org/dl/",children:"Go versions"})," with support for modules. So make sure to initialize one first if you didn't do that yet:"]}

1),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"go mod init github.com/<user>/<repo>\n"})}),"\n",(0,i.jsx)(n.p,{children:"And then install the s3 implementation:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"go get github.com/gofiber/storage/s3/v2\n"})}),"\n",(0,i.jsx)(n.h3,{id:"examples",children:"Examples"}),"\n",(0,i.jsx)(n.p,{children:"Import the storage package."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'import "github.com/gofiber/storage/s3/v2"\n'})}),"\n",(0,i.jsx)(n.p,{children:"You can use the following possibilities to create a storage:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'// Initialize default config\nstore := s3.New()\n\n// Initialize custom config\nstore := s3.New(s3.Config{\n	Bucket:   "my-bucket-url",\n	Endpoint: "my-endpoint",\n	Region:   "my-region",\n	Reset:    false,\n})\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Create an object with ",(0,i.jsx)(n.code,{children:"Set()"}),":"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'err := store.Set("my-key", []byte("my-value"))\n'})}),"\n",(0,i.jsxs)(n.p,{children:["Or, call ",(0,i.jsx)(n.code,{children:"SetWithChecksum()"})," to create an object with checksum to\nask S3 server to verify data integrity on server side:"]}),"\n",(0,i.jsxs)(n.blockquote,{children:["\n",(0,i.jsx)(n.p,{children:"Currently 4 algorithms are supported:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["types.ChecksumAlgorithmCrc32 (",(0,i.jsx)(n.code,{children:"CRC32"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:["types.ChecksumAlgorithmCrc32c (",(0,i.jsx)(n.code,{children:"CRC32C"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:["types.ChecksumAlgorithmSha1 (",(0,i.jsx)(n.code,{children:"SHA1"}),")"]}),"\n",(0,i.jsxs)(n.li,{children:["types.ChecksumAlgorithmSha256 (",(0,i.jsx)(n.code,{children:"SHA256"}),")"]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["For more information, see ",(0,i.jsx)(n.a,{href:"https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#PutObjectInput",children:"PutObjectInput"}),"."]}),"\n"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'key := "my-key"\nval := []byte("my-value")\n\nhash := sha256.New()\nhash.Write(val)\nsha256sum := hash.Sum(nil)\n\n// import "github.com/aws/aws-sdk-go-v2/service/s3/types"\nchecksum  = map[types.ChecksumAlgorithm][]byte{\n    types.ChecksumAlgorithmSha256: sha256sum,\n}\n\nerr := store.SetWithChecksum(key, val, checksum)\n'})}),"\n",(0,i.jsx)(n.h3,{id:"config",children:"Config"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:"// Config defines the config for storage.\ntype Config struct {\n	// S3 bucket name\n	Bucket string\n\n	// AWS endpoint\n	Endpoint string\n\n	// AWS region\n	Region string\n\n	// Request timeout\n	//\n	// Optional. Default is 0 (no timeout)\n	RequestTimeout time.Duration\n\n	// Reset clears any existing keys in existing Bucket\n	//\n	// Optional. Default is false\n	Reset bool\n\n    // Credentials overrides AWS access key and AWS secret access key. Not recommended.\n	//\n	// Optional. Default is Credentials{}\n	Credentials Credentials\n\n	// The maximum number of times requests that encounter retryable failures should be attempted.\n	//\n	// Optional. Default is 3\n	MaxAttempts int\n\n}\n\ntype Credentials struct {\n	AccessKey       string\n	SecretAccessKey string\n}\n"})}),"\n",(0,i.jsx)(n.h3,{id:"default-config",children:"Default Config"}),"\n",(0,i.jsx)(n.p,{children:"The default configuration lacks Bucket, Region, and Endpoint which are all required and must be overwritten:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'// ConfigDefault is the default config\nvar ConfigDefault = Config{\n	Bucket:         "",\n	Region:         "",\n	Endpoint:       "",\n	Credentials:    Credentials{},\n	MaxAttempts:    3,\n	RequestTimeout: 0,\n	Reset:          false,\n}\n'})}),"\n",(0,i.jsx)(n.h3,{id:"using-an-existing-s3-client",children:"Using an Existing S3 Client"}),"\n",(0,i.jsxs)(n.p,{children:["If your application already holds an ",(0,i.jsx)(n.code,{children:"*s3.Client"}),", you can build the storage on it instead of creating a second one. Only the ",(0,i.jsx)(n.code,{children:"Bucket"}),", ",(0,i.jsx)(n.code,{children:"RequestTimeout"})," and ",(0,i.jsx)(n.code,{children:"Reset"})," options are read; the endpoint and credentials come from the client."]}),"\n",(0,i.jsxs)(n.p,{children:["The client stays yours to manage: ",(0,i.jsx)(n.code,{children:"Close"})," on a storage built this way is a no-op, so the rest of your application keeps working."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-go",children:'import (\n    "context"\n\n    awsconfig "github.com/aws/aws-sdk-go-v2/config"\n    awss3 "github.com/aws/aws-sdk-go-v2/service/s3"\n    "github.com/gofiber/storage/s3/v2"\n)\n\nfunc main() {\n    awscfg, err := awsconfig.LoadDefaultConfig(context.Backgroun

1d())\n    if err != nil {\n        panic(err)\n    }\n\n    client := awss3.NewFromConfig(awscfg)\n\n    store := s3.NewFromConnection(client, s3.Config{\n        Bucket: "my-bucket",\n    })\n    defer store.Close()\n}\n'})})]})}function g(e={}){let{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},28453(e,n,t){t.d(n,{R:()=>o,x:()=>a});var s=t(296540);let i={},r=s.createContext(i);function o(e){let n=s.useContext(r);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:o(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);