memcached

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 19, 2024 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package memcached binary protocol packet formats and constants.

Index

Constants

View Source 
const (
	REQ_MAGIC = 0x80
	RES_MAGIC = 0x81
)
View Source 
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)
)
View Source 
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)
)
View Source 
const (
	// HDR_LEN is a number of bytes in a binary protocol header.
	HDR_LEN  = 24
	BODY_LEN = 128
)
View Source 
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
)
View Source 
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
)
View Source 
const (
	SaslMechanism = "PLAIN"
)

Variables

View Source 
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")
)
View Source 
var CommandNames map[OpCode]string

Mapping of OpCode -> name of command (not exhaustive)

View Source 
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 

func InitFromEnv(opts ...Option) (*Client, error)

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 

func (c *Client) Append(appendMode AppendMode, key string, data []byte) (_ *Response, err error)

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 

func (c *Client) CloseAvailableConnsInAllShardPools(numOfClose int) int

CloseAvailableConnsInAllShardPools - removes the specified number of connections from the pools of all shards.

func (*Client) Delete 

func (c *Client) Delete(key string) (_ *Response, err error)

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) FlushAll 

func (c *Client) FlushAll(exp uint32) (err error)

FlushAll is a deletes all items in the cache.

func (*Client) Get 

func (c *Client) Get(key string) (_ *Response, err error)

Get is return an item for provided key.

func (*Client) MultiDelete 

func (c *Client) MultiDelete(keys []string) (err error)

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 

func (c *Client) MultiGet(keys []string) (_ map[string][]byte, err error)

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 

func (c *Client) MultiStore(storeMode StoreMode, items map[string][]byte, exp uint32) (err error)

MultiStore is a batch version of Store. Writes the provided items with expiration.

func (*Client) Store 

func (c *Client) Store(storeMode StoreMode, key string, exp uint32, body []byte) (_ *Response, err error)

Store is a wrote the provided item with expiration.

type ConnectTimeoutError 

type ConnectTimeoutError struct {
	Addr net.Addr
}

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 DeltaMode 

type DeltaMode uint8
const (
	// Increment - increases the value by the specified amount
	Increment DeltaMode = iota
	// Decrement - decreases the value by the specified amount
	Decrement
)

func (DeltaMode) Resolve 

func (sm DeltaMode) Resolve() OpCode

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

func (OpCode) IsQuiet 

func (o OpCode) IsQuiet() bool

IsQuiet return true if a command is a "quiet" command.

func (OpCode) String 

func (o OpCode) String() (rv string)

String an op code.

type Option 

type Option func(*options)

func WithAuthentication 

func WithAuthentication(user, pass string) Option

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 

func WithMaxIdleConns(num int) Option

WithMaxIdleConns is sets a custom value of open connections per address. By default, DefaultMaxIdleConns will be used.

func WithPeriodForNodeHealthCheck 

func WithPeriodForNodeHealthCheck(t time.Duration) Option

WithPeriodForNodeHealthCheck is sets a custom frequency for health checker of physical nodes. By default, DefaultNodeHealthCheckPeriod will be used.

func WithPeriodForRebuildingNodes 

func WithPeriodForRebuildingNodes(t time.Duration) Option

WithPeriodForRebuildingNodes is sets a custom frequency for resharding and checking for dead nodes. By default, DefaultRebuildingNodePeriod will be used.

func WithTimeout 

func WithTimeout(tm time.Duration) Option

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) Bytes 

func (r *Request) Bytes() []byte

Bytes is a wire representation of this request.

func (*Request) HeaderBytes 

func (r *Request) HeaderBytes() []byte

HeaderBytes is a wire representation of the header (with the extras and key)

func (*Request) Receive 

func (r *Request) Receive(rd io.Reader, hdrBytes []byte) (int, error)

Receive a fill this Request with the data from this reader.

func (*Request) Size 

func (r *Request) Size() int

Size is a number of bytes this request requires.

func (Request) String 

func (r Request) String() string

String is a debugging string representation of this request

func (*Request) Transmit 

func (r *Request) Transmit(w io.Writer) (n int, err error)

Transmit is send this request message across a writer.

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 

func UnwrapMemcachedError(err error) *Response

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) Bytes 

func (r *Response) Bytes() []byte

Bytes the actual bytes transmitted for this response.

func (*Response) Error 

func (r *Response) Error() string

Error - Response as an error.

func (*Response) HeaderBytes 

func (r *Response) HeaderBytes() []byte

HeaderBytes get just the header bytes for this response.

func (*Response) Receive 

func (r *Response) Receive(rd io.Reader, hdrBytes []byte) (int, error)

Receive - fill this Response with the data from this reader.

func (*Response) Size 

func (r *Response) Size() int

Size is a number of bytes this response consumes on the wire.

func (Response) String 

func (r Response) String() string

String a debugging string representation of this response

func (*Response) Transmit 

func (r *Response) Transmit(w io.Writer) (n int, err error)

Transmit send this response message across a writer.

type Status 

type Status uint16

func (Status) String 

func (s Status) String() (rv string)

String an op code.

type StoreMode 

type StoreMode uint8
const (
	// Add - Store the data, but only if the server does not already hold data for a given key
	Add StoreMode = iota
	// Set -  Store the data, overwrite if already exists
	Set
	// Replace - Store the data, but only if the server does already hold data for a given key
	Replace
)

func (StoreMode) Resolve 

func (sm StoreMode) Resolve() OpCode

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.