From 10e449a07ec4dc7e49026f9bf49427daab2d3f06 Mon Sep 17 00:00:00 2001 From: Sanjay Vasandani Date: Thu, 1 Jun 2023 11:24:38 -0700 Subject: [PATCH] Fix api-linter errors. --- src/main/proto/api-linter.yaml | 21 ++++ .../wfa/measurement/api/v2alpha/BUILD.bazel | 56 ++++++++- .../wfa/measurement/api/v2alpha/account.proto | 1 + .../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/data_provider.proto | 28 ++--- .../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 | 11 +- .../api/v2alpha/exchange_steps_service.proto | 45 ++++++-- .../api/v2alpha/exchange_workflow.proto | 33 ++++-- .../api/v2alpha/exchanges_service.proto | 38 +++--- .../measurement/api/v2alpha/measurement.proto | 109 ++++++++++++------ .../api/v2alpha/measurement_consumer.proto | 8 +- .../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_release.proto | 5 + .../api/v2alpha/model_releases_service.proto | 22 +++- .../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 ++++-- .../v2alpha/recurring_exchanges_service.proto | 29 +++-- .../measurement/api/v2alpha/requisition.proto | 4 +- .../requisition_fulfillment_service.proto | 27 +++-- .../api/v2alpha/requisition_spec.proto | 46 +++++--- tools/api-lint | 20 ++++ 44 files changed, 870 insertions(+), 338 deletions(-) create mode 100644 src/main/proto/api-linter.yaml create mode 100755 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..f7a9d35f1 --- /dev/null +++ b/src/main/proto/api-linter.yaml @@ -0,0 +1,21 @@ +# 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' diff --git a/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel b/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel index dc927c07d..d1e93b074 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel +++ b/src/main/proto/wfa/measurement/api/v2alpha/BUILD.bazel @@ -23,6 +23,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 +34,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 +45,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 +58,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", ], ) @@ -73,6 +77,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 +88,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 +100,7 @@ proto_library( deps = [ ":crypto_proto", ":measurement_consumer_proto", + "@com_google_googleapis//google/api:field_behavior_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -150,7 +157,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 +168,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 +179,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 +221,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 +244,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 +270,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 +295,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 +306,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 +318,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 +344,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 +356,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 +367,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 +378,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 +389,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 +402,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 +411,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 +423,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 +434,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 +447,7 @@ proto_library( deps = [ ":measurement_proto", ":requisition_proto", + "@com_google_googleapis//google/api:client_proto", "@com_google_googleapis//google/api:resource_proto", ], ) @@ -431,6 +458,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 +470,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 +482,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 +494,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 +506,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 +518,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 +530,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 +541,8 @@ proto_library( srcs = ["recurring_exchanges_service.proto"], deps = [ ":recurring_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 +552,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", ], ) @@ -530,6 +574,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", "@com_google_protobuf//:timestamp_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..dae64a36b 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/account.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/account.proto @@ -27,6 +27,7 @@ message Account { option (google.api.resource) = { type: "halo.wfanet.org/Account" pattern: "accounts/{account}" + plural: "accounts" }; enum View { 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/data_provider.proto b/src/main/proto/wfa/measurement/api/v2alpha/data_provider.proto index a88510b4b..879893a04 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,35 @@ 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"]; + repeated string required_external_duchy_ids = 6 + [(google.api.field_behavior) = UNORDERED_LIST]; } 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 c89c8f944..064194add 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"; @@ -28,6 +29,8 @@ message Exchange { option (google.api.resource) = { type: "halo.wfanet.org/Exchange" pattern: "recurringExchanges/{recurring_exchange}/exchanges/{exchange}" + singular: "exchange" + plural: "exchanges" }; // Resource name. @@ -36,7 +39,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. @@ -48,9 +53,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; @@ -59,7 +63,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 ffe6798a0..24b0bcf08 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"; @@ -28,13 +29,15 @@ message ExchangeStep { option (google.api.resource) = { type: "halo.wfanet.org/ExchangeStep" pattern: "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; @@ -46,7 +49,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. @@ -54,6 +59,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 339f131dd..5c4dfd3ca 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 @@ -38,7 +38,8 @@ service ExchangeStepAttempts { returns (ListExchangeStepAttemptsResponse); // 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). // @@ -100,15 +101,15 @@ message ListExchangeStepAttemptsResponse { string next_page_token = 2; } -// 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"]; // The messages to append. Do NOT include sensitive information in this field. - repeated ExchangeStepAttempt.DebugLog log_entries = 2; + repeated ExchangeStepAttempt.DebugLogEntry log_entries = 2; } // Request message for `FinishExchangeStepAttempt` method. @@ -121,5 +122,5 @@ message FinishExchangeStepAttemptRequest { ExchangeStepAttempt.State final_state = 2; // 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 65fbbd942..81b193ae1 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 @@ -28,7 +28,9 @@ option java_outer_classname = "ExchangeStepsServiceProto"; // Service for interacting with `ExchangeStep` resources. service ExchangeSteps { // Returns the `ExchangeStep` with the specified resource key. - rpc GetExchangeStep(GetExchangeStepRequest) returns (ExchangeStep); + rpc GetExchangeStep(GetExchangeStepRequest) returns (ExchangeStep) { + option (google.api.method_signature) = "name"; + } // Find and claims an `ExchangeStep` that is ready to be worked on, creating // an initial `ExchangeStepAttempt` for it. @@ -40,14 +42,18 @@ service ExchangeSteps { // Lists `ExchangeStep`s. rpc ListExchangeSteps(ListExchangeStepsRequest) - returns (ListExchangeStepsResponse); + returns (ListExchangeStepsResponse) { + option (google.api.method_signature) = "parent"; + } } // Request message for `GetExchangeStep` method. message GetExchangeStepRequest { // Resource name. - string name = 1 - [(google.api.resource_reference).type = "halo.wfanet.org/ExchangeStep"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/ExchangeStep", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `ClaimReadyExchangeStep` method. @@ -75,8 +81,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. @@ -95,29 +104,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..14048925d 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_count = 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_count = 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_count = 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 4762bd40d..f5efc5b9b 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,10 +28,14 @@ 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"; + } // Lists `Exchanges`. - rpc ListExchanges(ListExchangesRequest) returns (ListExchangesResponse); + rpc ListExchanges(ListExchangesRequest) returns (ListExchangesResponse) { + option (google.api.method_signature) = "parent"; + } // Uploads an encrypted audit trail for the exchange. // Only the EDP will be authorized to call this method. @@ -40,21 +46,19 @@ service Exchanges { // 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 + ]; } // Request message for `ListExchanges` method. message ListExchangesRequest { - // TODO(efoxepstein): add fields + // Resource name of the parent `RecurringExchange`. + string parent = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/RecurringExchange", + (google.api.field_behavior) = REQUIRED + ]; // The maximum number of `Exchange`s to return. // The service may return fewer than this value. @@ -68,6 +72,8 @@ message ListExchangesRequest { // When paginating, all other parameters provided to `ListExchangesRequest` // must match the call that provided the page token. string page_token = 3; + + // TODO(efoxepstein): add fields } // Response message for `ListExchanges` method. @@ -92,9 +98,13 @@ message UploadAuditTrailRequest { bytes audit_trail_data = 2; } + // Header for a series of `UploadAuditTrailRequest` messages. + // + // (-- api-linter: core::0123::resource-annotation=disabled + // aip.dev/not-precedent: This is not a resource message. --) message Header { // The `Exchange` to upload the data to. string name = 1 [(google.api.resource_reference).type = "halo.wfanet.org/Exchange"]; } -} \ No newline at end of file +} 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..215178338 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"; @@ -52,8 +53,11 @@ message 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"]; + 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; 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_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_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/recurring_exchanges_service.proto b/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchanges_service.proto index cd6a6f589..db7a0832b 100644 --- a/src/main/proto/wfa/measurement/api/v2alpha/recurring_exchanges_service.proto +++ b/src/main/proto/wfa/measurement/api/v2alpha/recurring_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/recurring_exchange.proto"; @@ -27,11 +29,15 @@ option java_outer_classname = "RecurringExchangesServiceProto"; service RecurringExchanges { // Returns the `RecurringExchange` with the specified resource key. rpc GetRecurringExchange(GetRecurringExchangeRequest) - returns (RecurringExchange); + returns (RecurringExchange) { + option (google.api.method_signature) = "name"; + } // Creates a `RecurringExchange`. rpc CreateRecurringExchange(CreateRecurringExchangeRequest) - returns (RecurringExchange); + returns (RecurringExchange) { + option (google.api.method_signature) = "recurring_exchange"; + } // Lists `RecurringExchanges`. rpc ListRecurringExchanges(ListRecurringExchangesRequest) @@ -45,15 +51,18 @@ service RecurringExchanges { // Request message for `GetRecurringExchange` method. message GetRecurringExchangeRequest { // Resource name. - string name = 1 [(google.api.resource_reference).type = - "halo.wfanet.org/RecurringExchange"]; + string name = 1 [ + (google.api.resource_reference).type = "halo.wfanet.org/RecurringExchange", + (google.api.field_behavior) = REQUIRED + ]; } // Request message for `CreateRecurringExchange` method. message CreateRecurringExchangeRequest { - // The `RecurringExchange` to create. Required. The `key` field will be + // The `RecurringExchange` to create. Required. The `name` field will be // ignored, and the system will assign an ID. - RecurringExchange recurring_exchange = 1; + RecurringExchange recurring_exchange = 1 + [(google.api.field_behavior) = REQUIRED]; } // Request message for `ListRecurringExchanges` method. @@ -75,8 +84,10 @@ message ListRecurringExchangesRequest { // Limits the results to those that match ALL of the specified criteria. Unset // fields are ignored (i.e. treated like wildcards). message Filter { + // Resource name of `DataProvider` to filter by. string data_provider = 1 [(google.api.resource_reference).type = "halo.wfanet.org/DataProvider"]; + // Resource name of `ModelProvider` to filter by. string model_provider = 2 [(google.api.resource_reference).type = "halo.wfanet.org/ModelProvider"]; } @@ -84,18 +95,22 @@ message ListRecurringExchangesRequest { // Restrictions on the RecurringExchanges listed. It is an error to request // RecurringExchanges that are not associated with the caller, so at least // one of `data_provider` or `model_provider` should be specified. + // (-- api-linter: core::0132::request-field-types=disabled + // aip.dev/not-precedent: This API uses structured filters. --) Filter filter = 3; } +// Response message for `ListRecurringExchanges` method. message ListRecurringExchangesResponse { // Page of `RecurringExchange`s. - repeated RecurringExchange resources = 1; + repeated RecurringExchange recurring_exchanges = 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 `RetireRecurringExchange` method. message RetireRecurringExchangeRequest { // Resource name. string name = 1 [(google.api.resource_reference).type = diff --git a/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto b/src/main/proto/wfa/measurement/api/v2alpha/requisition.proto index e1da63d9a..9924bf5e0 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"; @@ -97,7 +98,8 @@ message Requisition { Value value = 2; } // Map of `Duchy` name to parameters for that `Duchy`. Required. Immutable. - repeated DuchyEntry duchies = 9; + repeated DuchyEntry duchies = 9 + [(google.api.field_behavior) = UNORDERED_LIST]; // State of a `Requisition`. enum State { 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/tools/api-lint b/tools/api-lint new file mode 100755 index 000000000..b6ad4e77d --- /dev/null +++ b/tools/api-lint @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +set -eu -o pipefail + +readonly PROTO_PATH='src/main/proto' + +declare bazel_bin +bazel_bin="$(bazel info bazel-bin)" + +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" \ + "$@"