From 18e547ee1033f7c7c577c31c71c250ba2f402ee1 Mon Sep 17 00:00:00 2001 From: Robert van Gent Date: Mon, 4 Jul 2022 21:37:59 -0700 Subject: [PATCH] all: Reformat using the new gofmt --- aws/aws.go | 16 +- blob/azureblob/azureblob.go | 52 +++---- blob/blob.go | 29 ++-- blob/drivertest/bindata.go | 12 +- blob/drivertest/drivertest.go | 17 ++- blob/fileblob/fileblob.go | 60 ++++---- blob/gcsblob/gcsblob.go | 30 ++-- blob/memblob/memblob.go | 4 +- blob/s3blob/s3blob.go | 50 +++---- blob/s3blob/s3blob_test.go | 7 +- doc.go | 4 +- docstore/awsdynamodb/dynamo.go | 16 +- docstore/doc.go | 140 +++++++++--------- docstore/docstore.go | 16 +- docstore/gcpfirestore/fs.go | 25 ++-- docstore/gcpfirestore/urls.go | 1 + docstore/internal/fields/fields.go | 30 ++-- docstore/internal/fields/fold.go | 5 +- docstore/memdocstore/mem.go | 6 +- docstore/memdocstore/urls.go | 4 +- docstore/mongodocstore/mongo.go | 23 ++- docstore/mongodocstore/query.go | 4 +- internal/openurl/openurl_test.go | 2 +- internal/releasehelper/releasehelper.go | 8 +- internal/releasehelper/releasehelper_test.go | 3 +- internal/testing/test-summary/test-summary.go | 3 +- mysql/awsmysql/awsmysql.go | 2 +- mysql/azuremysql/azuremysql.go | 2 +- mysql/gcpmysql/gcpmysql.go | 2 +- postgres/awspostgres/awspostgres.go | 2 +- postgres/gcppostgres/gcppostgres.go | 2 +- pubsub/acks_test.go | 2 +- pubsub/awssnssqs/awssnssqs.go | 38 ++--- pubsub/azuresb/azuresb.go | 18 +-- pubsub/azuresb/azuresb_test.go | 2 +- pubsub/drivertest/drivertest.go | 4 +- pubsub/gcppubsub/gcppubsub.go | 18 +-- pubsub/kafkapubsub/kafka.go | 18 +-- pubsub/mempubsub/mem.go | 8 +- pubsub/natspubsub/nats.go | 16 +- pubsub/pubsub.go | 43 +++--- pubsub/pubsub_test.go | 2 +- pubsub/rabbitpubsub/doc.go | 18 +-- pubsub/sub_test.go | 2 +- runtimevar/awsparamstore/awsparamstore.go | 14 +- .../awssecretsmanager/awssecretsmanager.go | 14 +- runtimevar/blobvar/blobvar.go | 14 +- runtimevar/constantvar/constantvar.go | 10 +- runtimevar/etcdvar/etcdvar.go | 10 +- runtimevar/filevar/filevar.go | 13 +- .../gcpruntimeconfig/gcpruntimeconfig.go | 17 ++- .../gcpsecretmanager/gcpsecretmanager.go | 17 ++- runtimevar/httpvar/httpvar.go | 12 +- runtimevar/runtimevar.go | 10 +- samples/order/order.go | 6 +- secrets/awskms/kms.go | 6 +- secrets/azurekeyvault/akv.go | 4 +- secrets/gcpkms/kms.go | 6 +- secrets/hashivault/vault.go | 4 +- secrets/localsecrets/localsecrets.go | 4 +- secrets/secrets.go | 8 +- 61 files changed, 474 insertions(+), 461 deletions(-) diff --git a/aws/aws.go b/aws/aws.go index b145c53e92..8b16a3b533 100644 --- a/aws/aws.go +++ b/aws/aws.go @@ -77,10 +77,10 @@ func (co ConfigOverrider) ClientConfig(serviceName string, cfgs ...*aws.Config) // ConfigFromURLParams. // // The following query options are supported: -// - region: The AWS region for requests; sets aws.Config.Region. -// - endpoint: The endpoint URL (hostname only or fully qualified URI); sets aws.Config.Endpoint. -// - disableSSL: A value of "true" disables SSL when sending requests; sets aws.Config.DisableSSL. -// - s3ForcePathStyle: A value of "true" forces the request to use path-style addressing; sets aws.Config.S3ForcePathStyle. +// - region: The AWS region for requests; sets aws.Config.Region. +// - endpoint: The endpoint URL (hostname only or fully qualified URI); sets aws.Config.Endpoint. +// - disableSSL: A value of "true" disables SSL when sending requests; sets aws.Config.DisableSSL. +// - s3ForcePathStyle: A value of "true" forces the request to use path-style addressing; sets aws.Config.S3ForcePathStyle. func ConfigFromURLParams(q url.Values) (*aws.Config, error) { var cfg aws.Config for param, values := range q { @@ -119,8 +119,8 @@ func ConfigFromURLParams(q url.Values) (*aws.Config, error) { // parameters it knows about // // The following query options are supported: -// - profile: The AWS profile to use from the AWS configs (shared config file and -// shared credentials file) +// - profile: The AWS profile to use from the AWS configs (shared config file and +// shared credentials file) func NewSessionFromURLParams(q url.Values) (*session.Session, url.Values, error) { // always enable shared config (~/.aws/config by default) opts := session.Options{SharedConfigState: session.SharedConfigEnable} @@ -175,8 +175,8 @@ func NewDefaultV2Config(ctx context.Context) (awsv2.Config, error) { // V2ConfigFromURLParams. // // The following query options are supported: -// - region: The AWS region for requests; sets WithRegion. -// - profile: The shared config profile to use; sets SharedConfigProfile. +// - region: The AWS region for requests; sets WithRegion. +// - profile: The shared config profile to use; sets SharedConfigProfile. func V2ConfigFromURLParams(ctx context.Context, q url.Values) (awsv2.Config, error) { var opts []func(*awsv2cfg.LoadOptions) error for param, values := range q { diff --git a/blob/azureblob/azureblob.go b/blob/azureblob/azureblob.go index 8e1ca4f304..7bcd101832 100644 --- a/blob/azureblob/azureblob.go +++ b/blob/azureblob/azureblob.go @@ -20,7 +20,7 @@ // set to "BlockBlob". // See https://stackoverflow.com/questions/37824136/put-on-sas-blob-url-without-specifying-x-ms-blob-type-header. // -// URLs +// # URLs // // For blob.OpenBucket, azureblob registers for the scheme "azblob". // The default URL opener will use credentials from the environment variables @@ -37,34 +37,34 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings; to make this work with services lacking // full UTF-8 support, strings must be escaped (during writes) and unescaped // (during reads). The following escapes are performed for azureblob: -// - Blob keys: ASCII characters 0-31, 92 ("\"), and 127 are escaped to -// "__0x__". Additionally, the "/" in "../" and a trailing "/" in a -// key (e.g., "foo/") are escaped in the same way. -// - Metadata keys: Per https://docs.microsoft.com/en-us/azure/storage/blobs/storage-properties-metadata, -// Azure only allows C# identifiers as metadata keys. Therefore, characters -// other than "[a-z][A-z][0-9]_" are escaped using "__0x__". In addition, -// characters "[0-9]" are escaped when they start the string. -// URL encoding would not work since "%" is not valid. -// - Metadata values: Escaped using URL encoding. +// - Blob keys: ASCII characters 0-31, 92 ("\"), and 127 are escaped to +// "__0x__". Additionally, the "/" in "../" and a trailing "/" in a +// key (e.g., "foo/") are escaped in the same way. +// - Metadata keys: Per https://docs.microsoft.com/en-us/azure/storage/blobs/storage-properties-metadata, +// Azure only allows C# identifiers as metadata keys. Therefore, characters +// other than "[a-z][A-z][0-9]_" are escaped using "__0x__". In addition, +// characters "[0-9]" are escaped when they start the string. +// URL encoding would not work since "%" is not valid. +// - Metadata values: Escaped using URL encoding. // -// As +// # As // // azureblob exposes the following types for As: -// - Bucket: *azblob.ContainerURL -// - Error: azblob.StorageError -// - ListObject: azblob.BlobItemInternal for objects, azblob.BlobPrefix for "directories" -// - ListOptions.BeforeList: *azblob.ListBlobsSegmentOptions -// - Reader: azblob.DownloadResponse -// - Reader.BeforeRead: *azblob.BlockBlobURL, *azblob.BlobAccessConditions -// - Attributes: azblob.BlobGetPropertiesResponse -// - CopyOptions.BeforeCopy: azblob.Metadata, *azblob.ModifiedAccessConditions, *azblob.BlobAccessConditions -// - WriterOptions.BeforeWrite: *azblob.UploadStreamToBlockBlobOptions -// - SignedURLOptions.BeforeSign: *azblob.BlobSASSignatureValues +// - Bucket: *azblob.ContainerURL +// - Error: azblob.StorageError +// - ListObject: azblob.BlobItemInternal for objects, azblob.BlobPrefix for "directories" +// - ListOptions.BeforeList: *azblob.ListBlobsSegmentOptions +// - Reader: azblob.DownloadResponse +// - Reader.BeforeRead: *azblob.BlockBlobURL, *azblob.BlobAccessConditions +// - Attributes: azblob.BlobGetPropertiesResponse +// - CopyOptions.BeforeCopy: azblob.Metadata, *azblob.ModifiedAccessConditions, *azblob.BlobAccessConditions +// - WriterOptions.BeforeWrite: *azblob.UploadStreamToBlockBlobOptions +// - SignedURLOptions.BeforeSign: *azblob.BlobSASSignatureValues package azureblob import ( @@ -207,10 +207,10 @@ const Scheme = "azblob" // The URL host is used as the bucket name. // // The following query options are supported: -// - domain: The domain name used to access the Azure Blob storage (e.g. blob.core.windows.net) -// - protocol: The protocol to use (e.g., http or https; default to https) -// - cdn: Set to true when domain represents a CDN -// - localemu: Set to true when domain points to the Local Storage Emulator (Azurite) +// - domain: The domain name used to access the Azure Blob storage (e.g. blob.core.windows.net) +// - protocol: The protocol to use (e.g., http or https; default to https) +// - cdn: Set to true when domain represents a CDN +// - localemu: Set to true when domain points to the Local Storage Emulator (Azurite) // // See Options for more details. type URLOpener struct { diff --git a/blob/blob.go b/blob/blob.go index 45a55af742..b136cbe654 100644 --- a/blob/blob.go +++ b/blob/blob.go @@ -18,8 +18,7 @@ // // See https://gocloud.dev/howto/blob/ for a detailed how-to guide. // -// -// Errors +// # Errors // // The errors returned from this package can be inspected in several ways: // @@ -29,20 +28,20 @@ // The Bucket.ErrorAs method can retrieve the driver error underlying the returned // error. // -// -// OpenCensus Integration +// # OpenCensus Integration // // OpenCensus supports tracing and metric collection for multiple languages and // backend providers. See https://opencensus.io. // // This API collects OpenCensus traces and metrics for the following methods: -// - Attributes -// - Copy -// - Delete -// - ListPage -// - NewRangeReader, from creation until the call to Close. (NewReader and ReadAll -// are included because they call NewRangeReader.) -// - NewWriter, from creation until the call to Close. +// - Attributes +// - Copy +// - Delete +// - ListPage +// - NewRangeReader, from creation until the call to Close. (NewReader and ReadAll +// are included because they call NewRangeReader.) +// - NewWriter, from creation until the call to Close. +// // All trace and metric names begin with the package import path. // The traces add the method name. // For example, "gocloud.dev/blob/Attributes". @@ -52,8 +51,8 @@ // For example, "gocloud.dev/blob/latency". // // It also collects the following metrics: -// - gocloud.dev/blob/bytes_read: the total number of bytes read, by driver. -// - gocloud.dev/blob/bytes_written: the total number of bytes written, by driver. +// - gocloud.dev/blob/bytes_read: the total number of bytes read, by driver. +// - gocloud.dev/blob/bytes_written: the total number of bytes written, by driver. // // To enable trace collection in your application, see "Configure Exporter" at // https://opencensus.io/quickstart/go/tracing. @@ -1309,9 +1308,9 @@ func DefaultURLMux() *URLMux { // the following query parameters: // // - prefix: wraps the resulting Bucket using PrefixedBucket with the -// given prefix. +// given prefix. // - key: wraps the resulting Bucket using SingleKeyBucket with the -// given key. +// given key. func OpenBucket(ctx context.Context, urlstr string) (*Bucket, error) { return defaultURLMux.OpenBucket(ctx, urlstr) } diff --git a/blob/drivertest/bindata.go b/blob/drivertest/bindata.go index 2f3f3ea823..a9ee194bfa 100644 --- a/blob/drivertest/bindata.go +++ b/blob/drivertest/bindata.go @@ -99,11 +99,13 @@ var _bindata = map[string]func() ([]byte, error){ // directory embedded in the file by go-bindata. // For example if you run go-bindata on data/... and data contains the // following hierarchy: -// data/ -// foo.txt -// img/ -// a.png -// b.png +// +// data/ +// foo.txt +// img/ +// a.png +// b.png +// // then AssetDir("data") would return []string{"foo.txt", "img"} // AssetDir("data/img") would return []string{"a.png", "b.png"} // AssetDir("foo.txt") and AssetDir("notexist") would return an error diff --git a/blob/drivertest/drivertest.go b/blob/drivertest/drivertest.go index 418d0c65bf..482b7920e9 100644 --- a/blob/drivertest/drivertest.go +++ b/blob/drivertest/drivertest.go @@ -71,16 +71,23 @@ type HarnessMaker func(ctx context.Context, t *testing.T) (Harness, error) // 2. Creates a blob in a directory, using BeforeWrite as a WriterOption. // 3. Fetches the blob's attributes and calls AttributeCheck. // 4. Creates a Reader for the blob using BeforeReader as a ReaderOption, -// and calls ReaderCheck with the resulting Reader. +// +// and calls ReaderCheck with the resulting Reader. +// // 5. Calls List using BeforeList as a ListOption, with Delimiter set so -// that only the directory is returned, and calls ListObjectCheck -// on the single directory list entry returned. +// +// that only the directory is returned, and calls ListObjectCheck +// on the single directory list entry returned. +// // 6. Calls List using BeforeList as a ListOption, and calls ListObjectCheck -// on the single blob entry returned. +// +// on the single blob entry returned. +// // 7. Tries to read a non-existent blob, and calls ErrorCheck with the error. // 8. Makes a copy of the blob, using BeforeCopy as a CopyOption. // 9. Calls SignedURL using BeforeSign as a SignedURLOption for each supported -// signing method (i.e. GET, PUT and DELETE). +// +// signing method (i.e. GET, PUT and DELETE). // // For example, an AsTest might set a driver-specific field to a custom // value in BeforeWrite, and then verify the custom value was returned in diff --git a/blob/fileblob/fileblob.go b/blob/fileblob/fileblob.go index 392ea27c7c..8587017c50 100644 --- a/blob/fileblob/fileblob.go +++ b/blob/fileblob/fileblob.go @@ -23,35 +23,35 @@ // In any case, absent any stored metadata many blob.Attributes fields // will be set to default values. // -// URLs +// # URLs // // For blob.OpenBucket, fileblob registers for the scheme "file". // To customize the URL opener, or for more details on the URL format, // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings; to make this work with services lacking // full UTF-8 support, strings must be escaped (during writes) and unescaped // (during reads). The following escapes are performed for fileblob: -// - Blob keys: ASCII characters 0-31 are escaped to "__0x__". -// If os.PathSeparator != "/", it is also escaped. -// Additionally, the "/" in "../", the trailing "/" in "//", and a trailing -// "/" is key names are escaped in the same way. -// On Windows, the characters "<>:"|?*" are also escaped. +// - Blob keys: ASCII characters 0-31 are escaped to "__0x__". +// If os.PathSeparator != "/", it is also escaped. +// Additionally, the "/" in "../", the trailing "/" in "//", and a trailing +// "/" is key names are escaped in the same way. +// On Windows, the characters "<>:"|?*" are also escaped. // -// As +// # As // // fileblob exposes the following types for As: -// - Bucket: os.FileInfo -// - Error: *os.PathError -// - ListObject: os.FileInfo -// - Reader: io.Reader -// - ReaderOptions.BeforeRead: *os.File -// - Attributes: os.FileInfo -// - CopyOptions.BeforeCopy: *os.File -// - WriterOptions.BeforeWrite: *os.File +// - Bucket: os.FileInfo +// - Error: *os.PathError +// - ListObject: os.FileInfo +// - Reader: io.Reader +// - ReaderOptions.BeforeRead: *os.File +// - Attributes: os.FileInfo +// - CopyOptions.BeforeCopy: *os.File +// - WriterOptions.BeforeWrite: *os.File package fileblob // import "gocloud.dev/blob/fileblob" import ( @@ -110,20 +110,20 @@ const Scheme = "file" // // If either of base_url / secret_key_path are provided, both must be. // -// - file:///a/directory -// -> Passes "/a/directory" to OpenBucket. -// - file://localhost/a/directory -// -> Also passes "/a/directory". -// - file://./../.. -// -> The hostname is ".", signaling a relative path; passes "../..". -// - file:///c:/foo/bar on Windows. -// -> Passes "c:\foo\bar". -// - file://localhost/c:/foo/bar on Windows. -// -> Also passes "c:\foo\bar". -// - file:///a/directory?base_url=/show&secret_key_path=secret.key -// -> Passes "/a/directory" to OpenBucket, and sets Options.URLSigner -// to a URLSignerHMAC initialized with base URL "/show" and secret key -// bytes read from the file "secret.key". +// - file:///a/directory +// -> Passes "/a/directory" to OpenBucket. +// - file://localhost/a/directory +// -> Also passes "/a/directory". +// - file://./../.. +// -> The hostname is ".", signaling a relative path; passes "../..". +// - file:///c:/foo/bar on Windows. +// -> Passes "c:\foo\bar". +// - file://localhost/c:/foo/bar on Windows. +// -> Also passes "c:\foo\bar". +// - file:///a/directory?base_url=/show&secret_key_path=secret.key +// -> Passes "/a/directory" to OpenBucket, and sets Options.URLSigner +// to a URLSignerHMAC initialized with base URL "/show" and secret key +// bytes read from the file "secret.key". type URLOpener struct { // Options specifies the default options to pass to OpenBucket. Options Options diff --git a/blob/gcsblob/gcsblob.go b/blob/gcsblob/gcsblob.go index 56ffbdc464..2b129cdc90 100644 --- a/blob/gcsblob/gcsblob.go +++ b/blob/gcsblob/gcsblob.go @@ -15,7 +15,7 @@ // Package gcsblob provides a blob implementation that uses GCS. Use OpenBucket // to construct a *blob.Bucket. // -// URLs +// # URLs // // For blob.OpenBucket, gcsblob registers for the scheme "gs". // The default URL opener will set up a connection using default credentials @@ -32,27 +32,27 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings; to make this work with services lacking // full UTF-8 support, strings must be escaped (during writes) and unescaped // (during reads). The following escapes are performed for gcsblob: -// - Blob keys: ASCII characters 10 and 13 are escaped to "__0x__". -// Additionally, the "/" in "../" is escaped in the same way. +// - Blob keys: ASCII characters 10 and 13 are escaped to "__0x__". +// Additionally, the "/" in "../" is escaped in the same way. // -// As +// # As // // gcsblob exposes the following types for As: -// - Bucket: *storage.Client -// - Error: *googleapi.Error -// - ListObject: storage.ObjectAttrs -// - ListOptions.BeforeList: *storage.Query -// - Reader: *storage.Reader -// - ReaderOptions.BeforeRead: **storage.ObjectHandle, *storage.Reader (if accessing both, must be in that order) -// - Attributes: storage.ObjectAttrs -// - CopyOptions.BeforeCopy: *CopyObjectHandles, *storage.Copier (if accessing both, must be in that order) -// - WriterOptions.BeforeWrite: **storage.ObjectHandle, *storage.Writer (if accessing both, must be in that order) -// - SignedURLOptions.BeforeSign: *storage.SignedURLOptions +// - Bucket: *storage.Client +// - Error: *googleapi.Error +// - ListObject: storage.ObjectAttrs +// - ListOptions.BeforeList: *storage.Query +// - Reader: *storage.Reader +// - ReaderOptions.BeforeRead: **storage.ObjectHandle, *storage.Reader (if accessing both, must be in that order) +// - Attributes: storage.ObjectAttrs +// - CopyOptions.BeforeCopy: *CopyObjectHandles, *storage.Copier (if accessing both, must be in that order) +// - WriterOptions.BeforeWrite: **storage.ObjectHandle, *storage.Writer (if accessing both, must be in that order) +// - SignedURLOptions.BeforeSign: *storage.SignedURLOptions package gcsblob // import "gocloud.dev/blob/gcsblob" import ( diff --git a/blob/memblob/memblob.go b/blob/memblob/memblob.go index 59a9c45607..f46ddcc4a5 100644 --- a/blob/memblob/memblob.go +++ b/blob/memblob/memblob.go @@ -15,14 +15,14 @@ // Package memblob provides an in-memory blob implementation. // Use OpenBucket to construct a *blob.Bucket. // -// URLs +// # URLs // // For blob.OpenBucket memblob registers for the scheme "mem". // To customize the URL opener, or for more details on the URL format, // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // memblob does not support any types for As. package memblob // import "gocloud.dev/blob/memblob" diff --git a/blob/s3blob/s3blob.go b/blob/s3blob/s3blob.go index 78281fd6e4..a8da69e5d8 100644 --- a/blob/s3blob/s3blob.go +++ b/blob/s3blob/s3blob.go @@ -15,7 +15,7 @@ // Package s3blob provides a blob implementation that uses S3. Use OpenBucket // to construct a *blob.Bucket. // -// URLs +// # URLs // // For blob.OpenBucket, s3blob registers for the scheme "s3". // The default URL opener will use an AWS session with the default credentials @@ -27,37 +27,37 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings; to make this work with services lacking // full UTF-8 support, strings must be escaped (during writes) and unescaped // (during reads). The following escapes are performed for s3blob: -// - Blob keys: ASCII characters 0-31 are escaped to "__0x__". -// Additionally, the "/" in "../" and the trailing "/" in "//" are escaped in -// the same way. -// - Metadata keys: Escaped using URL encoding, then additionally "@:=" are -// escaped using "__0x__". These characters were determined by -// experimentation. -// - Metadata values: Escaped using URL encoding. +// - Blob keys: ASCII characters 0-31 are escaped to "__0x__". +// Additionally, the "/" in "../" and the trailing "/" in "//" are escaped in +// the same way. +// - Metadata keys: Escaped using URL encoding, then additionally "@:=" are +// escaped using "__0x__". These characters were determined by +// experimentation. +// - Metadata values: Escaped using URL encoding. // -// As +// # As // // s3blob exposes the following types for As: -// - Bucket: (V1) *s3.S3; (V2) *s3v2.Client -// - Error: (V1) awserr.Error; (V2) any error type returned by the service, notably smithy.APIError -// - ListObject: (V1) s3.Object for objects, s3.CommonPrefix for "directories"; (V2) typesv2.Object for objects, typesv2.CommonPrefix for "directories -// - ListOptions.BeforeList: (V1) *s3.ListObjectsV2Input, or *s3.ListObjectsInput -// when Options.UseLegacyList == true; (V2) *s3v2.ListObjectsV2Input, or *s3v2.ListObjectsInput -// when Options.UseLegacyList == true -// - Reader: (V1) s3.GetObjectOutput; (V2) s3v2.GetObjectInput -// - ReaderOptions.BeforeRead: (V1) *s3.GetObjectInput; (V2) *s3v2.GetObjectInput -// - Attributes: (V1) s3.HeadObjectOutput; (V2)s3v2.HeadObjectOutput -// - CopyOptions.BeforeCopy: *(V1) s3.CopyObjectInput; (V2) s3v2.CopyObjectInput -// - WriterOptions.BeforeWrite: (V1) *s3manager.UploadInput, *s3manager.Uploader; (V2) *s3v2.PutObjectInput, *s3v2manager.Uploader -// - SignedURLOptions.BeforeSign: -// (V1) *s3.GetObjectInput; (V2) *s3v2.GetObjectInput, when Options.Method == http.MethodGet, or -// (V1) *s3.PutObjectInput; (V2) *s3v2.PutObjectInput, when Options.Method == http.MethodPut, or -// (V1) *s3.DeleteObjectInput; (V2) [not supported] when Options.Method == http.MethodDelete +// - Bucket: (V1) *s3.S3; (V2) *s3v2.Client +// - Error: (V1) awserr.Error; (V2) any error type returned by the service, notably smithy.APIError +// - ListObject: (V1) s3.Object for objects, s3.CommonPrefix for "directories"; (V2) typesv2.Object for objects, typesv2.CommonPrefix for "directories +// - ListOptions.BeforeList: (V1) *s3.ListObjectsV2Input, or *s3.ListObjectsInput +// when Options.UseLegacyList == true; (V2) *s3v2.ListObjectsV2Input, or *s3v2.ListObjectsInput +// when Options.UseLegacyList == true +// - Reader: (V1) s3.GetObjectOutput; (V2) s3v2.GetObjectInput +// - ReaderOptions.BeforeRead: (V1) *s3.GetObjectInput; (V2) *s3v2.GetObjectInput +// - Attributes: (V1) s3.HeadObjectOutput; (V2)s3v2.HeadObjectOutput +// - CopyOptions.BeforeCopy: *(V1) s3.CopyObjectInput; (V2) s3v2.CopyObjectInput +// - WriterOptions.BeforeWrite: (V1) *s3manager.UploadInput, *s3manager.Uploader; (V2) *s3v2.PutObjectInput, *s3v2manager.Uploader +// - SignedURLOptions.BeforeSign: +// (V1) *s3.GetObjectInput; (V2) *s3v2.GetObjectInput, when Options.Method == http.MethodGet, or +// (V1) *s3.PutObjectInput; (V2) *s3v2.PutObjectInput, when Options.Method == http.MethodPut, or +// (V1) *s3.DeleteObjectInput; (V2) [not supported] when Options.Method == http.MethodDelete package s3blob // import "gocloud.dev/blob/s3blob" import ( diff --git a/blob/s3blob/s3blob_test.go b/blob/s3blob/s3blob_test.go index d9ad510664..51e765f071 100644 --- a/blob/s3blob/s3blob_test.go +++ b/blob/s3blob/s3blob_test.go @@ -40,10 +40,13 @@ import ( // These constants record the region & bucket used for the last --record. // If you want to use --record mode, // 1. Create a bucket in your AWS project from the S3 management console. -// https://s3.console.aws.amazon.com/s3/home. +// +// https://s3.console.aws.amazon.com/s3/home. +// // 2. Update this constant to your bucket name. // TODO(issue #300): Use Terraform to provision a bucket, and get the bucket -// name from the Terraform output instead (saving a copy of it for replay). +// +// name from the Terraform output instead (saving a copy of it for replay). const ( bucketName = "go-cloud-testing" region = "us-west-1" diff --git a/doc.go b/doc.go index db99623648..b4a370fe79 100644 --- a/doc.go +++ b/doc.go @@ -36,11 +36,11 @@ increasing compile times or binary sizes, and avoiding any side effects from For non-reference documentation, see https://gocloud.dev/ -URLs +# URLs See https://gocloud.dev/concepts/urls/ for a discussion of URLs in the Go CDK. -As +# As See https://gocloud.dev/concepts/as/ for a discussion of how to write service-specific code with the Go CDK. diff --git a/docstore/awsdynamodb/dynamo.go b/docstore/awsdynamodb/dynamo.go index 04bf8d178d..6f71f15622 100644 --- a/docstore/awsdynamodb/dynamo.go +++ b/docstore/awsdynamodb/dynamo.go @@ -16,7 +16,7 @@ // DynamoDB. // Use OpenCollection to construct a *docstore.Collection. // -// URLs +// # URLs // // For docstore.OpenCollection, awsdynamodb registers for the scheme // "dynamodb". The default URL opener will use an AWS session with the default @@ -26,15 +26,15 @@ // URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // awsdynamodb exposes the following types for As: -// - Collection.As: *dynamodb.DynamoDB -// - ActionList.BeforeDo: *dynamodb.BatchGetItemInput or *dynamodb.PutItemInput or *dynamodb.DeleteItemInput -// or *dynamodb.UpdateItemInput -// - Query.BeforeQuery: *dynamodb.QueryInput or *dynamodb.ScanInput -// - DocumentIterator: *dynamodb.QueryOutput or *dynamodb.ScanOutput -// - ErrorAs: awserr.Error +// - Collection.As: *dynamodb.DynamoDB +// - ActionList.BeforeDo: *dynamodb.BatchGetItemInput or *dynamodb.PutItemInput or *dynamodb.DeleteItemInput +// or *dynamodb.UpdateItemInput +// - Query.BeforeQuery: *dynamodb.QueryInput or *dynamodb.ScanInput +// - DocumentIterator: *dynamodb.QueryOutput or *dynamodb.ScanOutput +// - ErrorAs: awserr.Error package awsdynamodb import ( diff --git a/docstore/doc.go b/docstore/doc.go index 469ce2d808..9082b4993f 100644 --- a/docstore/doc.go +++ b/docstore/doc.go @@ -18,16 +18,14 @@ // // See https://gocloud.dev/howto/docstore/ for a detailed how-to guide. // -// -// Collections +// # Collections // // In docstore, documents are grouped into collections, and each document has a key // that is unique in its collection. You can add, retrieve, modify and delete // documents by key, and you can query a collection to retrieve documents that match // certain criteria. // -// -// Representing Documents +// # Representing Documents // // A document is a set of named fields, each with a value. A field's value can be a scalar, // a list, or a nested document. @@ -37,38 +35,38 @@ // and the values are map values. Lists are represented with slices. For example, // here is a document about a book described as a map: // -// doc := map[string]interface{}{ -// "Title": "The Master and Margarita", -// "Author": map[string]interface{}{ -// "First": "Mikhail", -// "Last": "Bulgakov", -// }, -// "PublicationYears": []int{1967, 1973}, -// } +// doc := map[string]interface{}{ +// "Title": "The Master and Margarita", +// "Author": map[string]interface{}{ +// "First": "Mikhail", +// "Last": "Bulgakov", +// }, +// "PublicationYears": []int{1967, 1973}, +// } // // Note that the value of "PublicationYears" is a list, and the value of "Author" is // itself a document. // // Here is the same document represented with structs: // -// type Book struct { -// Title string -// Author Name -// PublicationYears []int -// } -// -// type Name struct { -// First, Last string -// } -// -// doc := &Book{ -// Title: "The Master and Margarita", -// Author: Name{ -// First: "Mikhail", -// Last: "Bulgakov", -// }, -// PublicationYears: []int{1967, 1973}, -// } +// type Book struct { +// Title string +// Author Name +// PublicationYears []int +// } +// +// type Name struct { +// First, Last string +// } +// +// doc := &Book{ +// Title: "The Master and Margarita", +// Author: Name{ +// First: "Mikhail", +// Last: "Bulgakov", +// }, +// PublicationYears: []int{1967, 1973}, +// } // // You must use a pointer to a struct to represent a document, although structs // nested inside a document, like the Name struct above, need not be pointers. @@ -84,12 +82,12 @@ // encoding/json. For example, this is the Book struct with different field // names: // -// type Book struct { -// Title string `docstore:"title"` -// Author Name `docstore:"author"` -// PublicationYears []int `docstore:"pub_years,omitempty"` -// NumPublications int `docstore:"-"` -// } +// type Book struct { +// Title string `docstore:"title"` +// Author Name `docstore:"author"` +// PublicationYears []int `docstore:"pub_years,omitempty"` +// NumPublications int `docstore:"-"` +// } // // This struct describes a document with field names "title", "author" and // "pub_years". The pub_years field is omitted from the stored document if it has @@ -105,8 +103,7 @@ // Note that unlike encoding/json, Docstore does case-sensitive matching during // decoding to match the behavior of decoders in most docstore services. // -// -// Representing Data +// # Representing Data // // Values stored in document fields can be any of a wide range of types. All // primitive types except for complex numbers are supported, as well as slices and @@ -124,8 +121,7 @@ // time in nanoseconds using time's UnixNano method, you can get the original // time back (in the local timezone) with the time.Unix function. // -// -// Representing Keys +// # Representing Keys // // The key of a docstore document is its unique identifier, usually a field. // Keys never appear alone in the docstore API, only as part of a document. For @@ -139,14 +135,13 @@ // document. // Usually, you provide the name of the key field, as in the example below: // -// coll, err := memdocstore.OpenCollection("SSN", nil) +// coll, err := memdocstore.OpenCollection("SSN", nil) // // Here, the "SSN" field of the document is used as the key. Some drivers let you // supply a function to extract the key from the document, which can be useful if the // key is composed of more than one field. // -// -// Actions +// # Actions // // Docstore supports six actions on documents as methods on the Collection type: // - Get retrieves a document. @@ -159,7 +154,7 @@ // Each action acts atomically on a single document. You can execute actions // individually or you can group them into an action list, like so: // -// err := coll.Actions().Put(doc1).Replace(doc2).Get(doc3).Do(ctx) +// err := coll.Actions().Put(doc1).Replace(doc2).Get(doc3).Do(ctx) // // When you use an action list, docstore will try to optimize the execution of the // actions. For example, multiple Get actions may be combined into a single "batch @@ -168,8 +163,7 @@ // document are executed in the user-specified order. See the documentation of // ActionList for details. // -// -// Revisions +// # Revisions // // Docstore supports document revisions to distinguish different versions of a // document and enable optimistic locking. By default, Docstore stores the @@ -197,27 +191,26 @@ // of unspecified type must be handled. When defining a document struct, // define the field to be of type interface{}. For example, // -// type User { -// Name string -// DocstoreRevision interface{} -// } +// type User { +// Name string +// DocstoreRevision interface{} +// } // -// -// Queries +// # Queries // // Docstore supports querying within a collection. Call the Query method on // Collection to obtain a Query value, then build your query by calling Query methods // like Where, Limit and so on. Finally, call the Get method on the query to execute it. // The result is an iterator, whose use is described below. // -// iter := coll.Query().Where("size", ">", 10).Limit(5).Get(ctx) +// iter := coll.Query().Where("size", ">", 10).Limit(5).Get(ctx) // // The Where method defines a filter condition, much like a WHERE clause in SQL. // Conditions are of the form "field op value", where field is any document field // path (including dot-separated paths), op is one of "=", ">", "<", ">=" or "<=", // and value can be any value. // -// iter := coll.Query().Where("Author.Last", "=", "Bulgakov").Limit(3).Get(ctx) +// iter := coll.Query().Where("Author.Last", "=", "Bulgakov").Limit(3).Get(ctx) // // You can make multiple Where calls. In some cases, parts of a Where clause may be // processed in the driver rather than natively by the backing service, which may have @@ -228,22 +221,21 @@ // method until it returns io.EOF. Always call Stop when you are finished with an // iterator. It is wise to use a defer statement for this. // -// iter := coll.Query().Where("size", ">", 10).Limit(5).Get(ctx) -// defer iter.Stop() -// for { -// m := map[string]interface{}{} -// err := iter.Next(ctx, m) -// if err == io.EOF { -// break -// } -// if err != nil { -// return err -// } -// fmt.Println(m) -// } -// -// -// Errors +// iter := coll.Query().Where("size", ">", 10).Limit(5).Get(ctx) +// defer iter.Stop() +// for { +// m := map[string]interface{}{} +// err := iter.Next(ctx, m) +// if err == io.EOF { +// break +// } +// if err != nil { +// return err +// } +// fmt.Println(m) +// } +// +// # Errors // // The errors returned from this package can be inspected in several ways: // @@ -254,15 +246,15 @@ // the returned error. See the specific driver's package doc for the supported // types. // -// -// OpenCensus Integration +// # OpenCensus Integration // // OpenCensus supports tracing and metric collection for multiple languages and // backend providers. See https://opencensus.io. // // This API collects OpenCensus traces and metrics for the following methods: -// - ActionList.Do -// - Query.Get (for the first query only; drivers may make additional calls while iterating over results) +// - ActionList.Do +// - Query.Get (for the first query only; drivers may make additional calls while iterating over results) +// // All trace and metric names begin with the package import path. // The traces add the method name. // For example, "gocloud.dev/docstore/ActionList.Do". diff --git a/docstore/docstore.go b/docstore/docstore.go index 25c83c7fc3..388d46ea8a 100644 --- a/docstore/docstore.go +++ b/docstore/docstore.go @@ -104,9 +104,10 @@ func (c *Collection) revisionField() string { } // A FieldPath is a dot-separated sequence of UTF-8 field names. Examples: -// room -// room.size -// room.size.width +// +// room +// room.size +// room.size.width // // A FieldPath can be used select top-level fields or elements of sub-documents. // There is no way to select a single list element. @@ -259,16 +260,17 @@ func (l *ActionList) Update(doc Document, mods Mods) *ActionList { // Mods is a map from field paths to modifications. // At present, a modification is one of: -// - nil, to delete the field -// - an Increment value, to add a number to the field -// - any other value, to set the field to that value +// - nil, to delete the field +// - an Increment value, to add a number to the field +// - any other value, to set the field to that value +// // See ActionList.Update. type Mods map[FieldPath]interface{} // Increment returns a modification that results in a field being incremented. It // should only be used as a value in a Mods map, like so: // -// docstore.Mods{"count": docstore.Increment(1)} +// docstore.Mods{"count": docstore.Increment(1)} // // The amount must be an integer or floating-point value. func Increment(amount interface{}) interface{} { diff --git a/docstore/gcpfirestore/fs.go b/docstore/gcpfirestore/fs.go index 8df0fadd2f..6e3e84c391 100644 --- a/docstore/gcpfirestore/fs.go +++ b/docstore/gcpfirestore/fs.go @@ -17,14 +17,13 @@ // Use OpenCollection to construct a *docstore.Collection. // // Docstore types not supported by the Go firestore client, cloud.google.com/go/firestore: -// - unsigned integers: encoded is int64s -// - arrays: encoded as Firestore array values +// - unsigned integers: encoded is int64s +// - arrays: encoded as Firestore array values // // Firestore types not supported by Docstore: -// - Document reference (a pointer to another Firestore document) +// - Document reference (a pointer to another Firestore document) // -// -// URLs +// # URLs // // For docstore.OpenCollection, gcpfirestore registers for the scheme // "firestore". @@ -35,20 +34,18 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// -// As +// # As // // gcpfirestore exposes the following types for as functions. // The pb package is google.golang.org/genproto/googleapis/firestore/v1. // The firestore package is cloud.google.com/go/firestore/apiv1. -// - Collection.As: *firestore.Client -// - ActionList.BeforeDo: *pb.BatchGetDocumentsRequest or *pb.CommitRequest. -// - Query.BeforeQuery: *pb.RunQueryRequest -// - DocumentIterator: firestore.Firestore_RunQueryClient -// - Error: *google.golang.org/grpc/status.Status -// +// - Collection.As: *firestore.Client +// - ActionList.BeforeDo: *pb.BatchGetDocumentsRequest or *pb.CommitRequest. +// - Query.BeforeQuery: *pb.RunQueryRequest +// - DocumentIterator: firestore.Firestore_RunQueryClient +// - Error: *google.golang.org/grpc/status.Status // -// Queries +// # Queries // // Firestore allows only one field in a query to be compared with an inequality // operator (one other than "="). This driver selects the first field in a Where diff --git a/docstore/gcpfirestore/urls.go b/docstore/gcpfirestore/urls.go index f511663988..9e2a585232 100644 --- a/docstore/gcpfirestore/urls.go +++ b/docstore/gcpfirestore/urls.go @@ -75,6 +75,7 @@ const Scheme = "firestore" // The following query parameters are supported: // // - name_field (required): gcpfirestore requires that a single string field, +// // name_field, be designated the primary key. Its values must be unique over all // documents in the collection, and the primary key must be provided to retrieve // a document. diff --git a/docstore/internal/fields/fields.go b/docstore/internal/fields/fields.go index d8dad7db5f..7e6c196f90 100644 --- a/docstore/internal/fields/fields.go +++ b/docstore/internal/fields/fields.go @@ -15,11 +15,11 @@ // Package fields provides a view of the fields of a struct that follows the Go // rules, amended to consider tags and case insensitivity. // -// Usage +// # Usage // // First define a function that interprets tags: // -// func parseTag(st reflect.StructTag) (name string, keep bool, other interface{}, err error) { ... } +// func parseTag(st reflect.StructTag) (name string, keep bool, other interface{}, err error) { ... } // // The function's return values describe whether to ignore the field // completely or provide an alternate name, as well as other data from the @@ -27,29 +27,29 @@ // // Then define a function to validate the type: // -// func validate(t reflect.Type) error { ... } +// func validate(t reflect.Type) error { ... } // // Then, if necessary, define a function to specify leaf types - types // which should be considered one field and not be recursed into: // -// func isLeafType(t reflect.Type) bool { ... } +// func isLeafType(t reflect.Type) bool { ... } // // eg: // -// func isLeafType(t reflect.Type) bool { -// return t == reflect.TypeOf(time.Time{}) -// } +// func isLeafType(t reflect.Type) bool { +// return t == reflect.TypeOf(time.Time{}) +// } // // Next, construct a Cache, passing your functions. As its name suggests, a // Cache remembers validation and field information for a type, so subsequent // calls with the same type are very fast. // -// cache := fields.NewCache(parseTag, validate, isLeafType) +// cache := fields.NewCache(parseTag, validate, isLeafType) // // To get the fields of a struct type as determined by the above rules, call // the Fields method: // -// fields, err := cache.Fields(reflect.TypeOf(MyStruct{})) +// fields, err := cache.Fields(reflect.TypeOf(MyStruct{})) // // The return value can be treated as a slice of Fields. // @@ -57,7 +57,7 @@ // call Match on the list of fields to find a field whose name is the best // match: // -// field := fields.Match(name) +// field := fields.Match(name) // // Match looks for an exact match first, then falls back to a case-insensitive // comparison. @@ -474,10 +474,12 @@ func dominantField(fs []Field) (Field, bool) { // ParseStandardTag extracts the sub-tag named by key, then parses it using the // de facto standard format introduced in encoding/json: -// "-" means "ignore this tag", unless it has options (that is, is followed by a comma), -// in which case it is treated a name. -// "" provides an alternative name for the field -// ",opt1,opt2,..." specifies options after the name. +// +// "-" means "ignore this tag", unless it has options (that is, is followed by a comma), +// in which case it is treated a name. +// "" provides an alternative name for the field +// ",opt1,opt2,..." specifies options after the name. +// // The options are returned as a []string. func ParseStandardTag(key string, t reflect.StructTag) (name string, keep bool, options []string) { s := t.Get(key) diff --git a/docstore/internal/fields/fold.go b/docstore/internal/fields/fold.go index a72fd24011..d9b6d01f28 100644 --- a/docstore/internal/fields/fold.go +++ b/docstore/internal/fields/fold.go @@ -37,8 +37,9 @@ const ( // 4) simpleLetterEqualFold, no specials, no non-letters. // // The letters S and K are special because they map to 3 runes, not just 2: -// * S maps to s and to U+017F 'ſ' Latin small letter long s -// * k maps to K and to U+212A 'K' Kelvin sign +// - S maps to s and to U+017F 'ſ' Latin small letter long s +// - k maps to K and to U+212A 'K' Kelvin sign +// // See https://play.golang.org/p/tTxjOc0OGo // // The returned function is specialized for matching against s and diff --git a/docstore/memdocstore/mem.go b/docstore/memdocstore/mem.go index 14f0a99438..a5470261b6 100644 --- a/docstore/memdocstore/mem.go +++ b/docstore/memdocstore/mem.go @@ -18,8 +18,7 @@ // Every document in a memdocstore collection has a unique primary key. The primary // key values need not be strings; they may be any comparable Go value. // -// -// Action Lists +// # Action Lists // // Action lists are executed concurrently. Each action in an action list is executed // in a separate goroutine. @@ -27,8 +26,7 @@ // memdocstore calls the BeforeDo function of an ActionList once before executing the // actions. Its As function never returns true. // -// -// URLs +// # URLs // // For docstore.OpenCollection, memdocstore registers for the scheme // "mem". diff --git a/docstore/memdocstore/urls.go b/docstore/memdocstore/urls.go index 0fc982fa49..599abfbd5d 100644 --- a/docstore/memdocstore/urls.go +++ b/docstore/memdocstore/urls.go @@ -39,8 +39,8 @@ const Scheme = "mem" // // The following query parameters are supported: // -// - revision_field (optional): the name of the revision field. -// - filename (optional): the filename to store the collection in. +// - revision_field (optional): the name of the revision field. +// - filename (optional): the filename to store the collection in. type URLOpener struct { mu sync.Mutex collections map[string]urlColl diff --git a/docstore/mongodocstore/mongo.go b/docstore/mongodocstore/mongo.go index f142a5fe5c..0dacc4467e 100644 --- a/docstore/mongodocstore/mongo.go +++ b/docstore/mongodocstore/mongo.go @@ -16,8 +16,7 @@ // and MongoDB-compatible services hosted on-premise or by cloud providers, // including Amazon DocumentDB and Azure Cosmos DB. // -// -// URLs +// # URLs // // For docstore.OpenCollection, mongodocstore registers for the scheme "mongo". // The default URL opener will dial a Mongo server using the environment @@ -26,26 +25,24 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// -// Action Lists +// # Action Lists // // mongodocstore uses the unordered BulkWrite call of the underlying driver for writes, and uses Find with a list of document IDs for Get. // (These implementation choices are subject to change.) // It calls the BeforeDo function once before each call to the underlying driver. The as function passed // to the BeforeDo function exposes the following types: -// - Gets: *options.FindOptions -// - writes: []mongo.WriteModel and *options.BulkWriteOptions +// - Gets: *options.FindOptions +// - writes: []mongo.WriteModel and *options.BulkWriteOptions // -// As +// # As // // mongodocstore exposes the following types for As: -// - Collection: *mongo.Collection -// - Query.BeforeQuery: *options.FindOptions or bson.D (the filter for Delete and Update queries) -// - DocumentIterator: *mongo.Cursor -// - Error: mongo.CommandError, mongo.BulkWriteError, mongo.BulkWriteException -// +// - Collection: *mongo.Collection +// - Query.BeforeQuery: *options.FindOptions or bson.D (the filter for Delete and Update queries) +// - DocumentIterator: *mongo.Cursor +// - Error: mongo.CommandError, mongo.BulkWriteError, mongo.BulkWriteException // -// Special Considerations +// # Special Considerations // // MongoDB represents times to millisecond precision, while Go's time.Time type has // nanosecond precision. To save time.Times to MongoDB without loss of precision, diff --git a/docstore/mongodocstore/query.go b/docstore/mongodocstore/query.go index 83f0099984..d37ea2f814 100644 --- a/docstore/mongodocstore/query.go +++ b/docstore/mongodocstore/query.go @@ -94,7 +94,9 @@ func (c *collection) filtersToBSON(fs []driver.Filter) (bson.D, error) { // filterToBSON converts a driver.Filter to the MongoDB equivalent, expressed // as a bson.E (key-value pair). // The MongoDB document corresponding to "field op value" is -// {field: {mop: value}} +// +// {field: {mop: value}} +// // where mop is the mongo version of op (see the mongoQueryOps map above). func (c *collection) filterToBSON(f driver.Filter) (bson.E, error) { key := c.toMongoFieldPath(f.FieldPath) diff --git a/internal/openurl/openurl_test.go b/internal/openurl/openurl_test.go index 3ac418d91f..306ce3013f 100644 --- a/internal/openurl/openurl_test.go +++ b/internal/openurl/openurl_test.go @@ -4,7 +4,7 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// https://www.apache.org/licenses/LICENSE-2.0 +// https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, diff --git a/internal/releasehelper/releasehelper.go b/internal/releasehelper/releasehelper.go index f79bee32f6..dc0963d807 100644 --- a/internal/releasehelper/releasehelper.go +++ b/internal/releasehelper/releasehelper.go @@ -127,10 +127,10 @@ func parseModuleInfo(path string) GoMod { // Each require in the go.mod file is processed with reqHandler, a callback // function. It's called with these arguments: // -// gomodPath - path to the go.mod file where this 'require' was found -// mod - name of the module being 'require'd -// modPath - mod's location in the filesystem relative to -// the go.mod 'require'ing it +// gomodPath - path to the go.mod file where this 'require' was found +// mod - name of the module being 'require'd +// modPath - mod's location in the filesystem relative to +// the go.mod 'require'ing it func runOnGomod(path string, reqHandler func(gomodPath, mod, modPath string)) { gomodPath := filepath.Join(path, "go.mod") fmt.Println("Processing", gomodPath) diff --git a/internal/releasehelper/releasehelper_test.go b/internal/releasehelper/releasehelper_test.go index baf4a21494..a2bb5c6b88 100644 --- a/internal/releasehelper/releasehelper_test.go +++ b/internal/releasehelper/releasehelper_test.go @@ -29,7 +29,8 @@ import ( // ROOT/go.mod <-- main go.mod for gocloud.dev // ROOT/submod/go.mod <-- go.mod for a submodule of gocloud.dev // ROOT/samples/go.mod <-- go.mod for "samples" that include both of the -// other modules +// +// other modules var mainGomod = []byte("module gocloud.dev\n") var submodGomod = []byte(`module gocloud.dev/submod diff --git a/internal/testing/test-summary/test-summary.go b/internal/testing/test-summary/test-summary.go index 161ac9e746..3faff60442 100644 --- a/internal/testing/test-summary/test-summary.go +++ b/internal/testing/test-summary/test-summary.go @@ -14,7 +14,8 @@ // Summarizes the output of go test. // Run like so: -// go test -json ./... | test-summary +// +// go test -json ./... | test-summary package main import ( diff --git a/mysql/awsmysql/awsmysql.go b/mysql/awsmysql/awsmysql.go index d38920d560..e768d630f6 100644 --- a/mysql/awsmysql/awsmysql.go +++ b/mysql/awsmysql/awsmysql.go @@ -14,7 +14,7 @@ // Package awsmysql provides connections to AWS RDS MySQL instances. // -// URLs +// # URLs // // For mysql.Open, awsmysql registers for the scheme "awsmysql". // The default URL opener will create a connection using the default diff --git a/mysql/azuremysql/azuremysql.go b/mysql/azuremysql/azuremysql.go index dfd97acacc..f731679389 100644 --- a/mysql/azuremysql/azuremysql.go +++ b/mysql/azuremysql/azuremysql.go @@ -15,7 +15,7 @@ // Package azuremysql provides connections to Azure Database for MySQL. // See https://docs.microsoft.com/en-us/azure/mysql. // -// URLs +// # URLs // // For mysql.Open, azuremysql registers for the scheme "azuremysql". // To customize the URL opener, or for more details on the URL format, diff --git a/mysql/gcpmysql/gcpmysql.go b/mysql/gcpmysql/gcpmysql.go index 8dd5ff528f..89baf46952 100644 --- a/mysql/gcpmysql/gcpmysql.go +++ b/mysql/gcpmysql/gcpmysql.go @@ -15,7 +15,7 @@ // Package gcpmysql provides connections to managed MySQL Cloud SQL instances. // See https://cloud.google.com/sql/docs/mysql/ for more information. // -// URLs +// # URLs // // For mysql.Open, gcpmysql registers for the scheme "gcpmysql". // The default URL opener will create a connection using the default diff --git a/postgres/awspostgres/awspostgres.go b/postgres/awspostgres/awspostgres.go index 859aa46f63..db1df87bd5 100644 --- a/postgres/awspostgres/awspostgres.go +++ b/postgres/awspostgres/awspostgres.go @@ -14,7 +14,7 @@ // Package awspostgres provides connections to AWS RDS PostgreSQL instances. // -// URLs +// # URLs // // For postgres.Open, awspostgres registers for the scheme "awspostgres". // The default URL opener will create a connection using the default diff --git a/postgres/gcppostgres/gcppostgres.go b/postgres/gcppostgres/gcppostgres.go index cd9b2d5587..0b6b6cb8d9 100644 --- a/postgres/gcppostgres/gcppostgres.go +++ b/postgres/gcppostgres/gcppostgres.go @@ -15,7 +15,7 @@ // Package gcppostgres provides connections to managed PostgreSQL Cloud SQL instances. // See https://cloud.google.com/sql/docs/postgres/ for more information. // -// URLs +// # URLs // // For postgres.Open, gcppostgres registers for the scheme "gcppostgres". // The default URL opener will create a connection using the default diff --git a/pubsub/acks_test.go b/pubsub/acks_test.go index f17896582e..c7ed525bd5 100644 --- a/pubsub/acks_test.go +++ b/pubsub/acks_test.go @@ -4,7 +4,7 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// https://www.apache.org/licenses/LICENSE-2.0 +// https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, diff --git a/pubsub/awssnssqs/awssnssqs.go b/pubsub/awssnssqs/awssnssqs.go index feb709aa5e..a81fb61001 100644 --- a/pubsub/awssnssqs/awssnssqs.go +++ b/pubsub/awssnssqs/awssnssqs.go @@ -17,7 +17,7 @@ // messages to SQS (Simple Queuing Service). It also provides an implementation // of pubsub.Subscription that receives messages from SQS. // -// URLs +// # URLs // // For pubsub.OpenTopic, awssnssqs registers for the scheme "awssns" for // an SNS topic, and "awssqs" for an SQS topic. For pubsub.OpenSubscription, @@ -30,37 +30,37 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Message Delivery Semantics +// # Message Delivery Semantics // // AWS SQS supports at-least-once semantics; applications must call Message.Ack // after processing a message, or it will be redelivered. // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings; to make this work with services lacking // full UTF-8 support, strings must be escaped (during writes) and unescaped // (during reads). The following escapes are required for awssnssqs: -// - Metadata keys: Characters other than "a-zA-z0-9_-.", and additionally "." -// when it's at the start of the key or the previous character was ".", -// are escaped using "__0x__". These characters were determined by -// experimentation. -// - Metadata values: Escaped using URL encoding. -// - Message body: AWS SNS/SQS only supports UTF-8 strings. See the -// BodyBase64Encoding enum in TopicOptions for strategies on how to send -// non-UTF-8 message bodies. By default, non-UTF-8 message bodies are base64 -// encoded. +// - Metadata keys: Characters other than "a-zA-z0-9_-.", and additionally "." +// when it's at the start of the key or the previous character was ".", +// are escaped using "__0x__". These characters were determined by +// experimentation. +// - Metadata values: Escaped using URL encoding. +// - Message body: AWS SNS/SQS only supports UTF-8 strings. See the +// BodyBase64Encoding enum in TopicOptions for strategies on how to send +// non-UTF-8 message bodies. By default, non-UTF-8 message bodies are base64 +// encoded. // -// As +// # As // // awssnssqs exposes the following types for As: -// - Topic: (V1) *sns.SNS for OpenSNSTopic, *sqs.SQS for OpenSQSTopic; (V2) *snsv2.Client for OpenSNSTopicV2, *sqsv2.Client for OpenSQSTopicV2 -// - Subscription: (V1) *sqs.SQS; (V2) *sqsv2.Client -// - Message: (V1) *sqs.Message; (V2) sqstypesv2.Message -// - Message.BeforeSend: (V1) *sns.PublishInput for OpenSNSTopic, *sqs.SendMessageBatchRequestEntry or *sqs.SendMessageInput(deprecated) for OpenSQSTopic; (V2) *snsv2.PublishInput for OpenSNSTopicV2, sqstypesv2.SendMessageBatchRequestEntry for OpenSQSTopicV2 -// - Message.AfterSend: (V1) *sns.PublishOutput for OpenSNSTopic, *sqs.SendMessageBatchResultEntry for OpenSQSTopic; (V2) *snsv2.PublishOutput for OpenSNSTopicV2, sqstypesv2.SendMessageBatchResultEntry for OpenSQSTopicV2 -// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError +// - Topic: (V1) *sns.SNS for OpenSNSTopic, *sqs.SQS for OpenSQSTopic; (V2) *snsv2.Client for OpenSNSTopicV2, *sqsv2.Client for OpenSQSTopicV2 +// - Subscription: (V1) *sqs.SQS; (V2) *sqsv2.Client +// - Message: (V1) *sqs.Message; (V2) sqstypesv2.Message +// - Message.BeforeSend: (V1) *sns.PublishInput for OpenSNSTopic, *sqs.SendMessageBatchRequestEntry or *sqs.SendMessageInput(deprecated) for OpenSQSTopic; (V2) *snsv2.PublishInput for OpenSNSTopicV2, sqstypesv2.SendMessageBatchRequestEntry for OpenSQSTopicV2 +// - Message.AfterSend: (V1) *sns.PublishOutput for OpenSNSTopic, *sqs.SendMessageBatchResultEntry for OpenSQSTopic; (V2) *snsv2.PublishOutput for OpenSNSTopicV2, sqstypesv2.SendMessageBatchResultEntry for OpenSQSTopicV2 +// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError package awssnssqs // import "gocloud.dev/pubsub/awssnssqs" import ( diff --git a/pubsub/azuresb/azuresb.go b/pubsub/azuresb/azuresb.go index 4ea38c4459..ebb058504d 100644 --- a/pubsub/azuresb/azuresb.go +++ b/pubsub/azuresb/azuresb.go @@ -16,7 +16,7 @@ // Bus Topic and Subscription. // See https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview for an overview. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, azuresb registers // for the scheme "azuresb". @@ -26,7 +26,7 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Message Delivery Semantics +// # Message Delivery Semantics // // Azure ServiceBus supports at-least-once semantics in the default Peek-Lock // mode; messages will be redelivered if they are not Acked, or if they are @@ -42,15 +42,15 @@ // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// As +// # As // // azuresb exposes the following types for As: -// - Topic: *servicebus.Topic -// - Subscription: *servicebus.Subscription -// - Message.BeforeSend: *servicebus.Message -// - Message.AfterSend: None -// - Message: *servicebus.Message -// - Error: common.Retryable, *amqp.Error, *amqp.DetachError +// - Topic: *servicebus.Topic +// - Subscription: *servicebus.Subscription +// - Message.BeforeSend: *servicebus.Message +// - Message.AfterSend: None +// - Message: *servicebus.Message +// - Error: common.Retryable, *amqp.Error, *amqp.DetachError package azuresb // import "gocloud.dev/pubsub/azuresb" import ( diff --git a/pubsub/azuresb/azuresb_test.go b/pubsub/azuresb/azuresb_test.go index dd7b5a0ac5..674266f0b9 100644 --- a/pubsub/azuresb/azuresb_test.go +++ b/pubsub/azuresb/azuresb_test.go @@ -4,7 +4,7 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// https://www.apache.org/licenses/LICENSE-2.0 +// https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, diff --git a/pubsub/drivertest/drivertest.go b/pubsub/drivertest/drivertest.go index f60d5861ac..355816cdcf 100644 --- a/pubsub/drivertest/drivertest.go +++ b/pubsub/drivertest/drivertest.go @@ -80,7 +80,9 @@ type HarnessMaker func(ctx context.Context, t *testing.T) (Harness, error) // 1. Calls TopicCheck. // 2. Calls SubscriptionCheck. // 3. Sends a message, setting Message.BeforeSend to BeforeSend -// and Message.AfterSend to AfterSend. +// +// and Message.AfterSend to AfterSend. +// // 4. Receives the message and calls MessageCheck. // 5. Calls TopicErrorCheck. // 6. Calls SubscriptionErrorCheck. diff --git a/pubsub/gcppubsub/gcppubsub.go b/pubsub/gcppubsub/gcppubsub.go index 1061e5660e..3e81d1019d 100644 --- a/pubsub/gcppubsub/gcppubsub.go +++ b/pubsub/gcppubsub/gcppubsub.go @@ -16,7 +16,7 @@ // PubSub. Use OpenTopic to construct a *pubsub.Topic, and/or OpenSubscription // to construct a *pubsub.Subscription. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, gcppubsub registers // for the scheme "gcppubsub". @@ -31,22 +31,22 @@ // So, when environment variable 'PUBSUB_EMULATOR_HOST' is set // driver connects to the specified emulator host by default. // -// Message Delivery Semantics +// # Message Delivery Semantics // // GCP Pub/Sub supports at-least-once semantics; applications must // call Message.Ack after processing a message, or it will be redelivered. // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// As +// # As // // gcppubsub exposes the following types for As: -// - Topic: *raw.PublisherClient -// - Subscription: *raw.SubscriberClient -// - Message.BeforeSend: *pb.PubsubMessage -// - Message.AfterSend: *string for the pb.PublishResponse.MessageIds entry corresponding to the message. -// - Message: *pb.PubsubMessage, *pb.ReceivedMessage -// - Error: *google.golang.org/grpc/status.Status +// - Topic: *raw.PublisherClient +// - Subscription: *raw.SubscriberClient +// - Message.BeforeSend: *pb.PubsubMessage +// - Message.AfterSend: *string for the pb.PublishResponse.MessageIds entry corresponding to the message. +// - Message: *pb.PubsubMessage, *pb.ReceivedMessage +// - Error: *google.golang.org/grpc/status.Status package gcppubsub // import "gocloud.dev/pubsub/gcppubsub" import ( diff --git a/pubsub/kafkapubsub/kafka.go b/pubsub/kafkapubsub/kafka.go index f8bb1f5ef8..e1fcfe61d9 100644 --- a/pubsub/kafkapubsub/kafka.go +++ b/pubsub/kafkapubsub/kafka.go @@ -23,7 +23,7 @@ // kafkapubsub does not support Message.Nack; Message.Nackable will return // false, and Message.Nack will panic if called. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, kafkapubsub registers // for the scheme "kafka". @@ -34,22 +34,22 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Escaping +// # Escaping // // Go CDK supports all UTF-8 strings. No escaping is required for Kafka. // Message metadata is supported through Kafka Headers, which allow arbitrary // []byte for both key and value. These are converted to string for use in // Message.Metadata. // -// As +// # As // // kafkapubsub exposes the following types for As: -// - Topic: sarama.SyncProducer -// - Subscription: sarama.ConsumerGroup, sarama.ConsumerGroupSession (may be nil during session renegotiation, and session may go stale at any time) -// - Message: *sarama.ConsumerMessage -// - Message.BeforeSend: *sarama.ProducerMessage -// - Message.AfterSend: None -// - Error: sarama.ConsumerError, sarama.ConsumerErrors, sarama.ProducerError, sarama.ProducerErrors, sarama.ConfigurationError, sarama.PacketDecodingError, sarama.PacketEncodingError, sarama.KError +// - Topic: sarama.SyncProducer +// - Subscription: sarama.ConsumerGroup, sarama.ConsumerGroupSession (may be nil during session renegotiation, and session may go stale at any time) +// - Message: *sarama.ConsumerMessage +// - Message.BeforeSend: *sarama.ProducerMessage +// - Message.AfterSend: None +// - Error: sarama.ConsumerError, sarama.ConsumerErrors, sarama.ProducerError, sarama.ProducerErrors, sarama.ConfigurationError, sarama.PacketDecodingError, sarama.PacketEncodingError, sarama.KError package kafkapubsub // import "gocloud.dev/pubsub/kafkapubsub" import ( diff --git a/pubsub/mempubsub/mem.go b/pubsub/mempubsub/mem.go index 7b44f45806..9262c63fa0 100644 --- a/pubsub/mempubsub/mem.go +++ b/pubsub/mempubsub/mem.go @@ -19,7 +19,7 @@ // mempubsub should not be used for production: it is intended for local // development and testing. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, mempubsub registers // for the scheme "mem". @@ -27,14 +27,14 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Message Delivery Semantics +// # Message Delivery Semantics // // mempubsub supports at-least-once semantics; applications must // call Message.Ack after processing a message, or it will be redelivered. // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// As +// # As // // mempubsub does not support any types for As. package mempubsub // import "gocloud.dev/pubsub/mempubsub" @@ -69,7 +69,7 @@ const Scheme = "mem" // // Query parameters: // - ackdeadline: The ack deadline for OpenSubscription, in time.ParseDuration formats. -// Defaults to 1m. +// Defaults to 1m. type URLOpener struct { mu sync.Mutex topics map[string]*pubsub.Topic diff --git a/pubsub/natspubsub/nats.go b/pubsub/natspubsub/nats.go index de8f6f3970..ec09c5f865 100644 --- a/pubsub/natspubsub/nats.go +++ b/pubsub/natspubsub/nats.go @@ -17,7 +17,7 @@ // *pubsub.Subscription. This package uses gob to encode and decode driver.Message to // []byte. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, natspubsub registers // for the scheme "nats". @@ -27,21 +27,21 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Message Delivery Semantics +// # Message Delivery Semantics // // NATS supports at-most-semantics; applications need not call Message.Ack, // and must not call Message.Nack. // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// As +// # As // // natspubsub exposes the following types for As: -// - Topic: *nats.Conn -// - Subscription: *nats.Subscription -// - Message.BeforeSend: None. -// - Message.AfterSend: None. -// - Message: *nats.Msg +// - Topic: *nats.Conn +// - Subscription: *nats.Subscription +// - Message.BeforeSend: None. +// - Message.AfterSend: None. +// - Message: *nats.Msg package natspubsub // import "gocloud.dev/pubsub/natspubsub" import ( diff --git a/pubsub/pubsub.go b/pubsub/pubsub.go index 6182f18852..7805854735 100644 --- a/pubsub/pubsub.go +++ b/pubsub/pubsub.go @@ -18,8 +18,7 @@ // // See https://gocloud.dev/howto/pubsub/ for a detailed how-to guide. // -// -// At-most-once and At-least-once Delivery +// # At-most-once and At-least-once Delivery // // The semantics of message delivery vary across PubSub services. // Some services guarantee that messages received by subscribers but not @@ -34,22 +33,23 @@ // documentation for more information about message delivery semantics. // // After receiving a Message via Subscription.Receive: -// - Always call Message.Ack or Message.Nack after processing the message. -// - For some drivers, Ack will be a no-op. -// - For some drivers, Nack is not supported and will panic; you can call -// Message.Nackable to see. +// - Always call Message.Ack or Message.Nack after processing the message. +// - For some drivers, Ack will be a no-op. +// - For some drivers, Nack is not supported and will panic; you can call +// Message.Nackable to see. // -// OpenCensus Integration +// # OpenCensus Integration // // OpenCensus supports tracing and metric collection for multiple languages and // backend providers. See https://opencensus.io. // // This API collects OpenCensus traces and metrics for the following methods: -// - Topic.Send -// - Topic.Shutdown -// - Subscription.Receive -// - Subscription.Shutdown -// - The internal driver methods SendBatch, SendAcks and ReceiveBatch. +// - Topic.Send +// - Topic.Shutdown +// - Subscription.Receive +// - Subscription.Shutdown +// - The internal driver methods SendBatch, SendAcks and ReceiveBatch. +// // All trace and metric names begin with the package import path. // The traces add the method name. // For example, "gocloud.dev/pubsub/Topic.Send". @@ -520,15 +520,18 @@ func (s *Subscription) updateBatchSize() int { // Receive retries retryable errors from the underlying driver forever. // Therefore, if Receive returns an error, either: // 1. It is a non-retryable error from the underlying driver, either from -// an attempt to fetch more messages or from an attempt to ack messages. -// Operator intervention may be required (e.g., invalid resource, quota -// error, etc.). Receive will return the same error from then on, so the -// application should log the error and either recreate the Subscription, -// or exit. +// +// an attempt to fetch more messages or from an attempt to ack messages. +// Operator intervention may be required (e.g., invalid resource, quota +// error, etc.). Receive will return the same error from then on, so the +// application should log the error and either recreate the Subscription, +// or exit. +// // 2. The provided ctx is Done. Error() on the returned error will include both -// the ctx error and the underlying driver error, and ErrorAs on it -// can access the underlying driver error type if needed. Receive may -// be called again with a fresh ctx. +// +// the ctx error and the underlying driver error, and ErrorAs on it +// can access the underlying driver error type if needed. Receive may +// be called again with a fresh ctx. // // Callers can distinguish between the two by checking if the ctx they passed // is Done, or via xerrors.Is(err, context.DeadlineExceeded or context.Canceled) diff --git a/pubsub/pubsub_test.go b/pubsub/pubsub_test.go index 6155f434a5..0ec1a894f1 100644 --- a/pubsub/pubsub_test.go +++ b/pubsub/pubsub_test.go @@ -4,7 +4,7 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// https://www.apache.org/licenses/LICENSE-2.0 +// https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, diff --git a/pubsub/rabbitpubsub/doc.go b/pubsub/rabbitpubsub/doc.go index 4e58890b8f..86fcd3342e 100644 --- a/pubsub/rabbitpubsub/doc.go +++ b/pubsub/rabbitpubsub/doc.go @@ -25,7 +25,7 @@ // A Pub/Sub subscription is an AMQP queue. The queue should be bound to the exchange // that is the topic of the subscription. See the package example for details. // -// URLs +// # URLs // // For pubsub.OpenTopic and pubsub.OpenSubscription, rabbitpubsub registers // for the scheme "rabbit". @@ -35,20 +35,20 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// Message Delivery Semantics +// # Message Delivery Semantics // // RabbitMQ supports at-least-once semantics; applications must // call Message.Ack after processing a message, or it will be redelivered. // See https://godoc.org/gocloud.dev/pubsub#hdr-At_most_once_and_At_least_once_Delivery // for more background. // -// As +// # As // // rabbitpubsub exposes the following types for As: -// - Topic: *amqp.Connection -// - Subscription: *amqp.Connection -// - Message.BeforeSend: *amqp.Publishing -// - Message.AfterSend: None -// - Message: amqp.Delivery -// - Error: *amqp.Error and MultiError +// - Topic: *amqp.Connection +// - Subscription: *amqp.Connection +// - Message.BeforeSend: *amqp.Publishing +// - Message.AfterSend: None +// - Message: amqp.Delivery +// - Error: *amqp.Error and MultiError package rabbitpubsub // import "gocloud.dev/pubsub/rabbitpubsub" diff --git a/pubsub/sub_test.go b/pubsub/sub_test.go index 14b84b852f..087fa65f97 100644 --- a/pubsub/sub_test.go +++ b/pubsub/sub_test.go @@ -4,7 +4,7 @@ // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // -// https://www.apache.org/licenses/LICENSE-2.0 +// https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, diff --git a/runtimevar/awsparamstore/awsparamstore.go b/runtimevar/awsparamstore/awsparamstore.go index 58bc76e66e..cae85a203f 100644 --- a/runtimevar/awsparamstore/awsparamstore.go +++ b/runtimevar/awsparamstore/awsparamstore.go @@ -17,7 +17,7 @@ // (https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) // Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, awsparamstore registers for the scheme "awsparamstore". // The default URL opener will use an AWS session with the default credentials @@ -27,11 +27,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // awsparamstore exposes the following types for As: -// - Snapshot: (V1) *ssm.GetParameterOutput, *ssm.DescribeParametersOutput, (V2) *ssmv2.GetParameterOutput, *ssmv2.DescribeParametersOutput -// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError +// - Snapshot: (V1) *ssm.GetParameterOutput, *ssm.DescribeParametersOutput, (V2) *ssmv2.GetParameterOutput, *ssmv2.DescribeParametersOutput +// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError package awsparamstore // import "gocloud.dev/runtimevar/awsparamstore" import ( @@ -80,10 +80,10 @@ var Set = wire.NewSet( // // In addition, the following URL parameters are supported: // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // UseV2 indicates whether the AWS SDK V2 should be used. UseV2 bool diff --git a/runtimevar/awssecretsmanager/awssecretsmanager.go b/runtimevar/awssecretsmanager/awssecretsmanager.go index 9835ab863d..fb9361695d 100644 --- a/runtimevar/awssecretsmanager/awssecretsmanager.go +++ b/runtimevar/awssecretsmanager/awssecretsmanager.go @@ -16,7 +16,7 @@ // read from AWS Secrets Manager (https://aws.amazon.com/secrets-manager) // Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, awssecretsmanager registers for the scheme "awssecretsmanager". // The default URL opener will use an AWS session with the default credentials @@ -26,11 +26,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // awssecretsmanager exposes the following types for As: -// - Snapshot: (V1) *secretsmanager.GetSecretValueOutput, *secretsmanager.DescribeSecretOutput, (V2) *secretsmanagerv2.GetSecretValueOutput, *secretsmanagerv2.DescribeSecretOutput -// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError +// - Snapshot: (V1) *secretsmanager.GetSecretValueOutput, *secretsmanager.DescribeSecretOutput, (V2) *secretsmanagerv2.GetSecretValueOutput, *secretsmanagerv2.DescribeSecretOutput +// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError package awssecretsmanager // import "gocloud.dev/runtimevar/awssecretsmanager" import ( @@ -79,10 +79,10 @@ var Set = wire.NewSet( // // In addition, the following URL parameters are supported: // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // UseV2 indicates whether the AWS SDK V2 should be used. UseV2 bool diff --git a/runtimevar/blobvar/blobvar.go b/runtimevar/blobvar/blobvar.go index b5b595b058..77c2469741 100644 --- a/runtimevar/blobvar/blobvar.go +++ b/runtimevar/blobvar/blobvar.go @@ -16,7 +16,7 @@ // variables read from a blob.Bucket. // Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, blobvar registers for the scheme "blob". // The default URL opener will open a blob.Bucket based on the environment @@ -25,11 +25,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // blobvar exposes the following types for As: -// - Snapshot: Not supported. -// - Error: error, which can be passed to blob.ErrorAs. +// - Snapshot: Not supported. +// - Error: error, which can be passed to blob.ErrorAs. package blobvar // import "gocloud.dev/runtimevar/blobvar" import ( @@ -85,10 +85,10 @@ const Scheme = "blob" // URLOpener opens blob-backed URLs like "blob://myblobkey?decoder=string". // It supports the following URL parameters: // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // Bucket is required. Bucket *blob.Bucket diff --git a/runtimevar/constantvar/constantvar.go b/runtimevar/constantvar/constantvar.go index 7adfda9f7d..a8018777ad 100644 --- a/runtimevar/constantvar/constantvar.go +++ b/runtimevar/constantvar/constantvar.go @@ -16,13 +16,13 @@ // that never change. Use New, NewBytes, or NewError to construct a // *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, constantvar registers for the scheme "constant". // For more details on the URL format, see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // constantvar does not support any types for As. package constantvar // import "gocloud.dev/runtimevar/constantvar" @@ -52,11 +52,11 @@ const Scheme = "constant" // // The following URL parameters are supported: // - val: The value to use for the constant Variable. The bytes from val -// are passed to NewBytes. +// are passed to NewBytes. // - err: The error to use for the constant Variable. A new error is created -// using errors.New and passed to NewError. +// using errors.New and passed to NewError. // - decoder: The decoder to use. Defaults to runtimevar.BytesDecoder. -// See runtimevar.DecoderByName for supported values. +// See runtimevar.DecoderByName for supported values. // // If both "err" and "val" are provided, "val" is ignored. type URLOpener struct { diff --git a/runtimevar/etcdvar/etcdvar.go b/runtimevar/etcdvar/etcdvar.go index 1792901ee3..501797ad6e 100644 --- a/runtimevar/etcdvar/etcdvar.go +++ b/runtimevar/etcdvar/etcdvar.go @@ -15,7 +15,7 @@ // Package etcdvar provides a runtimevar implementation with variables // backed by etcd. Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, etcdvar registers for the scheme "etcd". // The default URL opener will dial an etcd server based on the environment @@ -24,11 +24,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // etcdvar exposes the following types for As: -// - Snapshot: *clientv3.GetResponse -// - Error: rpctypes.EtcdError +// - Snapshot: *clientv3.GetResponse +// - Error: rpctypes.EtcdError package etcdvar // import "gocloud.dev/runtimevar/etcdvar" import ( @@ -88,7 +88,7 @@ func (o *defaultDialer) OpenVariableURL(ctx context.Context, u *url.URL) (*runti // // The following URL parameters are supported: // - decoder: The decoder to use. Defaults to runtimevar.BytesDecoder. -// See runtimevar.DecoderByName for supported values. +// See runtimevar.DecoderByName for supported values. type URLOpener struct { // The Client to use; required. Client *clientv3.Client diff --git a/runtimevar/filevar/filevar.go b/runtimevar/filevar/filevar.go index 1c4341c084..a51de89749 100644 --- a/runtimevar/filevar/filevar.go +++ b/runtimevar/filevar/filevar.go @@ -24,16 +24,17 @@ // Known Issues: // // * On macOS, if an empty file is copied into a configuration file, -// filevar will not detect the change. // -// URLs +// filevar will not detect the change. +// +// # URLs // // For runtimevar.OpenVariable, filevar registers for the scheme "file". // To customize the URL opener, or for more details on the URL format, // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // filevar does not support any types for As. package filevar // import "gocloud.dev/runtimevar/filevar" @@ -71,10 +72,10 @@ const Scheme = "file" // // The following URL parameters are supported: // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The frequency for retries after an error, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // Decoder specifies the decoder to use if one is not specified in the URL. // Defaults to runtimevar.BytesDecoder. diff --git a/runtimevar/gcpruntimeconfig/gcpruntimeconfig.go b/runtimevar/gcpruntimeconfig/gcpruntimeconfig.go index e41dbf7b17..1e7ebca7b2 100644 --- a/runtimevar/gcpruntimeconfig/gcpruntimeconfig.go +++ b/runtimevar/gcpruntimeconfig/gcpruntimeconfig.go @@ -17,7 +17,7 @@ // (https://cloud.google.com/deployment-manager/runtime-configurator). // Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, gcpruntimeconfig registers for the scheme // "gcpruntimeconfig". @@ -28,11 +28,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // gcpruntimeconfig exposes the following types for As: -// - Snapshot: *pb.Variable -// - Error: *status.Status +// - Snapshot: *pb.Variable +// - Error: *status.Status package gcpruntimeconfig // import "gocloud.dev/runtimevar/gcpruntimeconfig" import ( @@ -133,10 +133,10 @@ const Scheme = "gcpruntimeconfig" // The following query parameters are supported: // // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // Client must be set to a non-nil client authenticated with // Cloud RuntimeConfigurator scope or equivalent. @@ -187,7 +187,8 @@ type Options struct { // GCP Cloud Runtime Configurator. // // A variableKey will look like: -// projects/[project_id]/configs/[CONFIG_ID]/variables/[VARIABLE_NAME] +// +// projects/[project_id]/configs/[CONFIG_ID]/variables/[VARIABLE_NAME] // // You can use the full string (e.g., copied from the GCP Console), or // construct one from its parts using VariableKey. diff --git a/runtimevar/gcpsecretmanager/gcpsecretmanager.go b/runtimevar/gcpsecretmanager/gcpsecretmanager.go index f96f2fd1b7..cc500b2b33 100644 --- a/runtimevar/gcpsecretmanager/gcpsecretmanager.go +++ b/runtimevar/gcpsecretmanager/gcpsecretmanager.go @@ -17,7 +17,7 @@ // (https://cloud.google.com/secret-manager). // Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, gcpsecretmanager registers for the scheme // "gcpsecretmanager". @@ -28,11 +28,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // gcpsecretmanager exposes the following types for As: -// - Snapshot: *secretmanagerpb.AccessSecretVersionResponse -// - Error: *status.Status +// - Snapshot: *secretmanagerpb.AccessSecretVersionResponse +// - Error: *status.Status package gcpsecretmanager // import "gocloud.dev/runtimevar/gcpsecretmanager" import ( @@ -133,10 +133,10 @@ const Scheme = "gcpsecretmanager" // The following query parameters are supported: // // - decoder: The decoder to use. Defaults to URLOpener.Decoder, or -// runtimevar.BytesDecoder if URLOpener.Decoder is nil. -// See runtimevar.DecoderByName for supported values. +// runtimevar.BytesDecoder if URLOpener.Decoder is nil. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // Client must be set to a non-nil client authenticated with // Secret Manager scope or equivalent. @@ -186,7 +186,8 @@ type Options struct { // OpenVariable constructs a *runtimevar.Variable backed by secretKey in GCP Secret Manager. // // A secretKey will look like: -// projects/[project_id]/secrets/[secret_id] +// +// projects/[project_id]/secrets/[secret_id] // // A project ID is a unique, user-assigned ID of the Project. // It must be 6 to 30 lowercase letters, digits, or hyphens. diff --git a/runtimevar/httpvar/httpvar.go b/runtimevar/httpvar/httpvar.go index 15c560c261..096dd927fb 100644 --- a/runtimevar/httpvar/httpvar.go +++ b/runtimevar/httpvar/httpvar.go @@ -15,7 +15,7 @@ // Package httpvar provides a runtimevar implementation with variables // backed by http endpoint. Use OpenVariable to construct a *runtimevar.Variable. // -// URLs +// # URLs // // For runtimevar.OpenVariable, httpvar registers for the schemes "http" and // "https". The default URL opener will use http.DefaultClient. @@ -25,11 +25,11 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // httpvar exposes the following types for As: -// - Snapshot: *http.Response -// - Error: httpvar.RequestError, url.Error +// - Snapshot: *http.Response +// - Error: httpvar.RequestError, url.Error package httpvar // import "gocloud.dev/runtimevar/httpvar" import ( @@ -63,9 +63,9 @@ var Schemes = []string{"http", "https"} // The full URL, including scheme, is used as the endpoint, except that the // the following URL parameters are removed if present: // - decoder: The decoder to use. Defaults to runtimevar.BytesDecoder. -// See runtimevar.DecoderByName for supported values. +// See runtimevar.DecoderByName for supported values. // - wait: The poll interval, in time.ParseDuration formats. -// Defaults to 30s. +// Defaults to 30s. type URLOpener struct { // The Client to use; required. Client *http.Client diff --git a/runtimevar/runtimevar.go b/runtimevar/runtimevar.go index d8df21fd9d..dab59b042e 100644 --- a/runtimevar/runtimevar.go +++ b/runtimevar/runtimevar.go @@ -18,8 +18,7 @@ // // See https://gocloud.dev/howto/runtimevar/ for a detailed how-to guide. // -// -// OpenCensus Integration +// # OpenCensus Integration // // OpenCensus supports tracing and metric collection for multiple languages and // backend providers. See https://opencensus.io. @@ -497,12 +496,13 @@ func DecryptDecode(k *secrets.Keeper, post Decode) Decode { // // Supported values include: // - empty string: Returns the default from the URLOpener.Decoder, or -// BytesDecoder if URLOpener.Decoder is nil (which is true if you're -// using the default URLOpener). +// BytesDecoder if URLOpener.Decoder is nil (which is true if you're +// using the default URLOpener). // - "bytes": Returns a BytesDecoder; Snapshot.Value will be of type []byte. // - "jsonmap": Returns a JSON decoder for a map[string]interface{}; -// Snapshot.Value will be of type *map[string]interface{}. +// Snapshot.Value will be of type *map[string]interface{}. // - "string": Returns StringDecoder; Snapshot.Value will be of type string. +// // It also supports using "decrypt+" (or "decrypt" for default // decoder) to decrypt the data before decoding. It uses the secrets package to // open a keeper by the URL string stored in a environment variable diff --git a/samples/order/order.go b/samples/order/order.go index 4e43eee17e..ec608ed0d3 100644 --- a/samples/order/order.go +++ b/samples/order/order.go @@ -17,9 +17,9 @@ // can use to place and view orders; and a processor, which performs the // conversions. This binary can run both together in one process (the default), // or it can run either on its own. Either way, the two components: -// - communicate over a topic using the gocloud.dev/pubsub API; -// - write orders to a database using the gocloud.dev/docstore API; -// - and save image files to cloud storage using the gocloud.dev/blob API. +// - communicate over a topic using the gocloud.dev/pubsub API; +// - write orders to a database using the gocloud.dev/docstore API; +// - and save image files to cloud storage using the gocloud.dev/blob API. // // This application assumes at-least-once processing. Make sure the pubsub // implementation you provide to it has that behavior. diff --git a/secrets/awskms/kms.go b/secrets/awskms/kms.go index f97230edf3..c0acfca1de 100644 --- a/secrets/awskms/kms.go +++ b/secrets/awskms/kms.go @@ -16,7 +16,7 @@ // Use OpenKeeper to construct a *secrets.Keeper, or OpenKeeperV2 to // use AWS SDK V2. // -// URLs +// # URLs // // For secrets.OpenKeeper, awskms registers for the scheme "awskms". // The default URL opener will use an AWS session with the default credentials @@ -27,10 +27,10 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // awskms exposes the following type for As: -// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError +// - Error: (V1) awserr.Error, (V2) any error type returned by the service, notably smithy.APIError package awskms // import "gocloud.dev/secrets/awskms" import ( diff --git a/secrets/azurekeyvault/akv.go b/secrets/azurekeyvault/akv.go index cfc373cf53..f6e3e5f70d 100644 --- a/secrets/azurekeyvault/akv.go +++ b/secrets/azurekeyvault/akv.go @@ -16,7 +16,7 @@ // See https://docs.microsoft.com/en-us/azure/key-vault/key-vault-whatis for more information. // Use OpenKeeper to construct a *secrets.Keeper. // -// URLs +// # URLs // // For secrets.OpenKeeper, azurekeyvault registers for the scheme "azurekeyvault". // The default URL opener will use Dial, which gets default credentials from the @@ -28,7 +28,7 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // azurekeyvault exposes the following type for As: // - Error: autorest.DetailedError, see https://godoc.org/github.com/Azure/go-autorest/autorest#DetailedError diff --git a/secrets/gcpkms/kms.go b/secrets/gcpkms/kms.go index ad34dbdbca..3fad4a6c8f 100644 --- a/secrets/gcpkms/kms.go +++ b/secrets/gcpkms/kms.go @@ -15,7 +15,7 @@ // Package gcpkms provides a secrets implementation backed by Google Cloud KMS. // Use OpenKeeper to construct a *secrets.Keeper. // -// URLs +// # URLs // // For secrets.OpenKeeper, gcpkms registers for the scheme "gcpkms". // The default URL opener will create a connection using use default @@ -25,10 +25,10 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // gcpkms exposes the following type for As: -// - Error: *google.golang.org/grpc/status.Status +// - Error: *google.golang.org/grpc/status.Status package gcpkms // import "gocloud.dev/secrets/gcpkms" import ( diff --git a/secrets/hashivault/vault.go b/secrets/hashivault/vault.go index 8c69e3fb10..d3ae262e14 100644 --- a/secrets/hashivault/vault.go +++ b/secrets/hashivault/vault.go @@ -16,7 +16,7 @@ // Secrets Engine of Vault by Hashicorp. // Use OpenKeeper to construct a *secrets.Keeper. // -// URLs +// # URLs // // For secrets.OpenKeeper, hashivault registers for the scheme "hashivault". // The default URL opener will dial a Vault server using the environment variables @@ -25,7 +25,7 @@ // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // hashivault does not support any types for As. package hashivault diff --git a/secrets/localsecrets/localsecrets.go b/secrets/localsecrets/localsecrets.go index fe38b3959b..30298b1ad2 100644 --- a/secrets/localsecrets/localsecrets.go +++ b/secrets/localsecrets/localsecrets.go @@ -16,14 +16,14 @@ // provided symmetric key. // Use NewKeeper to construct a *secrets.Keeper. // -// URLs +// # URLs // // For secrets.OpenKeeper, localsecrets registers for the scheme "base64key". // To customize the URL opener, or for more details on the URL format, // see URLOpener. // See https://gocloud.dev/concepts/urls/ for background information. // -// As +// # As // // localsecrets does not support any types for As. package localsecrets // import "gocloud.dev/secrets/localsecrets" diff --git a/secrets/secrets.go b/secrets/secrets.go index 647ae0588e..58bcc7bcd7 100644 --- a/secrets/secrets.go +++ b/secrets/secrets.go @@ -18,15 +18,15 @@ // // See https://gocloud.dev/howto/secrets/ for a detailed how-to guide. // -// -// OpenCensus Integration +// # OpenCensus Integration // // OpenCensus supports tracing and metric collection for multiple languages and // backend providers. See https://opencensus.io. // // This API collects OpenCensus traces and metrics for the following methods: -// - Encrypt -// - Decrypt +// - Encrypt +// - Decrypt +// // All trace and metric names begin with the package import path. // The traces add the method name. // For example, "gocloud.dev/secrets/Encrypt".