spec: default field sizes; clarify OPTIONAL fields

Author: James DeFelice

csi.proto

@@ -181,6 +181,7 @@ message VolumeCapability {
   // Indicate that the volume will be accessed via the filesystem API.
   message MountVolume {
     // The filesystem type. This field is OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string fs_type = 1;
 
     // The mount options that can be used for the volume. This field is
@@ -232,24 +233,25 @@ message VolumeCapability {
 // `required_bytes` and `limit_bytes` can be set to the same value. At
 // least one of the these fields MUST be specified.
 message CapacityRange {
-  // Volume must be at least this big.
+  // Volume must be at least this big. This field is OPTIONAL.
+  // A value of 0 is equal to an unspecified field value.
   uint64 required_bytes = 1;
 
-  // Volume must not be bigger than this.
+  // Volume must not be bigger than this. This field is OPTIONAL.
+  // A value of 0 is equal to an unspecified field value.
   uint64 limit_bytes = 2;
 }
 
 // The information about a provisioned volume.
 message VolumeInfo {
   // The capacity of the volume in bytes. This field is OPTIONAL. If not
-  // set, it indicates that the capacity of the volume is unknown (e.g.,
-  // NFS share). If set, it MUST be non-zero.
+  // set (value of 0), it indicates that the capacity of the volume is
+  // unknown (e.g., NFS share).
   uint64 capacity_bytes = 1;
 
   // Contains identity information for the created volume. This field is
   // REQUIRED. The identity information will be used by the CO in
-  // subsequent calls to refer to the provisioned volume. This field
-  // should not exceed 1MiB.
+  // subsequent calls to refer to the provisioned volume.
   string id = 2;
 
   // Attributes reflect static properties of a volume and MUST be passed
@@ -421,6 +423,7 @@ message ValidateVolumeCapabilitiesResponse {
 
     // Message to the CO if `supported` above is false. This field is
     // OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string message = 2;
   }
 
@@ -436,18 +439,19 @@ message ListVolumesRequest {
   // The API version assumed by the CO. This field is REQUIRED.
   Version version = 1;
 
-  // If specified, the Plugin MUST NOT return more entries than this
-  // number in the response. If the actual number of entries is more
-  // than this number, the Plugin MUST set `next_token` in the response
-  // which can be used to get the next page of entries in the subsequent
-  // `ListVolumes` call. This field is OPTIONAL. If not specified, it
-  // means there is no restriction on the number of entries that can be
-  // returned.
+  // If specified (non-zero value), the Plugin MUST NOT return more
+  // entries than this number in the response. If the actual number of
+  // entries is more than this number, the Plugin MUST set `next_token`
+  // in the response which can be used to get the next page of entries
+  // in the subsequent `ListVolumes` call. This field is OPTIONAL. If
+  // not specified (zero value), it means there is no restriction on the
+  // number of entries that can be returned.
   uint32 max_entries = 2;
 
   // A token to specify where to start paginating. Set this field to
   // `next_token` returned by a previous `ListVolumes` call to get the
   // next page of entries. This field is OPTIONAL.
+  // An empty string is equal to an unspecified field value.
   string starting_token = 3;
 }
 
@@ -464,6 +468,7 @@ message ListVolumesResponse {
     // `max_entries`, use the `next_token` as a value for the
     // `starting_token` field in the next `ListVolumes` request. This
     // field is OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string next_token = 2;
   }
 

lib/go/csi/csi.pb.go

@@ -295,6 +295,18 @@ However, in some circumstances, the CO may lose state (for example when the CO c
 The plugin should handle this as gracefully as possible.
 The error code `OPERATION_PENDING_FOR_VOLUME` may be returned by the plugin in this case (see general error code section for details).
 
+#### Field Size Limits
+
+CSI defines general size limits for fields of various types (see table below).
+The general size limit for a particular field may be overridden by specifying a different size limit in said field's description.
+The general size limits apply for messages generated by both COs and plugins.
+
+| Size       | Field Type          |
+|------------|---------------------|
+| 128 bytes  | string              |
+| 4 KiB      | map<string, string> |
+| 4 KiB      | repeated string     |
+
 ### Identity Service RPC
 
 Identity service RPCs allow a CO to negotiate an API protocol version that MAY be used for subsequent RPCs across all CSI services with respect to a particular CSI plugin.
@@ -476,6 +488,7 @@ message VolumeCapability {
   // Indicate that the volume will be accessed via the filesystem API.
   message MountVolume {
     // The filesystem type. This field is OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string fs_type = 1;
 
     // The mount options that can be used for the volume. This field is
@@ -527,24 +540,25 @@ message VolumeCapability {
 // `required_bytes` and `limit_bytes` can be set to the same value. At
 // least one of the these fields MUST be specified.
 message CapacityRange {
-  // Volume must be at least this big.
+  // Volume must be at least this big. This field is OPTIONAL.
+  // A value of 0 is equal to an unspecified field value.
   uint64 required_bytes = 1;
 
-  // Volume must not be bigger than this.
+  // Volume must not be bigger than this. This field is OPTIONAL.
+  // A value of 0 is equal to an unspecified field value.
   uint64 limit_bytes = 2;
 }
 
 // The information about a provisioned volume.
 message VolumeInfo {
   // The capacity of the volume in bytes. This field is OPTIONAL. If not
-  // set, it indicates that the capacity of the volume is unknown (e.g.,
-  // NFS share). If set, it MUST be non-zero.
+  // set (value of 0), it indicates that the capacity of the volume is
+  // unknown (e.g., NFS share).
   uint64 capacity_bytes = 1;
 
   // Contains identity information for the created volume. This field is
   // REQUIRED. The identity information will be used by the CO in
-  // subsequent calls to refer to the provisioned volume. This field
-  // should not exceed 1MiB.
+  // subsequent calls to refer to the provisioned volume.
   string id = 2;
 
   // Attributes reflect static properties of a volume and MUST be passed
@@ -761,6 +775,7 @@ message ValidateVolumeCapabilitiesResponse {
 
     // Message to the CO if `supported` above is false. This field is
     // OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string message = 2;
   }
 
@@ -782,18 +797,19 @@ message ListVolumesRequest {
   // The API version assumed by the CO. This field is REQUIRED.
   Version version = 1;
 
-  // If specified, the Plugin MUST NOT return more entries than this
-  // number in the response. If the actual number of entries is more
-  // than this number, the Plugin MUST set `next_token` in the response
-  // which can be used to get the next page of entries in the subsequent
-  // `ListVolumes` call. This field is OPTIONAL. If not specified, it
-  // means there is no restriction on the number of entries that can be
-  // returned.
+  // If specified (non-zero value), the Plugin MUST NOT return more
+  // entries than this number in the response. If the actual number of
+  // entries is more than this number, the Plugin MUST set `next_token`
+  // in the response which can be used to get the next page of entries
+  // in the subsequent `ListVolumes` call. This field is OPTIONAL. If
+  // not specified (zero value), it means there is no restriction on the
+  // number of entries that can be returned.
   uint32 max_entries = 2;
 
   // A token to specify where to start paginating. Set this field to
   // `next_token` returned by a previous `ListVolumes` call to get the
   // next page of entries. This field is OPTIONAL.
+  // An empty string is equal to an unspecified field value.
   string starting_token = 3;
 }
 
@@ -810,6 +826,7 @@ message ListVolumesResponse {
     // `max_entries`, use the `next_token` as a value for the
     // `starting_token` field in the next `ListVolumes` request. This
     // field is OPTIONAL.
+    // An empty string is equal to an unspecified field value.
     string next_token = 2;
   }