redisx

Documentation

Overview

Package redisx wraps https://github.com/joomcode/redispipe in an interface where rather than returning the result, you pass in a pointer to the variable you want to put the result into and it uses reflection to do that.

It is inspired by https://github.com/jmoiron/sqlx and https://github.com/mediocregopher/radix

Index

• type BaseSync
  • func (s BaseSync) Scanner(ctx context.Context, opts redis.ScanOpts) ScanIterator
• type InvalidInputError
  • func (e *InvalidInputError) Error() string
  • func (e *InvalidInputError) Retryable() int
• type Request
  • func Req(v interface{}, cmd string, args ...interface{}) Request
• type ResponseInputTypeError
  • func (e *ResponseInputTypeError) Error() string
  • func (e *ResponseInputTypeError) Retryable() int
• type ScanIterator
• type Sync
• type Syncx
  • func (s Syncx) Do(ctx context.Context, v interface{}, cmd string, args ...interface{}) error
  • func (s Syncx) Scanner(ctx context.Context, opts redis.ScanOpts) ScanIterator
  • func (s Syncx) Send(ctx context.Context, r Request) error
  • func (s Syncx) SendMany(ctx context.Context, reqs ...Request) []error
  • func (s Syncx) SendTransaction(ctx context.Context, reqs ...Request) error
• type UnexpectedResponseError
  • func (e *UnexpectedResponseError) Error() string
  • func (e *UnexpectedResponseError) Retryable() int

Types

type BaseSync

type BaseSync struct {
	redis.SyncCtx
}

BaseSync wraps SyncCtx from redispipe, replacing it's "Scanner" method with one that implements the definition in the SyncCtx interface defined in "redispipebp".

func (BaseSync) Scanner

func (s BaseSync) Scanner(ctx context.Context, opts redis.ScanOpts) ScanIterator

Scanner returns s.SyncCtx.Scanner as a ScanIterator rather than redis.SyncCtxIterator. This allows it to implement the Sync interface.

type InvalidInputError

type InvalidInputError struct {
	Message string
}

InvalidInputError is returned when the response input is invalid. This check happens after the command has already been processed by Redis while processing the input.

func (*InvalidInputError) Error

func (e *InvalidInputError) Error() string

Error implements the error interface.

func (*InvalidInputError) Retryable

func (e *InvalidInputError) Retryable() int

Retryable implements retrybp.RetryableError. InvalidInputError is never retryable.

type Request

type Request struct {
	redis.Request

	V interface{}
}

Request wraps the Request object from redispipe and also holds the response input passed in by the caller that we will use to set the response from Redis.

func Req

func Req(v interface{}, cmd string, args ...interface{}) Request

Req is a convenience function for creating new Request objects.

type ResponseInputTypeError

type ResponseInputTypeError struct {
	Cmd               string
	ResponseInputType reflect.Type
}

ResponseInputTypeError is returned when response input is valid but the command does not support the response input type passed in to it. This check happens after the command has already been processed by Redis while processing the input.

func (*ResponseInputTypeError) Error

func (e *ResponseInputTypeError) Error() string

Error implements the error interface.

func (*ResponseInputTypeError) Retryable

func (e *ResponseInputTypeError) Retryable() int

Retryable implements retrybp.RetryableError. ResponseInputTypeError is never retryable.

type ScanIterator

type ScanIterator interface {
	Next() ([]string, error)
}

ScanIterator iterates over the results of a SCAN call.

type Sync

type Sync interface {
	// Do executes a single redis command with the given args.
	Do(ctx context.Context, cmd string, args ...interface{}) interface{}

	// Send executes the given redis.Request.
	Send(ctx context.Context, req redis.Request) interface{}

	// SendMany executes all of the given requests in a single, non-transactional
	// pipeline.
	SendMany(ctx context.Context, reqs []redis.Request) []interface{}

	// SendTransaction executes al of the given requests in a single, transactional
	// pipeline.
	SendTransaction(ctx context.Context, reqs []redis.Request) ([]interface{}, error)

	// Scanner returns an iterator over the results from running a SCAN with the
	// given redis.ScanOpts.
	Scanner(ctx context.Context, opts redis.ScanOpts) ScanIterator
}

Sync is the interface used Syncx.

redispipe's SyncCtx almost implements this interface, the difference is its Scanner function returns a distinct type rather than a ScanIterator. BaseSync has been provided as an adapter around redis.SyncCtx to make it conform to the Sync interface defined here.

