Introduce Valkey client overview

[asafpamzn]

• Created a new document that provides an overview of recommended Valkey clients across various programming languages.
• Included mandatory features required for each client, such as Cluster Support and TLS/SSL Support.
• Detailed advanced features supported by the clients, including:
  • Read from Replica
  • Exponential Backoff to Prevent Storm
  • Valkey Version Compatibility
  • PubSub State Restoration
  • Cluster Scan
  • Latency-Based Read from Replica
  • Client-Side Caching
• Added feature comparison tables for each programming language (Python, JavaScript/Node.js, Java, Go, PHP, C#) to highlight the unique capabilities of each client.
• Placeholder sections for Ruby and other languages marked as TODO for future updates.
• References section includes a link to the official Valkey documentation.

[ranshid]

@asafpamzn Thank you for that initiative. it was discussed several times that we need some feature support metric for known clients.

Several high level remarks:

1. our new process for introducing new features/documentations which will require some discussion is to create a suggestion in valkey-rfc first. I suggest you create one there.
2. I am wondering if a separate table for each language is better than a single flat table also indicating the supported language? (eg. for glide it would state comma separated list of languages and a single one for others)?
3. I would think we need to discuss which features are important to indicate. For example inline protocol support, binary protocol, functions, client algorithms etc... WDYT?

[asafpamzn]

@ranshid , thanks for the feedback.

1. Sure, will do.
2. I think that usually users are having a single language or 2, it will be more convenient to jump to the relevant part at the doc.
3. This is just a draft PR and proposal. I agree that we should discuss, what should be the forum? Can we discuss in this PR or do we need additional process?

[asafpamzn]

@ranshid , @zuiderkwast ,

I updated the PR according to your comments.
Who should I work with on this PR to merge it to the website?

[madolson]

I like the summary overall. @rueian @yangbodong22011 Would also be great if you can review this.

[yangbodong22011]

I think we can put all clients Feature Comparison Table in one tables.

Name	Language	Mode Support	Recommend Version	Connection Mode	SSL Support	Cluster Advanced Command	Read from replica	Exponential backoff to prevent storm	Valkey version compatibility	PubSub state restoration	Cluster Scan	Latency-Based Read from Replica	Client Side Caching	RESP3	Async API	Auto reconnect when network down
valkey-java	Java	standalone/sentinel/cluster	5.3.0+	connection pool	Yes	No	No	No	7.2	No	No	No	No	Yes	No	Yes
...

[zuiderkwast]

I think we can put all clients Feature Comparison Table in one tables.

I like this idea.

If the table is large, it can be messy to maintain it as Markdown.

If we have one JSON file per client (like we have for the old redis clients still in this repo), we could add this information in the JSON files and render the table on the website.

[yangbodong22011]

I think we can put all clients Feature Comparison Table in one tables.

I like this idea.

If the table is large, it can be messy to maintain it as Markdown.

If we have one JSON file per client (like we have for the old redis clients still in this repo), we could add this information in the JSON files and render the table on the website.

agree👍

[asafpamzn]

I think we can put all clients Feature Comparison Table in one tables.

I like this idea.
If the table is large, it can be messy to maintain it as Markdown.
If we have one JSON file per client (like we have for the old redis clients still in this repo), we could add this information in the JSON files and render the table on the website.

agree👍

I don't agree, usually customers are first choosing the language and next the client, the client is a small part at the application, basically a driver. I don't think that the average reader will care about clients in other languages. I do agree that for the valkey maintainers it is a better view.

[mcollina]

lgtm

[zuiderkwast]

We need to decide where to put this document.

[zuiderkwast]

I finally had some time to look and think about this.

I have added some comment on some random lines of code, just to get separate threads for each of them.

Did we discuss information about which Valkey version each client supports, or works with, or is tested with? Have we considered some field like this?

"tested-with": ["7.2.7", "8.0.2"]

[zuiderkwast]

Someone (don't remember who) said that we should skip "version", since it is likely to become outdated if client maintainers don't update this information regularly. Isn't it the same situation with package size? A package size is for a specific version, so they're connected.

Even the information about supported features is describing a particular version of each client, and this too may become outdated.

I believe this is a risk with almost all information we put in these files. It's also what happened with the old JSON files. I don't have a solution to this problem, but I have an idea. We can show a timestamp of when the page was last modified. Then the readers can judge for themselves if the information is relevant or outdated.

Or maybe better than last-modified, we can include the date when the last version was released. This is what Wikipedia does in the info-box about software, such as Valkey. If it is a long time ago, it either means that the client is dead or the information is outdated. Possibly, we can even hide clients automatically if it hasn't been updated for years.

So, my idea is that we include two fields such as

    "version": "1.0.3",
    "version-released": "2024-12-01",

[zuiderkwast]

@valkey-io/client-maintainers please share your thoughts, mainly regarding how to be resilient to outdated information about clients.

[yangbodong22011]

I agree remove package_size field, this is what package download sites like maven and pypi should do.

[zuiderkwast]

@yangbodong22011 thanks, and what about version and date? Skip it or include it?

IMO without version, readers can't know if the features supported are about the latest version and if this information is updated or not.

[zuiderkwast]

We discussed this in a meeting with client maintainers and it was mentioned that we'll probably never want to show the old Redis clients, so I think we should simply delete these old JSON files. It's always possible to find them in the git history if we ever want them again.

[zuiderkwast]

Regarding the paths for these new files, I think it should be clients/go/valkey-go.json. The client-page-client shouldn't be in the path. This is information about clients and it can theoretically be used for other things, not tied to be used a specific website page.

[liorsve]

yup, if we're fine with deleting the old Redis clients it sounds like the right thing anyway

[zuiderkwast]

Yes, I'm fine with deleting it. It's not like it's gone forever. It's in the git history if we want it back.

Maybe open a separate PR to delete it? We can merge it before this PR.

[liorsve]

Will do

[liorsve]

#219

[zuiderkwast]

Merged. :)

[zuiderkwast]

We should describe the fields of these JSON files in the README file of this repo, or possibly in a separate clients/README.md if it's too much information for the main README.

[zuiderkwast]

Another field I think we should have is "license". We can use the SPDX License Identifier as listed on this page: https://spdx.org/licenses/ as the value.

[liorsve]

Added 👍

[avifenesh]

I finally had some time to look and think about this.

I have added some comment on some random lines of code, just to get separate threads for each of them.

Did we discuss information about which Valkey version each client supports, or works with, or is tested with? Have we considered some field like this?

"tested-with": ["7.2.7", "8.0.2"]

Chat discussion TLDR:
Tested with mainly matters when there are breaking changes. So, in most cases it's a nice to have, but won't say a lot.
The better option raised by @zuiderkwast is to add the features support.
I agree with this one, but I want to offer a bit less strictness when it is not regarding features we discuss and decided that should be transparent, e.g. PubSub State Restoration, Cluster Scan, Client-Side Caching, AZ affinity and so on…
When new features, comparably less significant, are presented, I think it can be up to the project to decide whether to mention it or not.
I do see why I would like to have IFEQ mentioned as supported by Glide in the next few releases, but I don't think some library that doesn't have it implemented has to mention it. It can be disruptive and pull eyes to what is a bit less significant when you choose a library to your need.

[liorsve]

The better option raised by @zuiderkwast is to add the features support. I agree with this one, but I want to offer a bit less strictness when it is not regarding features we discuss and decided that should be transparent, e.g. PubSub State Restoration, Cluster Scan, Client-Side Caching, AZ affinity and so on… When new features, comparably less significant, are presented, I think it can be up to the project to decide whether to mention it or not. I do see why I would like to have IFEQ mentioned as supported by Glide in the next few releases, but I don't think some library that doesn't have it implemented has to mention it. It can be disruptive and pull eyes to what is a bit less significant when you choose a library to your need.

All the feature details are now included in the feature comparison table, with every significant feature having its own dedicated column, so each client has to specify whether they support it or not. So the best option for what you describe might be to include an "Other Supported Features" column as the last column, where clients can list any additional features they offer and the rest don't have mention them. And it can come from an "other supported features" array field in the JSON files. But I think for this to work well there needs to be some alignment on what qualifies to get in that column because it could easily lose uniformity and look bad, for example if one client lists lots of minor features, some of which not that relevant anymore, while another lists none.

[asafpamzn]

Have not we discussed to change it to client libraries?

[liorsve]

It's a remnant from when it was in the topics section, It's not supposed to be here anymore at all. will delete this

[avifenesh]

The better option raised by @zuiderkwast is to add the features support. I agree with this one, but I want to offer a bit less strictness when it is not regarding features we discuss and decided that should be transparent, e.g. PubSub State Restoration, Cluster Scan, Client-Side Caching, AZ affinity and so on… When new features, comparably less significant, are presented, I think it can be up to the project to decide whether to mention it or not. I do see why I would like to have IFEQ mentioned as supported by Glide in the next few releases, but I don't think some library that doesn't have it implemented has to mention it. It can be disruptive and pull eyes to what is a bit less significant when you choose a library to your need.

All the feature details are now included in the feature comparison table, with every significant feature having its own dedicated column, so each client has to specify whether they support it or not. So the best option for what you describe might be to include an "Other Supported Features" column as the last column, where clients can list any additional features they offer and the rest don't have mention them. And it can come from an "other supported features" array field in the JSON files. But I think for this to work well there needs to be some alignment on what qualifies to get in that column because it could easily lose uniformity and look bad, for example if one client lists lots of minor features, some of which not that relevant anymore, while another lists none.

Looks bad for the site or for the client?
Because before we discuss how we make it work for keeping the integrity of all clients, I want to discuss the idea of having some minor apace for uniqueness for each client.
As such, the client can choose what to mention.
Of course, we need to find the balance between this, and between still having all the clients look good, and the site looks good.
But first, is it acceptable to have some uniqueness between the clients?

[yangbodong22011]

Suggested change

	"client_capa_redirect": false,
	"client_capa_redirect": true,

[liorsve]

Added 👍

[yangbodong22011]

I agree remove package_size field, this is what package download sites like maven and pypi should do.

[liorsve]

The better option raised by @zuiderkwast is to add the features support. I agree with this one, but I want to offer a bit less strictness when it is not regarding features we discuss and decided that should be transparent, e.g. PubSub State Restoration, Cluster Scan, Client-Side Caching, AZ affinity and so on… When new features, comparably less significant, are presented, I think it can be up to the project to decide whether to mention it or not. I do see why I would like to have IFEQ mentioned as supported by Glide in the next few releases, but I don't think some library that doesn't have it implemented has to mention it. It can be disruptive and pull eyes to what is a bit less significant when you choose a library to your need.

All the feature details are now included in the feature comparison table, with every significant feature having its own dedicated column, so each client has to specify whether they support it or not. So the best option for what you describe might be to include an "Other Supported Features" column as the last column, where clients can list any additional features they offer and the rest don't have mention them. And it can come from an "other supported features" array field in the JSON files. But I think for this to work well there needs to be some alignment on what qualifies to get in that column because it could easily lose uniformity and look bad, for example if one client lists lots of minor features, some of which not that relevant anymore, while another lists none.

Looks bad for the site or for the client? Because before we discuss how we make it work for keeping the integrity of all clients, I want to discuss the idea of having some minor apace for uniqueness for each client. As such, the client can choose what to mention. Of course, we need to find the balance between this, and between still having all the clients look good, and the site looks good. But first, is it acceptable to have some uniqueness between the clients?

Looks bad both for clients and website IMO, it can look less aesthetic in the table if it's a super long list of features, and also just make the impression that one client has significantly less supported features than another even if it's not the case. But if we're more or less aligned there it can work. Besides that about uniqueness, we can always use the description and specific features fields, but they are indeed less for mentioning minor features, because it would look weird to have minor features described right at the top in the client list and major ones described only in the table at the bottom.

[zuiderkwast]

Just a few comments on the READMEs. Looks good in general.

unblocking this

[rueian]

Isn't this link wired?

[zuiderkwast]

What's weird with the link?

The idea is that you can click on this link on the GitHub web view in this repo, so it is relative to the current directory.

We can remove ./ in the beginning of the link, if this is the weird part?

[zuiderkwast]

Ah!! Is valkey-go a Python client? 🤣 Maybe it's a Go client.

[liorsve]

Fixed, good catch

[rueian]

I also think package_size should be removed. For Go, package_size doesn't seem very useful to users. The portion of the library in the final binary depends not only on the library version but also on how the user uses it and compiles the program.

[liorsve]

I think we're also supporting removing the package size field, and if it's also less relevant for some languages, sounds like regardless of the question of whether we want to include version data, package size should be removed.

@valkey-io/client-maintainers Pinging everyone once again to address the remaining open issues so we can advance towards merging this -

1. Should we maintain version data as @zuiderkwast suggested here?
2. should we include a 'tested_with' field for Valkey versions or some alternative 'additional features' field for more minor features? Would you use this field and maintain it?

[nihohit]

For both 1&2 I support adding the max information, as long as its easy for a user to see if the information is out of date, for example by adding a "entry was last checked & updated on " field.
I doubt that I'll check & update every new feature on every release, and the reader should be able to differentiate between an unmaintained client and an unmaintained entry describing a maintained client.

[zuiderkwast]

as long as its easy for a user to see if the information is out of date, for example by adding a "entry was last checked & updated on " field.

@nihohit I suggested earlier that we put the release date of the version described. If we put "entry was last updated", it may even become outdated while a change is waiting to be merged. We'll end up with "last updated 2025-01-28" merged on 2025-02-10 in the commit log. Another way would be to pick the date from git. Not sure if our website generator can do that though.

[tillkruss]

I'm the new owner for the last couple of years.

Suggested change

	"JoL1hAHN"
	"tillkruss"

[liorsve]

So this field is actually a leftover from the old structure of these JSON files, and so it won't be rendered anywhere when this goes to the website. I removed this for all of the other JSON client files as well and left it here by mistake, so I think It's better to just remove this field altogether :)

[avifenesh]

I think that credentials providers integration should also be part of the features.

[tillkruss]

Any change you can add Relay as well?

{
    "name": "Relay",
    "description": "Next-generation caching layer for Valkey/Redis.",
    "repo": "https://github.com/cachewerk/relay",
    "installation": "https://relay.so/docs/installation",
    "language": "php",
    "package_size": "2.5M",
    "license": "Proprietary",
    "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": true,
    "client_capa_redirect": false,
    "persistent_connection_pool": true
}

[zuiderkwast]

Proprietary? I'd say no to that. We do open source only.