From af4e72706de7e38c69c22870fc262dbadb32617e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rn=20Friedrich=20Dreyer?= Date: Wed, 8 Sep 2021 16:09:26 +0200 Subject: [PATCH] use the google protobuf field mask MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jörn Friedrich Dreyer use received share Signed-off-by: Jörn Friedrich Dreyer --- .../v1beta1/collaboration_api.proto | 19 +- .../collaboration/v1beta1/resources.proto | 7 +- cs3/sharing/ocm/v1beta1/ocm_api.proto | 18 +- cs3/sharing/ocm/v1beta1/resources.proto | 7 +- docs/index.html | 118 +++------ proto.lock | 117 ++++++--- prototool.yaml | 35 +++ third_party/google/protobuf/field_mask.proto | 245 ++++++++++++++++++ tools/check-license/check-license.go | 2 +- 9 files changed, 412 insertions(+), 156 deletions(-) create mode 100644 third_party/google/protobuf/field_mask.proto diff --git a/cs3/sharing/collaboration/v1beta1/collaboration_api.proto b/cs3/sharing/collaboration/v1beta1/collaboration_api.proto index 437f3954..b1c3a4d5 100644 --- a/cs3/sharing/collaboration/v1beta1/collaboration_api.proto +++ b/cs3/sharing/collaboration/v1beta1/collaboration_api.proto @@ -32,6 +32,7 @@ import "cs3/rpc/v1beta1/status.proto"; import "cs3/sharing/collaboration/v1beta1/resources.proto"; import "cs3/storage/provider/v1beta1/resources.proto"; import "cs3/types/v1beta1/types.proto"; +import "google/protobuf/field_mask.proto"; // User Share Provider API // @@ -225,19 +226,11 @@ message UpdateReceivedShareRequest { // Opaque information. cs3.types.v1beta1.Opaque opaque = 1; // REQUIRED. - ShareReference ref = 2; - // REQUIRED. - // The field to update. - message UpdateField { - // One of the update fields MUST be specified. - oneof field { - // Update the display name. - string display_name = 1; - // Update the share state - ShareState state = 2; - } - } - UpdateField field = 3; + // The received share to update. + ReceivedShare share = 2; + // The update mask applies to the resource. For the `FieldMask` definition, + // see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 3; } message UpdateReceivedShareResponse { diff --git a/cs3/sharing/collaboration/v1beta1/resources.proto b/cs3/sharing/collaboration/v1beta1/resources.proto index 6419df27..7e852604 100644 --- a/cs3/sharing/collaboration/v1beta1/resources.proto +++ b/cs3/sharing/collaboration/v1beta1/resources.proto @@ -79,14 +79,17 @@ message SharePermissions { // A received share is the share that a grantee will receive. // It expands the original share by adding state to the share, // a display name from the perspective of the grantee and a -// resource mount path in case the share will be mounted -// in a path in a storage provider. +// resource mount point in case the share will be mounted +// in a storage provider. message ReceivedShare { // REQUIRED. Share share = 1; // REQUIRED. // The state of the share. ShareState state = 2; + // REQUIRED. + // The mount point of the share. + storage.provider.v1beta1.Reference mount_point = 3; } // The state of the share. diff --git a/cs3/sharing/ocm/v1beta1/ocm_api.proto b/cs3/sharing/ocm/v1beta1/ocm_api.proto index af17547b..25d90244 100644 --- a/cs3/sharing/ocm/v1beta1/ocm_api.proto +++ b/cs3/sharing/ocm/v1beta1/ocm_api.proto @@ -34,6 +34,7 @@ import "cs3/rpc/v1beta1/status.proto"; import "cs3/sharing/ocm/v1beta1/resources.proto"; import "cs3/storage/provider/v1beta1/resources.proto"; import "cs3/types/v1beta1/types.proto"; +import "google/protobuf/field_mask.proto"; // OCM Share Provider API // @@ -245,18 +246,11 @@ message UpdateReceivedOCMShareRequest { // Opaque information. cs3.types.v1beta1.Opaque opaque = 1; // REQUIRED. - ShareReference ref = 2; - // REQUIRED. - message UpdateField { - // One of the update fields MUST be specified. - oneof field { - // Update the display name. - string display_name = 1; - // Update the share state - ShareState state = 2; - } - } - UpdateField field = 3; + // The received share to update. + ReceivedShare share = 2; + // The update mask applies to the resource. For the `FieldMask` definition, + // see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask + google.protobuf.FieldMask update_mask = 3; } message UpdateReceivedOCMShareResponse { diff --git a/cs3/sharing/ocm/v1beta1/resources.proto b/cs3/sharing/ocm/v1beta1/resources.proto index efc0c405..f3de64fd 100644 --- a/cs3/sharing/ocm/v1beta1/resources.proto +++ b/cs3/sharing/ocm/v1beta1/resources.proto @@ -91,14 +91,17 @@ message SharePermissions { // A received share is the share that a grantee will receive. // It expands the original share by adding state to the share, // a display name from the perspective of the grantee and a -// resource mount path in case the share will be mounted -// in a path in a storage provider. +// resource mount point in case the share will be mounted +// in a storage provider. message ReceivedShare { // REQUIRED. Share share = 1; // REQUIRED. // The state of the share. ShareState state = 2; + // REQUIRED. + // The mount point of the share. + storage.provider.v1beta1.Reference mount_point = 3; } // The state of the share. diff --git a/docs/index.html b/docs/index.html index 4eb3d4a8..c01ec4b3 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1168,10 +1168,6 @@

