// Copyright 2016 The Fuchsia Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

package cobalt;

import "config/encodings.proto";

option go_package = "config";

message DifferentialPrivacyConfig {
  float epsilon = 1;
  float delta = 2;
}

// A list of candidates to use during a string RAPPOR analysis.
message RapporCandidateList {
  repeated string candidates = 1;
}

// Human-readable labels to associate with the rows of a report for a
// metric variable of type INDEX. Values of this type are zero-based indices
// into some enumerated set defined outside of the Cobalt configuration system.
message IndexLabels {
  // The keys to the map are the zero-based indices and
  // the values are human-readable labels to be used in the report.
  // A missing label is NOT a fatal error. If an index occurs in the data but
  // there is no corresponding label specified here then the generated report
  // will contain a string such as "<index 42>."
  map<uint32, string> labels = 1;
}

// A ReportVariable is used within a |ReportConfig|. It specifies that
// a generated report should include a named part of a metric and it
// gives additional information necessary to analyze that metric part.
message ReportVariable {
  // The named part of the metric to include in the report.
  string metric_part = 1;

  // This field will be populated only if the corresponding metric part
  // is of type INDEX.
  IndexLabels index_labels = 2;

  // This field will be populated only if the corresponding metric part
  // is of type STRING and if the report is expected to include some
  // string RAPPOR analysis.
  RapporCandidateList rappor_candidates = 3;
}

// The different types of reports that Cobalt knows how to create. Each
// ReportConfig specifies one ReportType in its |report_type| field.
//
// The number of variables that occur in the ReportConfig's |variable| field
// must be consistent with the ReportType.
//
// Not every ReportType is consistent with every kind of encoding. If an
// observation occurs in the set of  observations being analyzed whose
// encoding is not consistent with the ReportType then the report generation
// may fail.
enum ReportType {
  // A single-variable histogram report. Exactly one variable must appear in
  // the |variable| field. Each row of the report presents a value and an
  // estimate of the count of observations in the analysis set that contain
  // that value.
  //
  // All encoding types are supported but in the current version of Cobalt
  // the set of observations being analyzed must be homogeneous with respect to
  // the encoding.
  HISTOGRAM = 0;

  // A joint two-variable histogram report. Exactly two variables must appear
  // in the |variable| field. Each row of the report presents two values and an
  // estimate of the count of observations in the analysis set that contain
  // those two values.
  //
  // A report of this type will be dependent on the two one-way marginal reports
  // being generated prior to the generation of this report. When a report of
  // this type is requested by a user, the Cobalt system will arrange for the
  // two one-way marginals to also be generated--the user does not have to
  // explicitly request those. The association between the joint report and
  // its two one-way marginals will be captured via the |associated_report_ids|
  // field of |ReportMetadata|.
  //
  // Only the String RAPPOR and Basic RAPPOR encoding types are supported.
  JOINT = 1;
}

// A ReportConfig describes to the Analyzer a particular report to produce.
// A report is for a particular metric.
message ReportConfig {
  // These three numbers form this ReportConfig's unique ID in the Cobalt Config
  // DB.
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 id = 3;

  // e.g. "Fuchsia Usage by Hour"
  string name = 4;

  // e.g. "Whenever a Fuchsia device is woken up from sleep we capture the
  //  hour of the day."
  string description = 5;

  // The customer_id, project_id and metric_id refer to the metric that this
  // is a report of.
  uint32 metric_id = 6;

  // Which type of report is this?
  ReportType report_type = 7;

  // The variables being analyzed in this report. The number of variables must
  // be consistent with the type of report.
  repeated ReportVariable variable = 8;

  // The type of epoch to use when aggregating Observations for a report.
  // This also determines the frequency of generating reports.
  EpochType aggregation_epoch_type = 9;

  // The number of days after an epoch ends before a report analyzing that
  // epoch should be run. For example if |aggregation_epoch_type| = WEEK
  // and report_delay_days = 3 then an analyis will be executed and a report
  // will be generated every Tuesday for the 7 day period ending on the Saturday
  // three days prior to the report day.
  uint32 report_delay_days = 10;

  DifferentialPrivacyConfig dp_config = 11;
}

// Constains the list of all ReportConfig that are registered in the
// Cobalt system. An instance of RegisteredReports is deserialized
// from a text file.
message RegisteredReports {
  repeated ReportConfig element = 1;
}