protocol-redis 0.8.1 → 0.10.0

data/lib/protocol/redis/methods/streams.rb

@@ -6,115 +6,116 @@
 module Protocol
 	module Redis
 		module Methods
+			# Methods for managing Redis streams.
 			module Streams
 				# Get information on streams and consumer groups. O(N) with N being the number of returned items for the subcommands CONSUMERS and GROUPS. The STREAM subcommand is O(log N) with N being the number of items in the stream.
-				# @see https://redis.io/commands/xinfo
-				# @param help [Enum]
+				# See <https://redis.io/commands/xinfo> for more details.
+				# @parameter help [Enum]
 				def xinfo(*arguments)
 					call("XINFO", *arguments)
 				end
 				
 				# Appends a new entry to a stream. O(1).
-				# @see https://redis.io/commands/xadd
-				# @param key [Key]
-				# @param ID [String]
+				# See <https://redis.io/commands/xadd> for more details.
+				# @parameter key [Key]
+				# @parameter ID [String]
 				def xadd(*arguments)
 					call("XADD", *arguments)
 				end
 				
 				# Trims the stream to (approximately if '~' is passed) a certain size. O(N), with N being the number of evicted entries. Constant times are very small however, since entries are organized in macro nodes containing multiple entries that can be released with a single deallocation.
-				# @see https://redis.io/commands/xtrim
-				# @param key [Key]
-				# @param strategy [Enum]
-				# @param approx [Enum]
-				# @param count [Integer]
+				# See <https://redis.io/commands/xtrim> for more details.
+				# @parameter key [Key]
+				# @parameter strategy [Enum]
+				# @parameter approx [Enum]
+				# @parameter count [Integer]
 				def xtrim(*arguments)
 					call("XTRIM", *arguments)
 				end
 				
 				# Removes the specified entries from the stream. Returns the number of items actually deleted, that may be different from the number of IDs passed in case certain IDs do not exist. O(1) for each single item to delete in the stream, regardless of the stream size.
-				# @see https://redis.io/commands/xdel
-				# @param key [Key]
-				# @param ID [String]
+				# See <https://redis.io/commands/xdel> for more details.
+				# @parameter key [Key]
+				# @parameter ID [String]
 				def xdel(*arguments)
 					call("XDEL", *arguments)
 				end
 				
 				# Return a range of elements in a stream, with IDs matching the specified IDs interval. O(N) with N being the number of elements being returned. If N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1).
-				# @see https://redis.io/commands/xrange
-				# @param key [Key]
-				# @param start [String]
-				# @param end [String]
+				# See <https://redis.io/commands/xrange> for more details.
+				# @parameter key [Key]
+				# @parameter start [String]
+				# @parameter end [String]
 				def xrange(*arguments)
 					call("XRANGE", *arguments)
 				end
 				
 				# Return a range of elements in a stream, with IDs matching the specified IDs interval, in reverse order (from greater to smaller IDs) compared to XRANGE. O(N) with N being the number of elements returned. If N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1).
-				# @see https://redis.io/commands/xrevrange
-				# @param key [Key]
-				# @param end [String]
-				# @param start [String]
+				# See <https://redis.io/commands/xrevrange> for more details.
+				# @parameter key [Key]
+				# @parameter end [String]
+				# @parameter start [String]
 				def xrevrange(*arguments)
 					call("XREVRANGE", *arguments)
 				end
 				
 				# Return the number of entires in a stream. O(1).
-				# @see https://redis.io/commands/xlen
-				# @param key [Key]
+				# See <https://redis.io/commands/xlen> for more details.
+				# @parameter key [Key]
 				def xlen(*arguments)
 					call("XLEN", *arguments)
 				end
 				
 				# Return never seen elements in multiple streams, with IDs greater than the ones reported by the caller for each stream. Can block. For each stream mentioned: O(N) with N being the number of elements being returned, it means that XREAD-ing with a fixed COUNT is O(1). Note that when the BLOCK option is used, XADD will pay O(M) time in order to serve the M clients blocked on the stream getting new data.