Table of Contents

MUpdateReceivedShareRequest -
  • - MUpdateReceivedShareRequest.UpdateField -
    • -
  • MUpdateReceivedShareResponse
    • @@ -1440,10 +1436,6 @@

    Table of Contents

    MUpdateReceivedOCMShareRequest -
  • - MUpdateReceivedOCMShareRequest.UpdateField -
    • -
  • MUpdateReceivedOCMShareResponse
    • @@ -9833,48 +9825,19 @@

    UpdateRece - ref - ShareReference - -

    REQUIRED.

    - - - - field - UpdateReceivedShareRequest.UpdateField - -

    - - - - - - - - - -

    UpdateReceivedShareRequest.UpdateField

    -

    REQUIRED.

    The field to update.

    - - - - - - - - - - - + + - + - - + + - + @@ -10184,7 +10147,7 @@

    Filter

    ReceivedShare

    -

    A received share is the share that a grantee will receive.

    It expands the original share by adding state to the share,

    a display name from the perspective of the grantee and a

    resource mount path in case the share will be mounted

    in a path in a storage provider.

    +

    A received share is the share that a grantee will receive.

    It expands the original share by adding state to the share,

    a display name from the perspective of the grantee and a

    resource mount point in case the share will be mounted

    in a storage provider.

    FieldTypeLabelDescription
    display_namestringshareReceivedShare

    Update the display name.

    REQUIRED. +The received share to update.

    stateShareStateupdate_maskgoogle.protobuf.FieldMask

    Update the share state

    The update mask applies to the resource. For the `FieldMask` definition, +see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

    @@ -10208,6 +10171,14 @@

    ReceivedShare

    The state of the share.

    + + + + + + +
    mount_pointcs3.storage.provider.v1beta1.Reference

    REQUIRED. +The mount point of the share.

    @@ -12260,48 +12231,19 @@

    UpdateReceivedOCM - ref - ShareReference - -

    REQUIRED.

    - - - - field - UpdateReceivedOCMShareRequest.UpdateField - -

    - - - - - - - - - -

    UpdateReceivedOCMShareRequest.UpdateField

    -

    REQUIRED.

    - - - - - - - - - - - + + - + - - + + - + @@ -12491,7 +12433,7 @@

    cs3/sharing/ocm/v1beta1/resourc

    ReceivedShare

    -

    A received share is the share that a grantee will receive.

    It expands the original share by adding state to the share,

    a display name from the perspective of the grantee and a

    resource mount path in case the share will be mounted

    in a path in a storage provider.

    +

    A received share is the share that a grantee will receive.

    It expands the original share by adding state to the share,

    a display name from the perspective of the grantee and a

    resource mount point in case the share will be mounted

    in a storage provider.

    FieldTypeLabelDescription
    display_namestringshareReceivedShare

    Update the display name.

    REQUIRED. +The received share to update.

    stateShareStateupdate_maskgoogle.protobuf.FieldMask

    Update the share state

    The update mask applies to the resource. For the `FieldMask` definition, +see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask

    @@ -12515,6 +12457,14 @@

    ReceivedShare

    The state of the share.

    + + + + + + +
    mount_pointcs3.storage.provider.v1beta1.Reference

    REQUIRED. +The mount point of the share.

    diff --git a/proto.lock b/proto.lock index fe23bc68..528774c3 100644 --- a/proto.lock +++ b/proto.lock @@ -4830,30 +4830,13 @@ }, { "id": 2, - "name": "ref", - "type": "ShareReference" + "name": "share", + "type": "ReceivedShare" }, { "id": 3, - "name": "field", - "type": "UpdateField" - } - ], - "messages": [ - { - "name": "UpdateField", - "fields": [ - { - "id": 1, - "name": "display_name", - "type": "string" - }, - { - "id": 2, - "name": "state", - "type": "ShareState" - } - ] + "name": "update_mask", + "type": "google.protobuf.FieldMask" } ] }, @@ -4972,6 +4955,9 @@ }, { "path": "cs3/types/v1beta1/types.proto" + }, + { + "path": "google/protobuf/field_mask.proto" } ], "package": { @@ -5134,6 +5120,11 @@ "id": 2, "name": "state", "type": "ShareState" + }, + { + "id": 3, + "name": "mount_point", + "type": "storage.provider.v1beta1.Reference" } ] }, @@ -6217,30 +6208,13 @@ }, { "id": 2, - "name": "ref", - "type": "ShareReference" + "name": "share", + "type": "ReceivedShare" }, { "id": 3, - "name": "field", - "type": "UpdateField" - } - ], - "messages": [ - { - "name": "UpdateField", - "fields": [ - { - "id": 1, - "name": "display_name", - "type": "string" - }, - { - "id": 2, - "name": "state", - "type": "ShareState" - } - ] + "name": "update_mask", + "type": "google.protobuf.FieldMask" } ] }, @@ -6360,6 +6334,9 @@ }, { "path": "cs3/types/v1beta1/types.proto" + }, + { + "path": "google/protobuf/field_mask.proto" } ], "package": { @@ -6521,6 +6498,11 @@ "id": 2, "name": "state", "type": "ShareState" + }, + { + "id": 3, + "name": "mount_point", + "type": "storage.provider.v1beta1.Reference" } ] }, @@ -9333,6 +9315,57 @@ } ] } + }, + { + "protopath": "third_party:/:google:/:protobuf:/:field_mask.proto", + "def": { + "messages": [ + { + "name": "FieldMask", + "fields": [ + { + "id": 1, + "name": "paths", + "type": "string", + "is_repeated": true + } + ] + } + ], + "package": { + "name": "google.protobuf" + }, + "options": [ + { + "name": "cc_enable_arenas", + "value": "true" + }, + { + "name": "csharp_namespace", + "value": "Google.Protobuf.WellKnownTypes" + }, + { + "name": "go_package", + "value": "google.golang.org/protobuf/types/known/fieldmaskpb" + }, + { + "name": "java_multiple_files", + "value": "true" + }, + { + "name": "java_outer_classname", + "value": "FieldMaskProto" + }, + { + "name": "java_package", + "value": "com.google.protobuf" + }, + { + "name": "objc_class_prefix", + "value": "GPB" + } + ] + } } ] } \ No newline at end of file diff --git a/prototool.yaml b/prototool.yaml index e6150164..55709699 100644 --- a/prototool.yaml +++ b/prototool.yaml @@ -1,3 +1,18 @@ +# Paths to exclude when searching for Protobuf files. +# These can either be file or directory names. +# If there is a directory name, that directory and all sub-directories will be excluded. +excludes: + - docs + - tools + +# Protoc directives. +protoc: + # Additional paths to include with -I to protoc. + # By default, the directory of the config file is included, + # or the current directory if there is no config file. + includes: + - third_party + lint: group: uber2 ignores: @@ -16,6 +31,26 @@ lint: - id: REQUEST_RESPONSE_NAMES_MATCH_RPC files: - cs3/gateway/v1beta1/gateway_api.proto + # the external google field mask + - id: FILE_OPTIONS_EQUAL_CSHARP_NAMESPACE_CAPITALIZED + files: + - third_party/google/protobuf/field_mask.proto + - id: FILE_OPTIONS_EQUAL_GO_PACKAGE_V2_SUFFIX + files: + - third_party/google/protobuf/field_mask.proto + - id: FILE_OPTIONS_EQUAL_OBJC_CLASS_PREFIX_ABBR + files: + - third_party/google/protobuf/field_mask.proto + - id: FILE_OPTIONS_REQUIRE_PHP_NAMESPACE + files: + - third_party/google/protobuf/field_mask.proto + - id: MESSAGES_HAVE_SENTENCE_COMMENTS_EXCEPT_REQUEST_RESPONSE_TYPES + files: + - third_party/google/protobuf/field_mask.proto + - id: PACKAGE_MAJOR_BETA_VERSIONED + files: + - third_party/google/protobuf/field_mask.proto + diff --git a/third_party/google/protobuf/field_mask.proto b/third_party/google/protobuf/field_mask.proto new file mode 100644 index 00000000..858e94da --- /dev/null +++ b/third_party/google/protobuf/field_mask.proto @@ -0,0 +1,245 @@ +// Protocol Buffers - Google's data interchange format +// Copyright 2008 Google Inc. All rights reserved. +// https://developers.google.com/protocol-buffers/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto3"; + +package google.protobuf; + +option cc_enable_arenas = true; +option csharp_namespace = "Google.Protobuf.WellKnownTypes"; +option go_package = "google.golang.org/protobuf/types/known/fieldmaskpb"; +option java_multiple_files = true; +option java_outer_classname = "FieldMaskProto"; +option java_package = "com.google.protobuf"; +option objc_class_prefix = "GPB"; + +// `FieldMask` represents a set of symbolic field paths, for example: +// +// paths: "f.a" +// paths: "f.b.d" +// +// Here `f` represents a field in some root message, `a` and `b` +// fields in the message found in `f`, and `d` a field found in the +// message in `f.b`. +// +// Field masks are used to specify a subset of fields that should be +// returned by a get operation or modified by an update operation. +// Field masks also have a custom JSON encoding (see below). +// +// # Field Masks in Projections +// +// When used in the context of a projection, a response message or +// sub-message is filtered by the API to only contain those fields as +// specified in the mask. For example, if the mask in the previous +// example is applied to a response message as follows: +// +// f { +// a : 22 +// b { +// d : 1 +// x : 2 +// } +// y : 13 +// } +// z: 8 +// +// The result will not contain specific values for fields x,y and z +// (their value will be set to the default, and omitted in proto text +// output): +// +// +// f { +// a : 22 +// b { +// d : 1 +// } +// } +// +// A repeated field is not allowed except at the last position of a +// paths string. +// +// If a FieldMask object is not present in a get operation, the +// operation applies to all fields (as if a FieldMask of all fields +// had been specified). +// +// Note that a field mask does not necessarily apply to the +// top-level response message. In case of a REST get operation, the +// field mask applies directly to the response, but in case of a REST +// list operation, the mask instead applies to each individual message +// in the returned resource list. In case of a REST custom method, +// other definitions may be used. Where the mask applies will be +// clearly documented together with its declaration in the API. In +// any case, the effect on the returned resource/resources is required +// behavior for APIs. +// +// # Field Masks in Update Operations +// +// A field mask in update operations specifies which fields of the +// targeted resource are going to be updated. The API is required +// to only change the values of the fields as specified in the mask +// and leave the others untouched. If a resource is passed in to +// describe the updated values, the API ignores the values of all +// fields not covered by the mask. +// +// If a repeated field is specified for an update operation, new values will +// be appended to the existing repeated field in the target resource. Note that +// a repeated field is only allowed in the last position of a `paths` string. +// +// If a sub-message is specified in the last position of the field mask for an +// update operation, then new value will be merged into the existing sub-message +// in the target resource. +// +// For example, given the target message: +// +// f { +// b { +// d: 1 +// x: 2 +// } +// c: [1] +// } +// +// And an update message: +// +// f { +// b { +// d: 10 +// } +// c: [2] +// } +// +// then if the field mask is: +// +// paths: ["f.b", "f.c"] +// +// then the result will be: +// +// f { +// b { +// d: 10 +// x: 2 +// } +// c: [1, 2] +// } +// +// An implementation may provide options to override this default behavior for +// repeated and message fields. +// +// In order to reset a field's value to the default, the field must +// be in the mask and set to the default value in the provided resource. +// Hence, in order to reset all fields of a resource, provide a default +// instance of the resource and set all fields in the mask, or do +// not provide a mask as described below. +// +// If a field mask is not present on update, the operation applies to +// all fields (as if a field mask of all fields has been specified). +// Note that in the presence of schema evolution, this may mean that +// fields the client does not know and has therefore not filled into +// the request will be reset to their default. If this is unwanted +// behavior, a specific service may require a client to always specify +// a field mask, producing an error if not. +// +// As with get operations, the location of the resource which +// describes the updated values in the request message depends on the +// operation kind. In any case, the effect of the field mask is +// required to be honored by the API. +// +// ## Considerations for HTTP REST +// +// The HTTP kind of an update operation which uses a field mask must +// be set to PATCH instead of PUT in order to satisfy HTTP semantics +// (PUT must only be used for full updates). +// +// # JSON Encoding of Field Masks +// +// In JSON, a field mask is encoded as a single string where paths are +// separated by a comma. Fields name in each path are converted +// to/from lower-camel naming conventions. +// +// As an example, consider the following message declarations: +// +// message Profile { +// User user = 1; +// Photo photo = 2; +// } +// message User { +// string display_name = 1; +// string address = 2; +// } +// +// In proto a field mask for `Profile` may look as such: +// +// mask { +// paths: "user.display_name" +// paths: "photo" +// } +// +// In JSON, the same mask is represented as below: +// +// { +// mask: "user.displayName,photo" +// } +// +// # Field Masks and Oneof Fields +// +// Field masks treat fields in oneofs just as regular fields. Consider the +// following message: +// +// message SampleMessage { +// oneof test_oneof { +// string name = 4; +// SubMessage sub_message = 9; +// } +// } +// +// The field mask can be: +// +// mask { +// paths: "name" +// } +// +// Or: +// +// mask { +// paths: "sub_message" +// } +// +// Note that oneof type names ("test_oneof" in this case) cannot be used in +// paths. +// +// ## Field Mask Verification +// +// The implementation of any API method which has a FieldMask type field in the +// request should verify the included field paths, and return an +// `INVALID_ARGUMENT` error if any path is unmappable. +message FieldMask { + // The set of field mask paths. + repeated string paths = 1; +} diff --git a/tools/check-license/check-license.go b/tools/check-license/check-license.go index ed0dc84f..d4ac267d 100644 --- a/tools/check-license/check-license.go +++ b/tools/check-license/check-license.go @@ -58,7 +58,7 @@ var skip = map[string]bool{} func main() { flag.Parse() - err := filepath.Walk(".", func(path string, fi os.FileInfo, err error) error { + err := filepath.Walk("cs3", func(path string, fi os.FileInfo, err error) error { if skip[path] { return nil }