Clarification for eXtended Headers in MetaHeader

Minor clarification to show how XHeaders should be used.

Signed-off-by: Stanislav Bogatyrev <stanislav@nspcc.ru>

object/service.proto

@@ -19,6 +19,16 @@ service ObjectService {
   // be restored by concatenation of object message payload and all chunks
   // keeping receiving order.
   //
+  // Extended headers can change `Get` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  // * __NEOFS__NETMAP_LOOKUP_DEPTH \
+  //   Will try older versions of network map to find an object until the depth
+  //   limit reached.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   object has been successfully read;
@@ -42,6 +52,13 @@ service ObjectService {
   // object payload. All messages, except first one, SHOULD be payload chunks.
   // Chunk messages SHOULD be sent in direct order of fragmentation.
   //
+  // Extended headers can change `Put` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   object has been successfully saved in the container;
@@ -66,6 +83,13 @@ service ObjectService {
   // Delete the object from a container. There is no immediate removal
   // guarantee. Object will be marked for removal and deleted eventually.
   //
+  // Extended headers can change `Delete` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   object has been successfully marked to be removed from the container;
@@ -84,6 +108,13 @@ service ObjectService {
   // returned. If `main_only` request field is set, the short header with only
   // the very minimal information would be returned instead.
   //
+  // Extended headers can change `Head` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   object header has been successfully read;
@@ -104,6 +135,13 @@ service ObjectService {
   // Header's filed values. Please see the corresponding NeoFS Technical
   // Specification section for more details.
   //
+  // Extended headers can change `Search` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   objects have been successfully selected;
@@ -121,6 +159,16 @@ service ObjectService {
   // restored by concatenation of all received payload chunks keeping receiving
   // order.
   //
+  // Extended headers can change `GetRange` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  // * __NEOFS__NETMAP_LOOKUP_DEPTH \
+  //   Will try older versions of network map to find an object until the depth
+  //   limit reached.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   data range of the object payload has been successfully read;
@@ -142,6 +190,16 @@ service ObjectService {
   // length) tuples. Hashes order in response corresponds to ranges order in
   // request. Note that hash is calculated for XORed data.
   //
+  // Extended headers can change `GetRangeHash` behaviour:
+  // * __NEOFS__NETMAP_EPOCH \
+  //   Will use the requsted version of Network Map for object placement
+  //   calculation.
+  // * __NEOFS__NETMAP_LOOKUP_DEPTH \
+  //   Will try older versions of network map to find an object until the depth
+  //   limit reached.
+  //
+  // Please refer to detailed `XHeader` description.
+  //
   // Statuses:
   // - **OK** (0, SECTION_SUCCESS): \
   //   data range of the object payload has been successfully hashed;

session/types.proto

@@ -117,8 +117,15 @@ message SessionToken {
   neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"];
 }
 
-// Extended headers for Request/Response. May contain any user-defined headers
-// to be interpreted on application level.
+// Extended headers for Request/Response may contain any user-defined headers to
+// be interpreted on application level. It may be used by Storage Nodes for
+// experimental protocol extensions with official adoption of such changes in
+// the future protocol versions.
+//
+// It may be useful to have extended headers in both Request and Response. For
+// example, if the Request has a header enabling some extended functionality,
+// the Response might have an extended header indicating that the requested
+// functionality was enabled during request processing.
 //
 // Key name must be unique valid UTF-8 string. Value can't be empty. Requests or
 // Responses with duplicated header names or headers with empty values will be