Introduce Valkey client overview #164

asafpamzn · 2024-08-17T20:09:46Z

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.

clients/ValkeyClients.md

ranshid · 2024-08-18T08:28:21Z

@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:

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.
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)?
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 · 2024-08-25T09:12:03Z

@ranshid , thanks for the feedback.

Sure, will do.
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.
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?

clients/ValkeyClients.md

asafpamzn · 2024-09-09T14:17:02Z

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

clients/ValkeyClients.md

yangbodong22011 · 2024-09-10T09:55:36Z

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 · 2024-09-10T12:21:53Z

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 · 2024-09-10T12:24:29Z

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👍

clients/ValkeyClients.md

asafpamzn · 2024-09-15T14:45:28Z

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.

clients/ValkeyClients.md

- 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. Signed-off-by: asafpamzn <[email protected]>

Co-authored-by: Avi Fenesh <[email protected]> Signed-off-by: asafpamzn <[email protected]>

…#159) Update cluster-slots docs ref: valkey-io/valkey#265 --------- Signed-off-by: Roshan Khatri <[email protected]> Signed-off-by: Madelyn Olson <[email protected]> Co-authored-by: Madelyn Olson <[email protected]> Signed-off-by: asafpamzn <[email protected]>

Add documentation for the new `info stats` fields. --------- Signed-off-by: Uri Yagelnik <[email protected]> Signed-off-by: asafpamzn <[email protected]>

Signed-off-by: asafpamzn <[email protected]>

Co-authored-by: Rueian <[email protected]> Signed-off-by: asafpamzn <[email protected]>

Signed-off-by: asafpamzn <[email protected]>

stockholmux · 2024-09-30T16:13:38Z

I think this will become very difficult to maintain if we have it as hand-written markdown.

I'm generally in favour of having it generated from JSON @zuiderkwast suggested.

The question for me is does that get generated as part of docs or website. Related: should this be in the man pages? The information could be useful but if they're mostly links out to GitHub repos it feels like that's more typically something someone would browse from the web, not from a terminal.

asafpamzn · 2024-10-15T13:51:59Z

'm generally in favour of having it generated from JSON @zuiderkwast suggested.

The question for me is does that get generated as part of docs or website. Related: should this be in the man pages? The information could be useful but if they're mostly links out to GitHub repos it feels like that's more typically something someone would browse from the web, not from a terminal.

@stockholmux , why do you think that it will be hard to maintain? It is up on the clients maintainers to update it once new feature is added. It does not happen that frequently.

It should be part of the website, I agree

stockholmux · 2024-10-15T14:22:14Z

@asafpamzn If something is represented as data (i.e. JSON), it's far more maintainable than hand written markdown which is difficult/time consuming to review and audit. As an example, some of the hand written markdown in the content we inherited in this repo was literally a decade out-of-date. No one reported this for years. Data we can query and answer questions quickly.

Additionally, markdown fixes the format in markdown tables which is not sortable or filterable. If it's data, that we have more options.

Finally, If we have it stored as data we can do represent of the data in different ways and in different places not just fixed into a single markdown file.

madolson · 2024-10-15T22:23:36Z

The question for me is does that get generated as part of docs or website. Related: should this be in the man pages? The information could be useful but if they're mostly links out to GitHub repos it feels like that's more typically something someone would browse from the web, not from a terminal.

My intuition is that all the specific client information shouldn't be part of the man pages. I feel like that is getting too low level to be materially useful to most individuals, and the clients are also updated independently from the rest of the code.

Additionally, markdown fixes the format in markdown tables which is not sortable or filterable. If it's data, that we have more options.

I suppose to extend this, we already have JSON files for all of the clients. We could simply extend them to also include all these extra fields which can be used during the render.

liorsve · 2024-11-14T20:06:29Z

Hi all! Joining @asafpamzn in trying to move this PR along.

I only did a short dive so correct me if I'm wrong or missing something (which may very well be the case), but from what I got from your conversation so far, assuming we're not adding to man pages, seems like we need to -

Add the fields to the json client files for the clients mentioned here
Decide where in the website this page goes, and accordingly
Decide whether the markdown gets generated from this repo (like the docs by topic render to the website now for example) or do we move it to the content of the valkey-io.github.io repo (@stockholmux was this your intention here?) Then
Add the html template for the page in valkey-io.github.io that would have a unified table for all clients, and would render the data from the json files.

