[Development] QtProtobuf and QtGrpc final API review

Mon Apr 22 13:52:42 CEST 2024

(slow in answering so a bit of redundancy from the prev message)

We indeed don't have a guide/example on how to implement a custom channel.
This is targeted towards advanced users who might need such a thing in e.g. the embedded world.

Our client implementation supports all four RPC types (unary, server-stream, client-stream, bidir-stream).
This can be found here: https://doc-snapshots.qt.io/qt6-dev/qtgrpc-service-client-methods.html.

Should we really consider making a cross-api comparison between QtGrpc and grpc/c++ grpc/java and so on in our docs? Perhaps we could add such a section in the overview or create a dedicated place for it. It shouldn't do any harm IMO.

So to boil things down:

* Should we provide a tutorial for creating a QAbstractGrpcChannel implementation?
* Should we add an overview / comparison of our client api usage between other well-known implementations?

-> Explicitly mention that QtGrpc in its current state is a client-side implementation. I'll do that.

best,

________________________
Dennis Oberst
Software Engineer

The Qt Company GmbH
Erich-Thilo-Str. 10
12489 Berlin, Germany
dennis.oberst at qt.io
https://www.qt.io

Geschäftsführer: Mika Pälsi,
Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht
Charlottenburg, HRB 144331 B

________________________________
From: Alexey Edelev <alexey.edelev at qt.io>
Sent: Monday, April 22, 2024 1:47 PM
To: Ivan Solovev via Development <development at qt-project.org>; Dennis Oberst <dennis.oberst at qt.io>; Fabian Kosmale <fabian.kosmale at qt.io>
Subject: Re: QtProtobuf and QtGrpc final API review

Hi,

For gRPC we have the similar API overview and guidance here:
https://doc-snapshots.qt.io/qt6-dev/qtgrpc-service-client-methods.html

For Protobuf we probably might want to introduce the similar thing. I will try to manage this request ASAP.

Regards,
Alexey

________________________________
From: Development <development-bounces at qt-project.org> on behalf of Fabian Kosmale via Development <development at qt-project.org>
Sent: Monday, April 22, 2024 12:56 PM
To: Ivan Solovev via Development <development at qt-project.org>; Dennis Oberst <dennis.oberst at qt.io>
Subject: Re: [Development] QtProtobuf and QtGrpc final API review

Hi,

before diving into the API: Do we have more recent documentation than
https://doc-snapshots.qt.io/qt6-dev/qtprotobuf-index.html?

I have the following issue: The API provides both a set of abstract interfaces which can be used to _implement_ grpc
support, as well as an actual implementation using HTTP2 as the protocol layer. However, as far as I can tell, there's
currently no guidance in the documentation where to start as an actual user of gRPC, and where to start as an
implementer.  There's even the question whether we actually expect anyone to implement additional protocols, or
whether that should be left to Qt.
On the "user" side, there's also some (as far as I can tell) missing information on what the module actually
supports. IIRC, qtgrpc only supports the client part, not the server side. Which is fine even when going out
of TP, but should be mentinoed explicitly.  And as far as the client is concerned: What can you actually do?
gRPC supports quite a few ways of doing calls; do we support all of them? How? Compare e.g. with
https://learn.microsoft.com/en-us/aspnet/core/grpc/client or
https://grpc.io/docs/languages/kotlin/basics/#calling-service-methods

You might ask why this is needed for an API review. Well, we can nitpick the choice of containers and the merits of
passing by value or const-ref on the current API with the changes uploaded to gerrit. But that only gives us a very
narrow view. To verify that the API actually presents a consistent interface which covers all uses-cases, we need
a more application centric view. How else would you figure out tha API is _missing_ (in contrast to just not being
expressed in the best possible way)?

There are application examples, which at least helps with reviewing the usage part of the API, but any additional
design documentation would be appreciated before diving into a proper review.

Kind regards,
Fabian

________________________________________
Von: Development <development-bounces at qt-project.org> im Auftrag von Dennis Oberst via Development <development at qt-project.org>
Gesendet: Montag, 22. April 2024 12:15
An: Ivan Solovev via Development
Betreff: [Development] QtProtobuf and QtGrpc final API review

Hey everyone,

The new QtProtobuf and QtGrpc modules are preparing to exit the technical preview phase. For that, these modules require their final API review for Qt 6.8 to iron out any remaining issues, so that we can finalize the API with its current features for us and our users. We deliberately want to avoid doing this large of a review during the usual review time after Qt 6.8 FF. At best the FF review will be based on the diff of todays state and the state at the time of the official review (much much smaller).

We would really appreciate the help of anyone willing to review the existing API. We have divided it into multiple parts, which you can find here:

- QtGrpc<https://codereview.qt-project.org/c/qt/qtgrpc/+/550653>
- QtProtobuf<https://codereview.qt-project.org/c/qt/qtgrpc/+/550655>
    - WellKnownTypes<https://codereview.qt-project.org/c/qt/qtgrpc/+/550654>
    - GuiTypes<https://codereview.qt-project.org/c/qt/qtgrpc/+/550652>
    - CoreTypes<https://codereview.qt-project.org/c/qt/qtgrpc/+/550651>
    - GeneratedUserApi<https://codereview.qt-project.org/c/qt/qtgrpc/+/556448>

Or through the topic "qtgrpc_6.8_api_review<https://codereview.qt-project.org/q/topic:%22qtgrpc_6.8_api_review%22>".

Thanks in advance, and have a great Monday!

best,

________________________
Dennis Oberst
Software Engineer

The Qt Company GmbH
Erich-Thilo-Str. 10
12489 Berlin, Germany
dennis.oberst at qt.io
https://www.qt.io

Geschäftsführer: Mika Pälsi,
Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht
Charlottenburg, HRB 144331 B

--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240422/02f19573/attachment-0001.htm>