// -*- Protocol-Buffers -*-
//==============================================================================
/// @file signal.proto
/// @brief Message type and enumerations for use in signal streams
/// @author Tor Slettnes <tslettnes@picarro.com>
//==============================================================================

// Definitions and data types used to implement the signal/slot pattern using
// custom ProtoBuf messages.  These signals can then be propagated across
// applications over transports such as gRPC, thereby emulating the pub/sub
// pattern.
//
// Our implementation makes use of a container message to multiplex between the
// various signals your application provides, looking something like this:
//
//   ```proto
//   message MySignalMultiplexer
//   {
//       oneof signal
//       {
//           MyTypeA signal_a = 8;
//           MyTypeB signal_b = 9;
//           ...
//       }
//   }
//   ```
//
// Our implementation also supports a specialization of the above, which we
// will refer to as "mapping signal". Here, two extra fields are introduced:
//
//   ```proto
//   message MySignalMultiplexer
//   {
//       // Mapping action: one of MAP_ADDITION, MAP_UPDATE, MAP_REMOVAL
//       picarro.signal.MappingAction mapping_action = 1;
//
//       // Mapping key
//       string mapping_key = 2;
//
//       oneof signal
//       {
//           MyTypeA signal_a = 8;
//           MyTypeB signal_b = 9;
//           ...
//       }
//   }
//   ```
//
// Below you will find the `MappingAction` type used for this purpose.
//
// Secondly, to propagate such signals over gRPC, your service needs
// a method to stream signals, similar to the following:
//
//   ```proto
//   service MyService
//   {
//       ...
//       rpc watch (picarro.signal.Filter) returns (stream MySignalMultiplexer);
//   }
//   ```
//
// The `Filter` type is defined and described below, and is used by the client
// to select which of the available signals the client wants to receive (similar
// to a _topic_ in a pub/sub scheme).  An empty `Filter` means listen for all
// signal events.


syntax = "proto3";

package picarro.signal;

//==============================================================================
// MappingAction

enum MappingAction
{
    // Synchronized to 'MappingAction' type in
    // [signaltemplate.h++](../cpp/inner-core/common/thread/signaltemplate.h++).
    MAP_NONE     = 0;  // No operation
    MAP_ADDITION = 1;  // A new item has been mapped
    MAP_REMOVAL  = 2;  // An existing item has been removed
    MAP_UPDATE   = 3;  // An existing item has bene updated
};


//==============================================================================
// Filter - Client-provided mask of signals to be streamed back from server

message Filter
{
    // If true, the `signals` list specify signals to include in rather than
    // than exclude from the signal stream.
    bool polarity = 1;

    // A list of indices from the "oneof" switch in the target Signal message,
    // corresponding to specific signals to be filtered to the client.
    //
    // For instance, consider the following definitions
    //
    //   ```proto
    //   package picarro.example;
    //
    //   service SignalExample
    //   {
    //     /// Watch for signals from server.
    //     rpc watch (picarro.signal.Filter) returns (stream Signal);
    //   }
    //
    //   message Signal
    //   {
    //     ...
    //     oneof signal
    //     {
    //        FooType foo = 9;
    //        BarType bar = 10;
    //        BazType baz = 11;
    //     }
    //   }
    //   ```
    //
    // The following Python invocation will stream back only the signals `bar`
    // and `baz`, but not `foo`:
    //
    //   ```python
    //   >>> for event in client_stub.watch(
    //   ...     picarro.signal.Filter(
    //   ...         polarity=True,
    //   ...         indices=[10, 11])):
    //   ...     my_handler(event)
    //   ```
    //
    repeated uint32 indices = 2;
}