potyarkin/frostfs-api
1
0
Fork 0
forked from TrueCloudLab/frostfs-api
Code Pull requests Activity Actions
frostfs-api/proto-docs/apemanager.md
Airat Arifullin c94b8ab6ae [#46] apemanager: Introduce proto-s for apemanager service 
* Introduce proto-s for `APEManagerService` and related types.
* Introduce a new status section related to `APEManagerService`.
* Generate proto-docs.

Signed-off-by: Airat Arifullin <aarifullin@yadro.com>
2024-04-27 13:48:04 +00:00

329 lines
13 KiB
Markdown
Raw Blame History

# 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 |
View git blame Copy permalink