// This file is part of arduino-cli.
//
// Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
//
// This software is released under the GNU General Public License version 3,
// which covers the main part of arduino-cli.
// The terms of this license can be found at:
// https://www.gnu.org/licenses/gpl-3.0.en.html
//
// You can be released from the requirements of the above licenses by purchasing
// a commercial license. Buying such a license is mandatory if you want to
// modify or otherwise use the software for commercial activities involving the
// Arduino software without disclosing the source code of your own applications.
// To purchase a commercial license, send an email to license@arduino.cc.

syntax = "proto3";

package cc.arduino.cli.monitor.v1;

option go_package = "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/monitor/v1;monitor";

import "google/protobuf/struct.proto";

// MonitorService provides services for boards monitor
service MonitorService {
  // Open a bidirectional monitor stream. This can be used to implement
  // something similar to the Arduino IDE's Serial Monitor.
  rpc StreamingOpen(stream StreamingOpenRequest)
      returns (stream StreamingOpenResponse) {}
}

// The top-level message sent by the client for the `StreamingOpen` method.
// Multiple `StreamingOpenReq` messages can be sent but the first message
// must contain a `monitor_config` message to initialize the monitor target.
// All subsequent messages must contain bytes to be sent to the target
// and must not contain a `monitor_config` message.
message StreamingOpenRequest {
  // Content must be either a monitor config or data to be sent.
  oneof content {
    // Provides information to the monitor that specifies which is the target.
    // The first `StreamingOpenReq` message must contain a `config`
    // message.
    MonitorConfig config = 1;

    // The data to be sent to the target being monitored.
    bytes data = 2;

    // When the rate limiter is enabled, this parameter is used to report the
    // number of successfully processed StreamingOpenResp messages (with data).
    int32 recv_acknowledge = 3;
  }
}

// Tells the monitor which target to open and provides additional parameters
// that might be needed to configure the target or the monitor itself.
message MonitorConfig {
  enum TargetType {
    TARGET_TYPE_SERIAL = 0;
    TARGET_TYPE_NULL = 99;
  }

  // The target name.
  string target = 1;
  TargetType type = 2;
  // Additional parameters that might be needed to configure the target or the
  // monitor itself.
  google.protobuf.Struct additional_config = 3;

  // This parameter indicates how many bytes should be buffered on the server
  // side before dropping. If >0 then the server will enable a rate limiter and
  // will send incoming data to the client only when the client allows it: see
  // the StreamingOpenReq.recv_acknowledge parameter for details.
  int32 recv_rate_limit_buffer = 4;
}

message StreamingOpenResponse {
  // The data received from the target.
  bytes data = 1;

  // The number of bytes dropped.
  // During regular updates this number should be 0, but in case the
  // client is not able to process the recv window quickly enough this
  // parameter will report the number of dropped bytes.
  int32 dropped = 2;
}