From 16d48cd2d7433d2bf82953d74eb16766d2c41b0b Mon Sep 17 00:00:00 2001 From: Sean Kane <68240067+seankane-msft@users.noreply.github.com> Date: Tue, 7 Sep 2021 13:17:18 -0400 Subject: [PATCH] [azcore] updating doc.go (#15477) * updating doc.go * update changelog * joels comments * fix up package names and examples * add section on logging * add doc.go for sub-packages Co-authored-by: Joel Hendrix --- sdk/azcore/CHANGELOG.md | 7 +-- sdk/azcore/README.md | 2 +- sdk/azcore/arm/doc.go | 9 ++++ sdk/azcore/doc.go | 67 +++++++++++++++++----------- sdk/azcore/log/doc.go | 10 +++++ sdk/azcore/policy/doc.go | 10 +++++ sdk/azcore/runtime/doc.go | 10 +++++ sdk/azcore/runtime/policy_logging.go | 2 +- sdk/azcore/streaming/doc.go | 9 ++++ sdk/azcore/to/doc.go | 9 ++++ 10 files changed, 100 insertions(+), 35 deletions(-) create mode 100644 sdk/azcore/arm/doc.go create mode 100644 sdk/azcore/log/doc.go create mode 100644 sdk/azcore/policy/doc.go create mode 100644 sdk/azcore/runtime/doc.go create mode 100644 sdk/azcore/streaming/doc.go create mode 100644 sdk/azcore/to/doc.go diff --git a/sdk/azcore/CHANGELOG.md b/sdk/azcore/CHANGELOG.md index 51e53a1bc3e6..8311838d540b 100644 --- a/sdk/azcore/CHANGELOG.md +++ b/sdk/azcore/CHANGELOG.md @@ -3,12 +3,7 @@ ## v0.20.0 (Unreleased) ### Features Added - -### Breaking Changes - -### Bug Fixes - -### Other Changes +* Updating Documentation ## v0.19.0 (2021-08-25) diff --git a/sdk/azcore/README.md b/sdk/azcore/README.md index d4e3802a5c2f..35a74e18d09a 100644 --- a/sdk/azcore/README.md +++ b/sdk/azcore/README.md @@ -15,7 +15,7 @@ Typically, you will not need to explicitly install `azcore` as it will be instal To add the latest version to your `go.mod` file, execute the following command. ```bash -go get -u github.com/Azure/azure-sdk-for-go/sdk/azcore +go get github.com/Azure/azure-sdk-for-go/sdk/azcore ``` General documentation and examples can be found on [pkg.go.dev](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore). diff --git a/sdk/azcore/arm/doc.go b/sdk/azcore/arm/doc.go new file mode 100644 index 000000000000..657e2c84aef1 --- /dev/null +++ b/sdk/azcore/arm/doc.go @@ -0,0 +1,9 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package arm contains functionality specific to Azure Resource Manager clients. +package arm diff --git a/sdk/azcore/doc.go b/sdk/azcore/doc.go index a90b6e542c23..69211850e428 100644 --- a/sdk/azcore/doc.go +++ b/sdk/azcore/doc.go @@ -11,8 +11,8 @@ Package azcore implements an HTTP request/response middleware pipeline. The middleware consists of three components. - One or more Policy instances. - - A Transport instance. - - A Pipeline instance that combines the Policy and Transport instances. + - A Transporter instance. + - A Pipeline instance that combines the Policy and Transporter instances. Implementing the Policy Interface @@ -24,18 +24,25 @@ avoid race conditions. A Policy's Do method is called when an HTTP request wants to be sent over the network. The Do method can perform any operation(s) it desires. For example, it can log the outgoing request, mutate the URL, headers, and/or query parameters, inject a failure, etc. Once the Policy has successfully completed its request -work, it must call the Next() method on the *azcore.Request instance in order to pass the request to the +work, it must call the Next() method on the *policy.Request instance in order to pass the request to the next Policy in the chain. When an HTTP response comes back, the Policy then gets a chance to process the response/error. The Policy instance can log the response, retry the operation if it failed due to a transient error or timeout, unmarshal the response -body, etc. Once the Policy has successfully completed its response work, it must return the *azcore.Response +body, etc. Once the Policy has successfully completed its response work, it must return the *http.Response and error instances to its caller. Template for implementing a stateless Policy: - func NewMyStatelessPolicy() Policy { - return azcore.PolicyFunc(func(req *azcore.Request) (*azcore.Response, error) { + type policyFunc func(*policy.Request) (*http.Response, error) + // Do implements the Policy interface on policyFunc. + + func (pf policyFunc) Do(req *policy.Request) (*http.Response, error) { + return pf(req) + } + + func NewMyStatelessPolicy() policy.Policy { + return policyFunc(func(req *policy.Request) (*http.Response, error) { // TODO: mutate/process Request here // forward Request to next Policy & get Response/error @@ -55,13 +62,13 @@ Template for implementing a stateful Policy: } // TODO: add initialization args to NewMyStatefulPolicy() - func NewMyStatefulPolicy() Policy { + func NewMyStatefulPolicy() policy.Policy { return &MyStatefulPolicy{ // TODO: initialize configuration/setting fields here } } - func (p *MyStatefulPolicy) Do(req *azcore.Request) (resp *azcore.Response, err error) { + func (p *MyStatefulPolicy) Do(req *policy.Request) (resp *http.Response, err error) { // TODO: mutate/process Request here // forward Request to next Policy & get Response/error @@ -73,30 +80,30 @@ Template for implementing a stateful Policy: return resp, err } -Implementing the Transport Interface +Implementing the Transporter Interface -The Transport interface is responsible for sending the HTTP request and returning the corresponding -HTTP response or error. The Transport is invoked by the last Policy in the chain. The default Transport +The Transporter interface is responsible for sending the HTTP request and returning the corresponding +HTTP response or error. The Transporter is invoked by the last Policy in the chain. The default Transporter implementation uses a shared http.Client from the standard library. -The same stateful/stateless rules for Policy implementations apply to Transport implementations. +The same stateful/stateless rules for Policy implementations apply to Transporter implementations. -Using Policy and Transport Instances Via a Pipeline +Using Policy and Transporter Instances Via a Pipeline -To use the Policy and Transport instances, an application passes them to the NewPipeline function. +To use the Policy and Transporter instances, an application passes them to the runtime.NewPipeline function. - func NewPipeline(transport Transport, policies ...Policy) Pipeline + func NewPipeline(transport Transporter, policies ...Policy) Pipeline The specified Policy instances form a chain and are invoked in the order provided to NewPipeline -followed by the Transport. +followed by the Transporter. -Once the Pipeline has been created, create a Request instance and pass it to Pipeline's Do method. +Once the Pipeline has been created, create a runtime.Request instance and pass it to Pipeline's Do method. func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error) - func (p Pipeline) Do(req *Request) (*Response, error) + func (p Pipeline) Do(req *Request) (*http.Request, error) -The Pipeline.Do method sends the specified Request through the chain of Policy and Transport +The Pipeline.Do method sends the specified Request through the chain of Policy and Transporter instances. The response/error is then sent through the same chain of Policy instances in reverse order. For example, assuming there are Policy types PolicyA, PolicyB, and PolicyC along with TransportA. @@ -105,17 +112,17 @@ TransportA. The flow of Request and Response looks like the following: - azcore.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+ + policy.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+ | HTTP(s) endpoint | - caller <--------- PolicyA <- PolicyB <- PolicyC <- azcore.Response-+ + caller <--------- PolicyA <- PolicyB <- PolicyC <- http.Response-+ Creating a Request Instance The Request instance passed to Pipeline's Do method is a wrapper around an *http.Request. It also contains some internal state and provides various convenience methods. You create a Request instance -by calling the NewRequest function: +by calling the runtime.NewRequest function: func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error) @@ -158,11 +165,17 @@ This sends an explict "null" for Count, indicating that any current value for Co Processing the Response -When the HTTP response is received, the underlying *http.Response is wrapped in a Response type. -The Response type contains various convenience methods, like testing the HTTP response code and -unmarshalling the response body in a particular format. +When the HTTP response is received, the *http.Response is returned directly. Each Policy instance +can inspect/mutate the *http.Response. + +Built-in Logging + +To enable logging, set environment variable AZURE_SDK_GO_LOGGING to "all" before executing your program. + +By default the logger writes to stderr. This can be customized by calling log.SetListener, providing +a callback that writes to the desired location. Any custom logging implementation MUST provide its +own synchronization to handle concurrent invocations. -The Response is returned through all the Policy instances. Each Policy instance can inspect/mutate the -embedded *http.Response. +See the docs for the log package for further details. */ package azcore diff --git a/sdk/azcore/log/doc.go b/sdk/azcore/log/doc.go new file mode 100644 index 000000000000..9fc18afee8a3 --- /dev/null +++ b/sdk/azcore/log/doc.go @@ -0,0 +1,10 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package log contains functionality for configuring logging behavior. +// Default logging to stderr can be enabled by setting environment variable AZURE_SDK_GO_LOGGING to "all". +package log diff --git a/sdk/azcore/policy/doc.go b/sdk/azcore/policy/doc.go new file mode 100644 index 000000000000..572c7f119b86 --- /dev/null +++ b/sdk/azcore/policy/doc.go @@ -0,0 +1,10 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package policy contains the definitions needed for configuring in-box pipeline policies +// and creating custom policies. +package policy diff --git a/sdk/azcore/runtime/doc.go b/sdk/azcore/runtime/doc.go new file mode 100644 index 000000000000..d3f5408def39 --- /dev/null +++ b/sdk/azcore/runtime/doc.go @@ -0,0 +1,10 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package runtime contains various facilities for creating requests and handling responses. +// The content is intended for SDK authors. +package runtime diff --git a/sdk/azcore/runtime/policy_logging.go b/sdk/azcore/runtime/policy_logging.go index b013a0c45f1a..25b39c4995ff 100644 --- a/sdk/azcore/runtime/policy_logging.go +++ b/sdk/azcore/runtime/policy_logging.go @@ -24,7 +24,7 @@ type logPolicy struct { options policy.LogOptions } -// NewLogPolicy creates a RequestLogPolicy object configured using the specified options. +// NewLogPolicy creates a request/response logging policy object configured using the specified options. // Pass nil to accept the default values; this is the same as passing a zero-value options. func NewLogPolicy(o *policy.LogOptions) policy.Policy { if o == nil { diff --git a/sdk/azcore/streaming/doc.go b/sdk/azcore/streaming/doc.go new file mode 100644 index 000000000000..b613f085bb62 --- /dev/null +++ b/sdk/azcore/streaming/doc.go @@ -0,0 +1,9 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package streaming contains helpers for streaming IO operations and progress reporting. +package streaming diff --git a/sdk/azcore/to/doc.go b/sdk/azcore/to/doc.go new file mode 100644 index 000000000000..64733444fb5a --- /dev/null +++ b/sdk/azcore/to/doc.go @@ -0,0 +1,9 @@ +//go:build go1.16 +// +build go1.16 + +// Copyright 2017 Microsoft Corporation. All rights reserved. +// Use of this source code is governed by an MIT +// license that can be found in the LICENSE file. + +// Package to contains various type-conversion helper functions. +package to