-				# @see https://redis.io/commands/xread
-				# @param streams [Enum]
-				# @param key [Key]
-				# @param id [String]
+				# See <https://redis.io/commands/xread> for more details.
+				# @parameter streams [Enum]
+				# @parameter key [Key]
+				# @parameter id [String]
 				def xread(*arguments)
 					call("XREAD", *arguments)
 				end
 				
 				# Create, destroy, and manage consumer groups. O(1) for all the subcommands, with the exception of the DESTROY subcommand which takes an additional O(M) time in order to delete the M entries inside the consumer group pending entries list (PEL).
-				# @see https://redis.io/commands/xgroup
+				# See <https://redis.io/commands/xgroup> for more details.
 				def xgroup(*arguments)
 					call("XGROUP", *arguments)
 				end
 				
 				# Return new entries from a stream using a consumer group, or access the history of the pending entries for a given consumer. Can block. For each stream mentioned: O(M) with M being the number of elements returned. If M is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1). On the other side when XREADGROUP blocks, XADD will pay the O(N) time in order to serve the N clients blocked on the stream getting new data.
-				# @see https://redis.io/commands/xreadgroup
-				# @param noack [Enum]
-				# @param streams [Enum]
-				# @param key [Key]
-				# @param ID [String]
+				# See <https://redis.io/commands/xreadgroup> for more details.
+				# @parameter noack [Enum]
+				# @parameter streams [Enum]
+				# @parameter key [Key]
+				# @parameter ID [String]
 				def xreadgroup(*arguments)
 					call("XREADGROUP", *arguments)
 				end
 				
 				# Marks a pending message as correctly processed, effectively removing it from the pending entries list of the consumer group. Return value of the command is the number of messages successfully acknowledged, that is, the IDs we were actually able to resolve in the PEL. O(1) for each message ID processed.
-				# @see https://redis.io/commands/xack
-				# @param key [Key]
-				# @param group [String]
-				# @param ID [String]
+				# See <https://redis.io/commands/xack> for more details.
+				# @parameter key [Key]
+				# @parameter group [String]
+				# @parameter ID [String]
 				def xack(*arguments)
 					call("XACK", *arguments)
 				end
 				
 				# Changes (or acquires) ownership of a message in a consumer group, as if the message was delivered to the specified consumer. O(log N) with N being the number of messages in the PEL of the consumer group.
-				# @see https://redis.io/commands/xclaim
-				# @param key [Key]
-				# @param group [String]
-				# @param consumer [String]
-				# @param min-idle-time [String]
-				# @param ID [String]
+				# See <https://redis.io/commands/xclaim> for more details.
+				# @parameter key [Key]
+				# @parameter group [String]
+				# @parameter consumer [String]
+				# @parameter min-idle-time [String]
+				# @parameter ID [String]
 				def xclaim(*arguments)
 					call("XCLAIM", *arguments)
 				end
 				
 				# Return information and entries from a stream consumer group pending entries list, that are messages fetched but never acknowledged. O(N) with N being the number of elements returned, so asking for a small fixed number of entries per call is O(1). When the command returns just the summary it runs in O(1) time assuming the list of consumers is small, otherwise there is additional O(N) time needed to iterate every consumer.
-				# @see https://redis.io/commands/xpending
-				# @param key [Key]
-				# @param group [String]
-				# @param consumer [String]
+				# See <https://redis.io/commands/xpending> for more details.
+				# @parameter key [Key]
+				# @parameter group [String]
+				# @parameter consumer [String]
 				def xpending(*arguments)
 					call("XPENDING", *arguments)
 				end

data/lib/protocol/redis/methods/strings.rb

@@ -6,191 +6,192 @@
 module Protocol
 	module Redis
 		module Methods
