From cd5fdbbd5598812f5c7aa687a67a5509970835f3 Mon Sep 17 00:00:00 2001
From: Stanislav Bogatyrev <stanislav@nspcc.ru>
Date: Sat, 5 Mar 2022 13:57:52 +0300
Subject: [PATCH] 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 | 58 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/object/service.proto b/object/service.proto
index 8ad4330..248fe89 100644
--- a/object/service.proto
+++ b/object/service.proto
@@ -19,6 +19,16 @@ service ObjectService {
   // be restored by concatenation of object message payload and all chunks
   // keeping the 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 the 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 will 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 the 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 the ranges order in
   // the 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;