| Scott Baker | eee8dd8 | 2019-09-24 12:52:34 -0700 | [diff] [blame] | 1 | // Copyright 2016 The etcd Authors |
| 2 | // |
| 3 | // Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | // you may not use this file except in compliance with the License. |
| 5 | // You may obtain a copy of the License at |
| 6 | // |
| 7 | // http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | // |
| 9 | // Unless required by applicable law or agreed to in writing, software |
| 10 | // distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | // See the License for the specific language governing permissions and |
| 13 | // limitations under the License. |
| 14 | |
| 15 | // Package clientv3 implements the official Go etcd client for v3. |
| 16 | // |
| 17 | // Create client using `clientv3.New`: |
| 18 | // |
| 19 | // // expect dial time-out on ipv4 blackhole |
| 20 | // _, err := clientv3.New(clientv3.Config{ |
| 21 | // Endpoints: []string{"http://254.0.0.1:12345"}, |
| 22 | // DialTimeout: 2 * time.Second, |
| 23 | // }) |
| 24 | // |
| 25 | // // etcd clientv3 >= v3.2.10, grpc/grpc-go >= v1.7.3 |
| 26 | // if err == context.DeadlineExceeded { |
| 27 | // // handle errors |
| 28 | // } |
| 29 | // |
| 30 | // // etcd clientv3 <= v3.2.9, grpc/grpc-go <= v1.2.1 |
| 31 | // if err == grpc.ErrClientConnTimeout { |
| 32 | // // handle errors |
| 33 | // } |
| 34 | // |
| 35 | // cli, err := clientv3.New(clientv3.Config{ |
| 36 | // Endpoints: []string{"localhost:2379", "localhost:22379", "localhost:32379"}, |
| 37 | // DialTimeout: 5 * time.Second, |
| 38 | // }) |
| 39 | // if err != nil { |
| 40 | // // handle error! |
| 41 | // } |
| 42 | // defer cli.Close() |
| 43 | // |
| 44 | // Make sure to close the client after using it. If the client is not closed, the |
| 45 | // connection will have leaky goroutines. |
| 46 | // |
| 47 | // To specify a client request timeout, wrap the context with context.WithTimeout: |
| 48 | // |
| 49 | // ctx, cancel := context.WithTimeout(context.Background(), timeout) |
| 50 | // resp, err := kvc.Put(ctx, "sample_key", "sample_value") |
| 51 | // cancel() |
| 52 | // if err != nil { |
| 53 | // // handle error! |
| 54 | // } |
| 55 | // // use the response |
| 56 | // |
| 57 | // The Client has internal state (watchers and leases), so Clients should be reused instead of created as needed. |
| 58 | // Clients are safe for concurrent use by multiple goroutines. |
| 59 | // |
| 60 | // etcd client returns 3 types of errors: |
| 61 | // |
| 62 | // 1. context error: canceled or deadline exceeded. |
| 63 | // 2. gRPC status error: e.g. when clock drifts in server-side before client's context deadline exceeded. |
| 64 | // 3. gRPC error: see https://github.com/etcd-io/etcd/blob/master/etcdserver/api/v3rpc/rpctypes/error.go |
| 65 | // |
| 66 | // Here is the example code to handle client errors: |
| 67 | // |
| 68 | // resp, err := kvc.Put(ctx, "", "") |
| 69 | // if err != nil { |
| 70 | // if err == context.Canceled { |
| 71 | // // ctx is canceled by another routine |
| 72 | // } else if err == context.DeadlineExceeded { |
| 73 | // // ctx is attached with a deadline and it exceeded |
| 74 | // } else if err == rpctypes.ErrEmptyKey { |
| 75 | // // client-side error: key is not provided |
| 76 | // } else if ev, ok := status.FromError(err); ok { |
| 77 | // code := ev.Code() |
| 78 | // if code == codes.DeadlineExceeded { |
| 79 | // // server-side context might have timed-out first (due to clock skew) |
| 80 | // // while original client-side context is not timed-out yet |
| 81 | // } |
| 82 | // } else { |
| 83 | // // bad cluster endpoints, which are not etcd servers |
| 84 | // } |
| 85 | // } |
| 86 | // |
| 87 | // go func() { cli.Close() }() |
| 88 | // _, err := kvc.Get(ctx, "a") |
| 89 | // if err != nil { |
| 90 | // // with etcd clientv3 <= v3.3 |
| 91 | // if err == context.Canceled { |
| 92 | // // grpc balancer calls 'Get' with an inflight client.Close |
| Scott Baker | 611f6bd | 2019-10-18 13:45:19 -0700 | [diff] [blame] | 93 | // } else if err == grpc.ErrClientConnClosing { // <= gRCP v1.7.x |
| Scott Baker | eee8dd8 | 2019-09-24 12:52:34 -0700 | [diff] [blame] | 94 | // // grpc balancer calls 'Get' after client.Close. |
| 95 | // } |
| 96 | // // with etcd clientv3 >= v3.4 |
| 97 | // if clientv3.IsConnCanceled(err) { |
| 98 | // // gRPC client connection is closed |
| 99 | // } |
| 100 | // } |
| 101 | // |
| 102 | // The grpc load balancer is registered statically and is shared across etcd clients. |
| 103 | // To enable detailed load balancer logging, set the ETCD_CLIENT_DEBUG environment |
| 104 | // variable. E.g. "ETCD_CLIENT_DEBUG=1". |
| 105 | // |
| 106 | package clientv3 |