In some circumstances users may have connection pools configured without
any SocketAddresses ready to go. This is particularly likely in service
discovery configurations. Right now, the effect of attempting to use
such a pool is two fold. First, we'll emit a bunch of error level logs
telling users we have no addresses. Second, we'll fall into the
exponential backoff phase of connection establishment.
The first property is annoying, but the second one is actively harmful.
If your construction is timed incorrectly, we'll have the awkward
problem of burning a bunch of CPU trying to create connections we know
we cannot, and then a lengthy delay after the addresses are actually
configured before we start trying to use them. That's the worst of all
worlds.
This patch adds logic to detect the attempt to create connections when
we don't have any configured addresses and delays them. This path should
improve performance and ergonomics when in this mode.
Authored-by: Cory Benfield <lukasa@apple.com>
Motivation:
When `RedisConnection.allowSubscriptions` is set to `false`, the connection could still be in a subscription state
leaving further commands to fail slowly from a full roundtrip to Redis, rather than succeeding as expected.
This changes the implementation so that it triggers a full unsubscribe from patterns and channels when set to `false`.
Modifications:
- Change: `RedisConnection.allowSubscriptions` to call `unsubscribe()` and `punsubscribe()` when set to `false`
- Change: `RedisPubSubHandler` to prefix storage of all dictionary keys to avoid name clashes between pattern and channel subscriptions
Result:
Developers should now have more deterministic and unsurprising behavior with PubSub
in regards to subscription management and connection state.
Motivation:
The methods of unsubscribing from all channels / patterns were not working as expected as they need to be special-case handled.
Modifications:
- Change: `RedisPubSubHandler` to be special-case unsubscribe when no arguments are provided
Result:
Developers should now properly be able to unsubscribe from all channels / patterns with a single method call.
Motivation:
Some Redis commands are very connection specific that have impacts on future access that makes it difficult in the current
checkout-use-return cycle that `RedisConnectionPool` uses.
Developers need a way to borrow a specific connection, chain several commands together, and then return the connection to the pool.
Modifications:
- Add: `leaseConnection` method to `RedisConnectionPool` which provides a connection from the pool and returns it after a provided closure's ELF resolves
- Add: `allowSubscriptions` property to `RedisConnection` for controlling the ability to make PubSub subscriptions
- Add: `RedisClientError.pubsubNotAllowed` case for when `RedisConnection.allowSubscriptions` is set to `false` and a subscription was still attempted
Result:
Developers should now have an "escape hatch" with `RedisConnectionPool` to do limited exclusive chains of operations on a specific connection.
Motivation:
One of the great features of Redis is being able to subscribe and receive messages published to specific channels
as a way of acting as a message queue for processing jobs.
PubSub requires a specific understanding of the connection model that can only be implemented directly in this library.
Modifications:
- Add: `RedisPubSubHandler` to sit in front of `RedisCommandHandler` to manage subscription callbacks and Redis registration
- Add: `publish` and the `pubsub` commands
- Add: `addPubSubHandler` extension to `NIO.Channel`
- Add: Type-safe String wrapper of `RedisChannelName` for PubSub methods
- Add: `pubsubSubscriptionNotFound` error case
- Add: `isSubscribed` property to `RedisConnection`
- Add: `availableConnectionCount` and `leasedConnectionCount` properties to `RedisConnectionPool`
- Add: Metrics for PubSub
- Add: `makeNewPool` factory method to `RedisConnectionPoolIntegrationTestCase`
- Change: `RedisClient` to require methods for PubSub management, as they are intrinsicly tied to the client's connection model
- Change: Parsing of `PING` response for handling special case in PubSub mode
- Rename: `ActiveConnectionGauge` to `RedisMetrics.IncrementalGauge`
Result:
Developers will now be able to use Redis in PubSub mode with both connections and pools.
This resolves#6
Motivation:
The original implementation of Logging was done in more haste than should have been, without proper attention given to the semantic requirements.
As the Swift ecosystem has matured a bit, lessons have been learned on handling metadata and passing of external context into internal subcomponents.
A mixture of the "protocol-based context passing" and "explicit context passing" patterns have been adopted.
Both patterns are more fully described in the Swift forum discussion: https://forums.swift.org/t/the-context-passing-problem/39162
Modifications:
- Add: `RedisLogging` namespace with references to static keys and labels that are used for Logging throughout the library
- Add: `Logger` static computed properties to access the Logger prototypes used in connection and connection pools
- Add: `RedisClientWithUserContext` protocol and `UserContextRedisClient` types to assist with wrapping client types for custom logger contexts
- Remove: `logger` property from `RedisClient` requirements
- Change: Many log statements to have higher or lower log levels for their appropriate context
- Change: `RedisConnection` and `RedisConnectionPool` to conform to `RedisClientWithUserContext`
- Change: `logging(to:)` protocol requirement to return a `RedisClient` existential
- Change: ConnectionPool to explicitly pass a logger instance around for pooling methods
Result:
Logging in RediStack will now have a stronger contract of where and how logs will be generated and which context will be used.
Fixes#79 and #74
Motivation:
The SETEX and PSETEX commands are missing.
Modifications:
- Add SETEX command
- Add PSETEX command
- Add integration tests
Result:
Users can atomically set a key with an expire
Motivation:
SET has a range of options for setting expirations and conditionally
setting a value.
Modification:
- Add another `set` function with a range of options. Options are
modelled as `struct`s backed by private `enum`s to allow additional
options to be added without breaking API.
- Added tests
Result:
Options may be specified with `set`, and resolves#67
Motivation:
Users of Redis will frequently want to be able to run queries in
parallel, while bounding the number of connections they use. They will
also often want to be able to reuse connections, without having to
arrange to manage those connections themselves. These are jobs usually
done by a Connection Pool.
This new connection pool will conform to `RedisClient` so a pool of clients and a single connection are interchangeable.
Connection Pools come in a wide range of shapes and sizes. In NIO
applications and frameworks, there are a number of questions that have
to be answered by any pool implementation:
1. Is the pool safe to share across EventLoops: that is, is its
interface thread-safe?
2. Is the pool _tied_ to an EventLoop: that is, can the pool return
connections that belong on lots of event loops, or just one?
3. If the pool is not tied to an EventLoop, is it possible to influence
its choice about what event loop it uses for a given connection?
Question 1 is straightforward: it is almost always a trivial win to
ensure that the public interface to a connection pool is thread-safe.
NIO makes it possible to do this fairly cheaply in the case when the
pool is only used on a single loop.
Question 2 is a lot harder. Pools that are not tied to a specific
EventLoop have two advantages. The first is that it is easier to bound
maximum concurrency by simply configuring the pool, instead of needing
to do math on the number of pools and the number of event loops. The
second is that non-tied pools can arrange to keep busy applications
close to this maximum concurrency regardless of how the application
spreads its load across loops.
However, pools that are tied to a specific EventLoop have advantages
too. The first is one of implementation simplicity. As they always serve
connections on a single EventLoop, they can arrange to have all of their
state on that event loop too. This avoids the need to acquire locks on
that loop, making internal state management easier and more obviously
correct without having to worry about how long locks are held for.
The second advantage is that they can be used for latency sensitive
use-cases without needing to go to the work of (3). In cases where
latency is very important, it can be valuable to ensure that any Channel
that needs a connection can get one on the same event loop as itself.
This avoids the need to thread-hop in order to communicate between the
pooled connection and the user connection, reducing the latency of
operations.
Given the simplicity and latency benefits (which we deem particularly
important for Redis use-cases), we concluded that a good initial
implementation will be a pool that has a thread-safe interface, but is
tied to a single EventLoop. This allows a compact, easy-to-verify
implementation of the pool with great low-latency performance and simple
implementation logic, that can still be accessed from any EventLoop in
cases when latency is not a concern.
Modifications:
- Add new internal `ConnectionPool` object
- Add new `RedisConnectionPool` object
- Add new `RedisConnectionPoolError` type
- Add tests for new types
Results:
Users will have access to a pooled Redis client.
Motivation:
The SETNX command is missing.
Modifications:
- Add SETNX command
- Add integration test
Result:
Users can set a key only if it does not already exist
Motivation:
The TTL and PTTL commands are missing.
Modifications:
- Add TTL and PTTL commands
- Add integration tests
Result:
- Users can query the ttl in seconds or milliseconds of a key
Motivation:
The EXISTS command was missing.
Modifications:
- Add 'EXISTS' to basic commands
- Add integration tests
Result:
The existence of a key can be checked.
Motivation:
It was noticed that many of the commands are cumbersome to use with boilerplate type casting for each use that can be simplified within the library
by doing type conversion before returning the value to an end user.
Modifications:
Many APIs that return a `RESPValue` now have overloads to provide a `RESPValueConvertible` type that the value will be turned into before being returned.
For a few APIs that returned `RESPValue`, they did so as an Optional. Those APIs have been changed to always provide a `RESPValue` and return `.null` in cases where `nil` was returned.
In addition, the `@inlinable` attribute has been removed from any non-generic command API.
Result:
Developers should have less code boilerplate for turning values from `RESPValue` to their desired type with many commands.
Motivation:
The SortedSet and List range commands (LTRIM, LRANGE, ZRANGE, etc.) are stringly-based and not flexible with Swift syntax.
Modifications:
- Add overloads of LTRIM that support the gambit of Range Standard Library types
- Rework LRANGE to mirror LTRIM method signatures
- Rework ZScore Range based commands to be more type-safe with `RedisZScoreBound` enum
- Rework ZLex Range based commands to be more type-safe with `RedisZLexBound` enum
- Rework ZCOUNT, ZLEXCOUNT, ZRANGE, ZREVRANGE, ZREMRANGEBYLEX, ZREMRANGEBYRANK, ZREMRANGEBYSCORE methods to be more type-safe and support Swift Range syntax
Result:
Working with SortedSet ranges should be much more type safe, and expressive with Swift's Range syntax.
Motivation:
While reviewing the API, the current design does not read well, and still has room for misunderstanding the actual end result of a ZADD operation.
Modifications:
- Rename `RedisSortedSetAddOption` to `RedisZaddInsertBehavior` and update cases to match desired use site syntax.
- Add `RedisZaddReturnBehavior` enum to define how `zadd` should calculate the return value.
- Update `zadd` and its overloads to support the two new enums in the form of `zadd(_:to:inserting:returning:)`
Result:
The more "Swifty" API will make it much more clear to developers at the call site what the actual behavior of the ZADD command will be.
Motivation:
The goal is to have a strong-typed API for type-safety in arbitrary values, such as trying to use
Int to represent time - as '3' could mean any unit of time, leaving many places for errors and bugs.
Modifications:
Switch all current APIs that accept a `timeout` argument to use `NIO.TimeAmount` instead of a plain `Int`.
Result:
Developers will have an easier time reasoning about their own code as to what values might mean when working with
timeouts in Redis APIs.
Motivation:
Inspired by Swift by Sundell's article on type-safe identifers, the goal of this commit is to have the compiler
assist in preventing incorrect Redis key values from being used in API calls.
See https://www.swiftbysundell.com/articles/type-safe-identifiers-in-swift/ for the inspiration.
Modifications:
- Add new `RedisKey` struct that wraps around a single `String` value that conforms to several expected protocols
(Hashable, Comparable, Codable, etc.)
- Change all command APIs to require `RedisKey` rather than plain strings
Result:
When encountering an API requiring a RedisKey, it should be much more apparant at the use site what form a value should take.
Motivation:
Logging is more dynamic in real world usage than the current static heavy API allows.
Users generally want to be capable of updating connection logger metadata to attach dynamic properties such as an HTTP request ID for log tracing.
Modifications:
- Move all logs to `RedisConnection`
- Add `id: UUID` property to `RedisConnection`
- Add `logging` property and `setLogging(to:)` method requirements to `RedisClient`
- Add chainable `logging(to:)` method extension to `RedisClient`
- Add additional `trace` log statements to `RedisConnection`
- Change when `RedisConnection.init` logging and metric calls are made
- Change some `debug` log statements to `trace in `RedisConnection`
Result:
Users should have infinitely more flexibility in how RedisConnection, and RedisClient implementations in general, behave in regards to logging.
Motivation:
For ergonomics, users sometimes want to provide arguments as a variadic list rather than an array.
Modifications:
- Add variadic overloads for almost all methods that accept lists of homogenous types
Result:
Users should have more flexibility in the way arguments are passed to command methods
Motivation:
It is wrong to always assume that a GET operation is expecting a String response type, as users may be storing other types of data.
Modifications:
- Add `get` generic method with a constraint for types of `RESPValueConvertible` to convert values to the user desired type
- Change existing `get` method to specialize the generic overload
- Fix incorrect doc block regarding the ELF failure condition
Result:
Users should now be able to specialize the return type of a "GET" command
Motivation:
After working with RedisKit with RediStackTestUtils as a dependency, it was realized how opinionated the module is in how RedisConnections can be created in test environments.
Modifications:
Require more information, with reasonable defaults for `RedisConnection.init()`. Provide subclass hooks for `RedisIntegrationTestCase` for implementors to make decisions for themselves at how to connect to Redis.
Result:
Users should have more freedom in how they connect to Redis in their units tests.
Motivation:
For users looking to contribute, and for those looking to validate the library, it was unclear what tests require an actual connection to a Redis instance in order to run.
Modifications:
Add a `RediStackIntegrationTests` that takes all tests that require a Redis instance in order to run.
Result:
Those looking to run just unit tests, or contribute new tests, can now directly point to a specific testTarget as defined in the Package manifest.
Fabian Fett
Joannis Orlandos
Nathan Harris
George Barnett
Lukasa