josephscott/marmerine

An alternate Memcached implementation

0.0.3 2022-05-21 17:37 UTC

Requires

• php: >=8.1.0
• workerman/workerman: 4.0.37

Requires (Dev)

• pestphp/pest: 1.21.3
• phpstan/phpstan: 1.6.7

Suggests

• ext-event: Better for PHP workerman performance

MIT

README

This is an alternate Memcached implementation.

git clone https://github.com/josephscott/marmerine.git
composer install
php server.php start

Storage Commands

set

• Supported: Yes ✅
• Format: set <key> <flags> <exptime> <length> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Error Response: CLIENT_ERROR [error]\r\nERROR\r\n

Examples

$ printf "set thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED

$ printf "set thing 0 300 3\r\nabc123XYZ\r\n" | nc localhost 11211
CLIENT_ERROR bad data chunk
ERROR

Description

This will store the value of the given key, even if it already exists.

add

• Supported: Yes ✅
• Format: add <key> <flags> <exptime> <length> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Failure Response: NOT_STORED\r\n
• Error Response: CLIENT_ERROR [error]\r\nERROR\r\n

Examples

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED

$ printf "add thing 0 300 3\r\nabc123XYZ\r\n" | nc localhost 11211
CLIENT_ERROR bad data chunk
ERROR

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
NOT_STORED

Description

This will store the value of the given key, only if it does not already exist.

replace

• Supported: Yes ✅
• Format: replace <key> <flags> <exptime> <length> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Error Response: NOT_STORED\r\n

Examples

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "replace thing 0 300 12\r\nabc-REPLACED\r\n" | nc localhost 11211
STORED
$ printf "get thing\r\n" | nc localhost 11211
VALUE thing 0 12
abc-REPLACED
END

$ printf "replace thing 0 300 3\r\nabc\r\n" | nc localhost 11211
NOT_STORED

Description

This will replace the value of the given key.

append

• Supported: Yes ✅
• Format: append <key> <flags> <exptime> <length> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Error Response: NOT_STORED\r\n

Examples

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "append thing 0 300 6\r\n-AFTER\r\n" | nc localhost 11211
STORED
$ printf "get thing\r\n" | nc localhost 11211
VALUE thing 0 9
abc-AFTER
END

$ printf "append thing 0 300 6\r\n-AFTER\r\n" | nc localhost 11211
NOT_STORED

Description This will append a string to the value of an existing key.

prepend

• Supported: Yes ✅
• Format: prepend <key> <flags> <exptime> <length> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Error Response: NOT_STORED\r\n

EXAMPLES

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "prepend thing 0 300 7\r\nBEFORE-\r\n" | nc localhost 11211
STORED
$ printf "get thing\r\n" | nc localhost 11211
VALUE thing 0 10
BEFORE-abc
END

Description This will prepend a string to the value of an existing key.

cas

• Supported: Yes ✅
• Format: cas <key> <flags> <expiry> <datalen> <cas> [noreply]\r\n<data>\r\n
• Success Response: STORED\r\n
• Error Resposne: NOT_STORED\r\n

EXAMPLES

$ printf "set thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "gets thing\r\n" | nc localhost 11211
VALUE thing 0 3 1
abc
END
$ printf "cas thing 0 300 3 1\r\nXYZ\r\n"| nc localhost 11211
STORED

Description

Set a new value for a key if the cas token hasn't changed.

touch

• Supported: Yes ✅
• Format: touch <key> <expiry> [noreply]\r\n
• Success Response: TOUCHED\r\n
• Error Resposne: NOT_FOUND\r\n

Examples

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "touch thing 1800\r\n" | nc localhost 11211
TOUCHED

Description

Update the expiration time of an existing key.

Retrieve Commands

get

• Supported: Yes ✅
• Format: get <key> [key2 key3 ... keyn]\r\n
• Found Response: VALUE <key> <flags> <length>\r\n<data>\r\nEND\r\n
• Not Found Response: END\r\n

Examples

$ printf "set thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "get thing\r\n" | nc localhost 11211
VALUE thing 0 3
abc
END

$ printf "get thing\r\n" | nc localhost 11211
END

$ printf "set thing1 0 300 4\r\n1abc\r\n" | nc localhost 11211
STORED
$ printf "set thing2 0 300 4\r\n2abc\r\n" | nc localhost 11211
STORED
$ printf "set thing3 0 300 4\r\n3abc\r\n" | nc localhost 11211
STORED
$ printf "get thing thing1 thing2 thing3\r\n" | nc localhost 11211
VALUE thing1 0 4
1abc
VALUE thing2 0 4
2abc
VALUE thing3 0 4
3abc
END

