107 | ```
108 |
109 | This can be done easily with the `--signoff` option to `git commit`.
110 |
111 | By doing this, you state that you can certify the following (from [The Developer
112 | Certificate of Origin](https://developercertificate.org/)):
113 |
114 | ```
115 | Developer Certificate of Origin
116 | Version 1.1
117 |
118 | Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
119 | 1 Letterman Drive
120 | Suite D4700
121 | San Francisco, CA, 94129
122 |
123 | Everyone is permitted to copy and distribute verbatim copies of this
124 | license document, but changing it is not allowed.
125 |
126 |
127 | Developer's Certificate of Origin 1.1
128 |
129 | By making a contribution to this project, I certify that:
130 |
131 | (a) The contribution was created in whole or in part by me and I
132 | have the right to submit it under the open source license
133 | indicated in the file; or
134 |
135 | (b) The contribution is based upon previous work that, to the best
136 | of my knowledge, is covered under an appropriate open source
137 | license and I have the right under that license to submit that
138 | work with modifications, whether created in whole or in part
139 | by me, under the same open source license (unless I am
140 | permitted to submit under a different license), as indicated
141 | in the file; or
142 |
143 | (c) The contribution was provided directly to me by some other
144 | person who certified (a), (b) or (c) and I have not modified
145 | it.
146 |
147 | (d) I understand and agree that this project and the contribution
148 | are public and that a record of the contribution (including all
149 | personal information I submit with it, including my sign-off) is
150 | maintained indefinitely and may be redistributed consistent with
151 | this project or the open source license(s) involved.
152 | ```
153 |
--------------------------------------------------------------------------------
/CREDITS.md:
--------------------------------------------------------------------------------
1 | # Credits
2 |
3 | Initial NeoFS research and development (2018-2020) was done by
4 | [NeoSPCC](https://nspcc.ru) team.
5 |
6 | In alphabetical order:
7 |
8 | - Alexey Vanin
9 | - Anastasia Prasolova
10 | - Anatoly Bogatyrev
11 | - Evgeny Kulikov
12 | - Evgeny Stratonikov
13 | - Leonard Liubich
14 | - Sergei Liubich
15 | - Stanislav Bogatyrev
16 |
17 | # Contributors
18 |
19 | In chronological order:
20 | - Pavel Korotkov
21 | - Pavel Karpy
22 |
23 | # Special Thanks
24 |
25 | For product development support:
26 |
27 | - Fabian Wahle
28 | - Neo Global Development
29 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "[]"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright [yyyy] [name of copyright owner]
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | #!/usr/bin/make -f
2 | SHELL=bash
3 |
4 | # BRanch to match for BReaking changes
5 | BRBR?=master
6 |
7 | .PHONY: lint
8 | lint:
9 | buf lint
10 | buf breaking --against '.git#branch=$(BRBR)'
11 |
12 | .PHONY: doc
13 | # Regenerate documentation for proto files:
14 | doc:
15 | @for f in `find . -type f -name '*.proto' -exec dirname {} \; | sort -u `; do \
16 | echo "⇒ Documentation for $$(basename $$f)"; \
17 | protoc \
18 | --doc_opt=.github/markdown.tmpl,$${f}.md \
19 | --proto_path=.:/usr/local/include \
20 | --doc_out=proto-docs/ $${f}/*.proto; \
21 | done
22 |
23 | .PHONY: format
24 | format:
25 | buf format -w
26 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 | 
3 |
4 |
5 | NeoFS API language-agnostic protocol definitions
6 |
7 |
8 | ---
9 | 
10 | 
11 |
12 | ## Overview
13 |
14 | NeoFS-API repository is the basis for language-specific libraries, e.g.:
15 |
16 | - [neofs-sdk-go](https://github.com/nspcc-dev/neofs-sdk-go) (see `proto` package there for vanilla API)
17 | - [neofs-api-csharp](https://github.com/neo-ngd/neofs-api-csharp)
18 |
19 | Those libraries contain compiled protocol buffers definitions, wrapped with
20 | language-specific code. Use them to integrate applications with NeoFS.
21 |
22 | This repository contains:
23 |
24 | - protocol buffers packages
25 | - [auto-generated docs](proto-docs) for protocol buffers
26 |
27 | To perform linting and formatting buf is required, see https://buf.build/.
28 |
29 | ## Contributing
30 |
31 | Feel free to contribute to this project after reading the [contributing
32 | guidelines](CONTRIBUTING.md).
33 |
34 | Before you start working on a certain topic, first create a new issue
35 | describing the feature/topic you are going to implement.
36 |
37 | ## License
38 |
39 | This project is licensed under the Apache 2.0 License -
40 | see the [LICENSE](LICENSE) file for details
41 |
--------------------------------------------------------------------------------
/accounting/service.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.accounting;
4 |
5 | import "accounting/types.proto";
6 | import "refs/types.proto";
7 | import "session/types.proto";
8 |
9 | option csharp_namespace = "Neo.FileStorage.API.Accounting";
10 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting";
11 |
12 | // Accounting service provides methods for interaction with FS chain via
13 | // other NeoFS nodes to get information about the account balance. Deposit and
14 | // Withdraw operations can't be implemented here, as they require Mainnet NeoFS
15 | // smart contract invocation. Transfer operations between internal NeoFS
16 | // accounts are possible if both use the same token type.
17 | service AccountingService {
18 | // Returns the amount of funds in GAS token for the requested NeoFS account.
19 | //
20 | // Statuses:
21 | // - **OK** (0, SECTION_SUCCESS):
22 | // balance has been successfully read;
23 | // - Common failures (SECTION_FAILURE_COMMON).
24 | rpc Balance(BalanceRequest) returns (BalanceResponse);
25 | }
26 |
27 | // BalanceRequest message
28 | message BalanceRequest {
29 | // To indicate the account for which the balance is requested, its identifier
30 | // is used. It can be any existing account in FS chain `Balance` smart
31 | // contract. If omitted, client implementation MUST set it to the request's
32 | // signer `OwnerID`.
33 | message Body {
34 | // Valid user identifier in `OwnerID` format for which the balance is
35 | // requested. Required field.
36 | neo.fs.v2.refs.OwnerID owner_id = 1;
37 | }
38 | // Body of the balance request message.
39 | Body body = 1;
40 |
41 | // Carries request meta information. Header data is used only to regulate
42 | // message transport and does not affect request execution.
43 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
44 |
45 | // Carries request verification information. This header is used to
46 | // authenticate the nodes of the message route and check the correctness of
47 | // transmission.
48 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
49 | }
50 |
51 | // BalanceResponse message
52 | message BalanceResponse {
53 | // The amount of funds in GAS token for the `OwnerID`'s account requested.
54 | // Balance is given in the `Decimal` format to avoid precision issues with rounding.
55 | message Body {
56 | // Amount of funds in GAS token for the requested account.
57 | Decimal balance = 1;
58 | }
59 | // Body of the balance response message.
60 | Body body = 1;
61 |
62 | // Carries response meta information. Header data is used only to regulate
63 | // message transport and does not affect request execution.
64 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
65 |
66 | // Carries response verification information. This header is used to
67 | // authenticate the nodes of the message route and check the correctness of
68 | // transmission.
69 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
70 | }
71 |
--------------------------------------------------------------------------------
/accounting/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.accounting;
4 |
5 | option csharp_namespace = "Neo.FileStorage.API.Accounting";
6 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/accounting";
7 |
8 | // Standard floating point data type can't be used in NeoFS due to inexactness
9 | // of the result when doing lots of small number operations. To solve the lost
10 | // precision issue, special `Decimal` format is used for monetary computations.
11 | //
12 | // Please see [The General Decimal Arithmetic
13 | // Specification](http://speleotrove.com/decimal/) for detailed problem
14 | // description.
15 | message Decimal {
16 | // Number in the smallest Token fractions.
17 | int64 value = 1 [json_name = "value"];
18 |
19 | // Precision value indicating how many smallest fractions can be in one
20 | // integer.
21 | uint32 precision = 2 [json_name = "precision"];
22 | }
23 |
--------------------------------------------------------------------------------
/acl/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.acl;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Acl";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/acl";
9 |
10 | // Target role of the access control rule in access control list.
11 | enum Role {
12 | // Unspecified role, default value
13 | ROLE_UNSPECIFIED = 0;
14 |
15 | // User target rule is applied if sender is the owner of the container
16 | USER = 1;
17 |
18 | // System target rule is applied if sender is a storage node within the
19 | // container or an inner ring node
20 | SYSTEM = 2;
21 |
22 | // Others target rule is applied if sender is neither a user nor a system target
23 | OTHERS = 3;
24 | }
25 |
26 | // MatchType is an enumeration of match types.
27 | enum MatchType {
28 | // Unspecified match type, default value.
29 | MATCH_TYPE_UNSPECIFIED = 0;
30 |
31 | // Return true if strings are equal
32 | STRING_EQUAL = 1;
33 |
34 | // Return true if strings are different
35 | STRING_NOT_EQUAL = 2;
36 |
37 | // Absence of attribute
38 | NOT_PRESENT = 3;
39 |
40 | // Numeric 'greater than'
41 | NUM_GT = 4;
42 |
43 | // Numeric 'greater or equal than'
44 | NUM_GE = 5;
45 |
46 | // Numeric 'less than'
47 | NUM_LT = 6;
48 |
49 | // Numeric 'less or equal than'
50 | NUM_LE = 7;
51 | }
52 |
53 | // Request's operation type to match if the rule is applicable to a particular
54 | // request.
55 | enum Operation {
56 | // Unspecified operation, default value
57 | OPERATION_UNSPECIFIED = 0;
58 |
59 | // Get
60 | GET = 1;
61 |
62 | // Head
63 | HEAD = 2;
64 |
65 | // Put
66 | PUT = 3;
67 |
68 | // Delete
69 | DELETE = 4;
70 |
71 | // Search
72 | SEARCH = 5;
73 |
74 | // GetRange
75 | GETRANGE = 6;
76 |
77 | // GetRangeHash
78 | GETRANGEHASH = 7;
79 | }
80 |
81 | // Rule execution result action. Either allows or denies access if the rule's
82 | // filters match.
83 | enum Action {
84 | // Unspecified action, default value
85 | ACTION_UNSPECIFIED = 0;
86 |
87 | // Allow action
88 | ALLOW = 1;
89 |
90 | // Deny action
91 | DENY = 2;
92 | }
93 |
94 | // Enumeration of possible sources of Headers to apply filters.
95 | enum HeaderType {
96 | // Unspecified header, default value.
97 | HEADER_UNSPECIFIED = 0;
98 |
99 | // Filter request headers
100 | REQUEST = 1;
101 |
102 | // Filter object headers
103 | OBJECT = 2;
104 |
105 | // Filter service headers. These are not processed by NeoFS nodes and
106 | // exist for service use only.
107 | SERVICE = 3;
108 | }
109 |
110 | // Describes a single eACL rule.
111 | message EACLRecord {
112 | // NeoFS request Verb to match
113 | Operation operation = 1 [json_name = "operation"];
114 |
115 | // Rule execution result. Either allows or denies access if filters match.
116 | Action action = 2 [json_name = "action"];
117 |
118 | // Filter to check particular properties of the request or the object.
119 | //
120 | // The `value` field must be empty if `match_type` is an unary operator
121 | // (e.g. `NOT_PRESENT`). If `match_type` field is numeric (e.g. `NUM_GT`),
122 | // the `value` field must be a base-10 integer.
123 | //
124 | // By default `key` field refers to the corresponding object's `Attribute`.
125 | // Some Object's header fields can also be accessed by adding `$Object:`
126 | // prefix to the name. For such attributes, field 'match_type' must not be
127 | // 'NOT_PRESENT'. Here is the list of fields available via this prefix:
128 | //
129 | // * $Object:version \
130 | // version
131 | // * $Object:objectID \
132 | // object_id
133 | // * $Object:containerID \
134 | // container_id
135 | // * $Object:ownerID \
136 | // owner_id
137 | // * $Object:creationEpoch \
138 | // creation_epoch
139 | // * $Object:payloadLength \
140 | // payload_length
141 | // * $Object:payloadHash \
142 | // payload_hash
143 | // * $Object:objectType \
144 | // object_type
145 | // * $Object:homomorphicHash \
146 | // homomorphic_hash
147 | //
148 | // Numeric `match_type` field can only be used with `$Object:creationEpoch`
149 | // and `$Object:payloadLength` system attributes.
150 | //
151 | // Please note, that if request or response does not have object's headers of
152 | // full object (Range, RangeHash, Search, Delete), it will not be possible to
153 | // filter by object header fields or user attributes. From the well-known list
154 | // only `$Object:objectID` and `$Object:containerID` will be available, as
155 | // it's possible to take that information from the requested address.
156 | message Filter {
157 | // Define if Object or Request header will be used
158 | HeaderType header_type = 1 [json_name = "headerType"];
159 |
160 | // Match operation type
161 | MatchType match_type = 2 [json_name = "matchType"];
162 |
163 | // Name of the Header to use
164 | string key = 3 [json_name = "key"];
165 |
166 | // Expected Header Value or pattern to match
167 | string value = 4 [json_name = "value"];
168 | }
169 |
170 | // List of filters to match and see if rule is applicable
171 | repeated Filter filters = 3 [json_name = "filters"];
172 |
173 | // Target to apply ACL rule. Can be a subject's role class or a list of public
174 | // keys to match.
175 | message Target {
176 | // Target subject's role class
177 | Role role = 1 [json_name = "role"];
178 |
179 | // List of 25-byte accounts to identify target subjects.
180 | // 33-byte public keys are also supported, however, they are deprecated and script hashes should be derived from them.
181 | repeated bytes keys = 2 [json_name = "keys"];
182 | }
183 | // List of target subjects to apply ACL rule to
184 | repeated Target targets = 4 [json_name = "targets"];
185 | }
186 |
187 | // Extended ACL rules table. A list of ACL rules defined additionally to Basic
188 | // ACL. Extended ACL rules can be attached to a container and can be updated
189 | // or may be defined in `BearerToken` structure. Please see the corresponding
190 | // NeoFS Technical Specification section for detailed description.
191 | message EACLTable {
192 | // eACL format version. Effectively, the version of API library used to create
193 | // eACL Table.
194 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
195 |
196 | // Identifier of the container that should use given access control rules
197 | neo.fs.v2.refs.ContainerID container_id = 2 [json_name = "containerID"];
198 |
199 | // List of Extended ACL rules
200 | repeated EACLRecord records = 3 [json_name = "records"];
201 | }
202 |
203 | // BearerToken allows to attach signed Extended ACL rules to the request in
204 | // `RequestMetaHeader`. If container's Basic ACL rules allow, the attached rule
205 | // set will be checked instead of one attached to the container itself. Just
206 | // like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
207 | // used in the similar use cases, like providing authorisation to externally
208 | // authenticated party.
209 | //
210 | // BearerToken can be issued only by the container's owner and must be signed using
211 | // the key associated with the container's `OwnerID`.
212 | message BearerToken {
213 | // Bearer Token body structure contains Extended ACL table issued by the container
214 | // owner with additional information preventing token abuse.
215 | message Body {
216 | // Table of Extended ACL rules to use instead of the ones attached to the
217 | // container. If it contains `container_id` field, bearer token is only
218 | // valid for this specific container. Otherwise, any container of the same owner
219 | // is allowed.
220 | EACLTable eacl_table = 1 [json_name = "eaclTable"];
221 |
222 | // `OwnerID` defines to whom the token was issued. It must match the request
223 | // originator's `OwnerID`. If empty, any token bearer will be accepted.
224 | neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"];
225 |
226 | // Lifetime parameters of the token. Field names taken from
227 | // [rfc7519](https://tools.ietf.org/html/rfc7519).
228 | message TokenLifetime {
229 | // Expiration epoch, the last epoch when token is valid.
230 | uint64 exp = 1 [json_name = "exp"];
231 |
232 | // Not valid before epoch, the first epoch when token is valid.
233 | uint64 nbf = 2 [json_name = "nbf"];
234 |
235 | // Issued at Epoch
236 | uint64 iat = 3 [json_name = "iat"];
237 | }
238 | // Token expiration and valid time period parameters
239 | TokenLifetime lifetime = 3 [json_name = "lifetime"];
240 |
241 | // Token issuer's user ID in NeoFS. It must equal to the related
242 | // container's owner.
243 | neo.fs.v2.refs.OwnerID issuer = 4 [json_name = "issuer"];
244 | }
245 | // Bearer Token body
246 | Body body = 1 [json_name = "body"];
247 |
248 | // Signature of BearerToken body
249 | neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"];
250 | }
251 |
--------------------------------------------------------------------------------
/audit/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.audit;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Audit";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/audit";
9 |
10 | // DataAuditResult keeps record of conducted Data Audits. The detailed report is
11 | // generated separately.
12 | message DataAuditResult {
13 | // Data Audit Result format version. Effectively, the version of API library
14 | // used to report DataAuditResult structure.
15 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
16 |
17 | // Epoch number when the Data Audit was conducted
18 | fixed64 audit_epoch = 2 [json_name = "auditEpoch"];
19 |
20 | // Container under audit
21 | neo.fs.v2.refs.ContainerID container_id = 3 [json_name = "containerID"];
22 |
23 | // Public key of the auditing InnerRing node in a binary format
24 | bytes public_key = 4 [json_name = "publicKey"];
25 |
26 | // Shows if Data Audit process was complete in time or if it was cancelled
27 | bool complete = 5 [json_name = "complete"];
28 |
29 | // Number of request done at PoR stage
30 | uint32 requests = 6 [json_name = "requests"];
31 |
32 | // Number of retries done at PoR stage
33 | uint32 retries = 7 [json_name = "retries"];
34 |
35 | // List of Storage Groups that passed audit PoR stage
36 | repeated neo.fs.v2.refs.ObjectID pass_sg = 8 [json_name = "passSG"];
37 |
38 | // List of Storage Groups that failed audit PoR stage
39 | repeated neo.fs.v2.refs.ObjectID fail_sg = 9 [json_name = "failSG"];
40 |
41 | // Number of sampled objects under the audit placed in an optimal way according to
42 | // the containers placement policy when checking PoP
43 | uint32 hit = 10 [json_name = "hit"];
44 |
45 | // Number of sampled objects under the audit placed in suboptimal way according to
46 | // the containers placement policy, but still at a satisfactory level when
47 | // checking PoP
48 | uint32 miss = 11 [json_name = "miss"];
49 |
50 | // Number of sampled objects under the audit stored inconsistently with the
51 | // placement policy or not found at all when checking PoP
52 | uint32 fail = 12 [json_name = "fail"];
53 |
54 | // List of storage node public keys that passed at least one PDP
55 | repeated bytes pass_nodes = 13 [json_name = "passNodes"];
56 |
57 | // List of storage node public keys that failed at least one PDP
58 | repeated bytes fail_nodes = 14 [json_name = "failNodes"];
59 | }
60 |
--------------------------------------------------------------------------------
/buf.yaml:
--------------------------------------------------------------------------------
1 | version: v2
2 | lint:
3 | use:
4 | - STANDARD
5 | - COMMENTS
6 | - ENUM_FIRST_VALUE_ZERO
7 | except:
8 | - PACKAGE_DIRECTORY_MATCH
9 | - PACKAGE_VERSION_SUFFIX
10 | - ENUM_VALUE_PREFIX
11 | - ENUM_ZERO_VALUE_SUFFIX
12 |
--------------------------------------------------------------------------------
/container/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.container;
4 |
5 | import "netmap/types.proto";
6 | import "refs/types.proto";
7 |
8 | option csharp_namespace = "Neo.FileStorage.API.Container";
9 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/container";
10 |
11 | // Container is a structure that defines object placement behaviour. Objects can
12 | // be stored only within containers. They define placement rule, attributes and
13 | // access control information. An ID of a container is a 32 byte long SHA256 hash
14 | // of stable-marshalled container message.
15 | message Container {
16 | // Container format version. Effectively, the version of API library used to
17 | // create the container.
18 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
19 |
20 | // Identifier of the container owner
21 | neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"];
22 |
23 | // Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s
24 | bytes nonce = 3 [json_name = "nonce"];
25 |
26 | // `BasicACL` contains access control rules for the owner, system and others groups,
27 | // as well as permission bits for `BearerToken` and `Extended ACL`
28 | uint32 basic_acl = 4 [json_name = "basicACL"];
29 |
30 | // `Attribute` is a user-defined Key-Value metadata pair attached to the
31 | // container. Container attributes are immutable. They are set at the moment of
32 | // container creation and can never be added or updated.
33 | //
34 | // Key name must be a container-unique valid UTF-8 string. Value can't be
35 | // empty. Containers with duplicated attribute names or attributes with empty
36 | // values will be considered invalid. Zero byte is also forbidden in UTF-8
37 | // strings.
38 | //
39 | // There are some "well-known" attributes affecting system behaviour:
40 | //
41 | // * __NEOFS__SUBNET \
42 | // DEPRECATED. Was used for a string ID of a container's storage subnet.
43 | // Currently doesn't affect anything.
44 | // * __NEOFS__NAME \
45 | // String of a human-friendly container name registered as a domain in
46 | // NNS contract.
47 | // * __NEOFS__ZONE \
48 | // String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS
49 | // contract. If no zone is specified, use default zone: `container`.
50 | // * __NEOFS__DISABLE_HOMOMORPHIC_HASHING \
51 | // Disables homomorphic hashing for the container if the value equals "true" string.
52 | // Any other values are interpreted as missing attribute. Container could be
53 | // accepted in a NeoFS network only if the global network hashing configuration
54 | // value corresponds with that attribute's value. After container inclusion, network
55 | // setting is ignored.
56 | // * __NEOFS__METAINFO_CONSISTENCY \
57 | // Policy rule that defines the condition under which an object is considered
58 | // processed. Acceptable values and meanings:
59 | // 1. "strict": SN processes objects' meta information, it is validated,
60 | // indexed and signed accordingly by a required minimal number of nodes
61 | // that are included in the container, a corresponding object inclusion
62 | // notification can be caught
63 | // 2. "optimistic": the same as "strict" but a successful PUT operation
64 | // does not mean objects' meta information has been multi signed and
65 | // indexed correctly, however, SNs will try to do it asynchronously;
66 | // in general PUT operations are expected to be faster than in the
67 | // "strict" case
68 | // 3. : SN does not process objects' meta
69 | // information, it is not indexed and object presence/number of copies
70 | // is not proven after a successful object PUT operation; the behavior
71 | // is the same as it was before this attribute introduction
72 | //
73 | // And some well-known attributes used by applications only:
74 | //
75 | // * Name \
76 | // Human-friendly name
77 | // * Timestamp \
78 | // User-defined local time of container creation in Unix Timestamp format
79 | message Attribute {
80 | // Attribute name key
81 | string key = 1 [json_name = "key"];
82 |
83 | // Attribute value
84 | string value = 2 [json_name = "value"];
85 | }
86 | // Attributes represent immutable container's meta data
87 | repeated Attribute attributes = 5 [json_name = "attributes"];
88 |
89 | // Placement policy for the object inside the container
90 | neo.fs.v2.netmap.PlacementPolicy placement_policy = 6 [json_name = "placementPolicy"];
91 | }
92 |
--------------------------------------------------------------------------------
/doc/release_instructions.md:
--------------------------------------------------------------------------------
1 | # Release instructions
2 |
3 | This documents outlines the neofs-api release process and can be used as a TODO
4 | list for a new release.
5 |
6 | ## Pre-release checks
7 |
8 | This should run successfully:
9 | * `make lint`
10 |
11 | ## Pre-release actions
12 |
13 | This must be run:
14 | * `make doc`
15 |
16 | ## Writing CHANGELOG
17 |
18 | Add an entry to the CHANGELOG.md following the style established there.
19 |
20 | Add a codename for releases with the new major version, version and release date in
21 | the heading. Write a paragraph describing the most significant changes done in
22 | this release. Then add sections with what has been added, changed and removed,
23 | describing each change briefly with a reference to GitHub issues, where
24 | available.
25 |
26 | ## Release commit
27 |
28 | Release commit summary should follow the template:
29 |
30 | `Release v`, e.g.:
31 |
32 | ```
33 | Release v2.9.0
34 | ```
35 |
36 | ## Tag the release
37 |
38 | Use `vX.Y.Z` tag following the semantic versioning standard. For pre-release
39 | versions use `vX.Y.Z-rc.N` scheme.
40 |
41 | ## Push changes and release tag to Github
42 |
43 | This step should bypass the default PR mechanism to get a correct result (so
44 | that releasing requires admin privileges for the project), both the `master`
45 | branch update and tag must be pushed simultaneously like this:
46 |
47 | ```
48 | $ git push origin master v2.7.0
49 | ```
50 |
51 | ## Make a proper Github release
52 |
53 | Edit an automatically-created release on Github.
54 |
55 | Release title has to follow ` ( )` scheme for major releases and just `` for regular point
57 | releases.
58 |
59 | ## Post-release actions
60 |
61 | * Close corresponding X.Y.Z Github milestone
62 | * Make announcements in Matrix and Discord channels
63 | * Update [NeoFS Technical Specification](https://github.com/nspcc-dev/neofs-spec)
64 |
--------------------------------------------------------------------------------
/link/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.link;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Link";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/link";
9 |
10 | // Link is a payload of helper objects that contain the full list of the split
11 | // chain objects' IDs. It is created only after the whole split chain is known
12 | // and signed. This object is the only object that refers to every "child object"
13 | // ID. It is NOT required for the original object assembling. It MUST have ALL
14 | // the "child objects" IDs. Child objects MUST be ordered according to the
15 | // original payload split, meaning the first payload part holder MUST be placed
16 | // at the first place in the corresponding link object. Sizes MUST NOT be omitted
17 | // and MUST be a real object payload size in bytes.
18 | message Link {
19 | // Object ID with its object's payload size.
20 | message MeasuredObject {
21 | // Object ID.
22 | neo.fs.v2.refs.ObjectID id = 1 [json_name = "id"];
23 |
24 | // Object size in bytes.
25 | uint32 size = 2 [json_name = "size"];
26 | }
27 |
28 | // Full list of the "child" object descriptors.
29 | repeated MeasuredObject children = 1 [json_name = "children"];
30 | }
31 |
--------------------------------------------------------------------------------
/lock/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.lock;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Lock";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/lock";
9 |
10 | // Lock objects protects a list of objects from being deleted. The lifetime of a
11 | // lock object is limited similar to regular objects in
12 | // `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch.
13 | // It is impossible to delete a lock object via ObjectService.Delete RPC call.
14 | // Deleting a container containing lock/locked objects results in their removal
15 | // too, regardless of their expiration epochs.
16 | message Lock {
17 | // List of objects to lock. Must not be empty or carry empty IDs.
18 | // All members must be of the `REGULAR` type.
19 | repeated neo.fs.v2.refs.ObjectID members = 1 [json_name = "members"];
20 | }
21 |
--------------------------------------------------------------------------------
/netmap/service.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.netmap;
4 |
5 | import "netmap/types.proto";
6 | import "refs/types.proto";
7 | import "session/types.proto";
8 |
9 | option csharp_namespace = "Neo.FileStorage.API.Netmap";
10 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap";
11 |
12 | // `NetmapService` provides methods to work with `Network Map` and the information
13 | // required to build it. The resulting `Network Map` is stored in FS chain
14 | // `Netmap` smart contract, while related information can be obtained from other
15 | // NeoFS nodes.
16 | service NetmapService {
17 | // Get NodeInfo structure from the particular node directly.
18 | // Node information can be taken from `Netmap` smart contract. In some cases, though,
19 | // one may want to get recent information directly or to talk to the node not yet
20 | // present in the `Network Map` to find out what API version can be used for
21 | // further communication. This can be also used to check if a node is up and running.
22 | //
23 | // Statuses:
24 | // - **OK** (0, SECTION_SUCCESS):
25 | // information about the server has been successfully read;
26 | // - Common failures (SECTION_FAILURE_COMMON).
27 | rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
28 |
29 | // Read recent information about the NeoFS network.
30 | //
31 | // Statuses:
32 | // - **OK** (0, SECTION_SUCCESS):
33 | // information about the current network state has been successfully read;
34 | // - Common failures (SECTION_FAILURE_COMMON).
35 | rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse);
36 |
37 | // Returns network map snapshot of the current NeoFS epoch.
38 | //
39 | // Statuses:
40 | // - **OK** (0, SECTION_SUCCESS):
41 | // information about the current network map has been successfully read;
42 | // - Common failures (SECTION_FAILURE_COMMON).
43 | rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse);
44 | }
45 |
46 | // Get NodeInfo structure directly from a particular node
47 | message LocalNodeInfoRequest {
48 | // LocalNodeInfo request body is empty.
49 | message Body {}
50 | // Body of the LocalNodeInfo request message
51 | Body body = 1;
52 |
53 | // Carries request meta information. Header data is used only to regulate
54 | // message transport and does not affect request execution.
55 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
56 |
57 | // Carries request verification information. This header is used to
58 | // authenticate the nodes of the message route and check the correctness of
59 | // transmission.
60 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
61 | }
62 |
63 | // Local Node Info, including API Version in use
64 | message LocalNodeInfoResponse {
65 | // Local Node Info, including API Version in use.
66 | message Body {
67 | // Latest NeoFS API version in use
68 | neo.fs.v2.refs.Version version = 1;
69 |
70 | // NodeInfo structure with recent information from node itself
71 | NodeInfo node_info = 2;
72 | }
73 | // Body of the balance response message.
74 | Body body = 1;
75 |
76 | // Carries response meta information. Header data is used only to regulate
77 | // message transport and does not affect response execution.
78 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
79 |
80 | // Carries response verification information. This header is used to
81 | // authenticate the nodes of the message route and check the correctness of
82 | // transmission.
83 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
84 | }
85 |
86 | // Get NetworkInfo structure with the network view from a particular node.
87 | message NetworkInfoRequest {
88 | // NetworkInfo request body is empty.
89 | message Body {}
90 | // Body of the NetworkInfo request message
91 | Body body = 1;
92 |
93 | // Carries request meta information. Header data is used only to regulate
94 | // message transport and does not affect request execution.
95 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
96 |
97 | // Carries request verification information. This header is used to
98 | // authenticate the nodes of the message route and check the correctness of
99 | // transmission.
100 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
101 | }
102 |
103 | // Response with NetworkInfo structure including current epoch and
104 | // FS chain magic number.
105 | message NetworkInfoResponse {
106 | // Information about the network.
107 | message Body {
108 | // NetworkInfo structure with recent information.
109 | NetworkInfo network_info = 1;
110 | }
111 | // Body of the NetworkInfo response message.
112 | Body body = 1;
113 |
114 | // Carries response meta information. Header data is used only to regulate
115 | // message transport and does not affect response execution.
116 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
117 |
118 | // Carries response verification information. This header is used to
119 | // authenticate the nodes of the message route and check the correctness of
120 | // transmission.
121 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
122 | }
123 |
124 | // Get netmap snapshot request
125 | message NetmapSnapshotRequest {
126 | // Get netmap snapshot request body.
127 | message Body {}
128 |
129 | // Body of get netmap snapshot request message.
130 | Body body = 1;
131 |
132 | // Carries request meta information. Header data is used only to regulate
133 | // message transport and does not affect request execution.
134 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
135 |
136 | // Carries request verification information. This header is used to
137 | // authenticate the nodes of the message route and check the correctness of
138 | // transmission.
139 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
140 | }
141 |
142 | // Response with current netmap snapshot
143 | message NetmapSnapshotResponse {
144 | // Get netmap snapshot response body
145 | message Body {
146 | // Structure of the requested network map.
147 | Netmap netmap = 1 [json_name = "netmap"];
148 | }
149 |
150 | // Body of get netmap snapshot response message.
151 | Body body = 1;
152 |
153 | // Carries response meta information. Header data is used only to regulate
154 | // message transport and does not affect response execution.
155 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
156 |
157 | // Carries response verification information. This header is used to
158 | // authenticate the nodes of the message route and check the correctness of
159 | // transmission.
160 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
161 | }
162 |
--------------------------------------------------------------------------------
/netmap/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.netmap;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Netmap";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/netmap";
9 |
10 | // Operations on filters
11 | enum Operation {
12 | // No Operation defined
13 | OPERATION_UNSPECIFIED = 0;
14 |
15 | // Equal
16 | EQ = 1;
17 |
18 | // Not Equal
19 | NE = 2;
20 |
21 | // Greater then
22 | GT = 3;
23 |
24 | // Greater or equal
25 | GE = 4;
26 |
27 | // Less then
28 | LT = 5;
29 |
30 | // Less or equal
31 | LE = 6;
32 |
33 | // Logical OR
34 | OR = 7;
35 |
36 | // Logical AND
37 | AND = 8;
38 | }
39 |
40 | // Selector modifier shows how the node set will be formed. By default selector
41 | // just groups nodes into a bucket by attribute, selecting nodes only by their
42 | // hash distance.
43 | enum Clause {
44 | // No modifier defined. Nodes will be selected from the bucket randomly
45 | CLAUSE_UNSPECIFIED = 0;
46 |
47 | // SAME will select only nodes having the same value of bucket attribute
48 | SAME = 1;
49 |
50 | // DISTINCT will select nodes having different values of bucket attribute
51 | DISTINCT = 2;
52 | }
53 |
54 | // This filter will return the subset of nodes from `NetworkMap` or another filter's
55 | // results that will satisfy filter's conditions.
56 | message Filter {
57 | // Name of the filter or a reference to a named filter. '*' means
58 | // application to the whole unfiltered NetworkMap. At top level it's used as a
59 | // filter name. At lower levels it's considered to be a reference to another
60 | // named filter
61 | string name = 1 [json_name = "name"];
62 |
63 | // Key to filter
64 | string key = 2 [json_name = "key"];
65 |
66 | // Filtering operation
67 | Operation op = 3 [json_name = "op"];
68 |
69 | // Value to match
70 | string value = 4 [json_name = "value"];
71 |
72 | // List of inner filters. Top level operation will be applied to the whole
73 | // list.
74 | repeated Filter filters = 5 [json_name = "filters"];
75 | }
76 |
77 | // Selector chooses a number of nodes from the bucket taking the nearest nodes
78 | // to the provided `ContainerID` by hash distance.
79 | message Selector {
80 | // Selector name to reference in object placement section
81 | string name = 1 [json_name = "name"];
82 |
83 | // How many nodes to select from the bucket
84 | uint32 count = 2 [json_name = "count"];
85 |
86 | // Selector modifier showing how to form a bucket
87 | Clause clause = 3 [json_name = "clause"];
88 |
89 | // Bucket attribute to select from
90 | string attribute = 4 [json_name = "attribute"];
91 |
92 | // Filter reference to select from
93 | string filter = 5 [json_name = "filter"];
94 | }
95 |
96 | // Number of object replicas in a set of nodes from the defined selector. If no
97 | // selector set, the root bucket containing all possible nodes will be used by
98 | // default.
99 | message Replica {
100 | // How many object replicas to put. Limited to 8.
101 | uint32 count = 1 [json_name = "count"];
102 |
103 | // Named selector bucket to put replicas
104 | string selector = 2 [json_name = "selector"];
105 | }
106 |
107 | // Set of rules to select a subset of nodes from `NetworkMap` able to store
108 | // container's objects. The format is simple enough to transpile from different
109 | // storage policy definition languages.
110 | message PlacementPolicy {
111 | // Rules to set number of object replicas and place each one into a named
112 | // bucket. Limited to 256 items.
113 | repeated Replica replicas = 1 [json_name = "replicas"];
114 |
115 | // Container backup factor (CBF) controls how deep NeoFS will search for
116 | // alternative nodes to include into container's nodes subset. In total,
117 | // the number of container nodes is Selector (used by Replica) count
118 | // times CBF. This number is limited to 64 per-Replica and 512 overall.
119 | uint32 container_backup_factor = 2 [json_name = "containerBackupFactor"];
120 |
121 | // Set of Selectors to form the container's nodes subset
122 | repeated Selector selectors = 3 [json_name = "selectors"];
123 |
124 | // List of named filters to reference in selectors
125 | repeated Filter filters = 4 [json_name = "filters"];
126 |
127 | // DEPRECATED. Was used for subnetwork ID to select nodes from, currently
128 | // ignored.
129 | refs.SubnetID subnet_id = 5 [
130 | json_name = "subnetId",
131 | deprecated = true
132 | ];
133 | }
134 |
135 | // NeoFS node description
136 | message NodeInfo {
137 | // Public key of the NeoFS node in a binary format
138 | bytes public_key = 1 [json_name = "publicKey"];
139 |
140 | // Ways to connect to a node
141 | repeated string addresses = 2 [json_name = "addresses"];
142 |
143 | // Administrator-defined Attributes of the NeoFS Storage Node.
144 | //
145 | // `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8
146 | // string (without zero bytes that are forbidden). Value can't be empty.
147 | //
148 | // Attributes can be constructed into a chain of attributes: any attribute can
149 | // have a parent attribute and a child attribute (except the first and the last
150 | // one). A string representation of the chain of attributes in NeoFS Storage
151 | // Node configuration uses ":" and "/" symbols, e.g.:
152 | //
153 | // `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2`
154 | //
155 | // Therefore the string attribute representation in the Node configuration must
156 | // use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's
157 | // key or value.
158 | //
159 | // Node's attributes are mostly used during Storage Policy evaluation to
160 | // calculate object's placement and find a set of nodes satisfying policy
161 | // requirements. There are some "well-known" node attributes common to all the
162 | // Storage Nodes in the network and used implicitly with default values if not
163 | // explicitly set:
164 | //
165 | // * Capacity \
166 | // Total available disk space in Gigabytes.
167 | // * Price \
168 | // Price in GAS tokens for storing one GB of data during one Epoch. In node
169 | // attributes it's a string presenting floating point number with comma or
170 | // point delimiter for decimal part. In the Network Map it will be saved as
171 | // 64-bit unsigned integer representing number of minimal token fractions.
172 | // * __NEOFS__SUBNET_%s \
173 | // DEPRECATED. Defined if the node is included in the `%s` subnetwork
174 | // or not. Currently ignored.
175 | // * UN-LOCODE \
176 | // Node's geographic location in
177 | // [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html)
178 | // format approximated to the nearest point defined in the standard.
179 | // * CountryCode \
180 | // Country code in
181 | // [ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
182 | // format. Calculated automatically from `UN-LOCODE` attribute.
183 | // * Country \
184 | // Country short name in English, as defined in
185 | // [ISO-3166](https://www.iso.org/obp/ui/#search). Calculated automatically
186 | // from `UN-LOCODE` attribute.
187 | // * Location \
188 | // Place names are given, whenever possible, in their national language
189 | // versions as expressed in the Roman alphabet using the 26 characters of
190 | // the character set adopted for international trade data interchange,
191 | // written without diacritics . Calculated automatically from `UN-LOCODE`
192 | // attribute.
193 | // * SubDivCode \
194 | // Country's administrative subdivision where node is located. Calculated
195 | // automatically from `UN-LOCODE` attribute based on `SubDiv` field.
196 | // Presented in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)
197 | // format.
198 | // * SubDiv \
199 | // Country's administrative subdivision name, as defined in
200 | // [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated
201 | // automatically from `UN-LOCODE` attribute.
202 | // * Continent \
203 | // Node's continent name according to the [Seven-Continent model]
204 | // (https://en.wikipedia.org/wiki/Continent#Number). Calculated
205 | // automatically from `UN-LOCODE` attribute.
206 | // * ExternalAddr
207 | // Node's preferred way for communications with external clients.
208 | // Clients SHOULD use these addresses if possible.
209 | // Must contain a comma-separated list of multi-addresses.
210 | // DEPRECATED. Use 'addresses' field instead.
211 | // * Version
212 | // Node implementation's version in a free string form.
213 | // * VerifiedNodesDomain
214 | // Confirmation of admission to a group of storage nodes.
215 | // The value is the domain name registered in the NeoFS NNS. If attribute
216 | // is specified, the storage node requesting entry into the NeoFS network
217 | // map with this attribute must be included in the access list located on
218 | // the specified domain. The access list is represented by a set of TXT
219 | // records: Neo addresses resolved from public keys. To be admitted to the
220 | // network, Neo address of the node's public key declared in 'public_key'
221 | // field must be present in domain records. Otherwise, registration will be
222 | // denied.
223 | // Value must be a valid NeoFS NNS domain name. Note that if this attribute
224 | // is absent, this check is not carried out.
225 | //
226 | // For detailed description of each well-known attribute please see the
227 | // corresponding section in NeoFS Technical Specification.
228 | message Attribute {
229 | // Key of the node attribute
230 | string key = 1 [json_name = "key"];
231 |
232 | // Value of the node attribute
233 | string value = 2 [json_name = "value"];
234 |
235 | // Parent keys, if any. For example for `City` it could be `Region` and
236 | // `Country`.
237 | repeated string parents = 3 [json_name = "parents"];
238 | }
239 | // Carries list of the NeoFS node attributes in a key-value form. Key name
240 | // must be a node-unique valid UTF-8 string (without zero bytes). Value can't
241 | // be empty. NodeInfo structures with duplicated attribute names or
242 | // attributes with empty values will be considered invalid.
243 | repeated Attribute attributes = 3 [json_name = "attributes"];
244 |
245 | // Represents the enumeration of various states of the NeoFS node.
246 | enum State {
247 | // Unknown state
248 | UNSPECIFIED = 0;
249 |
250 | // Active state in the network
251 | ONLINE = 1;
252 |
253 | // Network unavailable state
254 | OFFLINE = 2;
255 |
256 | // Maintenance state
257 | MAINTENANCE = 3;
258 | }
259 |
260 | // Carries state of the NeoFS node
261 | State state = 4 [json_name = "state"];
262 | }
263 |
264 | // Network map structure
265 | message Netmap {
266 | // Network map revision number.
267 | uint64 epoch = 1 [json_name = "epoch"];
268 |
269 | // Nodes presented in network.
270 | repeated NodeInfo nodes = 2 [json_name = "nodes"];
271 | }
272 |
273 | // NeoFS network configuration
274 | message NetworkConfig {
275 | // Single configuration parameter. Key MUST be network-unique.
276 | //
277 | // System parameters:
278 | // - **AuditFee** \
279 | // Fee paid by the storage group owner to the Inner Ring member.
280 | // Value: little-endian integer. Default: 0.
281 | // - **BasicIncomeRate** \
282 | // Cost of storing one gigabyte of data for a period of one epoch. Paid by
283 | // container owner to container nodes.
284 | // Value: little-endian integer. Default: 0.
285 | // - **ContainerAliasFee** \
286 | // Fee paid for named container's creation by the container owner.
287 | // Value: little-endian integer. Default: 0.
288 | // - **ContainerFee** \
289 | // Fee paid for container creation by the container owner.
290 | // Value: little-endian integer. Default: 0.
291 | // - **EigenTrustAlpha** \
292 | // Alpha parameter of EigenTrust algorithm used in the Reputation system.
293 | // Value: decimal floating-point number in UTF-8 string representation.
294 | // Default: 0.
295 | // - **EigenTrustIterations** \
296 | // Number of EigenTrust algorithm iterations to pass in the Reputation system.
297 | // Value: little-endian integer. Default: 0.
298 | // - **EpochDuration** \
299 | // NeoFS epoch duration measured in FS chain blocks.
300 | // Value: little-endian integer. Default: 0.
301 | // - **HomomorphicHashingDisabled** \
302 | // Flag of disabling the homomorphic hashing of objects' payload.
303 | // Value: true if any byte != 0. Default: false.
304 | // - **InnerRingCandidateFee** \
305 | // Fee for entrance to the Inner Ring paid by the candidate.
306 | // Value: little-endian integer. Default: 0.
307 | // - **MaintenanceModeAllowed** \
308 | // Flag allowing setting the MAINTENANCE state to storage nodes.
309 | // Value: true if any byte != 0. Default: false.
310 | // - **MaxObjectSize** \
311 | // Maximum size of physically stored NeoFS object measured in bytes.
312 | // Value: little-endian integer. Default: 0.
313 | // - **WithdrawFee** \
314 | // Fee paid for withdrawal of funds paid by the account owner.
315 | // Value: little-endian integer. Default: 0.
316 | message Parameter {
317 | // Parameter key. UTF-8 encoded string (with no zero bytes).
318 | bytes key = 1 [json_name = "key"];
319 |
320 | // Parameter value
321 | bytes value = 2 [json_name = "value"];
322 | }
323 | // List of parameter values
324 | repeated Parameter parameters = 1 [json_name = "parameters"];
325 | }
326 |
327 | // Information about NeoFS network
328 | message NetworkInfo {
329 | // Number of the current epoch in the NeoFS network
330 | uint64 current_epoch = 1 [json_name = "currentEpoch"];
331 |
332 | // Magic number of FS chain of the NeoFS network
333 | uint64 magic_number = 2 [json_name = "magicNumber"];
334 |
335 | // MillisecondsPerBlock network parameter of FS chain of the NeoFS network
336 | int64 ms_per_block = 3 [json_name = "msPerBlock"];
337 |
338 | // NeoFS network configuration
339 | NetworkConfig network_config = 4 [json_name = "networkConfig"];
340 | }
341 |
--------------------------------------------------------------------------------
/object/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.object;
4 |
5 | import "refs/types.proto";
6 | import "session/types.proto";
7 |
8 | option csharp_namespace = "Neo.FileStorage.API.Object";
9 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/object";
10 |
11 | // Type of the object payload content. Only `REGULAR` type objects can be split,
12 | // hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum
13 | // object size.
14 | //
15 | // String presentation of object type is the same as definition:
16 | // * REGULAR
17 | // * TOMBSTONE
18 | // * STORAGE_GROUP
19 | // * LOCK
20 | // * LINK
21 | enum ObjectType {
22 | // Just a normal object
23 | REGULAR = 0;
24 |
25 | // Used internally to identify deleted objects
26 | TOMBSTONE = 1;
27 |
28 | // StorageGroup information
29 | STORAGE_GROUP = 2;
30 |
31 | // Object lock
32 | LOCK = 3;
33 |
34 | // Object that stores child object IDs for the split objects.
35 | LINK = 4;
36 | }
37 |
38 | // Type of match expression
39 | enum MatchType {
40 | // Unknown. Not used
41 | MATCH_TYPE_UNSPECIFIED = 0;
42 |
43 | // Full string match
44 | STRING_EQUAL = 1;
45 |
46 | // Full string mismatch
47 | STRING_NOT_EQUAL = 2;
48 |
49 | // Lack of key
50 | NOT_PRESENT = 3;
51 |
52 | // String prefix match
53 | COMMON_PREFIX = 4;
54 |
55 | // Numerical 'greater than'
56 | NUM_GT = 5;
57 |
58 | // Numerical 'greater or equal than'
59 | NUM_GE = 6;
60 |
61 | // Numerical 'less than'
62 | NUM_LT = 7;
63 |
64 | // Numerical 'less or equal than'
65 | NUM_LE = 8;
66 | }
67 |
68 | // Filter structure checks if the object header field or the attribute content
69 | // matches a value.
70 | //
71 | // If no filters are set, search request will return all objects of the
72 | // container, including Regular object, Tombstones and Storage Group
73 | // objects. Most human users expect to get only object they can directly
74 | // work with. In that case, `$Object:ROOT` filter should be used.
75 | //
76 | // If `match_type` field is numerical, both `value` field and object
77 | // attribute MUST be base-10 integers.
78 | //
79 | // By default `key` field refers to the corresponding object's `Attribute`.
80 | // Some Object's header fields can also be accessed by adding `$Object:`
81 | // prefix to the name. Here is the list of fields available via this prefix:
82 | //
83 | // * $Object:version \
84 | // version
85 | // * $Object:ownerID \
86 | // owner_id
87 | // * $Object:creationEpoch \
88 | // creation_epoch
89 | // * $Object:payloadLength \
90 | // payload_length
91 | // * $Object:payloadHash \
92 | // payload_hash
93 | // * $Object:objectType \
94 | // object_type
95 | // * $Object:homomorphicHash \
96 | // homomorphic_hash
97 | // * $Object:split.parent \
98 | // object_id of parent
99 | // * $Object:split.splitID \
100 | // 16 byte UUIDv4 used to identify the split object hierarchy parts
101 | // * $Object:split.first \
102 | // object_id of the first part in split chain; non-acceptable for deprecated V1 split scheme
103 | //
104 | // There are some well-known filter aliases to match objects by certain
105 | // properties:
106 | //
107 | // * $Object:ROOT \
108 | // Returns only `REGULAR` type objects that are not split or that are the top
109 | // level root objects in a split hierarchy. This includes objects not
110 | // present physically, like large objects split into smaller objects
111 | // without a separate top-level root object. Objects of other types like
112 | // StorageGroups and Tombstones will not be shown. This filter may be
113 | // useful for listing objects like `ls` command of some virtual file
114 | // system. This filter is activated if the `key` exists, disregarding the
115 | // value and matcher type.
116 | // * $Object:PHY \
117 | // Returns only objects physically stored in the system. This filter is
118 | // activated if the `key` exists, disregarding the value and matcher type.
119 | //
120 | // Following filters are deprecated:
121 | //
122 | // * $Object:objectID \
123 | // object_id
124 | // * $Object:containerID \
125 | // container_id
126 | //
127 | // Note: using filters with a key with prefix `$Object:` and match type
128 | // `NOT_PRESENT `is not recommended since this is not a cross-version approach.
129 | // Behavior when processing this kind of filters is undefined.
130 | message SearchFilter {
131 | // Match type to use
132 | MatchType match_type = 1 [json_name = "matchType"];
133 |
134 | // Attribute or Header fields to match
135 | string key = 2 [json_name = "key"];
136 |
137 | // Value to match
138 | string value = 3 [json_name = "value"];
139 | }
140 |
141 | // Short header fields
142 | message ShortHeader {
143 | // Object format version. Effectively, the version of API library used to
144 | // create particular object.
145 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
146 |
147 | // Epoch when the object was created
148 | uint64 creation_epoch = 2 [json_name = "creationEpoch"];
149 |
150 | // Object's owner
151 | neo.fs.v2.refs.OwnerID owner_id = 3 [json_name = "ownerID"];
152 |
153 | // Type of the object payload content
154 | ObjectType object_type = 4 [json_name = "objectType"];
155 |
156 | // Size of payload in bytes.
157 | // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
158 | uint64 payload_length = 5 [json_name = "payloadLength"];
159 |
160 | // SHA256 hash of payload bytes.
161 | neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"];
162 |
163 | // Homomorphic hash of the object payload (Tillich-Zemor).
164 | neo.fs.v2.refs.Checksum homomorphic_hash = 7 [json_name = "homomorphicHash"];
165 | }
166 |
167 | // Object Header
168 | message Header {
169 | // Object format version. Effectively, the version of API library used to
170 | // create particular object
171 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
172 |
173 | // Object's container
174 | neo.fs.v2.refs.ContainerID container_id = 2 [json_name = "containerID"];
175 |
176 | // Object's owner
177 | neo.fs.v2.refs.OwnerID owner_id = 3 [json_name = "ownerID"];
178 |
179 | // Object creation Epoch
180 | uint64 creation_epoch = 4 [json_name = "creationEpoch"];
181 |
182 | // Size of payload in bytes.
183 | // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown.
184 | uint64 payload_length = 5 [json_name = "payloadLength"];
185 |
186 | // SHA256 hash of payload bytes
187 | neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"];
188 |
189 | // Type of the object payload content
190 | ObjectType object_type = 7 [json_name = "objectType"];
191 |
192 | // Homomorphic hash of the object payload (Tillich-Zemor).
193 | neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"];
194 |
195 | // Session token, if it was used during Object creation. Need it to verify
196 | // integrity and authenticity out of Request scope.
197 | neo.fs.v2.session.SessionToken session_token = 9 [json_name = "sessionToken"];
198 |
199 | // `Attribute` is a user-defined Key-Value metadata pair attached to an
200 | // object.
201 | //
202 | // Key name must be an object-unique valid UTF-8 string. Value can't be empty.
203 | // Objects with duplicated attribute names or attributes with empty values
204 | // will be considered invalid. Keys and values can't contain zero bytes as
205 | // well.
206 | //
207 | // There are some "well-known" attributes starting with `__NEOFS__` prefix
208 | // that affect system behaviour:
209 | //
210 | // * __NEOFS__EXPIRATION_EPOCH \
211 | // Tells GC to delete object after that epoch (but object is available
212 | // throughout the epoch specified in this attribute).
213 | // * __NEOFS__TICK_EPOCH \
214 | // Decimal number that defines what epoch must produce
215 | // object notification with UTF-8 object address in a
216 | // body (`0` value produces notification right after
217 | // object put).
218 | // DEPRECATED: attribute ignored by servers.
219 | // * __NEOFS__TICK_TOPIC \
220 | // UTF-8 string topic ID that is used for object notification.
221 | // DEPRECATED: attribute ignored by servers.
222 | //
223 | // And some well-known attributes used by applications only:
224 | //
225 | // * Name \
226 | // Human-friendly name
227 | // * FileName \
228 | // File name to be associated with the object on saving
229 | // * FilePath \
230 | // Full path to be associated with the object on saving. Should start with a
231 | // '/' and use '/' as a delimiting symbol. Trailing '/' should be
232 | // interpreted as a virtual directory marker. If an object has conflicting
233 | // FilePath and FileName, FilePath should have higher priority, because it
234 | // is used to construct the directory tree. FilePath with trailing '/' and
235 | // non-empty FileName attribute should not be used together.
236 | // * Timestamp \
237 | // User-defined local time of object creation in Unix Timestamp format
238 | // * Content-Type \
239 | // MIME Content Type of object's payload
240 | //
241 | // For detailed description of each well-known attribute please see the
242 | // corresponding section in NeoFS Technical Specification.
243 | message Attribute {
244 | // string key to the object attribute
245 | string key = 1 [json_name = "key"];
246 | // string value of the object attribute
247 | string value = 2 [json_name = "value"];
248 | }
249 | // User-defined object attributes. Attributes vary in length from object to
250 | // object, so keep an eye on the entire Header limit depending on the context.
251 | repeated Attribute attributes = 10 [json_name = "attributes"];
252 |
253 | // Bigger objects can be split into a chain of smaller objects. Information
254 | // about inter-dependencies between spawned objects and how to re-construct
255 | // the original one is in the `Split` headers. Parent and children objects
256 | // must be within the same container.
257 | message Split {
258 | // Identifier of the origin object. Known only to the minor child.
259 | neo.fs.v2.refs.ObjectID parent = 1 [json_name = "parent"];
260 |
261 | // Identifier of the left split neighbor
262 | neo.fs.v2.refs.ObjectID previous = 2 [json_name = "previous"];
263 |
264 | // `signature` field of the parent object. Used to reconstruct parent.
265 | neo.fs.v2.refs.Signature parent_signature = 3 [json_name = "parentSignature"];
266 |
267 | // `header` field of the parent object. Used to reconstruct parent.
268 | Header parent_header = 4 [json_name = "parentHeader"];
269 |
270 | // DEPRECATED. Was used before creating the separate LINK object type. Keep
271 | // child objects list in the LINK object's payload.
272 | // List of identifiers of the objects generated by splitting current one.
273 | repeated neo.fs.v2.refs.ObjectID children = 5 [json_name = "children"];
274 |
275 | // DEPRECATED. Was used as an identifier of a split chain. Use the first
276 | // part ID instead.
277 | // 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be
278 | // unique inside container. All objects participating in the split must have
279 | // the same `split_id` value.
280 | bytes split_id = 6 [json_name = "splitID"];
281 |
282 | // Identifier of the first part of the origin object. Known to all the split
283 | // parts except the first one. Identifies the split and allows to differ them.
284 | neo.fs.v2.refs.ObjectID first = 7 [json_name = "first"];
285 | }
286 | // Position of the object in the split hierarchy
287 | Split split = 11 [json_name = "split"];
288 | }
289 |
290 | // Object structure. Object is immutable and content-addressed. It means
291 | // `ObjectID` will change if the header or the payload changes. It's calculated as a
292 | // hash of header field which contains hash of the object's payload.
293 | //
294 | // For non-regular object types payload format depends on object type specified
295 | // in the header.
296 | message Object {
297 | // Object's unique identifier.
298 | neo.fs.v2.refs.ObjectID object_id = 1 [json_name = "objectID"];
299 |
300 | // Signed object_id
301 | neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"];
302 |
303 | // Object metadata headers
304 | Header header = 3 [json_name = "header"];
305 |
306 | // Payload bytes
307 | bytes payload = 4 [json_name = "payload"];
308 | }
309 |
310 | // Meta information of split hierarchy for object assembly. With the last part
311 | // one can traverse linked list of split hierarchy back to the first part and
312 | // assemble the original object. With a linking object one can assemble an object
313 | // right from the object parts.
314 | message SplitInfo {
315 | // DEPRECATED. Was used as an identifier of a split chain. Use the first
316 | // part ID instead.
317 | // 16 byte UUID used to identify the split object hierarchy parts.
318 | bytes split_id = 1;
319 |
320 | // The identifier of the last object in split hierarchy parts. It contains
321 | // split header with the original object header.
322 | neo.fs.v2.refs.ObjectID last_part = 2;
323 |
324 | // The identifier of a linking object for split hierarchy parts. It contains
325 | // split header with the original object header and a sorted list of
326 | // object parts.
327 | neo.fs.v2.refs.ObjectID link = 3;
328 |
329 | // Identifier of the first part of the origin object. Known to all the split
330 | // parts except the first one. Identifies the split and allows to differ them.
331 | neo.fs.v2.refs.ObjectID first_part = 4;
332 | }
333 |
--------------------------------------------------------------------------------
/proto-docs/accounting.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [accounting/service.proto](#accounting/service.proto)
7 | - Services
8 | - [AccountingService](#neo.fs.v2.accounting.AccountingService)
9 |
10 | - Messages
11 | - [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest)
12 | - [BalanceRequest.Body](#neo.fs.v2.accounting.BalanceRequest.Body)
13 | - [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse)
14 | - [BalanceResponse.Body](#neo.fs.v2.accounting.BalanceResponse.Body)
15 |
16 |
17 | - [accounting/types.proto](#accounting/types.proto)
18 |
19 | - Messages
20 | - [Decimal](#neo.fs.v2.accounting.Decimal)
21 |
22 |
23 | - [Scalar Value Types](#scalar-value-types)
24 |
25 |
26 |
27 |
28 | Top
29 |
30 | ## accounting/service.proto
31 |
32 |
33 |
34 |
35 |
36 |
37 | ### Service "neo.fs.v2.accounting.AccountingService"
38 | Accounting service provides methods for interaction with FS chain via
39 | other NeoFS nodes to get information about the account balance. Deposit and
40 | Withdraw operations can't be implemented here, as they require Mainnet NeoFS
41 | smart contract invocation. Transfer operations between internal NeoFS
42 | accounts are possible if both use the same token type.
43 |
44 | ```
45 | rpc Balance(BalanceRequest) returns (BalanceResponse);
46 |
47 | ```
48 |
49 | #### Method Balance
50 |
51 | Returns the amount of funds in GAS token for the requested NeoFS account.
52 |
53 | Statuses:
54 | - **OK** (0, SECTION_SUCCESS):
55 | balance has been successfully read;
56 | - Common failures (SECTION_FAILURE_COMMON).
57 |
58 | | Name | Input | Output |
59 | | ---- | ----- | ------ |
60 | | Balance | [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest) | [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse) |
61 |
62 |
63 |
64 |
65 |
66 | ### Message BalanceRequest
67 | BalanceRequest message
68 |
69 |
70 | | Field | Type | Label | Description |
71 | | ----- | ---- | ----- | ----------- |
72 | | body | [BalanceRequest.Body](#neo.fs.v2.accounting.BalanceRequest.Body) | | Body of the balance request message. |
73 | | 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. |
74 | | 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. |
75 |
76 |
77 |
78 |
79 | ### Message BalanceRequest.Body
80 | To indicate the account for which the balance is requested, its identifier
81 | is used. It can be any existing account in FS chain `Balance` smart
82 | contract. If omitted, client implementation MUST set it to the request's
83 | signer `OwnerID`.
84 |
85 |
86 | | Field | Type | Label | Description |
87 | | ----- | ---- | ----- | ----------- |
88 | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Valid user identifier in `OwnerID` format for which the balance is requested. Required field. |
89 |
90 |
91 |
92 |
93 | ### Message BalanceResponse
94 | BalanceResponse message
95 |
96 |
97 | | Field | Type | Label | Description |
98 | | ----- | ---- | ----- | ----------- |
99 | | body | [BalanceResponse.Body](#neo.fs.v2.accounting.BalanceResponse.Body) | | Body of the balance response message. |
100 | | 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. |
101 | | 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. |
102 |
103 |
104 |
105 |
106 | ### Message BalanceResponse.Body
107 | The amount of funds in GAS token for the `OwnerID`'s account requested.
108 | Balance is given in the `Decimal` format to avoid precision issues with rounding.
109 |
110 |
111 | | Field | Type | Label | Description |
112 | | ----- | ---- | ----- | ----------- |
113 | | balance | [Decimal](#neo.fs.v2.accounting.Decimal) | | Amount of funds in GAS token for the requested account. |
114 |
115 |
116 |
117 |
118 |
119 |
120 |
121 |
122 | Top
123 |
124 | ## accounting/types.proto
125 |
126 |
127 |
128 |
129 |
130 |
131 |
132 | ### Message Decimal
133 | Standard floating point data type can't be used in NeoFS due to inexactness
134 | of the result when doing lots of small number operations. To solve the lost
135 | precision issue, special `Decimal` format is used for monetary computations.
136 |
137 | Please see [The General Decimal Arithmetic
138 | Specification](http://speleotrove.com/decimal/) for detailed problem
139 | description.
140 |
141 |
142 | | Field | Type | Label | Description |
143 | | ----- | ---- | ----- | ----------- |
144 | | value | [int64](#int64) | | Number in the smallest Token fractions. |
145 | | precision | [uint32](#uint32) | | Precision value indicating how many smallest fractions can be in one integer. |
146 |
147 |
148 |
149 |
150 |
151 |
152 |
153 | ## Scalar Value Types
154 |
155 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
156 | | ----------- | ----- | -------- | --------- | ----------- |
157 | | double | | double | double | float |
158 | | float | | float | float | float |
159 | | 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 |
160 | | 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 |
161 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
162 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
163 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
164 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
165 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
166 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
167 | | sfixed32 | Always four bytes. | int32 | int | int |
168 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
169 | | bool | | bool | boolean | boolean |
170 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
171 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
172 |
173 |
--------------------------------------------------------------------------------
/proto-docs/acl.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [acl/types.proto](#acl/types.proto)
7 |
8 | - Messages
9 | - [BearerToken](#neo.fs.v2.acl.BearerToken)
10 | - [BearerToken.Body](#neo.fs.v2.acl.BearerToken.Body)
11 | - [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime)
12 | - [EACLRecord](#neo.fs.v2.acl.EACLRecord)
13 | - [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter)
14 | - [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target)
15 | - [EACLTable](#neo.fs.v2.acl.EACLTable)
16 |
17 |
18 | - [Scalar Value Types](#scalar-value-types)
19 |
20 |
21 |
22 |
23 | Top
24 |
25 | ## acl/types.proto
26 |
27 |
28 |
29 |
30 |
31 |
32 |
33 | ### Message BearerToken
34 | BearerToken allows to attach signed Extended ACL rules to the request in
35 | `RequestMetaHeader`. If container's Basic ACL rules allow, the attached rule
36 | set will be checked instead of one attached to the container itself. Just
37 | like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
38 | used in the similar use cases, like providing authorisation to externally
39 | authenticated party.
40 |
41 | BearerToken can be issued only by the container's owner and must be signed using
42 | the key associated with the container's `OwnerID`.
43 |
44 |
45 | | Field | Type | Label | Description |
46 | | ----- | ---- | ----- | ----------- |
47 | | body | [BearerToken.Body](#neo.fs.v2.acl.BearerToken.Body) | | Bearer Token body |
48 | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of BearerToken body |
49 |
50 |
51 |
52 |
53 | ### Message BearerToken.Body
54 | Bearer Token body structure contains Extended ACL table issued by the container
55 | owner with additional information preventing token abuse.
56 |
57 |
58 | | Field | Type | Label | Description |
59 | | ----- | ---- | ----- | ----------- |
60 | | eacl_table | [EACLTable](#neo.fs.v2.acl.EACLTable) | | Table of Extended ACL rules to use instead of the ones attached to the container. If it contains `container_id` field, bearer token is only valid for this specific container. Otherwise, any container of the same owner is allowed. |
61 | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | `OwnerID` defines to whom the token was issued. It must match the request originator's `OwnerID`. If empty, any token bearer will be accepted. |
62 | | lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters |
63 | | issuer | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Token issuer's user ID in NeoFS. It must equal to the related container's owner. |
64 |
65 |
66 |
67 |
68 | ### Message BearerToken.Body.TokenLifetime
69 | Lifetime parameters of the token. Field names taken from
70 | [rfc7519](https://tools.ietf.org/html/rfc7519).
71 |
72 |
73 | | Field | Type | Label | Description |
74 | | ----- | ---- | ----- | ----------- |
75 | | exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. |
76 | | nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. |
77 | | iat | [uint64](#uint64) | | Issued at Epoch |
78 |
79 |
80 |
81 |
82 | ### Message EACLRecord
83 | Describes a single eACL rule.
84 |
85 |
86 | | Field | Type | Label | Description |
87 | | ----- | ---- | ----- | ----------- |
88 | | operation | [Operation](#neo.fs.v2.acl.Operation) | | NeoFS request Verb to match |
89 | | action | [Action](#neo.fs.v2.acl.Action) | | Rule execution result. Either allows or denies access if filters match. |
90 | | filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | List of filters to match and see if rule is applicable |
91 | | targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | List of target subjects to apply ACL rule to |
92 |
93 |
94 |
95 |
96 | ### Message EACLRecord.Filter
97 | Filter to check particular properties of the request or the object.
98 |
99 | The `value` field must be empty if `match_type` is an unary operator
100 | (e.g. `NOT_PRESENT`). If `match_type` field is numeric (e.g. `NUM_GT`),
101 | the `value` field must be a base-10 integer.
102 |
103 | By default `key` field refers to the corresponding object's `Attribute`.
104 | Some Object's header fields can also be accessed by adding `$Object:`
105 | prefix to the name. For such attributes, field 'match_type' must not be
106 | 'NOT_PRESENT'. Here is the list of fields available via this prefix:
107 |
108 | * $Object:version \
109 | version
110 | * $Object:objectID \
111 | object_id
112 | * $Object:containerID \
113 | container_id
114 | * $Object:ownerID \
115 | owner_id
116 | * $Object:creationEpoch \
117 | creation_epoch
118 | * $Object:payloadLength \
119 | payload_length
120 | * $Object:payloadHash \
121 | payload_hash
122 | * $Object:objectType \
123 | object_type
124 | * $Object:homomorphicHash \
125 | homomorphic_hash
126 |
127 | Numeric `match_type` field can only be used with `$Object:creationEpoch`
128 | and `$Object:payloadLength` system attributes.
129 |
130 | Please note, that if request or response does not have object's headers of
131 | full object (Range, RangeHash, Search, Delete), it will not be possible to
132 | filter by object header fields or user attributes. From the well-known list
133 | only `$Object:objectID` and `$Object:containerID` will be available, as
134 | it's possible to take that information from the requested address.
135 |
136 |
137 | | Field | Type | Label | Description |
138 | | ----- | ---- | ----- | ----------- |
139 | | header_type | [HeaderType](#neo.fs.v2.acl.HeaderType) | | Define if Object or Request header will be used |
140 | | match_type | [MatchType](#neo.fs.v2.acl.MatchType) | | Match operation type |
141 | | key | [string](#string) | | Name of the Header to use |
142 | | value | [string](#string) | | Expected Header Value or pattern to match |
143 |
144 |
145 |
146 |
147 | ### Message EACLRecord.Target
148 | Target to apply ACL rule. Can be a subject's role class or a list of public
149 | keys to match.
150 |
151 |
152 | | Field | Type | Label | Description |
153 | | ----- | ---- | ----- | ----------- |
154 | | role | [Role](#neo.fs.v2.acl.Role) | | Target subject's role class |
155 | | keys | [bytes](#bytes) | repeated | List of 25-byte accounts to identify target subjects. 33-byte public keys are also supported, however, they are deprecated and script hashes should be derived from them. |
156 |
157 |
158 |
159 |
160 | ### Message EACLTable
161 | Extended ACL rules table. A list of ACL rules defined additionally to Basic
162 | ACL. Extended ACL rules can be attached to a container and can be updated
163 | or may be defined in `BearerToken` structure. Please see the corresponding
164 | NeoFS Technical Specification section for detailed description.
165 |
166 |
167 | | Field | Type | Label | Description |
168 | | ----- | ---- | ----- | ----------- |
169 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | eACL format version. Effectively, the version of API library used to create eACL Table. |
170 | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container that should use given access control rules |
171 | | records | [EACLRecord](#neo.fs.v2.acl.EACLRecord) | repeated | List of Extended ACL rules |
172 |
173 |
174 |
175 |
176 |
177 |
178 | ### Action
179 | Rule execution result action. Either allows or denies access if the rule's
180 | filters match.
181 |
182 | | Name | Number | Description |
183 | | ---- | ------ | ----------- |
184 | | ACTION_UNSPECIFIED | 0 | Unspecified action, default value |
185 | | ALLOW | 1 | Allow action |
186 | | DENY | 2 | Deny action |
187 |
188 |
189 |
190 |
191 |
192 | ### HeaderType
193 | Enumeration of possible sources of Headers to apply filters.
194 |
195 | | Name | Number | Description |
196 | | ---- | ------ | ----------- |
197 | | HEADER_UNSPECIFIED | 0 | Unspecified header, default value. |
198 | | REQUEST | 1 | Filter request headers |
199 | | OBJECT | 2 | Filter object headers |
200 | | SERVICE | 3 | Filter service headers. These are not processed by NeoFS nodes and exist for service use only. |
201 |
202 |
203 |
204 |
205 |
206 | ### MatchType
207 | MatchType is an enumeration of match types.
208 |
209 | | Name | Number | Description |
210 | | ---- | ------ | ----------- |
211 | | MATCH_TYPE_UNSPECIFIED | 0 | Unspecified match type, default value. |
212 | | STRING_EQUAL | 1 | Return true if strings are equal |
213 | | STRING_NOT_EQUAL | 2 | Return true if strings are different |
214 | | NOT_PRESENT | 3 | Absence of attribute |
215 | | NUM_GT | 4 | Numeric 'greater than' |
216 | | NUM_GE | 5 | Numeric 'greater or equal than' |
217 | | NUM_LT | 6 | Numeric 'less than' |
218 | | NUM_LE | 7 | Numeric 'less or equal than' |
219 |
220 |
221 |
222 |
223 |
224 | ### Operation
225 | Request's operation type to match if the rule is applicable to a particular
226 | request.
227 |
228 | | Name | Number | Description |
229 | | ---- | ------ | ----------- |
230 | | OPERATION_UNSPECIFIED | 0 | Unspecified operation, default value |
231 | | GET | 1 | Get |
232 | | HEAD | 2 | Head |
233 | | PUT | 3 | Put |
234 | | DELETE | 4 | Delete |
235 | | SEARCH | 5 | Search |
236 | | GETRANGE | 6 | GetRange |
237 | | GETRANGEHASH | 7 | GetRangeHash |
238 |
239 |
240 |
241 |
242 |
243 | ### Role
244 | Target role of the access control rule in access control list.
245 |
246 | | Name | Number | Description |
247 | | ---- | ------ | ----------- |
248 | | ROLE_UNSPECIFIED | 0 | Unspecified role, default value |
249 | | USER | 1 | User target rule is applied if sender is the owner of the container |
250 | | SYSTEM | 2 | System target rule is applied if sender is a storage node within the container or an inner ring node |
251 | | OTHERS | 3 | Others target rule is applied if sender is neither a user nor a system target |
252 |
253 |
254 |
255 |
256 |
257 |
258 | ## Scalar Value Types
259 |
260 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
261 | | ----------- | ----- | -------- | --------- | ----------- |
262 | | double | | double | double | float |
263 | | float | | float | float | float |
264 | | 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 |
265 | | 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 |
266 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
267 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
268 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
269 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
270 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
271 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
272 | | sfixed32 | Always four bytes. | int32 | int | int |
273 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
274 | | bool | | bool | boolean | boolean |
275 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
276 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
277 |
278 |
--------------------------------------------------------------------------------
/proto-docs/audit.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [audit/types.proto](#audit/types.proto)
7 |
8 | - Messages
9 | - [DataAuditResult](#neo.fs.v2.audit.DataAuditResult)
10 |
11 |
12 | - [Scalar Value Types](#scalar-value-types)
13 |
14 |
15 |
16 |
17 | Top
18 |
19 | ## audit/types.proto
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 | ### Message DataAuditResult
28 | DataAuditResult keeps record of conducted Data Audits. The detailed report is
29 | generated separately.
30 |
31 |
32 | | Field | Type | Label | Description |
33 | | ----- | ---- | ----- | ----------- |
34 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Data Audit Result format version. Effectively, the version of API library used to report DataAuditResult structure. |
35 | | audit_epoch | [fixed64](#fixed64) | | Epoch number when the Data Audit was conducted |
36 | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container under audit |
37 | | public_key | [bytes](#bytes) | | Public key of the auditing InnerRing node in a binary format |
38 | | complete | [bool](#bool) | | Shows if Data Audit process was complete in time or if it was cancelled |
39 | | requests | [uint32](#uint32) | | Number of request done at PoR stage |
40 | | retries | [uint32](#uint32) | | Number of retries done at PoR stage |
41 | | pass_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that passed audit PoR stage |
42 | | fail_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that failed audit PoR stage |
43 | | hit | [uint32](#uint32) | | Number of sampled objects under the audit placed in an optimal way according to the containers placement policy when checking PoP |
44 | | miss | [uint32](#uint32) | | Number of sampled objects under the audit placed in suboptimal way according to the containers placement policy, but still at a satisfactory level when checking PoP |
45 | | fail | [uint32](#uint32) | | Number of sampled objects under the audit stored inconsistently with the placement policy or not found at all when checking PoP |
46 | | pass_nodes | [bytes](#bytes) | repeated | List of storage node public keys that passed at least one PDP |
47 | | fail_nodes | [bytes](#bytes) | repeated | List of storage node public keys that failed at least one PDP |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 | ## Scalar Value Types
56 |
57 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
58 | | ----------- | ----- | -------- | --------- | ----------- |
59 | | double | | double | double | float |
60 | | float | | float | float | float |
61 | | 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 |
62 | | 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 |
63 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
64 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
65 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
66 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
67 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
68 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
69 | | sfixed32 | Always four bytes. | int32 | int | int |
70 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
71 | | bool | | bool | boolean | boolean |
72 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
73 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
74 |
75 |
--------------------------------------------------------------------------------
/proto-docs/bootstrap.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [bootstrap/types.proto](#bootstrap/types.proto)
7 |
8 | - Messages
9 | - [NodeInfo](#bootstrap.NodeInfo)
10 | - [NodeInfo.Attribute](#bootstrap.NodeInfo.Attribute)
11 |
12 |
13 | - [Scalar Value Types](#scalar-value-types)
14 |
15 |
16 |
17 |
18 | Top
19 |
20 | ## bootstrap/types.proto
21 |
22 |
23 |
24 |
25 |
26 |
27 |
28 | ### Message NodeInfo
29 | Groups the information about the NeoFS node.
30 |
31 |
32 | | Field | Type | Label | Description |
33 | | ----- | ---- | ----- | ----------- |
34 | | Address | [string](#string) | | Carries network address of the NeoFS node. |
35 | | PublicKey | [bytes](#bytes) | | Carries public key of the NeoFS node in a binary format. |
36 | | Attributes | [NodeInfo.Attribute](#bootstrap.NodeInfo.Attribute) | repeated | Carries list of the NeoFS node attributes in a string key-value format. |
37 | | state | [NodeInfo.State](#bootstrap.NodeInfo.State) | | Carries state of the NeoFS node. |
38 |
39 |
40 |
41 |
42 | ### Message NodeInfo.Attribute
43 | Groups attributes of the NeoFS node.
44 |
45 |
46 | | Field | Type | Label | Description |
47 | | ----- | ---- | ----- | ----------- |
48 | | Key | [string](#string) | | Carries string key to the node attribute. |
49 | | Value | [string](#string) | | Carries string value of the node attribute. |
50 |
51 |
52 |
53 |
54 |
55 |
56 | ### NodeInfo.State
57 | Represents the enumeration of various states of the NeoFS node.
58 |
59 | | Name | Number | Description |
60 | | ---- | ------ | ----------- |
61 | | Unknown | 0 | Undefined state. |
62 | | Online | 1 | Active state on the network. |
63 | | Offline | 2 | Network unavailable state. |
64 |
65 |
66 |
67 |
68 |
69 |
70 | ## Scalar Value Types
71 |
72 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
73 | | ----------- | ----- | -------- | --------- | ----------- |
74 | | double | | double | double | float |
75 | | float | | float | float | float |
76 | | 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 |
77 | | 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 |
78 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
79 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
80 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
81 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
82 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
83 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
84 | | sfixed32 | Always four bytes. | int32 | int | int |
85 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
86 | | bool | | bool | boolean | boolean |
87 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
88 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
89 |
90 |
--------------------------------------------------------------------------------
/proto-docs/link.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [link/types.proto](#link/types.proto)
7 |
8 | - Messages
9 | - [Link](#neo.fs.v2.link.Link)
10 | - [Link.MeasuredObject](#neo.fs.v2.link.Link.MeasuredObject)
11 |
12 |
13 | - [Scalar Value Types](#scalar-value-types)
14 |
15 |
16 |
17 |
18 | Top
19 |
20 | ## link/types.proto
21 |
22 |
23 |
24 |
25 |
26 |
27 |
28 | ### Message Link
29 | Link is a payload of helper objects that contain the full list of the split
30 | chain objects' IDs. It is created only after the whole split chain is known
31 | and signed. This object is the only object that refers to every "child object"
32 | ID. It is NOT required for the original object assembling. It MUST have ALL
33 | the "child objects" IDs. Child objects MUST be ordered according to the
34 | original payload split, meaning the first payload part holder MUST be placed
35 | at the first place in the corresponding link object. Sizes MUST NOT be omitted
36 | and MUST be a real object payload size in bytes.
37 |
38 |
39 | | Field | Type | Label | Description |
40 | | ----- | ---- | ----- | ----------- |
41 | | children | [Link.MeasuredObject](#neo.fs.v2.link.Link.MeasuredObject) | repeated | Full list of the "child" object descriptors. |
42 |
43 |
44 |
45 |
46 | ### Message Link.MeasuredObject
47 | Object ID with its object's payload size.
48 |
49 |
50 | | Field | Type | Label | Description |
51 | | ----- | ---- | ----- | ----------- |
52 | | id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object ID. |
53 | | size | [uint32](#uint32) | | Object size in bytes. |
54 |
55 |
56 |
57 |
58 |
59 |
60 |
61 | ## Scalar Value Types
62 |
63 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
64 | | ----------- | ----- | -------- | --------- | ----------- |
65 | | double | | double | double | float |
66 | | float | | float | float | float |
67 | | 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 |
68 | | 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 |
69 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
70 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
71 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
72 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
73 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
74 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
75 | | sfixed32 | Always four bytes. | int32 | int | int |
76 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
77 | | bool | | bool | boolean | boolean |
78 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
79 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
80 |
81 |
--------------------------------------------------------------------------------
/proto-docs/lock.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [lock/types.proto](#lock/types.proto)
7 |
8 | - Messages
9 | - [Lock](#neo.fs.v2.lock.Lock)
10 |
11 |
12 | - [Scalar Value Types](#scalar-value-types)
13 |
14 |
15 |
16 |
17 | Top
18 |
19 | ## lock/types.proto
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 | ### Message Lock
28 | Lock objects protects a list of objects from being deleted. The lifetime of a
29 | lock object is limited similar to regular objects in
30 | `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch.
31 | It is impossible to delete a lock object via ObjectService.Delete RPC call.
32 | Deleting a container containing lock/locked objects results in their removal
33 | too, regardless of their expiration epochs.
34 |
35 |
36 | | Field | Type | Label | Description |
37 | | ----- | ---- | ----- | ----------- |
38 | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to lock. Must not be empty or carry empty IDs. All members must be of the `REGULAR` type. |
39 |
40 |
41 |
42 |
43 |
44 |
45 |
46 | ## Scalar Value Types
47 |
48 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
49 | | ----------- | ----- | -------- | --------- | ----------- |
50 | | double | | double | double | float |
51 | | float | | float | float | float |
52 | | 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 |
53 | | 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 |
54 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
55 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
56 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
57 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
58 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
59 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
60 | | sfixed32 | Always four bytes. | int32 | int | int |
61 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
62 | | bool | | bool | boolean | boolean |
63 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
64 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
65 |
66 |
--------------------------------------------------------------------------------
/proto-docs/refs.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [refs/types.proto](#refs/types.proto)
7 |
8 | - Messages
9 | - [Address](#neo.fs.v2.refs.Address)
10 | - [Checksum](#neo.fs.v2.refs.Checksum)
11 | - [ContainerID](#neo.fs.v2.refs.ContainerID)
12 | - [ObjectID](#neo.fs.v2.refs.ObjectID)
13 | - [OwnerID](#neo.fs.v2.refs.OwnerID)
14 | - [Signature](#neo.fs.v2.refs.Signature)
15 | - [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979)
16 | - [SubnetID](#neo.fs.v2.refs.SubnetID)
17 | - [Version](#neo.fs.v2.refs.Version)
18 |
19 |
20 | - [Scalar Value Types](#scalar-value-types)
21 |
22 |
23 |
24 |
25 | Top
26 |
27 | ## refs/types.proto
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 | ### Message Address
36 | Objects in NeoFS are addressed by their ContainerID and ObjectID.
37 |
38 | String presentation of `Address` is a concatenation of string encoded
39 | `ContainerID` and `ObjectID` delimited by '/' character.
40 |
41 |
42 | | Field | Type | Label | Description |
43 | | ----- | ---- | ----- | ----------- |
44 | | container_id | [ContainerID](#neo.fs.v2.refs.ContainerID) | | Container identifier |
45 | | object_id | [ObjectID](#neo.fs.v2.refs.ObjectID) | | Object identifier |
46 |
47 |
48 |
49 |
50 | ### Message Checksum
51 | Checksum message.
52 | Depending on checksum algorithm type, the string presentation may vary:
53 |
54 | * TZ \
55 | Hex encoded string without `0x` prefix
56 | * SHA256 \
57 | Hex encoded string without `0x` prefix
58 |
59 |
60 | | Field | Type | Label | Description |
61 | | ----- | ---- | ----- | ----------- |
62 | | type | [ChecksumType](#neo.fs.v2.refs.ChecksumType) | | Checksum algorithm type |
63 | | sum | [bytes](#bytes) | | Checksum itself |
64 |
65 |
66 |
67 |
68 | ### Message ContainerID
69 | NeoFS container identifier. Container structures are immutable and
70 | content-addressed.
71 |
72 | `ContainerID` is a 32 byte long
73 | [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
74 | stable-marshalled container message. ID consisting of all zero bytes is
75 | reserved for undefined value and must not be specified as a field.
76 |
77 | String presentation is a
78 | [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
79 |
80 | JSON value will be data encoded as a string using standard base64
81 | encoding with paddings. Either
82 | [standard](https://tools.ietf.org/html/rfc4648#section-4) or
83 | [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
84 | with/without paddings are accepted.
85 |
86 |
87 | | Field | Type | Label | Description |
88 | | ----- | ---- | ----- | ----------- |
89 | | value | [bytes](#bytes) | | Container identifier in a binary format. |
90 |
91 |
92 |
93 |
94 | ### Message ObjectID
95 | NeoFS Object unique identifier. Objects are immutable and content-addressed.
96 | It means `ObjectID` will change if the `header` or the `payload` changes.
97 |
98 | `ObjectID` is a 32 byte long
99 | [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
100 | the object's `header` field, which, in it's turn, contains the hash of the object's
101 | payload. ID consisting of all zero bytes is reserved for undefined value and
102 | must not be specified as a field.
103 |
104 | String presentation is a
105 | [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
106 |
107 | JSON value will be data encoded as a string using standard base64
108 | encoding with paddings. Either
109 | [standard](https://tools.ietf.org/html/rfc4648#section-4) or
110 | [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
111 | with/without paddings are accepted.
112 |
113 |
114 | | Field | Type | Label | Description |
115 | | ----- | ---- | ----- | ----------- |
116 | | value | [bytes](#bytes) | | Object identifier in a binary format |
117 |
118 |
119 |
120 |
121 | ### Message OwnerID
122 | `OwnerID` is a derivative of a user's main public key. The transformation
123 | algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can
124 | be directly used as `OwnerID`.
125 |
126 | `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte
127 | followed by 20 bytes of ScrptHash and 4 bytes of checksum.
128 |
129 | String presentation is a [Base58
130 | Check](https://en.bitcoin.it/wiki/Base58Check_encoding) Encoded string.
131 |
132 | JSON value will be data encoded as a string using standard base64
133 | encoding with paddings. Either
134 | [standard](https://tools.ietf.org/html/rfc4648#section-4) or
135 | [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
136 | with/without paddings are accepted.
137 |
138 |
139 | | Field | Type | Label | Description |
140 | | ----- | ---- | ----- | ----------- |
141 | | value | [bytes](#bytes) | | Identifier of the container owner in a binary format |
142 |
143 |
144 |
145 |
146 | ### Message Signature
147 | Signature of something in NeoFS.
148 |
149 |
150 | | Field | Type | Label | Description |
151 | | ----- | ---- | ----- | ----------- |
152 | | key | [bytes](#bytes) | | Public key used for signing. For N3 `scheme`, the field represents a verification script. |
153 | | sign | [bytes](#bytes) | | Signature. For N3 `scheme`, the field represents an invocation script. |
154 | | scheme | [SignatureScheme](#neo.fs.v2.refs.SignatureScheme) | | Scheme contains digital signature scheme identifier |
155 |
156 |
157 |
158 |
159 | ### Message SignatureRFC6979
160 | RFC 6979 signature.
161 |
162 |
163 | | Field | Type | Label | Description |
164 | | ----- | ---- | ----- | ----------- |
165 | | key | [bytes](#bytes) | | Public key used for signing. For N3 auth scheme, the field represents a verification script. |
166 | | sign | [bytes](#bytes) | | Deterministic ECDSA with SHA-256 hashing. For N3 auth scheme, the field represents an invocation script. |
167 |
168 |
169 |
170 |
171 | ### Message SubnetID
172 | NeoFS subnetwork identifier.
173 |
174 | String representation of a value is base-10 integer.
175 |
176 | JSON representation is an object containing a single `value` number field.
177 |
178 | DEPRECATED. Kept for compatibility only.
179 |
180 |
181 | | Field | Type | Label | Description |
182 | | ----- | ---- | ----- | ----------- |
183 | | value | [fixed32](#fixed32) | | 4-byte integer subnetwork identifier. |
184 |
185 |
186 |
187 |
188 | ### Message Version
189 | API version used by a node.
190 |
191 | String presentation is a Semantic Versioning 2.0.0 compatible version string
192 | with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number.
193 |
194 |
195 | | Field | Type | Label | Description |
196 | | ----- | ---- | ----- | ----------- |
197 | | major | [uint32](#uint32) | | Major API version |
198 | | minor | [uint32](#uint32) | | Minor API version |
199 |
200 |
201 |
202 |
203 |
204 |
205 | ### ChecksumType
206 | Checksum algorithm type.
207 |
208 | | Name | Number | Description |
209 | | ---- | ------ | ----------- |
210 | | CHECKSUM_TYPE_UNSPECIFIED | 0 | Unknown. Not used |
211 | | TZ | 1 | Tillich-Zemor homomorphic hash function |
212 | | SHA256 | 2 | SHA-256 |
213 |
214 |
215 |
216 |
217 |
218 | ### SignatureScheme
219 | Signature scheme describes digital signing scheme used for (key, signature) pair.
220 |
221 | | Name | Number | Description |
222 | | ---- | ------ | ----------- |
223 | | ECDSA_SHA512 | 0 | ECDSA with SHA-512 hashing (FIPS 186-3) |
224 | | ECDSA_RFC6979_SHA256 | 1 | Deterministic ECDSA with SHA-256 hashing (RFC 6979) |
225 | | ECDSA_RFC6979_SHA256_WALLET_CONNECT | 2 | Deterministic ECDSA with SHA-256 hashing using WalletConnect API. Here the algorithm is the same, but the message format differs. |
226 | | N3 | 3 | Neo N3 witness. |
227 |
228 |
229 |
230 |
231 |
232 |
233 | ## Scalar Value Types
234 |
235 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
236 | | ----------- | ----- | -------- | --------- | ----------- |
237 | | double | | double | double | float |
238 | | float | | float | float | float |
239 | | 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 |
240 | | 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 |
241 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
242 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
243 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
244 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
245 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
246 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
247 | | sfixed32 | Always four bytes. | int32 | int | int |
248 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
249 | | bool | | bool | boolean | boolean |
250 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
251 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
252 |
253 |
--------------------------------------------------------------------------------
/proto-docs/reputation.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [reputation/service.proto](#reputation/service.proto)
7 | - Services
8 | - [ReputationService](#neo.fs.v2.reputation.ReputationService)
9 |
10 | - Messages
11 | - [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest)
12 | - [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body)
13 | - [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse)
14 | - [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body)
15 | - [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest)
16 | - [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body)
17 | - [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse)
18 | - [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body)
19 |
20 |
21 | - [reputation/types.proto](#reputation/types.proto)
22 |
23 | - Messages
24 | - [GlobalTrust](#neo.fs.v2.reputation.GlobalTrust)
25 | - [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body)
26 | - [PeerID](#neo.fs.v2.reputation.PeerID)
27 | - [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust)
28 | - [Trust](#neo.fs.v2.reputation.Trust)
29 |
30 |
31 | - [Scalar Value Types](#scalar-value-types)
32 |
33 |
34 |
35 |
36 | Top
37 |
38 | ## reputation/service.proto
39 |
40 |
41 |
42 |
43 |
44 |
45 | ### Service "neo.fs.v2.reputation.ReputationService"
46 | `ReputationService` provides mechanisms for exchanging trust values with
47 | other NeoFS nodes. Nodes rate each other's reputation based on how good they
48 | process requests and set a trust level based on that rating. The trust
49 | information is passed to the next nodes to check and aggregate unless the
50 | final result is recorded.
51 |
52 | ```
53 | rpc AnnounceLocalTrust(AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse);
54 | rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse);
55 |
56 | ```
57 |
58 | #### Method AnnounceLocalTrust
59 |
60 | Announce local client trust information to any node in NeoFS network.
61 |
62 | Statuses:
63 | - **OK** (0, SECTION_SUCCESS):
64 | local trust has been successfully announced;
65 | - Common failures (SECTION_FAILURE_COMMON).
66 |
67 | | Name | Input | Output |
68 | | ---- | ----- | ------ |
69 | | AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) |
70 | #### Method AnnounceIntermediateResult
71 |
72 | Announce the intermediate result of the iterative algorithm for
73 | calculating the global reputation of the node in NeoFS network.
74 |
75 | Statuses:
76 | - **OK** (0, SECTION_SUCCESS):
77 | intermediate trust estimation has been successfully announced;
78 | - Common failures (SECTION_FAILURE_COMMON).
79 |
80 | | Name | Input | Output |
81 | | ---- | ----- | ------ |
82 | | AnnounceIntermediateResult | [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) | [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) |
83 |
84 |
85 |
86 |
87 |
88 | ### Message AnnounceIntermediateResultRequest
89 | Announce intermediate global trust information.
90 |
91 |
92 | | Field | Type | Label | Description |
93 | | ----- | ---- | ----- | ----------- |
94 | | body | [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body) | | Body of the request message. |
95 | | 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. |
96 | | 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. |
97 |
98 |
99 |
100 |
101 | ### Message AnnounceIntermediateResultRequest.Body
102 | Announce intermediate global trust information.
103 |
104 |
105 | | Field | Type | Label | Description |
106 | | ----- | ---- | ----- | ----------- |
107 | | epoch | [uint64](#uint64) | | Iteration execution Epoch number |
108 | | iteration | [uint32](#uint32) | | Iteration sequence number |
109 | | trust | [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust) | | Current global trust value calculated at the specified iteration |
110 |
111 |
112 |
113 |
114 | ### Message AnnounceIntermediateResultResponse
115 | Intermediate global trust information announcement response.
116 |
117 |
118 | | Field | Type | Label | Description |
119 | | ----- | ---- | ----- | ----------- |
120 | | body | [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body) | | Body of the response message. |
121 | | 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. |
122 | | 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. |
123 |
124 |
125 |
126 |
127 | ### Message AnnounceIntermediateResultResponse.Body
128 | Response to the node's intermediate global trust information announcement has
129 | an empty body because the trust exchange operation is asynchronous. If
130 | Trust information does not pass sanity checks, it is silently ignored.
131 |
132 |
133 |
134 |
135 |
136 | ### Message AnnounceLocalTrustRequest
137 | Announce node's local trust information.
138 |
139 |
140 | | Field | Type | Label | Description |
141 | | ----- | ---- | ----- | ----------- |
142 | | body | [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body) | | Body of the request message. |
143 | | 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. |
144 | | 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. |
145 |
146 |
147 |
148 |
149 | ### Message AnnounceLocalTrustRequest.Body
150 | Announce node's local trust information.
151 |
152 |
153 | | Field | Type | Label | Description |
154 | | ----- | ---- | ----- | ----------- |
155 | | epoch | [uint64](#uint64) | | Trust assessment Epoch number |
156 | | trusts | [Trust](#neo.fs.v2.reputation.Trust) | repeated | List of normalized local trust values to other NeoFS nodes. The value is calculated according to EigenTrust++ algorithm and must be a floating point number in [0;1] range. |
157 |
158 |
159 |
160 |
161 | ### Message AnnounceLocalTrustResponse
162 | Node's local trust information announcement response.
163 |
164 |
165 | | Field | Type | Label | Description |
166 | | ----- | ---- | ----- | ----------- |
167 | | body | [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body) | | Body of the response message. |
168 | | 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. |
169 | | 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. |
170 |
171 |
172 |
173 |
174 | ### Message AnnounceLocalTrustResponse.Body
175 | Response to the node's local trust information announcement has an empty body
176 | because the trust exchange operation is asynchronous. If Trust information
177 | does not pass sanity checks, it is silently ignored.
178 |
179 |
180 |
181 |
182 |
183 |
184 |
185 |
186 |
187 | Top
188 |
189 | ## reputation/types.proto
190 |
191 |
192 |
193 |
194 |
195 |
196 |
197 | ### Message GlobalTrust
198 | Global trust level to NeoFS node.
199 |
200 |
201 | | Field | Type | Label | Description |
202 | | ----- | ---- | ----- | ----------- |
203 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Message format version. Effectively, the version of API library used to create the message. |
204 | | body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body |
205 | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. |
206 |
207 |
208 |
209 |
210 | ### Message GlobalTrust.Body
211 | Message body structure.
212 |
213 |
214 | | Field | Type | Label | Description |
215 | | ----- | ---- | ----- | ----------- |
216 | | manager | [PeerID](#neo.fs.v2.reputation.PeerID) | | Node manager ID |
217 | | trust | [Trust](#neo.fs.v2.reputation.Trust) | | Global trust level |
218 |
219 |
220 |
221 |
222 | ### Message PeerID
223 | NeoFS unique peer identifier is a 33 byte long compressed public key of the
224 | node, the same as the one stored in the network map.
225 |
226 | String presentation is a
227 | [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
228 |
229 | JSON value will be data encoded as a string using standard base64
230 | encoding with paddings. Either
231 | [standard](https://tools.ietf.org/html/rfc4648#section-4) or
232 | [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
233 | with/without paddings are accepted.
234 |
235 |
236 | | Field | Type | Label | Description |
237 | | ----- | ---- | ----- | ----------- |
238 | | public_key | [bytes](#bytes) | | Peer node's public key |
239 |
240 |
241 |
242 |
243 | ### Message PeerToPeerTrust
244 | Trust level of a peer to a peer.
245 |
246 |
247 | | Field | Type | Label | Description |
248 | | ----- | ---- | ----- | ----------- |
249 | | trusting_peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusting peer |
250 | | trust | [Trust](#neo.fs.v2.reputation.Trust) | | Trust level |
251 |
252 |
253 |
254 |
255 | ### Message Trust
256 | Trust level to a NeoFS network peer.
257 |
258 |
259 | | Field | Type | Label | Description |
260 | | ----- | ---- | ----- | ----------- |
261 | | peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusted peer |
262 | | value | [double](#double) | | Trust level in [0:1] range |
263 |
264 |
265 |
266 |
267 |
268 |
269 |
270 | ## Scalar Value Types
271 |
272 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
273 | | ----------- | ----- | -------- | --------- | ----------- |
274 | | double | | double | double | float |
275 | | float | | float | float | float |
276 | | 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 |
277 | | 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 |
278 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
279 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
280 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
281 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
282 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
283 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
284 | | sfixed32 | Always four bytes. | int32 | int | int |
285 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
286 | | bool | | bool | boolean | boolean |
287 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
288 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
289 |
290 |
--------------------------------------------------------------------------------
/proto-docs/service.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [service/types.proto](#service/types.proto)
7 |
8 | - Messages
9 | - [RequestMetaHeader](#neo.fs.v2.service.RequestMetaHeader)
10 | - [RequestVerificationHeader](#neo.fs.v2.service.RequestVerificationHeader)
11 | - [ResponseMetaHeader](#neo.fs.v2.service.ResponseMetaHeader)
12 | - [ResponseVerificationHeader](#neo.fs.v2.service.ResponseVerificationHeader)
13 | - [XHeader](#neo.fs.v2.service.XHeader)
14 |
15 |
16 | - [Scalar Value Types](#scalar-value-types)
17 |
18 |
19 |
20 |
21 | Top
22 |
23 | ## service/types.proto
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 | ### Message RequestMetaHeader
32 | Information about the request
33 |
34 |
35 | | Field | Type | Label | Description |
36 | | ----- | ---- | ----- | ----------- |
37 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Client API version. |
38 | | epoch | [uint64](#uint64) | | Client local epoch number. Set to 0 if unknown. |
39 | | ttl | [uint32](#uint32) | | Maximum number of nodes in the request route. |
40 | | x_headers | [XHeader](#neo.fs.v2.service.XHeader) | repeated | Request X-Headers. |
41 | | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Token is a token of the session within which the request is sent |
42 | | bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | Bearer is a Bearer token of the request |
43 | | origin | [RequestMetaHeader](#neo.fs.v2.service.RequestMetaHeader) | | RequestMetaHeader of the origin request. |
44 |
45 |
46 |
47 |
48 | ### Message RequestVerificationHeader
49 | Verification info for request signed by all intermediate nodes
50 |
51 |
52 | | Field | Type | Label | Description |
53 | | ----- | ---- | ----- | ----------- |
54 | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by request initiator. |
55 | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by any intermediate node |
56 | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops |
57 | | origin | [RequestVerificationHeader](#neo.fs.v2.service.RequestVerificationHeader) | | Chain of previous hops signatures |
58 |
59 |
60 |
61 |
62 | ### Message ResponseMetaHeader
63 | Information about the response
64 |
65 |
66 | | Field | Type | Label | Description |
67 | | ----- | ---- | ----- | ----------- |
68 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Server API version. |
69 | | epoch | [uint64](#uint64) | | Server local epoch number. |
70 | | ttl | [uint32](#uint32) | | Maximum number of nodes in the response route. |
71 | | x_headers | [XHeader](#neo.fs.v2.service.XHeader) | repeated | Response X-Headers. |
72 | | origin | [ResponseMetaHeader](#neo.fs.v2.service.ResponseMetaHeader) | | Carries response meta header of the origin response. |
73 |
74 |
75 |
76 |
77 | ### Message ResponseVerificationHeader
78 | Verification info for response signed by all intermediate nodes
79 |
80 |
81 | | Field | Type | Label | Description |
82 | | ----- | ---- | ----- | ----------- |
83 | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by answering node. |
84 | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by any intermediate node |
85 | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops |
86 | | origin | [ResponseVerificationHeader](#neo.fs.v2.service.ResponseVerificationHeader) | | Chain of previous hops signatures |
87 |
88 |
89 |
90 |
91 | ### Message XHeader
92 | Extended headers for Request/Response
93 |
94 |
95 | | Field | Type | Label | Description |
96 | | ----- | ---- | ----- | ----------- |
97 | | key | [string](#string) | | Key of the X-Header. |
98 | | value | [string](#string) | | Value of the X-Header. |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 | ## Scalar Value Types
107 |
108 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
109 | | ----------- | ----- | -------- | --------- | ----------- |
110 | | double | | double | double | float |
111 | | float | | float | float | float |
112 | | 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 |
113 | | 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 |
114 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
115 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
116 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
117 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
118 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
119 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
120 | | sfixed32 | Always four bytes. | int32 | int | int |
121 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
122 | | bool | | bool | boolean | boolean |
123 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
124 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
125 |
126 |
--------------------------------------------------------------------------------
/proto-docs/session.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [session/service.proto](#session/service.proto)
7 | - Services
8 | - [SessionService](#neo.fs.v2.session.SessionService)
9 |
10 | - Messages
11 | - [CreateRequest](#neo.fs.v2.session.CreateRequest)
12 | - [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body)
13 | - [CreateResponse](#neo.fs.v2.session.CreateResponse)
14 | - [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body)
15 |
16 |
17 | - [session/types.proto](#session/types.proto)
18 |
19 | - Messages
20 | - [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext)
21 | - [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext)
22 | - [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target)
23 | - [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader)
24 | - [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader)
25 | - [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader)
26 | - [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader)
27 | - [SessionToken](#neo.fs.v2.session.SessionToken)
28 | - [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body)
29 | - [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime)
30 | - [XHeader](#neo.fs.v2.session.XHeader)
31 |
32 |
33 | - [Scalar Value Types](#scalar-value-types)
34 |
35 |
36 |
37 |
38 | Top
39 |
40 | ## session/service.proto
41 |
42 |
43 |
44 |
45 |
46 |
47 | ### Service "neo.fs.v2.session.SessionService"
48 | `SessionService` allows to establish a temporary trust relationship between
49 | two peer nodes and generate a `SessionToken` as the proof of trust to be
50 | attached in requests for further verification. Please see corresponding
51 | section of NeoFS Technical Specification for details.
52 |
53 | ```
54 | rpc Create(CreateRequest) returns (CreateResponse);
55 |
56 | ```
57 |
58 | #### Method Create
59 |
60 | Open a new session between two peers.
61 |
62 | Statuses:
63 | - **OK** (0, SECTION_SUCCESS):
64 | session has been successfully opened;
65 | - Common failures (SECTION_FAILURE_COMMON).
66 |
67 | | Name | Input | Output |
68 | | ---- | ----- | ------ |
69 | | Create | [CreateRequest](#neo.fs.v2.session.CreateRequest) | [CreateResponse](#neo.fs.v2.session.CreateResponse) |
70 |
71 |
72 |
73 |
74 |
75 | ### Message CreateRequest
76 | Information necessary for opening a session.
77 |
78 |
79 | | Field | Type | Label | Description |
80 | | ----- | ---- | ----- | ----------- |
81 | | body | [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) | | Body of a create session token request message. |
82 | | meta_header | [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. |
83 | | verify_header | [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. |
84 |
85 |
86 |
87 |
88 | ### Message CreateRequest.Body
89 | Session creation request body
90 |
91 |
92 | | Field | Type | Label | Description |
93 | | ----- | ---- | ----- | ----------- |
94 | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Session initiating user's or node's key derived `OwnerID` |
95 | | expiration | [uint64](#uint64) | | Session expiration epoch, the last epoch when session is valid. |
96 |
97 |
98 |
99 |
100 | ### Message CreateResponse
101 | Information about the opened session.
102 |
103 |
104 | | Field | Type | Label | Description |
105 | | ----- | ---- | ----- | ----------- |
106 | | body | [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body) | | Body of create session token response message. |
107 | | meta_header | [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. |
108 | | verify_header | [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. |
109 |
110 |
111 |
112 |
113 | ### Message CreateResponse.Body
114 | Session creation response body
115 |
116 |
117 | | Field | Type | Label | Description |
118 | | ----- | ---- | ----- | ----------- |
119 | | id | [bytes](#bytes) | | Identifier of a newly created session |
120 | | session_key | [bytes](#bytes) | | Public key used for session |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
128 |
129 | Top
130 |
131 | ## session/types.proto
132 |
133 |
134 |
135 |
136 |
137 |
138 |
139 | ### Message ContainerSessionContext
140 | Context information for Session Tokens related to ContainerService requests.
141 |
142 |
143 | | Field | Type | Label | Description |
144 | | ----- | ---- | ----- | ----------- |
145 | | verb | [ContainerSessionContext.Verb](#neo.fs.v2.session.ContainerSessionContext.Verb) | | Type of request for which the token is issued |
146 | | wildcard | [bool](#bool) | | Spreads the action to all owner containers. If set, container_id field is ignored. |
147 | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Particular container to which the action applies. Ignored if wildcard flag is set. |
148 |
149 |
150 |
151 |
152 | ### Message ObjectSessionContext
153 | Context information for Session Tokens related to ObjectService requests
154 |
155 |
156 | | Field | Type | Label | Description |
157 | | ----- | ---- | ----- | ----------- |
158 | | verb | [ObjectSessionContext.Verb](#neo.fs.v2.session.ObjectSessionContext.Verb) | | Type of request for which the token is issued |
159 | | target | [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) | | Object session target. MUST be correctly formed and set. If `objects` field is not empty, then the session applies only to these elements, otherwise, to all objects from the specified container. |
160 |
161 |
162 |
163 |
164 | ### Message ObjectSessionContext.Target
165 | Carries objects involved in the object session.
166 |
167 |
168 | | Field | Type | Label | Description |
169 | | ----- | ---- | ----- | ----------- |
170 | | container | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Indicates which container the session is spread to. Field MUST be set and correct. |
171 | | objects | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Indicates which objects the session is spread to. Objects are expected to be stored in the NeoFS container referenced by `container` field. Each element MUST have correct format. |
172 |
173 |
174 |
175 |
176 | ### Message RequestMetaHeader
177 | Meta information attached to the request. When forwarded between peers,
178 | request meta headers are folded in matryoshka style.
179 |
180 |
181 | | Field | Type | Label | Description |
182 | | ----- | ---- | ----- | ----------- |
183 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Peer's API version used |
184 | | epoch | [uint64](#uint64) | | Peer's local epoch number. Set to 0 if unknown. |
185 | | ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route |
186 | | x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Request X-Headers |
187 | | session_token | [SessionToken](#neo.fs.v2.session.SessionToken) | | Session token within which the request is sent |
188 | | bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | `BearerToken` with eACL overrides for the request |
189 | | origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | `RequestMetaHeader` of the origin request |
190 | | magic_number | [uint64](#uint64) | | NeoFS network magic. Must match the value for the network that the server belongs to. |
191 |
192 |
193 |
194 |
195 | ### Message RequestVerificationHeader
196 | Verification info for the request signed by all intermediate nodes.
197 |
198 |
199 | | Field | Type | Label | Description |
200 | | ----- | ---- | ----- | ----------- |
201 | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by the request initiator. |
202 | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by each intermediate node |
203 | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops |
204 | | origin | [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Chain of previous hops signatures |
205 |
206 |
207 |
208 |
209 | ### Message ResponseMetaHeader
210 | Information about the response
211 |
212 |
213 | | Field | Type | Label | Description |
214 | | ----- | ---- | ----- | ----------- |
215 | | version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Peer's API version used |
216 | | epoch | [uint64](#uint64) | | Peer's local epoch number |
217 | | ttl | [uint32](#uint32) | | Maximum number of intermediate nodes in the request route |
218 | | x_headers | [XHeader](#neo.fs.v2.session.XHeader) | repeated | Response X-Headers |
219 | | origin | [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | `ResponseMetaHeader` of the origin request |
220 | | status | [neo.fs.v2.status.Status](#neo.fs.v2.status.Status) | | Status return |
221 |
222 |
223 |
224 |
225 | ### Message ResponseVerificationHeader
226 | Verification info for the response signed by all intermediate nodes
227 |
228 |
229 | | Field | Type | Label | Description |
230 | | ----- | ---- | ----- | ----------- |
231 | | body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by an answering node. |
232 | | meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by each intermediate node |
233 | | origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of previous hops |
234 | | origin | [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Chain of previous hops signatures |
235 |
236 |
237 |
238 |
239 | ### Message SessionToken
240 | NeoFS Session Token.
241 |
242 |
243 | | Field | Type | Label | Description |
244 | | ----- | ---- | ----- | ----------- |
245 | | body | [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) | | Session Token contains the proof of trust between peers to be attached in requests for further verification. Please see corresponding section of NeoFS Technical Specification for details. |
246 | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of `SessionToken` information |
247 |
248 |
249 |
250 |
251 | ### Message SessionToken.Body
252 | Session Token body
253 |
254 |
255 | | Field | Type | Label | Description |
256 | | ----- | ---- | ----- | ----------- |
257 | | id | [bytes](#bytes) | | Token identifier is a valid UUIDv4 in binary form |
258 | | owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the session initiator |
259 | | lifetime | [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) | | Lifetime of the session |
260 | | session_key | [bytes](#bytes) | | Public key used in session |
261 | | object | [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) | | ObjectService session context |
262 | | container | [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) | | ContainerService session context |
263 |
264 |
265 |
266 |
267 | ### Message SessionToken.Body.TokenLifetime
268 | Lifetime parameters of the token. Field names taken from rfc7519.
269 |
270 |
271 | | Field | Type | Label | Description |
272 | | ----- | ---- | ----- | ----------- |
273 | | exp | [uint64](#uint64) | | Expiration epoch, the last epoch when token is valid. |
274 | | nbf | [uint64](#uint64) | | Not valid before epoch, the first epoch when token is valid. |
275 | | iat | [uint64](#uint64) | | Issued at Epoch |
276 |
277 |
278 |
279 |
280 | ### Message XHeader
281 | Extended headers for Request/Response. They may contain any user-defined headers
282 | to be interpreted on application level.
283 |
284 | Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
285 | Responses with duplicated header names or headers with empty values will be
286 | considered invalid.
287 |
288 | There are some "well-known" headers starting with `__NEOFS__` prefix that
289 | affect system behaviour:
290 |
291 | * __NEOFS__NETMAP_EPOCH \
292 | Netmap epoch to use for object placement calculation. The `value` is string
293 | encoded `uint64` in decimal presentation. If set to '0' or not set, the
294 | current epoch only will be used. DEPRECATED: header ignored by servers.
295 | * __NEOFS__NETMAP_LOOKUP_DEPTH \
296 | If object can't be found using current epoch's netmap, this header limits
297 | how many past epochs the node can look up through. The `value` is string
298 | encoded `uint64` in decimal presentation. If set to '0' or not set, only the
299 | current epoch will be used. DEPRECATED: header ignored by servers.
300 |
301 |
302 | | Field | Type | Label | Description |
303 | | ----- | ---- | ----- | ----------- |
304 | | key | [string](#string) | | Key of the X-Header |
305 | | value | [string](#string) | | Value of the X-Header |
306 |
307 |
308 |
309 |
310 |
311 |
312 | ### ContainerSessionContext.Verb
313 | Container request verbs
314 |
315 | | Name | Number | Description |
316 | | ---- | ------ | ----------- |
317 | | VERB_UNSPECIFIED | 0 | Unknown verb |
318 | | PUT | 1 | Refers to container.Put RPC call |
319 | | DELETE | 2 | Refers to container.Delete RPC call |
320 | | SETEACL | 3 | Refers to container.SetExtendedACL RPC call |
321 |
322 |
323 |
324 |
325 |
326 | ### ObjectSessionContext.Verb
327 | Object request verbs
328 |
329 | | Name | Number | Description |
330 | | ---- | ------ | ----------- |
331 | | VERB_UNSPECIFIED | 0 | Unknown verb |
332 | | PUT | 1 | Refers to object.Put RPC call |
333 | | GET | 2 | Refers to object.Get RPC call |
334 | | HEAD | 3 | Refers to object.Head RPC call |
335 | | SEARCH | 4 | Refers to object.Search RPC call |
336 | | DELETE | 5 | Refers to object.Delete RPC call |
337 | | RANGE | 6 | Refers to object.GetRange RPC call |
338 | | RANGEHASH | 7 | Refers to object.GetRangeHash RPC call |
339 |
340 |
341 |
342 |
343 |
344 |
345 | ## Scalar Value Types
346 |
347 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
348 | | ----------- | ----- | -------- | --------- | ----------- |
349 | | double | | double | double | float |
350 | | float | | float | float | float |
351 | | 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 |
352 | | 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 |
353 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
354 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
355 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
356 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
357 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
358 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
359 | | sfixed32 | Always four bytes. | int32 | int | int |
360 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
361 | | bool | | bool | boolean | boolean |
362 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
363 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
364 |
365 |
--------------------------------------------------------------------------------
/proto-docs/status.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [status/types.proto](#status/types.proto)
7 |
8 | - Messages
9 | - [Status](#neo.fs.v2.status.Status)
10 | - [Status.Detail](#neo.fs.v2.status.Status.Detail)
11 |
12 |
13 | - [Scalar Value Types](#scalar-value-types)
14 |
15 |
16 |
17 |
18 | Top
19 |
20 | ## status/types.proto
21 |
22 |
23 |
24 |
25 |
26 |
27 |
28 | ### Message Status
29 | Declares the general format of the status returns of the NeoFS RPC protocol.
30 | Status is present in all response messages. Each RPC of NeoFS protocol
31 | describes the possible outcomes and details of the operation.
32 |
33 | Each status is assigned a one-to-one numeric code. Any unique result of an
34 | operation in NeoFS is unambiguously associated with the code value.
35 |
36 | Numerical set of codes is split into 1024-element sections. An enumeration
37 | is defined for each section. Values can be referred to in the following ways:
38 |
39 | * numerical value ranging from 0 to 4,294,967,295 (global code);
40 |
41 | * values from enumeration (local code). The formula for the ratio of the
42 | local code (`L`) of a defined section (`S`) to the global one (`G`):
43 | `G = 1024 * S + L`.
44 |
45 | All outcomes are divided into successful and failed, which corresponds
46 | to the success or failure of the operation. The definition of success
47 | follows the semantics of RPC and the description of its purpose.
48 | The server must not attach code that is the opposite of the outcome type.
49 |
50 | See the set of return codes in the description for calls.
51 |
52 | Each status can carry a developer-facing error message. It should be a human
53 | readable text in English. The server should not transmit (and the client
54 | should not expect) useful information in the message. Field `details`
55 | should make the return more detailed.
56 |
57 |
58 | | Field | Type | Label | Description |
59 | | ----- | ---- | ----- | ----------- |
60 | | code | [uint32](#uint32) | | The status code |
61 | | message | [string](#string) | | Developer-facing error message |
62 | | details | [Status.Detail](#neo.fs.v2.status.Status.Detail) | repeated | Data detailing the outcome of the operation. Must be unique by ID. |
63 |
64 |
65 |
66 |
67 | ### Message Status.Detail
68 | Return detail. It contains additional information that can be used to
69 | analyze the response. Each code defines a set of details that can be
70 | attached to a status. Client should not handle details that are not
71 | covered by the code.
72 |
73 |
74 | | Field | Type | Label | Description |
75 | | ----- | ---- | ----- | ----------- |
76 | | id | [uint32](#uint32) | | Detail ID. The identifier is required to determine the binary format of the detail and how to decode it. |
77 | | value | [bytes](#bytes) | | Binary status detail. Must follow the format associated with ID. The possibility of missing a value must be explicitly allowed. |
78 |
79 |
80 |
81 |
82 |
83 |
84 | ### CommonFail
85 | Section of failed statuses independent of the operation.
86 |
87 | | Name | Number | Description |
88 | | ---- | ------ | ----------- |
89 | | INTERNAL | 0 | [**1024**] Internal server error, default failure. Not detailed. If the server cannot match failed outcome to the code, it should use this code. |
90 | | WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the NeoFS network. Details: - [**0**] Magic number of the served NeoFS network (big-endian 64-bit unsigned integer). |
91 | | SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. |
92 | | NODE_UNDER_MAINTENANCE | 3 | [**1027**] Node is under maintenance. |
93 |
94 |
95 |
96 |
97 |
98 | ### Container
99 | Section of statuses for container-related operations.
100 |
101 | | Name | Number | Description |
102 | | ---- | ------ | ----------- |
103 | | CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. |
104 | | EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. |
105 |
106 |
107 |
108 |
109 |
110 | ### Object
111 | Section of statuses for object-related operations.
112 |
113 | | Name | Number | Description |
114 | | ---- | ------ | ----------- |
115 | | ACCESS_DENIED | 0 | [**2048**] Access denied by ACL. Details: - [**0**] Human-readable description (UTF-8 encoded string). |
116 | | OBJECT_NOT_FOUND | 1 | [**2049**] Object not found. |
117 | | LOCKED | 2 | [**2050**] Operation rejected by the object lock. |
118 | | LOCK_NON_REGULAR_OBJECT | 3 | [**2051**] Locking an object with a non-REGULAR type rejected. |
119 | | OBJECT_ALREADY_REMOVED | 4 | [**2052**] Object has been marked deleted. |
120 | | OUT_OF_RANGE | 5 | [**2053**] Invalid range has been requested for an object. |
121 |
122 |
123 |
124 |
125 |
126 | ### Section
127 | Section identifiers.
128 |
129 | | Name | Number | Description |
130 | | ---- | ------ | ----------- |
131 | | SECTION_SUCCESS | 0 | Successful return codes. |
132 | | SECTION_FAILURE_COMMON | 1 | Failure codes regardless of the operation. |
133 | | SECTION_OBJECT | 2 | Object service-specific errors. |
134 | | SECTION_CONTAINER | 3 | Container service-specific errors. |
135 | | SECTION_SESSION | 4 | Session service-specific errors. |
136 |
137 |
138 |
139 |
140 |
141 | ### Session
142 | Section of statuses for session-related operations.
143 |
144 | | Name | Number | Description |
145 | | ---- | ------ | ----------- |
146 | | TOKEN_NOT_FOUND | 0 | [**4096**] Token not found. |
147 | | TOKEN_EXPIRED | 1 | [**4097**] Token has expired. |
148 |
149 |
150 |
151 |
152 |
153 | ### Success
154 | Section of NeoFS successful return codes.
155 |
156 | | Name | Number | Description |
157 | | ---- | ------ | ----------- |
158 | | OK | 0 | [**0**] Default success. Not detailed. If the server cannot match successful outcome to the code, it should use this code. |
159 |
160 |
161 |
162 |
163 |
164 |
165 | ## Scalar Value Types
166 |
167 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
168 | | ----------- | ----- | -------- | --------- | ----------- |
169 | | double | | double | double | float |
170 | | float | | float | float | float |
171 | | 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 |
172 | | 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 |
173 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
174 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
175 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
176 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
177 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
178 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
179 | | sfixed32 | Always four bytes. | int32 | int | int |
180 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
181 | | bool | | bool | boolean | boolean |
182 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
183 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
184 |
185 |
--------------------------------------------------------------------------------
/proto-docs/storagegroup.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [storagegroup/types.proto](#storagegroup/types.proto)
7 |
8 | - Messages
9 | - [StorageGroup](#neo.fs.v2.storagegroup.StorageGroup)
10 |
11 |
12 | - [Scalar Value Types](#scalar-value-types)
13 |
14 |
15 |
16 |
17 | Top
18 |
19 | ## storagegroup/types.proto
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 | ### Message StorageGroup
28 | StorageGroup keeps verification information for Data Audit sessions. Objects
29 | that require paid storage guarantees are gathered in `StorageGroups` with
30 | additional information used for the proof of storage. `StorageGroup` only
31 | contains objects from the same container.
32 |
33 | Being an object payload, StorageGroup may have expiration Epoch set with
34 | `__NEOFS__EXPIRATION_EPOCH` well-known attribute. When expired, StorageGroup
35 | will be ignored by InnerRing nodes during Data Audit cycles and will be
36 | deleted by Storage Nodes.
37 |
38 |
39 | | Field | Type | Label | Description |
40 | | ----- | ---- | ----- | ----------- |
41 | | validation_data_size | [uint64](#uint64) | | Total size of the payloads of objects in the storage group |
42 | | validation_hash | [neo.fs.v2.refs.Checksum](#neo.fs.v2.refs.Checksum) | | Homomorphic hash from the concatenation of the payloads of the storage group members. The order of concatenation is the same as the order of the members in the `members` field. |
43 | | expiration_epoch | [uint64](#uint64) | | DEPRECATED. Last NeoFS epoch number of the storage group lifetime |
44 | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects. Members MUST be unique |
45 |
46 |
47 |
48 |
49 |
50 |
51 |
52 | ## Scalar Value Types
53 |
54 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
55 | | ----------- | ----- | -------- | --------- | ----------- |
56 | | double | | double | double | float |
57 | | float | | float | float | float |
58 | | 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 |
59 | | 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 |
60 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
61 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
62 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
63 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
64 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
65 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
66 | | sfixed32 | Always four bytes. | int32 | int | int |
67 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
68 | | bool | | bool | boolean | boolean |
69 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
70 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
71 |
72 |
--------------------------------------------------------------------------------
/proto-docs/subnet.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [subnet/types.proto](#subnet/types.proto)
7 |
8 | - Messages
9 | - [SubnetInfo](#neo.fs.v2.subnet.SubnetInfo)
10 |
11 |
12 | - [Scalar Value Types](#scalar-value-types)
13 |
14 |
15 |
16 |
17 | Top
18 |
19 | ## subnet/types.proto
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 | ### Message SubnetInfo
28 | NeoFS subnetwork description
29 |
30 | DEPRECATED. Ignored and kept for compatibility only.
31 |
32 |
33 | | Field | Type | Label | Description |
34 | | ----- | ---- | ----- | ----------- |
35 | | id | [neo.fs.v2.refs.SubnetID](#neo.fs.v2.refs.SubnetID) | | Unique subnet identifier. Missing ID is equivalent to zero (default subnetwork) ID. |
36 | | owner | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the subnetwork owner |
37 |
38 |
39 |
40 |
41 |
42 |
43 |
44 | ## Scalar Value Types
45 |
46 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
47 | | ----------- | ----- | -------- | --------- | ----------- |
48 | | double | | double | double | float |
49 | | float | | float | float | float |
50 | | 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 |
51 | | 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 |
52 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
53 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
54 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
55 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
56 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
57 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
58 | | sfixed32 | Always four bytes. | int32 | int | int |
59 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
60 | | bool | | bool | boolean | boolean |
61 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
62 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
63 |
64 |
--------------------------------------------------------------------------------
/proto-docs/tombstone.md:
--------------------------------------------------------------------------------
1 | # Protocol Documentation
2 |
3 |
4 | ## Table of Contents
5 |
6 | - [tombstone/types.proto](#tombstone/types.proto)
7 |
8 | - Messages
9 | - [Tombstone](#neo.fs.v2.tombstone.Tombstone)
10 |
11 |
12 | - [Scalar Value Types](#scalar-value-types)
13 |
14 |
15 |
16 |
17 | Top
18 |
19 | ## tombstone/types.proto
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 | ### Message Tombstone
28 | Tombstone keeps record of deleted objects for a few epochs until they are
29 | purged from the NeoFS network. It is impossible to delete a tombstone object
30 | via ObjectService.Delete RPC call.
31 |
32 |
33 | | Field | Type | Label | Description |
34 | | ----- | ---- | ----- | ----------- |
35 | | expiration_epoch | [uint64](#uint64) | | Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current NeoFS network settings. DEPRECATED. Field ignored by servers, set corresponding object attribute `__NEOFS__EXPIRATION_EPOCH` only. |
36 | | split_id | [bytes](#bytes) | | 16 byte UUID used to identify the split object hierarchy parts. Must be unique inside a container. All objects participating in the split must have the same `split_id` value. DEPRECATED. The field is ignored by servers. |
37 | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. IDs should be either: 1. Root object IDs (objects that are not split OR parent objects) 2. Children IDs for unfinished objects that does not have LINK objects (garbage collecting). |
38 |
39 |
40 |
41 |
42 |
43 |
44 |
45 | ## Scalar Value Types
46 |
47 | | .proto Type | Notes | C++ Type | Java Type | Python Type |
48 | | ----------- | ----- | -------- | --------- | ----------- |
49 | | double | | double | double | float |
50 | | float | | float | float | float |
51 | | 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 |
52 | | 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 |
53 | | uint32 | Uses variable-length encoding. | uint32 | int | int/long |
54 | | uint64 | Uses variable-length encoding. | uint64 | long | int/long |
55 | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
56 | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
57 | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
58 | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
59 | | sfixed32 | Always four bytes. | int32 | int | int |
60 | | sfixed64 | Always eight bytes. | int64 | long | int/long |
61 | | bool | | bool | boolean | boolean |
62 | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
63 | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
64 |
65 |
--------------------------------------------------------------------------------
/refs/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.refs;
4 |
5 | option csharp_namespace = "Neo.FileStorage.API.Refs";
6 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/refs";
7 |
8 | // Objects in NeoFS are addressed by their ContainerID and ObjectID.
9 | //
10 | // String presentation of `Address` is a concatenation of string encoded
11 | // `ContainerID` and `ObjectID` delimited by '/' character.
12 | message Address {
13 | // Container identifier
14 | ContainerID container_id = 1 [json_name = "containerID"];
15 | // Object identifier
16 | ObjectID object_id = 2 [json_name = "objectID"];
17 | }
18 |
19 | // NeoFS Object unique identifier. Objects are immutable and content-addressed.
20 | // It means `ObjectID` will change if the `header` or the `payload` changes.
21 | //
22 | // `ObjectID` is a 32 byte long
23 | // [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
24 | // the object's `header` field, which, in it's turn, contains the hash of the object's
25 | // payload. ID consisting of all zero bytes is reserved for undefined value and
26 | // must not be specified as a field.
27 | //
28 | // String presentation is a
29 | // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
30 | //
31 | // JSON value will be data encoded as a string using standard base64
32 | // encoding with paddings. Either
33 | // [standard](https://tools.ietf.org/html/rfc4648#section-4) or
34 | // [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
35 | // with/without paddings are accepted.
36 | message ObjectID {
37 | // Object identifier in a binary format
38 | bytes value = 1 [json_name = "value"];
39 | }
40 |
41 | // NeoFS container identifier. Container structures are immutable and
42 | // content-addressed.
43 | //
44 | // `ContainerID` is a 32 byte long
45 | // [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
46 | // stable-marshalled container message. ID consisting of all zero bytes is
47 | // reserved for undefined value and must not be specified as a field.
48 | //
49 | // String presentation is a
50 | // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
51 | //
52 | // JSON value will be data encoded as a string using standard base64
53 | // encoding with paddings. Either
54 | // [standard](https://tools.ietf.org/html/rfc4648#section-4) or
55 | // [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
56 | // with/without paddings are accepted.
57 | message ContainerID {
58 | // Container identifier in a binary format.
59 | bytes value = 1 [json_name = "value"];
60 | }
61 |
62 | // `OwnerID` is a derivative of a user's main public key. The transformation
63 | // algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can
64 | // be directly used as `OwnerID`.
65 | //
66 | // `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte
67 | // followed by 20 bytes of ScrptHash and 4 bytes of checksum.
68 | //
69 | // String presentation is a [Base58
70 | // Check](https://en.bitcoin.it/wiki/Base58Check_encoding) Encoded string.
71 | //
72 | // JSON value will be data encoded as a string using standard base64
73 | // encoding with paddings. Either
74 | // [standard](https://tools.ietf.org/html/rfc4648#section-4) or
75 | // [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
76 | // with/without paddings are accepted.
77 | message OwnerID {
78 | // Identifier of the container owner in a binary format
79 | bytes value = 1 [json_name = "value"];
80 | }
81 |
82 | // NeoFS subnetwork identifier.
83 | //
84 | // String representation of a value is base-10 integer.
85 | //
86 | // JSON representation is an object containing a single `value` number field.
87 | //
88 | // DEPRECATED. Kept for compatibility only.
89 | message SubnetID {
90 | // 4-byte integer subnetwork identifier.
91 | fixed32 value = 1 [json_name = "value"];
92 | }
93 |
94 | // API version used by a node.
95 | //
96 | // String presentation is a Semantic Versioning 2.0.0 compatible version string
97 | // with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number.
98 | message Version {
99 | // Major API version
100 | uint32 major = 1 [json_name = "major"];
101 |
102 | // Minor API version
103 | uint32 minor = 2 [json_name = "minor"];
104 | }
105 |
106 | // Signature of something in NeoFS.
107 | message Signature {
108 | // Public key used for signing. For N3 `scheme`, the field represents a
109 | // verification script.
110 | bytes key = 1 [json_name = "key"];
111 | // Signature. For N3 `scheme`, the field represents an invocation script.
112 | bytes sign = 2 [json_name = "signature"];
113 | // Scheme contains digital signature scheme identifier
114 | SignatureScheme scheme = 3 [json_name = "scheme"];
115 | }
116 |
117 | // Signature scheme describes digital signing scheme used for (key, signature) pair.
118 | enum SignatureScheme {
119 | // ECDSA with SHA-512 hashing (FIPS 186-3)
120 | ECDSA_SHA512 = 0;
121 |
122 | // Deterministic ECDSA with SHA-256 hashing (RFC 6979)
123 | ECDSA_RFC6979_SHA256 = 1;
124 |
125 | // Deterministic ECDSA with SHA-256 hashing using WalletConnect API.
126 | // Here the algorithm is the same, but the message format differs.
127 | ECDSA_RFC6979_SHA256_WALLET_CONNECT = 2;
128 |
129 | // Neo N3 witness.
130 | N3 = 3;
131 | }
132 |
133 | // RFC 6979 signature.
134 | message SignatureRFC6979 {
135 | // Public key used for signing. For N3 auth scheme, the field represents a
136 | // verification script.
137 | bytes key = 1 [json_name = "key"];
138 | // Deterministic ECDSA with SHA-256 hashing. For N3 auth scheme, the field
139 | // represents an invocation script.
140 | bytes sign = 2 [json_name = "signature"];
141 | }
142 |
143 | // Checksum algorithm type.
144 | enum ChecksumType {
145 | // Unknown. Not used
146 | CHECKSUM_TYPE_UNSPECIFIED = 0;
147 |
148 | // Tillich-Zemor homomorphic hash function
149 | TZ = 1;
150 |
151 | // SHA-256
152 | SHA256 = 2;
153 | }
154 |
155 | // Checksum message.
156 | // Depending on checksum algorithm type, the string presentation may vary:
157 | //
158 | // * TZ \
159 | // Hex encoded string without `0x` prefix
160 | // * SHA256 \
161 | // Hex encoded string without `0x` prefix
162 | message Checksum {
163 | // Checksum algorithm type
164 | ChecksumType type = 1 [json_name = "type"];
165 |
166 | // Checksum itself
167 | bytes sum = 2 [json_name = "sum"];
168 | }
169 |
--------------------------------------------------------------------------------
/reputation/service.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.reputation;
4 |
5 | import "reputation/types.proto";
6 | import "session/types.proto";
7 |
8 | option csharp_namespace = "Neo.FileStorage.API.Reputation";
9 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation";
10 |
11 | // `ReputationService` provides mechanisms for exchanging trust values with
12 | // other NeoFS nodes. Nodes rate each other's reputation based on how good they
13 | // process requests and set a trust level based on that rating. The trust
14 | // information is passed to the next nodes to check and aggregate unless the
15 | // final result is recorded.
16 | service ReputationService {
17 | // Announce local client trust information to any node in NeoFS network.
18 | //
19 | // Statuses:
20 | // - **OK** (0, SECTION_SUCCESS):
21 | // local trust has been successfully announced;
22 | // - Common failures (SECTION_FAILURE_COMMON).
23 | rpc AnnounceLocalTrust(AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse);
24 |
25 | // Announce the intermediate result of the iterative algorithm for
26 | // calculating the global reputation of the node in NeoFS network.
27 | //
28 | // Statuses:
29 | // - **OK** (0, SECTION_SUCCESS):
30 | // intermediate trust estimation has been successfully announced;
31 | // - Common failures (SECTION_FAILURE_COMMON).
32 | rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse);
33 | }
34 |
35 | // Announce node's local trust information.
36 | message AnnounceLocalTrustRequest {
37 | // Announce node's local trust information.
38 | message Body {
39 | // Trust assessment Epoch number
40 | uint64 epoch = 1;
41 |
42 | // List of normalized local trust values to other NeoFS nodes. The value
43 | // is calculated according to EigenTrust++ algorithm and must be a
44 | // floating point number in [0;1] range.
45 | repeated Trust trusts = 2;
46 | }
47 |
48 | // Body of the request message.
49 | Body body = 1;
50 |
51 | // Carries request meta information. Header data is used only to regulate
52 | // message transport and does not affect request execution.
53 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
54 |
55 | // Carries request verification information. This header is used to
56 | // authenticate the nodes of the message route and check the correctness of
57 | // transmission.
58 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
59 | }
60 |
61 | // Node's local trust information announcement response.
62 | message AnnounceLocalTrustResponse {
63 | // Response to the node's local trust information announcement has an empty body
64 | // because the trust exchange operation is asynchronous. If Trust information
65 | // does not pass sanity checks, it is silently ignored.
66 | message Body {}
67 |
68 | // Body of the response message.
69 | Body body = 1;
70 |
71 | // Carries response meta information. Header data is used only to regulate
72 | // message transport and does not affect request execution.
73 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
74 |
75 | // Carries response verification information. This header is used to
76 | // authenticate the nodes of the message route and check the correctness of
77 | // transmission.
78 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
79 | }
80 |
81 | // Announce intermediate global trust information.
82 | message AnnounceIntermediateResultRequest {
83 | // Announce intermediate global trust information.
84 | message Body {
85 | // Iteration execution Epoch number
86 | uint64 epoch = 1;
87 |
88 | // Iteration sequence number
89 | uint32 iteration = 2;
90 |
91 | // Current global trust value calculated at the specified iteration
92 | PeerToPeerTrust trust = 3;
93 | }
94 |
95 | // Body of the request message.
96 | Body body = 1;
97 |
98 | // Carries request meta information. Header data is used only to regulate
99 | // message transport and does not affect request execution.
100 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
101 |
102 | // Carries request verification information. This header is used to
103 | // authenticate the nodes of the message route and check the correctness of
104 | // transmission.
105 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
106 | }
107 |
108 | // Intermediate global trust information announcement response.
109 | message AnnounceIntermediateResultResponse {
110 | // Response to the node's intermediate global trust information announcement has
111 | // an empty body because the trust exchange operation is asynchronous. If
112 | // Trust information does not pass sanity checks, it is silently ignored.
113 | message Body {}
114 |
115 | // Body of the response message.
116 | Body body = 1;
117 |
118 | // Carries response meta information. Header data is used only to regulate
119 | // message transport and does not affect request execution.
120 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
121 |
122 | // Carries response verification information. This header is used to
123 | // authenticate the nodes of the message route and check the correctness of
124 | // transmission.
125 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
126 | }
127 |
--------------------------------------------------------------------------------
/reputation/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.reputation;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Reputation";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/reputation";
9 |
10 | // NeoFS unique peer identifier is a 33 byte long compressed public key of the
11 | // node, the same as the one stored in the network map.
12 | //
13 | // String presentation is a
14 | // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
15 | //
16 | // JSON value will be data encoded as a string using standard base64
17 | // encoding with paddings. Either
18 | // [standard](https://tools.ietf.org/html/rfc4648#section-4) or
19 | // [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding
20 | // with/without paddings are accepted.
21 | message PeerID {
22 | // Peer node's public key
23 | bytes public_key = 1 [json_name = "publicKey"];
24 | }
25 |
26 | // Trust level to a NeoFS network peer.
27 | message Trust {
28 | // Identifier of the trusted peer
29 | PeerID peer = 1 [json_name = "peer"];
30 |
31 | // Trust level in [0:1] range
32 | double value = 2 [json_name = "value"];
33 | }
34 |
35 | // Trust level of a peer to a peer.
36 | message PeerToPeerTrust {
37 | // Identifier of the trusting peer
38 | PeerID trusting_peer = 1 [json_name = "trustingPeer"];
39 |
40 | // Trust level
41 | Trust trust = 2 [json_name = "trust"];
42 | }
43 |
44 | // Global trust level to NeoFS node.
45 | message GlobalTrust {
46 | // Message format version. Effectively, the version of API library used to create
47 | // the message.
48 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
49 | // Message body structure.
50 | message Body {
51 | // Node manager ID
52 | PeerID manager = 1 [json_name = "manager"];
53 |
54 | // Global trust level
55 | Trust trust = 2 [json_name = "trust"];
56 | }
57 |
58 | // Message body
59 | Body body = 2 [json_name = "body"];
60 |
61 | // Signature of the binary `body` field by the manager.
62 | neo.fs.v2.refs.Signature signature = 3 [json_name = "signature"];
63 | }
64 |
--------------------------------------------------------------------------------
/session/service.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.session;
4 |
5 | import "refs/types.proto";
6 | import "session/types.proto";
7 |
8 | option csharp_namespace = "Neo.FileStorage.API.Session";
9 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session";
10 |
11 | // `SessionService` allows to establish a temporary trust relationship between
12 | // two peer nodes and generate a `SessionToken` as the proof of trust to be
13 | // attached in requests for further verification. Please see corresponding
14 | // section of NeoFS Technical Specification for details.
15 | service SessionService {
16 | // Open a new session between two peers.
17 | //
18 | // Statuses:
19 | // - **OK** (0, SECTION_SUCCESS):
20 | // session has been successfully opened;
21 | // - Common failures (SECTION_FAILURE_COMMON).
22 | rpc Create(CreateRequest) returns (CreateResponse);
23 | }
24 |
25 | // Information necessary for opening a session.
26 | message CreateRequest {
27 | // Session creation request body
28 | message Body {
29 | // Session initiating user's or node's key derived `OwnerID`
30 | neo.fs.v2.refs.OwnerID owner_id = 1;
31 | // Session expiration epoch, the last epoch when session is valid.
32 | uint64 expiration = 2;
33 | }
34 | // Body of a create session token request message.
35 | Body body = 1;
36 |
37 | // Carries request meta information. Header data is used only to regulate
38 | // message transport and does not affect request execution.
39 | neo.fs.v2.session.RequestMetaHeader meta_header = 2;
40 |
41 | // Carries request verification information. This header is used to
42 | // authenticate the nodes of the message route and check the correctness of
43 | // transmission.
44 | neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
45 | }
46 |
47 | // Information about the opened session.
48 | message CreateResponse {
49 | // Session creation response body
50 | message Body {
51 | // Identifier of a newly created session
52 | bytes id = 1;
53 |
54 | // Public key used for session
55 | bytes session_key = 2;
56 | }
57 |
58 | // Body of create session token response message.
59 | Body body = 1;
60 |
61 | // Carries response meta information. Header data is used only to regulate
62 | // message transport and does not affect request execution.
63 | neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
64 |
65 | // Carries response verification information. This header is used to
66 | // authenticate the nodes of the message route and check the correctness of
67 | // transmission.
68 | neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
69 | }
70 |
--------------------------------------------------------------------------------
/session/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.session;
4 |
5 | import "acl/types.proto";
6 | import "refs/types.proto";
7 | import "status/types.proto";
8 |
9 | option csharp_namespace = "Neo.FileStorage.API.Session";
10 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/session";
11 |
12 | // Context information for Session Tokens related to ObjectService requests
13 | message ObjectSessionContext {
14 | // Object request verbs
15 | enum Verb {
16 | // Unknown verb
17 | VERB_UNSPECIFIED = 0;
18 |
19 | // Refers to object.Put RPC call
20 | PUT = 1;
21 |
22 | // Refers to object.Get RPC call
23 | GET = 2;
24 |
25 | // Refers to object.Head RPC call
26 | HEAD = 3;
27 |
28 | // Refers to object.Search RPC call
29 | SEARCH = 4;
30 |
31 | // Refers to object.Delete RPC call
32 | DELETE = 5;
33 |
34 | // Refers to object.GetRange RPC call
35 | RANGE = 6;
36 |
37 | // Refers to object.GetRangeHash RPC call
38 | RANGEHASH = 7;
39 | }
40 | // Type of request for which the token is issued
41 | Verb verb = 1 [json_name = "verb"];
42 |
43 | // Carries objects involved in the object session.
44 | message Target {
45 | // Indicates which container the session is spread to. Field MUST be set
46 | // and correct.
47 | refs.ContainerID container = 1 [json_name = "container"];
48 |
49 | // Indicates which objects the session is spread to. Objects are expected
50 | // to be stored in the NeoFS container referenced by `container` field.
51 | // Each element MUST have correct format.
52 | repeated refs.ObjectID objects = 2 [json_name = "objects"];
53 | }
54 | // Object session target. MUST be correctly formed and set. If `objects`
55 | // field is not empty, then the session applies only to these elements,
56 | // otherwise, to all objects from the specified container.
57 | Target target = 2 [json_name = "target"];
58 | }
59 |
60 | // Context information for Session Tokens related to ContainerService requests.
61 | message ContainerSessionContext {
62 | // Container request verbs
63 | enum Verb {
64 | // Unknown verb
65 | VERB_UNSPECIFIED = 0;
66 |
67 | // Refers to container.Put RPC call
68 | PUT = 1;
69 |
70 | // Refers to container.Delete RPC call
71 | DELETE = 2;
72 |
73 | // Refers to container.SetExtendedACL RPC call
74 | SETEACL = 3;
75 | }
76 | // Type of request for which the token is issued
77 | Verb verb = 1 [json_name = "verb"];
78 |
79 | // Spreads the action to all owner containers.
80 | // If set, container_id field is ignored.
81 | bool wildcard = 2 [json_name = "wildcard"];
82 |
83 | // Particular container to which the action applies.
84 | // Ignored if wildcard flag is set.
85 | refs.ContainerID container_id = 3 [json_name = "containerID"];
86 | }
87 |
88 | // NeoFS Session Token.
89 | message SessionToken {
90 | // Session Token body
91 | message Body {
92 | // Token identifier is a valid UUIDv4 in binary form
93 | bytes id = 1 [json_name = "id"];
94 |
95 | // Identifier of the session initiator
96 | neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"];
97 |
98 | // Lifetime parameters of the token. Field names taken from rfc7519.
99 | message TokenLifetime {
100 | // Expiration epoch, the last epoch when token is valid.
101 | uint64 exp = 1 [json_name = "exp"];
102 |
103 | // Not valid before epoch, the first epoch when token is valid.
104 | uint64 nbf = 2 [json_name = "nbf"];
105 |
106 | // Issued at Epoch
107 | uint64 iat = 3 [json_name = "iat"];
108 | }
109 | // Lifetime of the session
110 | TokenLifetime lifetime = 3 [json_name = "lifetime"];
111 |
112 | // Public key used in session
113 | bytes session_key = 4 [json_name = "sessionKey"];
114 |
115 | // Session Context information
116 | oneof context {
117 | // ObjectService session context
118 | ObjectSessionContext object = 5 [json_name = "object"];
119 |
120 | // ContainerService session context
121 | ContainerSessionContext container = 6 [json_name = "container"];
122 | }
123 | }
124 | // Session Token contains the proof of trust between peers to be attached in
125 | // requests for further verification. Please see corresponding section of
126 | // NeoFS Technical Specification for details.
127 | Body body = 1 [json_name = "body"];
128 |
129 | // Signature of `SessionToken` information
130 | neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"];
131 | }
132 |
133 | // Extended headers for Request/Response. They may contain any user-defined headers
134 | // to be interpreted on application level.
135 | //
136 | // Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
137 | // Responses with duplicated header names or headers with empty values will be
138 | // considered invalid.
139 | //
140 | // There are some "well-known" headers starting with `__NEOFS__` prefix that
141 | // affect system behaviour:
142 | //
143 | // * __NEOFS__NETMAP_EPOCH \
144 | // Netmap epoch to use for object placement calculation. The `value` is string
145 | // encoded `uint64` in decimal presentation. If set to '0' or not set, the
146 | // current epoch only will be used. DEPRECATED: header ignored by servers.
147 | // * __NEOFS__NETMAP_LOOKUP_DEPTH \
148 | // If object can't be found using current epoch's netmap, this header limits
149 | // how many past epochs the node can look up through. The `value` is string
150 | // encoded `uint64` in decimal presentation. If set to '0' or not set, only the
151 | // current epoch will be used. DEPRECATED: header ignored by servers.
152 | message XHeader {
153 | // Key of the X-Header
154 | string key = 1 [json_name = "key"];
155 |
156 | // Value of the X-Header
157 | string value = 2 [json_name = "value"];
158 | }
159 |
160 | // Meta information attached to the request. When forwarded between peers,
161 | // request meta headers are folded in matryoshka style.
162 | message RequestMetaHeader {
163 | // Peer's API version used
164 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
165 |
166 | // Peer's local epoch number. Set to 0 if unknown.
167 | uint64 epoch = 2 [json_name = "epoch"];
168 |
169 | // Maximum number of intermediate nodes in the request route
170 | uint32 ttl = 3 [json_name = "ttl"];
171 |
172 | // Request X-Headers
173 | repeated XHeader x_headers = 4 [json_name = "xHeaders"];
174 |
175 | // Session token within which the request is sent
176 | SessionToken session_token = 5 [json_name = "sessionToken"];
177 |
178 | // `BearerToken` with eACL overrides for the request
179 | neo.fs.v2.acl.BearerToken bearer_token = 6 [json_name = "bearerToken"];
180 |
181 | // `RequestMetaHeader` of the origin request
182 | RequestMetaHeader origin = 7 [json_name = "origin"];
183 |
184 | // NeoFS network magic. Must match the value for the network
185 | // that the server belongs to.
186 | uint64 magic_number = 8 [json_name = "magicNumber"];
187 | }
188 |
189 | // Information about the response
190 | message ResponseMetaHeader {
191 | // Peer's API version used
192 | neo.fs.v2.refs.Version version = 1 [json_name = "version"];
193 |
194 | // Peer's local epoch number
195 | uint64 epoch = 2 [json_name = "epoch"];
196 |
197 | // Maximum number of intermediate nodes in the request route
198 | uint32 ttl = 3 [json_name = "ttl"];
199 |
200 | // Response X-Headers
201 | repeated XHeader x_headers = 4 [json_name = "xHeaders"];
202 |
203 | // `ResponseMetaHeader` of the origin request
204 | ResponseMetaHeader origin = 5 [json_name = "origin"];
205 |
206 | // Status return
207 | neo.fs.v2.status.Status status = 6 [json_name = "status"];
208 | }
209 |
210 | // Verification info for the request signed by all intermediate nodes.
211 | message RequestVerificationHeader {
212 | // Request Body signature. Should be generated once by the request initiator.
213 | neo.fs.v2.refs.Signature body_signature = 1 [json_name = "bodySignature"];
214 | // Request Meta signature is added and signed by each intermediate node
215 | neo.fs.v2.refs.Signature meta_signature = 2 [json_name = "metaSignature"];
216 | // Signature of previous hops
217 | neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"];
218 |
219 | // Chain of previous hops signatures
220 | RequestVerificationHeader origin = 4 [json_name = "origin"];
221 | }
222 |
223 | // Verification info for the response signed by all intermediate nodes
224 | message ResponseVerificationHeader {
225 | // Response Body signature. Should be generated once by an answering node.
226 | neo.fs.v2.refs.Signature body_signature = 1 [json_name = "bodySignature"];
227 | // Response Meta signature is added and signed by each intermediate node
228 | neo.fs.v2.refs.Signature meta_signature = 2 [json_name = "metaSignature"];
229 | // Signature of previous hops
230 | neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"];
231 |
232 | // Chain of previous hops signatures
233 | ResponseVerificationHeader origin = 4 [json_name = "origin"];
234 | }
235 |
--------------------------------------------------------------------------------
/status/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.status;
4 |
5 | option csharp_namespace = "Neo.FileStorage.API.Status";
6 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/status";
7 |
8 | // Declares the general format of the status returns of the NeoFS RPC protocol.
9 | // Status is present in all response messages. Each RPC of NeoFS protocol
10 | // describes the possible outcomes and details of the operation.
11 | //
12 | // Each status is assigned a one-to-one numeric code. Any unique result of an
13 | // operation in NeoFS is unambiguously associated with the code value.
14 | //
15 | // Numerical set of codes is split into 1024-element sections. An enumeration
16 | // is defined for each section. Values can be referred to in the following ways:
17 | //
18 | // * numerical value ranging from 0 to 4,294,967,295 (global code);
19 | //
20 | // * values from enumeration (local code). The formula for the ratio of the
21 | // local code (`L`) of a defined section (`S`) to the global one (`G`):
22 | // `G = 1024 * S + L`.
23 | //
24 | // All outcomes are divided into successful and failed, which corresponds
25 | // to the success or failure of the operation. The definition of success
26 | // follows the semantics of RPC and the description of its purpose.
27 | // The server must not attach code that is the opposite of the outcome type.
28 | //
29 | // See the set of return codes in the description for calls.
30 | //
31 | // Each status can carry a developer-facing error message. It should be a human
32 | // readable text in English. The server should not transmit (and the client
33 | // should not expect) useful information in the message. Field `details`
34 | // should make the return more detailed.
35 | message Status {
36 | // The status code
37 | uint32 code = 1;
38 |
39 | // Developer-facing error message
40 | string message = 2;
41 |
42 | // Return detail. It contains additional information that can be used to
43 | // analyze the response. Each code defines a set of details that can be
44 | // attached to a status. Client should not handle details that are not
45 | // covered by the code.
46 | message Detail {
47 | // Detail ID. The identifier is required to determine the binary format
48 | // of the detail and how to decode it.
49 | uint32 id = 1;
50 |
51 | // Binary status detail. Must follow the format associated with ID.
52 | // The possibility of missing a value must be explicitly allowed.
53 | bytes value = 2;
54 | }
55 |
56 | // Data detailing the outcome of the operation. Must be unique by ID.
57 | repeated Detail details = 3;
58 | }
59 |
60 | // Section identifiers.
61 | enum Section {
62 | // Successful return codes.
63 | SECTION_SUCCESS = 0;
64 |
65 | // Failure codes regardless of the operation.
66 | SECTION_FAILURE_COMMON = 1;
67 |
68 | // Object service-specific errors.
69 | SECTION_OBJECT = 2;
70 |
71 | // Container service-specific errors.
72 | SECTION_CONTAINER = 3;
73 |
74 | // Session service-specific errors.
75 | SECTION_SESSION = 4;
76 | }
77 |
78 | // Section of NeoFS successful return codes.
79 | enum Success {
80 | // [**0**] Default success. Not detailed.
81 | // If the server cannot match successful outcome to the code, it should
82 | // use this code.
83 | OK = 0;
84 | }
85 |
86 | // Section of failed statuses independent of the operation.
87 | enum CommonFail {
88 | // [**1024**] Internal server error, default failure. Not detailed.
89 | // If the server cannot match failed outcome to the code, it should
90 | // use this code.
91 | INTERNAL = 0;
92 |
93 | // [**1025**] Wrong magic of the NeoFS network.
94 | // Details:
95 | // - [**0**] Magic number of the served NeoFS network (big-endian 64-bit
96 | // unsigned integer).
97 | WRONG_MAGIC_NUMBER = 1;
98 |
99 | // [**1026**] Signature verification failure.
100 | SIGNATURE_VERIFICATION_FAIL = 2;
101 |
102 | // [**1027**] Node is under maintenance.
103 | NODE_UNDER_MAINTENANCE = 3;
104 | }
105 |
106 | // Section of statuses for object-related operations.
107 | enum Object {
108 | // [**2048**] Access denied by ACL.
109 | // Details:
110 | // - [**0**] Human-readable description (UTF-8 encoded string).
111 | ACCESS_DENIED = 0;
112 |
113 | // [**2049**] Object not found.
114 | OBJECT_NOT_FOUND = 1;
115 |
116 | // [**2050**] Operation rejected by the object lock.
117 | LOCKED = 2;
118 |
119 | // [**2051**] Locking an object with a non-REGULAR type rejected.
120 | LOCK_NON_REGULAR_OBJECT = 3;
121 |
122 | // [**2052**] Object has been marked deleted.
123 | OBJECT_ALREADY_REMOVED = 4;
124 |
125 | // [**2053**] Invalid range has been requested for an object.
126 | OUT_OF_RANGE = 5;
127 | }
128 |
129 | // Section of statuses for container-related operations.
130 | enum Container {
131 | // [**3072**] Container not found.
132 | CONTAINER_NOT_FOUND = 0;
133 |
134 | // [**3073**] eACL table not found.
135 | EACL_NOT_FOUND = 1;
136 | }
137 |
138 | // Section of statuses for session-related operations.
139 | enum Session {
140 | // [**4096**] Token not found.
141 | TOKEN_NOT_FOUND = 0;
142 |
143 | // [**4097**] Token has expired.
144 | TOKEN_EXPIRED = 1;
145 | }
146 |
--------------------------------------------------------------------------------
/storagegroup/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.storagegroup;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.StorageGroup";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/storagegroup";
9 |
10 | // StorageGroup keeps verification information for Data Audit sessions. Objects
11 | // that require paid storage guarantees are gathered in `StorageGroups` with
12 | // additional information used for the proof of storage. `StorageGroup` only
13 | // contains objects from the same container.
14 | //
15 | // Being an object payload, StorageGroup may have expiration Epoch set with
16 | // `__NEOFS__EXPIRATION_EPOCH` well-known attribute. When expired, StorageGroup
17 | // will be ignored by InnerRing nodes during Data Audit cycles and will be
18 | // deleted by Storage Nodes.
19 | //
20 | message StorageGroup {
21 | // Total size of the payloads of objects in the storage group
22 | uint64 validation_data_size = 1 [json_name = "validationDataSize"];
23 |
24 | // Homomorphic hash from the concatenation of the payloads of the storage
25 | // group members. The order of concatenation is the same as the order of the
26 | // members in the `members` field.
27 | neo.fs.v2.refs.Checksum validation_hash = 2 [json_name = "validationHash"];
28 |
29 | // DEPRECATED. Last NeoFS epoch number of the storage group lifetime
30 | uint64 expiration_epoch = 3 [
31 | json_name = "expirationEpoch",
32 | deprecated = true
33 | ];
34 |
35 | // Strictly ordered list of storage group member objects. Members MUST be unique
36 | repeated neo.fs.v2.refs.ObjectID members = 4 [json_name = "members"];
37 | }
38 |
--------------------------------------------------------------------------------
/subnet/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.subnet;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Subnet";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/subnet";
9 |
10 | // NeoFS subnetwork description
11 | //
12 | // DEPRECATED. Ignored and kept for compatibility only.
13 | message SubnetInfo {
14 | // Unique subnet identifier. Missing ID is
15 | // equivalent to zero (default subnetwork) ID.
16 | neo.fs.v2.refs.SubnetID id = 1;
17 |
18 | // Identifier of the subnetwork owner
19 | neo.fs.v2.refs.OwnerID owner = 2;
20 | }
21 |
--------------------------------------------------------------------------------
/tombstone/types.proto:
--------------------------------------------------------------------------------
1 | syntax = "proto3";
2 |
3 | package neo.fs.v2.tombstone;
4 |
5 | import "refs/types.proto";
6 |
7 | option csharp_namespace = "Neo.FileStorage.API.Tombstone";
8 | option go_package = "github.com/nspcc-dev/neofs-sdk-go/proto/tombstone";
9 |
10 | // Tombstone keeps record of deleted objects for a few epochs until they are
11 | // purged from the NeoFS network. It is impossible to delete a tombstone object
12 | // via ObjectService.Delete RPC call.
13 | message Tombstone {
14 | // Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone
15 | // creator depending on the current NeoFS network settings.
16 | // DEPRECATED. Field ignored by servers, set corresponding object attribute
17 | // `__NEOFS__EXPIRATION_EPOCH` only.
18 | uint64 expiration_epoch = 1 [
19 | json_name = "expirationEpoch",
20 | deprecated = true
21 | ];
22 |
23 | // 16 byte UUID used to identify the split object hierarchy parts. Must be
24 | // unique inside a container. All objects participating in the split must
25 | // have the same `split_id` value.
26 | // DEPRECATED. The field is ignored by servers.
27 | bytes split_id = 2 [json_name = "splitID"];
28 |
29 | // List of objects to be deleted.
30 | // IDs should be either:
31 | // 1. Root object IDs (objects that are not split OR parent objects)
32 | // 2. Children IDs for unfinished objects that does not have LINK objects (garbage collecting).
33 | repeated neo.fs.v2.refs.ObjectID members = 3 [json_name = "members"];
34 | }
35 |
--------------------------------------------------------------------------------