| 1 |
# NOTE: The modules in this repo will go out of support by March 31, 2023. Additional information can be found [here](https://azure.microsoft.com/updates/support-for-azure-sdk-libraries-that-do-not-conform-to-our-current-azure-sdk-guidelines-will-be-retired-as-of-31-march-2023/). |
| 2 |
|
| 3 |
# go-autorest |
| 4 |
|
| 5 |
[](https://godoc.org/github.com/Azure/go-autorest/autorest) |
| 6 |
[](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=625&branchName=master) |
| 7 |
[](https://goreportcard.com/report/Azure/go-autorest) |
| 8 |
|
| 9 |
Package go-autorest provides an HTTP request client for use with [Autorest](https://github.com/Azure/autorest.go)-generated API client packages. |
| 10 |
|
| 11 |
An authentication client tested with Azure Active Directory (AAD) is also |
| 12 |
provided in this repo in the package |
| 13 |
`github.com/Azure/go-autorest/autorest/adal`. Despite its name, this package |
| 14 |
is maintained only as part of the Azure Go SDK and is not related to other |
| 15 |
"ADAL" libraries in [github.com/AzureAD](https://github.com/AzureAD). |
| 16 |
|
| 17 |
## Overview |
| 18 |
|
| 19 |
Package go-autorest implements an HTTP request pipeline suitable for use across |
| 20 |
multiple goroutines and provides the shared routines used by packages generated |
| 21 |
by [Autorest](https://github.com/Azure/autorest.go). |
| 22 |
|
| 23 |
The package breaks sending and responding to HTTP requests into three phases: Preparing, Sending, |
| 24 |
and Responding. A typical pattern is: |
| 25 |
|
| 26 |
```go |
| 27 |
req, err := Prepare(&http.Request{}, |
| 28 |
token.WithAuthorization()) |
| 29 |
|
| 30 |
resp, err := Send(req, |
| 31 |
WithLogging(logger), |
| 32 |
DoErrorIfStatusCode(http.StatusInternalServerError), |
| 33 |
DoCloseIfError(), |
| 34 |
DoRetryForAttempts(5, time.Second)) |
| 35 |
|
| 36 |
err = Respond(resp, |
| 37 |
ByDiscardingBody(), |
| 38 |
ByClosing()) |
| 39 |
``` |
| 40 |
|
| 41 |
Each phase relies on decorators to modify and / or manage processing. Decorators may first modify |
| 42 |
and then pass the data along, pass the data first and then modify the result, or wrap themselves |
| 43 |
around passing the data (such as a logger might do). Decorators run in the order provided. For |
| 44 |
example, the following: |
| 45 |
|
| 46 |
```go |
| 47 |
req, err := Prepare(&http.Request{}, |
| 48 |
WithBaseURL("https://microsoft.com/"), |
| 49 |
WithPath("a"), |
| 50 |
WithPath("b"), |
| 51 |
WithPath("c")) |
| 52 |
``` |
| 53 |
|
| 54 |
will set the URL to: |
| 55 |
|
| 56 |
``` |
| 57 |
https://microsoft.com/a/b/c |
| 58 |
``` |
| 59 |
|
| 60 |
Preparers and Responders may be shared and re-used (assuming the underlying decorators support |
| 61 |
sharing and re-use). Performant use is obtained by creating one or more Preparers and Responders |
| 62 |
shared among multiple go-routines, and a single Sender shared among multiple sending go-routines, |
| 63 |
all bound together by means of input / output channels. |
| 64 |
|
| 65 |
Decorators hold their passed state within a closure (such as the path components in the example |
| 66 |
above). Be careful to share Preparers and Responders only in a context where such held state |
| 67 |
applies. For example, it may not make sense to share a Preparer that applies a query string from a |
| 68 |
fixed set of values. Similarly, sharing a Responder that reads the response body into a passed |
| 69 |
struct (e.g., `ByUnmarshallingJson`) is likely incorrect. |
| 70 |
|
| 71 |
Errors raised by autorest objects and methods will conform to the `autorest.Error` interface. |
| 72 |
|
| 73 |
See the included examples for more detail. For details on the suggested use of this package by |
| 74 |
generated clients, see the Client described below. |
| 75 |
|
| 76 |
## Helpers |
| 77 |
|
| 78 |
### Handling Swagger Dates |
| 79 |
|
| 80 |
The Swagger specification (https://swagger.io) that drives AutoRest |
| 81 |
(https://github.com/Azure/autorest/) precisely defines two date forms: date and date-time. The |
| 82 |
github.com/Azure/go-autorest/autorest/date package provides time.Time derivations to ensure correct |
| 83 |
parsing and formatting. |
| 84 |
|
| 85 |
### Handling Empty Values |
| 86 |
|
| 87 |
In JSON, missing values have different semantics than empty values. This is especially true for |
| 88 |
services using the HTTP PATCH verb. The JSON submitted with a PATCH request generally contains |
| 89 |
only those values to modify. Missing values are to be left unchanged. Developers, then, require a |
| 90 |
means to both specify an empty value and to leave the value out of the submitted JSON. |
| 91 |
|
| 92 |
The Go JSON package (`encoding/json`) supports the `omitempty` tag. When specified, it omits |
| 93 |
empty values from the rendered JSON. Since Go defines default values for all base types (such as "" |
| 94 |
for string and 0 for int) and provides no means to mark a value as actually empty, the JSON package |
| 95 |
treats default values as meaning empty, omitting them from the rendered JSON. This means that, using |
| 96 |
the Go base types encoded through the default JSON package, it is not possible to create JSON to |
| 97 |
clear a value at the server. |
| 98 |
|
| 99 |
The workaround within the Go community is to use pointers to base types in lieu of base types within |
| 100 |
structures that map to JSON. For example, instead of a value of type `string`, the workaround uses |
| 101 |
`*string`. While this enables distinguishing empty values from those to be unchanged, creating |
| 102 |
pointers to a base type (notably constant, in-line values) requires additional variables. This, for |
| 103 |
example, |
| 104 |
|
| 105 |
```go |
| 106 |
s := struct { |
| 107 |
S *string |
| 108 |
}{ S: &"foo" } |
| 109 |
``` |
| 110 |
fails, while, this |
| 111 |
|
| 112 |
```go |
| 113 |
v := "foo" |
| 114 |
s := struct { |
| 115 |
S *string |
| 116 |
}{ S: &v } |
| 117 |
``` |
| 118 |
succeeds. |
| 119 |
|
| 120 |
To ease using pointers, the subpackage `to` contains helpers that convert to and from pointers for |
| 121 |
Go base types which have Swagger analogs. It also provides a helper that converts between |
| 122 |
`map[string]string` and `map[string]*string`, enabling the JSON to specify that the value |
| 123 |
associated with a key should be cleared. With the helpers, the previous example becomes |
| 124 |
|
| 125 |
```go |
| 126 |
s := struct { |
| 127 |
S *string |
| 128 |
}{ S: to.StringPtr("foo") } |
| 129 |
``` |
| 130 |
|
| 131 |
## Install |
| 132 |
|
| 133 |
```bash |
| 134 |
go get github.com/Azure/go-autorest/autorest |
| 135 |
go get github.com/Azure/go-autorest/autorest/azure |
| 136 |
go get github.com/Azure/go-autorest/autorest/date |
| 137 |
go get github.com/Azure/go-autorest/autorest/to |
| 138 |
``` |
| 139 |
|
| 140 |
### Using with Go Modules |
| 141 |
In [v12.0.1](https://github.com/Azure/go-autorest/pull/386), this repository introduced the following modules. |
| 142 |
|
| 143 |
- autorest/adal |
| 144 |
- autorest/azure/auth |
| 145 |
- autorest/azure/cli |
| 146 |
- autorest/date |
| 147 |
- autorest/mocks |
| 148 |
- autorest/to |
| 149 |
- autorest/validation |
| 150 |
- autorest |
| 151 |
- logger |
| 152 |
- tracing |
| 153 |
|
| 154 |
Tagging cumulative SDK releases as a whole (e.g. `v12.3.0`) is still enabled to support consumers of this repo that have not yet migrated to modules. |
| 155 |
|
| 156 |
## License |
| 157 |
|
| 158 |
See LICENSE file. |
| 159 |
|
| 160 |
----- |
| 161 |
|
| 162 |
This project has adopted the [Microsoft Open Source Code of |
| 163 |
Conduct](https://opensource.microsoft.com/codeofconduct/). For more information |
| 164 |
see the [Code of Conduct |
| 165 |
FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact |
| 166 |
[[email protected]](mailto:[email protected]) with any additional |
| 167 |
questions or comments. |