From ada830616be372fb9acf6c736ba960bdb9d9973d Mon Sep 17 00:00:00 2001 From: Denis Kirillov Date: Wed, 3 Aug 2022 09:53:16 +0300 Subject: [PATCH] [#36] Add docs Signed-off-by: Denis Kirillov --- spec/rest.yaml | 31 +++++++++++++++++++++++++++++++ static/docs/docs.md | 20 ++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/spec/rest.yaml b/spec/rest.yaml index 9a398eb..4e72954 100644 --- a/spec/rest.yaml +++ b/spec/rest.yaml @@ -1132,6 +1132,11 @@ definitions: required: - lifetime - members + example: + name: my-storage-group + lifetime: 100 + members: + - 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd StorageGroup: description: Storage group keeps verification information for Data Audit sessions. type: object @@ -1144,10 +1149,13 @@ definitions: readOnly: true $ref: '#/definitions/Address' expirationEpoch: + description: Expiration epoch of storage group. type: string hash: + description: Homomorphic hash from the concatenation of the payloads of the storage group members. Empty means hashing is disabled. type: string size: + description: Total size of the payloads of objects in the storage group. type: string members: description: Object identifiers to be placed into storage group. Must be unique. @@ -1159,6 +1167,15 @@ definitions: - expirationEpoch - size - members + example: + name: my-storage-group + address: + objectId: 9N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + expirationEpoch: 5000 + size: 4096 + members: + - 8N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd StorageGroupBaseInfo: description: Storage group info for listing. type: object @@ -1172,6 +1189,12 @@ definitions: required: - address - expirationEpoch + example: + name: my-storage-group + address: + objectId: 9N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + expirationEpoch: 5000 StorageGroupList: description: List of storage groups. type: object @@ -1185,6 +1208,14 @@ definitions: required: - size - storageGroups + example: + size: 1 + storageGroups: + - name: my-storage-group + address: + objectId: 9N3o7Dtr6T1xteCt6eRwhpmJ7JhME58Hyu1dvaswuTDd + containerId: 5HZTn5qkRnmgSz9gSrw22CEdPPk6nQhkwf2Mgzyvkikv + expirationEpoch: 5000 Attribute: description: Attribute is a pair of strings that can be attached to a container or an object. type: object diff --git a/static/docs/docs.md b/static/docs/docs.md index e26c849..cb436f8 100644 --- a/static/docs/docs.md +++ b/static/docs/docs.md @@ -75,4 +75,24 @@ Also, you can use this attribute to further object searching. More about FrostFS status code you can find [here](https://github.com/nspcc-dev/neofs-spec/blob/master/20-api-v2/status.md). +### Storage groups +The concept of a storage group has been introduced to reduce the dependence of the complexity of +the check on the number of stored objects in the system. + +The consistency and availability of multiple objects on the network are achieved by validating the +storage group without saving meta information and performing validation on each object. + +`StorageGroup` keeps verification information for Data Audit sessions. Objects that require paid storage +guaranties are gathered in `StorageGroups` with additional information used for proof of storage +checks. A `StorageGroup` can be created only for objects from the same container. + +A `StorageGroup` are objects of a special type with the payload containing the serialized protobuf +structure. For the details on the format please refer to the [API specification](https://github.com/nspcc-dev/neofs-spec/blob/master/20-api-v2/storagegroup.md) in the corresponding section. + +StorageGroup structure has information about: +* Total size of the payloads of objects in the storage group +* Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the members field. + +* Last NeoFS epoch number of the storage group lifetime +* Alpha-numerically sorted list of member objects