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