+			# Methods for managing Redis strings.
 			module Strings
 				# Append a value to a key. O(1). The amortized time complexity is O(1) assuming the appended value is small and the already present value is of any size, since the dynamic string library used by Redis will double the free space available on every reallocation.
-				# @see https://redis.io/commands/append
-				# @param key [Key]
-				# @param value [String]
+				# See <https://redis.io/commands/append> for more details.
+				# @parameter key [Key]
+				# @parameter value [String]
 				def append(key, value)
-					call('APPEND', key, value)
+					call("APPEND", key, value)
 				end
-
+				
 				# Count set bits in a string. O(N).
-				# @see https://redis.io/commands/bitcount
-				# @param key [Key]
+				# See <https://redis.io/commands/bitcount> for more details.
+				# @parameter key [Key]
 				def bitcount(key, *range)
-					call('BITCOUNT', key, *range)
+					call("BITCOUNT", key, *range)
 				end
-
+				
 				# Decrement the integer value of a key by one. O(1).
-				# @see https://redis.io/commands/decr
-				# @param key [Key]
+				# See <https://redis.io/commands/decr> for more details.
+				# @parameter key [Key]
 				def decr(key)
-					call('DECR', key)
+					call("DECR", key)
 				end
-
+				
 				# Decrement the integer value of a key by the given number. O(1).
-				# @see https://redis.io/commands/decrby
-				# @param key [Key]
-				# @param decrement [Integer]
+				# See <https://redis.io/commands/decrby> for more details.
+				# @parameter key [Key]
+				# @parameter decrement [Integer]
 				def decrby(key, decrement)
-					call('DECRBY', key, decrement)
+					call("DECRBY", key, decrement)
 				end
-
+				
 				# Get the value of a key. O(1).
-				# @see https://redis.io/commands/get
-				# @param key [Key]
+				# See <https://redis.io/commands/get> for more details.
+				# @parameter key [Key]
 				def get(key)
-					call('GET', key)
+					call("GET", key)
 				end
-
+				
 				# Returns the bit value at offset in the string value stored at key. O(1).
-				# @see https://redis.io/commands/getbit
-				# @param key [Key]
-				# @param offset [Integer]
+				# See <https://redis.io/commands/getbit> for more details.
+				# @parameter key [Key]
+				# @parameter offset [Integer]
 				def getbit(key, offset)
-					call('GETBIT', key, offset)
+					call("GETBIT", key, offset)
 				end
-
+				
 				# Get a substring of the string stored at a key. O(N) where N is the length of the returned string. The complexity is ultimately determined by the returned length, but because creating a substring from an existing string is very cheap, it can be considered O(1) for small strings.
-				# @see https://redis.io/commands/getrange
-				# @param key [Key]
-				# @param start [Integer]
-				# @param end [Integer]
+				# See <https://redis.io/commands/getrange> for more details.
+				# @parameter key [Key]
+				# @parameter start [Integer]
+				# @parameter end [Integer]
 				def getrange(key, start_index, end_index)
-					call('GETRANGE', key, start_index, end_index)
+					call("GETRANGE", key, start_index, end_index)
 				end
-
+				
 				# Set the string value of a key and return its old value. O(1).
-				# @see https://redis.io/commands/getset
-				# @param key [Key]
-				# @param value [String]
+				# See <https://redis.io/commands/getset> for more details.
+				# @parameter key [Key]
+				# @parameter value [String]
 				def getset(key, value)
-					call('GETSET', key, value)
+					call("GETSET", key, value)
 				end
-
+				
 				# Increment the integer value of a key by one. O(1).
-				# @see https://redis.io/commands/incr
-				# @param key [Key]
+				# See <https://redis.io/commands/incr> for more details.
+				# @parameter key [Key]
 				def incr(key)
-					call('INCR', key)
+					call("INCR", key)
 				end
-
+				
 				# Increment the integer value of a key by the given amount. O(1).
