estransport

Documentation

Overview

Package estransport provides the transport layer for the Elasticsearch client.

It is automatically included in the client provided by the github.com/elastic/go-elasticsearch package and is not intended for direct use: to configure the client, use the elasticsearch.Config struct.

The default HTTP transport of the client is http.Transport; use the Transport option to customize it; see the _examples/configuration.go and _examples/customization.go files in this repository for information.

The package will automatically retry requests on network-related errors, and on specific response status codes (by default 502, 503, 504). Use the RetryOnStatus option to customize the list. The transport will not retry a timeout network error, unless enabled by setting EnableRetryOnTimeout to true.

Use the MaxRetries option to configure the number of retries, and set DisableRetry to true to disable the retry behaviour altogether.

By default, the retry will be performed without any delay; to configure a backoff interval, implement the RetryBackoff option function; see an example in the package unit tests for information.

When multiple addresses are passed in configuration, the package will use them in a round-robin fashion, and will keep track of live and dead nodes. The status of dead nodes is checked periodically.

To customize the node selection behaviour, provide a Selector implementation in the configuration. To replace the connection pool entirely, provide a custom ConnectionPool implementation via the ConnectionPoolFunc option.

The package defines the Logger interface for logging information about request and response. It comes with several bundled loggers for logging in text and JSON.

Use the EnableDebugLogger option to enable the debugging logger for connection management.

Use the EnableMetrics option to enable metric collection and export.

Index

• Constants
• type Client
  • func New(cfg Config) (*Client, error)
  • func (c *Client) DiscoverNodes() error
  • func (c *Client) Metrics() (Metrics, error)
  • func (c *Client) Perform(req *http.Request) (*http.Response, error)
  • func (c *Client) URLs() []*url.URL
• type ColorLogger
  • func (l *ColorLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, ...) error
  • func (l *ColorLogger) RequestBodyEnabled() bool
  • func (l *ColorLogger) ResponseBodyEnabled() bool
• type Config
• type Connection
  • func (c *Connection) String() string
• type ConnectionMetric
  • func (cm ConnectionMetric) String() string
• type ConnectionPool
  • func NewConnectionPool(conns []*Connection, selector Selector) (ConnectionPool, error)
• type CurlLogger
  • func (l *CurlLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, ...) error
  • func (l *CurlLogger) RequestBodyEnabled() bool
  • func (l *CurlLogger) ResponseBodyEnabled() bool
• type DebuggingLogger
• type Discoverable
• type Interface
• type JSONLogger
  • func (l *JSONLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, ...) error
  • func (l *JSONLogger) RequestBodyEnabled() bool
  • func (l *JSONLogger) ResponseBodyEnabled() bool
• type Logger
• type Measurable
• type Metrics
  • func (m Metrics) String() string
• type Selector
• type TextLogger
  • func (l *TextLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, ...) error
  • func (l *TextLogger) RequestBodyEnabled() bool
  • func (l *TextLogger) ResponseBodyEnabled() bool

Constants

const HeaderClientMeta = "x-elastic-client-meta"

HeaderClientMeta Key for the HTTP Header related to telemetry data sent with each request to Elasticsearch.

const (
	// Version returns the package version as a string.
	Version = version.Client
)

Types

type Client

type Client struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Client represents the HTTP client.

func New

func New(cfg Config) (*Client, error)

New creates new transport client.

http.DefaultTransport will be used if no transport is passed in the configuration.

func (*Client) DiscoverNodes

func (c *Client) DiscoverNodes() error

DiscoverNodes reloads the client connections by fetching information from the cluster.

func (*Client) Metrics

func (c *Client) Metrics() (Metrics, error)

Metrics returns the transport metrics.

func (*Client) Perform

func (c *Client) Perform(req *http.Request) (*http.Response, error)

Perform executes the request and returns a response or error.

func (*Client) URLs

func (c *Client) URLs() []*url.URL

URLs returns a list of transport URLs.

type ColorLogger

type ColorLogger struct {
	Output             io.Writer
	EnableRequestBody  bool
	EnableResponseBody bool
}

ColorLogger prints the log message in a terminal-optimized plain text.

func (*ColorLogger) LogRoundTrip

func (l *ColorLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, dur time.Duration) error

LogRoundTrip prints the information about request and response.

func (*ColorLogger) RequestBodyEnabled

func (l *ColorLogger) RequestBodyEnabled() bool

RequestBodyEnabled returns true when the request body should be logged.

func (*ColorLogger) ResponseBodyEnabled

func (l *ColorLogger) ResponseBodyEnabled() bool

ResponseBodyEnabled returns true when the response body should be logged.

type Config

type Config struct {
	URLs         []*url.URL
	Username     string
	Password     string
	APIKey       string
	ServiceToken string

	Header http.Header
	CACert []byte

	RetryOnStatus        []int
	DisableRetry         bool
	EnableRetryOnTimeout bool
	MaxRetries           int
	RetryBackoff         func(attempt int) time.Duration

	CompressRequestBody bool

	EnableMetrics     bool
	EnableDebugLogger bool

	DisableMetaHeader bool

	DiscoverNodesInterval time.Duration

	Transport http.RoundTripper
	Logger    Logger
	Selector  Selector

	ConnectionPoolFunc func([]*Connection, Selector) ConnectionPool
}

