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.

[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]

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.

[madolson]

My concern is also package_size won't really be actively maintained at all, so it will also quickly fall out of date. I think we should omit it.

[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 :)

[madolson]

I agree. Let's let the github be the main access page, and then individuals can include links like twitter there.

[avifenesh]

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

[madolson]

I would ask we should probably stop adding features here, and just get the current list up to date. This PR has been open for awhile, and it's probably for the best to get it merged.

[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.

[madolson]

The main repo seems to be using an MIT license, is it actually proprietary?

[liorsve]

@zuiderkwast @madolson I removed package_size, and added version and version date. So updated view of how this looks like -

[zuiderkwast]

LGTM.

Can you merge the latest main into this branch?

We should mention the latest changes in the client maintainers meeting. We discussed it last time and some things have changed since then.