-				# @see https://redis.io/commands/incrby
-				# @param key [Key]
-				# @param increment [Integer]
+				# See <https://redis.io/commands/incrby> for more details.
+				# @parameter key [Key]
+				# @parameter increment [Integer]
 				def incrby(key, increment)
-					call('INCRBY', key, increment)
+					call("INCRBY", key, increment)
 				end
-
+				
 				# Increment the float value of a key by the given amount. O(1).
-				# @see https://redis.io/commands/incrbyfloat
-				# @param key [Key]
-				# @param increment [Double]
+				# See <https://redis.io/commands/incrbyfloat> for more details.
+				# @parameter key [Key]
+				# @parameter increment [Double]
 				def incrbyfloat(key, increment)
-					call('INCRBYFLOAT', key, increment)
+					call("INCRBYFLOAT", key, increment)
 				end
-
+				
 				# Get the values of all the given keys. O(N) where N is the number of keys to retrieve.
-				# @see https://redis.io/commands/mget
-				# @param key [Key]
+				# See <https://redis.io/commands/mget> for more details.
+				# @parameter key [Key]
 				def mget(key, *keys)
-					call('MGET', key, *keys)
+					call("MGET", key, *keys)
 				end
-
+				
 				# Set multiple keys to multiple values. O(N) where N is the number of keys to set.
-				# @see https://redis.io/commands/mset
+				# See <https://redis.io/commands/mset> for more details.
 				def mset(pairs)
 					flattened_pairs = pairs.keys.zip(pairs.values).flatten
 					
-					call('MSET', *flattened_pairs)
+					call("MSET", *flattened_pairs)
 				end
-
+				
 				# Set multiple keys to multiple values, only if none of the keys exist. O(N) where N is the number of keys to set.
-				# @see https://redis.io/commands/msetnx
+				# See <https://redis.io/commands/msetnx> for more details.
 				def msetnx(pairs)
 					flattened_pairs = pairs.keys.zip(pairs.values).flatten
 					
-					call('MSETNX', *flattened_pairs)
+					call("MSETNX", *flattened_pairs)
 				end
-
+				
 				# Set the value and expiration in milliseconds of a key. O(1).
-				# @see https://redis.io/commands/psetex
-				# @param key [Key]
-				# @param milliseconds [Integer]
-				# @param value [String]
+				# See <https://redis.io/commands/psetex> for more details.
+				# @parameter key [Key]
+				# @parameter milliseconds [Integer]
+				# @parameter value [String]
 				def psetex(key, milliseconds, value)
-					call('PSETEX', key, milliseconds, value)
+					call("PSETEX", key, milliseconds, value)
 				end
-
+				
 				# Set the string value of a key. O(1).
-				# @see https://redis.io/commands/set
-				# @param key [Key]
-				# @param value [String]
-				# @param expiration [Enum]
-				# @param update [Boolean, nil] If true, only update elements that already exist (never add elements). If false, don't update existing elements (only add new elements).
+				# See <https://redis.io/commands/set> for more details.
+				# @parameter key [Key]
+				# @parameter value [String]
+				# @parameter expiration [Enum]
+				# @parameter update [Boolean, nil] If true, only update elements that already exist (never add elements). If false, don't update existing elements (only add new elements).
 				def set(key, value, update: nil, seconds: nil, milliseconds: nil)
 					arguments = []
-
+					
 					if seconds
-						arguments << 'EX' << seconds
+						arguments << "EX" << seconds
 					end
-
+					
 					if milliseconds
-						arguments << 'PX' << milliseconds
+						arguments << "PX" << milliseconds
 					end
-
+					
 					if update == true
 						arguments << "XX"
 					elsif update == false
 						arguments << "NX"
 					end
-
-					call('SET', key, value, *arguments)
+					
+					call("SET", key, value, *arguments)
 				end
