Protons custom options

Protons supports some custom options to control how messages are decoded.

limit

The limit option allows you to limit the size of decoded maps and repeated fields.

In the following example any message with more than 10 instances of repeatedField in it's serialized form will cause an error to be thrown on decode:

syntax = "proto3";

import "protons.proto";

message Message {
  repeated string repeatedField = 1 [(protons.options).limit = 10];
}

Similarly the following example will cause decoding of any message with more than 10 map entries for mapField to error:

syntax = "proto3";

import "protons.proto";

message Message {
  map<string, string> mapField = 1 [(protons.options).limit = 10];
}

Building custom options

Protons options are hints to the message decoder and are not required to be sent as part of the message so there are no special build instructions.

If you wish you can build the ProtonsOptions message and supporting messages. To do this, pass a path option to the protons cli that points to the protons-runtime folder under node_modules in order to resolve protons.proto. This will result in a lot of extra message definitions in the output file:

$ protons --path node_modules/protons-runtime ./path/to/my-messages.proto
... warnings here

Note that there will be warnings emitted as the .proto files bundled with protobufjs-cli do not conform to proto3.

Editor setup

To validate these options during development you may need to configure your editor to add additional paths to protoc.

For example if you are using the vscode-proto3 plugin with VSCode add the following configuration to allow resolving protons.proto from your project's node_modules folder:

{
  "protoc": {
    "options": [
        "--proto_path=${workspaceRoot}/node_modules/protons-runtime"
    ]
  }
}

Other plugins may require other options.