Documentation ¶
Overview ¶
Package memcached binary protocol packet formats and constants.
Index ¶
- Constants
- Variables
- type AppendMode
- type Client
- func (c *Client) Append(appendMode AppendMode, key string, data []byte) (_ *Response, err error)
- func (c *Client) CloseAllConns()
- func (c *Client) CloseAvailableConnsInAllShardPools(numOfClose int) int
- func (c *Client) Delete(key string) (_ *Response, err error)
- func (c *Client) Delta(deltaMode DeltaMode, key string, delta, initial uint64, exp uint32) (newValue uint64, err error)
- func (c *Client) FlushAll(exp uint32) (err error)
- func (c *Client) Get(key string) (_ *Response, err error)
- func (c *Client) MultiDelete(keys []string) (err error)
- func (c *Client) MultiGet(keys []string) (_ map[string][]byte, err error)
- func (c *Client) MultiStore(storeMode StoreMode, items map[string][]byte, exp uint32) (err error)
- func (c *Client) Store(storeMode StoreMode, key string, exp uint32, body []byte) (_ *Response, err error)
- type ConnectTimeoutError
- type DeltaMode
- type Memcached
- type OpCode
- type Option
- func WithAuthentication(user, pass string) Option
- func WithCustomHashRing(hr *consistenthash.HashRing) Option
- func WithDisableLogger() Option
- func WithDisableMemcachedDiagnostic() Option
- func WithDisableNodeProvider() Option
- func WithDisableRefreshConnsInPool() Option
- func WithMaxIdleConns(num int) Option
- func WithPeriodForNodeHealthCheck(t time.Duration) Option
- func WithPeriodForRebuildingNodes(t time.Duration) Option
- func WithTimeout(tm time.Duration) Option
- type Request
- type Response
- func (r *Response) Bytes() []byte
- func (r *Response) Error() string
- func (r *Response) HeaderBytes() []byte
- func (r *Response) Receive(rd io.Reader, hdrBytes []byte) (int, error)
- func (r *Response) Size() int
- func (r Response) String() string
- func (r *Response) Transmit(w io.Writer) (n int, err error)
- type Status
- type StoreMode
Constants ¶
const ( REQ_MAGIC = 0x80 RES_MAGIC = 0x81 )
const ( GET = OpCode(0x00) SET = OpCode(0x01) ADD = OpCode(0x02) REPLACE = OpCode(0x03) DELETE = OpCode(0x04) INCREMENT = OpCode(0x05) DECREMENT = OpCode(0x06) QUIT = OpCode(0x07) FLUSH = OpCode(0x08) GETQ = OpCode(0x09) NOOP = OpCode(0x0a) VERSION = OpCode(0x0b) GETK = OpCode(0x0c) GETKQ = OpCode(0x0d) APPEND = OpCode(0x0e) PREPEND = OpCode(0x0f) STAT = OpCode(0x10) SETQ = OpCode(0x11) ADDQ = OpCode(0x12) REPLACEQ = OpCode(0x13) DELETEQ = OpCode(0x14) INCREMENTQ = OpCode(0x15) DECREMENTQ = OpCode(0x16) QUITQ = OpCode(0x17) FLUSHQ = OpCode(0x18) APPENDQ = OpCode(0x19) PREPENDQ = OpCode(0x1a) SASL_LIST_MECHS = OpCode(0x20) SASL_AUTH = OpCode(0x21) SASL_STEP = OpCode(0x22) )
const ( // SUCCESS - Successful operation. SUCCESS = Status(0x00) // KEY_ENOENT - Key not found. KEY_ENOENT = Status(0x01) // KEY_EEXISTS -Key already exists. KEY_EEXISTS = Status(0x02) // E2BIG - Data size exceeds limit. E2BIG = Status(0x03) // EINVAL - Invalid arguments or operation parameters. EINVAL = Status(0x04) // NOT_STORED - Operation was not performed because the data was not stored. NOT_STORED = Status(0x05) // DELTA_BADVAL - Invalid value specified for increment/decrement. DELTA_BADVAL = Status(0x06) // AUTHFAIL - Authentication required / Not Successful. AUTHFAIL = Status(0x20) // FURTHER_AUTH - Further authentication steps required. FURTHER_AUTH = Status(0x21) // UNKNOWN_COMMAND - Unknown command. UNKNOWN_COMMAND = Status(0x81) // ENOMEM - Insufficient memory for the operation. ENOMEM = Status(0x82) // TMPFAIL - Temporary failure, the operation cannot be performed at the moment. TMPFAIL = Status(0x86) // UNKNOWN_STATUS is not a Memcached status UNKNOWN_STATUS = Status(0xffff) )
const ( // HDR_LEN is a number of bytes in a binary protocol header. HDR_LEN = 24 BODY_LEN = 128 )
const ( // DefaultTimeout is the default socket read/write timeout. DefaultTimeout = 500 * time.Millisecond // DefaultMaxIdleConns is the default maximum number of idle connections // kept for any single address. DefaultMaxIdleConns = 100 // DefaultNodeHealthCheckPeriod is the default time period for start check available nods DefaultNodeHealthCheckPeriod = 15 * time.Second // DefaultRebuildingNodePeriod is the default time period for rebuilds the nodes in hash ring using freshly discovered DefaultRebuildingNodePeriod = 15 * time.Second // DefaultRetryCountForConn is a default number of connection retries before return i/o timeout error DefaultRetryCountForConn = uint8(3) // DefaultOfNumberConnsToDestroyPerRBPeriod is number of connections in pool whose needed close in every rebuild node cycle DefaultOfNumberConnsToDestroyPerRBPeriod = 1 // DefaultSocketPoolingTimeout Amount of time to acquire socket from pool DefaultSocketPoolingTimeout = 50 * time.Millisecond )
const ( // MaxBodyLen a maximum reasonable body length to expect. // Anything larger than this will result in an error. MaxBodyLen = int(22 * 1e6) // 22 MB BUF_LEN = 256 )
const (
SaslMechanism = "PLAIN"
)
Variables ¶
var ( // ErrCacheMiss means that a Get failed because the item wasn't present. ErrCacheMiss = errors.New("gomemcached: cache miss") // ErrCASConflict means that a CompareAndSwap call failed due to the // cached value being modified between the Get and the CompareAndSwap. // If the cached value was simply evicted rather than replaced, // ErrNotStored will be returned instead. ErrCASConflict = errors.New("gomemcached: compare-and-swap conflict") // ErrNotStored means that a conditional write operation (i.e. Add or // CompareAndSwap) failed because the condition was not satisfied. ErrNotStored = errors.New("gomemcached: item not stored") // ErrServerError means that a server error occurred. ErrServerError = errors.New("gomemcached: server error") // ErrNoStats means that no statistics were available. ErrNoStats = errors.New("gomemcached: no statistics available") // ErrMalformedKey is returned when an invalid key is used. // Keys must be at maximum 250 bytes long and not // contain whitespace or control characters. ErrMalformedKey = errors.New("gomemcached: key is too long or contains invalid characters") // ErrNoServers is returned when no servers are configured or available. ErrNoServers = errors.New("gomemcached: no servers configured or available") // ErrInvalidAddr means that an incorrect address was passed and could not be cast to net.Addr ErrInvalidAddr = errors.New("gomemcached: invalid address for server") // ErrServerNotAvailable means that one of the nodes is currently unavailable ErrServerNotAvailable = errors.New("gomemcached: server(s) is not available") // ErrNotConfigured means that some required parameter is not set in the configuration ErrNotConfigured = errors.New("gomemcached: not complete configuration") // ErrUnknownCommand means that in request consumer use unknown command for memcached. ErrUnknownCommand = errors.New("gomemcached: Unknown command") // ErrDataSizeExceedsLimit means that memcached cannot process the request data due to its size. ErrDataSizeExceedsLimit = errors.New("gomemcached: Data size exceeds limit") // ErrInvalidArguments indicates invalid arguments or operation parameters (non-user request error). ErrInvalidArguments = errors.New("gomemcached: Invalid arguments or operation parameters") // ErrAuthFail indicates that an authorization attempt was made, but it did not work ErrAuthFail = errors.New("gomemcached: authentication enabled but operation failed") )
var CommandNames map[OpCode]string
Mapping of OpCode -> name of command (not exhaustive)
var StatusNames map[Status]string
Functions ¶
This section is empty.
Types ¶
type AppendMode ¶
type AppendMode uint8
const ( // Append - Appends data to the end of an existing key value. Append AppendMode = iota // Prepend -Appends data to the beginning of an existing key value. Prepend )
func (AppendMode) Resolve ¶
func (sm AppendMode) Resolve() OpCode
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a memcached client. It is safe for unlocked use by multiple concurrent goroutines.
func InitFromEnv ¶
InitFromEnv returns a memcached client using the config.HeadlessServiceAddress or config.Servers with equal weight. If a server is listed multiple times, it gets a proportional amount of weight.
func (*Client) Append ¶
Append is an appends/prepends the given item to the existing item, if a value already exists for its key. ErrNotStored is returned if that condition is not met.
func (*Client) CloseAllConns ¶
func (c *Client) CloseAllConns()
CloseAllConns is close all opened connection per shards. Once closed, resources should be released.
func (*Client) CloseAvailableConnsInAllShardPools ¶
CloseAvailableConnsInAllShardPools - removes the specified number of connections from the pools of all shards.
func (*Client) Delete ¶
Delete is a deletes the element with the provided key. If the element does not exist, an ErrCacheMiss error is returned.
func (*Client) Delta ¶
func (c *Client) Delta(deltaMode DeltaMode, key string, delta, initial uint64, exp uint32) (newValue uint64, err error)
Delta is an atomically increments/decrements value by delta. The return value is the new value after being incremented/decrements or an error.
func (*Client) MultiDelete ¶
MultiDelete is a batch version of Delete. Deletes the items with the provided keys. If there is a key in the provided keys that is missing in the cache, the ErrCacheMiss error is ignored.
func (*Client) MultiGet ¶
MultiGet is a batch version of Get. The returned map from keys to items may have fewer elements than the input slice, due to memcached cache misses. Each key must be at most 250 bytes in length. If no error is returned, the returned map will also be non-nil.
func (*Client) MultiStore ¶
MultiStore is a batch version of Store. Writes the provided items with expiration.
type ConnectTimeoutError ¶
ConnectTimeoutError is the error type used when it takes too long to connect to the desired host. This level of detail can generally be ignored.
func (*ConnectTimeoutError) Error ¶
func (cte *ConnectTimeoutError) Error() string
type Memcached ¶
type Memcached interface { Store(storeMode StoreMode, key string, exp uint32, body []byte) (*Response, error) Get(key string) (*Response, error) Delete(key string) (*Response, error) Delta(deltaMode DeltaMode, key string, delta, initial uint64, exp uint32) (newValue uint64, err error) Append(appendMode AppendMode, key string, data []byte) (*Response, error) FlushAll(exp uint32) error MultiDelete(keys []string) error MultiStore(storeMode StoreMode, items map[string][]byte, exp uint32) error MultiGet(keys []string) (map[string][]byte, error) CloseAllConns() CloseAvailableConnsInAllShardPools(numOfClose int) int }
type OpCode ¶
type OpCode uint8
type Option ¶
type Option func(*options)
func WithAuthentication ¶
WithAuthentication is turn on authenticate for memcached
func WithCustomHashRing ¶
func WithCustomHashRing(hr *consistenthash.HashRing) Option
WithCustomHashRing for setup use consistenthash.NewCustomHashRing
func WithDisableLogger ¶
func WithDisableLogger() Option
WithDisableLogger is disabled internal library logs.
func WithDisableMemcachedDiagnostic ¶
func WithDisableMemcachedDiagnostic() Option
WithDisableMemcachedDiagnostic is disabled write library metrics.
gomemcached_method_duration_seconds
func WithDisableNodeProvider ¶
func WithDisableNodeProvider() Option
WithDisableNodeProvider is disabled node health cheek and rebuild nodes for hash ring
func WithDisableRefreshConnsInPool ¶
func WithDisableRefreshConnsInPool() Option
WithDisableRefreshConnsInPool is disabled auto close some connections in pool in NodeProvider. This is done to refresh connections in the pool.
func WithMaxIdleConns ¶
WithMaxIdleConns is sets a custom value of open connections per address. By default, DefaultMaxIdleConns will be used.
func WithPeriodForNodeHealthCheck ¶
WithPeriodForNodeHealthCheck is sets a custom frequency for health checker of physical nodes. By default, DefaultNodeHealthCheckPeriod will be used.
func WithPeriodForRebuildingNodes ¶
WithPeriodForRebuildingNodes is sets a custom frequency for resharding and checking for dead nodes. By default, DefaultRebuildingNodePeriod will be used.
func WithTimeout ¶
WithTimeout is sets custom timeout for connections. By default, DefaultTimeout will be used.
type Request ¶
type Request struct { // The command being issued Opcode OpCode // The CAS (if applicable, or 0) Cas uint64 // An opaque value to be returned with this request Opaque uint32 // Command extras, key, and body Extras, Key, Body []byte }
Request a Memcached request
func (*Request) HeaderBytes ¶
HeaderBytes is a wire representation of the header (with the extras and key)
type Response ¶
type Response struct { // The command opcode of the command that sent the request Opcode OpCode // The status of the response Status Status // The opaque sent in the request Opaque uint32 // The CAS identifier (if applicable) Cas uint64 // Extras, key, and body for this response Extras, Key, Body []byte }
Response is a memcached response
func UnwrapMemcachedError ¶
UnwrapMemcachedError converts memcached errors to normal responses.
If the error is a memcached response, declare the error to be nil so a client can handle the status without worrying about whether it indicates success or failure.
func (*Response) HeaderBytes ¶
HeaderBytes get just the header bytes for this response.