-
+				
 				# Sets or clears the bit at offset in the string value stored at key. O(1).
-				# @see https://redis.io/commands/setbit
-				# @param key [Key]
-				# @param offset [Integer]
-				# @param value [Integer]
+				# See <https://redis.io/commands/setbit> for more details.
+				# @parameter key [Key]
+				# @parameter offset [Integer]
+				# @parameter value [Integer]
 				def setbit(key, offset, value)
-					call('SETBIT', key, offset, value)
+					call("SETBIT", key, offset, value)
 				end
-
+				
 				# Set the value and expiration of a key. O(1).
-				# @see https://redis.io/commands/setex
-				# @param key [Key]
-				# @param seconds [Integer]
-				# @param value [String]
+				# See <https://redis.io/commands/setex> for more details.
+				# @parameter key [Key]
+				# @parameter seconds [Integer]
+				# @parameter value [String]
 				def setex(key, seconds, value)
-					call('SETEX', key, seconds, value)
+					call("SETEX", key, seconds, value)
 				end
-
+				
 				# Set the value of a key, only if the key does not exist. O(1).
-				# @return [Boolean] if the key was set.
-				# @see https://redis.io/commands/setnx
-				# @param key [Key]
-				# @param value [String]
+				# @returns [Boolean] if the key was set.
+				# See <https://redis.io/commands/setnx> for more details.
+				# @parameter key [Key]
+				# @parameter value [String]
 				def setnx(key, value)
-					call('SETNX', key, value) == 1
+					call("SETNX", key, value) == 1
 				end
-
+				
 				# Overwrite part of a string at key starting at the specified offset. O(1), not counting the time taken to copy the new string in place. Usually, this string is very small so the amortized complexity is O(1). Otherwise, complexity is O(M) with M being the length of the value argument.
-				# @see https://redis.io/commands/setrange
-				# @param key [Key]
-				# @param offset [Integer]
-				# @param value [String]
+				# See <https://redis.io/commands/setrange> for more details.
+				# @parameter key [Key]
+				# @parameter offset [Integer]
+				# @parameter value [String]
 				def setrange(key, offset, value)
-					call('SETRANGE', key, offset, value)
+					call("SETRANGE", key, offset, value)
 				end
-
+				
 				# Get the length of the value stored in a key. O(1).
-				# @see https://redis.io/commands/strlen
-				# @param key [Key]
+				# See <https://redis.io/commands/strlen> for more details.
+				# @parameter key [Key]
 				def strlen(key)
-					call('STRLEN', key)
+					call("STRLEN", key)
 				end
 			end
 		end

data/lib/protocol/redis/methods.rb

@@ -6,27 +6,29 @@
 # Copyright, 2021, by Daniel Evans.
 # Copyright, 2023, by Nick Burwell.
 
-require_relative 'methods/generic'
-require_relative 'methods/connection'
-require_relative 'methods/server'
-require_relative 'methods/cluster'
-require_relative 'methods/geospatial'
+require_relative "methods/generic"
+require_relative "methods/connection"
+require_relative "methods/server"
+require_relative "methods/cluster"
+require_relative "methods/geospatial"
 
-require_relative 'methods/counting'
+require_relative "methods/counting"
 
-require_relative 'methods/hashes'
-require_relative 'methods/lists'
-require_relative 'methods/scripting'
-require_relative 'methods/sets'
-require_relative 'methods/strings'
-require_relative 'methods/streams'
-require_relative 'methods/sorted_sets'
+require_relative "methods/hashes"
+require_relative "methods/lists"
+require_relative "methods/scripting"
+require_relative "methods/sets"
+require_relative "methods/strings"
+require_relative "methods/streams"
+require_relative "methods/sorted_sets"
 
-require_relative 'methods/pubsub'
+require_relative "methods/pubsub"
 
 module Protocol
 	module Redis
+		# A collection of methods for interacting with Redis.
 		module Methods
