orikik/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Pull requests 1 Activity Actions

[#194] Generate docs with recent protocol changes

Browse source 
Signed-off-by: Leonard Lyubich <leonard@nspcc.ru>
This commit is contained in:
Leonard Lyubich 2022-02-21 19:00:08 +03:00 • committed by LeL
parent fc79cd18cc
commit 2743e4ba11
6 changed files with 279 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

118
proto-docs/object.md
View file

@ -93,9 +93,19 @@ be restored by concatenation of object message payload and all chunks
keeping receiving order.
Statuses:
- **OK** (0, SECTION_SUCCESS):
object has been successfully read;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
object has been successfully read;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
read access to the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
object not found in container;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired;
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
the requested object has been marked as deleted.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -110,9 +120,24 @@ object payload. All messages, except first one, SHOULD be payload chunks.
Chunk messages SHOULD be sent in direct order of fragmentation.
Statuses:
- **OK** (0, SECTION_SUCCESS):
object has been successfully saved in the container;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
object has been successfully saved in the container;
- Common failures (SECTION_FAILURE_COMMON);
- **LOCKED** (2050, SECTION_OBJECT): \
placement of an object of type TOMBSTONE that includes at least one locked
object is prohibited;
- **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
placement of an object of type LOCK that includes at least one object of
type other than REGULAR is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object storage container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
write access to the container is denied;
- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
(for trusted object preparation) session private key does not exist or has
been deleted;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -123,9 +148,17 @@ Delete the object from a container. There is no immediate removal
guarantee. Object will be marked for removal and deleted eventually.
Statuses:
- **OK** (0, SECTION_SUCCESS):
object has been successfully marked to be removed from the container;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
object has been successfully marked to be removed from the container;
- Common failures (SECTION_FAILURE_COMMON);
- **LOCKED** (2050, SECTION_OBJECT): \
deleting a locked object is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
delete access to the object is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -137,9 +170,19 @@ returned. If `main_only` request field is set, the short header with only
the very minimal information would be returned instead.
Statuses:
- **OK** (0, SECTION_SUCCESS):
object header has been successfully read;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
object header has been successfully read;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
access to operation HEAD of the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
object not found in container;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired;
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
the requested object has been marked as deleted.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -151,9 +194,15 @@ Header's filed values. Please see the corresponding NeoFS Technical
Specification section for more details.
Statuses:
- **OK** (0, SECTION_SUCCESS):
objects have been successfully selected;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
objects have been successfully selected;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
search container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
access to operation SEARCH of the object is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -166,9 +215,19 @@ restored by concatenation of all received payload chunks keeping receiving
order.
Statuses:
- **OK** (0, SECTION_SUCCESS):
data range of the object payload has been successfully read;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
data range of the object payload has been successfully read;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
access to operation RANGE of the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
object not found in container;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired;
- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \
the requested object has been marked as deleted.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -181,9 +240,17 @@ length) tuples. Hashes order in response corresponds to ranges order in
request. Note that hash is calculated for XORed data.
Statuses:
- **OK** (0, SECTION_SUCCESS):
data range of the object payload has been successfully hashed;
- Common failures (SECTION_FAILURE_COMMON).
- **OK** (0, SECTION_SUCCESS): \
data range of the object payload has been successfully hashed;
- Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found;
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \
access to operation RANGEHASH of the object is denied;
- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
object not found in container;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired.
| Name | Input | Output |
| ---- | ----- | ------ |
@ -780,6 +847,9 @@ Object structure. Object is immutable and content-addressed. It means
`ObjectID` will change if header or payload changes. It's calculated as a
hash of header field, which contains hash of object's payload.
For non-regular object types payload format depends on object type specified
in the header.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
@ -843,19 +913,21 @@ Type of match expression
### ObjectType
Type of the object payload content. Only `REGULAR` type objects can be split,
hence `TOMBSTONE` and `STORAGE_GROUP` payload is limited by maximal object
size.
hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by maximal
object size.
String presentation of object type is the same as definition:
* REGULAR
* TOMBSTONE
* STORAGE_GROUP
* LOCK
| Name | Number | Description |
| ---- | ------ | ----------- |
| REGULAR | 0 | Just a normal object |
| TOMBSTONE | 1 | Used internally to identify deleted objects |
| STORAGE_GROUP | 2 | StorageGroup information |
| LOCK | 3 | Object lock |
<!-- end enums -->