Debian Codegraph @

client.go

raw
1 // Copyright 2012-present Oliver Eilhard. All rights reserved.
2 // Use of this source code is governed by a MIT-license.
3 // See http://olivere.mit-license.org/license.txt for details.
4
5 package elastic
6
7 import (
8 "bytes"
9 "context"
10 "encoding/json"
11 "fmt"
12 "log"
13 "net/http"
14 "net/http/httputil"
15 "net/url"
16 "os"
17 "regexp"
18 "strings"
19 "sync"
20 "time"
21
22 "github.com/pkg/errors"
23
24 "gopkg.in/olivere/elastic.v5/config"
25 )
26
27 const (
28 // Version is the current version of Elastic.
29 Version = "5.0.83"
30
31 // DefaultURL is the default endpoint of Elasticsearch on the local machine.
32 // It is used e.g. when initializing a new Client without a specific URL.
33 DefaultURL = "http://127.0.0.1:9200"
34
35 // DefaultScheme is the default protocol scheme to use when sniffing
36 // the Elasticsearch cluster.
37 DefaultScheme = "http"
38
39 // DefaultHealthcheckEnabled specifies if healthchecks are enabled by default.
40 DefaultHealthcheckEnabled = true
41
42 // DefaultHealthcheckTimeoutStartup is the time the healthcheck waits
43 // for a response from Elasticsearch on startup, i.e. when creating a
44 // client. After the client is started, a shorter timeout is commonly used
45 // (its default is specified in DefaultHealthcheckTimeout).
46 DefaultHealthcheckTimeoutStartup = 5 * time.Second
47
48 // DefaultHealthcheckTimeout specifies the time a running client waits for
49 // a response from Elasticsearch. Notice that the healthcheck timeout
50 // when a client is created is larger by default (see DefaultHealthcheckTimeoutStartup).
51 DefaultHealthcheckTimeout = 1 * time.Second
52
53 // DefaultHealthcheckInterval is the default interval between
54 // two health checks of the nodes in the cluster.
55 DefaultHealthcheckInterval = 60 * time.Second
56
57 // DefaultSnifferEnabled specifies if the sniffer is enabled by default.
58 DefaultSnifferEnabled = true
59
60 // DefaultSnifferInterval is the interval between two sniffing procedures,
61 // i.e. the lookup of all nodes in the cluster and their addition/removal
62 // from the list of actual connections.
63 DefaultSnifferInterval = 15 * time.Minute
64
65 // DefaultSnifferTimeoutStartup is the default timeout for the sniffing
66 // process that is initiated while creating a new client. For subsequent
67 // sniffing processes, DefaultSnifferTimeout is used (by default).
68 DefaultSnifferTimeoutStartup = 5 * time.Second
69
70 // DefaultSnifferTimeout is the default timeout after which the
71 // sniffing process times out. Notice that for the initial sniffing
72 // process, DefaultSnifferTimeoutStartup is used.
73 DefaultSnifferTimeout = 2 * time.Second
74
75 // DefaultSendGetBodyAs is the HTTP method to use when elastic is sending
76 // a GET request with a body.
77 DefaultSendGetBodyAs = "GET"
78
79 // DefaultGzipEnabled specifies if gzip compression is enabled by default.
80 DefaultGzipEnabled = false
81
82 // off is used to disable timeouts.
83 off = -1 * time.Second
84 )
85
86 var (
87 // ErrNoClient is raised when no Elasticsearch node is available.
88 ErrNoClient = errors.New("no Elasticsearch node available")
89
90 // ErrRetry is raised when a request cannot be executed after the configured
91 // number of retries.
92 ErrRetry = errors.New("cannot connect after several retries")
93
94 // ErrTimeout is raised when a request timed out, e.g. when WaitForStatus
95 // didn't return in time.
96 ErrTimeout = errors.New("timeout")
97
98 // noRetries is a retrier that does not retry.
99 noRetries = NewStopRetrier()
100 )
101
102 // ClientOptionFunc is a function that configures a Client.
103 // It is used in NewClient.
104 type ClientOptionFunc func(*Client) error
105
106 // Client is an Elasticsearch client. Create one by calling NewClient.
107 type Client struct {
108 c *http.Client // net/http Client to use for requests
109
110 connsMu sync.RWMutex // connsMu guards the next block
111 conns []*conn // all connections
112 cindex int // index into conns
113
114 mu sync.RWMutex // guards the next block
115 urls []string // set of URLs passed initially to the client
116 running bool // true if the client's background processes are running
117 errorlog Logger // error log for critical messages
118 infolog Logger // information log for e.g. response times
119 tracelog Logger // trace log for debugging
120 scheme string // http or https
121 healthcheckEnabled bool // healthchecks enabled or disabled
122 healthcheckTimeoutStartup time.Duration // time the healthcheck waits for a response from Elasticsearch on startup
123 healthcheckTimeout time.Duration // time the healthcheck waits for a response from Elasticsearch
124 healthcheckInterval time.Duration // interval between healthchecks
125 healthcheckStop chan bool // notify healthchecker to stop, and notify back
126 snifferEnabled bool // sniffer enabled or disabled
127 snifferTimeoutStartup time.Duration // time the sniffer waits for a response from nodes info API on startup
128 snifferTimeout time.Duration // time the sniffer waits for a response from nodes info API
129 snifferInterval time.Duration // interval between sniffing
130 snifferCallback SnifferCallback // callback to modify the sniffing decision
131 snifferStop chan bool // notify sniffer to stop, and notify back
132 decoder Decoder // used to decode data sent from Elasticsearch
133 basicAuth bool // indicates whether to send HTTP Basic Auth credentials
134 basicAuthUsername string // username for HTTP Basic Auth
135 basicAuthPassword string // password for HTTP Basic Auth
136 sendGetBodyAs string // override for when sending a GET with a body
137 requiredPlugins []string // list of required plugins
138 gzipEnabled bool // gzip compression enabled or disabled (default)
139 retrier Retrier // strategy for retries
140 }
141
142 // NewClient creates a new client to work with Elasticsearch.
143 //
144 // NewClient, by default, is meant to be long-lived and shared across
145 // your application. If you need a short-lived client, e.g. for request-scope,
146 // consider using NewSimpleClient instead.
147 //
148 // The caller can configure the new client by passing configuration options
149 // to the func.
150 //
151 // Example:
152 //
153 // client, err := elastic.NewClient(
154 // elastic.SetURL("http://127.0.0.1:9200", "http://127.0.0.1:9201"),
155 // elastic.SetBasicAuth("user", "secret"))
156 //
157 // If no URL is configured, Elastic uses DefaultURL by default.
158 //
159 // If the sniffer is enabled (the default), the new client then sniffes
160 // the cluster via the Nodes Info API
161 // (see https://www.elastic.co/guide/en/elasticsearch/reference/5.2/cluster-nodes-info.html#cluster-nodes-info).
162 // It uses the URLs specified by the caller. The caller is responsible
163 // to only pass a list of URLs of nodes that belong to the same cluster.
164 // This sniffing process is run on startup and periodically.
165 // Use SnifferInterval to set the interval between two sniffs (default is
166 // 15 minutes). In other words: By default, the client will find new nodes
167 // in the cluster and remove those that are no longer available every
168 // 15 minutes. Disable the sniffer by passing SetSniff(false) to NewClient.
169 //
170 // The list of nodes found in the sniffing process will be used to make
171 // connections to the REST API of Elasticsearch. These nodes are also
172 // periodically checked in a shorter time frame. This process is called
173 // a health check. By default, a health check is done every 60 seconds.
174 // You can set a shorter or longer interval by SetHealthcheckInterval.
175 // Disabling health checks is not recommended, but can be done by
176 // SetHealthcheck(false).
177 //
178 // Connections are automatically marked as dead or healthy while
179 // making requests to Elasticsearch. When a request fails, Elastic will
180 // call into the Retry strategy which can be specified with SetRetry.
181 // The Retry strategy is also responsible for handling backoff i.e. the time
182 // to wait before starting the next request. There are various standard
183 // backoff implementations, e.g. ExponentialBackoff or SimpleBackoff.
184 // Retries are disabled by default.
185 //
186 // If no HttpClient is configured, then http.DefaultClient is used.
187 // You can use your own http.Client with some http.Transport for
188 // advanced scenarios.
189 //
190 // An error is also returned when some configuration option is invalid or
191 // the new client cannot sniff the cluster (if enabled).
192 func NewClient(options ...ClientOptionFunc) (*Client, error) {
193 // Set up the client
194 c := &Client{
195 c: http.DefaultClient,
196 conns: make([]*conn, 0),
197 cindex: -1,
198 scheme: DefaultScheme,
199 decoder: &DefaultDecoder{},
200 healthcheckEnabled: DefaultHealthcheckEnabled,
201 healthcheckTimeoutStartup: DefaultHealthcheckTimeoutStartup,
202 healthcheckTimeout: DefaultHealthcheckTimeout,
203 healthcheckInterval: DefaultHealthcheckInterval,
204 healthcheckStop: make(chan bool),
205 snifferEnabled: DefaultSnifferEnabled,
206 snifferTimeoutStartup: DefaultSnifferTimeoutStartup,
207 snifferTimeout: DefaultSnifferTimeout,
208 snifferInterval: DefaultSnifferInterval,
209 snifferCallback: nopSnifferCallback,
210 snifferStop: make(chan bool),
211 sendGetBodyAs: DefaultSendGetBodyAs,
212 gzipEnabled: DefaultGzipEnabled,
213 retrier: noRetries, // no retries by default
214 }
215
216 // Run the options on it
217 for _, option := range options {
218 if err := option(c); err != nil {
219 return nil, err
220 }
221 }
222
223 // Use a default URL and normalize them
224 if len(c.urls) == 0 {
225 c.urls = []string{DefaultURL}
226 }
227 c.urls = canonicalize(c.urls...)
228
229 // If the URLs have auth info, use them here as an alternative to SetBasicAuth
230 if !c.basicAuth {
231 for _, urlStr := range c.urls {
232 u, err := url.Parse(urlStr)
233 if err == nil && u.User != nil {
234 c.basicAuth = true
235 c.basicAuthUsername = u.User.Username()
236 c.basicAuthPassword, _ = u.User.Password()
237 break
238 }
239 }
240 }
241
242 // Check if we can make a request to any of the specified URLs
243 if c.healthcheckEnabled {
244 if err := c.startupHealthcheck(c.healthcheckTimeoutStartup); err != nil {
245 return nil, err
246 }
247 }
248
249 if c.snifferEnabled {
250 // Sniff the cluster initially
251 if err := c.sniff(c.snifferTimeoutStartup); err != nil {
252 return nil, err
253 }
254 } else {
255 // Do not sniff the cluster initially. Use the provided URLs instead.
256 for _, url := range c.urls {
257 c.conns = append(c.conns, newConn(url, url))
258 }
259 }
260
261 if c.healthcheckEnabled {
262 // Perform an initial health check
263 c.healthcheck(c.healthcheckTimeoutStartup, true)
264 }
265 // Ensure that we have at least one connection available
266 if err := c.mustActiveConn(); err != nil {
267 return nil, err
268 }
269
270 // Check the required plugins
271 for _, plugin := range c.requiredPlugins {
272 found, err := c.HasPlugin(plugin)
273 if err != nil {
274 return nil, err
275 }
276 if !found {
277 return nil, fmt.Errorf("elastic: plugin %s not found", plugin)
278 }
279 }
280
281 if c.snifferEnabled {
282 go c.sniffer() // periodically update cluster information
283 }
284 if c.healthcheckEnabled {
285 go c.healthchecker() // start goroutine periodically ping all nodes of the cluster
286 }
287
288 c.mu.Lock()
289 c.running = true
290 c.mu.Unlock()
291
292 return c, nil
293 }
294
295 // NewClientFromConfig initializes a client from a configuration.
296 func NewClientFromConfig(cfg *config.Config) (*Client, error) {
297 var options []ClientOptionFunc
298 if cfg != nil {
299 if cfg.URL != "" {
300 options = append(options, SetURL(cfg.URL))
301 }
302 if cfg.Errorlog != "" {
303 f, err := os.OpenFile(cfg.Errorlog, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
304 if err != nil {
305 return nil, errors.Wrap(err, "unable to initialize error log")
306 }
307 l := log.New(f, "", 0)
308 options = append(options, SetErrorLog(l))
309 }
310 if cfg.Tracelog != "" {
311 f, err := os.OpenFile(cfg.Tracelog, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
312 if err != nil {
313 return nil, errors.Wrap(err, "unable to initialize trace log")
314 }
315 l := log.New(f, "", 0)
316 options = append(options, SetTraceLog(l))
317 }
318 if cfg.Infolog != "" {
319 f, err := os.OpenFile(cfg.Infolog, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
320 if err != nil {
321 return nil, errors.Wrap(err, "unable to initialize info log")
322 }
323 l := log.New(f, "", 0)
324 options = append(options, SetInfoLog(l))
325 }
326 if cfg.Username != "" || cfg.Password != "" {
327 options = append(options, SetBasicAuth(cfg.Username, cfg.Password))
328 }
329 if cfg.Sniff != nil {
330 options = append(options, SetSniff(*cfg.Sniff))
331 }
332 }
333 return NewClient(options...)
334 }
335
336 // NewSimpleClient creates a new short-lived Client that can be used in
337 // use cases where you need e.g. one client per request.
338 //
339 // While NewClient by default sets up e.g. periodic health checks
340 // and sniffing for new nodes in separate goroutines, NewSimpleClient does
341 // not and is meant as a simple replacement where you don't need all the
342 // heavy lifting of NewClient.
343 //
344 // NewSimpleClient does the following by default: First, all health checks
345 // are disabled, including timeouts and periodic checks. Second, sniffing
346 // is disabled, including timeouts and periodic checks. The number of retries
347 // is set to 1. NewSimpleClient also does not start any goroutines.
348 //
349 // Notice that you can still override settings by passing additional options,
350 // just like with NewClient.
351 func NewSimpleClient(options ...ClientOptionFunc) (*Client, error) {
352 c := &Client{
353 c: http.DefaultClient,
354 conns: make([]*conn, 0),
355 cindex: -1,
356 scheme: DefaultScheme,
357 decoder: &DefaultDecoder{},
358 healthcheckEnabled: false,
359 healthcheckTimeoutStartup: off,
360 healthcheckTimeout: off,
361 healthcheckInterval: off,
362 healthcheckStop: make(chan bool),
363 snifferEnabled: false,
364 snifferTimeoutStartup: off,
365 snifferTimeout: off,
366 snifferInterval: off,
367 snifferCallback: nopSnifferCallback,
368 snifferStop: make(chan bool),
369 sendGetBodyAs: DefaultSendGetBodyAs,
370 gzipEnabled: DefaultGzipEnabled,
371 retrier: noRetries, // no retries by default
372 }
373
374 // Run the options on it
375 for _, option := range options {
376 if err := option(c); err != nil {
377 return nil, err
378 }
379 }
380
381 // Use a default URL and normalize them
382 if len(c.urls) == 0 {
383 c.urls = []string{DefaultURL}
384 }
385 c.urls = canonicalize(c.urls...)
386
387 // If the URLs have auth info, use them here as an alternative to SetBasicAuth
388 if !c.basicAuth {
389 for _, urlStr := range c.urls {
390 u, err := url.Parse(urlStr)
391 if err == nil && u.User != nil {
392 c.basicAuth = true
393 c.basicAuthUsername = u.User.Username()
394 c.basicAuthPassword, _ = u.User.Password()
395 break
396 }
397 }
398 }
399
400 for _, url := range c.urls {
401 c.conns = append(c.conns, newConn(url, url))
402 }
403
404 // Ensure that we have at least one connection available
405 if err := c.mustActiveConn(); err != nil {
406 return nil, err
407 }
408
409 // Check the required plugins
410 for _, plugin := range c.requiredPlugins {
411 found, err := c.HasPlugin(plugin)
412 if err != nil {
413 return nil, err
414 }
415 if !found {
416 return nil, fmt.Errorf("elastic: plugin %s not found", plugin)
417 }
418 }
419
420 c.mu.Lock()
421 c.running = true
422 c.mu.Unlock()
423
424 return c, nil
425 }
426
427 // SetHttpClient can be used to specify the http.Client to use when making
428 // HTTP requests to Elasticsearch.
429 func SetHttpClient(httpClient *http.Client) ClientOptionFunc {
430 return func(c *Client) error {
431 if httpClient != nil {
432 c.c = httpClient
433 } else {
434 c.c = http.DefaultClient
435 }
436 return nil
437 }
438 }
439
440 // SetBasicAuth can be used to specify the HTTP Basic Auth credentials to
441 // use when making HTTP requests to Elasticsearch.
442 func SetBasicAuth(username, password string) ClientOptionFunc {
443 return func(c *Client) error {
444 c.basicAuthUsername = username
445 c.basicAuthPassword = password
446 c.basicAuth = c.basicAuthUsername != "" || c.basicAuthPassword != ""
447 return nil
448 }
449 }
450
451 // SetURL defines the URL endpoints of the Elasticsearch nodes. Notice that
452 // when sniffing is enabled, these URLs are used to initially sniff the
453 // cluster on startup.
454 func SetURL(urls ...string) ClientOptionFunc {
455 return func(c *Client) error {
456 switch len(urls) {
457 case 0:
458 c.urls = []string{DefaultURL}
459 default:
460 c.urls = urls
461 }
462 return nil
463 }
464 }
465
466 // SetScheme sets the HTTP scheme to look for when sniffing (http or https).
467 // This is http by default.
468 func SetScheme(scheme string) ClientOptionFunc {
469 return func(c *Client) error {
470 c.scheme = scheme
471 return nil
472 }
473 }
474
475 // SetSniff enables or disables the sniffer (enabled by default).
476 func SetSniff(enabled bool) ClientOptionFunc {
477 return func(c *Client) error {
478 c.snifferEnabled = enabled
479 return nil
480 }
481 }
482
483 // SetSnifferTimeoutStartup sets the timeout for the sniffer that is used
484 // when creating a new client. The default is 5 seconds. Notice that the
485 // timeout being used for subsequent sniffing processes is set with
486 // SetSnifferTimeout.
487 func SetSnifferTimeoutStartup(timeout time.Duration) ClientOptionFunc {
488 return func(c *Client) error {
489 c.snifferTimeoutStartup = timeout
490 return nil
491 }
492 }
493
494 // SetSnifferTimeout sets the timeout for the sniffer that finds the
495 // nodes in a cluster. The default is 2 seconds. Notice that the timeout
496 // used when creating a new client on startup is usually greater and can
497 // be set with SetSnifferTimeoutStartup.
498 func SetSnifferTimeout(timeout time.Duration) ClientOptionFunc {
499 return func(c *Client) error {
500 c.snifferTimeout = timeout
501 return nil
502 }
503 }
504
505 // SetSnifferInterval sets the interval between two sniffing processes.
506 // The default interval is 15 minutes.
507 func SetSnifferInterval(interval time.Duration) ClientOptionFunc {
508 return func(c *Client) error {
509 c.snifferInterval = interval
510 return nil
511 }
512 }
513
514 // SnifferCallback defines the protocol for sniffing decisions.
515 type SnifferCallback func(*NodesInfoNode) bool
516
517 // nopSnifferCallback is the default sniffer callback: It accepts
518 // all nodes the sniffer finds.
519 var nopSnifferCallback = func(*NodesInfoNode) bool { return true }
520
521 // SetSnifferCallback allows the caller to modify sniffer decisions.
522 // When setting the callback, the given SnifferCallback is called for
523 // each (healthy) node found during the sniffing process.
524 // If the callback returns false, the node is ignored: No requests
525 // are routed to it.
526 func SetSnifferCallback(f SnifferCallback) ClientOptionFunc {
527 return func(c *Client) error {
528 if f != nil {
529 c.snifferCallback = f
530 }
531 return nil
532 }
533 }
534
535 // SetHealthcheck enables or disables healthchecks (enabled by default).
536 func SetHealthcheck(enabled bool) ClientOptionFunc {
537 return func(c *Client) error {
538 c.healthcheckEnabled = enabled
539 return nil
540 }
541 }
542
543 // SetHealthcheckTimeoutStartup sets the timeout for the initial health check.
544 // The default timeout is 5 seconds (see DefaultHealthcheckTimeoutStartup).
545 // Notice that timeouts for subsequent health checks can be modified with
546 // SetHealthcheckTimeout.
547 func SetHealthcheckTimeoutStartup(timeout time.Duration) ClientOptionFunc {
548 return func(c *Client) error {
549 c.healthcheckTimeoutStartup = timeout
550 return nil
551 }
552 }
553
554 // SetHealthcheckTimeout sets the timeout for periodic health checks.
555 // The default timeout is 1 second (see DefaultHealthcheckTimeout).
556 // Notice that a different (usually larger) timeout is used for the initial
557 // healthcheck, which is initiated while creating a new client.
558 // The startup timeout can be modified with SetHealthcheckTimeoutStartup.
559 func SetHealthcheckTimeout(timeout time.Duration) ClientOptionFunc {
560 return func(c *Client) error {
561 c.healthcheckTimeout = timeout
562 return nil
563 }
564 }
565
566 // SetHealthcheckInterval sets the interval between two health checks.
567 // The default interval is 60 seconds.
568 func SetHealthcheckInterval(interval time.Duration) ClientOptionFunc {
569 return func(c *Client) error {
570 c.healthcheckInterval = interval
571 return nil
572 }
573 }
574
575 // SetMaxRetries sets the maximum number of retries before giving up when
576 // performing a HTTP request to Elasticsearch.
577 //
578 // Deprecated: Replace with a Retry implementation.
579 func SetMaxRetries(maxRetries int) ClientOptionFunc {
580 return func(c *Client) error {
581 if maxRetries < 0 {
582 return errors.New("MaxRetries must be greater than or equal to 0")
583 } else if maxRetries == 0 {
584 c.retrier = noRetries
585 } else {
586 // Create a Retrier that will wait for 100ms (+/- jitter) between requests.
587 // This resembles the old behavior with maxRetries.
588 ticks := make([]int, maxRetries)
589 for i := 0; i < len(ticks); i++ {
590 ticks[i] = 100
591 }
592 backoff := NewSimpleBackoff(ticks...)
593 c.retrier = NewBackoffRetrier(backoff)
594 }
595 return nil
596 }
597 }
598
599 // SetGzip enables or disables gzip compression (disabled by default).
600 func SetGzip(enabled bool) ClientOptionFunc {
601 return func(c *Client) error {
602 c.gzipEnabled = enabled
603 return nil
604 }
605 }
606
607 // SetDecoder sets the Decoder to use when decoding data from Elasticsearch.
608 // DefaultDecoder is used by default.
609 func SetDecoder(decoder Decoder) ClientOptionFunc {
610 return func(c *Client) error {
611 if decoder != nil {
612 c.decoder = decoder
613 } else {
614 c.decoder = &DefaultDecoder{}
615 }
616 return nil
617 }
618 }
619
620 // SetRequiredPlugins can be used to indicate that some plugins are required
621 // before a Client will be created.
622 func SetRequiredPlugins(plugins ...string) ClientOptionFunc {
623 return func(c *Client) error {
624 if c.requiredPlugins == nil {
625 c.requiredPlugins = make([]string, 0)
626 }
627 c.requiredPlugins = append(c.requiredPlugins, plugins...)
628 return nil
629 }
630 }
631
632 // SetErrorLog sets the logger for critical messages like nodes joining
633 // or leaving the cluster or failing requests. It is nil by default.
634 func SetErrorLog(logger Logger) ClientOptionFunc {
635 return func(c *Client) error {
636 c.errorlog = logger
637 return nil
638 }
639 }
640
641 // SetInfoLog sets the logger for informational messages, e.g. requests
642 // and their response times. It is nil by default.
643 func SetInfoLog(logger Logger) ClientOptionFunc {
644 return func(c *Client) error {
645 c.infolog = logger
646 return nil
647 }
648 }
649
650 // SetTraceLog specifies the log.Logger to use for output of HTTP requests
651 // and responses which is helpful during debugging. It is nil by default.
652 func SetTraceLog(logger Logger) ClientOptionFunc {
653 return func(c *Client) error {
654 c.tracelog = logger
655 return nil
656 }
657 }
658
659 // SetSendGetBodyAs specifies the HTTP method to use when sending a GET request
660 // with a body. It is GET by default.
661 func SetSendGetBodyAs(httpMethod string) ClientOptionFunc {
662 return func(c *Client) error {
663 c.sendGetBodyAs = httpMethod
664 return nil
665 }
666 }
667
668 // SetRetrier specifies the retry strategy that handles errors during
669 // HTTP request/response with Elasticsearch.
670 func SetRetrier(retrier Retrier) ClientOptionFunc {
671 return func(c *Client) error {
672 if retrier == nil {
673 retrier = noRetries // no retries by default
674 }
675 c.retrier = retrier
676 return nil
677 }
678 }
679
680 // String returns a string representation of the client status.
681 func (c *Client) String() string {
682 c.connsMu.Lock()
683 conns := c.conns
684 c.connsMu.Unlock()
685
686 var buf bytes.Buffer
687 for i, conn := range conns {
688 if i > 0 {
689 buf.WriteString(", ")
690 }
691 buf.WriteString(conn.String())
692 }
693 return buf.String()
694 }
695
696 // IsRunning returns true if the background processes of the client are
697 // running, false otherwise.
698 func (c *Client) IsRunning() bool {
699 c.mu.RLock()
700 defer c.mu.RUnlock()
701 return c.running
702 }
703
704 // Start starts the background processes like sniffing the cluster and
705 // periodic health checks. You don't need to run Start when creating a
706 // client with NewClient; the background processes are run by default.
707 //
708 // If the background processes are already running, this is a no-op.
709 func (c *Client) Start() {
710 c.mu.RLock()
711 if c.running {
712 c.mu.RUnlock()
713 return
714 }
715 c.mu.RUnlock()
716
717 if c.snifferEnabled {
718 go c.sniffer()
719 }
720 if c.healthcheckEnabled {
721 go c.healthchecker()
722 }
723
724 c.mu.Lock()
725 c.running = true
726 c.mu.Unlock()
727
728 c.infof("elastic: client started")
729 }
730
731 // Stop stops the background processes that the client is running,
732 // i.e. sniffing the cluster periodically and running health checks
733 // on the nodes.
734 //
735 // If the background processes are not running, this is a no-op.
736 func (c *Client) Stop() {
737 c.mu.RLock()
738 if !c.running {
739 c.mu.RUnlock()
740 return
741 }
742 c.mu.RUnlock()
743
744 if c.healthcheckEnabled {
745 c.healthcheckStop <- true
746 <-c.healthcheckStop
747 }
748
749 if c.snifferEnabled {
750 c.snifferStop <- true
751 <-c.snifferStop
752 }
753
754 c.mu.Lock()
755 c.running = false
756 c.mu.Unlock()
757
758 c.infof("elastic: client stopped")
759 }
760
761 // errorf logs to the error log.
762 func (c *Client) errorf(format string, args ...interface{}) {
763 if c.errorlog != nil {
764 c.errorlog.Printf(format, args...)
765 }
766 }
767
768 // infof logs informational messages.
769 func (c *Client) infof(format string, args ...interface{}) {
770 if c.infolog != nil {
771 c.infolog.Printf(format, args...)
772 }
773 }
774
775 // tracef logs to the trace log.
776 func (c *Client) tracef(format string, args ...interface{}) {
777 if c.tracelog != nil {
778 c.tracelog.Printf(format, args...)
779 }
780 }
781
782 // dumpRequest dumps the given HTTP request to the trace log.
783 func (c *Client) dumpRequest(r *http.Request) {
784 if c.tracelog != nil {
785 out, err := httputil.DumpRequestOut(r, true)
786 if err == nil {
787 c.tracef("%s\n", string(out))
788 }
789 }
790 }
791
792 // dumpResponse dumps the given HTTP response to the trace log.
793 func (c *Client) dumpResponse(resp *http.Response) {
794 if c.tracelog != nil {
795 out, err := httputil.DumpResponse(resp, true)
796 if err == nil {
797 c.tracef("%s\n", string(out))
798 }
799 }
800 }
801
802 // sniffer periodically runs sniff.
803 func (c *Client) sniffer() {
804 c.mu.RLock()
805 timeout := c.snifferTimeout
806 interval := c.snifferInterval
807 c.mu.RUnlock()
808
809 ticker := time.NewTicker(interval)
810 defer ticker.Stop()
811
812 for {
813 select {
814 case <-c.snifferStop:
815 // we are asked to stop, so we signal back that we're stopping now
816 c.snifferStop <- true
817 return
818 case <-ticker.C:
819 c.sniff(timeout)
820 }
821 }
822 }
823
824 // sniff uses the Node Info API to return the list of nodes in the cluster.
825 // It uses the list of URLs passed on startup plus the list of URLs found
826 // by the preceding sniffing process (if sniffing is enabled).
827 //
828 // If sniffing is disabled, this is a no-op.
829 func (c *Client) sniff(timeout time.Duration) error {
830 c.mu.RLock()
831 if !c.snifferEnabled {
832 c.mu.RUnlock()
833 return nil
834 }
835
836 // Use all available URLs provided to sniff the cluster.
837 var urls []string
838 urlsMap := make(map[string]bool)
839
840 // Add all URLs provided on startup
841 for _, url := range c.urls {
842 urlsMap[url] = true
843 urls = append(urls, url)
844 }
845 c.mu.RUnlock()
846
847 // Add all URLs found by sniffing
848 c.connsMu.RLock()
849 for _, conn := range c.conns {
850 if !conn.IsDead() {
851 url := conn.URL()
852 if _, found := urlsMap[url]; !found {
853 urls = append(urls, url)
854 }
855 }
856 }
857 c.connsMu.RUnlock()
858
859 if len(urls) == 0 {
860 return errors.Wrap(ErrNoClient, "no URLs found")
861 }
862
863 // Start sniffing on all found URLs
864 ch := make(chan []*conn, len(urls))
865
866 ctx, cancel := context.WithTimeout(context.Background(), timeout)
867 defer cancel()
868
869 for _, url := range urls {
870 go func(url string) { ch <- c.sniffNode(ctx, url) }(url)
871 }
872
873 // Wait for the results to come back, or the process times out.
874 for {
875 select {
876 case conns := <-ch:
877 if len(conns) > 0 {
878 c.updateConns(conns)
879 return nil
880 }
881 case <-ctx.Done():
882 // We get here if no cluster responds in time
883 return errors.Wrap(ErrNoClient, "sniff timeout")
884 }
885 }
886 }
887
888 // sniffNode sniffs a single node. This method is run as a goroutine
889 // in sniff. If successful, it returns the list of node URLs extracted
890 // from the result of calling Nodes Info API. Otherwise, an empty array
891 // is returned.
892 func (c *Client) sniffNode(ctx context.Context, url string) []*conn {
893 var nodes []*conn
894
895 // Call the Nodes Info API at /_nodes/http
896 req, err := NewRequest("GET", url+"/_nodes/http")
897 if err != nil {
898 return nodes
899 }
900
901 c.mu.RLock()
902 if c.basicAuth {
903 req.SetBasicAuth(c.basicAuthUsername, c.basicAuthPassword)
904 }
905 c.mu.RUnlock()
906
907 res, err := c.c.Do((*http.Request)(req).WithContext(ctx))
908 if err != nil {
909 return nodes
910 }
911 if res == nil {
912 return nodes
913 }
914
915 if res.Body != nil {
916 defer res.Body.Close()
917 }
918
919 var info NodesInfoResponse
920 if err := json.NewDecoder(res.Body).Decode(&info); err == nil {
921 if len(info.Nodes) > 0 {
922 for nodeID, node := range info.Nodes {
923 if c.snifferCallback(node) {
924 if node.HTTP != nil && len(node.HTTP.PublishAddress) > 0 {
925 url := c.extractHostname(c.scheme, node.HTTP.PublishAddress)
926 if url != "" {
927 nodes = append(nodes, newConn(nodeID, url))
928 }
929 }
930 }
931 }
932 }
933 }
934 return nodes
935 }
936
937 // reSniffHostAndPort is used to extract hostname and port from a result
938 // from a Nodes Info API (example: "inet[/127.0.0.1:9200]").
939 var reSniffHostAndPort = regexp.MustCompile(`\/([^:]*):([0-9]+)\]`)
940
941 func (c *Client) extractHostname(scheme, address string) string {
942 if strings.HasPrefix(address, "inet") {
943 m := reSniffHostAndPort.FindStringSubmatch(address)
944 if len(m) == 3 {
945 return fmt.Sprintf("%s://%s:%s", scheme, m[1], m[2])
946 }
947 }
948 s := address
949 if idx := strings.Index(s, "/"); idx >= 0 {
950 s = s[idx+1:]
951 }
952 if strings.Index(s, ":") < 0 {
953 return ""
954 }
955 return fmt.Sprintf("%s://%s", scheme, s)
956 }
957
958 // updateConns updates the clients' connections with new information
959 // gather by a sniff operation.
960 func (c *Client) updateConns(conns []*conn) {
961 c.connsMu.Lock()
962
963 // Build up new connections:
964 // If we find an existing connection, use that (including no. of failures etc.).
965 // If we find a new connection, add it.
966 var newConns []*conn
967 for _, conn := range conns {
968 var found bool
969 for _, oldConn := range c.conns {
970 if oldConn.NodeID() == conn.NodeID() {
971 // Take over the old connection
972 newConns = append(newConns, oldConn)
973 found = true
974 break
975 }
976 }
977 if !found {
978 // New connection didn't exist, so add it to our list of new conns.
979 c.infof("elastic: %s joined the cluster", conn.URL())
980 newConns = append(newConns, conn)
981 }
982 }
983
984 c.conns = newConns
985 c.cindex = -1
986 c.connsMu.Unlock()
987 }
988
989 // healthchecker periodically runs healthcheck.
990 func (c *Client) healthchecker() {
991 c.mu.RLock()
992 timeout := c.healthcheckTimeout
993 interval := c.healthcheckInterval
994 c.mu.RUnlock()
995
996 ticker := time.NewTicker(interval)
997 defer ticker.Stop()
998
999 for {
1000 select {
1001 case <-c.healthcheckStop:
1002 // we are asked to stop, so we signal back that we're stopping now
1003 c.healthcheckStop <- true
1004 return
1005 case <-ticker.C:
1006 c.healthcheck(timeout, false)
1007 }
1008 }
1009 }
1010
1011 // healthcheck does a health check on all nodes in the cluster. Depending on
1012 // the node state, it marks connections as dead, sets them alive etc.
1013 // If healthchecks are disabled and force is false, this is a no-op.
1014 // The timeout specifies how long to wait for a response from Elasticsearch.
1015 func (c *Client) healthcheck(timeout time.Duration, force bool) {
1016 c.mu.RLock()
1017 if !c.healthcheckEnabled && !force {
1018 c.mu.RUnlock()
1019 return
1020 }
1021 basicAuth := c.basicAuth
1022 basicAuthUsername := c.basicAuthUsername
1023 basicAuthPassword := c.basicAuthPassword
1024 c.mu.RUnlock()
1025
1026 c.connsMu.RLock()
1027 conns := c.conns
1028 c.connsMu.RUnlock()
1029
1030 for _, conn := range conns {
1031 // Run the HEAD request against ES with a timeout
1032 ctx, cancel := context.WithTimeout(context.Background(), timeout)
1033 defer cancel()
1034
1035 // Goroutine executes the HTTP request, returns an error and sets status
1036 var status int
1037 errc := make(chan error, 1)
1038 go func(url string) {
1039 req, err := NewRequest("HEAD", url)
1040 if err != nil {
1041 errc <- err
1042 return
1043 }
1044 if basicAuth {
1045 req.SetBasicAuth(basicAuthUsername, basicAuthPassword)
1046 }
1047 res, err := c.c.Do((*http.Request)(req).WithContext(ctx))
1048 if res != nil {
1049 status = res.StatusCode
1050 if res.Body != nil {
1051 res.Body.Close()
1052 }
1053 }
1054 errc <- err
1055 }(conn.URL())
1056
1057 // Wait for the Goroutine (or its timeout)
1058 select {
1059 case <-ctx.Done(): // timeout
1060 c.errorf("elastic: %s is dead", conn.URL())
1061 conn.MarkAsDead()
1062 case err := <-errc:
1063 if err != nil {
1064 c.errorf("elastic: %s is dead", conn.URL())
1065 conn.MarkAsDead()
1066 break
1067 }
1068 if status >= 200 && status < 300 {
1069 conn.MarkAsAlive()
1070 } else {
1071 conn.MarkAsDead()
1072 c.errorf("elastic: %s is dead [status=%d]", conn.URL(), status)
1073 }
1074 }
1075 }
1076 }
1077
1078 // startupHealthcheck is used at startup to check if the server is available
1079 // at all.
1080 func (c *Client) startupHealthcheck(timeout time.Duration) error {
1081 c.mu.Lock()
1082 urls := c.urls
1083 basicAuth := c.basicAuth
1084 basicAuthUsername := c.basicAuthUsername
1085 basicAuthPassword := c.basicAuthPassword
1086 c.mu.Unlock()
1087
1088 // If we don't get a connection after "timeout", we bail.
1089 var lastErr error
1090 start := time.Now()
1091 for {
1092 for _, url := range urls {
1093 req, err := http.NewRequest("HEAD", url, nil)
1094 if err != nil {
1095 return err
1096 }
1097 if basicAuth {
1098 req.SetBasicAuth(basicAuthUsername, basicAuthPassword)
1099 }
1100 ctx, cancel := context.WithTimeout(req.Context(), timeout)
1101 defer cancel()
1102 req = req.WithContext(ctx)
1103 res, err := c.c.Do(req)
1104 if err == nil && res != nil && res.StatusCode >= 200 && res.StatusCode < 300 {
1105 return nil
1106 } else if err != nil {
1107 lastErr = err
1108 }
1109 }
1110 time.Sleep(1 * time.Second)
1111 if time.Since(start) > timeout {
1112 break
1113 }
1114 }
1115 if lastErr != nil {
1116 return errors.Wrapf(ErrNoClient, "health check timeout: %v", lastErr)
1117 }
1118 return errors.Wrap(ErrNoClient, "health check timeout")
1119 }
1120
1121 // next returns the next available connection, or ErrNoClient.
1122 func (c *Client) next() (*conn, error) {
1123 // We do round-robin here.
1124 // TODO(oe) This should be a pluggable strategy, like the Selector in the official clients.
1125 c.connsMu.Lock()
1126 defer c.connsMu.Unlock()
1127
1128 i := 0
1129 numConns := len(c.conns)
1130 for {
1131 i++
1132 if i > numConns {
1133 break // we visited all conns: they all seem to be dead
1134 }
1135 c.cindex++
1136 if c.cindex >= numConns {
1137 c.cindex = 0
1138 }
1139 conn := c.conns[c.cindex]
1140 if !conn.IsDead() {
1141 return conn, nil
1142 }
1143 }
1144
1145 // We have a deadlock here: All nodes are marked as dead.
1146 // If sniffing is disabled, connections will never be marked alive again.
1147 // So we are marking them as alive--if sniffing is disabled.
1148 // They'll then be picked up in the next call to PerformRequest.
1149 if !c.snifferEnabled {
1150 c.errorf("elastic: all %d nodes marked as dead; resurrecting them to prevent deadlock", len(c.conns))
1151 for _, conn := range c.conns {
1152 conn.MarkAsAlive()
1153 }
1154 }
1155
1156 // We tried hard, but there is no node available
1157 return nil, errors.Wrap(ErrNoClient, "no available connection")
1158 }
1159
1160 // mustActiveConn returns nil if there is an active connection,
1161 // otherwise ErrNoClient is returned.
1162 func (c *Client) mustActiveConn() error {
1163 c.connsMu.Lock()
1164 defer c.connsMu.Unlock()
1165
1166 for _, c := range c.conns {
1167 if !c.IsDead() {
1168 return nil
1169 }
1170 }
1171 return errors.Wrap(ErrNoClient, "no active connection found")
1172 }
1173
1174 // -- PerformRequest --
1175
1176 // PerformRequestOptions must be passed into PerformRequest.
1177 type PerformRequestOptions struct {
1178 Method string
1179 Path string
1180 Params url.Values
1181 Body interface{}
1182 ContentType string
1183 IgnoreErrors []int
1184 Retrier Retrier
1185 }
1186
1187 // PerformRequest does a HTTP request to Elasticsearch.
1188 // See PerformRequestWithContentType for details.
1189 func (c *Client) PerformRequest(ctx context.Context, method, path string, params url.Values, body interface{}, ignoreErrors ...int) (*Response, error) {
1190 return c.PerformRequestWithOptions(ctx, PerformRequestOptions{
1191 Method: method,
1192 Path: path,
1193 Params: params,
1194 Body: body,
1195 ContentType: "application/json",
1196 IgnoreErrors: ignoreErrors,
1197 })
1198 }
1199
1200 // PerformRequestWithContentType executes a HTTP request with a specific content type.
1201 // It returns a response (which might be nil) and an error on failure.
1202 //
1203 // Optionally, a list of HTTP error codes to ignore can be passed.
1204 // This is necessary for services that expect e.g. HTTP status 404 as a
1205 // valid outcome (Exists, IndicesExists, IndicesTypeExists).
1206 func (c *Client) PerformRequestWithContentType(ctx context.Context, method, path string, params url.Values, body interface{}, contentType string, ignoreErrors ...int) (*Response, error) {
1207 return c.PerformRequestWithOptions(ctx, PerformRequestOptions{
1208 Method: method,
1209 Path: path,
1210 Params: params,
1211 Body: body,
1212 ContentType: contentType,
1213 IgnoreErrors: ignoreErrors,
1214 })
1215 }
1216
1217 // PerformRequestWithOptions executes a HTTP request with the specified options.
1218 // It returns a response (which might be nil) and an error on failure.
1219 func (c *Client) PerformRequestWithOptions(ctx context.Context, opt PerformRequestOptions) (*Response, error) {
1220 start := time.Now().UTC()
1221
1222 c.mu.RLock()
1223 timeout := c.healthcheckTimeout
1224 basicAuth := c.basicAuth
1225 basicAuthUsername := c.basicAuthUsername
1226 basicAuthPassword := c.basicAuthPassword
1227 sendGetBodyAs := c.sendGetBodyAs
1228 gzipEnabled := c.gzipEnabled
1229 retrier := c.retrier
1230 if opt.Retrier != nil {
1231 retrier = opt.Retrier
1232 }
1233 c.mu.RUnlock()
1234
1235 var err error
1236 var conn *conn
1237 var req *Request
1238 var resp *Response
1239 var retried bool
1240 var n int
1241
1242 // Change method if sendGetBodyAs is specified.
1243 if opt.Method == "GET" && opt.Body != nil && sendGetBodyAs != "GET" {
1244 opt.Method = sendGetBodyAs
1245 }
1246
1247 for {
1248 pathWithParams := opt.Path
1249 if len(opt.Params) > 0 {
1250 pathWithParams += "?" + opt.Params.Encode()
1251 }
1252
1253 // Get a connection
1254 conn, err = c.next()
1255 if errors.Cause(err) == ErrNoClient {
1256 n++
1257 if !retried {
1258 // Force a healtcheck as all connections seem to be dead.
1259 c.healthcheck(timeout, false)
1260 }
1261 wait, ok, rerr := retrier.Retry(ctx, n, nil, nil, err)
1262 if rerr != nil {
1263 return nil, rerr
1264 }
1265 if !ok {
1266 return nil, err
1267 }
1268 retried = true
1269 time.Sleep(wait)
1270 continue // try again
1271 }
1272 if err != nil {
1273 c.errorf("elastic: cannot get connection from pool")
1274 return nil, err
1275 }
1276
1277 req, err = NewRequest(opt.Method, conn.URL()+pathWithParams)
1278 if err != nil {
1279 c.errorf("elastic: cannot create request for %s %s: %v", strings.ToUpper(opt.Method), conn.URL()+pathWithParams, err)
1280 return nil, err
1281 }
1282
1283 if basicAuth {
1284 req.SetBasicAuth(basicAuthUsername, basicAuthPassword)
1285 }
1286 if opt.ContentType != "" {
1287 req.Header.Set("Content-Type", opt.ContentType)
1288 }
1289
1290 // Set body
1291 if opt.Body != nil {
1292 err = req.SetBody(opt.Body, gzipEnabled)
1293 if err != nil {
1294 c.errorf("elastic: couldn't set body %+v for request: %v", opt.Body, err)
1295 return nil, err
1296 }
1297 }
1298
1299 // Tracing
1300 c.dumpRequest((*http.Request)(req))
1301
1302 // Get response
1303 res, err := c.c.Do((*http.Request)(req).WithContext(ctx))
1304 if IsContextErr(err) {
1305 // Proceed, but don't mark the node as dead
1306 return nil, err
1307 }
1308 if err != nil {
1309 n++
1310 wait, ok, rerr := retrier.Retry(ctx, n, (*http.Request)(req), res, err)
1311 if rerr != nil {
1312 c.errorf("elastic: %s is dead", conn.URL())
1313 conn.MarkAsDead()
1314 return nil, rerr
1315 }
1316 if !ok {
1317 c.errorf("elastic: %s is dead", conn.URL())
1318 conn.MarkAsDead()
1319 return nil, err
1320 }
1321 retried = true
1322 time.Sleep(wait)
1323 continue // try again
1324 }
1325 if res.Body != nil {
1326 defer res.Body.Close()
1327 }
1328
1329 // Tracing
1330 c.dumpResponse(res)
1331
1332 // Check for errors
1333 if err := checkResponse((*http.Request)(req), res, opt.IgnoreErrors...); err != nil {
1334 // No retry if request succeeded
1335 // We still try to return a response.
1336 resp, _ = c.newResponse(res)
1337 return resp, err
1338 }
1339
1340 // We successfully made a request with this connection
1341 conn.MarkAsHealthy()
1342
1343 resp, err = c.newResponse(res)
1344 if err != nil {
1345 return nil, err
1346 }
1347
1348 break
1349 }
1350
1351 duration := time.Now().UTC().Sub(start)
1352 c.infof("%s %s [status:%d, request:%.3fs]",
1353 strings.ToUpper(opt.Method),
1354 req.URL,
1355 resp.StatusCode,
1356 float64(int64(duration/time.Millisecond))/1000)
1357
1358 return resp, nil
1359 }
1360
1361 // -- Document APIs --
1362
1363 // Index a document.
1364 func (c *Client) Index() *IndexService {
1365 return NewIndexService(c)
1366 }
1367
1368 // Get a document.
1369 func (c *Client) Get() *GetService {
1370 return NewGetService(c)
1371 }
1372
1373 // MultiGet retrieves multiple documents in one roundtrip.
1374 func (c *Client) MultiGet() *MgetService {
1375 return NewMgetService(c)
1376 }
1377
1378 // Mget retrieves multiple documents in one roundtrip.
1379 func (c *Client) Mget() *MgetService {
1380 return NewMgetService(c)
1381 }
1382
1383 // Delete a document.
1384 func (c *Client) Delete() *DeleteService {
1385 return NewDeleteService(c)
1386 }
1387
1388 // DeleteByQuery deletes documents as found by a query.
1389 func (c *Client) DeleteByQuery(indices ...string) *DeleteByQueryService {
1390 return NewDeleteByQueryService(c).Index(indices...)
1391 }
1392
1393 // Update a document.
1394 func (c *Client) Update() *UpdateService {
1395 return NewUpdateService(c)
1396 }
1397
1398 // UpdateByQuery performs an update on a set of documents.
1399 func (c *Client) UpdateByQuery(indices ...string) *UpdateByQueryService {
1400 return NewUpdateByQueryService(c).Index(indices...)
1401 }
1402
1403 // Bulk is the entry point to mass insert/update/delete documents.
1404 func (c *Client) Bulk() *BulkService {
1405 return NewBulkService(c)
1406 }
1407
1408 // BulkProcessor allows setting up a concurrent processor of bulk requests.
1409 func (c *Client) BulkProcessor() *BulkProcessorService {
1410 return NewBulkProcessorService(c)
1411 }
1412
1413 // Reindex copies data from a source index into a destination index.
1414 //
1415 // See https://www.elastic.co/guide/en/elasticsearch/reference/5.2/docs-reindex.html
1416 // for details on the Reindex API.
1417 func (c *Client) Reindex() *ReindexService {
1418 return NewReindexService(c)
1419 }
1420
1421 // TermVectors returns information and statistics on terms in the fields
1422 // of a particular document.
1423 func (c *Client) TermVectors(index, typ string) *TermvectorsService {
1424 builder := NewTermvectorsService(c)
1425 builder = builder.Index(index).Type(typ)
1426 return builder
1427 }
1428
1429 // MultiTermVectors returns information and statistics on terms in the fields
1430 // of multiple documents.
1431 func (c *Client) MultiTermVectors() *MultiTermvectorService {
1432 return NewMultiTermvectorService(c)
1433 }
1434
1435 // -- Search APIs --
1436
1437 // Search is the entry point for searches.
1438 func (c *Client) Search(indices ...string) *SearchService {
1439 return NewSearchService(c).Index(indices...)
1440 }
1441
1442 // Suggest returns a service to return suggestions.
1443 func (c *Client) Suggest(indices ...string) *SuggestService {
1444 return NewSuggestService(c).Index(indices...)
1445 }
1446
1447 // MultiSearch is the entry point for multi searches.
1448 func (c *Client) MultiSearch() *MultiSearchService {
1449 return NewMultiSearchService(c)
1450 }
1451
1452 // Count documents.
1453 func (c *Client) Count(indices ...string) *CountService {
1454 return NewCountService(c).Index(indices...)
1455 }
1456
1457 // Explain computes a score explanation for a query and a specific document.
1458 func (c *Client) Explain(index, typ, id string) *ExplainService {
1459 return NewExplainService(c).Index(index).Type(typ).Id(id)
1460 }
1461
1462 // TODO Search Template
1463 // TODO Search Exists API
1464
1465 // Validate allows a user to validate a potentially expensive query without executing it.
1466 func (c *Client) Validate(indices ...string) *ValidateService {
1467 return NewValidateService(c).Index(indices...)
1468 }
1469
1470 // SearchShards returns statistical information about nodes and shards.
1471 func (c *Client) SearchShards(indices ...string) *SearchShardsService {
1472 return NewSearchShardsService(c).Index(indices...)
1473 }
1474
1475 // FieldCaps returns statistical information about fields in indices.
1476 func (c *Client) FieldCaps(indices ...string) *FieldCapsService {
1477 return NewFieldCapsService(c).Index(indices...)
1478 }
1479
1480 // FieldStats returns statistical information about fields in indices.
1481 func (c *Client) FieldStats(indices ...string) *FieldStatsService {
1482 return NewFieldStatsService(c).Index(indices...)
1483 }
1484
1485 // Exists checks if a document exists.
1486 func (c *Client) Exists() *ExistsService {
1487 return NewExistsService(c)
1488 }
1489
1490 // Scroll through documents. Use this to efficiently scroll through results
1491 // while returning the results to a client.
1492 func (c *Client) Scroll(indices ...string) *ScrollService {
1493 return NewScrollService(c).Index(indices...)
1494 }
1495
1496 // ClearScroll can be used to clear search contexts manually.
1497 func (c *Client) ClearScroll(scrollIds ...string) *ClearScrollService {
1498 return NewClearScrollService(c).ScrollId(scrollIds...)
1499 }
1500
1501 // -- Indices APIs --
1502
1503 // CreateIndex returns a service to create a new index.
1504 func (c *Client) CreateIndex(name string) *IndicesCreateService {
1505 return NewIndicesCreateService(c).Index(name)
1506 }
1507
1508 // DeleteIndex returns a service to delete an index.
1509 func (c *Client) DeleteIndex(indices ...string) *IndicesDeleteService {
1510 return NewIndicesDeleteService(c).Index(indices)
1511 }
1512
1513 // IndexExists allows to check if an index exists.
1514 func (c *Client) IndexExists(indices ...string) *IndicesExistsService {
1515 return NewIndicesExistsService(c).Index(indices)
1516 }
1517
1518 // ShrinkIndex returns a service to shrink one index into another.
1519 func (c *Client) ShrinkIndex(source, target string) *IndicesShrinkService {
1520 return NewIndicesShrinkService(c).Source(source).Target(target)
1521 }
1522
1523 // RolloverIndex rolls an alias over to a new index when the existing index
1524 // is considered to be too large or too old.
1525 func (c *Client) RolloverIndex(alias string) *IndicesRolloverService {
1526 return NewIndicesRolloverService(c).Alias(alias)
1527 }
1528
1529 // TypeExists allows to check if one or more types exist in one or more indices.
1530 func (c *Client) TypeExists() *IndicesExistsTypeService {
1531 return NewIndicesExistsTypeService(c)
1532 }
1533
1534 // IndexStats provides statistics on different operations happining
1535 // in one or more indices.
1536 func (c *Client) IndexStats(indices ...string) *IndicesStatsService {
1537 return NewIndicesStatsService(c).Index(indices...)
1538 }
1539
1540 // OpenIndex opens an index.
1541 func (c *Client) OpenIndex(name string) *IndicesOpenService {
1542 return NewIndicesOpenService(c).Index(name)
1543 }
1544
1545 // CloseIndex closes an index.
1546 func (c *Client) CloseIndex(name string) *IndicesCloseService {
1547 return NewIndicesCloseService(c).Index(name)
1548 }
1549
1550 // IndexGet retrieves information about one or more indices.
1551 // IndexGet is only available for Elasticsearch 1.4 or later.
1552 func (c *Client) IndexGet(indices ...string) *IndicesGetService {
1553 return NewIndicesGetService(c).Index(indices...)
1554 }
1555
1556 // IndexGetSettings retrieves settings of all, one or more indices.
1557 func (c *Client) IndexGetSettings(indices ...string) *IndicesGetSettingsService {
1558 return NewIndicesGetSettingsService(c).Index(indices...)
1559 }
1560
1561 // IndexPutSettings sets settings for all, one or more indices.
1562 func (c *Client) IndexPutSettings(indices ...string) *IndicesPutSettingsService {
1563 return NewIndicesPutSettingsService(c).Index(indices...)
1564 }
1565
1566 // IndexSegments retrieves low level segment information for all, one or more indices.
1567 func (c *Client) IndexSegments(indices ...string) *IndicesSegmentsService {
1568 return NewIndicesSegmentsService(c).Index(indices...)
1569 }
1570
1571 // IndexAnalyze performs the analysis process on a text and returns the
1572 // token breakdown of the text.
1573 func (c *Client) IndexAnalyze() *IndicesAnalyzeService {
1574 return NewIndicesAnalyzeService(c)
1575 }
1576
1577 // Forcemerge optimizes one or more indices.
1578 // It replaces the deprecated Optimize API.
1579 func (c *Client) Forcemerge(indices ...string) *IndicesForcemergeService {
1580 return NewIndicesForcemergeService(c).Index(indices...)
1581 }
1582
1583 // Refresh asks Elasticsearch to refresh one or more indices.
1584 func (c *Client) Refresh(indices ...string) *RefreshService {
1585 return NewRefreshService(c).Index(indices...)
1586 }
1587
1588 // Flush asks Elasticsearch to free memory from the index and
1589 // flush data to disk.
1590 func (c *Client) Flush(indices ...string) *IndicesFlushService {
1591 return NewIndicesFlushService(c).Index(indices...)
1592 }
1593
1594 // Alias enables the caller to add and/or remove aliases.
1595 func (c *Client) Alias() *AliasService {
1596 return NewAliasService(c)
1597 }
1598
1599 // Aliases returns aliases by index name(s).
1600 func (c *Client) Aliases() *AliasesService {
1601 return NewAliasesService(c)
1602 }
1603
1604 // GetTemplate gets a search template.
1605 // Use IndexXXXTemplate funcs to manage index templates.
1606 func (c *Client) GetTemplate() *GetTemplateService {
1607 return NewGetTemplateService(c)
1608 }
1609
1610 // PutTemplate creates or updates a search template.
1611 // Use IndexXXXTemplate funcs to manage index templates.
1612 func (c *Client) PutTemplate() *PutTemplateService {
1613 return NewPutTemplateService(c)
1614 }
1615
1616 // DeleteTemplate deletes a search template.
1617 // Use IndexXXXTemplate funcs to manage index templates.
1618 func (c *Client) DeleteTemplate() *DeleteTemplateService {
1619 return NewDeleteTemplateService(c)
1620 }
1621
1622 // IndexGetTemplate gets an index template.
1623 // Use XXXTemplate funcs to manage search templates.
1624 func (c *Client) IndexGetTemplate(names ...string) *IndicesGetTemplateService {
1625 return NewIndicesGetTemplateService(c).Name(names...)
1626 }
1627
1628 // IndexTemplateExists gets check if an index template exists.
1629 // Use XXXTemplate funcs to manage search templates.
1630 func (c *Client) IndexTemplateExists(name string) *IndicesExistsTemplateService {
1631 return NewIndicesExistsTemplateService(c).Name(name)
1632 }
1633
1634 // IndexPutTemplate creates or updates an index template.
1635 // Use XXXTemplate funcs to manage search templates.
1636 func (c *Client) IndexPutTemplate(name string) *IndicesPutTemplateService {
1637 return NewIndicesPutTemplateService(c).Name(name)
1638 }
1639
1640 // IndexDeleteTemplate deletes an index template.
1641 // Use XXXTemplate funcs to manage search templates.
1642 func (c *Client) IndexDeleteTemplate(name string) *IndicesDeleteTemplateService {
1643 return NewIndicesDeleteTemplateService(c).Name(name)
1644 }
1645
1646 // GetMapping gets a mapping.
1647 func (c *Client) GetMapping() *IndicesGetMappingService {
1648 return NewIndicesGetMappingService(c)
1649 }
1650
1651 // PutMapping registers a mapping.
1652 func (c *Client) PutMapping() *IndicesPutMappingService {
1653 return NewIndicesPutMappingService(c)
1654 }
1655
1656 // GetFieldMapping gets mapping for fields.
1657 func (c *Client) GetFieldMapping() *IndicesGetFieldMappingService {
1658 return NewIndicesGetFieldMappingService(c)
1659 }
1660
1661 // -- cat APIs --
1662
1663 // TODO cat aliases
1664 // TODO cat allocation
1665 // TODO cat count
1666 // TODO cat fielddata
1667 // TODO cat health
1668 // TODO cat indices
1669 // TODO cat master
1670 // TODO cat nodes
1671 // TODO cat pending tasks
1672 // TODO cat plugins
1673 // TODO cat recovery
1674 // TODO cat thread pool
1675 // TODO cat shards
1676 // TODO cat segments
1677
1678 // -- Ingest APIs --
1679
1680 // IngestPutPipeline adds pipelines and updates existing pipelines in
1681 // the cluster.
1682 func (c *Client) IngestPutPipeline(id string) *IngestPutPipelineService {
1683 return NewIngestPutPipelineService(c).Id(id)
1684 }
1685
1686 // IngestGetPipeline returns pipelines based on ID.
1687 func (c *Client) IngestGetPipeline(ids ...string) *IngestGetPipelineService {
1688 return NewIngestGetPipelineService(c).Id(ids...)
1689 }
1690
1691 // IngestDeletePipeline deletes a pipeline by ID.
1692 func (c *Client) IngestDeletePipeline(id string) *IngestDeletePipelineService {
1693 return NewIngestDeletePipelineService(c).Id(id)
1694 }
1695
1696 // IngestSimulatePipeline executes a specific pipeline against the set of
1697 // documents provided in the body of the request.
1698 func (c *Client) IngestSimulatePipeline() *IngestSimulatePipelineService {
1699 return NewIngestSimulatePipelineService(c)
1700 }
1701
1702 // -- Cluster APIs --
1703
1704 // ClusterHealth retrieves the health of the cluster.
1705 func (c *Client) ClusterHealth() *ClusterHealthService {
1706 return NewClusterHealthService(c)
1707 }
1708
1709 // ClusterState retrieves the state of the cluster.
1710 func (c *Client) ClusterState() *ClusterStateService {
1711 return NewClusterStateService(c)
1712 }
1713
1714 // ClusterStats retrieves cluster statistics.
1715 func (c *Client) ClusterStats() *ClusterStatsService {
1716 return NewClusterStatsService(c)
1717 }
1718
1719 // NodesInfo retrieves one or more or all of the cluster nodes information.
1720 func (c *Client) NodesInfo() *NodesInfoService {
1721 return NewNodesInfoService(c)
1722 }
1723
1724 // NodesStats retrieves one or more or all of the cluster nodes statistics.
1725 func (c *Client) NodesStats() *NodesStatsService {
1726 return NewNodesStatsService(c)
1727 }
1728
1729 // TasksCancel cancels tasks running on the specified nodes.
1730 func (c *Client) TasksCancel() *TasksCancelService {
1731 return NewTasksCancelService(c)
1732 }
1733
1734 // TasksList retrieves the list of tasks running on the specified nodes.
1735 func (c *Client) TasksList() *TasksListService {
1736 return NewTasksListService(c)
1737 }
1738
1739 // TasksGetTask retrieves a task running on the cluster.
1740 func (c *Client) TasksGetTask() *TasksGetTaskService {
1741 return NewTasksGetTaskService(c)
1742 }
1743
1744 // TODO Pending cluster tasks
1745 // TODO Cluster Reroute
1746 // TODO Cluster Update Settings
1747 // TODO Nodes Stats
1748 // TODO Nodes hot_threads
1749
1750 // -- Snapshot and Restore --
1751
1752 // TODO Snapshot Delete
1753 // TODO Snapshot Get
1754 // TODO Snapshot Restore
1755 // TODO Snapshot Status
1756
1757 // SnapshotCreate creates a snapshot.
1758 func (c *Client) SnapshotCreate(repository string, snapshot string) *SnapshotCreateService {
1759 return NewSnapshotCreateService(c).Repository(repository).Snapshot(snapshot)
1760 }
1761
1762 // SnapshotCreateRepository creates or updates a snapshot repository.
1763 func (c *Client) SnapshotCreateRepository(repository string) *SnapshotCreateRepositoryService {
1764 return NewSnapshotCreateRepositoryService(c).Repository(repository)
1765 }
1766
1767 // SnapshotDeleteRepository deletes a snapshot repository.
1768 func (c *Client) SnapshotDeleteRepository(repositories ...string) *SnapshotDeleteRepositoryService {
1769 return NewSnapshotDeleteRepositoryService(c).Repository(repositories...)
1770 }
1771
1772 // SnapshotGetRepository gets a snapshot repository.
1773 func (c *Client) SnapshotGetRepository(repositories ...string) *SnapshotGetRepositoryService {
1774 return NewSnapshotGetRepositoryService(c).Repository(repositories...)
1775 }
1776
1777 // SnapshotVerifyRepository verifies a snapshot repository.
1778 func (c *Client) SnapshotVerifyRepository(repository string) *SnapshotVerifyRepositoryService {
1779 return NewSnapshotVerifyRepositoryService(c).Repository(repository)
1780 }
1781
1782 // -- Helpers and shortcuts --
1783
1784 // ElasticsearchVersion returns the version number of Elasticsearch
1785 // running on the given URL.
1786 func (c *Client) ElasticsearchVersion(url string) (string, error) {
1787 res, _, err := c.Ping(url).Do(context.Background())
1788 if err != nil {
1789 return "", err
1790 }
1791 return res.Version.Number, nil
1792 }
1793
1794 // IndexNames returns the names of all indices in the cluster.
1795 func (c *Client) IndexNames() ([]string, error) {
1796 res, err := c.IndexGetSettings().Index("_all").Do(context.Background())
1797 if err != nil {
1798 return nil, err
1799 }
1800 var names []string
1801 for name := range res {
1802 names = append(names, name)
1803 }
1804 return names, nil
1805 }
1806
1807 // Ping checks if a given node in a cluster exists and (optionally)
1808 // returns some basic information about the Elasticsearch server,
1809 // e.g. the Elasticsearch version number.
1810 //
1811 // Notice that you need to specify a URL here explicitly.
1812 func (c *Client) Ping(url string) *PingService {
1813 return NewPingService(c).URL(url)
1814 }
1815
1816 // WaitForStatus waits for the cluster to have the given status.
1817 // This is a shortcut method for the ClusterHealth service.
1818 //
1819 // WaitForStatus waits for the specified timeout, e.g. "10s".
1820 // If the cluster will have the given state within the timeout, nil is returned.
1821 // If the request timed out, ErrTimeout is returned.
1822 func (c *Client) WaitForStatus(status string, timeout string) error {
1823 health, err := c.ClusterHealth().WaitForStatus(status).Timeout(timeout).Do(context.Background())
1824 if err != nil {
1825 return err
1826 }
1827 if health.TimedOut {
1828 return ErrTimeout
1829 }
1830 return nil
1831 }
1832
1833 // WaitForGreenStatus waits for the cluster to have the "green" status.
1834 // See WaitForStatus for more details.
1835 func (c *Client) WaitForGreenStatus(timeout string) error {
1836 return c.WaitForStatus("green", timeout)
1837 }
1838
1839 // WaitForYellowStatus waits for the cluster to have the "yellow" status.
1840 // See WaitForStatus for more details.
1841 func (c *Client) WaitForYellowStatus(timeout string) error {
1842 return c.WaitForStatus("yellow", timeout)
1843 }