Memcached

<img src="./docs/memcached-cli.svg">

Memcached

This is a golang package for Memcached. It is a simple and easy to use package.

Features

• [x] Completed Memcached text protocol, includes meta text protocol.
• [ ] Integrated serialization and deserialization function
• [x] Cluster support, multiple hash algorithm support, include: crc32, murmur3, redezvous and also custom hash algorithm.
• [x] Fully connection pool features support.
• [x] CLI tool support.
• [x] <del>SASL support.</del>
• [x] support TCP、UDP and Unix domain socket transport.

Installation

go get github.com/yeqown/memcached@latest

Or you can install the CLI binary by running:

go install github.com/yeqown/memcached/cmd/memcached-cli@latest

More memcached-cli usage could be found in CLI.

Usage

There is a simple example to show how to use this package. More examples could be found in the example directory.

package main

import (
    "context"
    "time"

    "github.com/yeqown/memcached"
)

func main() {
	// 1. build client
	// addrs is a string, if you have multiple memcached servers, you can use comma to separate them.
	// e.g. "localhost:11211,localhost:11212,localhost:11213"
	addrs := "localhost:11211"

	// client support options, you can set the options to client.
	// e.g. memcached.New(addrs, memcached.WithDialTimeout(5*time.Second))
	client, err := memcached.New(addrs)
	if err != nil {
		panic(err)
	}

	// 2. use client
	// now, you can use the client API to finish your work.
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	version, err := client.Version(ctx)
	if err != nil {
		panic(err)
	}
	println("Version: ", version)

	if err = client.Set(ctx, "key", []byte("value"), 0, 0); err != nil {
		panic(err)
	}
	if err = client.Set(ctx, "key2", []byte("value2"), 0, 0); err != nil {
		panic(err)
	}

	items, err := client.Gets(ctx, "key", "key2")
	if err != nil {
		panic(err)
	}

	for _, item := range items {
		println("key: ", item.Key, " value: ", string(item.Value))
	}
}

Support Commands

Now, we have implemented some commands, and we will implement more commands in the future.

| Command | Status | API Usage | Description | |----------------|--------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| | ---- | ----- | STORAGE COMMANDS | --- | | Set | ✅ | Set(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error | Set a key-value pair to memcached | | Add | ✅ | Add(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error | Add a key-value pair to memcached | | Replace | ✅ | Replace(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error | Replace a key-value pair to memcached | | Append | ✅ | Append(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error | Append a value to the key | | Prepend | ✅ | Prepend(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration) error | Prepend a value to the key | | Cas | ✅ | Cas(ctx context.Context, key string, value []byte, flags uint32, expiry time.Duration, cas uint64) error | Compare and set a key-value pair to memcached | | ---- | ----- | RETRIEVAL COMMANDS | --- | | Gets | ✅ | Gets(ctx context.Context, keys ...string) ([]*Item, error) | Get a value by key from memcached with cas value | | Get | ✅ | Get(ctx context.Context, key string) (*Item, error) | Get a value by key from memcached | | GetAndTouch | ✅ | GetAndTouch(ctx context.Context, expiry uint32, key string) (*Item, error) | Get a value by key from memcached and touch the key's expire time | | GetAndTouches | ✅ | GetAndTouches(ctx context.Context, expiry uint32, keys ...string) ([]*Item, error) | Get a value by key from memcached and touch the key's expire time | | ----- | ----- | OTHER COMMANDS | --- | | Delete | ✅ | Delete(ctx context.Context, key string) error | Delete a key-value pair from memcached | | Incr | ✅ | Incr(ctx context.Context, key string, delta uint64) (uint64, error) | Increment a key's value | | Decr | ✅ | Decr(ctx context.Context, key string, delta uint64) (uint64, error) | Decrement a key's value | | Touch | ✅ | Touch(ctx context.Context, key string, expiry uint32) error | Touch a key's expire time | | MetaGet | ✅ | MetaGet(ctx context.Context, key []byte, options ...MetaGetOption) (*MetaItem, error) | Get a key's meta information | | MetaSet | ✅ | MetaSet(ctx context.Context, key, value []byte, options ...MetaSetOption) (*MetaItem, error) | Set a key's meta information | | MetaDelete | ✅ | MetaDelete(ctx context.Context, key []byte, options ...MetaDeleteOption) (*MetaItem, error) | Delete a key's meta information | | MetaArithmetic | ✅ | MetaArithmetic(ctx context.Context, key []byte, delta uint64, options ...MetaArithmeticOption) (*MetaItem, error) | Arithmetic a key's meta information | | MetaDebug | ✅ | MetaDebug(ctx context.Context, key []byte, options ...MetaDebugOption) (*MetaItemDebug, error) | Debug a key's meta information | | MetaNoop | ✅ | MetaNoop(ctx context.Context) error | Noop a key's meta information | | Version | ✅ | Version(ctx context.Context) (string, error) | Get memcached server version | | FlushAll | ✅ | FlushAll(ctx context.Context) error | Flush all keys in memcached server |

Development Guide

Prerequisites

• Go 1.21 or higher
• Python (for pre-commit hooks) or just brew install pre-commit on MacOS
• Docker (for running memcached in tests)

Setting up development environment

1. Clone the repository:

   git clone https://github.com/yeqown/memcached.git
   cd memcached
   

2. Install pre-commit hooks:

   pip install pre-commit
   # or MacOS
   # brew install pre-commit
   
   pre-commit install
   

3. Install golangci-lint:

   go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
   

Running Tests

go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...

Code Style

This project follows the standard Go code style guidelines and uses golangci-lint for additional checks. The configuration can be found in .golangci.yml.

Key points:

• Follow Go standard formatting (