Should we develop a basic protobuf editor? about kalix-jvm-sdk

[michaelpnash]

Just to be entirely clear: If we can't point to a feature, fully defined and pushed from Productboard into a GitHub issue, then there should be no work done in this direction, IMO - that's the process we must follow to ensure we're working on the highest priority things.

[kikiya]

It's true we will have a range of developers using Akka Serverless. It's also true that for now, protobuf is front and center and we need to be ready to support people along the range.

I would not worry so much about this being a forever maintenance issue and certainly not to the level of scala IDE. At some point, protobuf will become more and more familiar to developers and the day to day need for a plugin is likely to diminish.

We didn't build our platform around Open API, we decided on protobuf so we should lead with tooling that helps developers writing that. Of course this doesn't prevent us from allowing people to import Open API definitions to start editing in the future or things like that.

Also I don't think we should leave it to others (even other great OpenAPI tools) with the idea that they will make it better for us... At least not just yet. In this early stage I think it's very important that we have detailed control around our developer's experience especially with the parts that are so central. For example akkasls and the deployment experience. This lightweight editor could be very good for the proto experience.

Whatever we can reasonably do to help people write code for the platform we have today is what we should do. Again we will still be mindful of OpenAPI, just not as a part of this specific feature design.

[retgits]

It's most certainly an interesting concept. So far most (if not all) protobuf extensions I've seen for VS Code are language servers to provide syntax highlight and compilation capabilities. I've also seen more extensions appear over the past months that offer a more UI based approach, showing there's an interest in making development easier while not eliminating the capability to not use a UI (Stackery, for example, has done an amazing job building a graphical wrapper around CloudFormation).

it also permits us to explore the ability to provide the same editing experience for web-based applications such as the Akka Serverless web UI.

If/when we go down this route, I do feel very strongly about having the same functionality with the same look-and-feel available in the Akka Serverless UI as well so we can ensure developers that aren't using VS Code can also benefit from this. The ideas of how it could/would look in the Akka Serverless Console are in this Productboard ticket

I also have a few questions that might also get into the Solution Design space a bit

• How confident are we that we can support all the capabilities that we've currently put in our extensions?
• What milestones are we looking at and how can we make sure we ship this early and often?
• What kind of time/resource investment is needed to get an MVP ready?

I think it would be good to start that solution design.

[huntc]

it also permits us to explore the ability to provide the same editing experience for web-based applications such as the Akka Serverless web UI.

If/when we go down this route, I do feel very strongly about having the same functionality with the same look-and-feel available in the Akka Serverless UI as well so we can ensure developers that aren't using VS Code can also benefit from this. The ideas of how it could/would look in the Akka Serverless Console are in this Productboard ticket

Noted. I'd say this is an important requirement. Are you able to reference resources that may help us achieve the styling decisions presently made?

• How confident are we that we can support all the capabilities that we've currently put in our extensions?

Quite confident. We've done harder things. :-)

• What milestones are we looking at and how can we make sure we ship this early and often?

My estimate is 3 days for a solution design and perhaps 10 man days for an initial release. I think our development cadence has been good.

• What kind of time/resource investment is needed to get an MVP ready?

As above.

[viktorklang]

IF we do this, I think it should be built into akkasls*, so that A) we also can have it run on the command line, B) people can integrate it into their IDE/editor of choice if they want to, and C) we reduce the maintenance burden.

• Verifying well-formedness as protobuf, verifying that names line up (for instance, table definition for Views line up with queries), and be able to produce code offsets etc which can be used by IDEs to highlight errors etc.

[huntc]

IF we do this, I think it should be built into akkasls*, so that A) we also can have it run on the command line,

Apologies, but I don't understand. As per the video, this would be a GUI tool that seamlessly fits in with your IDE experience, leveraging the knowledge you already have.

B) people can integrate it into their IDE/editor of choice if they want to, and

I see that a VSC user already knows how to install a plugin and so does an IntelliJ one. Introducing another technology to do the same is an approach that we have de-emphasised so far.

C) we reduce the maintenance burden.

I don't believe we have introduced a maintenance burden by targeting the idiomatic developer experience so far. Similar to codegen and its leaf-toolchain-focused projects, we envisage a React/Ts project containing the majority of the project. Each IDE has its own requirements for plugins and these would be leaf projects.

[viktorklang]

Apologies, but I don't understand.

The apologies are mine, as I should have been more clear.
Trying to fix that below:

As per the video, this would be a GUI tool that seamlessly fits in with your IDE experience, leveraging the knowledge you already have.

Indeed—and my point there is that the proposed functionality only helps those who use it, whereas everyone are using protobuf (even if under the hood), so improve that [the protobuf/gRPC] experience with a unified backend to detect issues would give value across the board (warning for missing entity_key on input parameter messages, etc). Being able to hook such an error-checking backend into IDEs easily will increase the cohesion between teams where users use different editors.

