Motivation:
Redis is written in C, so even though it has concepts of "types" such as SortedSet or List
its commands are all "free-floating" functions.
This can make it unfamiliar for those new to Redis to work within its systems and understand the relation of all of the commands.
RediStack can improve this by giving a way of having a consistent reference to a Redis type and all of its associated methods.
Modifications:
- Add: New library product called "RedisTypes"
- Add: First type to "RedisTypes", `RedisSet`
Result:
Newcomers to Redis will have an easier time getting familiar with the APIs and working with its types by having wrappers that
provide a familiar Swift Standard Library API tailored to Redis APIs.
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:
parseInteger did not distinguish between not having enough bytes for an
integer and not being able to parse the integer that was present. This
was a bit tricky for code internally, where some call sites had extra
code looking for spooky action at a distance in order to determine if
the integer failed to parse.
This is unnecessary: parseInteger is sufficiently aware of what's going
on to address this problem itself.
Modifications:
- Added a new parser error (acceptable as we haven't tagged 1.0 yet).
- Throw it from parseInteger if the integer is invalid.
Result:
parseInteger clearly communicates if the integer failed to parse.
Motivation:
ByteBufferView is not zero indexed, but parseSimpleString assumes it is.
Modifications:
- Correctly compute on the distance between two indices.
- New, somewhat contrived, test case.
Result:
No functional change: because RediStack assumes the remote peer will
always correctly terminate with /r/n, there is no point at which this
code could misbehave in the current implementation. However, with small
changes it is possible to trigger it, as the new test demonstrates.
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:
While working to add more test coverage with `RESPTranslator`, it was made apparent that a `.bulkString(.none)` is impossible to create directly with the `RESPValue` initializers, even though it is a reasonable possibility.
Additionally, forcing all integer types to have to be stored in an `Int` is unnecessarily restrictive.
Modifications:
- Change `RESPValue.init(bulk:)` initializers to accept `Optional` instances
- Change `RESPValue.init(bulk:)` for `Int` initializer to be generic on `FixedWidthInteger`
Result:
Converting types to and from `RESPValue` should be more bi-directional and seamless.
Motivation:
Diagnostics for why `.bulkString` parses might fail were weak, and edge cases fell through gaps in coverage were found.
Modifications:
Added new cases to `RESPTranslator.ParsingError` for `.bulkString` parsing with additional test coverage.
Result:
Users should have better diagnostics for bogus data or failed parsing state.
Motivation:
While working on issue #56, it was forgotten to add the new test cases to the linux manifest file.
Modifications:
Update the linux manifests to include all current unit tests
Result:
All written unit tests should be ran on Linux
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.
Motivation:
There is a reasonable way to compare if two `RedisErrors` are equal, which was seen as needed in the `Equatable` conformance for `RESPValue`.
Modifications:
Added `Equatable` conformance for `RedisError` by comparing the messages.
Result:
Two `RedisError` instances are now equatable.
Motivation:
While working on unit tests the need for conformance to `Equatable` for `RESPValue` has been needed a few times and it was decided to make it public.
Modifications:
Added conformance to `Equatable` for `RESPValue` with unit test.
Result:
Users should now be able to compare two `RESPValue` instances for equality.
Motivation:
A handful of times, unit tests were forgotten to be added to the `allTests` extension, or were incorrectly copy/pasted.
Modifications:
Remove manual entries of `allTest` and use generated result from `swift test --generate-linuxmain`
Result:
There should be proper test parity between macOS and Linux.
Motivation:
Issue #60 called for improving the type safety of the options available for the `zadd` command, and MR !70 made some great headway, but attempted to cram too much into a single enum.
Modifications:
- Break the `RedisSortedSetAddOption.returnChangedCount` value into an additional boolean param
Result:
Using `zadd` should now be more straight forward, while being type safe.
Motivation:
To make it a little more generic, and to avoid turnover during renames (such as the planned rebranding in issue #61), `RedisClientError` more accurately reflects the source of the errors, as well as the responsibility of causing the bug.
Modifications:
- Rename `RedisNIOError` to `RedisClientError`
- Rename `RedisError` file to `RedisErrors`
- Add documentation of `RedisClientError`
- Remove no longer used `.unsupportedOperation(method:message:)` value
- Rename `.responseConversion(to:)` to `.failedRESPConversion(to:)`
Result:
Names of `RedisClientError` should be more descriptive, less prone to turnover, and more documented for users to understand the issues related to these thrown errors.
Motivation:
During proposal review, and while working within the codebase, several issues were identified with how `RedisConnection` was architectured.
Modifications:
- Change implementation of `RedisConnection` in some areas for new logic of internal `ConnectionState`
- Change behavior of logging in a few places
- The initializer for `RedisConnection` is now **internal**
- How users can override the default `ClientBootstrap` for a connection is by passing an instance to the `.connect` static method
- Change unit tests to inherit from a common XCTestCase class that handles creation and cleanup of `RedisConnection` in tests
- Remove Redis namespace enum
Result:
The API for `RedisConnection` should be much simpler, with the implementation being less buggy.
This resolves issues #49, #54, and #57.
Motivation:
While working through issue #59, it was noticed just how "stringly" the SortedSet command options for `zadd`, `zinterstore`, and `zunionstore` were, and Swift provides ways of having strong type safety for these options.
Modifications:
- Add `RedisSortedSetAddOption` and `RedisSortedSetAggregateMethod` to replace the String API in `zadd`, `zinterstore`, and `zunionstore`
- Fix an implication of how `overestimatedCountBeingAdded` documentation for `Array where Element == RESPValue` for `add(contentsOf:overestimatedCountBeingAdded:_:)`
Result:
Users should have a more discoverable and straightforward way that isn't error prone for calling `zadd`, `zinterstore`, and `zunionstore` with Redis supported options.
Motivation:
Johannes continues to provide great insight, and correctly pointed out that `RESPValueConvertible` was being used as an "existential" in all cases.
This can cause unexpected type-erasure and introduce unnecessary cost overhead with dynamic dispatch when in most cases we know the exact value we want for `RESPValue` to execute commands.
Modifications:
- Add new extensions to `Array where Element == RESPValue` for appending and adding elements into them
- Change `RedisClient.send(command:with:)` to require `[RESPValue]` instead of `[RESPValueConvertible]` as the `with` argument type
- Change all instances of `RESPValueConvertible` being an "existential" type for method arguments to instead be a generic constraint
Result:
The library should be safeguarded from a class of bugs, with the use of `send` being a bit more straight forward, with some new convenience methods for `[RESPValue]` types.
Motivation:
Johannes provided a fair code review of the project and summarized his findings in issue #48, and one of the prime offenders was all of the `unsafe*` APIs (pointers, buffers, bytes)
that were used with `RESPValue` and `RESPValueConvertible`.
He also provided great feedback and pointed out good points of confusion with the API design of `RESPValue` and `RESPValueConvertible`.
Modifications:
- Return to using `Array` instead of `ContiguousArray` for `RESPValue.array` storage
- Update all documentation to be more thorough in explaining how the types should be used and conformed to.
- Remove all uses of `unsafe*` APIs where possible
- Change implementations to be a lot more type and memory safe, double checking assumptions
- Remove conformance to `ExpressibleBy*Literal` as it is too easy for users to shoot themselves in the foot and saves only a few characters over `.init(bulk:)`
- Create new `RedisNIOTestUtils` target for common test extensions, making them public
- Move most almost all implementations of `RESPValue` computed properties into the `RESPValueConvertible` conformances
Result:
Users should be more safeguarded by the API against unknowingly getting incorrect `RESPValue` representations, the API design of `RESPValue` and `RESPValueConvertible` should be much clearer,
and memory safety should be at a higher bar from these changes.
This resolves issues #55 & #48, and contributes to issue #47.
Motivation:
During proposal review, it was appropriately pointed out that `RedisClient.expire` incorrectly mixes 'deadline' and 'timeout' terminology.
Modifications:
- Change references of 'deadline' to 'timeout' to follow Redis' established semantics for 'EXPIRE'
- Add additional unit test for `RedisClient.expire`
Result:
`RedisClient.expire` should now be more clear as to its semantics and not mix terminology incorrectly.
This contributes to issue #47
Motivation:
During proposal review, it was pointed out that the code with a position index was redundant and error prone over relying on `ByteBuffer`'s `readerIndex`.
Modifications:
Refactored `RESPTranslator` to rely on `ByteBuffer.readerIndex` for position of current parsing cursor,
and eliminated `ParsingResult` enum to instead return `RESPValue?`.
The implementation for writing out `RESPValue` has been expanded to `RESPValueConvertible` and moved to an extension of `ByteBuffer`.
Result:
Parsing `RESPValue` into and out of `ByteBuffer` should be less error-prone and more straight forward.
This contributes to issues #47 and #55
Motivation:
During SSWG review, feedback was provided on the API design of the `RESPValueConvertible.init` signature and how it should appropriately follow Swift Design Guidelines regarding labels.
Modifications:
`RESPValueConvertible.init(_:` is now `RESPValueConvertible.init(fromRESP:)`.
Result:
There should be more clarity at the call site when initializing a type from a `RESPValue`.
This contributes to #47
Motivation:
The default port for Redis is well published to be 6379, and it is common to want to pass this value around or use it as a static default value in methods and initializers.
Modifications:
Add `RedisConnection.defaultPort` static property for all users to use, and update references of the `6379` literals to use new the new property.
Result:
Users should have a reliable default defined to use everywhere to avoid bugs.
Motivation:
`Foundation.Data` was unexpectedly receiving `RESPValueConvertible` conformance through the `Collection` extension which lead to incorrect encoding.
Modifications:
Add explicit conformance to `RESPValueConvertible` for `Data`.
Result:
Users should see their `Data` encoding to RESP format as expected.
Motivation:
Now that the project has migrated from GitHub, it can now fully use GitLab CI.
Modifications:
Removed `circle.yml` and added `.gitlab-ci.yml` files
Result:
GitLab CI should be fully supported
Motivation:
The SSWG has identified a fast approaching reality of namespace clashes in SPM within the ecosystem and has proposed a rule on names that `NIORedis` no longer complies with.
Modifications:
All references to `NIORedis` have been switched to `RedisNIO` as this module name is unique (at least within GitHub's public repositories).
The goals for this name are as follows:
1. To indicate that this is a Redis client library that is built with SwiftNIO
2. That it is a lower level library, as it directly exposes SwiftNIO as an implementation detail
2a. The idea being that a higher level library (`Redis`) will be used, and to "go one level deeper" in the stack, you append the "deeper" `NIO` postfix
3. It follows a naming pattern adopted by Vapor who has expressed their desire to adopt this library as their Redis implementation
Result:
A repository, package name, and module name that are unique across GitHub's public repositories that achives the goals outlined above.
Motivation:
To be a comprehensive library, all commands should be implemented, even if they are highly discouraged. List's collection of commands were missing `brpop`, `blpop`, and `brpoplpush`.
Modifications:
`brpop`, `blpop` and `brpoplpush` are supported with defaults and overloads for an easier API.
Result:
Users now have access to `brpop`, `blpop` and `brpoplpush` commands.
Nathan Harris
George Barnett
Lukasa
Cory Benfield
Nathan Harris
Ondrej Rafaj