-
Notifications
You must be signed in to change notification settings - Fork 55
/
README.md
288 lines (212 loc) · 8.54 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
[![Build Status](https://github.com/Unleash/unleash-client-go/actions/workflows/build.yml/badge.svg)](https://github.com/Unleash/unleash-client-go/actions/workflows/build.yml) [![GoDoc](https://godoc.org/github.com/Unleash/unleash-client-go?status.svg)](https://godoc.org/github.com/Unleash/unleash-client-go) [![Go Report Card](https://goreportcard.com/badge/github.com/Unleash/unleash-client-go)](https://goreportcard.com/report/github.com/Unleash/unleash-client-go)
[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-client-go/badge.svg?branch=v3)](https://coveralls.io/github/Unleash/unleash-client-go?branch=v3)
# unleash-client-go
Unleash Client for Go. Read more about the [Unleash project](https://github.com/Unleash/unleash)
**Version 3.x of the client requires `unleash-server` v3.x or higher.**
## Go Version
The client is currently tested against Go 1.10.x and 1.13.x. These versions will be updated
as new versions of Go are released.
The client may work on older versions of Go as well, but is not actively tested.
## Getting started
### 1. Install unleash-client-go
To install the latest version of the client use:
```bash
go get github.com/Unleash/unleash-client-go/v3
```
If you are still using Unleash Server v2.x.x, then you should use:
```bash
go get github.com/Unleash/unleash-client-go
```
### 2. Initialize unleash
The easiest way to get started with Unleash is to initialize it early in your application code:
```go
import (
"github.com/Unleash/unleash-client-go/v3"
)
func init() {
unleash.Initialize(
unleash.WithListener(&unleash.DebugListener{}),
unleash.WithAppName("my-application"),
unleash.WithUrl("http://unleash.herokuapp.com/api/"),
unleash.WithCustomHeaders(http.Header{"Authorization": {"<API token>"}}),
)
}
```
#### Preloading feature toggles
If you'd like to prebake your application with feature toggles (maybe you're working without persistent storage, so Unleash's backup isn't available), you can replace the defaultStorage implementation with a BootstrapStorage. This allows you to pass in a reader to where data in the format of `/api/client/features` can be found.
#### Bootstrapping from file
Bootstrapping from file on disk is then done using something similar to:
```go
import (
"github.com/Unleash/unleash-client-go/v3"
)
func init() {
myBootstrap := os.Open("bootstrapfile.json") // or wherever your file is located at runtime
// BootstrapStorage handles the case where Reader is nil
unleash.Initialize(
unleash.WithListener(&unleash.DebugListener{}),
unleash.WithAppName("my-application"),
unleash.WithUrl("http://unleash.herokuapp.com/api/"),
unleash.WithStorage(&BootstrapStorage{Reader: myBootstrap})
)
}
```
#### Bootstrapping from S3
Bootstrapping from S3 is then done by downloading the file using the AWS library and then passing in a Reader to the just downloaded file:
```go
import (
"github.com/Unleash/unleash-client-go/v3"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
)
func init() {
// Load the shared AWS config
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Fatal(err)
}
// Create an S3 client
client := s3.NewFromConfig(cfg)
obj, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
Bucket: aws.String("YOURBUCKET"),
Key: aws.String("YOURKEY"),
})
if err != nil {
log.Fatal(err)
}
reader := obj.Body
defer reader.Close()
// BootstrapStorage handles the case where Reader is nil
unleash.Initialize(
unleash.WithListener(&unleash.DebugListener{}),
unleash.WithAppName("YOURAPPNAME"),
unleash.WithUrl("YOURINSTANCE_URL"),
unleash.WithStorage(&BootstrapStorage{Reader: reader})
)
}
```
#### Bootstrapping from Google
Since the Google Cloud Storage API returns a Reader, implementing a Bootstrap from GCS is done using something similar to
```go
import (
"github.com/Unleash/unleash-client-go/v3"
"cloud.google.com/go/storage"
)
func init() {
ctx := context.Background() // Configure Google Cloud context
client, err := storage.NewClient(ctx) // Configure your client
if err != nil {
// TODO: Handle error.
}
defer client.Close()
// Fetch the bucket, then object and then create a reader
reader := client.Bucket(bucketName).Object("my-bootstrap.json").NewReader(ctx)
// BootstrapStorage handles the case where Reader is nil
unleash.Initialize(
unleash.WithListener(&unleash.DebugListener{}),
unleash.WithAppName("my-application"),
unleash.WithUrl("http://unleash.herokuapp.com/api/"),
unleash.WithStorage(&unleash.BootstrapStorage{Reader: reader})
)
}
```
### 3. Use unleash
After you have initialized the unleash-client you can easily check if a feature
toggle is enabled or not.
```go
unleash.IsEnabled("app.ToggleX")
```
### 4. Stop unleash
To shut down the client (turn off the polling) you can simply call the
destroy-method. This is typically not required.
unleash.Close()
### Built in activation strategies
The Go client comes with implementations for the built-in activation strategies
provided by unleash.
- DefaultStrategy
- UserIdStrategy
- FlexibleRolloutStrategy
- GradualRolloutUserIdStrategy
- GradualRolloutSessionIdStrategy
- GradualRolloutRandomStrategy
- RemoteAddressStrategy
- ApplicationHostnameStrategy
[Read more about activation strategies in the docs](https://docs.getunleash.io/user_guide/activation_strategy).
### Unleash context
In order to use some of the common activation strategies you must provide an
[unleash-context](https://docs.getunleash.io/user_guide/unleash_context).
This client SDK allows you to send in the unleash context as part of the `isEnabled` call:
```go
ctx := context.Context{
UserId: "123",
SessionId: "some-session-id",
RemoteAddress: "127.0.0.1",
}
unleash.IsEnabled("someToggle", unleash.WithContext(ctx))
```
### Caveat
This client uses go routines to report several events and doesn't drain the channel by default. So you need to either register a listener using `WithListener` or drain the channel "manually" (demonstrated in [this example](https://github.com/Unleash/unleash-client-go/blob/master/example_with_instance_test.go)).
### Feature Resolver
`FeatureResolver` is a `FeatureOption` used in `IsEnabled` via the `WithResolver`.
The `FeatureResolver` can be used to provide a feature instance in a different way than the client would normally retrieve it. This alternative resolver can be useful if you already have the feature instance and don't want to incur the cost to retrieve it from the repository.
An example of its usage is below:
```go
ctx := context.Context{
UserId: "123",
SessionId: "some-session-id",
RemoteAddress: "127.0.0.1",
}
// the FeatureResolver function that will be passed into WithResolver
resolver := func(featureName string) *api.Feature {
if featureName == "someToggle" {
// Feature being created in place for sake of example, but it is preferable an existing feature instance is used
return &api.Feature{
Name: "someToggle",
Description: "Example of someToggle",
Enabled: true,
Strategies: []api.Strategy{
{
Id: 1,
Name: "default",
},
},
CreatedAt: time.Time{},
Strategy: "default-strategy",
}
} else {
// it shouldn't reach this block because the name will match above "someToggle" for this example
return nil
}
}
// This would return true because the matched strategy is default and the feature is Enabled
unleash.IsEnabled("someToggle", unleash.WithContext(ctx), unleash.WithResolver(resolver))
```
## Development
## Steps to release
- Update the clientVersion in `client.go`
- Tag the repository with the new tag
## Adding client specifications
In order to make sure the unleash clients uphold their contract, we have defined a set of
client specifications that define this contract. These are used to make sure that each unleash client
at any time adhere to the contract, and define a set of functionality that is core to unleash. You can view
the [client specifications here](https://github.com/Unleash/client-specification).
In order to make the tests run please do the following steps.
```
// in repository root
// testdata is gitignored
mkdir testdata
cd testdata
git clone https://github.com/Unleash/client-specification.git
```
Requirements:
- make
- golint (go get -u golang.org/x/lint/golint)
Run tests:
make
Run lint check:
make lint
Run code-style checks:(currently failing)
make strict-check
Run race-tests:
make test-all