1/*
2 * Copyright 2022 Google LLC
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17syntax = "proto3";
18
19package fcp.aggregation;
20
21import "fcp/secagg/shared/secagg_messages.proto";
22
23// Client resource passed to the Aggregation Protocol either as an inlined
24// binary data or as a resource URI.
25message ClientResource {
26  oneof resource_kind {
27    bytes inline_bytes = 1
28        ;
29    string uri = 2;
30  }
31}
32
33// Polymorhic client-to-server message carrying protocol specific content.
34message ClientMessage {
35  oneof protocol_kind {
36    SimpleAggregation simple_aggregation = 1;
37    SecureAggregation secure_aggregation = 2;
38  }
39
40  message SimpleAggregation {
41    ClientResource input = 1;
42  }
43
44  message SecureAggregation {
45    fcp.secagg.ClientToServerWrapperMessage content = 1;
46    ClientResource masked_input = 2;
47  }
48}
49
50// Polymorhic server-to-client message carrying protocol specific content.
51message ServerMessage {
52  oneof protocol_kind {
53    SecureAggregation secure_aggregation = 1;
54  }
55
56  message SecureAggregation {
57    fcp.secagg.ServerToClientWrapperMessage content = 1;
58  }
59}
60
61// Polymorhic server-to-client message which content is included into
62// response to each client when that client joins the aggregation and shortly
63// before the client begins the aggregation protocol.
64message AcceptanceMessage {
65  oneof protocol_kind {
66    SecureAggregation secure_aggregation = 1;
67  }
68
69  message SecureAggregation {
70    // TODO(team): define this message.
71  }
72}
73
74// Status of the aggregation protocol.
75message StatusMessage {
76  // The below buckets are mutually exclusive and exhaustive, such that
77  // it should always be the case that:
78  //     #clients = num_clients_completed
79  //                + num_clients_failed
80  //                + num_clients_pending
81  //                + num_clients_aborted
82  //
83  // Number of clients that have successfully completed the aggregation
84  // protocol.
85  int64 num_clients_completed = 1;
86
87  // Number of clients that started the aggregation protocol but failed
88  // to complete e.g. dropped out in the middle of the protocol.
89  int64 num_clients_failed = 2;
90
91  // Number of clients that started the aggregation protocol but have not
92  // finished yet (either successfully or not).
93  int64 num_clients_pending = 3;
94
95  // Number of clients that started the aggregation protocol but were aborted by
96  // the server before they could complete e.g. if progress on the session was
97  // no longer needed.
98  int64 num_clients_aborted = 4;
99
100  // The below buckets provide a breakdown of the aggregated inputs that have
101  // been submitted by the completed clients.
102  // The below should always be true:
103  //      num_clients_completed = num_inputs_aggregated_and_included
104  //                              + num_inputs_aggregated_and_pending
105  //                              + num_inputs_discarded.
106  //
107  // Number of inputs that were successfully aggregated and included in the
108  // final result of the protocol.
109  int64 num_inputs_aggregated_and_included = 5;
110
111  // Number of inputs that were received and are pending i.e. the inputs have
112  // not been included in the final result of the protocol yet.
113  int64 num_inputs_aggregated_and_pending = 6;
114
115  // Number of inputs that were received by the protocol but discarded for
116  // whatever reason, for example if the protocol has reached a state where it
117  // no longer needs client inputs to complete.
118  int64 num_inputs_discarded = 7;
119}
120