For the "GUI"-editing functionality demonstrated in the video—one other possible option there would be to implement the translator from OpenAPIv3 to gRPC (I have a bit of a work-in-progress branch for that here: cloudstateio/cloudstate#358 (comment) ) as OpenAPI already has a fair bit of GUI editor support such as, but not limited to, https://github.com/mermade/openapi-gui

The benefit with that is that we can let others improve and develop those in parallel with us developing the product.

/cc @retgits

[retgits]

I think we're discussing a few different features in this thread:

• Being able to start from an OpenAPI specification, which generates a Protobuf file, and gives the opportunity to make changes in a UI. This is captured in Productboard as https://lightbend.productboard.com/feature-board/1928097-as-full-hierarchy/features/7716215/detail
• Having validator functionality to validate all required elements of a Protobuf file are present so you can expect that Akka Serverless will work properly with it. I think this is indeed valuable, and I agree that should be a CLI feature
• Having a native, graphical capability in one of the most widely used IDEs to help design Protobuf files in a format that Akka Serverless will understand and making that easier than saving a file and running a validator command. While it's definitely easier to start from an OpenAPI spec, not everyone will want to start there so getting more help in the IDE of choice is good.

I think the latter is what we're discussing here, which I think is absolutely valuable to us. While we can certainly extend the capability with some of the other work and while we HAVE to make sure it exists in the Akka Serverless Console too, I'm not opposed to making opinionated choices for IDEs we have more native capabilities in. We don't have to support all of them.

[viktorklang]

Actually, they're all related:

Since there are GUI applications (existing, and evolving) which allow you to create and update OpenAPIv3 specifications, if we can transcode OpenAPIv3 to gRPC (and even back) then it becomes as visible as we want it to be.

Now, none of that really matters all that much if the generated/created/updated specifications are not really well-formed Akka Serverless definitions, hence the need to run some form of validation-logic on either the .proto-file, or even more ideally, on the generated .desc file (to make sure that things like I mentioned are correct), they all together form a very nice basis for a DX where we (Lightbend) need to spend minimal effort and maintenance to make sure that the DX is good.

Also, IDEs already in many cases already have OpenAPI plugins, and there are, as I linked, graphical web-based tools which do the same, which we might even be able to integrate into our own web GUI.

Having the capability to transcode OpenAPIv3 <-> gRPC also means that Akka Serverless Proxy can expose in concert with the gRPC Server Reflection also expose an openapi endpoint so that OpenAPI-clients Just Work (tm).

So, to summarize, if we add support for OpenAPI transcoding, and create a .desc-validator function in the CLI, we have opened up a lot of possibilities where we do not need to spend time and effort maintaining external logic, while still making it possible for users to plug this functionality into different tools of which we do not need to be even aware of.

[huntc]

I think a decision needs to be made on open api, transcoding or not, separate to this issue here. This issue assumes protobuf as the exclusive IDL and will go off further topic otherwise.

[retgits]

I understand the concern that building and maintaining code all come with extra effort on our side. Regardless of whether we want to adopt OpenAPI or not (and we'll want to, but that's a separate story/feature) we'll need to make sure that developers can adopt Protobufs in a straightforward way and easily create and maintain new ones. Having a graphical interface to do that, is worth looking at IMHO, especially since we'll want to have this capability in the Akka Serverless Console too. We'll need to have more native integrations into the ecosystems of the developers we want to target and I think that this might be worth the effort for VS Code devs (which doesn't mean we'll do this for every editor out there)

[huntc]

We will be going ahead with a solution design to gather more requirements and feedback. OpenAPI will be out of scope for this solution design so that it can be discussed separately.

[jroper]

I have no idea on the amount of effort it is to write/maintaing VSC plugins - the thought scares me and harks back to the difficulty we had maintaining things like the Scala IDE, but that's completely uninformed.

While absolutely, OpenAPI should be out of scope for the implementation, I think it's important that anything we design should be designed keeping in mind the future direction of the project, and OpenAPI does seem to be a major possibility for the future. I can imagine a number of decisions that we might make for this where, by the current scope, it doesn't really matter which way we go, but would save significant effort in future if we took one option over the other if/when OpenAPI support is added. It's definitely a consideration that should be weighed in when we consider different options.

[huntc]

While absolutely, OpenAPI should be out of scope for the implementation, I think it's important that anything we design should be designed keeping in mind the future direction of the project, and OpenAPI does seem to be a major possibility for the future. I can imagine a number of decisions that we might make for this where, by the current scope, it doesn't really matter which way we go, but would save significant effort in future if we took one option over the other if/when OpenAPI support is added. It's definitely a consideration that should be weighed in when we consider different options.

Protobuf is in our world now and I'm assuming that it will be front-and-center for when Akka Serverless launches. The assertion is that we will be dealing with developers who won't want to invest in learning protobuf on day 1. Do we agree with this assertion or not?

[jroper]

We'll be dealing with a huge range of developers, I don't think there's any black and white assertions being made like that. I'm not saying that we should design how OpenAPI will be implemented if add support for it, I'm just saying we should keep it in mind as we weight the many different and often competing software attributes against each other. Essentially, if there are places where it's easy to abstract the Akka Serverless concepts that are defined in our annotations away from the protobuf, then let's do that.

[viktorklang]

@kikiya @retgits @huntc @jroper

All,

I have cited a number of the previous comments in this thread, so see this post as an attempt to clarify my thinking of the proposal that is this Issue.

I would not worry so much about this being a forever maintenance issue and certainly not to the level of scala IDE. At some point, protobuf will become more and more familiar to developers and the day to day need for a plugin is likely to diminish.

How will they become more familiar with protobuf if it is hidden from them by a tool which does things for them?

I have no idea on the amount of effort it is to write/maintaing VSC plugins - the thought scares me and harks back to the difficulty we had maintaining things like the Scala IDE, but that's completely uninformed.

I think it has been clear since many years that Lightbend does not want to be in the IDE business. If that has changed, I think it needs to be made very clear and be staffed accordingly.

Having a graphical interface to do that, is worth looking at IMHO, especially since we'll want to have this capability in the Akka Serverless Console too. We'll need to have more native integrations into the ecosystems of the developers we want to target and I think that this might be worth the effort for VS Code devs (which doesn't mean we'll do this for every editor out there)

How and when will we know if it is worth it, and what are we trading away which we could have done instead?

We didn't build our platform around Open API, we decided on protobuf so we should lead with tooling that helps developers writing that.

OpenAPI or no OpenAPI—the truth is that by basing things on established external standards means saving a lot of work for both us and the users. I have a PoC which demonstrates that we can programmatically derive an OpenAPI spec automatically in the proxy, in essence facilitating interop with both OpenAPI and gRPC tooling for all users regardless of PL or IDE.

Also I don't think we should leave it to others (even other great OpenAPI tools) with the idea that they will make it better for us... At least not just yet. In this early stage I think it's very important that we have detailed control around our developer's experience especially with the parts that are so central.

This, to me, contradicts itself—if we need to have detailed control around our developer's experience and that entails how their choice of IDE works, then we're talking about implementing a tool for every conceivable IDE our users might choose. This is unrealistic and likely to be a lot of work at a point where we don't have enough feedback to guide what potential users even want or need.

Interestingly, deciding to support a single IDE (VS Code?) is also something which may backfire—users having no choice of IDE, or not wanting to learn how to be productive in a new IDE risks feeling like they are "second-class citizens" as their IDE of choice has a worse experience than the only IDE we support. We're already risking that with our SDKs if we do not do them right (by supporting all features for all languages we have SDKs for)—and spending effort and maintenance serving a subsegment of a subsegment (those who want, and those who are able, to use VS Code) not only incurs opportunity costs for us, but is also of an unquantifiable benefit to an unknown ratio of our potential users.

We are not talking about a situation like in the early days of Scala when there were practially nothing in terms of tooling unless we made it happen. Both Protobuf/gRPC and OpenAPI have tons of tooling support already, and presuming that they don't suddenly stop being used in general in the world, there will be much more effort put into that tooling than we could ever realistically provide—case in point.

Whatever we can reasonably do to help people write code for the platform we have today is what we should do.

I aree in principle, yet I'd qualify that with:

Whatever we can reasonably do to help *as many* people *as possible* write code for the platform we have today is what we should do.

Because if we optimize for subgroups too early, when we have tons of low-hanging fruit to give more value across the board, I think we are risking too much for too little. We're at a point where we can still improve a lot for the lot.

We'll be dealing with a huge range of developers, I don't think there's any black and white assertions being made like that. I'm not saying that we should design how OpenAPI will be implemented if add support for it, I'm just saying we should keep it in mind as we weight the many different and often competing software attributes against each other.

Indeed—and it is also important to remember that technically we are not depending on ".proto" for Akka Serverless, what we depend on is a binary representation of a gRPC descriptor—how that descriptor is created doesn't really matter. This is a good thing, because it will allow for innovation on top by anyone—not necessarily ourselves.

Protobuf is in our world now and I'm assuming that it will be front-and-center for when Akka Serverless launches. The assertion is that we will be dealing with developers who won't want to invest in learning protobuf on day 1. Do we agree with this assertion or not?

What are we basing that assertion on? As far as I remember, essentially all feedback on the setup has been positive, but @retgits will definetely correct me and point to some data points if I am wrong.

[michaelpnash]

I can confirm that the feedback I've heard so far is that Protobuf is a very reasonable choice, and that gRPC in particular is also well-accepted by the beta users so far - so I would not say that I've heard any input that says our developers don't want to invest in learning protobuf, in fact, quite the opposite - the developers so far it seems have already made that investment. Leon will have a more direct picture of this, though.

[kikiya]

Got it.

And to clarify I didn't think we were avoiding users learning protobuf with a visual editor. I thought of it as more of a helper while learning. Much like having markdown render in a side by side window.

And there are productboard features that would support this, however they are not pushed or ranked properly to start this work. @michaelpnash is right.

We'll leave this behind and follow the right process. If it becomes important enough in productboard then we can revisit.

Thanks all for input.

[patriknw]

Closing (at least until it comes in as a feature request)