From cff4184cd3d1cbc9864df323fdd795e16883249a Mon Sep 17 00:00:00 2001
From: Anton Nikiforov <an.nikiforov@yadro.com>
Date: Thu, 29 Dec 2022 11:09:23 +0300
Subject: [PATCH] [#2128] Add doc for extended headers

Signed-off-by: Anton Nikiforov <an.nikiforov@yadro.com>
Signed-off-by: Evgenii Stratonikov <e.stratonikov@yadro.com>
---
 CHANGELOG.md                                  |  1 +
 cmd/frostfs-cli/docs/storage-node-xheaders.md | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 cmd/frostfs-cli/docs/storage-node-xheaders.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b42eedc2c..2d464585a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@ Changelog for FrostFS Node
 
 ### Added
 - Separate batching for replicated operations over the same container in pilorama (#1621)
+- Doc for extended headers (#2128)
 
 ### Changed
 ### Fixed
diff --git a/cmd/frostfs-cli/docs/storage-node-xheaders.md b/cmd/frostfs-cli/docs/storage-node-xheaders.md
new file mode 100644
index 000000000..f332b22a2
--- /dev/null
+++ b/cmd/frostfs-cli/docs/storage-node-xheaders.md
@@ -0,0 +1,34 @@
+# Extended headers
+
+## Overview
+
+Extended headers are used for request/response. They may contain any user-defined headers
+to be interpreted on application level.
+Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
+Responses with duplicated header names or headers with empty values are
+considered invalid.
+
+## Existing headers
+
+There are some "well-known" headers starting with `__NEOFS__` prefix that
+affect system behaviour:
+
+* `__NEOFS__NETMAP_EPOCH` - netmap epoch to use for object placement calculation. The `value` is string
+encoded `uint64` in decimal presentation. If set to '0' or omitted, the
+current epoch only will be used.
+* `__NEOFS__NETMAP_LOOKUP_DEPTH` - if object can't be found using current epoch's netmap, this header limits
+how many past epochs the node can look up through. Depth is applied to a current epoch or the value 
+of `__NEOFS__NETMAP_EPOCH` attribute. The `value` is string encoded `uint64` in decimal presentation. 
+If set to '0' or not set, only the current epoch is used.
+
+## `neofs-cli` commands with `--xhdr`
+
+List of commands with support of extended headers:
+* `container list-objects`
+* `object delete/get/hash/head/lock/put/range/search`
+* `storagegroup delete/get/list/put`
+
+Example:
+```shell
+$ neofs-cli object put -r s01.neofs.devenv:8080 -w wallet.json --cid CID --file FILE --xhdr "__NEOFS__NETMAP_EPOCH=777"
+```