Documentation
¶
Index ¶
Constants ¶
const DefaultDialKeepAlive = 30 * time.Second
DefaultDialKeepAlive is used when no HTTPClient is provided to control the keep-alive duration for an active connection.
const DefaultDialTimeout = 5 * time.Second
DefaultDialTimeout is used when no HTTPClient is provided to control the timeout for establishing a new connection.
const DefaultMaxIdleConnsPerHost = 1
DefaultMaxIdleConnsPerHost is used when no HTTPClient is provided to control how many idle connections to keep alive per host.
const DefaultQueryTimeout = 30 * time.Second
DefaultQueryTimeout is used when no HTTPClient is provided to control the duration a query will remain in flight prior to automatic cancellation.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CachingClient ¶
type CachingClient struct {
// contains filtered or unexported fields
}
Client attempts to resolve range queries to a list of strings or an error, and stores them in an in-memory cache for quick repeated lookups.
func (*CachingClient) Close ¶
func (cc *CachingClient) Close() error
Close releases all memory and go-routines used by the Simple swarm. If during instantiation, checkVersionPeriodicty was greater than the zero-value for time.Duration, this method may block while completing any in progress updates due to `%version` changes.
func (*CachingClient) Query ¶
func (cc *CachingClient) Query(expression string) ([]string, error)
Query returns the response of the query, first checking in the TTL cache, then by actually sending a query to one or more of the configured range servers.
If the response includes a RangeException header, it returns ErrRangeException. If the status code is not okay, it returns ErrStatusNotOK. Finally, if it cannot parse the lines in the response body, it returns ErrParseException.
lines, err := querier.Query("%someQuery")
if err != nil {
fmt.Fprintf(os.Stderr, "ERROR: %s", err)
os.Exit(1)
}
for _, line := range lines {
fmt.Println(line)
}
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client attempts to resolve range queries to a list of strings or an error.
func (*Client) Close ¶
Close cleans up resources held by Client. Calling Query method after Close will result in a panic.
func (*Client) Query ¶
Query sends the specified expression to one or more of the configured range servers, and converts a non-error result into a list of strings.
If the response includes a RangeException header, it returns ErrRangeException. If the status code is not okay, it returns ErrStatusNotOK. Finally, if it cannot parse the lines in the response body, it returns ErrParseException.
lines, err := querier.Query("%someQuery")
if err != nil {
fmt.Fprintf(os.Stderr, "ERROR: %s", err)
os.Exit(1)
}
for _, line := range lines {
fmt.Println(line)
}
type Configurator ¶
type Configurator struct {
// HTTPClient allows the caller to specify a specially configured
// http.Client instance to use for all queries. When none is provided, a
// client will be created using the default timeouts.
HTTPClient *http.Client
// RetryCallback is predicate function that tests whether query should be
// retried for a given error. Leave nil to retry all errors.
RetryCallback func(error) bool
// RetryCount is number of query retries to be issued if query returns
// error. Leave 0 to never retry query errors.
RetryCount int
// RetryPause is the amount of time to wait before retrying the query.
RetryPause time.Duration
// Servers is slice of range server address strings. Must contain at least
// one string.
Servers []string
// TTL is duration of time to cache query responses. Leave 0 to not cache
// responses. When a value is older than its TTL, it becomes stale. When a
// key is queried for a value that is stale, an asynchronous routine
// attempts to lookup the new value, while the existing value is immediately
// returned to the user. TTL, TTE, and CheckVersionPeriodicity work
// together to prevent frequently needlessly asking servers for information
// that is still current while preventing heap build-up on clients.
TTL time.Duration
// TTE is duration of time before cached response is no longer able to be
// served, even if attempts to fetch new value repeatedly fail. This value
// should be large if your application needs to still operate even when
// range servers are down. A zero-value for this implies that values never
// expire and can continue to be served. TTL, TTE, and
// CheckVersionPeriodicity work together to prevent frequently needlessly
// asking servers for information that is still current while preventing
// heap build-up on clients.
TTE time.Duration
// CheckVersionPeriodicity is the amount of time between checking the range
// `%version` key. If your range server returns the epoch seconds of the
// time the data set became active when given the `%version` query, using
// this option is much better than using just TTL and TTE. After the
// specified period of time the CachingClient will query the range server's
// `%version` key, and if greater than the value discovered during the
// previous check, schedules an asynchronous refresh of all keys last
// requested by the client less than the amount of time specified by the TTL
// from the new version epoch. In other words, say key A was last requested
// at time 300, and key B was last requested at time 360. If the version
// comes back as 400, and the TTL is 60, then key A will be deleted and B
// will be refreshed. It makes no sense for CheckVersionPeriodicity to be a
// non-zero value when TTL and TTE are both zero-values.
CheckVersionPeriodicity time.Duration
}
Configurator provides a way to list the range server addresses, and a way to override defaults when creating new http.Client instances.
type ErrParseException ¶
type ErrParseException struct {
Err error
}
ErrParseException is returned by Client.Query method when an error occurs while reading the io.ReadCloser from the response.
func (ErrParseException) Error ¶
func (err ErrParseException) Error() string
type ErrRangeException ¶
type ErrRangeException struct {
Message string
}
ErrRangeException is returned when the response headers includes 'RangeException'.
func (ErrRangeException) Error ¶
func (err ErrRangeException) Error() string
type ErrStatusNotOK ¶
ErrStatusNotOK is returned when the response status code is not Ok.
func (ErrStatusNotOK) Error ¶
func (err ErrStatusNotOK) Error() string
type Querier ¶
Querier is the interface implemented by a structure that allows key-value lookups, where keys are strings and values are slices of strings.
func NewQuerier ¶
func NewQuerier(config *Configurator) (Querier, error)
NewQuerier returns a new instance that sends queries to one or more range servers. The provided Config not only provides a way of listing one or more range servers, but also allows specification of optional retry-on-failure feature and optional TTL cache that memoizes range query responses.
func main() {
servers := []string{"range1.example.com", "range2.example.com", "range3.example.com"}
config := &gorange.Config{
RetryCount: len(servers),
RetryPause: 5 * time.Second,
Servers: servers,
CheckVersionPeriodicity: 15 * time.Second,
TTL: 30 * time.Second,
TTE: 15 * time.Minute,
}
// create a range querier; could list additional servers or include other options as well
querier, err := gorange.NewQuerier(config)
if err != nil {
fmt.Fprintf(os.Stderr, "%s", err)
os.Exit(1)
}
// must invoke Close method when finished using to prevent resource leakage
defer func() { _ = querier.Close() }()
}
Source Files