+			# Includes all Redis methods into the given class.
 			def self.included(klass)
 				klass.include Methods::Generic
 				klass.include Methods::Connection

data/lib/protocol/redis/version.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 module Protocol
 	module Redis
-		VERSION = "0.8.1"
+		VERSION = "0.10.0"
 	end
 end

data/lib/protocol/redis.rb

@@ -3,5 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2019-2023, by Samuel Williams.
 
-require_relative 'redis/version'
-require_relative 'redis/connection'
+require_relative "redis/version"
+require_relative "redis/connection"
+
+# @namespace
+module Protocol
+	# @namespace
+	module Redis
+	end
+end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2019-2023, by Samuel Williams.  
+Copyright, 2019-2024, by Samuel Williams.  
 Copyright, 2020, by Olle Jonsson.  
 Copyright, 2020, by Salim Semaoune.  
 Copyright, 2020, by Dimitry Chopey.  

data/readme.md

@@ -4,40 +4,68 @@ Implements the RESP2 and [RESP3](https://github.com/antirez/RESP3) Redis protoco
 
 [![Development Status](https://github.com/socketry/protocol-redis/workflows/Test/badge.svg)](https://github.com/socketry/protocol-redis/actions?workflow=Test)
 
-## Installation
+## Usage
 
-Add this line to your application's Gemfile:
+Please see the [project documentation](https://socketry.github.io/protocol-redis/) for more details.
 
-``` ruby
-gem 'protocol-redis'
-```
+  - [Getting Started](https://socketry.github.io/protocol-redis/guides/getting-started/index) - This guide explains how to use the `Protocol::Redis` gem to implement the RESP2 and RESP3 Redis protocols for low level client and server implementations.
 
-And then execute:
+## Releases
 
-    $ bundle
+Please see the [project releases](https://socketry.github.io/protocol-redis/releases/index) for all releases.
 
-Or install it yourself as:
+### v0.10.0
 
-    $ gem install protocol-redis
+  - Add agent context.
+  - 100% documentation and test coverage + minor bug fixes.
 
-## Usage
+### v0.9.0
+
+  - Add support for `client info` command.
+
+### v0.8.1
+
+  - Fix HSCAN method implementation.
+
+### v0.8.0
+
+  - Add missing `hscan` method.
+  - Add `mapped_hmget` and `mapped_hmset` methods to match `redis-rb` gem interface.
+  - Add cluster methods to client.
+  - Make hashes methods compatible with redis-rb.
+
+### v0.7.0
+
+  - Add scripting methods to client and fix script interface.
+  - Include sets and streams in the protocol methods.
+  - Add support for essential `exists?` method.
+  - Prefer bake-gem for release management.
 
-``` ruby
-sockets = Socket.pair(Socket::PF_UNIX, Socket::SOCK_STREAM)
+### v0.6.1
 
-client = Protocol::Redis::Connection.new(sockets.first)
-server = Protocol::Redis::Connection.new(sockets.last)
+  - Add support for multi-argument auth.
 
-client.write_object("Hello World!")
-puts server.read_object
-# => "Hello World!"
-```
+### v0.6.0
 
-## Development
+  - Add relevant pubsub method group.
 
-Run tests:
+### v0.5.1
 
-    bundle exec bake test
+  - Add tests for info command, streams, and string methods.
+  - Use correct CRLF constant in server methods.
+  - Modernize gem configuration.
+
+### v0.5.0
+
+  - Add incomplete implementations of scripting, sets and streams.
+  - Merge existing sorted set implementations.
+  - Add `zrangebyscore` method.
+  - Improve argument management.
+  - Modernize testing infrastructure.
+
+### v0.4.2
+
+  - Prefer implicit returns and improve return value for `setnx`.
 
 ## Contributing
 
@@ -48,3 +76,11 @@ We welcome contributions to this project.
 3.  Commit your changes (`git commit -am 'Add some feature'`).
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.