Description

Gets the value for the given key. When the key does not exist, a response with just END\r\n is given. When multiple keys are provided, only ones that exist will be returned.

gets

• Supported: Yes ✅
• Format: get <key> [key2 key3 ... keyn]\r\n
• Found Response: VALUE <key> <flags> <length> <cas>\r\n<data>\r\nEND\r\n
• Not Found Response: END\r\n

Examples

$ printf "set thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "gets thing\r\n" | nc localhost 11211
VALUE thing 0 3 1
abc
END

$ printf "gets thing\r\n" | nc localhost 11211
END

Description

This is the get command with the addition of the cas token in the response.

gat

• Supported: No ⛔

gats

• Supported: No ⛔

Delete Commands

delete

• Supported: Yes ✅
• Format: delete <key> [noreply]\r\n
• Success Response: DELETED\r\n
• Not Found Response: NOT_FOUND\r\n

Examples

$ printf "set thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "delete thing\r\n" | nc localhost 11211
DELETED

$ printf "delete thing\r\n" | nc localhost 11211
NOT_FOUND

Description

Delete the given key. If the key does not exist then NOT_FOUND is returned.

flush_all

• Supported: Yes ✅
• Format: flush_all [delay] [noreply]\r\n
• Every Response: OK\r\n

Examples

$ printf "flush_all\r\n" | nc localhost 11211
OK

$ printf "flush_all\r\n" | nc localhost 11211
OK
$ printf "flush_all\r\n" | nc localhost 11211
OK

Description

Delete all of the stored keys. There is no fail or error condition, it always returns OK.

Arithmetic Commands

incr

• Supported: Yes ✅
• Format: incr <key> <value> [noreply]\r\n
• Success Response: <incremented value>\r\n
• Error Response: CLIENT_ERROR cannot increment or decrement non-numeric value

Examples

$ printf "add thing 0 300 1\r\n1\r\n" | nc localhost 11211
STORED
$ printf "incr thing 1\r\n" | nc localhost 11211
2
$ printf "incr thing 1\r\n" | nc localhost 11211
3

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "incr thing 1\r\n" | nc localhost 11211
CLIENT_ERROR cannot increment or decrement non-numeric value

Description

This only works on integer values.

decr

• Supported: Yes ✅
• Format: decr <key> <value> [noreply]\r\n
• Success Response: <decremented value>\r\n
• Error Response: CLIENT_ERROR cannot increment or decrement non-numeric value

Examples

$ printf "add thing 0 300 1\r\n9\r\n" | nc localhost 11211
STORED
$ printf "decr thing 1\r\n" | nc localhost 11211
8
$ printf "decr thing 1\r\n" | nc localhost 11211
7

$ printf "add thing 0 300 3\r\nabc\r\n" | nc localhost 11211
STORED
$ printf "decr thing 1\r\n" | nc localhost 11211
CLIENT_ERROR cannot increment or decrement non-numeric value

Description

This only works on integer values.

Miscellaneous Commands

quit

• Supported: Yes ✅
• Format: quit\r\n
• Every Response: ( None )

Examples

$ printf "quit\r\n" | nc localhost 11211

Description

This closes the connection to the server. It does not return anything.

version

• Supported: Yes ✅
• Format: version\r\n
• Every Response: VERSION <version>\r\n

Examples

$ printf "version\r\n" | nc localhost 11211
VERSION 1.6.12

Description

Get the version number from the server.

verbosity

• Supported: No ⛔

stats

• Supported: Yes ✅
• Format: stats\r\n
• Every Response: STAT <stat> <value>\r\nEND\r\n

Example

$ printf "stats\r\n" | nc localhost 11211
STAT pid 92458
STAT uptime 9
STAT time 1650595977
END

Description

Stats that are currently supported:

• pid
• uptime
• time
• total_connections
• curr_items
• cmd_
• _hits
• _misses

Memcached Resources

• Memcached, the original.
• Memcached Protocol.txt, general description of the protocols.
• Twemproxy, a proxy for Memcached and Redis from Twitter.
• Twemproxy Memcached Notes, helpful list of of supported Memcached comands in Twemproxy.
• MySQL Memcached TCP Text Protocol, commands outlined for the MySQL implementation.
• Memcached Cheat Sheet, a list of other Memcached resources and examples.
• libmemcached-awesome, an updated version of the original libmemcached.
• memc.rs, Memcached clone written in Rust, compatible with the binary protocol.
• memtier_benchmark, a Memcached ( and Redis ) benchmarking tool.
• Expiration Times, good description of how Memcached treats the expiration times.