From d308f9187293086e5b8891024dcc7a4b0b641ba1 Mon Sep 17 00:00:00 2001 From: Leonard Lyubich Date: Wed, 5 Aug 2020 21:01:50 +0300 Subject: [PATCH] [#33] accounting: Tidy up the format Signed-off-by: Leonard Lyubich --- accounting/service.proto | 35 +++++++++++++++++++++++++---------- proto-docs/accounting.md | 21 ++++++++++++++------- 2 files changed, 39 insertions(+), 17 deletions(-) diff --git a/accounting/service.proto b/accounting/service.proto index 6f45b30..f08a312 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -1,5 +1,7 @@ syntax = "proto3"; + package accounting; + option go_package = "github.com/nspcc-dev/neofs-api-go/accounting"; option csharp_namespace = "NeoFS.API.Accounting"; @@ -7,20 +9,30 @@ import "service/meta.proto"; import "service/verify.proto"; import "refs/types.proto"; -// Accounting is a service that provides access for accounting balance -// information +// The service provides methods for obtaining information +// about the account balance in NeoFS system. service Accounting { - // Balance returns current balance status of the NeoFS user - rpc Balance(BalanceRequest) returns (BalanceResponse); + // Returns the amount of funds for the requested NeoFS account. + rpc Balance (BalanceRequest) returns (BalanceResponse); } +// Message defines the request body of Balance method. +// +// To indicate the account for which the balance is requested, its identifier is used. +// +// To gain access to the requested information, the request body must be formed according +// to the requirements from the system specification. message BalanceRequest { - // OwnerID carries user identifier in NeoFS system. + // Carries user identifier in NeoFS system for which the balance is requested. refs.OwnerID OwnerID = 1; - // RequestMetaHeader contains information about request meta headers (should be embedded into message) - service.RequestMetaHeader Meta = 98; - // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) - service.RequestVerificationHeader Verify = 99; + + // Carries request meta information. Header data is used only to regulate message + // transport and does not affect request execution. + service.RequestMetaHeader MetaHeader = 98; + + // Carries request verification information. This header is used to authenticate + // the nodes of the message route and check the correctness of transmission. + service.RequestVerificationHeader VerifyHeader = 99; } // Decimal represents the decimal numbers. @@ -32,7 +44,10 @@ message Decimal { uint32 Precision = 2; } +// Message defines the response body of Balance method. +// +// The amount of funds is calculated in decimal numbers. message BalanceResponse { - // Balance contains current account balance state + // Carries the amount of funds on the account. Decimal Balance = 1; } diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index 64eea91..14d9c7c 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -28,8 +28,8 @@ ### Service "accounting.Accounting" -Accounting is a service that provides access for accounting balance -information +The service provides methods for obtaining information +about the account balance in NeoFS system. ``` rpc Balance(BalanceRequest) returns (BalanceResponse); @@ -38,7 +38,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse); #### Method Balance -Balance returns current balance status of the NeoFS user +Returns the amount of funds for the requested NeoFS account. | Name | Input | Output | | ---- | ----- | ------ | @@ -49,25 +49,32 @@ Balance returns current balance status of the NeoFS user ### Message BalanceRequest +Message defines the request body of Balance method. +To indicate the account for which the balance is requested, its identifier is used. + +To gain access to the requested information, the request body must be formed according +to the requirements from the system specification. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| OwnerID | [refs.OwnerID](#refs.OwnerID) | | OwnerID carries user identifier in NeoFS system. | -| Meta | [service.RequestMetaHeader](#service.RequestMetaHeader) | | RequestMetaHeader contains information about request meta headers (should be embedded into message) | -| Verify | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message) | +| OwnerID | [refs.OwnerID](#refs.OwnerID) | | Carries user identifier in NeoFS system for which the balance is requested. | +| MetaHeader | [service.RequestMetaHeader](#service.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| VerifyHeader | [service.RequestVerificationHeader](#service.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | ### Message BalanceResponse +Message defines the response body of Balance method. +The amount of funds is calculated in decimal numbers. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| Balance | [Decimal](#accounting.Decimal) | | Balance contains current account balance state | +| Balance | [Decimal](#accounting.Decimal) | | Carries the amount of funds on the account. |