federatedcompute/proto/aggregations.proto

/*
 * Copyright (C) 2023 The Android Open Source Project
 *
 * 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 com.android.federatedcompute.proto;

import "common.proto";

option java_package = "com.android.federatedcompute.proto";
option java_multiple_files = true;

service Aggregations {
  // A request sent by the client after completing local (on-device) task
  // execution to notify the server that it has Aggregation data to upload. The
  // server responds with the location at which to upload the data. If a
  // client's result is no longer needed (e.g. the reporting goal was already
  // reached for the task), the server will respond with an ABORTED error in the
  // operation status.
  rpc StartAggregationDataUpload(StartAggregationDataUploadRequest)
      returns (StartAggregationDataUploadResponse) {}

  // A request sent by the client indicating the successful completion of the
  // client's aggregation session. If a client's result is not needed for the
  // aggregation (e.g. the reporting goal was already reached for the task), the
  // server will respond with an ABORTED error.
  //
  // Clients should use the `ForwardingInfo` from the
  // `StartAggregationDataUploadResponse.aggregation_protocol_forwarding_info`
  // response field to construct the URI for this request.
  rpc SubmitAggregationResult(SubmitAggregationResultRequest)
      returns (SubmitAggregationResultResponse) {}

  // A request sent by the client indicating the client's aggregation session
  // should be aborted.
  //
  // Clients must only call this if they've previously called
  // `StartAggregationDataUpload`.
  //
  // Clients should not call this if one of the requests returned an Aborted
  // status.
  //
  // If clients have already received a `StartAggregationDataUploadResponse`
  // they should use the `ForwardingInfo` from the
  // `StartAggregationDataUploadResponse.aggregation_protocol_forwarding_info`
  // response field to construct the URI for this request. Otherwise, clients
  // should use the same `ForwardingInfo` as was used to construct the
  // `StartAggregationDataUpload` request URI.
  rpc AbortAggregation(AbortAggregationRequest)
      returns (AbortAggregationResponse) {}
}

message StartAggregationDataUploadRequest {
  // The id of the aggregation session this client participates in. This value
  // was returned by the server when the client was assigned a task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string aggregation_id = 1;

  // The authorization token returned by the server when the client was assigned
  // a task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string authorization_token = 2;
}

message StartAggregationDataUploadResponse {
  // Information to construct the URI to use for continuing the aggregation
  // protocol after the data is uploaded.
  ForwardingInfo aggregation_protocol_forwarding_info = 1;

  // Information about where to upload aggregation result data.
  ByteStreamResource resource = 2;

  // Unique token that the client must include in the subsequent protocol
  // requests.
  string client_token = 3;
}

message SubmitAggregationResultRequest {
  // The id of the aggregation session this client participates in. This value
  // was returned by the server when the client was assigned a task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string aggregation_id = 1;

  // The client token returned by the server when the client was assigned a
  // task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string client_token = 2;

  // Name of the resource to which the aggregration result was uploaded.
  string resource_name = 3;
}

message SubmitAggregationResultResponse {}

message AbortAggregationRequest {
  // The id of the aggregation session this client participates in. This value
  // was returned by the server when the client was assigned a task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string aggregation_id = 1;

  // The client token returned by the server when the client was assigned a
  // task.
  //
  // Note that HTTP clients set this value in the request URL instead of the
  // request body.
  string client_token = 2;

  // Status code and optional message for why the aggregation was aborted.
  Status status = 3;
}

message AbortAggregationResponse {}