type Syncx

type Syncx struct {
	Sync Sync
}

Syncx is a wrapper around a Sync that provides an API that uses reflection to allow you to set the response from your redis command into a typed variable without having to manually cast it from "interface{}".

Methods no longer return an interface{}, instead they return only errors and you pass in a pointer to the value that you want to have the response put into.

The values that you can use as the "response" input vary depending on the command. You may also pass in 'nil' if you want to ignore any non-error results. In addition to errors, Redis commands return one of 4 types of responses:

1. Simple Strings: "*string" is the only type you can use as the response input.
2. Integers: "*int64" is the only type you can use as the response input.
3. Bulk strings: "*[]byte", the type returned by redispipe for these commands, is supported as a response input. In additon, you may use a "string" or "int64" and we will attempt to convert the "[]byte" response to that value. Note that this is done by converting it to a "string" first and, in the case of "int64", parsing it into an integer. You can also use "*string" or "*int64", to be able to represent null value.
4. Arrays: Arrays are the most flexible type returned by Redis as an array can contain elements of any of the types above. "[]interface{}" is the type that redispipe returns on these commands and is supported as a response input. Certain commands support more specific inputs though, specifically "*[]int64" or "*[][]byte" since they always return arrays that only contain a specific type.

Array Commands that support "*[][]byte":

• BLPOP
• BRPOP
• GEOHASH
• HKEYS
• HVALS
• KEYS
• LRANGE
• SDIFF
• SINTER
• SMEMBERS
• SPOPN
• SRANDMEMBERN
• SUNION
• XCLAIMJUSTID
• ZPOPMAX
• ZPOPMIN
• ZRANGE
• ZRANGEBYLEX
• ZRANGEBYSCORE
• ZREVRANGE
• ZREVRANGEBYLEX
• ZREVRANGEBYSCORE

Array Commands that support "*[]int64":

• BITFIELD
• SCRIPT EXISTS

In addition, some commands, specifically key/value commands, support Struct Scanning where you can pass in a pointer to an arbitrary struct and it will put the response values into the struct by mapping key values to field names. It also supports specifying keys using the "redisx" tag and fields with the tag "-" will be ignored. When mapping to field names, the mapping is case insensitive while tags are case sensitive. Fields in the struct that map to keys in the response must be one of "[]byte", "int64", or "string", depending on what you expect to be returned by that key, using other types will result in returning an error.

Array Commands that support Struct Scanning:

• HMGET
• MGET

func (Syncx) Do

func (s Syncx) Do(ctx context.Context, v interface{}, cmd string, args ...interface{}) error

Do is a convenience wrapper for s.Send. It does not use s.Sync.Do.

func (Syncx) Scanner

func (s Syncx) Scanner(ctx context.Context, opts redis.ScanOpts) ScanIterator

Scanner returns a ScanIterator from the underlying Sync.

func (Syncx) Send

func (s Syncx) Send(ctx context.Context, r Request) error

Send sends a single request to redis.

func (Syncx) SendMany

func (s Syncx) SendMany(ctx context.Context, reqs ...Request) []error

SendMany sends multiple requests to redis. It returns a slice of errors that is the same length as the number of requests passed to SendMany. The error at an index in the response is the error for the request at the same index. If there was no error for that individual request, then the entry in the response will be nil. These requests are not sent as a transaction, use SendTransaction if you wish to do that.

func (Syncx) SendTransaction

func (s Syncx) SendTransaction(ctx context.Context, reqs ...Request) error

SendTransaction sends multiple requests to redis in a single transaction. It returns a single error since a transaction either succeeds entirely or it fails. The response may be a errorsbp.Batch.

type UnexpectedResponseError

type UnexpectedResponseError struct {
	Message string
}

UnexpectedResponseError is returned when the response we received from redispipe does not match what we expect or is invalid. This check happens after the command has already been processed by Redis while processing the input.

You should not encounter this error and if you do, it likely indicates a bug in redisx or, less likely, redispipe. Please report this in https://github.com/reddit/baseplate.go/issues if you encounter it with any details.

func (*UnexpectedResponseError) Error

func (e *UnexpectedResponseError) Error() string

Error implements the error interface.

func (*UnexpectedResponseError) Retryable

func (e *UnexpectedResponseError) Retryable() int

Retryable implements retrybp.RetryableError. UnexpectedResponseError is never retryable.