tlbmc/subscription_params.proto

edition = "2023";

package milotic_hft;

import "telemetry_aggregation.proto";
import "identifier.proto";

message SubscriptionPolicy {
  enum ConfigurationType {
    CONFIGURATION_TYPE_UNSPECIFIED = 0;
    CONFIGURATION_TYPE_CONFIGURE_ALL_RESOURCES = 1;
    CONFIGURATION_TYPE_CONFIGURE_SPECIFIC_RESOURCES = 2;
  }

  enum ResourceType {
    RESOURCE_TYPE_UNSPECIFIED = 0;
    RESOURCE_TYPE_SENSOR = 1;
    RESOURCE_TYPE_FRU = 2;
    RESOURCE_TYPE_ICI_PORT = 3;
  }
  ConfigurationType configuration_type = 1;
  ResourceType resource_type = 2;
}

message SubscriptionParams {
  // The interval between two consecutive samples of a reading.
  // Positive integers are enforced (minimum value is 1ms).
  // If not set, 1 ms will be used as the default sampling interval.
  //
  // For sensor subscriptions the value must be a power of two in
  // [1, 2^30] ms; non-power-of-two or out-of-range values are rejected
  // with INVALID_ARGUMENT. This ensures the lowest requested polling
  // period is always an integer multiple of every other requested period.
  // Resampling then reduces to power-of-two decimation and a coarser
  // subscriber's samples are a strict subset of a finer one's, so multiple
  // subscribers to the same sensor share one decimated stream without
  // perturbing each other; decimation also tolerates poll jitter because
  // each reading is binned by its own timestamp.
  // FRU subscriptions are not constrained to powers of two.
  int32 sampling_interval_ms = 1;

  // The interval between two consecutive batches of readings.
  //
  // For sensor subscriptions, this must be at least twice the
  // sampling_interval_ms (the 2x invariant). This guarantees a producing
  // sensor always advances at least one decimation bin per export window,
  // so an empty window reliably indicates a sensor stall rather than a
  // timing artifact.
  //
  // Note: We purposely avoid using batch_size as a way to control the export
  // interval. This is because different data sources may have different
  // collection mechanics and if we need to batch data across multiple data
  // sources, we would need a complex synchronization mechanism to ensure that
  // the batches are exported at the same time.
  //
  // With the export interval, we can simply wait for the specified amount of
  // time between two consecutive batch exports and get new data since the last
  // export.
  int32 export_interval_ms = 2;

  // The number of batches to export before cancelling the subscription.
  // If not set, the subscription will continue until explicitly cancelled.
  int32 num_batches = 3;

  // The identifiers of the resources to subscribe to.
  repeated Identifier identifiers = 4;
  SubscriptionPolicy subscription_policy = 5;
  // Optional identifier for the subscription.
  string subscription_policy_id = 6;
  reserved 7, 8, 9;

  // Deprecated: Use EdgeFilter in Identifier instead.
  bool is_aggregate = 10 [deprecated = true];
  AggregationConfiguration aggregation_configuration = 11 [deprecated = true];
  reserved 12, 13, 14, 15, 16, 17, 18, 19;

  // Pre-flight stale-cache check. If set and != server's current
  // generation, the service fails the request with FAILED_PRECONDITION
  // before walking identifiers. Cheaper than discovering staleness via
  // NOT_FOUND on a per-identifier basis.
  string expected_generation = 20;
}