docs: Daemon JSON-RPC examples

[PiotrFLEURY]

Description

Current Deamon documenation

https://dartfrog.vgv.dev/docs/advanced/daemon

Dart Frog Daemon documentation need more examples.

The actual Daemon documentation explain the global JSON-RPC communication principle with only one usage example and domain, methods and events listing.

Method examples Interract with the Daemon in a terminal can be complicated the first time. For example I struggled to understand that the Parameters section of each method was related to the params field of the RequestMethod

JSON-RPC examples I'm also trying to implement a Dart CLI nenuphar watch command in order to generate the openapi every time a route change. As no implementation example exists for JSON-RPC communication between two processes I do not know if I'm doing something wrong or not. I can listen Daemon ready event but I cannot send any command to the Daemon. Sometimes I get a SocketException, errno = 5 error from the Daemon. With the current documentation I cannot qualify if this behavior is a bug or a missunderstading. This is my implementation tentative https://github.com/PiotrFLEURY/nenuphar_cli/blob/feat/watch/lib/src/commands/watch_command.dart

I guess at least one Dart implementation example of JSON-RPC should be put in the documentation in order to listen stdout and write to the stdin.

Requirements

• [ ] Add a communication example for each command
• [ ] Add a Dart implementation example for a JSON-RPC communication between a Dart process and the Daemon

I would be glad to participate to this documentation improvement but for the implementation part I need a clue to make it work.

[alestiago]

Hi @PiotrFLEURY! Thanks for opening an issue 💙

For example I struggled to understand that the Parameters section of each method was related to the params field of the RequestMethod

Is the issue you are mentioning here related to https://github.com/VeryGoodOpenSource/dart_frog/issues/913? Let me know if you want to be assigned to the issue 💙 🙌

I guess at least one Dart implementation example of JSON-RPC should be put in the documentation in order to listen stdout and write to the stdin.

A documentation example might help, but I recommend having a look at the e2e daemon tests, which serve as great up-to-date examples. You should find at least one e2e test per domain, if not, feel free to open an issue reporting so. Please let me know if this helps 🙌 .

I can listen Daemon ready event but I cannot send any command to the Daemon. Sometimes I get a SocketException, errno = 5 error from the Daemon.

When I've been using the daemon I've not seen the intermittent SocketException you mention. Do you mind sending a minimal reproductive sample? As a quick guess, this might be related to starting a server with conflicting ports. Maybe @renancaraujo might have some more context regarding this matter.

[PiotrFLEURY]

Hi @alestiago thank you for your detailed response.

I looked at the #913 issue. That does not seems so complicated to fix. You can assign it to me, I would be glad to help. Just note that I'm working on this on my free time. I saw that since the opening of the issue, the route_configuration domain was created and also require parameters. In my opinion we should fix both in the same pull request. What do you think ?

I also looked at your e2e daemon tests. It helped me a lot. I now have a working prototype of my nenuphar watch command 🚀 Can I make a documentation change proposal using my implementation experience ? I'll add a simple working code example to clearly understand how communicate using JSON-RPC trough the stdio.

Regarding the socket exeption, I tried using a different working station. I faced sometimes the error when I use an ubuntu desktop system. I was not able to reproduce it using Github Codespaces. errno = 5 seems to be related to a permission issue.

[alestiago]

Hello @PiotrFLEURY ! Thanks for the quick reply. I'm very glad my previous comment helped 💙 .

You can assign it to me, I would be glad to help.

Awesome! Thank you so much for taking the lead on #913 . Unfortunately GitHub doesn't allow assigning you to the issue unless you comment the issue, do you mind leaving a brief comment over there so I can assign it to you?

In my opinion we should fix both in the same pull request.

That sounds good to me! Thanks for catching that. Let's deviate future conversation about #913 over there so we avoid polluting this issue 👀

Can I make a documentation change proposal using my implementation experience ?

Feel free to open a Pull Request improving the documentation. I was thinking on updating the documentation with a brief sentence that pointed to the e2e tests, but I'm intrigued to see your proposed change 🙌 .

As a side note, you might want to have a look at #1017 , where @renancaraujo proposes a daemon client package that would allow you to "interact with the Daemon without having to touch the raw JSON-RPC protocol".

errno = 5 seems to be related to a permission issue.

Interesting, did you manage to resolve by giving permissions? Do you think other developers might encounter the same issue? If so, what steps did you follow?

[renancaraujo]

Yes, reading and writing to stdio can be tricky in any language. Ideally, we will have a dart package to abstract this kind of stuff, but first, it requires a big refactor (#1016).

We can't cover all use cases since theoretically, daemon clients could be written in any language, not only dart.

It is also important to notice that the daemon API is at the verison0.0.1. Which is very unstable and we may break that in the (near) future.

To close on this issue, what about mentioning the e2e tests as (for now) a Dart implementation example in the docs?

[PiotrFLEURY]

Feel free to open a Pull Request improving the documentation. I was thinking on updating the documentation with a brief sentence that pointed to the e2e tests, but I'm intrigued to see your proposed change 🙌 .

As a side note, you might want to have a look at #1017 , where @renancaraujo proposes a daemon client package that would allow you to "interact with the Daemon without having to touch the raw JSON-RPC protocol".

That's a good idea to create a daemon client package. In fact it can be made quickly if we just encapsulate the DaemonStdioHelper in a dedicated dart CLI package.

As @renancaraujo mentioned the #1016 refactor and the really early 0.0.1 version of the daemon the documentation should contain a disclaimer banner to warn users about it. Users should know that the daemon is kind of experimental even if dart_frog_cli version is 1.x and stable

errno = 5 seems to be related to a permission issue.

Interesting, did you manage to resolve by giving permissions? Do you think other developers might encounter the same issue? If so, what steps did you follow?

In fact the error message does always pop but I think the problem always occurs. I saw in your tests that some TODO are mentioning connection refused on linux

https://github.com/VeryGoodOpenSource/dart_frog/blob/d2e3e0bf97bfaa4b926e65bfdae69930745eea32/packages/dart_frog_cli/e2e/test/daemon/dev_server_domain_test.dart#L308

Can this permission problem be related to issue #807 ?

[PiotrFLEURY]

I just proposed the #1051 documentation change to fix this issue.

• Methods usage examples has been added
• End to end tests has been mentioned
• A disclaimer about the early stage warns the user

In my opinion, the permission problem can be follow up in the #807 issue.

Feel free to ask any change about this PR.

[renancaraujo]

Thanks for the updates.

About #807, it has nothing to do with the daemon in particular but with a local dev server, which can be observed even by using the dart_frog dev command. Also, I could never see #807 locally, but only on GHA workflow runs.

With that said, If you think the errno=5 problem is not related to #807, I suggest opening a separate issue with a small reproducible sample.