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 93// } else if err == grpc.ErrClientConnClosing { 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// 106package clientv3 107