forked from TrueCloudLab/frostfs-api
330 lines
13 KiB
Markdown
330 lines
13 KiB
Markdown
|
# Protocol Documentation
|
||
|
|
<a name="top"></a>
|
||
|
|
|
||
|
|
## Table of Contents
|
||
|
|
|
||
|
|
- [apemanager/service.proto](#apemanager/service.proto)
|
||
|
|
- Services
|
||
|
|
- [APEManagerService](#frostfs.v2.apemanager.APEManagerService)
|
||
|
|
|
||
|
|
- Messages
|
||
|
|
- [AddChainRequest](#frostfs.v2.apemanager.AddChainRequest)
|
||
|
|
- [AddChainRequest.Body](#frostfs.v2.apemanager.AddChainRequest.Body)
|
||
|
|
- [AddChainResponse](#frostfs.v2.apemanager.AddChainResponse)
|
||
|
|
- [AddChainResponse.Body](#frostfs.v2.apemanager.AddChainResponse.Body)
|
||
|
|
- [ListChainsRequest](#frostfs.v2.apemanager.ListChainsRequest)
|
||
|
|
- [ListChainsRequest.Body](#frostfs.v2.apemanager.ListChainsRequest.Body)
|
||
|
|
- [ListChainsResponse](#frostfs.v2.apemanager.ListChainsResponse)
|
||
|
|
- [ListChainsResponse.Body](#frostfs.v2.apemanager.ListChainsResponse.Body)
|
||
|
|
- [RemoveChainRequest](#frostfs.v2.apemanager.RemoveChainRequest)
|
||
|
|
- [RemoveChainRequest.Body](#frostfs.v2.apemanager.RemoveChainRequest.Body)
|
||
|
|
- [RemoveChainResponse](#frostfs.v2.apemanager.RemoveChainResponse)
|
||
|
|
- [RemoveChainResponse.Body](#frostfs.v2.apemanager.RemoveChainResponse.Body)
|
||
|
|
|
||
|
|
|
||
|
|
- [apemanager/types.proto](#apemanager/types.proto)
|
||
|
|
|
||
|
|
- Messages
|
||
|
|
- [Chain](#frostfs.v2.apemanager.Chain)
|
||
|
|
- [ChainTarget](#frostfs.v2.apemanager.ChainTarget)
|
||
|
|
|
||
|
|
|
||
|
|
- [Scalar Value Types](#scalar-value-types)
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<a name="apemanager/service.proto"></a>
|
||
|
|
<p align="right"><a href="#top">Top</a></p>
|
||
|
|
|
||
|
|
## apemanager/service.proto
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.APEManagerService"></a>
|
||
|
|
|
||
|
|
### Service "frostfs.v2.apemanager.APEManagerService"
|
||
|
|
`APEManagerService` provides API to manage rule chains within sidechain's
|
||
|
|
`Policy` smart contract.
|
||
|
|
|
||
|
|
```
|
||
|
|
rpc AddChain(AddChainRequest) returns (AddChainResponse);
|
||
|
|
rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse);
|
||
|
|
rpc ListChains(ListChainsRequest) returns (ListChainsResponse);
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Method AddChain
|
||
|
|
|
||
|
|
Add a rule chain for a specific target to `Policy` smart contract.
|
||
|
|
|
||
|
|
Statuses:
|
||
|
|
- **OK** (0, SECTION_SUCCESS): \
|
||
|
|
the chain has been successfully added;
|
||
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
||
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
||
|
|
container (as target) not found;
|
||
|
|
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
|
||
|
|
the operation is denied by the service.
|
||
|
|
|
||
|
|
| Name | Input | Output |
|
||
|
|
| ---- | ----- | ------ |
|
||
|
|
| AddChain | [AddChainRequest](#frostfs.v2.apemanager.AddChainRequest) | [AddChainResponse](#frostfs.v2.apemanager.AddChainResponse) |
|
||
|
|
#### Method RemoveChain
|
||
|
|
|
||
|
|
Remove a rule chain for a specific target from `Policy` smart contract.
|
||
|
|
RemoveChain is an idempotent operation: removal of non-existing rule chain
|
||
|
|
also means success.
|
||
|
|
|
||
|
|
Statuses:
|
||
|
|
- **OK** (0, SECTION_SUCCESS): \
|
||
|
|
the chain has been successfully removed;
|
||
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
||
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
||
|
|
container (as target) not found;
|
||
|
|
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
|
||
|
|
the operation is denied by the service.
|
||
|
|
|
||
|
|
| Name | Input | Output |
|
||
|
|
| ---- | ----- | ------ |
|
||
|
|
| RemoveChain | [RemoveChainRequest](#frostfs.v2.apemanager.RemoveChainRequest) | [RemoveChainResponse](#frostfs.v2.apemanager.RemoveChainResponse) |
|
||
|
|
#### Method ListChains
|
||
|
|
|
||
|
|
List chains defined for a specific target from `Policy` smart contract.
|
||
|
|
|
||
|
|
Statuses:
|
||
|
|
- **OK** (0, SECTION_SUCCESS): \
|
||
|
|
chains have been successfully listed;
|
||
|
|
- Common failures (SECTION_FAILURE_COMMON);
|
||
|
|
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
|
||
|
|
container (as target) not found;
|
||
|
|
- **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
|
||
|
|
the operation is denied by the service.
|
||
|
|
|
||
|
|
| Name | Input | Output |
|
||
|
|
| ---- | ----- | ------ |
|
||
|
|
| ListChains | [ListChainsRequest](#frostfs.v2.apemanager.ListChainsRequest) | [ListChainsResponse](#frostfs.v2.apemanager.ListChainsResponse) |
|
||
|
|
<!-- end services -->
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.AddChainRequest"></a>
|
||
|
|
|
||
|
|
### Message AddChainRequest
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [AddChainRequest.Body](#frostfs.v2.apemanager.AddChainRequest.Body) | | The request's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.AddChainRequest.Body"></a>
|
||
|
|
|
||
|
|
### Message AddChainRequest.Body
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| target | [ChainTarget](#frostfs.v2.apemanager.ChainTarget) | | A target for which a rule chain is added. |
|
||
|
|
| chain | [Chain](#frostfs.v2.apemanager.Chain) | | The chain to set for the target. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.AddChainResponse"></a>
|
||
|
|
|
||
|
|
### Message AddChainResponse
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [AddChainResponse.Body](#frostfs.v2.apemanager.AddChainResponse.Body) | | The response's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.AddChainResponse.Body"></a>
|
||
|
|
|
||
|
|
### Message AddChainResponse.Body
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| chain_id | [bytes](#bytes) | | Chain ID assigned for the added rule chain. If chain ID is left empty in the request, then it will be generated. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.ListChainsRequest"></a>
|
||
|
|
|
||
|
|
### Message ListChainsRequest
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [ListChainsRequest.Body](#frostfs.v2.apemanager.ListChainsRequest.Body) | | The request's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.ListChainsRequest.Body"></a>
|
||
|
|
|
||
|
|
### Message ListChainsRequest.Body
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| target | [ChainTarget](#frostfs.v2.apemanager.ChainTarget) | | Target for which rule chains are listed. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.ListChainsResponse"></a>
|
||
|
|
|
||
|
|
### Message ListChainsResponse
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [ListChainsResponse.Body](#frostfs.v2.apemanager.ListChainsResponse.Body) | | The response's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.ListChainsResponse.Body"></a>
|
||
|
|
|
||
|
|
### Message ListChainsResponse.Body
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| chains | [Chain](#frostfs.v2.apemanager.Chain) | repeated | The list of chains defined for the reqeusted target. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.RemoveChainRequest"></a>
|
||
|
|
|
||
|
|
### Message RemoveChainRequest
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [RemoveChainRequest.Body](#frostfs.v2.apemanager.RemoveChainRequest.Body) | | The request's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.RemoveChainRequest.Body"></a>
|
||
|
|
|
||
|
|
### Message RemoveChainRequest.Body
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| target | [ChainTarget](#frostfs.v2.apemanager.ChainTarget) | | Target for which a rule chain is removed. |
|
||
|
|
| chain_id | [bytes](#bytes) | | Chain ID assigned for the rule chain. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.RemoveChainResponse"></a>
|
||
|
|
|
||
|
|
### Message RemoveChainResponse
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| body | [RemoveChainResponse.Body](#frostfs.v2.apemanager.RemoveChainResponse.Body) | | The response's body. |
|
||
|
|
| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. |
|
||
|
|
| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.RemoveChainResponse.Body"></a>
|
||
|
|
|
||
|
|
### Message RemoveChainResponse.Body
|
||
|
|
Since RemoveChain is an idempotent operation, then the only indicator that
|
||
|
|
operation could not be performed is an error returning to a client.
|
||
|
|
|
||
|
|
|
||
|
|
<!-- end messages -->
|
||
|
|
|
||
|
|
<!-- end enums -->
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<a name="apemanager/types.proto"></a>
|
||
|
|
<p align="right"><a href="#top">Top</a></p>
|
||
|
|
|
||
|
|
## apemanager/types.proto
|
||
|
|
|
||
|
|
|
||
|
|
<!-- end services -->
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.Chain"></a>
|
||
|
|
|
||
|
|
### Message Chain
|
||
|
|
Chain is a chain of rules defined for a specific target.
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| raw | [bytes](#bytes) | | Raw representation of a serizalized rule chain. |
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.ChainTarget"></a>
|
||
|
|
|
||
|
|
### Message ChainTarget
|
||
|
|
ChainTarget is an object to which a rule chain is defined.
|
||
|
|
|
||
|
|
|
||
|
|
| Field | Type | Label | Description |
|
||
|
|
| ----- | ---- | ----- | ----------- |
|
||
|
|
| type | [TargetType](#frostfs.v2.apemanager.TargetType) | | |
|
||
|
|
| name | [string](#string) | | |
|
||
|
|
|
||
|
|
<!-- end messages -->
|
||
|
|
|
||
|
|
|
||
|
|
<a name="frostfs.v2.apemanager.TargetType"></a>
|
||
|
|
|
||
|
|
### TargetType
|
||
|
|
TargetType is a type target to which a rule chain is defined.
|
||
|
|
|
||
|
|
| Name | Number | Description |
|
||
|
|
| ---- | ------ | ----------- |
|
||
|
|
| UNDEFINED | 0 | |
|
||
|
|
| NAMESPACE | 1 | |
|
||
|
|
| CONTAINER | 2 | |
|
||
|
|
| USER | 3 | |
|
||
|
|
| GROUP | 4 | |
|
||
|
|
|
||
|
|
|
||
|
|
<!-- end enums -->
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## Scalar Value Types
|
||
|
|
|
||
|
|
| .proto Type | Notes | C++ Type | Java Type | Python Type |
|
||
|
|
| ----------- | ----- | -------- | --------- | ----------- |
|
||
|
|
| <a name="double" /> double | | double | double | float |
|
||
|
|
| <a name="float" /> float | | float | float | float |
|
||
|
|
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
|
||
|
|
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
|
||
|
|
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
|
||
|
|
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
|
||
|
|
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
|
||
|
|
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
|
||
|
|
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
|
||
|
|
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
|
||
|
|
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
|
||
|
|
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
|
||
|
|
| <a name="bool" /> bool | | bool | boolean | boolean |
|
||
|
|
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
|
||
|
|
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
|
||
|
|
|