@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