From 6b10c80ea0e09bf9a8fb7834348e2d9ab82ffda7 Mon Sep 17 00:00:00 2001 From: Sanjay Vasandani Date: Wed, 7 Jun 2023 16:32:11 -0700 Subject: [PATCH] Fix api-linter errors. --- .github/workflows/api-lint.yml | 46 +++++++ src/main/proto/api-linter.yaml | 23 ++++ .../wfa/measurement/api/v2alpha/BUILD.bazel | 60 ++++++++- .../wfa/measurement/api/v2alpha/account.proto | 49 +++++--- .../api/v2alpha/accounts_service.proto | 43 ++++--- .../wfa/measurement/api/v2alpha/api_key.proto | 17 +-- .../api/v2alpha/api_keys_service.proto | 31 +++-- .../measurement/api/v2alpha/certificate.proto | 14 ++- .../api/v2alpha/certificates_service.proto | 53 +++++--- .../wfa/measurement/api/v2alpha/crypto.proto | 23 ++-- .../api/v2alpha/data_provider.proto | 34 ++--- .../api/v2alpha/data_providers_service.proto | 29 +++-- .../api/v2alpha/differential_privacy.proto | 2 + .../wfa/measurement/api/v2alpha/duchy.proto | 13 +- .../api/v2alpha/event_annotations.proto | 8 ++ .../measurement/api/v2alpha/event_group.proto | 39 ++++-- .../event_group_metadata_descriptor.proto | 2 + ...t_group_metadata_descriptors_service.proto | 83 +++++++++---- .../api/v2alpha/event_groups_service.proto | 73 +++++++---- .../measurement/api/v2alpha/exchange.proto | 15 ++- .../api/v2alpha/exchange_step.proto | 10 +- .../api/v2alpha/exchange_step_attempt.proto | 33 ++--- .../exchange_step_attempts_service.proto | 33 +++-- .../api/v2alpha/exchange_steps_service.proto | 39 +++++- .../api/v2alpha/exchange_workflow.proto | 33 +++-- .../api/v2alpha/exchanges_service.proto | 20 ++- .../measurement/api/v2alpha/measurement.proto | 109 ++++++++++------ .../api/v2alpha/measurement_consumer.proto | 36 ++++-- .../measurement_consumers_service.proto | 55 ++++++--- .../api/v2alpha/measurement_spec.proto | 21 +++- .../api/v2alpha/measurements_service.proto | 66 +++++++--- .../measurement/api/v2alpha/model_line.proto | 12 +- .../api/v2alpha/model_lines_service.proto | 38 ++++-- .../api/v2alpha/model_outage.proto | 8 +- .../api/v2alpha/model_outages_service.proto | 33 +++-- .../api/v2alpha/model_provider.proto | 2 + .../api/v2alpha/model_providers_service.proto | 12 +- .../api/v2alpha/model_release.proto | 5 + .../api/v2alpha/model_releases_service.proto | 22 +++- .../api/v2alpha/model_rollout.proto | 5 + .../api/v2alpha/model_rollouts_service.proto | 28 ++++- .../measurement/api/v2alpha/model_shard.proto | 16 ++- .../api/v2alpha/model_shards_service.proto | 25 +++- .../measurement/api/v2alpha/model_suite.proto | 4 + .../api/v2alpha/model_suites_service.proto | 29 +++-- .../api/v2alpha/protocol_config.proto | 63 ++++++---- .../measurement/api/v2alpha/public_key.proto | 14 ++- .../api/v2alpha/public_keys_service.proto | 17 ++- .../api/v2alpha/recurring_exchange.proto | 35 ++++-- .../measurement/api/v2alpha/requisition.proto | 116 ++++++++++++------ .../requisition_fulfillment_service.proto | 27 ++-- .../api/v2alpha/requisition_spec.proto | 46 ++++--- .../api/v2alpha/requisitions_service.proto | 67 ++++++---- tools/api-lint | 21 ++++ 54 files changed, 1260 insertions(+), 497 deletions(-) create mode 100644 .github/workflows/api-lint.yml create mode 100644 src/main/proto/api-linter.yaml create mode 100755 tools/api-lint diff --git a/.github/workflows/api-lint.yml b/.github/workflows/api-lint.yml new file mode 100644 index 000000000..39fb355b5 --- /dev/null +++ b/.github/workflows/api-lint.yml @@ -0,0 +1,46 @@ +# Copyright 2023 The Cross-Media Measurement 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. + +# TODO(world-federation-of-advertisers/actions#40): Use lint action once it runs +# api-linter. + +name: API lint + +on: + pull_request: + branches: [main] + types: [opened, synchronize, edited] + +jobs: + lint: + name: API lint + runs-on: ubuntu-20.04 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v3 + + - name: Set up api-linter + env: + VERSION: 1.48.0 + run: | + cd ~ + curl -L "https://github.com/googleapis/api-linter/releases/download/v${VERSION}/api-linter-${VERSION}-linux-amd64.tar.gz" -o api-linter.tar.gz + mkdir -p ~/.local/bin + tar -xf api-linter.tar.gz -C ~/.local/bin + + - env: + BAZEL: bazelisk + run: tools/api-lint diff --git a/src/main/proto/api-linter.yaml b/src/main/proto/api-linter.yaml new file mode 100644 index 000000000..89b61559f --- /dev/null +++ b/src/main/proto/api-linter.yaml @@ -0,0 +1,23 @@ +# Copyright 2022 The Cross-Media Measurement 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. + +- included_paths: + - 'wfa/measurement/api/v2alpha/**/*.proto' + disabled_rules: + - 'core::0191::java-package' + - 'core::0127::http-annotation' + - 'core::0133::http-uri-parent' + - 'core::0146::any' + - 'core::0133::request-id-field' + - 'core::0121::resource-must-support-get' diff --git a/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel b/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel index 9051050e6..099de3f5f 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel +++ b/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel @@ -16,6 +16,7 @@ proto_library( name = "crypto_proto", srcs = ["crypto.proto"], strip_import_prefix = IMPORT_PREFIX, + deps = ["@com_google_googleapis//google/api:field_behavior_proto"], ) proto_library( @@ -23,6 +24,7 @@ proto_library( srcs = ["certificate.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -33,6 +35,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":crypto_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -43,6 +46,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ "//src/main/proto/wfa/measurement/api/v2alpha:time_interval_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -55,6 +59,7 @@ proto_library( ":crypto_proto", ":measurement_proto", ":protocol_config_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -64,6 +69,7 @@ proto_library( srcs = ["account.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -73,6 +79,7 @@ proto_library( srcs = ["api_key.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -83,6 +90,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":crypto_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -94,6 +102,7 @@ proto_library( deps = [ ":crypto_proto", ":measurement_consumer_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -141,6 +150,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":differential_privacy_proto", + "@com_google_googleapis//google/api:field_behavior_proto", ], ) @@ -150,7 +160,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":differential_privacy_proto", - "@com_google_googleapis//google/api:resource_proto", + "@com_google_googleapis//google/api:field_behavior_proto", ], ) @@ -161,6 +171,7 @@ proto_library( deps = [ ":crypto_proto", ":protocol_config_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_protobuf//:duration_proto", ], @@ -171,6 +182,7 @@ proto_library( srcs = ["duchy.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -212,6 +224,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":model_suite_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], @@ -234,6 +247,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":model_line_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_protobuf//:timestamp_proto", @@ -259,6 +273,7 @@ proto_library( deps = [ ":model_rollout_proto", "//src/main/proto/wfa/measurement/api/v2alpha:time_interval_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_protobuf//:empty_proto", @@ -283,6 +298,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":model_release_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], @@ -293,10 +309,8 @@ proto_library( srcs = ["model_shard.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ - "//src/main/proto/wfa/measurement/api/v2alpha:time_interval_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", - "@com_google_protobuf//:any_proto", "@com_google_protobuf//:timestamp_proto", ], ) @@ -307,7 +321,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":model_shard_proto", - "//src/main/proto/wfa/measurement/api/v2alpha:time_interval_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_protobuf//:empty_proto", @@ -333,6 +347,7 @@ proto_library( deps = [ ":model_outage_proto", "//src/main/proto/wfa/measurement/api/v2alpha:time_interval_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], @@ -344,6 +359,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":exchange_workflow_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_googleapis//google/type:date_proto", ], @@ -354,6 +370,7 @@ proto_library( srcs = ["exchange.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_googleapis//google/type:date_proto", ], @@ -364,6 +381,7 @@ proto_library( srcs = ["exchange_step.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_googleapis//google/type:date_proto", ], @@ -374,6 +392,7 @@ proto_library( srcs = ["exchange_step_attempt.proto"], strip_import_prefix = IMPORT_PREFIX, deps = [ + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_protobuf//:timestamp_proto", ], @@ -386,6 +405,8 @@ proto_library( srcs = ["certificates_service.proto"], deps = [ ":certificate_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -393,7 +414,11 @@ proto_library( proto_library( name = "public_keys_service_proto", srcs = ["public_keys_service.proto"], - deps = [":public_key_proto"], + deps = [ + ":public_key_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", + ], ) proto_library( @@ -401,6 +426,8 @@ proto_library( srcs = ["accounts_service.proto"], deps = [ ":account_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -410,6 +437,8 @@ proto_library( srcs = ["api_keys_service.proto"], deps = [ ":api_key_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -421,6 +450,8 @@ proto_library( deps = [ ":measurement_proto", ":requisition_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -431,6 +462,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":requisition_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -441,6 +474,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":measurement_consumer_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -451,6 +486,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":measurement_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -461,6 +498,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":data_provider_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -471,6 +510,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":model_provider_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -481,6 +522,7 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":event_group_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], @@ -492,6 +534,8 @@ proto_library( strip_import_prefix = IMPORT_PREFIX, deps = [ ":event_group_metadata_descriptor_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -501,6 +545,8 @@ proto_library( srcs = ["exchanges_service.proto"], deps = [ ":exchange_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -510,6 +556,8 @@ proto_library( srcs = ["exchange_steps_service.proto"], deps = [ ":exchange_step_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", "@com_google_googleapis//google/type:date_proto", ], @@ -520,6 +568,8 @@ proto_library( srcs = ["exchange_step_attempts_service.proto"], deps = [ ":exchange_step_attempt_proto", + "@com_google_googleapis//google/api:client_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) diff --git a/src/main/proto/wfa/measurement/api/v2alpha/account.proto b/src/main/proto/wfa/measurement/api/v2alpha/account.proto index a172d8e39..3eac61d88 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/account.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/account.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -27,8 +28,13 @@ message Account { option (google.api.resource) = { type: "halo.wfanet.org/Account" pattern: "accounts/{account}" + singular: "account" + plural: "accounts" }; + reserved 5; + + // View of an `Account`. enum View { // The default/unset value. // @@ -46,13 +52,16 @@ message Account { // Resource name. string name = 1; - // Resource name of the `Account` that created this one. Output-only. - // Immutable. - string creator = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; + // Resource name of the `Account` that created this one. + string creator = 2 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = OUTPUT_ONLY, + (google.api.field_behavior) = IMMUTABLE + ]; // Possible activation state of an `Account`. enum ActivationState { + // Default value used if the state is omitted. ACTIVATION_STATE_UNSPECIFIED = 0; // The `Account` has not yet been activated. UNACTIVATED = 1; @@ -60,7 +69,8 @@ message Account { ACTIVATED = 2; } // Activation state of this `Account`. Output-only. - ActivationState activation_state = 3; + ActivationState activation_state = 3 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Parameters for activation of an `Account`. message ActivationParams { @@ -68,28 +78,27 @@ message Account { // owner of upon activation. Immutable. // // This can only be a `MeasurementConsumer` that `creator` is an owner of. - string owned_measurement_consumer = 1 - [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; - - // Token that can be used to activate the account. Output-only. - string activation_token = 2; + string owned_measurement_consumer = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = IMMUTABLE + ]; + + // Token that can be used to activate the account. + string activation_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; } // Parameters for activation of this `Account`. // // Only set when `activation_state` is `UNACTIVATED` in `FULL` view. ActivationParams activation_params = 4; - // DEPRECATED: suppose not to be owned by an Account - string measurement_consumer_creation_token = 5 [deprecated = true]; - // OpenID Connect identity. message OpenIdConnectIdentity { - // Issuer (`iss` claim value). Required. - string issuer = 1; + // Issuer (`iss` claim value). + string issuer = 1 [(google.api.field_behavior) = REQUIRED]; - // Subject Identifier (`subj` claim value). Required. - string subject = 2; + // Subject Identifier (`subj` claim value). + string subject = 2 [(google.api.field_behavior) = REQUIRED]; } // Identity of the user for this `Account`. Output-only. @@ -97,6 +106,8 @@ message Account { // This must be set when `activation_state` is `ACTIVATED`. The specified // value is unique across all `Account` resources. oneof identity { - OpenIdConnectIdentity open_id = 6; + // OpenID Connect identity. + OpenIdConnectIdentity open_id = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; } } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/accounts_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/accounts_service.proto index 6aa9b7f01..26147c49e 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/accounts_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/accounts_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/account.proto"; @@ -32,7 +34,9 @@ service Accounts { // `owned_measurement_consumer` in `activation_params`. // // Returns the `FULL` view of the created `Account`. - rpc CreateAccount(CreateAccountRequest) returns (Account) {} + rpc CreateAccount(CreateAccountRequest) returns (Account) { + option (google.api.method_signature) = "account"; + } // Activates an account by transitioning its `account_state` to `ACTIVATED`. // @@ -46,35 +50,43 @@ service Accounts { rpc ReplaceAccountIdentity(ReplaceAccountIdentityRequest) returns (Account) {} // Authenticates the user using an OpenID Connect (OIDC) provider. + // + // (-- api-linter: core::0136::verb-noun=disabled + // aip.dev/not-precedent: This isn't strictly acting on a resource. --) rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {} } // Request message for `CreateAccount` method. message CreateAccountRequest { - // The `Account` to create. Required. The `name` field will be ignored, and + // The `Account` to create. The `name` field will be ignored, and // the system will assign an ID. - Account account = 1; + Account account = 1 [(google.api.field_behavior) = REQUIRED]; } // Request message for `ActivateAccount` method. message ActivateAccountRequest { - // Resource name. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; - - // Activation token. Required. - string activation_token = 2; + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = REQUIRED + ]; + + // Activation token. + string activation_token = 2 [(google.api.field_behavior) = REQUIRED]; } // Request message for `ReplaceAccountIdentity` method. message ReplaceAccountIdentityRequest { - // Resource name. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = REQUIRED + ]; + // Credentials for an `OpenIdConnectIdentity`. message OpenIdConnectCredentials { // Encoded JSON Web Token (JWT). Required. - string identity_bearer_token = 1; + string identity_bearer_token = 1 [(google.api.field_behavior) = REQUIRED]; } // Replacement credentials for an identity. Required. @@ -86,12 +98,13 @@ message ReplaceAccountIdentityRequest { // Request message for `Authenticate` method. message AuthenticateRequest { - // OpenID Connect issuer identifier. Required. + // OpenID Connect issuer identifier. // // For Self-Issued OpenID Providers, this will be `https://self-issued.me`. - string issuer = 1; + string issuer = 1 [(google.api.field_behavior) = REQUIRED]; } +// Response message for `Authenticate` method. message AuthenticateResponse { // URI for id_token authentication request to OpenID Provider. string authentication_request_uri = 1; diff --git a/src/main/proto/wfa/measurement/api/v2alpha/api_key.proto b/src/main/proto/wfa/measurement/api/v2alpha/api_key.proto index e37924cd5..947c4869c 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/api_key.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/api_key.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -27,18 +28,20 @@ message ApiKey { option (google.api.resource) = { type: "halo.wfanet.org/ApiKey" pattern: "measurementConsumers/{measurement_consumer}/apiKeys/{api_key}" + singular: "apiKey" + plural: "apiKeys" }; + // Resource name. string name = 1; - // Human-readable nickname for this `ApiKey`. Required. - string nickname = 2; + // Human-readable nickname for this `ApiKey`. + string nickname = 2 [(google.api.field_behavior) = REQUIRED]; - // Optional human-readable description for the intended usage of this - // `ApiKey`. + // Human-readable description for the intended usage of this `ApiKey`. string description = 3; - // The actual API key for authentication. Output-only. Only set in - // `CreateApiKey` responses. - string authentication_key = 4; + // The actual API key for authentication. Only set in `CreateApiKey` + // responses. + string authentication_key = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/api_keys_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/api_keys_service.proto index 70cd69e8d..7113789c1 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/api_keys_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/api_keys_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/api_key.proto"; @@ -29,29 +31,38 @@ service ApiKeys { // // Results in PERMISSION_DENIED if the authenticated caller does not own the // `MeasurementConsumer` the `ApiKey` is being created for. - rpc CreateApiKey(CreateApiKeyRequest) returns (ApiKey) {} + rpc CreateApiKey(CreateApiKeyRequest) returns (ApiKey) { + option (google.api.method_signature) = "parent,api_key"; + } // Deletes an `ApiKey`. // // Results in PERMISSION_DENIED if the authenticated caller does not own the // `MeasurementConsumer` the `ApiKey` is being used for. - rpc DeleteApiKey(DeleteApiKeyRequest) returns (ApiKey) {} + rpc DeleteApiKey(DeleteApiKeyRequest) returns (ApiKey) { + option (google.api.method_signature) = "name"; + } } // Request message for `CreateApiKey` method. message CreateApiKeyRequest { - // Name of the parent `MeasurementConsumer`. Required. - string parent = 1 - [(google.api.resource_reference).child_type = "halo.wfanet.org/ApiKey"]; + // Name of the parent `MeasurementConsumer`. + string parent = 1 [ + (google.api.resource_reference).child_type = "halo.wfanet.org/ApiKey", + (google.api.field_behavior) = REQUIRED + ]; - // The `ApiKey` to create. Required. + // The `ApiKey` to create. // // The `name` field will be ignored, and the system will assign an ID. - ApiKey apiKey = 2; + ApiKey api_key = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `DeleteApiKey` method. message DeleteApiKeyRequest { - // Resource name of the `ApiKey` to delete. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/ApiKey"]; + // Resource name of the `ApiKey` to delete. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/ApiKey", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/certificate.proto b/src/main/proto/wfa/measurement/api/v2alpha/certificate.proto index 23124ffd9..a4c809ef2 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/certificate.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/certificate.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -30,6 +31,8 @@ message Certificate { pattern: "duchies/{duchy}/certificates/{certificate}" pattern: "measurementConsumers/{measurement_consumer}/certificates/{certificate}" pattern: "modelProviders/{model_provider}/certificates/{certificate}" + singular: "certificate" + plural: "certificates" }; // Resource name. @@ -39,12 +42,16 @@ message Certificate { string name = 1; // X.509 certificate in DER format. Required. Immutable. - bytes x509_der = 2; + bytes x509_der = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // RFC 5280 revocation state. // // This is *not* a resource state as defined by https://google.aip.dev/216. enum RevocationState { + // Default value used if the revocation state is omitted. REVOCATION_STATE_UNSPECIFIED = 0; // Certificate is on hold and therefore invalid, possibly temporarily. @@ -53,11 +60,12 @@ message Certificate { // Certificate has been revoked. Terminal state. REVOKED = 2; } - // Revocation state of the certificate reported by an API caller. Output-only. + // Revocation state of the certificate reported by an API caller. // // If specified, it means that the certificate is not currently valid. // // Note that this is not guaranteed to reflect the actual revocation state // determined by the issuing certificate authority. - RevocationState revocation_state = 3; + RevocationState revocation_state = 3 + [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/certificates_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/certificates_service.proto index ecde15898..2b5aca76d 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/certificates_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/certificates_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/certificate.proto"; @@ -26,10 +28,14 @@ option java_outer_classname = "CertificatesServiceProto"; // Service for interacting with `Certificate` resources. service Certificates { // Returns the `Certificate` with the specified resource name. - rpc GetCertificate(GetCertificateRequest) returns (Certificate) {} + rpc GetCertificate(GetCertificateRequest) returns (Certificate) { + option (google.api.method_signature) = "name"; + } // Creates (adds) a `Certificate`. - rpc CreateCertificate(CreateCertificateRequest) returns (Certificate) {} + rpc CreateCertificate(CreateCertificateRequest) returns (Certificate) { + option (google.api.method_signature) = "parent,certificate"; + } // Revokes a `Certificate` by setting its revocation state. rpc RevokeCertificate(RevokeCertificateRequest) returns (Certificate) {} @@ -43,35 +49,48 @@ service Certificates { // Request message for `GetCertificate` method. message GetCertificateRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateCertificate` method. message CreateCertificateRequest { - // Name of the parent resource. Required. - string parent = 1 [(google.api.resource_reference).child_type = - "halo.wfanet.org/Certificate"]; + // Name of the parent resource. + string parent = 1 [ + (google.api.resource_reference).child_type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; - // The `Certificate` to create. Required. + // The `Certificate` to create. // // The `name` field will be ignored, and the system will assign an ID. - Certificate certificate = 2; + Certificate certificate = 2 [(google.api.field_behavior) = REQUIRED]; } // Request message for `RevokeCertificate` method. message RevokeCertificateRequest { - // Resource name. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; - // Revocation state to set. Required. - Certificate.RevocationState revocation_state = 2; + // Revocation state to set. + // + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) + Certificate.RevocationState revocation_state = 2 + [(google.api.field_behavior) = REQUIRED]; } // Request message for `ReleaseCertificateHold` method. message ReleaseCertificateHoldRequest { - // Resource name. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/crypto.proto b/src/main/proto/wfa/measurement/api/v2alpha/crypto.proto index 060c8355e..375a94fd9 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/crypto.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/crypto.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; + option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "CryptoProto"; @@ -24,27 +26,30 @@ option java_outer_classname = "CryptoProto"; message ElGamalPublicKey { // ID of the OpenSSL built-in elliptic curve. For example, 415 for the // prime256v1 curve. - int32 elliptic_curve_id = 1; + int32 elliptic_curve_id = 1 [(google.api.field_behavior) = REQUIRED]; // Public key generator `g`. - bytes generator = 2; + bytes generator = 2 [(google.api.field_behavior) = REQUIRED]; // Public key element `y = g^x`, where `g` is the generator and `x` is the // secret key. - bytes element = 3; + bytes element = 3 [(google.api.field_behavior) = REQUIRED]; } +// Data with an accompanying digital signature. message SignedData { // Arbitrary data to sign. - bytes data = 1; + bytes data = 1 [(google.api.field_behavior) = REQUIRED]; // Cryptographic digital signature of `data`. - bytes signature = 2; + bytes signature = 2 [(google.api.field_behavior) = REQUIRED]; } // A public key for asymmetric encryption. message EncryptionPublicKey { + // Format of data for a public key. enum Format { + // Default value used if the format is omitted. FORMAT_UNSPECIFIED = 0; // Tink Keyset format. @@ -56,12 +61,12 @@ message EncryptionPublicKey { // https://github.com/google/tink/blob/master/proto/tink.proto. TINK_KEYSET = 1; } - // Encryption key format. Required. - Format format = 1; + // Format of data for this public key. + Format format = 1 [(google.api.field_behavior) = REQUIRED]; - // The format-specific key data. Required. + // The format-specific key data. // // `format` and `data` together must specify all necessary information to // decrypt messages given a private key. - bytes data = 2; + bytes data = 2 [(google.api.field_behavior) = REQUIRED]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/data_provider.proto b/src/main/proto/wfa/measurement/api/v2alpha/data_provider.proto index a88510b4b..2122c9baf 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/data_provider.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/data_provider.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/crypto.proto"; @@ -29,36 +30,37 @@ message DataProvider { option (google.api.resource) = { type: "halo.wfanet.org/DataProvider" pattern: "dataProviders/{data_provider}" + singular: "dataProvider" + plural: "dataProviders" }; // Resource name. string name = 1; // The X.509 certificate belonging to this `DataProvider` in DER format which - // can be used to verify `public_key`. Required. - bytes certificate_der = 2; + // can be used to verify `public_key`. + bytes certificate_der = 2 [(google.api.field_behavior) = REQUIRED]; // Resource name of the `Certificate` belonging to this `DataProvider` which - // can be used to verify `public_key`. Output-only. + // can be used to verify `public_key`. // // The `x509_der` field of this resource matches `certificate_der`. - string certificate = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + string certificate = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = OUTPUT_ONLY + ]; // Serialized `EncryptionPublicKey` for this `DataProvider`, which can be - // verified using `certificate`. Required. - SignedData public_key = 4; + // verified using `certificate`. + SignedData public_key = 4 [(google.api.field_behavior) = REQUIRED]; // Display name of the data provider. string display_name = 5; - // The list of duchies that must be included in all computations involving - // this `DataProvider` - repeated string required_external_duchy_ids = 6; -} - -// Wrapper for a list of `DataProvider` resource names. -message DataProviderList { - repeated string data_provider = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Resource names of every `Duchy` that must be included in all computations + // involving this `DataProvider`. + repeated string required_duchies = 6 [ + (google.api.resource_reference).type = "halo.wfanet.org/Duchy", + (google.api.field_behavior) = UNORDERED_LIST + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/data_providers_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/data_providers_service.proto index 25f4efe56..a74de9f6a 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/data_providers_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/data_providers_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/data_provider.proto"; @@ -26,25 +28,36 @@ option java_outer_classname = "DataProvidersServiceProto"; // Service for interacting with `DataProvider` resources. service DataProviders { // Returns the `DataProvider` with the specified resource key. - rpc GetDataProvider(GetDataProviderRequest) returns (DataProvider) {} + rpc GetDataProvider(GetDataProviderRequest) returns (DataProvider) { + option (google.api.method_signature) = "name"; + } // Replaces the `required_duchies` field in a `DataProvider` resource. rpc ReplaceDataProviderRequiredDuchies( ReplaceDataProviderRequiredDuchiesRequest) returns (DataProvider) {} } -// Request message for ReplaceDataProviderDuchyList +// Request message for the `ReplaceDataProviderRequiredDuchies` method. message ReplaceDataProviderRequiredDuchiesRequest { - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; - - repeated string required_external_duchies = 2 + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; + + // Replacement for the `required_duchies` field. + // + // (-- api-linter: core::0203::required=disabled + // aip.dev/not-precedent: api-linter incorrectly identifies this. --) + repeated string required_duchies = 2 [(google.api.resource_reference).type = "halo.wfanet.org/Duchy"]; } // Request message for `GetDataProvider` method. message GetDataProviderRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/differential_privacy.proto b/src/main/proto/wfa/measurement/api/v2alpha/differential_privacy.proto index 7d56defd7..f75921da1 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/differential_privacy.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/differential_privacy.proto @@ -26,6 +26,8 @@ option java_outer_classname = "DifferentialPrivacyProto"; // foundations of differential privacy. Foundations and Trends in Theoretical // Computer Science, 9(3-4), pp.211-407." message DifferentialPrivacyParams { + // ε. The privacy budget. double epsilon = 1; + // δ. The probability of information accidentally being leaked. double delta = 2; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/duchy.proto b/src/main/proto/wfa/measurement/api/v2alpha/duchy.proto index f2d4a19c2..1a08fdf87 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/duchy.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/duchy.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -27,19 +28,21 @@ message Duchy { option (google.api.resource) = { type: "halo.wfanet.org/Duchy" pattern: "duchies/{duchy}" + singular: "duchy" + plural: "duchies" }; // Resource name. string name = 1; // The *preferred* X.509 certificate belonging to this `Duchy` in DER format. - // Required. - bytes preferred_certificate_der = 2; + bytes preferred_certificate_der = 2 [(google.api.field_behavior) = REQUIRED]; // Resource name of the *preferred* `Certificate` belonging to this `Duchy`. - // Output-only. // // The `x509_der` field of this resource matches `preferred_certificate_der`. - string preferred_certificate = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + string preferred_certificate = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = OUTPUT_ONLY + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/event_annotations.proto b/src/main/proto/wfa/measurement/api/v2alpha/event_annotations.proto index 9b2acd02d..a3ced40ef 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/event_annotations.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/event_annotations.proto @@ -12,6 +12,13 @@ // See the License for the specific language governing permissions and // limitations under the License. +// (-- +// api-linter: core::0123::resource-annotation=disabled +// api-linter: core::0203::required=disabled +// api-linter: core::0203::immutable=disabled +// aip.dev/not-precedent: These are protobuf annotations, not API messages. +// --) + syntax = "proto3"; package wfa.measurement.api.v2alpha; @@ -20,6 +27,7 @@ import "google/protobuf/descriptor.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; +option java_outer_classname = "EventAnnotationsProto"; // Descriptor for a field inside of an event template message. message EventFieldDescriptor { diff --git a/src/main/proto/wfa/measurement/api/v2alpha/event_group.proto b/src/main/proto/wfa/measurement/api/v2alpha/event_group.proto index 888590aab..d43593b0b 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/event_group.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/event_group.proto @@ -31,15 +31,21 @@ message EventGroup { option (google.api.resource) = { type: "halo.wfanet.org/EventGroup" pattern: "dataProviders/{data_provider}/eventGroups/{event_group}" + singular: "eventGroup" + plural: "eventGroups" }; // Resource name. string name = 1; // Resource name of the `MeasurementConsumer` associated with this - // `EventGroup`. Required. Immutable. - string measurement_consumer = 2 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + // `EventGroup`. + string measurement_consumer = 2 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Resource name of the `Certificate` belonging to `measurement_consumer`. // Must be set if `measurement_consumer_public_key` is set. @@ -56,29 +62,36 @@ message EventGroup { string event_group_reference_id = 5; // The set of VID model lines used to label events in this `EventGroup`. - // Required. - repeated string vid_model_lines = 6; + repeated string vid_model_lines = 6 [ + (google.api.resource_reference).type = "halo.wfanet.org/ModelLine", + (google.api.field_behavior) = UNORDERED_LIST + ]; + // Template for an event message. message EventTemplate { // The type of the Event Template. A fully-qualified protobuf message type. - // Required. - string type = 1; + string type = 1 [(google.api.field_behavior) = REQUIRED]; } // The `EventTemplate`s that events associated with this `EventGroup` conform // to. - repeated EventTemplate event_templates = 7; + repeated EventTemplate event_templates = 7 + [(google.api.field_behavior) = UNORDERED_LIST]; // Wrapper for per-EDP EventGroup metadata. message Metadata { // The resource name of the metadata descriptor. - string event_group_metadata_descriptor = 1 - [(google.api.resource_reference).type = - "halo.wfanet.org/EventGroupMetadataDescriptor"]; + string event_group_metadata_descriptor = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/EventGroupMetadataDescriptor", + (google.api.field_behavior) = REQUIRED + ]; // A message of a type described by the descriptor along with its type URL, // encoded as an `Any` message. - google.protobuf.Any metadata = 2; + // + // See https://protobuf.dev/programming-guides/techniques/#self-description + google.protobuf.Any metadata = 2 [(google.api.field_behavior) = REQUIRED]; } // Encrypted serialized `Metadata`. The encryption uses @@ -95,6 +108,6 @@ message EventGroup { // have all mutable optional fields cleared. This state is terminal. DELETED = 2; } - // Event Group state. Output-only. + // Event Group state. State state = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptor.proto b/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptor.proto index 275fe4c81..ab7762d99 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptor.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptor.proto @@ -33,6 +33,8 @@ message EventGroupMetadataDescriptor { option (google.api.resource) = { type: "halo.wfanet.org/EventGroupMetadataDescriptor" pattern: "dataProviders/{data_provider}/eventGroupMetadataDescriptors/{event_group_metadata_descriptor}" + singular: "eventGroupMetadataDescriptor" + plural: "eventGroupMetadataDescriptors" }; // Resource name. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptors_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptors_service.proto index 51a6b94c4..79b6a6b1f 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptors_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/event_group_metadata_descriptors_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/event_group_metadata_descriptor.proto"; @@ -28,21 +30,30 @@ service EventGroupMetadataDescriptors { // Returns the `EventGroupMetadataDescriptor` with the specified resource // name. rpc GetEventGroupMetadataDescriptor(GetEventGroupMetadataDescriptorRequest) - returns (EventGroupMetadataDescriptor) {} + returns (EventGroupMetadataDescriptor) { + option (google.api.method_signature) = "name"; + } // Creates (registers) a `EventGroupMetadataDescriptor` defined in the // specified `DataProvider`'s system. rpc CreateEventGroupMetadataDescriptor( CreateEventGroupMetadataDescriptorRequest) - returns (EventGroupMetadataDescriptor) {} + returns (EventGroupMetadataDescriptor) { + option (google.api.method_signature) = + "parent,event_group_metadata_descriptor"; + } // Updates an existing `EventGroupMetadataDescriptor`. Results in a // `PERMISSION_DENIED` error if the authenticated user does not have access to // the `EventGroupMetadataDescriptor`. Results in a `NOT_FOUND` error if the // the specified `EventGroupMetadataDescriptor` does not exist. + // (-- api-linter: core::0134::method-signature=disabled + // aip.dev/not-precedent: Partial update not supported. --) rpc UpdateEventGroupMetadataDescriptor( UpdateEventGroupMetadataDescriptorRequest) - returns (EventGroupMetadataDescriptor) {} + returns (EventGroupMetadataDescriptor) { + option (google.api.method_signature) = "event_group_metadata_descriptor"; + } // Batch gets `EventGroupMetadataDescriptors`s. Results in a `NOT_FOUND` error // if any of the specified `EventGroupMetadataDescriptor`s does not exist. @@ -55,28 +66,34 @@ service EventGroupMetadataDescriptors { // authenticated user does not have access to. rpc ListEventGroupMetadataDescriptors( ListEventGroupMetadataDescriptorsRequest) - returns (ListEventGroupMetadataDescriptorsResponse); + returns (ListEventGroupMetadataDescriptorsResponse) { + option (google.api.method_signature) = "parent"; + } } // Request message for `GetEventGroupMetadataDescriptor` method. message GetEventGroupMetadataDescriptorRequest { // Resource name. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/EventGroupMetadataDescriptor"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/EventGroupMetadataDescriptor", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateEventGroupMetadataDescriptor` method. message CreateEventGroupMetadataDescriptorRequest { - // Resource name of the parent `DataProvider`. Required. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Resource name of the parent `DataProvider`. + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; - // The `EventGroupMetadataDescriptor` to create. Required. + // The `EventGroupMetadataDescriptor` to create. // - // The `name` field will be ignored, and the system will assign an ID. Results - // in an `ALREADY_EXISTS` error if there is already a child - // `EventGroupMetadataDescriptor` with the same `event_group_reference_id`. - EventGroupMetadataDescriptor event_group_metadata_descriptor = 2; + // The `name` field will be ignored, and the system will assign an ID. + EventGroupMetadataDescriptor event_group_metadata_descriptor = 2 + [(google.api.field_behavior) = REQUIRED]; // Unique identifier for this request. // @@ -88,32 +105,45 @@ message CreateEventGroupMetadataDescriptorRequest { } // Request message for `UpdateEventGroup` method. +// +// (-- api-linter: core::0134::request-mask-required=disabled +// aip.dev/not-precedent: Partial update not supported. --) message UpdateEventGroupMetadataDescriptorRequest { - // The `EventGroupMetadataDescriptor` to update. Required. - EventGroupMetadataDescriptor event_group_metadata_descriptor = 1; + // The `EventGroupMetadataDescriptor` to update. + EventGroupMetadataDescriptor event_group_metadata_descriptor = 1 + [(google.api.field_behavior) = REQUIRED]; } +// Request message for `BatchGetEventGroupMetadataDescriptors` method. message BatchGetEventGroupMetadataDescriptorsRequest { - // Resource name of the parent `DataProvider`. Required. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; - - // The names of `EventGroupMetadataDescriptor`s to retrieve. - repeated string names = 2 - [(google.api.resource_reference).type = - "halo.wfanet.org/EventGroupMetadataDescriptor"]; + // Resource name of the parent `DataProvider`. + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; + + // The resource names of `EventGroupMetadataDescriptor`s to retrieve. + repeated string names = 2 [ + (google.api.resource_reference).type = + "halo.wfanet.org/EventGroupMetadataDescriptor", + (google.api.field_behavior) = REQUIRED + ]; } +// Response message for `BatchGetEventGroupMetadataDescriptors` method. message BatchGetEventGroupMetadataDescriptorsResponse { // The `EventGroupMetadataDescriptor` resources. repeated EventGroupMetadataDescriptor event_group_metadata_descriptors = 1; } +// Request message for `ListEventGroupMetadataDescriptors` method. message ListEventGroupMetadataDescriptorsRequest { // Resource name of the parent `DataProvider`. The wildcard ID (`-`) may be // used in place of the `DataProvider` ID to list across `DataProvider`s. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `EventGroupMetadataDescriptor`s to return. The // service may return fewer than this value. If unspecified, at most 50 @@ -126,6 +156,7 @@ message ListEventGroupMetadataDescriptorsRequest { string page_token = 3; } +// Response message for `ListEventGroupMetadataDescriptors` method. message ListEventGroupMetadataDescriptorsResponse { // The `EventGroupMetadataDescriptor` resources. repeated EventGroupMetadataDescriptor event_group_metadata_descriptors = 1; diff --git a/src/main/proto/wfa/measurement/api/v2alpha/event_groups_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/event_groups_service.proto index dbf96d3eb..18c48f1fc 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/event_groups_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/event_groups_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/event_group.proto"; @@ -27,47 +28,63 @@ option java_outer_classname = "EventGroupsServiceProto"; // Service for interacting with `EventGroup` resources. service EventGroups { // Returns the `EventGroup` with the specified resource key. - rpc GetEventGroup(GetEventGroupRequest) returns (EventGroup) {} + rpc GetEventGroup(GetEventGroupRequest) returns (EventGroup) { + option (google.api.method_signature) = "name"; + } // Creates (registers) a `EventGroup` defined in the specified // `DataProvider`'s system. - rpc CreateEventGroup(CreateEventGroupRequest) returns (EventGroup) {} + rpc CreateEventGroup(CreateEventGroupRequest) returns (EventGroup) { + option (google.api.method_signature) = "parent,event_group"; + } // Updates an existing `EventGroup`. Results in a `PERMISSION_DENIED` error if // the authenticated user does not have access to the `EventGroup`. Results in // a `NOT_FOUND` error if the the specified `EventGroup` does not exist. - rpc UpdateEventGroup(UpdateEventGroupRequest) returns (EventGroup) {} + // (-- api-linter: core::0134::method-signature=disabled + // aip.dev/not-precedent: Partial update not supported. --) + rpc UpdateEventGroup(UpdateEventGroupRequest) returns (EventGroup) { + option (google.api.method_signature) = "event_group"; + } // Deletes an existing `EventGroup`. `EventGroup` will transition to a DELETED // state and will have all of its mutable optional fields cleared. This action // is irreversible. Results in a `PERMISSION_DENIED` error if the // authenticated user does not have access to the `EventGroup`. Results in a // `NOT_FOUND` error if the the specified `EventGroup` does not exist. - rpc DeleteEventGroup(DeleteEventGroupRequest) returns (EventGroup) {} + rpc DeleteEventGroup(DeleteEventGroupRequest) returns (EventGroup) { + option (google.api.method_signature) = "name"; + } // Lists `EventGroup`s. Results in a `PERMISSION_DENIED` error if attempting // to list `EventGroup`s that the authenticated user does not have access to. rpc ListEventGroups(ListEventGroupsRequest) - returns (ListEventGroupsResponse) {} + returns (ListEventGroupsResponse) { + option (google.api.method_signature) = "parent"; + } } // Request message for `GetEventGroup` method. message GetEventGroupRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/EventGroup"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/EventGroup", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateEventGroup` method. message CreateEventGroupRequest { - // Resource name of the parent `DataProvider`. Required. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Resource name of the parent `DataProvider`. + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; - // The `EventGroup` to create. Required. + // The `EventGroup` to create. // // The `name` field will be ignored, and the system will assign an ID. - EventGroup event_group = 2; + EventGroup event_group = 2 [(google.api.field_behavior) = REQUIRED]; // Unique identifier for this request. // @@ -77,26 +94,31 @@ message CreateEventGroupRequest { } // Request message for `UpdateEventGroup` method. +// (-- api-linter: core::0134::request-mask-required=disabled +// aip.dev/not-precedent: Partial update not supported. --) message UpdateEventGroupRequest { - // The `EventGroup` to update. Required. - EventGroup event_group = 1; + // Resource. + EventGroup event_group = 1 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `DeleteEventGroup` method. message DeleteEventGroupRequest { - // The name of `EventGroup` to delete. Required. - // Format: dataProviders/{dataProvider}/eventGroups/{eventGroup} + // Resource name. string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference).type = "halo.wfanet.org/EventGroup" ]; } +// Request message for `ListEventGroups` method. message ListEventGroupsRequest { - // Resource key of the parent `DataProvider`. The wildcard ID (`-`) may be + // Resource name of the parent `DataProvider`. The wildcard ID (`-`) may be // used in place of the `DataProvider` ID to list across `DataProvider`s, in // which case a filter should be specified. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `EventGroup`s to return. The service may return fewer // than this value. If unspecified, at most 50 `EventGroup`s will be returned. @@ -106,20 +128,27 @@ message ListEventGroupsRequest { // https://aip.dev/158. string page_token = 3; - // Filter criteria. Repeated fields are treated as logical ORs, and multiple - // fields specified as logical ANDs. + // Filter criteria for a `ListEventGroups` request. + // + // Repeated fields are treated as logical ORs, and multiple fields specified + // as logical ANDs. message Filter { + // Matches against the `measurement_consumer` field. repeated string measurement_consumers = 1 [(google.api.resource_reference).type = "halo.wfanet.org/MeasurementConsumer"]; } - // Result filter. + // Filter criteria for this request. + // + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; // Whether to include EventGroups in the DELETED state. bool show_deleted = 5; } +// Response message for `ListEventGroups` method. message ListEventGroupsResponse { // The `EventGroup` resources. repeated EventGroup event_groups = 1; diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange.proto index cc97f488f..4c14c245b 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/type/date.proto"; @@ -30,6 +31,8 @@ message Exchange { pattern: "recurringExchanges/{recurring_exchange}/exchanges/{exchange}" pattern: "dataProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}" pattern: "modelProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}" + singular: "exchange" + plural: "exchanges" }; // Resource name. @@ -38,7 +41,9 @@ message Exchange { // Must be a complete date (no field can be unset/zero). google.type.Date date = 2; + // State of an `Exchange`. enum State { + // Default value used if the state is omitted. STATE_UNSPECIFIED = 0; // The exchange is has not yet reached a terminal state. @@ -50,9 +55,8 @@ message Exchange { // The exchange has failed. FAILED = 3; } - - // State of the Exchange. Output-only. - State state = 3; + // State of this `Exchange`. + State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; // SHA256 hash of the audit trail, if uploaded. bytes audit_trail_hash = 4; @@ -61,7 +65,6 @@ message Exchange { // relationship between all steps. // // See https://graphviz.org/doc/info/lang.html for the language specification. - // - // Output only. - string graphviz_representation = 5; + string graphviz_representation = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step.proto index 40cd7f642..86304b1c4 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/type/date.proto"; @@ -30,13 +31,15 @@ message ExchangeStep { pattern: "recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}" pattern: "dataProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}" pattern: "modelProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}" + singular: "exchangeStep" + plural: "exchangeSteps" }; // Resource name. string name = 1; - // Output-only. - State state = 2; + // State of this `ExchangeStep`. + State state = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; // Serialized ExchangeWorkflow that this ExchangeStep corresponds to. bytes serialized_exchange_workflow = 3; @@ -48,7 +51,9 @@ message ExchangeStep { // Current index of the step inside the serialized_exchange_workflow. int32 step_index = 5; + // State of an `ExchangeStep`. enum State { + // Default value used if the state is omitted. STATE_UNSPECIFIED = 0; // Some predecessor ExchangeStep is not in state SUCCEEDED. @@ -56,6 +61,7 @@ message ExchangeStep { // All predecessor ExchangeSteps are in state `SUCCEEDED` and there are no // associated ExchangeStepAttempts. + // (-- api-linter: core::0216::value-synonyms=disabled --) READY = 2; // All predecessor ExchangeSteps are in state `SUCCEEDED` and there is at diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempt.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempt.proto index e0fd2fe89..4d68141de 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempt.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempt.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/timestamp.proto"; @@ -28,8 +29,8 @@ message ExchangeStepAttempt { option (google.api.resource) = { type: "halo.wfanet.org/ExchangeStepAttempt" pattern: "recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}/attempts/{exchange_step_attempt}" - pattern: "dataProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}/attempts/{exchange_step_attempt}" - pattern: "modelProviders/{data_provider}/recurringExchanges/{recurring_exchange}/exchanges/{exchange}/steps/{exchange_step}/attempts/{exchange_step_attempt}" + singular: "exchangeStepAttempt" + plural: "exchangeStepAttempts" }; // Resource name. @@ -37,10 +38,11 @@ message ExchangeStepAttempt { // An ExchangeStep can have multiple ExchangeStepAttempts. When sorted by // `start_time`, these form a contiguous sequence of integers starting at 1. - // Output-only. - int32 attempt_number = 2; + int32 attempt_number = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; + // State of an `ExchangeStepAttempt`. enum State { + // The default value if the state is omitted. STATE_UNSPECIFIED = 0; // The attempt is has not yet reached a terminal state. @@ -59,22 +61,25 @@ message ExchangeStepAttempt { FAILED_STEP = 4; } - // State of the ExchangeStepAttempt. Output-only. - State state = 3; + // State of this `ExchangeStepAttempt`. + State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; - message DebugLog { - // When the log entry was made. - google.protobuf.Timestamp time = 1; + // Entry of debug log. + message DebugLogEntry { + // Time of the log entry from the caller. + google.protobuf.Timestamp entry_time = 1; // Human-readable debug message. This should NOT include any user data. string message = 2; } // Warnings, errors, and other messages for debugging purposes. Append-only. - repeated DebugLog debug_log_entries = 4; + repeated DebugLogEntry debug_log_entries = 4; - // When the ExchangeStepAttempt was created. Output-only. - google.protobuf.Timestamp start_time = 5; + // When the ExchangeStepAttempt was created. + google.protobuf.Timestamp start_time = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; - // When the ExchangeStepAttempt was last updated. Output-only. - google.protobuf.Timestamp update_time = 6; + // When the ExchangeStepAttempt was last updated. + google.protobuf.Timestamp update_time = 6 + [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempts_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempts_service.proto index 3f650f4fc..e421623c1 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempts_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange_step_attempts_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/exchange_step_attempt.proto"; @@ -29,7 +30,8 @@ option java_outer_classname = "ExchangeStepAttemptsServiceProto"; // /ExchangeSteps.ClaimReadyExchangeStep method. service ExchangeStepAttempts { // Adds a log entry to an `ExchangeStepAttempt`. - rpc AppendLogEntry(AppendLogEntryRequest) returns (ExchangeStepAttempt); + rpc AppendExchangeStepAttemptLogEntry( + AppendExchangeStepAttemptLogEntryRequest) returns (ExchangeStepAttempt); // Marks an `ExchangeStepAttempt` as finished (either successfully or not). // @@ -39,26 +41,37 @@ service ExchangeStepAttempts { returns (ExchangeStepAttempt); } -// Request message for `AppendLogEntry` method. -message AppendLogEntryRequest { +// Request message for `AppendExchangeStepLogEntry` method. +message AppendExchangeStepAttemptLogEntryRequest { // The `ExchangeStepAttempt` to append the entry to. It must be in a valid, // non-terminal state. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/ExchangeStepAttempt"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/ExchangeStepAttempt", + (google.api.field_behavior) = REQUIRED + ]; // The messages to append. Do NOT include sensitive information in this field. - repeated ExchangeStepAttempt.DebugLog log_entries = 2; + repeated ExchangeStepAttempt.DebugLogEntry log_entries = 2 + [(google.api.field_behavior) = REQUIRED]; } // Request message for `FinishExchangeStepAttempt` method. message FinishExchangeStepAttemptRequest { // The `ExchangeStep` to finish. It must be in a valid, non-terminal state. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/ExchangeStepAttempt"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/ExchangeStepAttempt", + (google.api.field_behavior) = REQUIRED + ]; // The ultimate state of the `ExchangeStepAttempt`. Must be a terminal state. - ExchangeStepAttempt.State final_state = 2; + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) + ExchangeStepAttempt.State final_state = 2 + [(google.api.field_behavior) = REQUIRED]; // Final debug log entries to append concurrently with the state transition. - repeated ExchangeStepAttempt.DebugLog log_entries = 3; + repeated ExchangeStepAttempt.DebugLogEntry log_entries = 3; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange_steps_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange_steps_service.proto index 332d8775f..855b0e8b6 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange_steps_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange_steps_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/type/date.proto"; import "wfa/measurement/api/v2alpha/exchange_step.proto"; @@ -37,7 +39,9 @@ service ExchangeSteps { // Lists `ExchangeStep`s. rpc ListExchangeSteps(ListExchangeStepsRequest) - returns (ListExchangeStepsResponse); + returns (ListExchangeStepsResponse) { + option (google.api.method_signature) = "parent"; + } } // Request message for `ClaimReadyExchangeStep` method. @@ -45,8 +49,10 @@ message ClaimReadyExchangeStepRequest { // If an `ExchangeStep` is returned, it should be executed by this party. // Required. oneof party { + // Resource name of parent `DataProvider`. string data_provider = 1 [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Resource name of parent `ModelProvider`. string model_provider = 2 [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; } @@ -65,8 +71,11 @@ message ClaimReadyExchangeStepResponse { // Request message for `ListExchangeSteps` method. message ListExchangeStepsRequest { - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Exchange"]; + // Resource name of the parent `Exchange`. + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Exchange", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `ExchangeStep`s to return. // The service may return fewer than this value. @@ -85,29 +94,47 @@ message ListExchangeStepsRequest { // Filter criteria. Repeated fields are treated as logical ORs, and multiple // fields specified as logical ANDs. message Filter { + // Matches against the `exchange_date` field. repeated google.type.Date exchange_dates = 1; + // Matches against the `state` field. + // + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) repeated ExchangeStep.State states = 2; + // Matches against the `event_data_provider` field of the ancestor + // `RecurringExchange`. repeated string recurring_exchange_data_providers = 3 [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Matches against the `model_provider` field of the ancestor + // `RecurringExchange`. repeated string recurring_exchange_model_providers = 4 [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; // Party name. oneof party { + // Matches against the `event_data_provider` field of the ancestor + // `RecurringExchange`. string data_provider = 5 [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Matches against the `model_provider` field of the ancestor + // `RecurringExchange`. string model_provider = 6 [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; } } + // Filter criteria for this request. + // + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; } +// Response message for `ListExchangeSteps` method. message ListExchangeStepsResponse { - // List of `ExchangeStep`s that has all of the tags in the - // ListExchangeStepsRequest - repeated ExchangeStep exchange_step = 1; + // Resources. + repeated ExchangeStep exchange_steps = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchange_workflow.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchange_workflow.proto index 7fdfa85d9..c20876128 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchange_workflow.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchange_workflow.proto @@ -29,9 +29,17 @@ option java_outer_classname = "ExchangeWorkflowProto"; // // See docs/panelmatch/example-exchange-workflow.textproto for an example // ExchangeWorkflow. +// +// (-- TODO(@stevenwarejones): Add documentation as mandated by AIP-192. --) +// (-- api-linter: core::0192::has-comments=disabled +// aip.dev/not-precedent: TODO --) +// +// (-- api-linter: core::0140::prepositions=disabled +// aip.dev/not-precedent: These are used to describe actions. --) message ExchangeWorkflow { // The type of participant that executes each step. enum Party { + // Default value used if the party is omitted. PARTY_UNSPECIFIED = 0; MODEL_PROVIDER = 1; DATA_PROVIDER = 2; @@ -39,7 +47,8 @@ message ExchangeWorkflow { // The type of storage used for shared storage in a workflow. enum StorageType { - UNKNOWN_STORAGE_CLIENT = 0; + // Default value used if the storage type is omitted. + STORAGE_TYPE_UNSPECIFIED = 0; GOOGLE_CLOUD_STORAGE = 1; AMAZON_S3 = 2; } @@ -57,6 +66,7 @@ message ExchangeWorkflow { // when, for each input label, there is a completed step with the same // output label. map input_labels = 3; + // Map from the step-specific name to a label for the output. map output_labels = 4; // Copies blobs from private to shared storage. @@ -87,7 +97,8 @@ message ExchangeWorkflow { message CopyOptions { enum LabelType { - BLOB_TYPE_UNKNOWN = 0; + // Default value used if the label type is omitted. + LABEL_TYPE_UNSPECIFIED = 0; // Indicates the blob should be treated as an opaque blob. BLOB = 1; @@ -136,8 +147,8 @@ message ExchangeWorkflow { // This is generally an instance of private_membership.batch.Parameters. google.protobuf.Any parameters = 1; int32 encrypted_query_result_file_count = 2; - int32 num_shards = 3; - int32 num_buckets_per_shard = 4; + int32 shard_count = 3; + int32 buckets_per_shard = 4; int32 max_queries_per_shard = 5; } @@ -147,10 +158,12 @@ message ExchangeWorkflow { google.protobuf.Any parameters = 1; int32 encrypted_query_bundle_file_count = 2; int32 query_id_to_ids_file_count = 3; - int32 num_shards = 4; - int32 num_buckets_per_shard = 5; - // Consider making this optional once its not experimental - int32 num_queries_per_shard = 6; + int32 shard_count = 4; + int32 buckets_per_shard = 5; + // (-- TODO: Consider making this optional once its not experimental. --) + // (-- api-linter: core::0203::optional=disabled + // aip.dev/not-precedent: Linter incorrectly identifies this. --) + int32 queries_per_shard = 6; bool add_padding_queries = 7; } @@ -195,7 +208,7 @@ message ExchangeWorkflow { // Generates random bytes message GenerateRandomBytesStep { - int32 num_bytes = 1; + int32 byte_count = 1; } oneof step { @@ -234,6 +247,7 @@ message ExchangeWorkflow { // Sequence of steps of the workflow. repeated Step steps = 1; + // Identifiers for an `Exchange`. message ExchangeIdentifiers { // Resource key of the Data Provider for the recurring exchange. string data_provider = 2 @@ -251,6 +265,7 @@ message ExchangeWorkflow { StorageType storage = 5; } + // Identifiers for the `Exchange`. ExchangeIdentifiers exchange_identifiers = 2; // The date of the first Exchange. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/exchanges_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/exchanges_service.proto index e7ff05829..129fdaf95 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/exchanges_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/exchanges_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/exchange.proto"; @@ -26,20 +28,16 @@ option java_outer_classname = "ExchangesServiceProto"; // Service for interacting with `Exchange` resources. service Exchanges { // Returns the `Exchange` with the specified resource key. - rpc GetExchange(GetExchangeRequest) returns (Exchange); + rpc GetExchange(GetExchangeRequest) returns (Exchange) { + option (google.api.method_signature) = "name"; + } } // Request message for `GetExchange` method. message GetExchangeRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Exchange"]; - - // Party name. Required. - oneof party { - string data_provider = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; - string model_provider = 3 [(google.api.resource_reference).type = - "halo.wfanet.org/ModelProvider"]; - } + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Exchange", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/measurement.proto b/src/main/proto/wfa/measurement/api/v2alpha/measurement.proto index e79e0d266..387339fdc 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/measurement.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/measurement.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/duration.proto"; import "wfa/measurement/api/v2alpha/crypto.proto"; @@ -25,69 +26,85 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "MeasurementProto"; +// A measurement from a set of `DataProvider`s requested by a +// `MeasurementConsumer`. message Measurement { option (google.api.resource) = { type: "halo.wfanet.org/Measurement" pattern: "measurementConsumers/{measurement_consumer}/measurements/{measurement}" + singular: "measurement" + plural: "measurements" }; // Resource name. string name = 1; // Resource name of the `Certificate` belonging to the parent - // `MeasurementConsumer`. Required. Immutable. - string measurement_consumer_certificate = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + // `MeasurementConsumer`. + string measurement_consumer_certificate = 2 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Serialized `MeasurementSpec` for requisitions, which can be verified using - // `measurement_consumer_certificate`. Required. Immutable. - SignedData measurement_spec = 3; - - // TODO(b/175707034): Consider adding a field to hold the private keys which - // is encrypted with some private/symmetric key belonging to the - // `MeasurementConsumer`. This way the `MeasurementConsumer` need not store - // the private keys for each `Measurement`. + // `measurement_consumer_certificate`. + SignedData measurement_spec = 3 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; + // Entry for `data_providers` map. message DataProviderEntry { - // Key of the map entry, which is a `DataProvider` resource name. Required. - string key = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Key of the map entry, which is a `DataProvider` resource name. + string key = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; + // Value of a map entry. message Value { // Resource name of the `Certificate` belonging to `data_provider`. - // Required. - string data_provider_certificate = 1 - [(google.api.resource_reference).type = - "halo.wfanet.org/Certificate"]; + string data_provider_certificate = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; // Pre-shared serialized `EncryptionPublicKey`, which can be verified - // using `data_provider_certificate`. Required. - SignedData data_provider_public_key = 2; + // using `data_provider_certificate`. + SignedData data_provider_public_key = 2 + [(google.api.field_behavior) = REQUIRED]; // Encrypted `SignedData` containing the serialized `RequisitionSpec` for // this entry, which can be verified using - // `measurement_consumer_certificate`. Required. + // `measurement_consumer_certificate`. // // The encryption uses `data_provider_public_key` as the recipient public // key. - bytes encrypted_requisition_spec = 3; + bytes encrypted_requisition_spec = 3 + [(google.api.field_behavior) = REQUIRED]; // SHA256 hash of the `nonce` from `encrypted_requisition_spec`, where the // nonce value has big-endian byte ordering. - bytes nonce_hash = 4; + bytes nonce_hash = 4 [(google.api.field_behavior) = REQUIRED]; } - // Value of the map entry. Required. - Value value = 2; + // Value of the map entry. + Value value = 2 [(google.api.field_behavior) = REQUIRED]; } - // Map of `DataProvider` name to parameters for that `DataProvider`. Required. - // Immutable. - repeated DataProviderEntry data_providers = 4; + // Map of `DataProvider` name to parameters for that `DataProvider`. + repeated DataProviderEntry data_providers = 4 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // The `ProtocolConfig` selected for this measurement according to the - // `measurement_spec`. Output-only. Immutable. - ProtocolConfig protocol_config = 5; + // `measurement_spec`. + ProtocolConfig protocol_config = 5 + [(google.api.field_behavior) = OUTPUT_ONLY]; + // State for a `Measurement`. enum State { + // Default value used if the state is omitted. STATE_UNSPECIFIED = 0; // Waiting for all linked `Requisition`s to be fulfilled. AWAITING_REQUISITION_FULFILLMENT = 1; @@ -100,16 +117,20 @@ message Measurement { // Cancelled by Measurement Consumer. Terminal state. CANCELLED = 5; } - State state = 6; + // State of this `Measurement`. + State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; // The result of a `Measurement`. message Result { + // A reach result. message Reach { // Number of unique users exposed. int64 value = 1; } + // The reach result. Reach reach = 1; + // A frequency result. message Frequency { // Map of frequency to reach ratio. For example, an entry // {key: 4 value: 0.333} means that 33.3% of users were exposed exactly 4 @@ -117,21 +138,27 @@ message Measurement { // means that 33.3% of users were exposed at least 4 times. map relative_frequency_distribution = 1; } + // The frequency result. Frequency frequency = 2; + // An impression result. message Impression { // Number of total impressions. int64 value = 1; } + // The impressio result. Impression impression = 3; + // A watch duration result. message WatchDuration { // Total duration. google.protobuf.Duration value = 1; } + // The watch duration result. WatchDuration watch_duration = 4; } + // Pair of `Result` to `Certificate`. message ResultPair { // Encrypted `SignedData` containing the serialized `Result` // which can be verified using `certificate`. @@ -146,15 +173,21 @@ message Measurement { [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; } - // List of `ResultPair`. Output-only. Only set if `state` is `SUCCEEDED`. - repeated ResultPair results = 8; + // Results of this `Measurement`. Only set if `state` is `SUCCEEDED`. + repeated ResultPair results = 8 [ + (google.api.field_behavior) = OUTPUT_ONLY, + (google.api.field_behavior) = UNORDERED_LIST + ]; // ID referencing the `Measurement` in an external system, provided by the - // Measurement Consumer. - string measurement_reference_id = 9; + // `MeasurementConsumer`. + string measurement_reference_id = 9 [(google.api.field_behavior) = IMMUTABLE]; + // Information about a failure. message Failure { + // Reason for a `Failure`. enum Reason { + // Default value used if the reason is omitted. REASON_UNSPECIFIED = 0; // An associated certificate was revoked. CERTIFICATE_REVOKED = 1; @@ -163,11 +196,13 @@ message Measurement { // ComputationParticipant state was set to FAILED. COMPUTATION_PARTICIPANT_FAILED = 3; } - Reason reason = 1; + // Reason for this `Failure`. + Reason reason = 1 [(google.api.field_behavior) = REQUIRED]; // Human-readable message. This should not contain any sensitive // information. string message = 2; } - // Set when the state is set to FAILED. Output-only. - Failure failure = 10; + // Information about the failure of this `Measurement`. Set when the `state` + // is set to `FAILED`. + Failure failure = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumer.proto b/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumer.proto index d7ba798e3..01649c1e4 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumer.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumer.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/crypto.proto"; @@ -28,33 +29,44 @@ message MeasurementConsumer { option (google.api.resource) = { type: "halo.wfanet.org/MeasurementConsumer" pattern: "measurementConsumers/{measurement_consumer}" + singular: "measurementConsumer" + plural: "measurementConsumers" }; // Resource name. string name = 1; // The X.509 certificate belonging to this `MeasurementConsumer` in DER format - // which can be used to verify `public_key`. Required. - bytes certificate_der = 2; + // which can be used to verify `public_key`. + bytes certificate_der = 2 [(google.api.field_behavior) = REQUIRED]; // Resource name of the `Certificate` belonging to this `MeasurementConsumer` - // which can be used to verify `public_key`. Output-only. + // which can be used to verify `public_key`. // // The `x509_der` field of this resource matches `certificate_der`. - string certificate = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + string certificate = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = OUTPUT_ONLY + ]; // Serialized `EncryptionPublicKey` for this `MeasurementConsumer`, which can - // be verified using `certificate`. Required. - SignedData public_key = 4; + // be verified using `certificate`. + SignedData public_key = 4 [(google.api.field_behavior) = REQUIRED]; // Display name of the `MeasurementConsumer`. string display_name = 5; - // Resource names of owner `Account`s. Output-only. - repeated string owners = 6 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; + // Resource names of owner `Account`s. + repeated string owners = 6 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = OUTPUT_ONLY, + (google.api.field_behavior) = UNORDERED_LIST + ]; - // Token to create a `MeasurementConsumer` resource. Required. Input-only. - string measurement_consumer_creation_token = 7; + // Token to create a `MeasurementConsumer` resource. + string measurement_consumer_creation_token = 7 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE, + (google.api.field_behavior) = INPUT_ONLY + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumers_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumers_service.proto index ca6881ca2..e3e4c27dc 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumers_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/measurement_consumers_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/measurement_consumer.proto"; @@ -27,11 +29,15 @@ option java_outer_classname = "MeasurementConsumersServiceProto"; service MeasurementConsumers { // Returns the `MeasurementConsumer` with the specified resource key. rpc GetMeasurementConsumer(GetMeasurementConsumerRequest) - returns (MeasurementConsumer) {} + returns (MeasurementConsumer) { + option (google.api.method_signature) = "name"; + } // Creates (registers) a `MeasurementConsumer`. rpc CreateMeasurementConsumer(CreateMeasurementConsumerRequest) - returns (MeasurementConsumer) {} + returns (MeasurementConsumer) { + option (google.api.method_signature) = "measurement_consumer"; + } // Adds an owner to the specified `MeasurementConsumer`. rpc AddMeasurementConsumerOwner(AddMeasurementConsumerOwnerRequest) @@ -45,37 +51,52 @@ service MeasurementConsumers { // Request message for `GetMeasurementConsumer` method. message GetMeasurementConsumerRequest { // Resource name. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateMeasurementConsumer` method. message CreateMeasurementConsumerRequest { - // The `MeasurementConsumer` to create. Required. The `name` field will be - // ignored, and the system will assign an ID. - MeasurementConsumer measurement_consumer = 1; + // The `MeasurementConsumer` to create. + // + // The `name` field will be ignored, and the system will assign an ID. + MeasurementConsumer measurement_consumer = 1 + [(google.api.field_behavior) = REQUIRED]; } // Request message for `AddMeasurementConsumerOwner` method. message AddMeasurementConsumerOwnerRequest { // Resource name. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED + ]; // Resource name of the `Account` to add as an owner of this - // `MeasurementConsumer`. Required. - string account = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; + // `MeasurementConsumer`. + string account = 2 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `RemoveMeasurementConsumerOwner` method. message RemoveMeasurementConsumerOwnerRequest { // Resource name. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + string name = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED + ]; // Resource name of the `Account` to remove as an owner of this - // `MeasurementConsumer`. Required. - string account = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/Account"]; + // `MeasurementConsumer`. + string account = 2 [ + (google.api.resource_reference).type = "halo.wfanet.org/Account", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/measurement_spec.proto b/src/main/proto/wfa/measurement/api/v2alpha/measurement_spec.proto index b8b7e1cae..7d41e4de3 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/measurement_spec.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/measurement_spec.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "wfa/measurement/api/v2alpha/differential_privacy.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -25,31 +26,35 @@ option java_outer_classname = "MeasurementSpecProto"; // Specification for a `Measurement`. Immutable. message MeasurementSpec { // Serialized `EncryptionPublicKey` for the `Measurement` that this - // `MeasurementSpec` is associated with. Required. + // `MeasurementSpec` is associated with. // // This is serialized so it can be easily compared with the same field in // `RequisitionSpec`. - bytes measurement_public_key = 1; + bytes measurement_public_key = 1 [(google.api.field_behavior) = REQUIRED]; // List of `nonce_hash` values from `data_providers` of the corresponding - // `Measurement`. Required. - repeated bytes nonce_hashes = 2; + // `Measurement`. + repeated bytes nonce_hashes = 2 [(google.api.field_behavior) = REQUIRED]; // Specifies a range of VIDs to be sampled. // start + width cannot be larger than 1 message VidSamplingInterval { + // Start of the sampling interval. float start = 1; + // Width of the sampling interval. float width = 2; } // Range of VIDs that will be included in this measurement VidSamplingInterval vid_sampling_interval = 3; + // Parameters for a reach-only measurement. message Reach { // Differential privacy parameters for reach. DifferentialPrivacyParams privacy_params = 1; } + // Parameters for a reach and frequency measurement. message ReachAndFrequency { // Differential privacy parameters for reach. DifferentialPrivacyParams reach_privacy_params = 1; @@ -61,14 +66,18 @@ message MeasurementSpec { int32 maximum_frequency_per_user = 3; } + // Parameters for an impression measurement. message Impression { + // Differential privacy parameters. DifferentialPrivacyParams privacy_params = 1; // Maximum frequency per user that will be included in this measurement. int32 maximum_frequency_per_user = 2; } + // Parameters for a duration measurement. message Duration { + // Differential privacy parameters. DifferentialPrivacyParams privacy_params = 1; // Maximum watch duration in seconds per user that will be included in this @@ -81,9 +90,13 @@ message MeasurementSpec { // Fields specific to the type of measurement. oneof measurement_type { + // Parameters for a reach and frequency measurement. ReachAndFrequency reach_and_frequency = 4; + // Parameters for an impression measurement. Impression impression = 5; + // Parameters for a duration measurement. Duration duration = 6; + // Parameters for a reach-only measurement. Reach reach = 7; } } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/measurements_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/measurements_service.proto index 9b1e8f17a..09d29211e 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/measurements_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/measurements_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/measurement.proto"; @@ -26,14 +28,20 @@ option java_outer_classname = "MeasurementsServiceProto"; // Service for interacting with `Measurement` resources. service Measurements { // Returns the `Measurement` with the specified resource key. - rpc GetMeasurement(GetMeasurementRequest) returns (Measurement) {} + rpc GetMeasurement(GetMeasurementRequest) returns (Measurement) { + option (google.api.method_signature) = "name"; + } // Creates (registers) a `Measurement`. - rpc CreateMeasurement(CreateMeasurementRequest) returns (Measurement) {} + rpc CreateMeasurement(CreateMeasurementRequest) returns (Measurement) { + option (google.api.method_signature) = "parent,measurement"; + } // Lists `Measurement`s for the parent `MeasurementConsumer`. rpc ListMeasurements(ListMeasurementsRequest) - returns (ListMeasurementsResponse) {} + returns (ListMeasurementsResponse) { + option (google.api.method_signature) = "parent"; + } // Transitions a `Measurement` to the `CANCELLED` state. This is a terminal // state for the `Measurement`. @@ -44,20 +52,25 @@ service Measurements { // Request message for `GetMeasurement` method. message GetMeasurementRequest { - // Resource name. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Measurement"]; + // Resource name. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Measurement", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateMeasurement` method. message CreateMeasurementRequest { - // Resource name of the parent `MeasurementConsumer`. Required. - string parent = 3 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + // Resource name of the parent `MeasurementConsumer`. + string parent = 3 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED + ]; - // The `Measurement` to create. Required. The `name` field will be ignored, - // and the system will assign an ID. - Measurement measurement = 1; + // The `Measurement` to create. The `name` field will be ignored, and the + // system will assign an ID. + Measurement measurement = 1 [(google.api.field_behavior) = REQUIRED]; // Unique identifier for this request. // @@ -68,9 +81,12 @@ message CreateMeasurementRequest { // Request message for `ListMeasurements` method. message ListMeasurementsRequest { - // Resource name of the parent `MeasurementConsumer`. Required. - string parent = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/MeasurementConsumer"]; + // Resource name of the parent `MeasurementConsumer`. + string parent = 1 [ + (google.api.resource_reference).type = + "halo.wfanet.org/MeasurementConsumer", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `Measurement`s to return. // The service may return fewer than this value. @@ -88,15 +104,25 @@ message ListMeasurementsRequest { // Filter criteria. Repeated fields are treated as logical ORs, and multiple // fields specified as logical ANDs. message Filter { + // Matches against the `state` field. + // + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) repeated Measurement.State states = 1; } + // Filter criteria. + // + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; } +// Response message for `ListMeasurements` method. message ListMeasurementsResponse { // List of `Measurement`s that has all of the tags in the // ListMeasurementsRequest - repeated Measurement measurement = 1; + repeated Measurement measurements = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. string next_page_token = 2; @@ -104,7 +130,9 @@ message ListMeasurementsResponse { // Request message for `CancelMeasurement` method. message CancelMeasurementRequest { - // Resource name of the `Measurement` to mark as `CANCELLED`. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Measurement"]; + // Resource name of the `Measurement` to mark as `CANCELLED`. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Measurement", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_line.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_line.proto index ea9f427b8..39d1f86bc 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_line.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_line.proto @@ -24,11 +24,16 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelLineProto"; +// Resource representing a series of models within a model suite. message ModelLine { option (google.api.resource) = { type: "halo.wfanet.org/ModelLine" pattern: "modelProviders/{model_provider}/modelSuites/{model_suite}/modelLines/{model_line}" + singular: "modelLine" + plural: "modelLines" }; + + // Resource name. string name = 1; // Human-readable display name for this 'ModelLine'. @@ -51,6 +56,7 @@ message ModelLine { // not specified, there is no end to the active time range. google.protobuf.Timestamp active_end_time = 5; + // Type of a `ModelLine`. enum Type { // The default value if 'Type' is omitted. Should not be used. TYPE_UNSPECIFIED = 0; @@ -65,8 +71,10 @@ message ModelLine { HOLDBACK = 3; } - // Defines the type of the `ModelLine`. EDPs must label events using all - // available `ModelLine`s independently of their type. + // Type of this `ModelLine`. + // + // `DataProvider`s must label events using all available `ModelLine`s + // independently of their type. Type type = 6 [ (google.api.field_behavior) = REQUIRED, (google.api.field_behavior) = IMMUTABLE diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_lines_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_lines_service.proto index de2cc5084..f152ff0b8 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_lines_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_lines_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/timestamp.proto"; @@ -25,19 +26,29 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelLinesServiceProto"; +// Service for interacting with `ModelLine` resources. service ModelLines { // Creates a new `ModelLine`. - rpc CreateModelLine(CreateModelLineRequest) returns (ModelLine); + rpc CreateModelLine(CreateModelLineRequest) returns (ModelLine) { + option (google.api.method_signature) = "parent,model_line"; + } // Lists `ModelLine`s for the parent `ModelSuite`. - rpc ListModelLines(ListModelLinesRequest) returns (ListModelLinesResponse); + rpc ListModelLines(ListModelLinesRequest) returns (ListModelLinesResponse) { + option (google.api.method_signature) = "parent"; + } // Sets the `holdback_model_line` for a `ModelLine`. + // (-- api-linter: core::0134::synonyms=disabled + // aip.dev/not-precedent: This is not a standard Update method. --) rpc SetModelLineHoldbackModelLine(SetModelLineHoldbackModelLineRequest) returns (ModelLine); - // Sets the active_end_time for a `ModelLine`. - rpc SetActiveEndTime(SetActiveEndTimeRequest) returns (ModelLine); + // Sets the `active_end_time` for a `ModelLine`. + // (-- api-linter: core::0134::synonyms=disabled + // aip.dev/not-precedent: This is not a standard Update method. --) + rpc SetModelLineActiveEndTime(SetModelLineActiveEndTimeRequest) + returns (ModelLine); } // Request message for `CreateModelLine` method. @@ -53,6 +64,7 @@ message CreateModelLineRequest { ModelLine model_line = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `ListModelLines` method. message ListModelLinesRequest { // Resource name of the parent `ModelSuite`. string parent = 1 [ @@ -73,22 +85,31 @@ message ListModelLinesRequest { // must match the call that provided the page token. string page_token = 3; - // Filter criteria. Repeated fields are treated as logical ORs. + // Filter criteria for a `ListModelLines` request. + // + // Repeated fields are treated as logical ORs, and multiple + // fields specified as logical ANDs. message Filter { - repeated ModelLine.Type type = 1; + // Matches against the `type` of the `ModelLine`. + repeated ModelLine.Type types = 1; } + // Filter criteria for this request. + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; } +// Response message for `ListModelLines` method. message ListModelLinesResponse { // List of `ModelLine`s. - repeated ModelLine model_line = 1; + repeated ModelLine model_lines = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. string next_page_token = 2; } +// Request message for `SetModelLineHoldbackModelLine` method. message SetModelLineHoldbackModelLineRequest { // Resource name. string name = 1 [ @@ -103,7 +124,8 @@ message SetModelLineHoldbackModelLineRequest { ]; } -message SetActiveEndTimeRequest { +// Request message for `SetModelLineActiveEndTime` method. +message SetModelLineActiveEndTimeRequest { // Resource name. string name = 1 [ (google.api.resource_reference).type = "halo.wfanet.org/ModelLine", diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_outage.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_outage.proto index 95bbc9661..ad7a1b195 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_outage.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_outage.proto @@ -25,11 +25,16 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelOutageProto"; +// Resource representing an outage of a model line. message ModelOutage { option (google.api.resource) = { type: "halo.wfanet.org/ModelOutage" pattern: "modelProviders/{model_provider}/modelSuites/{model_suite}/modelLines/{model_line}/modelOutages/{model_outage}" + singular: "modelOutage" + plural: "modelOutages" }; + + // Resource name. string name = 1; // TimeInterval in which the parent `ModelLine` cannot be used to generate @@ -41,6 +46,7 @@ message ModelOutage { (google.api.field_behavior) = IMMUTABLE ]; + // State of a `ModelOutage`, enum State { // The default value if state is omitted. Should never be used. STATE_UNSPECIFIED = 0; @@ -52,7 +58,7 @@ message ModelOutage { DELETED = 2; } - // `ModelOutage` state. + // State of this `ModelOutage`. State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; // When the 'ModelOutage' was created. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_outages_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_outages_service.proto index f35d5d10a..c7b7a18e6 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_outages_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_outages_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/model_outage.proto"; @@ -25,15 +26,20 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelOutagesServiceProto"; +// Service for interacting with `ModelOutage` resources. service ModelOutages { // Creates a new `ModelOutage`. A 'ModelOutage' can be created only for // 'ModelLine' with type equal to 'PROD'. Furthermore the // 'ModelLine'.'holdback_model_line' needs to be already specified. - rpc CreateModelOutage(CreateModelOutageRequest) returns (ModelOutage); + rpc CreateModelOutage(CreateModelOutageRequest) returns (ModelOutage) { + option (google.api.method_signature) = "parent,model_outage"; + } // Lists `ModelOutage`s. rpc ListModelOutages(ListModelOutagesRequest) - returns (ListModelOutagesResponse); + returns (ListModelOutagesResponse) { + option (google.api.method_signature) = "parent"; + } // Deletes an existing `ModelOutage`. `ModelOutage` will transition to a // DELETED state. This action is irreversible. Results in a `NOT_FOUND` error @@ -41,9 +47,12 @@ service ModelOutages { // deleted. // // This is a soft delete as defined by https://google.aip.dev/216. - rpc DeleteModelOutage(DeleteModelOutageRequest) returns (ModelOutage); + rpc DeleteModelOutage(DeleteModelOutageRequest) returns (ModelOutage) { + option (google.api.method_signature) = "name"; + } } +// Request message for `CreateModelOutage` method. message CreateModelOutageRequest { // Resource name of the parent `ModelLine`. string parent = 1 [ @@ -56,10 +65,11 @@ message CreateModelOutageRequest { ModelOutage model_outage = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `ListModelOutages` method. message ListModelOutagesRequest { // Resource name of the parent `ModelOutage`. string parent = 1 [ - (google.api.resource_reference).type = "halo.wfanet.org/ModelOutage", + (google.api.resource_reference).type = "halo.wfanet.org/ModelLine", (google.api.field_behavior) = REQUIRED ]; @@ -79,23 +89,28 @@ message ListModelOutagesRequest { // Whether to include ModelOutage in the DELETED state or not. bool show_deleted = 4; - // Filter criteria. Only 'ModelOutage's having 'outage_interval' overlapping - // 'time_interval' are returned. + // Filter criteria for a `ListModelOutages` request. message Filter { - TimeInterval time_interval = 1; + // Matches against the `outage_interval` of the `ModelOutage`. + TimeInterval outage_interval_overlapping = 1; } + // Filter criteria for this request. + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 5; } +// Response message for `ListModelOutages` method. message ListModelOutagesResponse { - // List of `ModelOutage`s. - repeated ModelOutage model_outage = 1; + // Resources. + repeated ModelOutage model_outages = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. string next_page_token = 2; } +// Request message for `DeleteModelOutage` method. message DeleteModelOutageRequest { // The name of `ModelOutage` to delete. // Format: diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_provider.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_provider.proto index 1c3f04860..8c334e4c5 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_provider.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_provider.proto @@ -27,6 +27,8 @@ message ModelProvider { option (google.api.resource) = { type: "halo.wfanet.org/ModelProvider" pattern: "modelProviders/{model_provider}" + singular: "modelProvider" + plural: "modelProviders" }; // Resource name. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_providers_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_providers_service.proto index 27589ad0a..f4ffb1499 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_providers_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_providers_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/model_provider.proto"; @@ -26,12 +28,16 @@ option java_outer_classname = "ModelProvidersServiceProto"; // Service for interacting with `ModelProvider` resources. service ModelProviders { // Returns the `ModelProvider` with the specified resource key. - rpc GetModelProvider(GetModelProviderRequest) returns (ModelProvider) {} + rpc GetModelProvider(GetModelProviderRequest) returns (ModelProvider) { + option (google.api.method_signature) = "name"; + } } // Request message for `GetModelProvider` method. message GetModelProviderRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/ModelProvider", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_release.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_release.proto index e62516dd5..4ded2cee6 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_release.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_release.proto @@ -24,11 +24,16 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelReleaseProto"; +// Resource representing a release of a model. message ModelRelease { option (google.api.resource) = { type: "halo.wfanet.org/ModelRelease" pattern: "modelProviders/{model_provider}/modelSuites/{model_suite}/modelReleases/{model_release}" + singular: "modelRelease" + plural: "modelReleases" }; + + // Resource name. string name = 1; // When the 'ModelRelease' was created. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_releases_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_releases_service.proto index ab7addae7..1ab95a1fd 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_releases_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_releases_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/model_release.proto"; @@ -24,18 +25,26 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelReleasesServiceProto"; +// Service for interacting with `ModelRelease` resources. service ModelReleases { // Creates a new `ModelRelease`. - rpc CreateModelRelease(CreateModelReleaseRequest) returns (ModelRelease); + rpc CreateModelRelease(CreateModelReleaseRequest) returns (ModelRelease) { + option (google.api.method_signature) = "parent,model_release"; + } // Returns a single `ModelRelease`. - rpc GetModelRelease(GetModelReleaseRequest) returns (ModelRelease); + rpc GetModelRelease(GetModelReleaseRequest) returns (ModelRelease) { + option (google.api.method_signature) = "name"; + } // Lists `ModelRelease`s. rpc ListModelReleases(ListModelReleasesRequest) - returns (ListModelReleasesResponse); + returns (ListModelReleasesResponse) { + option (google.api.method_signature) = "parent"; + } } +// Request message for `CreateModelRelease` method. message CreateModelReleaseRequest { // Resource name of the parent `ModelSuite`. string parent = 1 [ @@ -48,6 +57,7 @@ message CreateModelReleaseRequest { ModelRelease model_release = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `GetModelRelease` method. message GetModelReleaseRequest { // Resource name. string name = 1 [ @@ -56,6 +66,7 @@ message GetModelReleaseRequest { ]; } +// Request message for `ListModelReleases` method. message ListModelReleasesRequest { // Resource name of the parent `ModelSuite`. string parent = 1 [ @@ -78,9 +89,10 @@ message ListModelReleasesRequest { string page_token = 3; } +// Response message for `ListModelReleases` method. message ListModelReleasesResponse { - // List of `ModelRelease`s. - repeated ModelRelease model_release = 1; + // Resources. + repeated ModelRelease model_releases = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_rollout.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_rollout.proto index 6bab5bfcb..b3add781e 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_rollout.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_rollout.proto @@ -25,11 +25,16 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelRolloutProto"; +// Resource representing the rollout of a `ModelLine`. message ModelRollout { option (google.api.resource) = { type: "halo.wfanet.org/ModelRollout" pattern: "modelProviders/{model_provider}/modelSuites/{model_suite}/modelLines/{model_line}/modelRollouts/{model_rollout}" + singular: "modelRollout" + plural: "modelRollouts" }; + + // Resource name. string name = 1; // Time interval over which the rollout must be deployed. 'start_time' must be diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_rollouts_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_rollouts_service.proto index e4b0a3b16..40fcfa199 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_rollouts_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_rollouts_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/empty.proto"; @@ -27,15 +28,20 @@ option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelRolloutsServiceProto"; +// Service for interacting with `ModelRollout` resources. service ModelRollouts { // Creates a new `ModelRollout`. 'rollout_start_time' must be sufficiently in // the future to allow for EDPs to sync with the Kingdom. - rpc CreateModelRollout(CreateModelRolloutRequest) returns (ModelRollout); + rpc CreateModelRollout(CreateModelRolloutRequest) returns (ModelRollout) { + option (google.api.method_signature) = "parent,model_rollout"; + } // Lists `ModelRollout`s for a given ModelLine. It returns an sorted list by // rollout_start_time ASC. rpc ListModelRollouts(ListModelRolloutsRequest) - returns (ListModelRolloutsResponse); + returns (ListModelRolloutsResponse) { + option (google.api.method_signature) = "parent"; + } // Sets the `rollout_freeze_time` of a `ModelRollout`. rpc ScheduleModelRolloutFreeze(ScheduleModelRolloutFreezeRequest) @@ -44,9 +50,12 @@ service ModelRollouts { // Deletes a `ModelRollout`. Results in FAILED_PRECONDITION if the request is // received after 'ModelRollout.rollout_period.start_time`. rpc DeleteModelRollout(DeleteModelRolloutRequest) - returns (google.protobuf.Empty) {} + returns (google.protobuf.Empty) { + option (google.api.method_signature) = "name"; + } } +// Request message for `CreateModelRollout` method. message CreateModelRolloutRequest { // Resource name of the parent `ModelLine`. string parent = 1 [ @@ -59,6 +68,7 @@ message CreateModelRolloutRequest { ModelRollout model_rollout = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `ListModelRollouts` method. message ListModelRolloutsRequest { // Resource name of the parent `ModelLine`. string parent = 1 [ @@ -80,24 +90,29 @@ message ListModelRolloutsRequest { // token. string page_token = 3; - // Filter criteria. + // Filter criteria for a `ListModelRolloutsRequest`. message Filter { // Only 'ModelRollout's having 'rollout_period' overlapping // 'rollout_period_overlapping' are returned. TimeInterval rollout_period_overlapping = 1; } + // Filter criteria for this request. + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; } +// Response message for `ListModelRollouts` method. message ListModelRolloutsResponse { - // List of `ModelRollout`s. - repeated ModelRollout model_rollout = 1; + // Resources. + repeated ModelRollout model_rollouts = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. string next_page_token = 2; } +// Request message for `ScheduleModelRolloutFreeze` method. message ScheduleModelRolloutFreezeRequest { // Resource name. string name = 1 [ @@ -110,6 +125,7 @@ message ScheduleModelRolloutFreezeRequest { google.protobuf.Timestamp rollout_freeze_time = 2; } +// Request message for `DeleteModelRollout` method. message DeleteModelRolloutRequest { // The name of `ModelRollout` to delete. // Format: diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_shard.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_shard.proto index d89ef009d..2b7e39be9 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_shard.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_shard.proto @@ -18,28 +18,32 @@ package wfa.measurement.api.v2alpha; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; -import "google/protobuf/any.proto"; import "google/protobuf/timestamp.proto"; -import "wfa/measurement/api/v2alpha/time_interval.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelShardProto"; +// Resource representing a shard of a model for a `DataProvider`. message ModelShard { option (google.api.resource) = { type: "halo.wfanet.org/ModelShard" pattern: "dataProviders/{data_provider}/modelShards/{model_shard}" + singular: "modelShard" + plural: "modelShards" }; + + // Resource name. string name = 1; - // The ModelRelease resource this ModelShard references to. + // Resource name of the `ModelRelease` that this is a shard of. string model_release = 2 [ (google.api.resource_reference).type = "halo.wfanet.org/ModelRelease", (google.api.field_behavior) = REQUIRED, (google.api.field_behavior) = IMMUTABLE ]; + // A reference to a model blob. message ModelBlob { // The path the model blob can be downloaded from. // See CompileNode proto message: @@ -50,7 +54,11 @@ message ModelShard { ]; } - ModelBlob model_blob = 3; + // The blob for this model shard. + ModelBlob model_blob = 3 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // When the 'ModelShard' was created. google.protobuf.Timestamp create_time = 5 diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_shards_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_shards_service.proto index 447d79800..751f4b14d 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_shards_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_shards_service.proto @@ -16,27 +16,37 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/protobuf/empty.proto"; import "wfa/measurement/api/v2alpha/model_shard.proto"; -import "wfa/measurement/api/v2alpha/time_interval.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "ModelShardsServiceProto"; +// Service for interacting with `ModelShard` resources. service ModelShards { // Creates a new `ModelShard`. - rpc CreateModelShard(CreateModelShardRequest) returns (ModelShard); + rpc CreateModelShard(CreateModelShardRequest) returns (ModelShard) { + option (google.api.method_signature) = "parent,model_shard"; + } // Lists `ModelShard`s. - rpc ListModelShards(ListModelShardsRequest) returns (ListModelShardsResponse); + rpc ListModelShards(ListModelShardsRequest) + returns (ListModelShardsResponse) { + option (google.api.method_signature) = "parent"; + } // Deletes an existing `ModelShard`. - rpc DeleteModelShard(DeleteModelShardRequest) returns (google.protobuf.Empty); + rpc DeleteModelShard(DeleteModelShardRequest) + returns (google.protobuf.Empty) { + option (google.api.method_signature) = "name"; + } } +// Request message for `CreateModelShard` method. message CreateModelShardRequest { // Resource name of the parent `DataProvider`. string parent = 1 [ @@ -49,6 +59,7 @@ message CreateModelShardRequest { ModelShard model_shard = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `ListModelShards` method. message ListModelShardsRequest { // Resource name of the parent `DataProvider`. string parent = 1 [ @@ -70,15 +81,17 @@ message ListModelShardsRequest { string page_token = 3; } +// Response message for `ListModelShards` method. message ListModelShardsResponse { - // List of `ModelShard`s. - repeated ModelShard model_shard = 1; + // Resources. + repeated ModelShard model_shards = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. string next_page_token = 2; } +// Request message for `DeleteModelShard` method. message DeleteModelShardRequest { // The name of `ModelShard` to delete. // Format: dataProviders/{data_provider}/modelShards/{model_shard} diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_suite.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_suite.proto index efb98d40e..f488149c4 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_suite.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_suite.proto @@ -29,7 +29,11 @@ message ModelSuite { option (google.api.resource) = { type: "halo.wfanet.org/ModelSuite" pattern: "modelProviders/{model_provider}/modelSuites/{model_suite}" + singular: "modelSuite" + plural: "modelSuites" }; + + // Resource name. string name = 1; // Human-readable nickname for this ModelSuite. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/model_suites_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/model_suites_service.proto index 9feb5ab06..81d6ce6d1 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/model_suites_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/model_suites_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/model_suite.proto"; @@ -27,15 +28,23 @@ option java_outer_classname = "ModelSuitesServiceProto"; // Service for interacting with `ModelSuite` resources. service ModelSuites { // Creates a new `ModelSuite` - rpc CreateModelSuite(CreateModelSuiteRequest) returns (ModelSuite); + rpc CreateModelSuite(CreateModelSuiteRequest) returns (ModelSuite) { + option (google.api.method_signature) = "parent,model_suite"; + } // Returns the `ModelSuite` with the specified resource key. - rpc GetModelSuite(GetModelSuiteRequest) returns (ModelSuite); + rpc GetModelSuite(GetModelSuiteRequest) returns (ModelSuite) { + option (google.api.method_signature) = "name"; + } // Lists `ModelSuite`s. - rpc ListModelSuites(ListModelSuitesRequest) returns (ListModelSuitesResponse); + rpc ListModelSuites(ListModelSuitesRequest) + returns (ListModelSuitesResponse) { + option (google.api.method_signature) = "parent"; + } } +// Request message for `CreateModelSuite` method. message CreateModelSuiteRequest { // Resource name of the parent `ModelProvider`. string parent = 1 [ @@ -48,18 +57,23 @@ message CreateModelSuiteRequest { ModelSuite model_suite = 2 [(google.api.field_behavior) = REQUIRED]; } +// Request message for `GetModelSuite` method. message GetModelSuiteRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/ModelSuite"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/ModelSuite", + (google.api.field_behavior) = REQUIRED + ]; } +// Request message for `ListModelSuites` method. message ListModelSuitesRequest { // Resource name of the parent `ModelProvider`. string parent = 1 [ (google.api.resource_reference).type = "halo.wfanet.org/ModelProvider", (google.api.field_behavior) = REQUIRED ]; + // The maximum number of `ModelSuite`s to return. // The service may return fewer than this value. // If unspecified, at most 50 `ModelSuite`s will be returned. @@ -75,9 +89,10 @@ message ListModelSuitesRequest { string page_token = 3; } +// Response message for `ListModelSuites` method. message ListModelSuitesResponse { - // List of `ModelSuite`s. - repeated ModelSuite model_suite = 1; + // Resources. + repeated ModelSuite model_suites = 1; // A token, which can be sent as `page_token` to retrieve the next page. // If this field is omitted, there are no subsequent pages. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/protocol_config.proto b/src/main/proto/wfa/measurement/api/v2alpha/protocol_config.proto index fdd8305ab..f97958e69 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/protocol_config.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/protocol_config.proto @@ -16,7 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; -import "google/api/resource.proto"; +import "google/api/field_behavior.proto"; import "wfa/measurement/api/v2alpha/differential_privacy.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; @@ -24,6 +24,9 @@ option java_multiple_files = true; option java_outer_classname = "ProtocolConfigProto"; // Configuration for computation protocols. +// +// (-- api-linter: core::0123::resource-annotation=disabled +// aip.dev/not-precedent: This is not a resource message. --) message ProtocolConfig { // Resource name. // @@ -35,38 +38,50 @@ message ProtocolConfig { // The values should correspond to the fields in the `measurement_type` Oneof // in `MeasurementSpec`. enum MeasurementType { + // Default value used if the type is omitted. MEASUREMENT_TYPE_UNSPECIFIED = 0; + // Reach and frequency. REACH_AND_FREQUENCY = 1; + // Number of impressions. IMPRESSION = 2; + // Watch duration. DURATION = 3; + // Reach only (no frequency). REACH = 4; } - // The type of measurement that this protocol computes. Required. Immutable. - MeasurementType measurement_type = 2; + // The type of measurement that this protocol computes. + MeasurementType measurement_type = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // The mechanism used to generate noise in computations. enum NoiseMechanism { + // Default value used if the mechanism is omitted. NOISE_MECHANISM_UNSPECIFIED = 0; + // Geometric. GEOMETRIC = 1; + // Discrete Gaussian. DISCRETE_GAUSSIAN = 2; } // Configuration for the Liquid Legions v2 R/F protocol. message LiquidLegionsV2 { - // Parameters for sketch. Required. Immutable. - LiquidLegionsSketchParams sketch_params = 1; + // Parameters for sketch. + LiquidLegionsSketchParams sketch_params = 1 + [(google.api.field_behavior) = REQUIRED]; // Differential privacy parameters for data provider noise registers. - // Required. Immutable. // // Each of these registers contains a well-known constant register ID, and // arbitrary key and count values. - DifferentialPrivacyParams data_provider_noise = 2; + DifferentialPrivacyParams data_provider_noise = 2 + [(google.api.field_behavior) = REQUIRED]; // ID of the OpenSSL built-in elliptic curve. For example, 415 for the - // prime256v1 curve. Required. Immutable. - int32 elliptic_curve_id = 3; + // prime256v1 curve. + int32 elliptic_curve_id = 3 [(google.api.field_behavior) = REQUIRED]; // The maximum frequency to reveal in the histogram. int32 maximum_frequency = 4; @@ -75,22 +90,23 @@ message ProtocolConfig { NoiseMechanism noise_mechanism = 5; } - // Protocol for direct measurement. + // Configuration for the Direct protocol. message Direct {} + // Configuration for a specific protocol. message Protocol { // Configuration for the specific protocol. oneof protocol { - // Liquid Legions v2 config. + // Liquid Legions v2 protocol. // - // May only be set when the measurement type is REACH_AND_FREQUENCY. - // Requisition can be fulfilled by calling + // May only be set when the measurement type is REACH_AND_FREQUENCY or + // REACH. `Requisition`s using this protocol can be fulfilled by calling // RequisitionFulfillment/FulfillRequisition with an encrypted sketch. LiquidLegionsV2 liquid_legions_v2 = 1; // Direct protocol. // - // The Requisition can be fulfilled by calling + // `Requisition`s using this protocol can be fulfilled by calling // Requisitions/FulfillDirectRequisition. Direct direct = 2; } @@ -106,18 +122,21 @@ message ProtocolConfig { LiquidLegionsV2 liquid_legions_v2 = 3 [deprecated = true]; } - // List of protocols the EDP may use. - repeated Protocol protocols = 4; + // Set of protocols that may be used for this `Measurement`. + repeated Protocol protocols = 4 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; } // Parameters for a Liquid Legions sketch. message LiquidLegionsSketchParams { - // The decay rate of the Liquid Legions sketch. Required. - double decay_rate = 1; + // The decay rate of the Liquid Legions sketch. + double decay_rate = 1 [(google.api.field_behavior) = REQUIRED]; - // The maximum size of the Liquid Legions sketch. Required. - int64 max_size = 2; + // The maximum size of the Liquid Legions sketch. + int64 max_size = 2 [(google.api.field_behavior) = REQUIRED]; - // The size of the distribution of the sampling indicator value. Required. - int64 sampling_indicator_size = 3; + // The size of the distribution of the sampling indicator value. + int64 sampling_indicator_size = 3 [(google.api.field_behavior) = REQUIRED]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/public_key.proto b/src/main/proto/wfa/measurement/api/v2alpha/public_key.proto index 131504a06..36e13bcfd 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/public_key.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/public_key.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/crypto.proto"; @@ -29,19 +30,22 @@ message PublicKey { type: "halo.wfanet.org/PublicKey" pattern: "dataProviders/{data_provider}/publicKey" pattern: "measurementConsumers/{measurement_consumer}/publicKey" + singular: "publicKey" + plural: "publicKeys" }; // Resource name. string name = 1; // Serialized `EncryptionPublicKey` for the parent resource, which can be - // verified using `certificate`. Required. - SignedData public_key = 2; + // verified using `certificate`. + SignedData public_key = 2 [(google.api.field_behavior) = REQUIRED]; // Resource name of the `Certificate` that can be used to verify `public_key`. - // Required. // // This must have the same parent as the `PublicKey`. - string certificate = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + string certificate = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/public_keys_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/public_keys_service.proto index 9e3a69b42..6c04f908c 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/public_keys_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/public_keys_service.proto @@ -16,19 +16,30 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "wfa/measurement/api/v2alpha/public_key.proto"; option java_package = "org.wfanet.measurement.api.v2alpha"; option java_multiple_files = true; option java_outer_classname = "PublicKeysServiceProto"; +// Service for interacting with `PublicKey` resources. service PublicKeys { // Updates the `PublicKey` for the specified parent. - rpc UpdatePublicKey(UpdatePublicKeyRequest) returns (PublicKey) {} + // + // (-- api-linter: core::0134::method-signature=disabled + // aip.dev/not-precedent: Partial update not supported. --) + rpc UpdatePublicKey(UpdatePublicKeyRequest) returns (PublicKey) { + option (google.api.method_signature) = "public_key"; + } } // Request message for `UpdatePublicKey` method. +// +// (-- api-linter: core::0134::request-mask-required=disabled +// aip.dev/not-precedent: Partial update not supported. --) message UpdatePublicKeyRequest { - // Resource to update. Required. - PublicKey public_key = 1; + // Resource to update. + PublicKey public_key = 1 [(google.api.field_behavior) = REQUIRED]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchange.proto b/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchange.proto index 3be89d80d..552d331df 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchange.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchange.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/type/date.proto"; import "wfa/measurement/api/v2alpha/exchange_workflow.proto"; @@ -32,30 +33,44 @@ message RecurringExchange { type: "halo.wfanet.org/RecurringExchange" pattern: "recurringExchanges/{recurring_exchange}" pattern: "dataProviders/{data_provider}/recurringExchanges/{recurring_exchange}" - pattern: "modelProviders/{data_provider}/recurringExchanges/{recurring_exchange}" + pattern: "modelProviders/{model_provider}/recurringExchanges/{recurring_exchange}" + singular: "recurringExchange" + plural: "recurringExchanges" }; // Resource name. string name = 1; - // The ExchangeWorkflow for this recurring exchange. Immutable. - ExchangeWorkflow exchange_workflow = 2; + // The ExchangeWorkflow for this recurring exchange. + ExchangeWorkflow exchange_workflow = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // The DataProvider party. - string event_data_provider = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + string event_data_provider = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // The ModelProvider party. - string model_provider = 4 - [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; + string model_provider = 4 [ + (google.api.resource_reference).type = "halo.wfanet.org/ModelProvider", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; - // Whether this exchange is still enabled. - State state = 5; + // State of this `RecurringExchange`. + State state = 5 [(google.api.field_behavior) = OUTPUT_ONLY]; // The date of the next Exchange. - google.type.Date next_exchange_date = 6; + google.type.Date next_exchange_date = 6 + [(google.api.field_behavior) = REQUIRED]; + // State of a `RecurringExchange`. enum State { + // Default value used if the state is omitted. STATE_UNSPECIFIED = 0; // New Exchanges should be started according to the schedule. diff --git a/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto b/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto index e1da63d9a..df94e2520 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/crypto.proto"; import "wfa/measurement/api/v2alpha/measurement.proto"; @@ -35,69 +36,101 @@ message Requisition { option (google.api.resource) = { type: "halo.wfanet.org/Requisition" pattern: "dataProviders/{data_provider}/requisitions/{requisition}" + singular: "requisition" + plural: "requisitions" }; // Resource name. string name = 1; // Resource name of `Measurement` that this `Requisition` is associated with. - // Required. Immutable. - string measurement = 2 - [(google.api.resource_reference).type = "halo.wfanet.org/Measurement"]; + string measurement = 2 [ + (google.api.resource_reference).type = "halo.wfanet.org/Measurement", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Denormalized dereferenced `measurement_consumer_certificate` field from - // `measurement`. Required. Immutable. - string measurement_consumer_certificate = 3 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; - - // Denormalized `measurement_spec` field from `measurement`. Required. - // Immutable. - SignedData measurement_spec = 4; - - // Denormalized `protocol_config` field from `measurement`. Immutable. - ProtocolConfig protocol_config = 5; + // `measurement. + string measurement_consumer_certificate = 3 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; + + // Denormalized `measurement_spec` field from `measurement`. + SignedData measurement_spec = 4 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; + + // Denormalized `protocol_config` field from `measurement`. + ProtocolConfig protocol_config = 5 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Denormalized `data_provider_certificate` field from the corresponding - // `DataProviderEntry` in `measurement`. Required. Immutable. - string data_provider_certificate = 6 - [(google.api.resource_reference).type = "halo.wfanet.org/Certificate"]; + // `DataProviderEntry` in `measurement`. + string data_provider_certificate = 6 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Denormalized `data_provider_public_key` field from the corresponding - // `DataProviderEntry` in `measurement`. Required. Immutable. - SignedData data_provider_public_key = 7; + // `DataProviderEntry` in `measurement`. + SignedData data_provider_public_key = 7 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Denormalized `encrypted_requisition_spec` field from the corresponding - // `DataProviderEntry` in `measurement`. Required. Immutable. - bytes encrypted_requisition_spec = 8; + // `DataProviderEntry` in `measurement`. + bytes encrypted_requisition_spec = 8 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; + // Entry in the `duchies` map. message DuchyEntry { - // Key of the map entry, which is a `Duchy` resource name. Required. - string key = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Duchy"]; + // Key of the map entry, which is a `Duchy` resource name. + string key = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Duchy", + (google.api.field_behavior) = REQUIRED + ]; + // Information for the Liquid Legions v2 protocol. message LiquidLegionsV2 { // The `ElGamalPublicKey` generated by the `Duchy` for this `Requisition`. - // Required. - SignedData el_gamal_public_key = 1; + SignedData el_gamal_public_key = 1 + [(google.api.field_behavior) = REQUIRED]; } + // Value of a map entry. message Value { - // Resource name of the `Certificate` belonging to the `Duchy`. Required. + // Resource name of the `Certificate` belonging to the `Duchy`. // // This certificate can be used to verify signatures in `protocol`. - string duchy_certificate = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/Certificate"]; + string duchy_certificate = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Certificate", + (google.api.field_behavior) = REQUIRED + ]; // Protocol-specific information for the `Duchy`. Required. oneof protocol { + // Information for the Liquid Legions v2 protocol. LiquidLegionsV2 liquid_legions_v2 = 2; } } - // Value of the map entry. Required. - Value value = 2; + // Value of the map entry. + Value value = 2 [(google.api.field_behavior) = REQUIRED]; } - // Map of `Duchy` name to parameters for that `Duchy`. Required. Immutable. - repeated DuchyEntry duchies = 9; + // Map of `Duchy` name to parameters for that `Duchy`. + repeated DuchyEntry duchies = 9 [ + (google.api.field_behavior) = UNORDERED_LIST, + (google.api.field_behavior) = IMMUTABLE + ]; // State of a `Requisition`. enum State { @@ -113,13 +146,17 @@ message Requisition { REFUSED = 3; } // The state of this `Requisition`. - State state = 10; + State state = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; // The `nonce` value from `encrypted_requisition_spec`. Output-only. // // Set when `state` is `FULFILLED`. - fixed64 nonce = 11; + // + // (-- api-linter: core::0141::forbidden-types=disabled + // aip.dev/not-precedent: This is a random 64-bit value. --) + fixed64 nonce = 11 [(google.api.field_behavior) = OUTPUT_ONLY]; + // Refusal of a `Requisition`. message Refusal { // Justification for refusing to fulfill a `Requisition`. // @@ -145,7 +182,7 @@ message Requisition { // For example, `encrypted_requisition_spec` includes an invalid // `TimeInterval` (with `end_time` before `start_time`) or some // configuration that the `DataProvider` does not support. - SPECIFICATION_INVALID = 2; + SPEC_INVALID = 2; // There is insufficient remaining privacy budget to fulfill the // `Requisition`. @@ -164,8 +201,8 @@ message Requisition { // apply. DECLINED = 5; } - // Justification for refusing to fulfill this `Requisition`. Required. - Justification justification = 1; + // Justification for refusing to fulfill this `Requisition`. + Justification justification = 1 [(google.api.field_behavior) = REQUIRED]; // Human-readable string adding more context to the provided // `Justification`. This should NOT include sensitive information. @@ -177,6 +214,7 @@ message Requisition { // set when `state` is `REFUSED`. Refusal refusal = 12; - // Denormalized `state` field from `measurement`. Output-only. - Measurement.State measurement_state = 13; + // Denormalized `state` field from `measurement`. + Measurement.State measurement_state = 13 + [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/requisition_fulfillment_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/requisition_fulfillment_service.proto index 5f954cad7..3b02cb830 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/requisition_fulfillment_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/requisition_fulfillment_service.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/requisition.proto"; @@ -33,26 +34,32 @@ service RequisitionFulfillment { // Request message for `FulfillRequisition` method. message FulfillRequisitionRequest { // The header message for this streaming request. + // (-- api-linter: core::0123::resource-annotation=disabled + // aip.dev/not-precedent: This is not a resource message. --) message Header { - // Resource name of the `Requisition`. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Requisition"]; + // Resource name of the `Requisition`. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Requisition", + (google.api.field_behavior) = REQUIRED + ]; - // The fingerprint of the `Requisition`. Required. + // The fingerprint of the `Requisition`. // // This is defined as the SHA256 hash of the concatenation of: // 1. The `data` in `measurement_spec` from the `Requisition`. // 2. The SHA256 hash of `encrypted_requisition_spec` from the // `Requisition`. - bytes requisition_fingerprint = 2; + bytes requisition_fingerprint = 2 [(google.api.field_behavior) = REQUIRED]; - // The `nonce` value from the `encrypted_requisition_spec`. Required. - fixed64 nonce = 3; + // The `nonce` value from the `encrypted_requisition_spec`. + // (-- api-linter: core::0141::forbidden-types=disabled + // aip.dev/not-precedent: This is a random 64-bit value. --) + fixed64 nonce = 3 [(google.api.field_behavior) = REQUIRED]; } // The chunk message for this streaming request. message BodyChunk { - // The portion of the data for this `BodyChunk`. Required. + // The portion of the data for this `BodyChunk`. // // The format of the data depends on the corresponding `MeasurementSpec`. If // the `Requisition` is for an encrypted sketch, this is the register @@ -64,7 +71,7 @@ message FulfillRequisitionRequest { // The optimal size of this field is one that would result in the // `FulfillRequisitionRequest` message being between 16KiB and 64KiB. // See https://github.com/grpc/grpc.github.io/issues/371 - bytes data = 1; + bytes data = 1 [(google.api.field_behavior) = REQUIRED]; } // Request message payload. Exactly one of these must be specified. @@ -82,5 +89,5 @@ message FulfillRequisitionRequest { // Response message for `FulfillRequisition` method. message FulfillRequisitionResponse { // Resulting state of the `Requisition`. - Requisition.State state = 1; + Requisition.State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/requisition_spec.proto b/src/main/proto/wfa/measurement/api/v2alpha/requisition_spec.proto index 08283ea6b..f397b09ad 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/requisition_spec.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/requisition_spec.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/time_interval.proto"; @@ -32,34 +33,51 @@ message RequisitionSpec { // each event template. string expression = 1; } + // Entry for `event_groups` map. message EventGroupEntry { - // Key of the map entry, which is an `EventGroup` resource name. Required. - string key = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/EventGroup"]; + // Key of the map entry, which is an `EventGroup` resource name. + string key = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/EventGroup", + (google.api.field_behavior) = REQUIRED + ]; + // Value of an `EventGroupEntry`. message Value { - // Time interval over which the event data should be collected. Required. - TimeInterval collection_interval = 1; + // Time interval over which the event data should be collected. + TimeInterval collection_interval = 1 + [(google.api.field_behavior) = REQUIRED]; - // Optional filter to apply to events. + // Filter to apply to events. If not specified then all events will be + // matched. EventFilter filter = 2; } - // Value of the map entry. Required. - Value value = 2; + // Value of this `EventGroupEntry`. + Value value = 2 [(google.api.field_behavior) = REQUIRED]; } - // Map of `EventGroup` name to parameters for that `EventGroup`. Required. + // Map of `EventGroup` name to parameters for that `EventGroup`. // // All of the `EventGroup`s must belong to the same parent `DataProvider` // as this `Requisition`. - repeated EventGroupEntry event_groups = 1; + repeated EventGroupEntry event_groups = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; // Serialized `EncryptionPublicKey` for the `Measurement` that this - // `RequisitionSpec` is associated with. Required. + // `RequisitionSpec` is associated with. // // This is serialized so it can be easily compared with the same field in // `MeasurementSpec`. - bytes measurement_public_key = 2; + bytes measurement_public_key = 2 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; - // Non-zero cryptographic nonce for this `RequisitionSpec`. Required. - fixed64 nonce = 3; + // Non-zero cryptographic nonce for this `RequisitionSpec`. + // (-- api-linter: core::0141::forbidden-types=disabled + // aip.dev/not-precedent: This is a random 64-bit value. --) + fixed64 nonce = 3 [ + (google.api.field_behavior) = REQUIRED, + (google.api.field_behavior) = IMMUTABLE + ]; } diff --git a/src/main/proto/wfa/measurement/api/v2alpha/requisitions_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/requisitions_service.proto index 9b4945414..659a09651 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/requisitions_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/requisitions_service.proto @@ -16,6 +16,8 @@ syntax = "proto3"; package wfa.measurement.api.v2alpha; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "wfa/measurement/api/v2alpha/measurement.proto"; import "wfa/measurement/api/v2alpha/requisition.proto"; @@ -28,7 +30,9 @@ option java_outer_classname = "RequisitionsServiceProto"; service Requisitions { // Returns the `Requisition`s for the specified `EventGroup`. rpc ListRequisitions(ListRequisitionsRequest) - returns (ListRequisitionsResponse); + returns (ListRequisitionsResponse) { + option (google.api.method_signature) = "parent"; + } // Transitions a `Requisition` to the `REFUSED` state. // @@ -46,17 +50,18 @@ service Requisitions { // Request message for `ListRequisitions` method. message ListRequisitionsRequest { - // Resource key of the parent `DataProvider`. Required. The wildcard ID (`-`) - // may be used in place of the `DataProvider` ID to list across all - // `DataProvider`s, but in this case `measurement` must be specified in - // `filter`. + // Resource key of the parent `DataProvider`. The wildcard ID (`-`) may be + // used in place of the `DataProvider` ID to list across all `DataProvider`s, + // but in this case `measurement` must be specified in `filter`. // // Results in a `PERMISSION_DENIED` error if any key segment does not match // for the authenticated user. For example, attempting to list // `Requisition`s for other `DataProvider`s or for `Measurements`s // belonging to other `MeasurementConsumer`s. - string parent = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/DataProvider", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `Requisition`s to return. The service may return // fewer than this value. If unspecified, at most 50 `Requisition`s will be @@ -70,13 +75,26 @@ message ListRequisitionsRequest { // Filter criteria. Repeated fields are treated as logical ORs, and multiple // fields specified as logical ANDs. message Filter { + // Matches against the `state` field. + // + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) repeated Requisition.State states = 1; + // Matches against the `measurement` field. string measurement = 2 [(google.api.resource_reference).type = "halo.wfanet.org/Measurement"]; + // Matches against the `measurement_state` field. + // + // (-- api-linter: core::0216::state-field-output-only=disabled + // api-linter: core::0203::output-only=disabled + // aip.dev/not-precedent: This is not a resource state field. --) repeated Measurement.State measurement_states = 3; } // Result filter. If a page token is specified, then this will be ignored and // the filter for the first page will be applied. + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 4; } @@ -92,33 +110,40 @@ message ListRequisitionsResponse { // Request message for `RefuseRequisition` method. message RefuseRequisitionRequest { - // Resource name of the `Requisition` to mark as `UNFILLABLE`. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Requisition"]; - - // Details about the refusal. Required. - Requisition.Refusal refusal = 2; + // Resource name of the `Requisition` to mark as `UNFILLABLE`. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Requisition", + (google.api.field_behavior) = REQUIRED + ]; + + // Details about the refusal. + Requisition.Refusal refusal = 2 [(google.api.field_behavior) = REQUIRED]; } // Request message for `FulfillDirectRequisition` method. message FulfillDirectRequisitionRequest { - // Resource name of the `Requisition. Required. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/Requisition"]; + // Resource name of the `Requisition. + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/Requisition", + (google.api.field_behavior) = REQUIRED + ]; // Encrypted `SignedData` containing the data (serialized Measurement.Result - // message) for fulfillment. Required. + // message) for fulfillment. // // The encryption uses the measurement_public_key from measurement_spec as // the recipient's public key. - bytes encrypted_data = 2; + bytes encrypted_data = 2 [(google.api.field_behavior) = REQUIRED]; - // The `nonce` value from the `encrypted_requisition_spec`. Required. - fixed64 nonce = 3; + // The `nonce` value from the `encrypted_requisition_spec`. + // + // (-- api-linter: core::0141::forbidden-types=disabled + // aip.dev/not-precedent: This is a random 64-bit value. --) + fixed64 nonce = 3 [(google.api.field_behavior) = REQUIRED]; } // Response message for `FulfillDirectRequisition` method. message FulfillDirectRequisitionResponse { // Resulting state of the `Requisition`. - Requisition.State state = 1; + Requisition.State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; } diff --git a/tools/api-lint b/tools/api-lint new file mode 100755 index 000000000..fd6d8796f --- /dev/null +++ b/tools/api-lint @@ -0,0 +1,21 @@ +#!/usr/bin/env bash + +set -eu -o pipefail + +readonly BAZEL="${BAZEL:-bazel}" +readonly PROTO_PATH='src/main/proto' + +declare bazel_bin +bazel_bin="$("$BAZEL" info bazel-bin)" + +"$BAZEL" query "kind(proto_library, $PROTO_PATH/...)" | xargs "$BAZEL" build + +find "$PROTO_PATH" -name '*.proto' -printf '%P\0' | + xargs -0 api-linter --proto-path "$PROTO_PATH" \ + --config "$PROTO_PATH/api-linter.yaml" \ + --descriptor-set-in "${bazel_bin}/external/com_github_protocolbuffers_protobuf/descriptor_proto-descriptor-set.proto.bin" \ + --descriptor-set-in "${bazel_bin}/external/com_google_googleapis/google/type/date_proto-descriptor-set.proto.bin" \ + --descriptor-set-in "${bazel_bin}/external/com_google_googleapis/google/api/resource_proto-descriptor-set.proto.bin" \ + --descriptor-set-in "${bazel_bin}/external/com_google_googleapis/google/api/field_behavior_proto-descriptor-set.proto.bin" \ + --descriptor-set-in "${bazel_bin}/external/com_google_googleapis/google/api/client_proto-descriptor-set.proto.bin" \ + "$@"