memcache-0.5.0.0: CHANGELOG.md
# 0.5.0.0 - November 18th, 2026
This release changes how a cluster routes keys to its servers, so upgrading
moves keys to other servers, once; see "Upgrading from 0.4" in the README. It
also changes what `optsServerRetries` counts, the types of two lower-level
functions, and some return values and exceptions, so read the breaking
changes first. Two security fixes stop memcached from running the bytes of a
value being stored as commands, and memcached 1.6.10 or later is now
required; see Security.
## Security
Both fixes are also in 0.4.2.1.
- `set`, `add`, `replace`, `cas`, `append`, `prepend` and `setMany` reject a
value larger than 1GiB, memcached's largest possible item size, with
`OpError ErrValueTooLarge` before sending anything. A value of about 2GiB
or more (longer than 2147483645 bytes) previously made memcached run the
value's bytes as commands, so storing untrusted data could run commands on
the server, and a value over 1GiB could time out, be sent again and mark
the server dead. Such a value no longer reaches the server, so it no
longer makes memcached delete the key's existing value, as memcached does
whenever it rejects a store as too large; a value within 1GiB but over the
server's own limit (`-I`, 1MiB by default) still does. Every operation
that sends a value now evaluates it first, before its timeout starts: an
exception it throws is no longer retried and no longer marks the server
dead, and time spent computing it no longer counts towards
`optsServerTimeout`. `setMany` evaluates every value before it sends
anything, so a list of lazily computed values is all in memory at once,
and one value over the limit stores none of the pairs. The request
encoders in `Database.Memcache.Socket` still encode a value of any length;
don't send one longer than 1GiB.
- memcached 1.6.10 or later is now required (previously documented as
1.6.0). memcached before 1.6.10 rejects the meta set command this library
stores values with, without reading the value that follows it, and then
runs the value's bytes as commands, so storing untrusted data could run
commands on the server. Each new connection now asks the server for its
version before it is used: until that check passes, the only requests sent
are the authentication exchange, when credentials are set, and `version`.
A server older than 1.6.10, or any other reply that is neither an error
nor a readable version, is refused with `ProtocolError (UnknownOp ...)`,
whose message quotes the reply; the connection is closed, and the refusal
is not retried and doesn't mark the server dead. An error reply, such as
`CLIENT_ERROR unauthenticated`, throws what it throws for any request, and
so does a reply that can't be parsed, such as an empty line or an overlong
one, which counts against the server. This covers connections over TCP and
Unix sockets, and ElastiCache discovery, which now fails for a cluster
running a memcached older than 1.6.10. Through a proxy, the check sees
only the proxy's version, so every memcached behind it must be 1.6.10 or
later too. Each new connection takes one more round trip, which counts
towards `optsServerTimeout`. Connections made directly with
`Database.Memcache.Socket.newConnection` are not checked; send
`storeRequest`, `setManyRequest` and `modifyRequest` only to 1.6.10 or
later.
## Breaking changes
- memcached 1.6.10 or later is now required (see Security): a new
connection to an older server is refused, so every operation that needs
one fails with `ProtocolError (UnknownOp ...)`.
- Clusters route keys with ketama consistent hashing, compatible with
libmemcached (see New): `ketamaServerForKey` is the new default
`optsGetServerForKey`. 0.4's router sent keys to no more than two servers
at a time, and the server it chose for a key could change with the
`hashable` version. With n servers, upgrading moves all but about one key
in n to a different server, once: about half the keys with 2 servers, 70%
with 3 and 88% with 8. A single server is unaffected. While old and new
versions run side by side, as in a rolling deploy, they read and write a
moved key on different servers; "Upgrading from 0.4", in the README and in
`Database.Memcache.Cluster`, gives two ways to switch. One of them uses
`legacyServerForKey`, 0.4's router, which `Database.Memcache.Cluster` now
exports, deprecated, for one release; it will be removed in the next major
version. A key whose server is marked failed now goes to the next live
server on the ring, and other keys stay where they are.
- With keys spread over every server, `getMany` sends each server its keys
in batches of up to 256, one round trip per batch and one server after
another, so it can take longer than before with three or more servers. It
still returns its results grouped by server, so their order changes too.
- Servers keep the order they are configured or discovered in, instead of
being sorted by `sid`: `getServers` and `stats` list them in that order,
`flush` goes through them in it, and `version` asks the first live one.
- `optsServerRetries` now counts retries, as its documentation said, rather
than attempts: an operation is tried up to `optsServerRetries + 1` times,
and once for 0 or a negative value. So a value of 1 or more that you set
yourself makes one more attempt than in 0.4; set it one lower to keep the
old number of attempts. `minBound`, which used to retry practically
without end, now gives one attempt. The default drops from 2 to 1, so by
default an operation is still tried twice.
- `increment`, `decrement`, `append`, `prepend`, `add`, `delete`, and `cas`
and `replace` with a version other than 0 are no longer sent again once
their request may have reached the server, so they can't take effect twice
or report failure because their first request succeeded. Once the client
has begun to send the request, a failure such as a timeout, a network
error, a dropped connection, a reply that can't be read or a
`SERVER_ERROR` whose text names no status is thrown as it is, whatever
retries are left, and marks the server dead. A failure before sending,
such as a refused connection or a timeout while waiting for a pooled
connection, is still retried. Before sending one of these requests on a
pooled connection, the client checks, without waiting, that nothing is
left to read on it and that the server hasn't closed or reset it, as
memcached closes idle connections when it restarts or after
`-o idle_timeout`. If the check fails, the client retries the request on a
new connection when retries are left; on Windows, the check only sees what
has already been read, so it can't see a closed connection. Other
operations are still retried after any failure that counts against the
server, so the server may carry out their request twice.
- When a server's host name resolves to several addresses, the client now
tries each in turn, not just the first (see Fixes). So when the first
address refuses and a later one doesn't answer, an attempt throws
`ClientError Timeout` once its `optsServerTimeout` runs out, instead of
the first address's `IOException` at once. If the addresses are separate
memcached instances, give each its own `ServerSpec`: while the first
refuses connections, new connections go to the next one that accepts, and
so to another cache.
- `append` and `prepend` return `Nothing` when a non-zero version doesn't
match, as `cas` and `replace` do, instead of throwing
`OpError ErrKeyExists`.
- `flush` stops at the first server whose reply it rejects (see Fixes),
leaving the servers after it unflushed, where 0.4 checked such a reply
only after sending `flush_all` to every server.
- memcached's capitalised out-of-memory errors are thrown as
`OpError ErrOutOfMemory`, like the lowercase ones, instead of
`ProtocolError ServerError` (see Fixes), so the request is no longer sent
again, and they don't count towards marking the server dead. Code that
matched `ServerError` for them should match `ErrOutOfMemory` instead.
- Numbers in replies (value lengths, CAS versions, flags and counter values)
must be plain decimal digits that fit their type, as memcached writes them
(see Fixes), where 0.4 also read forms such as `(5)` and `0x10`, and
wrapped numbers around to fit. So from a server or proxy that writes them
otherwise, a value length now throws `BadLength`, and a CAS version, flags
or counter value reads as 0. A `VA` reply without a value length, which
used to read as a hit with an empty value, throws `BadLength` too.
- `displayException` for a `MemcacheError` gives a one-line message, such as
`memcached operation failed: key not found`, where it used to give the
same text as `show`, such as `OpError ErrKeyNotFound`; GHC 9.10 and later
also print it for an uncaught exception. Any detail, such as text from the
server, is cut to its first 200 characters, with backslashes and
characters outside printable ASCII escaped. `show` is unchanged, so code
that parses `displayException`'s text should match on the constructors, or
use `show`, instead.
- `ElastiCacheClient.newClient` throws `ClientError Timeout` unless its
first discovery, connecting included, finishes within `optsServerTimeout`.
It had no time limit, so with the default of 750ms, a slow DNS lookup or
connection can now make it fail. An `ERROR`, `CLIENT_ERROR` or
`SERVER_ERROR` reply to the request for the cluster configuration, such as
the `ERROR` that plain memcached gives, throws a `StringException` from
`UnliftIO.Exception` quoting the line, escaped and cut to 200 characters,
where `newClient` used to block forever, or throw
`ProtocolError UnexpectedEOF` if the endpoint then closed the connection.
Discovery now calls `optsServerSpecsToServers` with one node at a time.
- `stats` throws `BadLength` for a server's reply of more than 262,144
entries, or of more than 16MiB counting each line as it was sent, such as
the reply to `stats conns` on a server with more than about 65,500 open
connections. `stats` retries it, as it does other server failures, and it
counts towards marking the server dead. `recvRawUntil` throws `BadLength`
once it has read more than 1MiB without its delimiter, so ElastiCache
discovery does too for a version line or configuration reply that long. No
option raises these limits.
- `parseServerSpec`, and so `parseConfigurationEndpoint`, percent-decodes
the username and password of a `memcached://` URI to the bytes they
encode, so `memcached://user:p%40ss@cache.example` has the password
`p@ss`, and returns `Left` if the decoded credentials fail
`validateCredentials`. `validateCredentials`, which authentication also
uses, now allows `:` in passwords, as memcached's auth file splits each
line at its first `:`, and rejects NUL in usernames and passwords, so
connecting with a NUL in either now throws
`ClientError InvalidAuthentication` before anything is sent. An IPv6
address in brackets, as in `memcached://[::1]:11211`, now gives the host
`::1`, without the brackets, and the `%25` that introduces a zone ID is
decoded, so `[fe80::1%25eth0]` gives `fe80::1%eth0`. A path after an empty
host, other than slashes alone, as in `memcached:///run/memcached.sock`,
is now a Unix socket (see New), where 0.4 ignored it and gave `127.0.0.1`;
with a port, or with `%00` or a raw `@` in the path, such a URI now
returns `Left`.
- `show` for an `Authentication`, and so for a `ServerSpec`, prints the
password as `<redacted>`, and the error that `parseServerSpec` and
`parseConfigurationEndpoint` give for an invalid URI no longer quotes it,
so that passwords stay out of logs.
- `getManyRequest` in `Database.Memcache.Socket`, and the request builders
that `keyedBatchOp` in `Database.Memcache.Cluster` takes, have a new `Int`
argument: an opaque, which the request must send unchanged, in decimal, as
its `O` flag, so that its reply can be matched to it (see Fixes).
`getManyRequest` sends it in place of the `k` flag, so its replies no
longer echo the key.
- `Database.Memcache.Client` exports more names (see New), such as `Key`,
`Version`, `Server` and `defaultOptions`, and `Database.Memcache.Cluster`,
`Database.Memcache.Server`, `Database.Memcache.Socket` and
`Database.Memcache.Types` export new names too. A new name can clash with
another in a module that imports one of these modules unqualified without
listing the names it imports, even one that hides some with `hiding`.
## New
- Unix sockets, contributed by drlkf: a `ServerSpec` whose host begins with
`/` connects to the Unix socket at that path, for a memcached on the same
machine. `parseServerSpec` reads one from a URI with a path, other than
slashes alone, after an empty host, such as
`memcached:///run/memcached.sock`, or
`memcached://user:secret@/run/memcached.sock` with credentials. The path
is percent-decoded to bytes. A port or `%00` is an error, and so is an `@`
not written `%40`, so that a URI with one slash too many, such as
`memcached:///user:secret@cache.example`, isn't taken for a socket path
holding the password. The client doesn't use a socket's port to connect,
but the port still names the server when keys are routed: `"11211"`, which
a URI gives, names the socket by its path alone, as libmemcached's
`memcached_server_add` does, and `"0"` names it `path:0`, as
libmemcached's `memcached_server_add_unix_socket` and pylibmc do.
ElastiCache discovery fails, rather than connect to a socket on this
machine, if the endpoint lists a node whose host is a path.
- Keys go to the same server as with other clients that use libmemcached's
weighted ketama distribution, given the same host strings and ports in the
same order and equal weights: libmemcached with
`MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED`, php-memcached with
`OPT_LIBKETAMA_COMPATIBLE`, pylibmc with the `ketama_weighted` behavior,
and twemproxy with `hash: md5` and `distribution: ketama` and its servers
listed without node names. In the rare case that two servers have a point
with the same value, libmemcached before 1.1, which php-memcached and
pylibmc may be built with, and twemproxy may choose differently for the
keys just below it. The new module `Database.Memcache.Ketama` (`Ring`,
`ring`, `serverName`, `keyHash`, `owner`, `owners` and `ringPoints`) works
out which server a key belongs to, and builds rings with weights, which
clusters don't use. `Database.Memcache.Cluster` exports the default router
as `ketamaServerForKey`, and `isAlive` for a custom router that skips
servers marked failed, and `Database.Memcache.Server` exports `serverHost`
and `serverPort`.
- `withClient` creates a client, runs an action with it, and closes the
client's connections with `quit` when the action returns or throws.
- `setMany` and `deleteMany` store and delete many keys, pipelining the
requests to each server as `getMany` does. `setMany` returns the new
version of each key, grouped by server; `deleteMany` returns once each key
has been deleted or found missing, without saying which. Their request
encoders, `setManyRequest` and `deleteManyRequest`, are in
`Database.Memcache.Socket`.
- `defaultOptions`, `defaultServerOptions` and `defaultServerSpec` name the
values that `def` gives. They are exported from
`Database.Memcache.Cluster`, `Database.Memcache.Server` and
`Database.Memcache.Types` respectively, and all three from
`Database.Memcache.Client`.
- `Database.Memcache.Client` also exports `parseServerSpec`, `Retries`,
`ServerOptions(..)`, the abstract `Server` type, and `Key`, `Value`,
`Initial`, `Delta`, `Expiration`, `Flags` and `Version`, the types its own
functions use.
- For lower-level use: `closeAll` in `Database.Memcache.Server` closes every
connection to a server, as `quit` does for each server of a client;
`keyedOpExpecting`, `anyOpExpecting` and `allOpExpecting` in
`Database.Memcache.Cluster` reject a reply whose code is none of those
given, closing its connection, and `keyedOpExpectingOnce` also doesn't
send its request again once it may have reached the server; and
`checkIdle` in `Database.Memcache.Socket` checks, without waiting, that
nothing is left to read on a connection and that the server hasn't closed
it (on Windows, it only checks what has already been read).
## Fixes
- Fix `getMany` dropping keys, or returning one key's value as another's,
when it couldn't match the key that memcached echoed in a reply: a key
containing byte 0xa0, such as UTF-8 `"voilà"`; a key with a space or
control byte once an increment has created it or made its value longer, or
an append or prepend has rebuilt it; and a plain key that another client
stored with the `b` flag. When such a key held a line break, the echo also
ended the reply line inside the key, so `getMany` could return part of the
key as another key's value, fail with `BadLength` and mark a healthy
server dead, or end the batch early and leave the rest of its replies on
the pooled connection, to be read as the replies to later requests.
`getMany`'s requests no longer ask memcached to echo the key, and batch
replies are now matched to their requests by memcached's opaque (`O`) flag
instead. A reply that matches no request in its batch, which used to be
dropped, or that comes out of order, now throws `UnexpectedResponse` and
closes the connection; like any server failure, the batch is then sent
again on a new connection if retries are left, and the failure counts
towards marking the server dead.
- Reply lines are split into tokens on spaces alone, as memcached writes
them, so a token that `recvResponse` returns keeps any other whitespace
byte, such as a tab or 0xa0, and so do `stats` values.
- In single-key operations, `version`, `flush` and authentication, a reply
with an unknown code, or one the request can't get, as when an earlier
request's reply is still on the connection, now closes the connection
instead of returning it to the pool out of step, where later requests
would read each other's replies. It throws `UnknownStatus` or
`UnexpectedResponse`, where some such replies used to be taken as an
answer: as success by a store, `increment`, `decrement`, `delete`, `flush`
or authentication, and as a miss by `get`, `gat` and `touch` for an `NF`,
and by `cas`, `replace`, `append`, `prepend`, `increment`, `decrement` and
`delete` for an `EN`. `flush` now stops at the first server whose reply it
rejects, leaving the servers after it unflushed, where it used to check
such a reply only after sending `flush_all` to every server (see Breaking
changes). In `getMany`, `setMany` and `deleteMany`, a reply with an
unknown code throws `UnknownStatus` and closes the connection; the batch
is then sent again on a new connection if retries are left, and the
failure counts towards marking the server dead. `getMany` used to skip
such a reply, or throw for it without sending the batch again or counting
the failure.
- memcached's capitalised out-of-memory errors,
`Out of memory allocating new item` (from `increment` and `decrement`) and
`Out of memory during read`, are reported as `OpError ErrOutOfMemory`,
like the lowercase ones (see Breaking changes). They were thrown as
`ProtocolError ServerError`, so the request was sent again and a full but
healthy server was marked dead.
- An attempt that runs out of `optsServerTimeout` while still waiting for a
free pooled connection is no longer blamed on the server: it is retried as
before, but if it was the last attempt, the operation throws
`ClientError Timeout` without marking the server dead. Running out of time
later, while connecting, authenticating or using the connection, still
counts against the server. A connection is now opened, and authenticated,
once its request has a place in the pool, so a failed connect no longer
leaves requests queued for the pool blocked until their own timeout, as it
did with resource-pool 0.3.0.0 to 0.5.0.0. An `allOp'` operation must make
its requests through the `Server` it is given for its timeouts to count
against the server.
- A failed attempt that counts against the server now closes the server's
idle pooled connections before the operation is retried or the server is
marked dead, as a timeout already did. So with `soNumResources` of 2 or
more, a memcached restart or memcached's `idle_timeout` no longer sends
each retry to another closed connection, failing the operation and marking
a healthy server dead. With resource-pool 0.2, an asynchronous exception,
such as a `cancel`, that arrived while those connections were being closed
could be lost, so that the request carried on as if it hadn't arrived, or
cut the closing short, leaving some of them open; with later versions, it
could still cut the closing short between two of the pool's stripes.
`close` in `Database.Memcache.Server`, which closes them, now holds such
an exception back until every idle connection is closed, as `closeAll`
does, so they are all closed first, and the exception then ends the
request.
- Retries no longer run with asynchronous exceptions masked. Like the first
attempt, each runs in the caller's masking state, so `optsServerTimeout`
and the caller's own asynchronous exceptions, such as a `cancel`, can
interrupt a retry that keeps working without blocking.
- When a server's host name resolves to several addresses, the client tries
each in turn, within the attempt's `optsServerTimeout`, and keeps the
first connection that succeeds until it is closed; it used to try only the
first address. If every address fails, the error is still the first
address's. An address that doesn't answer uses up the attempt's time, so
when the first address refuses and a later one doesn't answer, an attempt
now throws `ClientError Timeout` where it used to throw the first
address's error at once (see Breaking changes). A failed authentication,
or a server version the client refuses, is not retried against another
address. If the addresses are separate memcached instances, then while the
first refuses connections, new connections go to the next one that
accepts, and so to another cache, and stay with it until they are closed;
give each instance its own `ServerSpec`.
- `quit` no longer sends memcached's `quit` command, so it never connects to
a server, and it never throws, even when every server is marked dead. It
closes the client's connections to every server, including those marked
dead: idle ones at once, and each one in use as soon as its request
finishes. An asynchronous exception, such as a `cancel`, that arrives
while it closes them is held back until every server's idle connections
are closed. A request that starts later, or is still waiting for a
connection, or opening one, when `quit` runs, opens a new one, which stays
open as usual.
- `ElastiCacheClient.newClient` no longer stops refreshing the node list
after the first refresh that fails. A refresh that throws, gets an error
reply or runs out of time keeps the current servers, and discovery tries
again at the next interval. Its error is dropped, where the first refresh
that threw used to end discovery and print its exception on stderr. Each
refresh has the first discovery's time limit, `optsServerTimeout`, and
connects to the endpoint afresh, looking its name up again, as a
connection kept from an earlier refresh could lead to a node that
ElastiCache has since replaced. A refresh also keeps the `Server`, and so
the pooled connections and failure state, of each node still listed, where
it used to replace every server and leave the old connections open. It
closes the connections of a node no longer listed, or listed with another
IP address, as when ElastiCache replaces it: idle ones at once, and one in
use as soon as its request finishes, so that requests connect again,
looking the node's name up afresh.
- ElastiCache discovery checks the endpoint's replies more strictly. A
configuration that lists more than 1,000 nodes, the same host and port
twice, or a node that isn't a plain host and port now fails discovery, as
a reply that can't be parsed does: `ElastiCacheClient.newClient` throws a
`StringException`, and a refresh keeps the current servers. A node isn't a
plain host and port if its host or port is empty, if its host is an IPv6
address in brackets, or if its host or port has a character, such as `/`,
`?` or `@`, that would change the host or port or add credentials, as
`h/x` on port 22122 used to give `h` on port 11211; an empty host used to
give `127.0.0.1`, and an empty port failed only at the first request. A
version of more than 64 bytes in the endpoint's version reply fails
discovery too, where parsing it took time that grew faster than the square
of its length. Discovery's errors escape the text they quote from the
endpoint and cut it to 200 characters, as `displayException` does for a
`MemcacheError`. The refresh thread runs with asynchronous exceptions
unmasked, even when `newClient` is called with them masked, as in the
acquire action of a `bracket`, so that each refresh's time limit can
interrupt it.
- In `getMany`, `setMany` and `deleteMany`, a bare `EN` (a miss reply
without an opaque) now counts as the reply to the next request. One after
the reply to the batch's last request throws `UnexpectedResponse`, and so
does a reply to a request that a bare `EN` was counted for, or to an
earlier one, so a server that sends bare `EN`s without end can no longer
keep a batch reading.
- `stats` now closes each connection it reads a reply from, instead of
returning it to the pool, so a later request to each server opens a new
one in its place. A key holding a line break, which `stats cachedump` can
list as it is stored, could end the reply early as `stats` read it, and
the rest of the reply was then read as the reply to a later request on the
same connection. The bytes after such a line break are still read as lines
of their own, so they can add entries or end the reply early, but `stats`
no longer sends its request again or marks the server dead when they make
an empty line, or a `SERVER_ERROR` line naming no status: after a reply's
first line, it throws the error of any empty or error line once every
server has answered.
- Numbers in replies (value lengths, CAS versions, flags and counter values)
are read only as plain decimal digits that fit their type, as memcached
writes them (see Breaking changes), where they used to be read leniently,
as with `(5)` or `0x10`, or wrapped around to fit. A value length in any
other form, or a `VA` reply without one, throws `BadLength`; such a `VA`
reply used to read as a hit with an empty value. A CAS version, flags or
counter value in any other form reads as 0, as a missing one does, so such
a CAS skips the check when passed back to an operation that takes a
`Version`.
## Documentation and development
- The README and `Database.Memcache.Client` explain why to create one client
and share it, and say more about timeouts, retries and failover, including
which requests are never sent twice. `Database.Memcache.Cluster` documents
routing, failover and upgrading from 0.4, which the README sums up, and
the README has a section on Unix sockets.
- The README and the docs say which error replies count against a server: a
`SERVER_ERROR` whose text names no status, such as memcached's proxy sends
when a backend fails, counts against the server as a timeout does, while
`ERROR`, `CLIENT_ERROR` and a `SERVER_ERROR` that names a status are
thrown at once without counting against it. So behind memcached's proxy, a
request for a key on a failed backend marks the whole proxy dead: at once
if it mustn't be sent twice, and otherwise once its retries get the same
reply. The docs of `Timeout` and `NoServersReady` now say when each is
thrown.
- The docs say what each resource-pool version does with `soNumResources`
and `soNumStripes`. With 0.3, which the bounds allow, a pool has a stripe
for each capability, whatever `soNumStripes` is, so a pool with the
default options holds one connection for each capability, and a thread
takes connections only from its own capability's stripe. With 0.4 or
later, `soNumResources` is split between the stripes, and creating a
client throws an `ErrorCall` if it is smaller than `soNumStripes`.
- New dependency: `cryptohash-md5`, for the MD5 hashes of the ketama ring.
The `spec` test suite now also depends on `directory`, `hashable`, `time`
and `unix` (except on Windows), and `integration` on `unliftio`.
- Expand the test suite. Routing is checked against the servers that
libmemcached-awesome 1.1.4 chooses for the same keys, including its own
test fixture, and `legacyServerForKey` against a copy of 0.4's router.
Mock tests cover the new operations, replies out of step, retries,
failover and pool timeouts, closing connections, connecting to each
resolved address, Unix sockets, and ElastiCache discovery and refreshes.
The integration tests also run against memcached restarted, paused with
`SIGSTOP`, listening on a Unix socket and out of memory, and test
ElastiCache discovery against plain memcached.
- The `integration` test suite needs memcached 1.6.13 or later. With 1.6.10
to 1.6.12, which the library accepts, two of its tests fail, as those
servers answer an `append` or `prepend` with the version the request
carried, or 0, rather than the new one. The documentation of `append` and
`prepend` says so, as passing that 0 back as a version skips the check.
- The `parser` benchmark also times hashing a key, building a ring, finding
a key's server on it and routing a key through a cluster.
- CI runs on the `ubuntu-26.04` runner image, named in the workflows instead
of `ubuntu-latest`, installs the gold linker that older GHCs need there,
keeps its caches per OS release, and uses `freckle/stack-action` 5.7.33.
# 0.4.2.1 - November 18th, 2026
No API changes from 0.4.2.0.
- `set`, `add`, `replace`, `cas`, `append` and `prepend` reject a value
larger than 1GiB, memcached's largest possible item size, with
`OpError ErrValueTooLarge` before sending anything. A value of about 2GiB
or more (longer than 2147483645 bytes) previously made memcached run the
value's bytes as commands, so storing untrusted data could run commands on
the server, and a value over 1GiB could time out, be sent again and mark
the server dead. Such a value no longer reaches the server, so it no
longer makes memcached delete the key's existing value, as memcached does
whenever it rejects a store as too large; a value within 1GiB but over the
server's own limit (`-I`, 1MiB by default) still does. Every operation
that sends a value now evaluates it first, before its timeout starts: an
exception it throws is no longer retried and no longer marks the server
dead, and time spent computing it no longer counts towards
`optsServerTimeout`. The request encoders in `Database.Memcache.Socket`
still encode a value of any length; don't send one longer than 1GiB.
- memcached 1.6.10 or later is now required (previously documented as
1.6.0). memcached before 1.6.10 rejects the meta set command this library
stores values with, without reading the value that follows it, and then
runs the value's bytes as commands, so storing untrusted data could run
commands on the server. Each new connection now asks the server for its
version before it is used: until that check passes, the only requests sent
are the authentication exchange, when credentials are set, and `version`.
A server older than 1.6.10, or any other reply that is neither an error
nor a readable version, is refused with `ProtocolError (UnknownOp ...)`,
whose message quotes the reply; the connection is closed, and the refusal
is not retried and doesn't mark the server dead. An error reply, such as
`CLIENT_ERROR unauthenticated`, throws what it throws for any request, and
so does a reply that can't be parsed, such as an empty line or an overlong
one, which counts against the server. This covers ElastiCache discovery,
which now fails for a cluster running a memcached older than 1.6.10.
Through a proxy, the check sees only the proxy's version, so every
memcached behind it must be 1.6.10 or later too. Each new connection that
an operation opens takes one more round trip, which counts towards
`optsServerTimeout`. Connections made directly with
`Database.Memcache.Socket.newConnection` are not checked; send
`storeRequest` and `modifyRequest` only to 1.6.10 or later.
# 0.4.2.0 - October 20th, 2026
No API changes from 0.4.0.0. This is the first Hackage release since 0.4.0.0,
so it also includes the 0.4.1.0 changes below.
- Fix `getMany` returning one key's value under another key's name when a
plain key equals the other's base64 form, such as `"IA=="` and `" "`.
- Requests that carry a value or a number are now encoded into a single
buffer instead of a chain of appends that copied the value once per piece.
Encoding a 64KiB `set` takes about 4µs instead of about 57µs.
- Document that a `Version` of `0` skips the CAS check, what `cas`, `replace`,
`append`, `prepend` and `delete` do for a missing key or a version mismatch,
and when `increment` and `decrement` create a missing key. Add the missing
`OverloadedStrings` to the usage examples in `Database.Memcache.Client` and
the package description, add usage and development instructions to the
README, and replace the template `SECURITY.md` with a full security policy.
# 0.4.1.0 - October 19th, 2026
Not uploaded to Hackage; these changes first ship there in 0.4.2.0. No API or
behaviour changes from 0.4.0.0.
- Reading a large value no longer allocates memory quadratic in its size. Each
receive is now capped at 64KiB, so fetching a 32MiB value allocates about
67MB rather than about 1.7GB.
- Drop the dependency on `errors` (and, through it, `safe` and
`transformers-compat`), which was only used for a one-line helper.
- Replace the hpack `package.yaml` with a hand-written `memcache.cabal`
(`cabal-version: 3.0`) that lists the exposed modules explicitly and gives
each component only the dependencies it uses. Remove `Setup.hs`, which only
did what `build-type: Simple` does anyway. The license field is now the SPDX
identifier `BSD-3-Clause`; the license itself is unchanged.
- Declare support for GHC 9.2 to 9.14 in `tested-with`.
- Fix the `parser` benchmark, which no longer compiled, and extend it to cover
key encoding, more requests, and reading CAS, flags and numbers out of
responses.
- Expand the package description. Hackage already shows it, as a revision of
0.4.0.0.
- Document the `InvalidAuthentication` and `KeyTooLong` constructors of
`ClientError`, and fix typos in the Haddock documentation.
- Greatly expand the test suite. Unit tests against mock servers now cover
every request encoder and client operation, retries and failover,
authentication, `parseServerSpec` and ElastiCache discovery, and the
integration tests also run against memcached in `-Y` auth-file mode and
against a three-server cluster.
- CI builds and tests with cabal on GHC 9.2 to 9.14 and from the source
distribution, builds the library against the oldest dependency versions the
bounds allow, and runs weekly, as well as building with Stack and running
HLint and weeder.
# 0.4.0.0 - October 19th, 2026
- Replace the deprecated binary protocol with buffered Meta Text requests.
- Add base64 binary-key support, `getMany`, hspec tests, and `Auth`.
- Remove binary protocol and builder dependencies.
- Replace request/response wrapper types with direct Meta Text encoders and `Response`.
- Authentication now uses the server's experimental `-Y authfile` mode
(introduced in memcached 1.5.15) instead of binary `-S` SASL.
- `encodeKey` now returns a validated `WireKey`; request builders and the
low-level `keyedOp` APIs accept encoded keys to avoid partial validation and
repeated encoding.
- Requires memcached 1.6.0 or newer for the meta commands.
- `stats` returns `[(Server, StatResults)]` rather than
`[(Server, Maybe StatResults)]`; the `Nothing` case was unreachable. Stat
values containing spaces are no longer truncated, and stats arguments may
now contain spaces (`stats cachedump 1 100`).
- `Status` loses `ErrInvalidArgs` and `ErrUnknownCommand`, which have no Meta
Text equivalent and now surface as `ProtocolError`. `ErrValueTooLarge`,
`ErrOutOfMemory` and `ErrValueNonNumeric` are recovered from the server's
error text so they keep being reported as `OpError`.
- A command the server rejects (`ERROR`, `CLIENT_ERROR`) or answers with an
operation status is no longer retried, and no longer counts towards marking
a server dead.
- `getMany` writes each batch in a single bounded send, so a large key list
cannot deadlock against the server's replies.
- Response lines are capped at 8KiB, bounding memory use on a desynchronised
connection.
- Authentication first checks that the server is in auth-file mode and
refuses to send credentials otherwise, so they are never stored as a plain
`auth` item. Credentials with a forbidden delimiter, or a server that isn't
in auth-file mode, raise `ClientError InvalidAuthentication`, and
credentials the server rejects raise `OpError TextAuthFail`. Neither is
retried or marks the server dead.
- Empty keys, and keys longer than 250 bytes, are rejected with
`ClientError KeyTooLong` before anything is sent.
- `append` and `prepend` on a missing key return `Nothing` instead of throwing
`OpError ErrItemNotStored`.
- `stats` accepts replies made of lines other than `STAT`, such as those from
`stats reset` and `stats cachedump`.
- `Database.Memcache.Socket` sends and receives on a buffered `Connection`
with `sendRaw` and `recvResponse`, replacing `send` and `recv`.
- ElastiCache auto discovery no longer holds the server list lock while
waiting for the next refresh.
- Exception helpers now come from `unliftio`, which is a new dependency.
- Library dependencies declare lower bounds, set to the oldest versions CI
builds against (GHC 9.2, Stackage LTS 20.26).
- Depend on `data-default` instead of the deprecated `data-default-class`,
which is now a compatibility shim over `data-default` 0.8.
- Add `Database.Memcache.ElastiCacheClient`, which creates a client from an
Amazon ElastiCache configuration endpoint and refreshes its node list on an
interval.
- Add `parseServerSpec`, which reads a `ServerSpec` from a `memcached://` URI.
- `Options` gains `optsServerOptions`, whose `ServerOptions` set the size,
stripes and keep-alive of each server's connection pool, and
`optsServerSpecsToServers`, which controls how servers are created.
`Database.Memcache.Server` exports `newServerDefault` in place of
`newServer`.
# 0.3.0.2 - March 27th, 2024
- Make the key hashing algorithm configurable by clients -- that is, let
clients provide a function mapping a key to a server.
# 0.3.0.1 - January 17th, 2021
- No changes, needed a new release to fix a Hackage upload issue.
# 0.3.0.0 - January 17th, 2021
- Bump package dependencies for newer GHC/back/network.
- Update code to work with newer dependencies.
# 0.2.0.1 - November 2nd, 2016
- Fix compatibility with latest `data-default-class`
- Add new ReqRaw type for external clients to implement custom requests. Quite
a hack right now, so behind a WARNING pragma.
# 0.2.0.0 - May 27th, 2016
- Big design change to reduce code duplication (`Protocol` module gone).
- Remove `Options` type - just fixed configuration for now.
- Design change also allows proper retry handling on operation failure - we
retry an operation against the same server, but after N consecutive failures,
we mark the server as dead and don't try using it again until M seconds has
passed.
- Simplify exception hierarchy - just one type `MemcacheError` now for
exceptions.
- Remove `defaultOptions` and `defaultServerSpec`, will revisit usefulness.
- Remove many `Typeable` instances.
- Support better testing with a mock Memcached server.
- Fix bug in socket handling - detected EOF properly.
- Greatly improve documentation.
- Use `data-default-class` for defaults of servers and options.
# 0.1.0.1 - February 26th, 2016
- Consistent usage of 'memcached' instead of 'memcache'.
- Document `Database.Memcache.Client`.
- Add inline pragmas in appropriate places.
- Fix bug handling fragmented IP packets (Alfredo Di Napoli).
# 0.1.0.0 - May 18th, 2015
- First proper release (although still lots of rough edges!).
- Filled out `Data.Memcache.Client` to a complete API.
- Integrated cluster and authentication handling.
- Better error and exception handling.
- Fix compilation under GHC 7.10.
# 0.0.1 - May 5th, 2015
- Initial (incomplete) support for a cluster of memcached servers.
- Fixed compilation under GHC 7.4.
# 0.0.0 - August 23rd, 2013
- Initial release. Support for a single server.