diff --git a/README.md b/README.md index b448f8ca..fe0383ab 100644 --- a/README.md +++ b/README.md @@ -61,13 +61,13 @@ They are maintained by their original developers. All clients are listed under language specific sub-folders of [clients](./clients) -The path follows the pattern: ``clients/{language}/github.com/{owner}/{repository}.json``. +The path follows the pattern: ``clients/{language}/{repository}.json``. The ``{language}`` component of the path is the path-safe representation of the full language name which is mapped in [languages.json](./languages.json). -Each client's JSON object represents the details displayed on the [clients documentation page](https://valkey.io/clients/). +Each client's JSON object represents the details displayed on the [clients documentation page](https://valkey.io/clients/), which are also detailed in [clients/README.md](clients/README.md). -For example [clients/python/github.com/valkey-io/valkey-go.json](./clients/python/github.com/valkey-io/valkey-go.json): +For example [clients/go/valkey-go.json](./clients/go/valkey-go.json): ```json { diff --git a/clients/README.md b/clients/README.md new file mode 100644 index 00000000..1feef692 --- /dev/null +++ b/clients/README.md @@ -0,0 +1,35 @@ +# Clients Documentation + +This repo contains the detailed JSON files specifying client libraries. It is used for generating contect for the [clients documentation page](https://valkey.io/clients/) + +## JSON Fields +Each JSON file includes general fields as well as boolean feature fields, specifying whether the client supports them or not. + +### General Fields + +1. **`description`** - a short despcription of the library, mostly taken from their repos. +2. **`repo`** - the url to the library's repo. +3. **`installation`** - an installation command from the most used package manager in the respective language. +4. **`language`** - the programming language in which the library is written. +5. **`package_size`** - the library's unpacked package size, including dependencies. + +### Feature Fields +1. **`read_from_replica`** - The ability to read data from a replica node, which can be useful for load balancing and reducing the load on the primary node. This feature is particularly important in read-heavy applications. + +2. **`smart_backoff_to_prevent_connection_storm`** - A strategy used to prevent connection storms by progressively updating the wait time between retries when attempting to reconnect to a Valkey server. This helps to reduce the load on the server during topology updates, periods of high demand or network instability. + +3. **`pubsub_state_restoration`** - The ability to restore the state of Pub/Sub (publish/subscribe) channels after a client reconnects. This feature ensures that clients can continue receiving messages after disconnections or topology updates such as adding or removing shards, for both legacy Pub/Sub and sharded Pub/Sub. The client will automatically resubscribe the connections to the new node. The advantage is that the application code is simplified, and doesn’t have to take care of resubscribing to new nodes during reconnects. + +4. **`cluster_scan`** - This feature ensures that the user experience and guarantees for scanning a cluster are identical to those for scanning a single node. The SCAN function operates as a cursor-based iterator. With each command, the server provides an updated cursor, which must be used as the cursor argument in subsequent calls. A complete iteration with SCAN retrieves all elements present in the collection from start to finish. If an element exists in the collection at the beginning and remains until the end of the iteration, SCAN will return it. Conversely, any element removed before the iteration begins and not re-added during the process will not be returned by SCAN. A client supporting this feature ensures the scan iterator remains valid even during failovers or cluster scaling (in or out) during the SCAN operation. + +5. **`latency_based_read_from_replica`** - This feature enables reading data from the nearest replica, i.e., the replica that offers the best latency. It supports complex deployments where replicas are distributed across various distances, including different geographical regions, to ensure data is read from the closest replica, thereby minimizing latency. + +6. **`AZ_based_read_from_replica`** - This feature enables reading data from replicas within the same Availability Zone (AZ). When running Valkey in a cloud environment across multiple AZs, it is preferable to keep traffic localized within an AZ to reduce costs and latency. By reading from replicas in the same AZ as the client, you can optimize performance and minimize cross-AZ data transfer charges. For more detailed information about this feature and its implementation, please refer to [this link.](https://github.com/valkey-io/valkey/pull/700) + +7. **`client_side_caching`** - Valkey client-side caching is a feature that allows clients to cache the results of Valkey queries on the client-side, reducing the need for frequent communication with the Valkey server. This can significantly improve application performance by lowering latency, reducing the network usage and cost and reducing the load on the Valkey server. + +8. **`client_capa_redirect`** - The `CLIENT CAPA redirect` feature was introduced in Valkey 8 to facilitate seamless upgrades without causing errors in standalone mode. When enabled, this feature allows the replica to redirect data access commands (both read and write operations) to the primary instance. This ensures uninterrupted service during the upgrade process. For more detailed information about this feature, please refer to [this link.](https://github.com/valkey-io/valkey/pull/325) + +9. **`persistent_connection_pool`** - This feature enables the Valkey client to maintain a pool of persistent connections to the Valkey server, improving performance and reducing overhead. Instead of establishing a new connection for each request, the client can reuse existing connections from the pool, minimizing the time and resources required for connection setup. + +10. **`specific_properties`** - An array field to specify any additional language or client specific properties that might not be relevant to all of the other clients (i.e. sync/async support for python clients). \ No newline at end of file diff --git a/clients/go/valkey-go.json b/clients/go/valkey-go.json new file mode 100644 index 00000000..00af9407 --- /dev/null +++ b/clients/go/valkey-go.json @@ -0,0 +1,19 @@ +{ + "name": "valkey-go", + "description": "A fast Golang Valkey client that does auto pipelining and supports server-assisted client-side caching.", + "repo":"https://github.com/valkey-io/valkey-go", + "installation": "go get github.com/valkey-io/valkey-go", + "version": "1.0.54", + "version_released":"2025-02-03", + "language":"go", + "license": "Apache-2.0", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": true, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": true, + "client_side_caching": true, + "client_capa_redirect": false, + "persistent_connection_pool": true +} diff --git a/clients/java/valkey-GLIDE.json b/clients/java/valkey-GLIDE.json new file mode 100644 index 00000000..f1f2f7ba --- /dev/null +++ b/clients/java/valkey-GLIDE.json @@ -0,0 +1,28 @@ +{ + "name": "valkey GLIDE", + "description": "Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python.", + "repo":"https://github.com/valkey-io/valkey-glide/tree/main/java", + "installation": [ + { + "type": "Maven", + "command": "\n io.valkey\n valkey-glide\n LATEST\n" + }, + { + "type": "Gradle", + "command":"implementation 'io.valkey:valkey-glide:+" + } + ], + "version":"v1.2.1", + "version_released":"2025-12-29", + "language":"java", + "license": "Apache-2.0", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": true, + "cluster_scan": true, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": true, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": false +} \ No newline at end of file diff --git a/clients/java/valkey-java.json b/clients/java/valkey-java.json new file mode 100644 index 00000000..56cf4b7e --- /dev/null +++ b/clients/java/valkey-java.json @@ -0,0 +1,29 @@ +{ + "name": "valkey-java", + "description": "valkey-java is Valkey's Java client, dedicated to maintaining simplicity and high performance.", + "repo":"https://github.com/valkey-io/valkey-java", + "installation": [ + { + "type": "Maven", + "command": "\n io.valkey\n valkey-java\n LATEST\n" + }, + { + "type": "Gradle", + "command":"implementation 'io.valkey:valkey-java:+'" + + } + ], + "version":"v5.3.0", + "version_released":"2024-08-08", + "language":"java", + "license":"MIT", + "read_from_replica": false, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": false, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": false, + "client_side_caching": false, + "client_capa_redirect": true, + "persistent_connection_pool": true +} diff --git a/clients/node.js/iovalkey.json b/clients/node.js/iovalkey.json new file mode 100644 index 00000000..101a2a60 --- /dev/null +++ b/clients/node.js/iovalkey.json @@ -0,0 +1,19 @@ +{ + "name": "iovalkey", + "description": "A robust, performance-focused and full-featured Redis client for Node.js.", + "repo":"https://github.com/valkey-io/iovalkey", + "installation": "npm install iovalkey", + "version":"v0.3.0", + "version_released":"2025-01-23", + "language":"node.js", + "license":"MIT", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": false, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": false, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": true +} \ No newline at end of file diff --git a/clients/node.js/valkey-GLIDE.json b/clients/node.js/valkey-GLIDE.json new file mode 100644 index 00000000..34d2adb3 --- /dev/null +++ b/clients/node.js/valkey-GLIDE.json @@ -0,0 +1,19 @@ +{ + "name": "valkey GLIDE", + "description": "Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python.", + "repo":"https://github.com/valkey-io/valkey-glide/tree/main/node", + "installation": "npm install valkey-glide", + "version":"v1.2.1", + "version_released":"2025-12-29", + "language":"node.js", + "license": "Apache-2.0", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": true, + "cluster_scan": true, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": true, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": false +} \ No newline at end of file diff --git a/clients/php/phpredis.json b/clients/php/phpredis.json new file mode 100644 index 00000000..4624ce5c --- /dev/null +++ b/clients/php/phpredis.json @@ -0,0 +1,19 @@ +{ + "name": "phpredis", + "description": " A PHP extension for Redis, offering high performance and a native API.", + "repo":"https://github.com/phpredis/phpredis", + "installation": "pecl install redis", + "version":"6.1.0", + "version_released":"204-10-05", + "language":"php", + "license": "PHP-3.01", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": false, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": false, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": true +} \ No newline at end of file diff --git a/clients/php/predis.json b/clients/php/predis.json new file mode 100644 index 00000000..0a71dd92 --- /dev/null +++ b/clients/php/predis.json @@ -0,0 +1,19 @@ +{ + "name": "predis", + "description": "A flexible and feature-complete Redis client for PHP.", + "repo":"https://github.com/predis/predis", + "installation": "composer require predis/predis", + "version":"v2.3.0", + "version_released":"2024-11-21", + "language":"php", + "license": "MIT", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": false, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": false, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": false +} \ No newline at end of file diff --git a/clients/python/valkey-GLIDE.json b/clients/python/valkey-GLIDE.json new file mode 100644 index 00000000..d29c0ce2 --- /dev/null +++ b/clients/python/valkey-GLIDE.json @@ -0,0 +1,20 @@ +{ + "name": "valkey GLIDE", + "description": "Valkey GLIDE is designed for reliability, optimized performance, and high-availability, for Valkey and Redis OSS based applications. GLIDE is a multi language client library, written in Rust with programming language bindings, such as Java, node.js and Python.", + "repo":"https://github.com/valkey-io/valkey-glide/tree/main/python", + "installation": "pip install valkey-glide", + "version":"v1.2.1", + "version_released":"2025-12-29", + "language":"python", + "license": "Apache-2.0", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": true, + "cluster_scan": true, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": true, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": false, + "specific_properties": ["Available in async API"] +} \ No newline at end of file diff --git a/clients/python/valkey-py.json b/clients/python/valkey-py.json new file mode 100644 index 00000000..056f108b --- /dev/null +++ b/clients/python/valkey-py.json @@ -0,0 +1,20 @@ +{ + "name": "valkey-py", + "description": "The Python interface to the Valkey key-value store.", + "repo":"https://github.com/valkey-io/valkey-py", + "installation": "pip install valkey", + "version":"6.0.2", + "version_released":"2024-09-11", + "language":"python", + "license": "MIT", + "read_from_replica": true, + "smart_backoff_to_prevent_connection_storm": true, + "pubsub_state_restoration": false, + "cluster_scan": false, + "latency_based_read_from_replica": false, + "AZ_based_read_from_replica": false, + "client_side_caching": false, + "client_capa_redirect": false, + "persistent_connection_pool": true, + "specific_properties": ["Available in sync and async API"] +} diff --git a/wordlist b/wordlist index 1811a498..19841317 100644 --- a/wordlist +++ b/wordlist @@ -59,10 +59,12 @@ autoload autoloader autoloading Autoloading +AZs B1 B2 B3 backend +Backoff backported backslashed backticks @@ -309,6 +311,7 @@ go-redis Gottlieb gpg Gradle +Golang Hacktoberfest hacktoberfest handleClientsWithPendingWrites @@ -368,6 +371,8 @@ invalidations iojob IOPs iostat +iovalkey +ioredis IoT ip ip:port @@ -589,6 +594,7 @@ perf_events performance-on-cpu PFAIL php-redis-lock +phpredis PHPRedisMutex pid pidfile @@ -633,6 +639,7 @@ programmatically-generated pseudorandom PSR-4 Pubsub +PubSub pubsub PubSub-related Pubsub.