From f57f4f82e824e6110767c7c7d67d87ff7e83e9e7 Mon Sep 17 00:00:00 2001 From: tom twinkle Date: Mon, 19 Aug 2024 14:05:39 +0900 Subject: [PATCH] document: add s3 options comment --- aws/awss3/options/s3download/s3_download.go | 3 +++ aws/awss3/options/s3head/s3_head.go | 13 +++++++++++++ aws/awss3/options/s3list/s3_head.go | 10 ++++++++++ aws/awss3/options/s3presigned/s3_presigned.go | 19 +++++++++++++++++-- 4 files changed, 43 insertions(+), 2 deletions(-) diff --git a/aws/awss3/options/s3download/s3_download.go b/aws/awss3/options/s3download/s3_download.go index 0e923c5..5d0ab83 100644 --- a/aws/awss3/options/s3download/s3_download.go +++ b/aws/awss3/options/s3download/s3_download.go @@ -5,6 +5,7 @@ type OptionS3Download interface { } type confS3Download struct { + // Sets the function used to replace file names in downloaded files. FileNameReplacer FileNameReplacerFunc } @@ -15,6 +16,8 @@ func (o OptionFileNameReplacer) Apply(c *confS3Download) { c.FileNameReplacer = FileNameReplacerFunc(o) } +// WithFileNameReplacerFunc +// Sets the function used to replace file names in downloaded files. func WithFileNameReplacerFunc(fileNameReplacerFunc FileNameReplacerFunc) OptionFileNameReplacer { return OptionFileNameReplacer(fileNameReplacerFunc) } diff --git a/aws/awss3/options/s3head/s3_head.go b/aws/awss3/options/s3head/s3_head.go index b0bf2c1..db833cb 100644 --- a/aws/awss3/options/s3head/s3_head.go +++ b/aws/awss3/options/s3head/s3_head.go @@ -31,6 +31,9 @@ func (o OptionTimeout) Apply(c *confS3Head) { c.Timeout = time.Duration(o) } +// WithTimeout +// Timeout can specify the number of seconds to wait when using a waiter +// to check for the existence of an object. func WithTimeout(duration time.Duration) OptionTimeout { return OptionTimeout(duration) } @@ -41,6 +44,10 @@ func (o OptionMinDelay) Apply(c *confS3Head) { c.MinDelay = time.Duration(o) } +// WithMinDelay +// MinDelay is the minimum amount of time to delay between retries. If unset, +// ObjectExistsWaiter will use default minimum delay of 5 seconds. Note that +// MinDelay must resolve to a value lesser than or equal to the MaxDelay. func WithMinDelay(minDelay time.Duration) OptionMinDelay { return OptionMinDelay(minDelay) } @@ -51,6 +58,10 @@ func (o OptionMaxDelay) Apply(c *confS3Head) { c.MaxDelay = time.Duration(o) } +// WithMaxDelay +// MaxDelay is the maximum amount of time to delay between retries. If unset or set +// to zero, ObjectExistsWaiter will use default max delay of 120 seconds. Note that +// MaxDelay must resolve to value greater than or equal to the MinDelay. func WithMaxDelay(maxDelay time.Duration) OptionMaxDelay { return OptionMaxDelay(maxDelay) } @@ -61,6 +72,8 @@ func (o OptionLogWaitAttempts) Apply(c *confS3Head) { c.LogWaitAttempts = bool(o) } +// WithLogWaitAttempts +// LogWaitAttempts is used to enable logging for waiter retry attempts func WithLogWaitAttempts(logWaitAttempts bool) OptionLogWaitAttempts { return OptionLogWaitAttempts(logWaitAttempts) } diff --git a/aws/awss3/options/s3list/s3_head.go b/aws/awss3/options/s3list/s3_head.go index 5f7010d..3572538 100644 --- a/aws/awss3/options/s3list/s3_head.go +++ b/aws/awss3/options/s3list/s3_head.go @@ -5,7 +5,11 @@ type OptionS3List interface { } type confS3List struct { + // https://github.com/aws/aws-sdk-go-v2/blob/v1.30.4/service/s3/api_op_ListObjectsV2.go#L201-L205 // Limits the response to keys that begin with the specified prefix. + // + // Directory buckets - For directory buckets, only prefixes that end in a + // delimiter ( / ) are supported. Prefix *string } @@ -16,6 +20,12 @@ func (o OptionPrefix) Apply(c *confS3List) { c.Prefix = &v } +// WithPrefix +// https://github.com/aws/aws-sdk-go-v2/blob/v1.30.4/service/s3/api_op_ListObjectsV2.go#L201-L205 +// Limits the response to keys that begin with the specified prefix. +// +// Directory buckets - For directory buckets, only prefixes that end in a +// delimiter ( / ) are supported. func WithPrefix(prefix string) OptionPrefix { return OptionPrefix(prefix) } diff --git a/aws/awss3/options/s3presigned/s3_presigned.go b/aws/awss3/options/s3presigned/s3_presigned.go index 2571ad9..b4985cc 100644 --- a/aws/awss3/options/s3presigned/s3_presigned.go +++ b/aws/awss3/options/s3presigned/s3_presigned.go @@ -7,14 +7,22 @@ type OptionS3Presigned interface { } type confS3Presigned struct { + // ContentDispositionType is the type of the Content-Disposition header. ContentDispositionType ContentDispositionType - PresignExpires time.Duration - PresignFileName string + // PresignExpires is the duration that the presigned URL will be valid for. + PresignExpires time.Duration + // PresignFileName is the name of the file that will be returned in the Content-Disposition header. + PresignFileName string } type ContentDispositionType int const ( + // ContentDispositionTypeAttachment is the Content-Disposition header type for attachment. + // default value, indicating it should be downloaded; most browsers presenting a 'Save as' dialog, + // prefilled with the value of the filename parameters if present. ContentDispositionTypeAttachment ContentDispositionType = iota + // ContentDispositionTypeInline is the Content-Disposition header type for inline. + // indicating it can be displayed inside the Web page, or as the Web page. ContentDispositionTypeInline ) @@ -36,6 +44,9 @@ func (o OptionPresignFileName) Apply(c *confS3Presigned) { c.PresignFileName = string(o) } +// WithPresignFileName +// PresignFileName is the name of the file that will be returned in the Content-Disposition header. +// If set, the Content-Disposition header must be set to ContentDispositionTypeAttachment. func WithPresignFileName(fileName string) OptionPresignFileName { return OptionPresignFileName(fileName) } @@ -46,6 +57,8 @@ func (o OptionPresignExpires) Apply(c *confS3Presigned) { c.PresignExpires = time.Duration(o) } +// WithPresignExpires +// PresignExpires is the duration that the presigned URL will be valid for. func WithPresignExpires(presignExpires time.Duration) OptionPresignExpires { return OptionPresignExpires(presignExpires) } @@ -56,6 +69,8 @@ func (o OptionContentDispositionType) Apply(c *confS3Presigned) { c.ContentDispositionType = ContentDispositionType(o) } +// WithContentDispositionType +// ContentDispositionType is the type of the Content-Disposition header. func WithContentDispositionType(tp ContentDispositionType) OptionContentDispositionType { return OptionContentDispositionType(tp) }