Config represents the configuration of HTTP client.

type Connection

type Connection struct {
	sync.Mutex

	URL       *url.URL
	IsDead    bool
	DeadSince time.Time
	Failures  int

	ID         string
	Name       string
	Roles      []string
	Attributes map[string]interface{}
}

Connection represents a connection to a node.

func (*Connection) String

func (c *Connection) String() string

String returns a readable connection representation.

type ConnectionMetric

type ConnectionMetric struct {
	URL       string     `json:"url"`
	Failures  int        `json:"failures,omitempty"`
	IsDead    bool       `json:"dead,omitempty"`
	DeadSince *time.Time `json:"dead_since,omitempty"`

	Meta struct {
		ID    string   `json:"id"`
		Name  string   `json:"name"`
		Roles []string `json:"roles"`
	} `json:"meta"`
}

ConnectionMetric represents metric information for a connection.

func (ConnectionMetric) String

func (cm ConnectionMetric) String() string

String returns the connection information as a string.

type ConnectionPool

type ConnectionPool interface {
	Next() (*Connection, error)  // Next returns the next available connection.
	OnSuccess(*Connection) error // OnSuccess reports that the connection was successful.
	OnFailure(*Connection) error // OnFailure reports that the connection failed.
	URLs() []*url.URL            // URLs returns the list of URLs of available connections.
}

ConnectionPool defines the interface for the connection pool.

func NewConnectionPool

func NewConnectionPool(conns []*Connection, selector Selector) (ConnectionPool, error)

NewConnectionPool creates and returns a default connection pool.

type CurlLogger

type CurlLogger struct {
	Output             io.Writer
	EnableRequestBody  bool
	EnableResponseBody bool
}

CurlLogger prints the log message as a runnable curl command.

func (*CurlLogger) LogRoundTrip

func (l *CurlLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, dur time.Duration) error

LogRoundTrip prints the information about request and response.

func (*CurlLogger) RequestBodyEnabled

func (l *CurlLogger) RequestBodyEnabled() bool

RequestBodyEnabled returns true when the request body should be logged.

func (*CurlLogger) ResponseBodyEnabled

func (l *CurlLogger) ResponseBodyEnabled() bool

ResponseBodyEnabled returns true when the response body should be logged.

type DebuggingLogger

type DebuggingLogger interface {
	Log(a ...interface{}) error
	Logf(format string, a ...interface{}) error
}

DebuggingLogger defines the interface for a debugging logger.

type Discoverable

type Discoverable interface {
	DiscoverNodes() error
}

Discoverable defines the interface for transports supporting node discovery.

type Interface

type Interface interface {
	Perform(*http.Request) (*http.Response, error)
}

Interface defines the interface for HTTP client.

type JSONLogger

type JSONLogger struct {
	Output             io.Writer
	EnableRequestBody  bool
	EnableResponseBody bool
}

JSONLogger prints the log message as JSON.

func (*JSONLogger) LogRoundTrip

func (l *JSONLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, dur time.Duration) error

LogRoundTrip prints the information about request and response.

func (*JSONLogger) RequestBodyEnabled

func (l *JSONLogger) RequestBodyEnabled() bool

RequestBodyEnabled returns true when the request body should be logged.

func (*JSONLogger) ResponseBodyEnabled

func (l *JSONLogger) ResponseBodyEnabled() bool

ResponseBodyEnabled returns true when the response body should be logged.

type Logger

type Logger interface {
	// LogRoundTrip should not modify the request or response, except for consuming and closing the body.
	// Implementations have to check for nil values in request and response.
	LogRoundTrip(*http.Request, *http.Response, error, time.Time, time.Duration) error
	// RequestBodyEnabled makes the client pass a copy of request body to the logger.
	RequestBodyEnabled() bool
	// ResponseBodyEnabled makes the client pass a copy of response body to the logger.
	ResponseBodyEnabled() bool
}

Logger defines an interface for logging request and response.

type Measurable

type Measurable interface {
	Metrics() (Metrics, error)
}

Measurable defines the interface for transports supporting metrics.

type Metrics

type Metrics struct {
	Requests  int         `json:"requests"`
	Failures  int         `json:"failures"`
	Responses map[int]int `json:"responses"`

	Connections []fmt.Stringer `json:"connections"`
}

Metrics represents the transport metrics.

func (Metrics) String

func (m Metrics) String() string

String returns the metrics as a string.

type Selector

type Selector interface {
	Select([]*Connection) (*Connection, error)
}

Selector defines the interface for selecting connections from the pool.

type TextLogger

type TextLogger struct {
	Output             io.Writer
	EnableRequestBody  bool
	EnableResponseBody bool
}

TextLogger prints the log message in plain text.

func (*TextLogger) LogRoundTrip

func (l *TextLogger) LogRoundTrip(req *http.Request, res *http.Response, err error, start time.Time, dur time.Duration) error

LogRoundTrip prints the information about request and response.

func (*TextLogger) RequestBodyEnabled

func (l *TextLogger) RequestBodyEnabled() bool

RequestBodyEnabled returns true when the request body should be logged.

func (*TextLogger) ResponseBodyEnabled

func (l *TextLogger) ResponseBodyEnabled() bool

ResponseBodyEnabled returns true when the response body should be logged.