Getting started documentation for ocaml-grpc #25

tmcgilchrist · 2023-03-17T22:31:09Z

Examples

Fixing the GRPC documentation one tutorial at a time.

TODO

Package examples so they compile in CI
Provide a quick start guide for GRPC equivalent to gRPC in Go
Provide routeguide implementation in OCaml based on tonic in Rust
Integrate with mdx to validate examples in Markdown format.

Based off the Diátaxis framework for technical documentation writing.

quernd · 2023-03-17T23:14:26Z

Thank you for this initiative! This kind of tutorial was sorely missing. Given that we have an Eio port in the making that has feature parity with the Lwt implementation (we haven't battle-tested it yet), we can easily port this tutorial too so we can offer it in two flavors (or even three including Async).

examples/helloworld-tutorial.md

quernd · 2023-03-17T23:26:53Z

examples/helloworld-tutorial.md

+let greeter_service =
+  Server.Service.(
+    v () |> add_rpc ~name:"SayHello" ~rpc:(Unary say_hello) |> handle_request)
+
+let server =
+  Server.(
+    v () |> add_service ~name:"helloworld.Greeter" ~service:greeter_service)


Relating to my above comment, with ocaml-protoc-plugin one can actually get the RPC and service names from the .proto file which is quite neat. (Mentioning this as a sidenote, not necessarily for inclusion in the tutorial -- we were considering writing a somewhat opinionated wrapper that would remove a lot of boilerplate)

we were considering writing a somewhat opinionated wrapper that would remove a lot of boilerplate.

That would be a good improvement for the API in my opinion, however I've only recently started using this library and don't have a considered opinion on how that should look.

The service name and function name are squashed into the val name field on the generated code. eg

module GetFeature = struct let name = "/routeguide.RouteGuide/GetFeature" module Request = Point module Response = Feature end

What about making a change to the Message module type to include returning the components?

module type Message = sig type t val name : () -> string (* returning GetFeature*) val service_name: () -> string (* returning routeguide.RouteGuide *) val from_proto: Reader.t -> t Result.t val to_proto: t -> Writer.t end

What about making a change to the Message module type to include returning the components?

This is a good idea, and it's not hard to do. In fact, we already did something like that in our fork. I could have sworn it was part of the changes that have been merged recently, but alas it wasn't. Here's the commit for reference:
dialohq/ocaml-protoc-plugin@beeffb2

There have been a few changes upstream so it won't merge cleanly anymore. I'll try to rebase it and open a new PR.

That would be great, let me know if I can help with it.

That would be great, let me know if I can help with it.

Feel free to give it a shot if you have some time to spare. Otherwise I'll get back to it next week as I'm still on vacation this week.

issuu/ocaml-protoc-plugin#28 is the PR we branched off of. It later got merged with some more changes, and some more cleanup was done in issuu/ocaml-protoc-plugin#43.

It's probably quickest to make these changes starting from the current trunk though.

issuu/ocaml-protoc-plugin#49

tmcgilchrist · 2023-03-18T01:43:28Z

Testing the EIO version and writing up the code for that is on my list.
Doing an Aysnc version is less interesting, I don't use it and have less experience with it. However it would not be that hard for someone else to do it if they want to.

wokalski · 2023-04-27T17:18:58Z

hey, amazing work. thanks for this!

Mis-matches can result in ocamlformat reformatting your code to be incompatible with the lowest OCaml versions.

tmcgilchrist · 2023-04-28T00:10:08Z

This is ready for review now @quernd and @wokalski

novemberkilo

A few fixes as I worked through the tutorial.

As discussed, dune-project requires an update -- currently dune build fails.

examples/helloworld-tutorial.md

quernd

Just a couple of nitpicks. I think we should just merge this PR after these small fixes. It will be good for visibility!
Please don't forget to add your name to the list of authors :)

One more thing: You converted the greeter examples to use ocaml-protoc-plugin instead of ocaml-protoc. I'm okay with that but it means we the README in the root directory is not accurate anymore.

examples/helloworld-tutorial.md

quernd · 2023-05-22T13:21:47Z

examples/helloworld-tutorial.md

+<!-- $MDX skip -->
+```shell
+{
+  "message": "Hello Tonic!"


Suggested change

"message": "Hello Tonic!"

"message": "Hello OCaml!"

grpc-async.opam

examples/routeguide-tutorial.md

tmcgilchrist · 2023-05-22T23:07:26Z

Just a couple of nitpicks. I think we should just merge this PR after these small fixes. It will be good for visibility! Please don't forget to add your name to the list of authors :)

I've done the smaller fixes, so it is ok to merge.

The tutorial pages don't flow the way I would like but I can fix that up in another PR this week.

quernd reviewed Mar 17, 2023

View reviewed changes

examples/helloworld-tutorial.md Outdated Show resolved Hide resolved

quernd reviewed Mar 17, 2023

View reviewed changes

tmcgilchrist force-pushed the documentation branch from aa631a1 to f129e08 Compare March 25, 2023 01:24

tmcgilchrist force-pushed the documentation branch from fbc4628 to 0c5fc86 Compare April 28, 2023 00:02

tmcgilchrist marked this pull request as ready for review April 28, 2023 00:03

tmcgilchrist added 4 commits April 28, 2023 10:07

Add markdown hello world tutorial as a Getting Started guide.

9c86aec

Add markdown routeguide tutorial as a Getting Started guide.

c6c6248

Match OCaml version from grpc.opam

59f901b

Mis-matches can result in ocamlformat reformatting your code to be incompatible with the lowest OCaml versions.

Trim bench dependencies to minimal set of packages

ff965a1

tmcgilchrist force-pushed the documentation branch from 0c5fc86 to 7e1bddd Compare April 28, 2023 00:07

Re-organise example code in preparation for mdx integration.

d2fcbcd

tmcgilchrist force-pushed the documentation branch 3 times, most recently from 1e65c74 to c6a2e74 Compare April 28, 2023 01:02

tmcgilchrist added 2 commits April 28, 2023 13:25

Add routeguide example code.

403dada

Add routeguide tutorial markdown.

850e841

tmcgilchrist force-pushed the documentation branch from 233486f to b1e26be Compare April 28, 2023 03:26

novemberkilo reviewed May 2, 2023

View reviewed changes

examples/helloworld-tutorial.md Show resolved Hide resolved

examples/helloworld-tutorial.md Show resolved Hide resolved

examples/helloworld-tutorial.md Show resolved Hide resolved

examples/helloworld-tutorial.md Show resolved Hide resolved

tmcgilchrist mentioned this pull request May 3, 2023

Async server implementation #27

Merged

quernd requested changes May 22, 2023

View reviewed changes

tmcgilchrist added 5 commits May 23, 2023 08:25

Make helloworld greeter tutorial MDX executable.

d628e47

Make routeguide tutorial MDX executable.

8cb3ea4

Reformat everything

7fa99db

Tidy-up benchmark dependencies.

76ff82f

Add Tim McGilchrist to authors.

d2c7a25

tmcgilchrist force-pushed the documentation branch from 84fd1de to d2c7a25 Compare May 22, 2023 22:26

tmcgilchrist mentioned this pull request May 22, 2023

Report HTTP2 error status when it's not OK #22

Merged

quernd approved these changes May 23, 2023

View reviewed changes

quernd merged commit 36d2a1b into dialohq:main May 23, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting started documentation for ocaml-grpc #25

Getting started documentation for ocaml-grpc #25

tmcgilchrist commented Mar 17, 2023 •

edited

Loading

quernd commented Mar 17, 2023

quernd Mar 17, 2023

tmcgilchrist Mar 18, 2023

tmcgilchrist Apr 28, 2023

quernd Apr 29, 2023

tmcgilchrist Apr 30, 2023

quernd May 2, 2023 •

edited

Loading

tmcgilchrist May 14, 2023

tmcgilchrist commented Mar 18, 2023

wokalski commented Apr 27, 2023

tmcgilchrist commented Apr 28, 2023

novemberkilo left a comment

quernd left a comment

quernd May 22, 2023

tmcgilchrist commented May 22, 2023

Getting started documentation for ocaml-grpc #25

Getting started documentation for ocaml-grpc #25

Conversation

tmcgilchrist commented Mar 17, 2023 • edited Loading

Examples

quernd commented Mar 17, 2023

quernd Mar 17, 2023

Choose a reason for hiding this comment

tmcgilchrist Mar 18, 2023

Choose a reason for hiding this comment

tmcgilchrist Apr 28, 2023

Choose a reason for hiding this comment

quernd Apr 29, 2023

Choose a reason for hiding this comment

tmcgilchrist Apr 30, 2023

Choose a reason for hiding this comment

quernd May 2, 2023 • edited Loading

Choose a reason for hiding this comment

tmcgilchrist May 14, 2023

Choose a reason for hiding this comment

tmcgilchrist commented Mar 18, 2023

wokalski commented Apr 27, 2023

tmcgilchrist commented Apr 28, 2023

novemberkilo left a comment

Choose a reason for hiding this comment

quernd left a comment

Choose a reason for hiding this comment

quernd May 22, 2023

Choose a reason for hiding this comment

tmcgilchrist commented May 22, 2023

tmcgilchrist commented Mar 17, 2023 •

edited

Loading

quernd May 2, 2023 •

edited

Loading