Remove runtime dependency on Protobuf

[aslakhellesoy]

When we adopted protobuf as the basis for messages, we had 3 goals:

• Be able to define messages with an IDL
• Wide programming language support
• JSON serialisation format (for debuggability)

Protobuf satisfies all of those, but has some drawbacks.

The primary drawback is runtime dependencies. The protoc code generator (or similar code generators in unofficial ports) generates code that depends on protobuf runtime libraries. This poses two challenges:

• Size. Loading all this code into a browser take a long time because the resulting code is megabytes.
• Compatibility. A project depending on a different version of protobuf than the one used by Cucumber might lead to conflicts

Another challenge with protobuf is maintenance cost. Because we want to inspect messages visually, we've decided to use the JSON serialisation format instead of the more commonly used binary representation. While JSON is "supported" by protobuf, the implementations have several bugs that we've had to work around or fix. These bugs exist because few people use protobuf with JSON.

During the weekly community meeting on 25 Feb 2021 two alternative solutions were put forward:

Keep .proto but use custom code generator

We could implement a custom code generator that parses the messages.proto file and reads a programming language-specific template file for code generation.

The code generator would generate code with an interface similar to the code generated by protoc, but without any runtime dependencies. It would only support JSON serialisation and not the binary representation.

For TypeScript for example, this could be just messages.d.ts (just the interface) and no implementation at all. We'd get type safety at compile time, and wouldn't need any runtime dependencies for serialisation (that would be handled by the stdlibrary JSON functions).

JSON Schema

(OpenAPI was suggested. OpenAPI has a lot of HTTP stuff in it that isn't relevant to us, and my understanding is that it relies on JSON Schema to define the schema of request/response payloads).

We could translate the .proto schema to JSON Schema and use existing tools to generate lightweight code. Here are some existing ones:

• TypeScript: json-schema-to-typescript
• .NET: NJsonSchema
• Java: jsonschema2pojo

For dynamically typed languages such as Ruby, we wouldn't need code generation or any runtime dependencies at all.

[mpkorstanje]

So we can generate the POJO's from the schema, how will the POJO's be serialized to JSON?

There are a few tricky things around date/time formats that may need to be looked into.

[laeubi]

I recently found the "protonature" of the messages API very useful. At least there should be public API that allows to read/write the messages from/to stream so the could be transfered-over-the-wire, e.g. I use that to "remote-debugging" cucumber runs. It should also be considered that code that currently uses the generated proto-messages have to be rewritten the generated methods do not match.

[davidjgoss]

+1 for JSON schema

So we can generate the POJO's from the schema, how will the POJO's be serialized to JSON?

Are we already using jackson or gson or similar in cucumber-jvm?

There are a few tricky things around date/time formats that may need to be looked into.

I don't think we represent date(time)s in messages though, just timestamps expressed as numbers of seconds and nanos?

[davidjgoss]

One thing to watch out for will be treatment of enum values. With OAI/JSON schema they are generally represented as the name (string), but I think with protobuf they serialise as the ordinal.

[laeubi]

Are we already using jackson or gson or similar in cucumber-jvm?

Isn't this replacing one dependency by another?

[aslakhellesoy]

but I think with protobuf they serialise as the ordinal.

The binary representation uses the ordinal, but the JSON representation uses the name. (This was buggy in some protobuf implementations, and we had to fix it).

[aslakhellesoy]

Isn't this replacing one dependency by another?

We’d be using the same JSON library we’re already using in other parts of the code. That library is shaded and won’t conflict if user code also uses it.

[aslakhellesoy]

At least there should be public API that allows to read/write the messages from/to stream so the could be transfered-over-the-wire

Agreed. We’ll keep the stream utilities that reads/writes message objects to/from streams.

[laeubi]

Just s

We’d be using the same JSON library we’re already using in other parts of the code. That library is shaded and won’t conflict if user code also uses it.

Just some thought

• maybe protobuf can be shaded too?
• instead of create own parsers/generator the protobuf json support could be enhanced

We’ll keep the stream utilities that reads/writes message objects to/from streams

👍

[aslakhellesoy]

maybe protobuf can be shaded too?

I think it already is.

The runtime library size problem for browser JavaScript I described above remains until the protobuf runtime is replaced with something lightweight.

Due to the cross platform nature of this project that means protobuf will have to be replaced for all platforms.

[aslakhellesoy]

instead of create own parsers/generator the protobuf json support could be enhanced

That’s what we have done. We’ve submitted pull requests for existing protobuf implementations. IIRC one of the protobuf implementations had been abandoned, so we had to fork.

This is not a case of NIH.

[aslakhellesoy]

@laeubi here are the two PRs to improve JSON support in the protobuf gem. They still haven't been merged, which is why we forked and released protobuf-cucumber. This has a high maintenance cost as we'll have to update our fork when/if security patches are released for example.