Debian Codegraph @

README.md

raw
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 [![GoDoc](https://godoc.org/github.com/Azure/go-autorest/autorest?status.png)](https://godoc.org/github.com/Azure/go-autorest/autorest)
6 [![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)
7 [![Go Report Card](https://goreportcard.com/badge/Azure/go-autorest)](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.