Did I get it right?
If so, I'll be happy to get to working on these based on what you say :) Also if there's someone I can work with on the website side of this, lmk

Signed-off-by: lior sventitzky <[email protected]>

Update client json files and put client page in topics

liorsve · 2024-11-25T18:46:54Z

Moved the markdown page to content/topics so it would be under docs by topics in the website.
Updated json client files with needed fields (including name changes to some).
a corresponding draft PR for the website for when this PR is merged - #166

zuiderkwast

Great, so there will be a generated list of clients that can display this information?

The old list of clients used to be rendered on the URL redis.io/clients/. Most of our docs are from that time. There are already links to the page where the list of clients is supposed to be, i.e. the ../clients/ directory relative the topics directory.

I used grep to find some of them:

topics/cluster-tutorial.md:322:See the documentation for your [client of choice](../clients/) to determine its cluster support.
topics/eval-intro.md:176:Most of [Valkey' clients](../clients/) already provide utility APIs for doing that automatically.
topics/installation.md:85:You'll find a [full list of clients for different languages in this page](../clients/).
topics/introduction.md:33:You can use Valkey from [most programming languages](../clients/).
topics/ldb.md:234:LDB uses the client-server model where the Valkey server acts as a debugging server that communicates using [RESP](protocol.md). While `valkey-cli` is the default debug client, any [client](../clients/) can be used for debugging as long as it meets one of the following conditions:
topics/quickstart.md:22:The first step is to connect to Valkey. There are client connectors for [most programming languages](../clients/).

The website instead points these links to the page corresponding to topics/clients.md, which is about the handling of client connections (CLIENT LIST, CLIENT KILL, etc.). I don't know why, but I can only guess that it is to avoid broken links. @stockholmux do you want to confirm? Anyway, these links are supposed to point to the list of clients which used to be at the /clients/ URL.

zuiderkwast · 2024-11-25T18:57:27Z

topics/valkey-clients.md

There is already a page called topics/clients.md. It's about inspecting and handling the client connections using commads like CLIENT LIST, CLIENT KILL, etc.

The difference between the names valkey-clients ans clients is not making the difference between these two pages any clearer.

To distinguish them in a meaningful way and still avoid renaming the old one, we could call the new one client-libraries for example.

We have a lot of existing links to valkey.io/clients/ on the web version, this is a hold over from the forked content.

For this file, I'd suggest something like client-list or something equally boring and descriptive.

As far as the valkey.io/clients/ path, once we have some sort of client path, I'll alias any existing links to the new page.

changed the file name to client-list

zuiderkwast · 2024-11-25T19:01:04Z

topics/valkey-clients.md

+title: "Valkey Clients"
+linkTitle: "Valkey Clients"


In the list of pages, we don't want all of them to start with Valkey.

I believe "linkTitle" is used in menues (@stockholmux correct me if I'm wrong!), where we see all of these together, and "title" is the title of the page.

For linkTitle, we don't want to repeat Valkey everywhere. We already have this for half of the pages and it looks like crap. See "Alphabetical index" on the page https://valkey.io/topics/ and scroll down.

Clarification: The page itself doesn't look like crap. It's looks pretty good IMO. But it's not nice that half of them start with "Valkey".

We no longer use linkTitle that was a hold the Jekyll version.

It does no harm but provides no value either.

Good to know. So we can delete linkTitle to avoid confusion.

Should we skip "Valkey" in the page titles then, or use it in all page titles?

@zuiderkwast (Slightly off topic)
Yeah, so it renders as <title>Valkey Documentation · Valkey persistence</title> which is a little silly.

Do you have a need for it to be "Valkey :topic:" vs just ":topic:"? If so, it's pretty trivial to just remove "Valkey" from the title string in the template rendering for things like the alphabetical index and document title. Feel free to put in an issue; I'm chewing through a backlog slowly.

I also have a PR in review that allows for conditional overrides of front matter directly into Zola so in the few edge cases where we might want to preserve 'Valkey' we can.

Yes, I'd like to remove Valkey from all the titles in markdown, so it renders as "Valkey Documentation · Persistence" instead.

The alphabetical index looks especially silly when all or most of the entries start with Valkey.

@viktor See PR that fixes this:
valkey-io/valkey-io.github.io#169

deleted the linkTitle

stockholmux

Good progress, needs a little work

stockholmux · 2024-11-26T15:39:26Z

clients/java/github.com/AWS/valkey-GLIDE.json

@@ -0,0 +1,15 @@
+{


why is this an aws directory? GLIDE is a valkey project not AWS

moved it to the valkey directory

stockholmux · 2024-11-26T15:40:21Z

clients/go/github.com/valkey/valkey-go.json

+    "language":"Go",
+    "read_from_replica": true,
+    "smart_backoff_to_prevent_connection_storm": true,
+    "valkey_version_compatibility": "7.2", 


I don't understand this field: Valkey didn't change the API between 8.0 and 7.2 - what makes it 'compatible'?

Supporting Valkey 8.0 features like AZ affinity, supporting new commands (like script show, cluster slot stats), and commands that were modified in 8.0.

stockholmux · 2024-11-26T15:44:10Z

clients/python/github.com/valkey/valkey-py.json

+    "AZ_based_read_from_replica": false,
+    "client_side_caching": false,
+    "client_capa_redirect": false,
+    "persistent_connection_pool": true


How does this take into account language specific properties? For example IIRC, valkey-py is synchronous or async, GLIDE is async. That's super relevant for someone picking a client in python but not at all for other languages.

There are others I'm sure as well.

Maybe we could add a sentence to the description for this sort of stuff where it seems necessary? I think it's better to put it in the upper part and not in the feature table, it will get messy and the table focuses on the specific features that are explained above.
Do you have other ideas for worth mentioning criteria?

stockholmux · 2024-11-26T15:47:14Z

clients/nodejs/github.com/AWS/valkey-GLIDE.json

+    "client_side_caching": false,
+    "client_capa_redirect": false,
+    "persistent_connection_pool": false
+}


Another relevant property: package size. I'm not sure the metric, but GLIDE is quite large compared to other clients (as it needs to pull down the Rust binary stuff).

stockholmux · 2024-11-26T15:52:11Z

topics/valkey-clients.md

+title: "Valkey Clients"
+linkTitle: "Valkey Clients"


We no longer use linkTitle that was a hold the Jekyll version.

It does no harm but provides no value either.

stockholmux · 2024-11-26T19:52:20Z

topics/valkey-clients.md

We have a lot of existing links to valkey.io/clients/ on the web version, this is a hold over from the forked content.

For this file, I'd suggest something like client-list or something equally boring and descriptive.

As far as the valkey.io/clients/ path, once we have some sort of client path, I'll alias any existing links to the new page.

stockholmux · 2024-11-26T19:59:21Z

topics/valkey-clients.md

+
+- **valkey-glide**
+  - GitHub: [valkey-glide](https://github.com/valkey-io/valkey-glide/tree/main/java)
+  - Installation: Available via Maven and Gradle


My preference would be to have a one-liner for ever Installation: field

added (small code block for Maven)

stockholmux · 2024-11-26T19:59:45Z

topics/valkey-clients.md

+- **Valkey-Java**
+  - GitHub: [valkey-java](https://github.com/valkey-io/valkey-java)
+  - Installation: Available via Maven and Gradle
+  - Description: valkey-java is Valkey's Java client, derived from Jedis fork, dedicated to maintaining simplicity and high performance.


'derived from Jedis fork' redundant?

Removed this

stockholmux · 2024-11-26T19:59:52Z

topics/valkey-clients.md

+-----
+- **valkey-go**
+  - GitHub: [go-valkey-go](https://github.com/valkey-io/valkey-go)
+  - Installation: TBD


stockholmux · 2024-11-26T20:05:23Z

clients/go/github.com/valkey/valkey-go.json

@@ -0,0 +1,15 @@
+{


I'm not sure of the value of this directory structure (e.g.clients/go/github.com/valkey/valkey-go.json). Seems like some remnant of something that other datastore was doing.

It might be worth just moving stuff around to be: clients/go/valkey-go.json

Do you mean for Go specifically or for all of the clients directory?

rueian · 2024-11-27T17:35:13Z

topics/valkey-clients.md

+-----
+- **valkey-go**
+  - GitHub: [go-valkey-go](https://github.com/valkey-io/valkey-go)
+  - Installation: TBD


Suggested change

- Installation: TBD

- Installation: `go get github.com/valkey-io/valkey-go`

⬆️ This is the command.

Added, thanks!

Signed-off-by: lior sventitzky <[email protected]>

asafpamzn mentioned this pull request Aug 17, 2024

Add documentation for clients #161

Open

avifenesh reviewed Aug 18, 2024

View reviewed changes