@exocet/pandora-protobuf

Pandora Protobuf

Addon to provide flow and setup functions to encode/decode Protobuf 3 using protobufjs.

npm install --save @exocet/pandora-protobuf

Concepts

Message envelope

The message envelope creates a pattern for transposing data between endpoints, this pattern is defined in the file "lib / standard.proto":

syntax = "proto3";

package pandora.standard;

message MessageEnvelope {
	bytes data = 1;
	repeated bytes collection = 2;
	uint32 total = 3;
}

Setup

Available features:

• Generate protos from entity definition
• Multiple protos defined by labels
• Provide encoder/decoder hook
• Flow steps: decodeProtobuf, encodeProtobuf

To add this addon into your project, put the addon spec into your endpoint YAML:

kind: Pandora/endpoint
metadata:
  name: myEndpoint
spec:
  addons:
    - name: protobuf
      package: "@exocet/pandora-protobuf"
      flow: true
      setup: true

After the setup the following property of the context will be available:

• .application.protos - Instance of protobufjs.Root

Hooks

The hooks created by this addon are:

• protobufEncoder (.service.hooks.useHook('protobufEncoder')) - Synchronous hook to encode data to protobuf

  const [protobufEncoder] = service.hooks.useHook('protobufEncoder');
  const encoded = protobufEncoder('myNamespace.myEntity.myLabel', data);

• protobufDecoder (.service.hooks.useHook('protobufDecoder')) - Synchronous hook to decode protobuf

  const [protobufDecoder] = service.hooks.useHook('protobufDecoder');
  const data = protobufDecoder('myNamespace.myEntity.myLabel', encoded);

Flow

The provided flow type and steps are listed bellow:

• decodeProtobuf - This flow decodes protobuf:

  kind: Pandora/flowStep
  metadata:
    name: decodeProtobuf
  spec:
    type: decodeProtobuf
    options:
      inboundFrom: request # JSON Path to acquire protobuf from execution context
      outboundTo: request # JSON path to put the decoded data
      wrappedMessageEnvelope: true # Decode inbound wrapped in message envelope
      collectionAsPayload: true # If the message envelope contains a collection then this flow will put the collection as outbound
      encodingFrom: null # JSON Path to execution value that contains the current encoding of inbound, if it's specified then this flow will only decode the inbound if the value is "proto3"
      entity: # The entity to parse the proto definition
        label: default
        namespace: stock
        name: product

• encodeProtobuf - This flow encodes data to protobuf:

  kind: Pandora/flowStep
  metadata:
    name: encodeProtobuf
  spec:
    type: encodeProtobuf
    options:
      inboundFrom: response # JSON Path to acquire data from execution context
      outboundTo: response # JSON path to put the encoded data
      wrappedMessageEnvelope: true # Wraps the outbound in message envelope
      encodingFrom: null  # JSON Path to execution value that contains the desired encoding of outbound, if it's specified then this flow will only encode the inbound if the value is "proto3"
      entity: # The entity to parse the proto definition
        label: default
        namespace: stock
        name: product