More clear docs needed

[toby-1-kenobi]

The docs are not clear on where relevant files should be put. Does there need to be a specific structure within app/rpc/ or can we order things however we like in there? How does the service file know how to find the foo_services_pb file? Does that need to be in a specific place? What about the .proto file, are they important?

I tried putting my files in various ways but every time I tried to run the server it failed because the module name for my service is not recognised in the gruff controller bind statement. I feel like there should be a require foo_services_pb statement at the top of the gruff controller file, but there isn't in the docs and the example app, so I'm confused how that works.

[splittingred]

Hi @toby-1-kenobi - thanks for calling this out. I definitely think the docs can be more elaborated here. For reference, we follow the same concepts as gRPC's core Ruby docs, which do require you to require those files beforehand.

As a recommendation, especially in a service-oriented architecture environment, I recommend you actually have all of your protobufs across your platform in a separate repository (an IDL, or interface definition library), and then generate an artifact (such as a gem) from those. From there, your repository can include them like so:

gem 'my-idl', github: 'toby-1-kenobi/idl'
gem 'gruf', '~> 2.7'

From there, create a Railtie or ask the service to require your gem, which should then require all the generated server/client stubs (we do this via glob). You don't need the proto files - just the generated _pb classes. The benefits of this is that as you branch out to multiple services you don't need multiple gems/clients, and you can centralize the definition (good organizationally for your eng org).

I'm on PTO for a couple of weeks, but will try and improve the docs more when I return. Thanks again!

[toby-1-kenobi]

Thanks for responding. I did get it working with a require statement. That's a good idea about having a separate repo for the protobufs.

Now it's working for me I'm really happy with Gruf. Thanks for making it available. I particularly like the interceptors. I'm using two customs ones. One for debugging that watches for a debug entry in the metadata, and one for validating the user's Google ID token.

[splittingred]

Perfect @toby-1-kenobi ! I've also added a wiki to Gruf, which I'll be augmenting in the next week or so even further: https://github.com/bigcommerce/gruf/wiki

This should have plenty of information to get you started even more. Thanks for the feedback!