From c94b8ab6aed6698a62f5efd4875ec3bef061440a Mon Sep 17 00:00:00 2001 From: Airat Arifullin Date: Tue, 23 Apr 2024 22:18:22 +0300 Subject: [PATCH] [#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 --- apemanager/service.proto | 171 ++++++++++++++++++++ apemanager/types.proto | 33 ++++ proto-docs/apemanager.md | 329 +++++++++++++++++++++++++++++++++++++++ proto-docs/status.md | 12 ++ status/types.proto | 9 ++ 5 files changed, 554 insertions(+) create mode 100644 apemanager/service.proto create mode 100644 apemanager/types.proto create mode 100644 proto-docs/apemanager.md diff --git a/apemanager/service.proto b/apemanager/service.proto new file mode 100644 index 0000000..6b9da60 --- /dev/null +++ b/apemanager/service.proto @@ -0,0 +1,171 @@ +syntax = "proto3"; + +package frostfs.v2.apemanager; + +import "apemanager/types.proto"; +import "session/types.proto"; + +option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager"; + +// `APEManagerService` provides API to manage rule chains within sidechain's +// `Policy` smart contract. +service APEManagerService { + // 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. + rpc AddChain(AddChainRequest) returns (AddChainResponse); + + // 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. + rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse); + + // 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. + rpc ListChains(ListChainsRequest) returns (ListChainsResponse); +} + +message AddChainRequest { + message Body { + // A target for which a rule chain is added. + ChainTarget target = 1; + + // The chain to set for the target. + Chain chain = 2; + } + + // The request's body. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +message AddChainResponse { + message Body { + // Chain ID assigned for the added rule chain. + // If chain ID is left empty in the request, then + // it will be generated. + bytes chain_id = 1; + } + + // The response's body. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} + +message RemoveChainRequest { + message Body { + // Target for which a rule chain is removed. + ChainTarget target = 1; + + // Chain ID assigned for the rule chain. + bytes chain_id = 2; + } + + // The request's body. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +message RemoveChainResponse { + // Since RemoveChain is an idempotent operation, then the only indicator that + // operation could not be performed is an error returning to a client. + message Body {} + + // The response's body. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} + +message ListChainsRequest { + message Body { + // Target for which rule chains are listed. + ChainTarget target = 1; + } + + // The request's body. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +message ListChainsResponse { + message Body { + // The list of chains defined for the reqeusted target. + repeated Chain chains = 1; + } + + // The response's body. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} \ No newline at end of file diff --git a/apemanager/types.proto b/apemanager/types.proto new file mode 100644 index 0000000..c064627 --- /dev/null +++ b/apemanager/types.proto @@ -0,0 +1,33 @@ +syntax = "proto3"; + +package frostfs.v2.apemanager; + +option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager"; + +// TargetType is a type target to which a rule chain is defined. +enum TargetType { + UNDEFINED = 0; + + NAMESPACE = 1; + + CONTAINER = 2; + + USER = 3; + + GROUP = 4; +} + +// ChainTarget is an object to which a rule chain is defined. +message ChainTarget { + TargetType type = 1; + + string name = 2; +} + +// Chain is a chain of rules defined for a specific target. +message Chain { + oneof kind { + // Raw representation of a serizalized rule chain. + bytes raw = 1; + } +} diff --git a/proto-docs/apemanager.md b/proto-docs/apemanager.md new file mode 100644 index 0000000..303f7f1 --- /dev/null +++ b/proto-docs/apemanager.md @@ -0,0 +1,329 @@ +# Protocol Documentation + + +## 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) + + + + +

Top

+ +## apemanager/service.proto + + + + + + +### 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) | + + + + + +### 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. | + + + + +### 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. | + + + + +### 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. | + + + + +### 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. | + + + + +### 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. | + + + + +### Message ListChainsRequest.Body + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| target | [ChainTarget](#frostfs.v2.apemanager.ChainTarget) | | Target for which rule chains are listed. | + + + + +### 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. | + + + + +### Message ListChainsResponse.Body + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| chains | [Chain](#frostfs.v2.apemanager.Chain) | repeated | The list of chains defined for the reqeusted target. | + + + + +### 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. | + + + + +### 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. | + + + + +### 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. | + + + + +### 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. + + + + + + + + + +

Top

+ +## apemanager/types.proto + + + + + + + +### 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. | + + + + +### 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) | | | + + + + + + +### 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 | | + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| 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 | +| 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 | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/status.md b/proto-docs/status.md index 87d3b41..c1401bd 100644 --- a/proto-docs/status.md +++ b/proto-docs/status.md @@ -79,6 +79,17 @@ covered by the code. + + +### APEManager +Section of status for APE manager related operations. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| APE_MANAGER_ACCESS_DENIED | 0 | [**5120**] The operation is denied by APE manager. | + + + ### CommonFail @@ -134,6 +145,7 @@ Section identifiers. | SECTION_OBJECT | 2 | Object service-specific errors. | | SECTION_CONTAINER | 3 | Container service-specific errors. | | SECTION_SESSION | 4 | Session service-specific errors. | +| SECTION_APE_MANAGER | 5 | Session service-specific errors. | diff --git a/status/types.proto b/status/types.proto index 52a7214..2205abc 100644 --- a/status/types.proto +++ b/status/types.proto @@ -73,6 +73,9 @@ enum Section { // Session service-specific errors. SECTION_SESSION = 4; + + // Session service-specific errors. + SECTION_APE_MANAGER = 5; } // Section of NeoFS successful return codes. @@ -146,3 +149,9 @@ enum Session { // [**4097**] Token has expired. TOKEN_EXPIRED = 1; } + +// Section of status for APE manager related operations. +enum APEManager { + // [**5120**] The operation is denied by APE manager. + APE_MANAGER_ACCESS_DENIED = 0; +} \ No newline at end of file