diff --git a/.forgejo/ISSUE_TEMPLATE/bug_report.md b/.forgejo/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 7e778d2..0000000 --- a/.forgejo/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: community, triage, bug -assignees: '' - ---- - - - -## Expected Behavior - - - -## Current Behavior - - - -## Possible Solution - - - - - - -## Steps to Reproduce (for bugs) - - - -1. - -## Context - - - -## Regression - - - -## Your Environment - -* Version used: -* Server setup and configuration: -* Operating System and version (`uname -a`): diff --git a/.forgejo/ISSUE_TEMPLATE/config.yml b/.forgejo/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index 3ba13e0..0000000 --- a/.forgejo/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1 +0,0 @@ -blank_issues_enabled: false diff --git a/.forgejo/ISSUE_TEMPLATE/feature_request.md b/.forgejo/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index d6d1162..0000000 --- a/.forgejo/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: community, triage -assignees: '' - ---- - -## Is your feature request related to a problem? Please describe. - - -## Describe the solution you'd like - - -## Describe alternatives you've considered - - -## Additional context - diff --git a/.forgejo/workflows/dco.yaml b/.forgejo/workflows/dco.yaml deleted file mode 100644 index 74fba6a..0000000 --- a/.forgejo/workflows/dco.yaml +++ /dev/null @@ -1,19 +0,0 @@ -name: DCO action -on: [pull_request] - -jobs: - dco: - name: DCO - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - name: Setup Go - uses: actions/setup-go@v3 - with: - go-version: '1.22' - - name: Run commit format checker - uses: https://git.frostfs.info/TrueCloudLab/dco-go@v3 - with: - from: 'origin/${{ github.event.pull_request.base.ref }}' diff --git a/.forgejo/workflows/fmt.yaml b/.forgejo/workflows/fmt.yaml deleted file mode 100644 index ddd50a7..0000000 --- a/.forgejo/workflows/fmt.yaml +++ /dev/null @@ -1,17 +0,0 @@ -name: Formatters -on: [pull_request] - -jobs: - fmt: - name: Run fmt - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v3 - - name: Install deps - run: | - apt update - apt install -y clang-format - - name: Run fmt - run: | - make fmt - git diff --exit-code --quiet diff --git a/.forgejo/workflows/pre-commit.yaml b/.forgejo/workflows/pre-commit.yaml deleted file mode 100644 index 5bf97eb..0000000 --- a/.forgejo/workflows/pre-commit.yaml +++ /dev/null @@ -1,18 +0,0 @@ -name: Pre-commit hooks -on: [pull_request] - -jobs: - pre-commit: - name: Pre-commit - env: - # Skip pre-commit hooks which are executed by other actions. - SKIP: make-fmt - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v3 - - name: Install deps - run: | - apt update - apt install -y pre-commit - - name: Run pre-commit - run: pre-commit run --all-files --hook-stage manual --color=always diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..29c4211 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @alexvanin @realloc @fyrchik @anatoly-bogatyrev diff --git a/.forgejo/logo.svg b/.github/logo.svg similarity index 100% rename from .forgejo/logo.svg rename to .github/logo.svg diff --git a/.forgejo/markdown.tmpl b/.github/markdown.tmpl similarity index 92% rename from .forgejo/markdown.tmpl rename to .github/markdown.tmpl index 2d6c57b..f945c13 100644 --- a/.forgejo/markdown.tmpl +++ b/.github/markdown.tmpl @@ -4,11 +4,11 @@ ## Table of Contents {{range .Files}} {{$file_name := .Name}}- [{{.Name}}](#{{.Name}}) -{{if .Services}} - Services - {{range .Services}} - [{{.Name}}](#{{.FullName}}) +{{if .Services}} - Services + {{range .Services}}- [{{.Name}}](#{{.FullName}}) {{end}}{{end}} {{if .Messages}} - Messages - {{range .Messages}} - [{{.LongName}}](#{{.FullName}}) + {{range .Messages}}- [{{.LongName}}](#{{.FullName}}) {{end}}{{end}} {{end}} - [Scalar Value Types](#scalar-value-types) diff --git a/.github/workflows/buf.yml b/.github/workflows/buf.yml new file mode 100644 index 0000000..5d9d740 --- /dev/null +++ b/.github/workflows/buf.yml @@ -0,0 +1,36 @@ +name: Buf lint + +on: + pull_request: + branches: + - master + +jobs: + lint: + runs-on: ubuntu-20.04 + steps: + - uses: actions/checkout@v2 + - uses: wizhi/setup-buf@v1 + with: + version: 0.20.5 + - run: buf check lint + + breaking: + runs-on: ubuntu-20.04 + steps: + - name: Setup buf + uses: wizhi/setup-buf@v1 + with: + version: 0.20.5 + - name: Check out ref code + uses: actions/checkout@v2 + with: + ref: ${{ github.base_ref }} + path: baseref + - run: cd baseref && buf image build -o image.bin + + - name: Check out code + uses: actions/checkout@v2 + with: + path: prclone + - run: cd prclone && buf check breaking --against-input ../baseref/image.bin diff --git a/.github/workflows/dco.yml b/.github/workflows/dco.yml new file mode 100644 index 0000000..40ed8fc --- /dev/null +++ b/.github/workflows/dco.yml @@ -0,0 +1,21 @@ +name: DCO check + +on: + pull_request: + branches: + - master + +jobs: + commits_check_job: + runs-on: ubuntu-latest + name: Commits Check + steps: + - name: Get PR Commits + id: 'get-pr-commits' + uses: tim-actions/get-pr-commits@master + with: + token: ${{ secrets.GITHUB_TOKEN }} + - name: DCO Check + uses: tim-actions/dco@master + with: + commits: ${{ steps.get-pr-commits.outputs.commits }} diff --git a/.gitignore b/.gitignore index 485dee6..c6ef218 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .idea + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml deleted file mode 100644 index 96f3e27..0000000 --- a/.pre-commit-config.yaml +++ /dev/null @@ -1,24 +0,0 @@ -repos: - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 - hooks: - - id: check-added-large-files - - id: check-case-conflict - - id: check-executables-have-shebangs - - id: check-shebang-scripts-are-executable - - id: check-merge-conflict - - id: check-json - - id: check-xml - - id: check-yaml - - id: trailing-whitespace - args: [--markdown-linebreak-ext=md] - - id: end-of-file-fixer - exclude: ".svg$" - - - repo: local - hooks: - - id: make-fmt - name: Run make fmt - entry: make fmt - language: system - pass_filenames: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 70ceb4a..81f2852 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,16 +1,5 @@ # Changelog -## [Unreleased] - -### Changed -- Add `__SYSTEM__` attribute prefix (#12, #14) -- Add `allow_impersonate` flag to bearer token (#18) - -### Removed -- Reputation system (#22) -- All `subnet` related fields and types (#25) -- Storage group (#19) - ## [2.14.0] - 2022-09-23 - Anmado (안마도, 鞍馬島) ### Added @@ -61,7 +50,7 @@ Network magic, main status codes, object locks and notifications. - `LOCK` value of `object.Type` enum (#194) - `Lock` message with payload content of `LOCK` objects (#194) - `LOCKED` and `LOCK_NON_REGULAR_OBJECT` status codes to `Object` section (#194) -- `scheme` field of type `SignatureScheme` to `Signature` message which determines +- `scheme` field of type `SignatureScheme` to `Signature` message which determines signature scheme (#55) - `SignatureRFC6979` message (#203) @@ -166,8 +155,8 @@ values in the objects. ### Changed -- Clarified processing of empty search query in `object.Search` RPC. -- Specified connection of tombstone expiration value with well-known +- Clarified processing of empty search query in `object.Search` RPC. +- Specified connection of tombstone expiration value with well-known `__NEOFS__EXPIRATION_EPOCH` object attribute. ## [2.3.0] - 2021-02-11 - Seonyudo (선유도, 仙遊島) diff --git a/CODEOWNERS b/CODEOWNERS deleted file mode 100644 index 854e751..0000000 --- a/CODEOWNERS +++ /dev/null @@ -1,3 +0,0 @@ -.* @alexvanin @realloc @fyrchik @a.bogatyrev @TrueCloudLab/storage-sdk-developers -.forgejo/.* @potyarkin -Makefile @potyarkin diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ca386f..c26de50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,8 +3,8 @@ First, thank you for contributing! We love and encourage pull requests from everyone. Please follow the guidelines: -- Check the open [issues](https://git.frostfs.info/TrueCloudLab/frostfs-api/issues) and - [pull requests](https://git.frostfs.info/TrueCloudLab/frostfs-api/pulls) for existing +- Check the open [issues](https://github.com/TrueCloudLab/frostfs-api/issues) and + [pull requests](https://github.com/TrueCloudLab/frostfs-api/pulls) for existing discussions. - Open an issue first, to discuss a new feature or enhancement. @@ -25,20 +25,19 @@ Start by forking the `frostfs-api` repository, make changes in a branch and then send a pull request. We encourage pull requests to discuss code changes. Here are the steps in details: -### Set up your repository - -Fork [FrostFS upstream](https://git.frostfs.info/TrueCloudLab/frostfs-api/fork) source +### Set up your GitHub Repository +Fork [NeoFS node upstream](https://github.com/TrueCloudLab/frostfs-api/fork) source repository to your own personal repository. Copy the URL of your fork (you will need it for the `git clone` command below). ```sh -$ git clone https://git.frostfs.info/TrueCloudLab/frostfs-api +$ git clone https://github.com/TrueCloudLab/frostfs-api ``` ### Set up git remote as ``upstream`` ```sh $ cd frostfs-api -$ git remote add upstream https://git.frostfs.info/TrueCloudLab/frostfs-api +$ git remote add upstream https://github.com/TrueCloudLab/frostfs-api $ git fetch upstream $ git merge upstream/master ... @@ -87,7 +86,7 @@ $ git push origin feature/123-something_awesome ``` ### Create a Pull Request -Pull requests can be created via git.frostfs.info. Refer to [this +Pull requests can be created via GitHub. Refer to [this document](https://help.github.com/articles/creating-a-pull-request/) for detailed steps on how to create a pull request. After a Pull Request gets peer reviewed and approved, it will be merged. diff --git a/Makefile b/Makefile old mode 100755 new mode 100644 index 6173f5c..d66c98a --- a/Makefile +++ b/Makefile @@ -1,35 +1,21 @@ #!/usr/bin/make -f SHELL=bash -include help.mk +# BRanch to match for BReaking changes +BRBR?=master -.PHONY: doc fmt pre-commit unpre-commit pre-commit-run +.PHONY: lint +lint: + buf check lint + buf check breaking --against-input '.git#branch=$(BRBR)' +.PHONY: doc # Regenerate documentation for proto files: doc: @for f in `find . -type f -name '*.proto' -exec dirname {} \; | sort -u `; do \ echo "⇒ Documentation for $$(basename $$f)"; \ protoc \ - --doc_opt=.forgejo/markdown.tmpl,$${f}.md \ + --doc_opt=.github/markdown.tmpl,$${f}.md \ --proto_path=.:/usr/local/include \ --doc_out=proto-docs/ $${f}/*.proto; \ done - -# Run clang-format -fmt: - @for f in `ls **/*.proto`; do \ - echo "⇒ Formatting $$f"; \ - clang-format -i $$f; \ - done - -# Activate pre-commit hooks -pre-commit: - pre-commit install --hook-type pre-commit - -# Deactivate pre-commit hooks -unpre-commit: - pre-commit uninstall --hook-type pre-commit - -# Run pre-commit hooks -pre-commit-run: - @pre-commit run --all-files --hook-stage manual diff --git a/README.md b/README.md index 5447b7b..5a262ae 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@

-FrostFS +FrostFS

- FrostFS API language-agnostic protocol definitions + FrostFS API language-agnostic protocol definitions

--- -![Release](https://git.frostfs.info/TrueCloudLab/frostfs-api/badges/release.svg) +![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/TrueCloudLab/frostfs-api?sort=semver) +![License](https://img.shields.io/github/license/TrueCloudLab/frostfs-api.svg?style=popout) ## Overview FrostFS-API repository is the basis for language-specific libraries, e.g.: -- [frostfs-api-go](https://git.frostfs.info/TrueCloudLab/frostfs-api-go) +- [frostfs-api-go](https://github.com/TrueCloudLab/frostfs-api-go) Those libraries contain compiled protocol buffers definitions, wrapped with language-specific code. Use them to integrate applications with FrostFS. diff --git a/accounting/service.proto b/accounting/service.proto index cd49b4d..154382a 100644 --- a/accounting/service.proto +++ b/accounting/service.proto @@ -1,35 +1,35 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.accounting; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting"; option csharp_namespace = "Neo.FileStorage.API.Accounting"; import "accounting/types.proto"; import "refs/types.proto"; import "session/types.proto"; -// Accounting service provides methods for interaction with FrostFS sidechain -// via other FrostFS nodes to get information about the account balance. Deposit -// and Withdraw operations can't be implemented here, as they require Mainnet -// FrostFS smart contract invocation. Transfer operations between internal -// FrostFS accounts are possible if both use the same token type. +// Accounting service provides methods for interaction with NeoFS sidechain via +// other NeoFS nodes to get information about the account balance. Deposit and +// Withdraw operations can't be implemented here, as they require Mainnet NeoFS +// smart contract invocation. Transfer operations between internal NeoFS +// accounts are possible if both use the same token type. service AccountingService { - // Returns the amount of funds in GAS token for the requested FrostFS account. + // Returns the amount of funds in GAS token for the requested NeoFS account. // // Statuses: // - **OK** (0, SECTION_SUCCESS): // balance has been successfully read; // - Common failures (SECTION_FAILURE_COMMON). - rpc Balance(BalanceRequest) returns (BalanceResponse); + rpc Balance (BalanceRequest) returns (BalanceResponse); } // BalanceRequest message message BalanceRequest { // To indicate the account for which the balance is requested, its identifier - // is used. It can be any existing account in FrostFS sidechain `Balance` - // smart contract. If omitted, client implementation MUST set it to the - // request's signer `OwnerID`. + // is used. It can be any existing account in NeoFS sidechain `Balance` smart + // contract. If omitted, client implementation MUST set it to the request's + // signer `OwnerID`. message Body { // Valid user identifier in `OwnerID` format for which the balance is // requested. Required field. @@ -51,8 +51,7 @@ message BalanceRequest { // BalanceResponse message message BalanceResponse { // The amount of funds in GAS token for the `OwnerID`'s account requested. - // Balance is given in the `Decimal` format to avoid precision issues with - // rounding. + // Balance is given in the `Decimal` format to avoid precision issues with rounding. message Body { // Amount of funds in GAS token for the requested account. Decimal balance = 1; diff --git a/accounting/types.proto b/accounting/types.proto index 7f5e89c..af16f84 100644 --- a/accounting/types.proto +++ b/accounting/types.proto @@ -1,11 +1,11 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.accounting; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting"; option csharp_namespace = "Neo.FileStorage.API.Accounting"; -// Standard floating point data type can't be used in FrostFS due to inexactness +// Standard floating point data type can't be used in NeoFS due to inexactness // of the result when doing lots of small number operations. To solve the lost // precision issue, special `Decimal` format is used for monetary computations. // @@ -14,9 +14,9 @@ option csharp_namespace = "Neo.FileStorage.API.Accounting"; // description. message Decimal { // Number in the smallest Token fractions. - int64 value = 1 [ json_name = "value" ]; + int64 value = 1 [json_name = "value"]; // Precision value indicating how many smallest fractions can be in one // integer. - uint32 precision = 2 [ json_name = "precision" ]; + uint32 precision = 2 [json_name = "precision"]; } diff --git a/acl/types.proto b/acl/types.proto index 78f247a..491c1e5 100644 --- a/acl/types.proto +++ b/acl/types.proto @@ -1,12 +1,11 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.acl; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/acl/grpc;acl"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/acl/grpc;acl"; option csharp_namespace = "Neo.FileStorage.API.Acl"; import "refs/types.proto"; -import "ape/types.proto"; // Target role of the access control rule in access control list. enum Role { @@ -20,8 +19,7 @@ enum Role { // container or an inner ring node SYSTEM = 2; - // Others target rule is applied if sender is neither a user nor a system - // target + // Others target rule is applied if sender is neither a user nor a system target OTHERS = 3; } @@ -89,18 +87,18 @@ enum HeaderType { // Filter object headers OBJECT = 2; - // Filter service headers. These are not processed by FrostFS nodes and + // Filter service headers. These are not processed by NeoFS nodes and // exist for service use only. SERVICE = 3; } // Describes a single eACL rule. message EACLRecord { - // FrostFS request Verb to match - Operation operation = 1 [ json_name = "operation" ]; + // NeoFS request Verb to match + Operation operation = 1 [json_name = "operation"]; // Rule execution result. Either allows or denies access if filters match. - Action action = 2 [ json_name = "action" ]; + Action action = 2 [json_name = "action"]; // Filter to check particular properties of the request or the object. // @@ -134,48 +132,48 @@ message EACLRecord { // it's possible to take that information from the requested address. message Filter { // Define if Object or Request header will be used - HeaderType header_type = 1 [ json_name = "headerType" ]; + HeaderType header_type = 1 [json_name = "headerType"]; // Match operation type - MatchType match_type = 2 [ json_name = "matchType" ]; + MatchType match_type = 2 [json_name = "matchType"]; // Name of the Header to use - string key = 3 [ json_name = "key" ]; + string key = 3 [json_name="key"]; // Expected Header Value or pattern to match - string value = 4 [ json_name = "value" ]; + string value = 4 [json_name="value"]; } // List of filters to match and see if rule is applicable - repeated Filter filters = 3 [ json_name = "filters" ]; + repeated Filter filters = 3 [json_name="filters"]; // Target to apply ACL rule. Can be a subject's role class or a list of public // keys to match. message Target { // Target subject's role class - Role role = 1 [ json_name = "role" ]; + Role role = 1 [json_name="role"]; // List of public keys to identify target subject - repeated bytes keys = 2 [ json_name = "keys" ]; + repeated bytes keys = 2 [json_name="keys"]; } // List of target subjects to apply ACL rule to - repeated Target targets = 4 [ json_name = "targets" ]; + repeated Target targets = 4 [json_name="targets"]; } // Extended ACL rules table. A list of ACL rules defined additionally to Basic // ACL. Extended ACL rules can be attached to a container and can be updated // or may be defined in `BearerToken` structure. Please see the corresponding -// FrostFS Technical Specification section for detailed description. +// NeoFS Technical Specification section for detailed description. message EACLTable { // eACL format version. Effectively, the version of API library used to create // eACL Table. - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Identifier of the container that should use given access control rules - neo.fs.v2.refs.ContainerID container_id = 2 [ json_name = "containerID" ]; + neo.fs.v2.refs.ContainerID container_id = 2 [json_name="containerID"]; // List of Extended ACL rules - repeated EACLRecord records = 3 [ json_name = "records" ]; + repeated EACLRecord records = 3 [json_name="records"]; } // BearerToken allows to attach signed Extended ACL rules to the request in @@ -185,65 +183,44 @@ message EACLTable { // used in the similar use cases, like providing authorisation to externally // authenticated party. // -// BearerToken can be issued only by the container's owner and must be signed -// using the key associated with the container's `OwnerID`. +// BearerToken can be issued only by the container's owner and must be signed using +// the key associated with the container's `OwnerID`. message BearerToken { - // Bearer Token body structure contains Extended ACL table issued by the - // container owner with additional information preventing token abuse. + // Bearer Token body structure contains Extended ACL table issued by the container + // owner with additional information preventing token abuse. message Body { // 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. - // - // Deprecated: eACL tables are no longer relevant - `APEOverrides` should be - // used instead. - EACLTable eacl_table = 1 [ json_name = "eaclTable" ]; + // valid for this specific container. Otherwise, any container of the same owner + // is allowed. + EACLTable eacl_table = 1 [json_name="eaclTable"]; // `OwnerID` defines to whom the token was issued. It must match the request // originator's `OwnerID`. If empty, any token bearer will be accepted. - neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ]; + neo.fs.v2.refs.OwnerID owner_id = 2 [json_name="ownerID"]; // Lifetime parameters of the token. Field names taken from // [rfc7519](https://tools.ietf.org/html/rfc7519). message TokenLifetime { // Expiration Epoch - uint64 exp = 1 [ json_name = "exp" ]; + uint64 exp = 1 [json_name="exp"]; // Not valid before Epoch - uint64 nbf = 2 [ json_name = "nbf" ]; + uint64 nbf = 2 [json_name="nbf"]; // Issued at Epoch - uint64 iat = 3 [ json_name = "iat" ]; + uint64 iat = 3 [json_name="iat"]; } // Token expiration and valid time period parameters - TokenLifetime lifetime = 3 [ json_name = "lifetime" ]; + TokenLifetime lifetime = 3 [json_name="lifetime"]; // AllowImpersonate flag to consider token signer as request owner. // If this field is true extended ACL table in token body isn't processed. - bool allow_impersonate = 4 [ json_name = "allowImpersonate" ]; - - // APEOverride is the list of APE chains defined for a target. - // These chains are meant to serve as overrides to the already defined (or - // even undefined) APE chains for the target (see contract `Policy`). - // - // The server-side processing of the bearer token with set APE overrides - // must verify if a client is permitted to override chains for the target, - // preventing unauthorized access through the APE mechanism. - message APEOverride { - // Target for which chains are applied. - frostfs.v2.ape.ChainTarget target = 1 [ json_name = "target" ]; - - // The list of APE chains. - repeated frostfs.v2.ape.Chain chains = 2 [ json_name = "chains" ]; - } - - // APE override for the target. - APEOverride ape_override = 5 [ json_name = "apeOverride" ]; + bool AllowImpersonate = 4 [json_name="allow_impersonate"]; } // Bearer Token body - Body body = 1 [ json_name = "body" ]; + Body body = 1 [json_name="body"]; // Signature of BearerToken body - neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ]; + neo.fs.v2.refs.Signature signature = 2 [json_name="signature"]; } diff --git a/ape/types.proto b/ape/types.proto deleted file mode 100644 index 2cbc5a9..0000000 --- a/ape/types.proto +++ /dev/null @@ -1,33 +0,0 @@ -edition = "2023"; - -package frostfs.v2.ape; - -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/ape/grpc;ape"; - -// TargetType is a type target to which a rule chain is defined. -enum TargetType { - UNDEFINED = 0; - - NAMESPACE = 1; - - CONTAINER = 2; - - USER = 3; - - GROUP = 4; -} - -// ChainTarget is an object to which a rule chain is defined. -message ChainTarget { - TargetType type = 1; - - string name = 2; -} - -// Chain is a chain of rules defined for a specific target. -message Chain { - oneof kind { - // Raw representation of a serizalized rule chain. - bytes raw = 1; - } -} diff --git a/apemanager/service.proto b/apemanager/service.proto deleted file mode 100644 index 64c2565..0000000 --- a/apemanager/service.proto +++ /dev/null @@ -1,171 +0,0 @@ -edition = "2023"; - -package frostfs.v2.apemanager; - -import "ape/types.proto"; -import "session/types.proto"; - -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager"; - -// `APEManagerService` provides API to manage rule chains within sidechain's -// `Policy` smart contract. -service APEManagerService { - // Add a rule chain for a specific target to `Policy` smart contract. - // - // Statuses: - // - **OK** (0, SECTION_SUCCESS): \ - // the chain has been successfully added; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // container (as target) not found; - // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \ - // the operation is denied by the service. - rpc AddChain(AddChainRequest) returns (AddChainResponse); - - // Remove a rule chain for a specific target from `Policy` smart contract. - // RemoveChain is an idempotent operation: removal of non-existing rule chain - // also means success. - // - // Statuses: - // - **OK** (0, SECTION_SUCCESS): \ - // the chain has been successfully removed; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // container (as target) not found; - // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \ - // the operation is denied by the service. - rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse); - - // List chains defined for a specific target from `Policy` smart contract. - // - // Statuses: - // - **OK** (0, SECTION_SUCCESS): \ - // chains have been successfully listed; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // container (as target) not found; - // - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \ - // the operation is denied by the service. - rpc ListChains(ListChainsRequest) returns (ListChainsResponse); -} - -message AddChainRequest { - message Body { - // A target for which a rule chain is added. - frostfs.v2.ape.ChainTarget target = 1; - - // The chain to set for the target. - frostfs.v2.ape.Chain chain = 2; - } - - // The request's body. - Body body = 1; - - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; - - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; -} - -message AddChainResponse { - message Body { - // Chain ID assigned for the added rule chain. - // If chain ID is left empty in the request, then - // it will be generated. - bytes chain_id = 1; - } - - // The response's body. - Body body = 1; - - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; -} - -message RemoveChainRequest { - message Body { - // Target for which a rule chain is removed. - frostfs.v2.ape.ChainTarget target = 1; - - // Chain ID assigned for the rule chain. - bytes chain_id = 2; - } - - // The request's body. - Body body = 1; - - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; - - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; -} - -message RemoveChainResponse { - // Since RemoveChain is an idempotent operation, then the only indicator that - // operation could not be performed is an error returning to a client. - message Body {} - - // The response's body. - Body body = 1; - - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; -} - -message ListChainsRequest { - message Body { - // Target for which rule chains are listed. - frostfs.v2.ape.ChainTarget target = 1; - } - - // The request's body. - Body body = 1; - - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; - - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; -} - -message ListChainsResponse { - message Body { - // The list of chains defined for the reqeusted target. - repeated frostfs.v2.ape.Chain chains = 1; - } - - // The response's body. - Body body = 1; - - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; -} diff --git a/audit/types.proto b/audit/types.proto new file mode 100644 index 0000000..156a31b --- /dev/null +++ b/audit/types.proto @@ -0,0 +1,59 @@ +syntax = "proto3"; + +package neo.fs.v2.audit; + +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/audit/grpc;audit"; +option csharp_namespace = "Neo.FileStorage.API.Audit"; + +import "refs/types.proto"; + +// DataAuditResult keeps record of conducted Data Audits. The detailed report is +// generated separately. +message DataAuditResult { + // Data Audit Result format version. Effectively, the version of API library + // used to report DataAuditResult structure. + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; + + // Epoch number when the Data Audit was conducted + fixed64 audit_epoch = 2 [json_name = "auditEpoch"]; + + // Container under audit + neo.fs.v2.refs.ContainerID container_id = 3 [json_name = "containerID"]; + + // Public key of the auditing InnerRing node in a binary format + bytes public_key = 4 [json_name = "publicKey"]; + + // Shows if Data Audit process was complete in time or if it was cancelled + bool complete = 5 [json_name = "complete"]; + + // Number of request done at PoR stage + uint32 requests = 6 [json_name = "requests"]; + + // Number of retries done at PoR stage + uint32 retries = 7 [json_name = "retries"]; + + // List of Storage Groups that passed audit PoR stage + repeated neo.fs.v2.refs.ObjectID pass_sg = 8 [json_name = "passSG"]; + + // List of Storage Groups that failed audit PoR stage + repeated neo.fs.v2.refs.ObjectID fail_sg = 9 [json_name = "failSG"]; + + // Number of sampled objects under the audit placed in an optimal way according to + // the containers placement policy when checking PoP + uint32 hit = 10 [json_name = "hit"]; + + // 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 + uint32 miss = 11 [json_name = "miss"]; + + // Number of sampled objects under the audit stored inconsistently with the + // placement policy or not found at all when checking PoP + uint32 fail = 12 [json_name = "fail"]; + + // List of storage node public keys that passed at least one PDP + repeated bytes pass_nodes = 13 [json_name = "passNodes"]; + + // List of storage node public keys that failed at least one PDP + repeated bytes fail_nodes = 14 [json_name = "failNodes"]; +} diff --git a/buf.yaml b/buf.yaml new file mode 100644 index 0000000..2006bea --- /dev/null +++ b/buf.yaml @@ -0,0 +1,10 @@ +lint: + use: + - DEFAULT + - COMMENTS + - ENUM_FIRST_VALUE_ZERO + except: + - PACKAGE_DIRECTORY_MATCH + - PACKAGE_VERSION_SUFFIX + - ENUM_VALUE_PREFIX + - ENUM_ZERO_VALUE_SUFFIX diff --git a/container/service.proto b/container/service.proto index 72b3789..249bfb1 100644 --- a/container/service.proto +++ b/container/service.proto @@ -1,43 +1,40 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.container; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container/grpc;container"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/container/grpc;container"; option csharp_namespace = "Neo.FileStorage.API.Container"; +import "acl/types.proto"; import "container/types.proto"; import "refs/types.proto"; import "session/types.proto"; // `ContainerService` provides API to interact with `Container` smart contract -// in FrostFS sidechain via other FrostFS nodes. All of those actions can be -// done equivalently by directly issuing transactions and RPC calls to sidechain +// in NeoFS sidechain via other NeoFS nodes. All of those actions can be done +// equivalently by directly issuing transactions and RPC calls to sidechain // nodes. service ContainerService { // `Put` invokes `Container` smart contract's `Put` method and returns // response immediately. After a new block is issued in sidechain, request is - // verified by Inner Ring nodes. After one more block in sidechain, the - // container is added into smart contract storage. + // verified by Inner Ring nodes. After one more block in sidechain, the container + // is added into smart contract storage. // // Statuses: // - **OK** (0, SECTION_SUCCESS): \ // request to save the container has been sent to the sidechain; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // container create access denied. + // - Common failures (SECTION_FAILURE_COMMON). rpc Put(PutRequest) returns (PutResponse); // `Delete` invokes `Container` smart contract's `Delete` method and returns // response immediately. After a new block is issued in sidechain, request is - // verified by Inner Ring nodes. After one more block in sidechain, the - // container is added into smart contract storage. + // verified by Inner Ring nodes. After one more block in sidechain, the container + // is added into smart contract storage. // // Statuses: // - **OK** (0, SECTION_SUCCESS): \ // request to remove the container has been sent to the sidechain; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // container delete access denied. + // - Common failures (SECTION_FAILURE_COMMON). rpc Delete(DeleteRequest) returns (DeleteResponse); // Returns container structure from `Container` smart contract storage. @@ -47,34 +44,50 @@ service ContainerService { // container has been successfully read; // - Common failures (SECTION_FAILURE_COMMON); // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // requested container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied. + // requested container not found. rpc Get(GetRequest) returns (GetResponse); - // Returns all owner's containers from `Container` smart contract storage. + // Returns all owner's containers from 'Container` smart contract' storage. // // Statuses: // - **OK** (0, SECTION_SUCCESS): \ // container list has been successfully read; - // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // container list access denied. + // - Common failures (SECTION_FAILURE_COMMON). rpc List(ListRequest) returns (ListResponse); - // Returns all owner's containers from `Container` smart contract storage - // via stream. + // Invokes 'SetEACL' method of 'Container` smart contract and returns response + // immediately. After one more block in sidechain, changes in an Extended ACL are + // added into smart contract storage. // // Statuses: // - **OK** (0, SECTION_SUCCESS): \ - // container list has been successfully read; + // request to save container eACL has been sent to the sidechain; + // - Common failures (SECTION_FAILURE_COMMON). + rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse); + + // Returns Extended ACL table and signature from `Container` smart contract + // storage. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): \ + // container eACL has been successfully read; // - Common failures (SECTION_FAILURE_COMMON); - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // container list access denied. - rpc ListStream(ListStreamRequest) returns (stream ListStreamResponse); + // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + // container not found; + // - **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \ + // eACL table not found. + rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse); + + // Announces the space values used by the container for P2P synchronization. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): \ + // estimation of used space has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). + rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse); } -// New FrostFS Container creation request +// New NeoFS Container creation request message PutRequest { // Container creation request has container structure's signature as a // separate field. It's not stored in sidechain, just verified on container @@ -82,7 +95,7 @@ message PutRequest { // the stable-marshalled container strucutre, hence there is no need for // additional signature checks. message Body { - // Container structure to register in FrostFS + // Container structure to register in NeoFS container.Container container = 1; // Signature of a stable-marshalled container according to RFC-6979. @@ -101,7 +114,7 @@ message PutRequest { neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } -// New FrostFS Container creation response +// New NeoFS Container creation response message PutResponse { // Container put response body contains information about the newly registered // container as seen by `Container` smart contract. `ContainerID` can be @@ -130,11 +143,10 @@ message DeleteRequest { // the container owner's intent. The signature will be verified by `Container` // smart contract, so signing algorithm must be supported by NeoVM. message Body { - // Identifier of the container to delete from FrostFS + // Identifier of the container to delete from NeoFS neo.fs.v2.refs.ContainerID container_id = 1; - // `ContainerID` signed with the container owner's key according to - // RFC-6979. + // `ContainerID` signed with the container owner's key according to RFC-6979. neo.fs.v2.refs.SignatureRFC6979 signature = 2; } // Body of container delete request message. @@ -257,14 +269,18 @@ message ListResponse { neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } -// List containers stream -message ListStreamRequest { - // List containers stream request body. +// Set Extended ACL +message SetExtendedACLRequest { + // Set Extended ACL request body does not have separate `ContainerID` + // reference. It will be taken from `EACLTable.container_id` field. message Body { - // Identifier of the container owner. - neo.fs.v2.refs.OwnerID owner_id = 1; + // Extended ACL table to set for the container + neo.fs.v2.acl.EACLTable eacl = 1; + + // Signature of stable-marshalled Extended ACL table according to RFC-6979. + neo.fs.v2.refs.SignatureRFC6979 signature = 2; } - // Body of list containers stream request message. + // Body of set extended acl request message. Body body = 1; // Carries request meta information. Header data is used only to regulate @@ -277,15 +293,117 @@ message ListStreamRequest { neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } -// List containers stream -message ListStreamResponse { - // List containers stream response body. - message Body { - // List of `ContainerID`s belonging to the requested `OwnerID` - repeated refs.ContainerID container_ids = 1; - } +// Set Extended ACL +message SetExtendedACLResponse { + // `SetExtendedACLResponse` has an empty body because the operation is + // asynchronous and the update should be reflected in `Container` smart contract's + // storage after next block is issued in sidechain. + message Body { } - // Body of list containers stream response message. + // Body of set extended acl response message. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} + +// Get Extended ACL +message GetExtendedACLRequest { + // Get Extended ACL request body + message Body { + // Identifier of the container having Extended ACL + neo.fs.v2.refs.ContainerID container_id = 1; + } + + // Body of get extended acl request message. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +// Get Extended ACL +message GetExtendedACLResponse { + // Get Extended ACL Response body can be empty if the requested container does + // not have Extended ACL Table attached or Extended ACL has not been allowed at + // the time of container creation. + message Body { + // Extended ACL requested, if available + neo.fs.v2.acl.EACLTable eacl = 1; + + // Signature of stable-marshalled Extended ACL according to RFC-6979. + neo.fs.v2.refs.SignatureRFC6979 signature = 2; + + // Session token if Extended ACL was set within a session + neo.fs.v2.session.SessionToken session_token = 3; + } + // Body of get extended acl response message. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} + +// Announce container used space +message AnnounceUsedSpaceRequest { + // Container used space announcement body. + message Body { + // Announcement contains used space information for a single container. + message Announcement { + // Epoch number for which the container size estimation was produced. + uint64 epoch = 1; + + // Identifier of the container. + neo.fs.v2.refs.ContainerID container_id = 2; + + // Used space is a sum of object payload sizes of a specified + // container, stored in the node. It must not include inhumed objects. + uint64 used_space = 3; + } + + // List of announcements. If nodes share several containers, + // announcements are transferred in a batch. + repeated Announcement announcements = 1; + } + + // Body of announce used space request message. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +// Announce container used space +message AnnounceUsedSpaceResponse { + // `AnnounceUsedSpaceResponse` has an empty body because announcements are + // one way communication. + message Body { } + + // Body of announce used space response message. Body body = 1; // Carries response meta information. Header data is used only to regulate diff --git a/container/types.proto b/container/types.proto index d114205..a735f74 100644 --- a/container/types.proto +++ b/container/types.proto @@ -1,8 +1,8 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.container; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container/grpc;container"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/container/grpc;container"; option csharp_namespace = "Neo.FileStorage.API.Container"; import "netmap/types.proto"; @@ -10,26 +10,26 @@ import "refs/types.proto"; // Container is a structure that defines object placement behaviour. Objects can // be stored only within containers. They define placement rule, attributes and -// access control information. An ID of a container is a 32 byte long SHA256 -// hash of stable-marshalled container message. +// access control information. An ID of a container is a 32 byte long SHA256 hash +// of stable-marshalled container message. message Container { // Container format version. Effectively, the version of API library used to // create the container. - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Identifier of the container owner - neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ]; + neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"]; // Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s - bytes nonce = 3 [ json_name = "nonce" ]; + bytes nonce = 3 [json_name = "nonce"]; - // `BasicACL` contains access control rules for the owner, system and others - // groups, as well as permission bits for `BearerToken` and `Extended ACL` - uint32 basic_acl = 4 [ json_name = "basicACL" ]; + // `BasicACL` contains access control rules for the owner, system and others groups, + // as well as permission bits for `BearerToken` and `Extended ACL` + uint32 basic_acl = 4 [json_name = "basicACL"]; // `Attribute` is a user-defined Key-Value metadata pair attached to the - // container. Container attributes are immutable. They are set at the moment - // of container creation and can never be added or updated. + // container. Container attributes are immutable. They are set at the moment of + // container creation and can never be added or updated. // // Key name must be a container-unique valid UTF-8 string. Value can't be // empty. Containers with duplicated attribute names or attributes with empty @@ -37,22 +37,21 @@ message Container { // // There are some "well-known" attributes affecting system behaviour: // - // * [ __SYSTEM__NAME ] \ - // (`__NEOFS__NAME` is deprecated) \ + // * __NEOFS__SUBNET \ + // String ID of a container's storage subnet. Any container can be attached to + // one subnet only. + // * __NEOFS__NAME \ // String of a human-friendly container name registered as a domain in // NNS contract. - // * [ __SYSTEM__ZONE ] \ - // (`__NEOFS__ZONE` is deprecated) \ - // String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated). - // Used as a TLD of a domain name in NNS contract. If no zone is specified, - // use default zone: `container`. - // * [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \ - // (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ - // Disables homomorphic hashing for the container if the value equals "true" - // string. Any other values are interpreted as missing attribute. Container - // could be accepted in a FrostFS network only if the global network hashing - // configuration value corresponds with that attribute's value. After - // container inclusion, network setting is ignored. + // * __NEOFS__ZONE \ + // String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS + // contract. If no zone is specified, use default zone: `container`. + // * __NEOFS__DISABLE_HOMOMORPHIC_HASHING \ + // Disables homomorphic hashing for the container if the value equals "true" string. + // Any other values are interpreted as missing attribute. Container could be + // accepted in a NeoFS network only if the global network hashing configuration + // value corresponds with that attribute's value. After container inclusion, network + // setting is ignored. // // And some well-known attributes used by applications only: // @@ -62,15 +61,14 @@ message Container { // User-defined local time of container creation in Unix Timestamp format message Attribute { // Attribute name key - string key = 1 [ json_name = "key" ]; + string key = 1 [json_name = "key"]; // Attribute value - string value = 2 [ json_name = "value" ]; + string value = 2 [json_name = "value"]; } // Attributes represent immutable container's meta data - repeated Attribute attributes = 5 [ json_name = "attributes" ]; + repeated Attribute attributes = 5 [json_name = "attributes"]; // Placement policy for the object inside the container - neo.fs.v2.netmap.PlacementPolicy placement_policy = 6 - [ json_name = "placementPolicy" ]; + neo.fs.v2.netmap.PlacementPolicy placement_policy = 6 [json_name = "placementPolicy"]; } diff --git a/doc/release_instructions.md b/doc/release_instructions.md index d4fb9d4..853b08a 100644 --- a/doc/release_instructions.md +++ b/doc/release_instructions.md @@ -1,6 +1,6 @@ # Release instructions -This documents outlines the frostfs-api release process and can be used as a TODO +This documents outlines the neofs-api release process and can be used as a TODO list for a new release. ## Pre-release checks @@ -20,7 +20,7 @@ Add an entry to the CHANGELOG.md following the style established there. Add a codename for releases with the new major version, version and release date in the heading. Write a paragraph describing the most significant changes done in this release. Then add sections with what has been added, changed and removed, -describing each change briefly with a reference to issues, where +describing each change briefly with a reference to GitHub issues, where available. ## Release commit @@ -38,7 +38,7 @@ Release v2.9.0 - Anmyeondo (안면도, 安眠島) Use `vX.Y.Z` tag following the semantic versioning standard. For pre-release versions use `vX.Y.Z-rc.N` scheme. -## Push changes and release tag to repository +## Push changes and release tag to Github This step should bypass the default PR mechanism to get a correct result (so that releasing requires admin privileges for the project), both the `master` @@ -48,9 +48,9 @@ branch update and tag must be pushed simultaneously like this: $ git push origin master v2.7.0 ``` -## Make a proper release +## Make a proper Github release -Edit an automatically-created release on git.frostfs.info +Edit an automatically-created release on Github. Release title has to follow ` ( )` scheme for major releases and just `` for regular point @@ -58,5 +58,6 @@ releases. ## Post-release actions -* Close corresponding X.Y.Z milestone +* Close corresponding X.Y.Z Github milestone * Make announcements in Matrix and Discord channels +* Update [NeoFS Technical Specification](https://github.com/nspcc-dev/neofs-spec) diff --git a/help.mk b/help.mk deleted file mode 100644 index a2ac989..0000000 --- a/help.mk +++ /dev/null @@ -1,11 +0,0 @@ -.PHONY: help - -# Show this help prompt -help: - @echo ' Usage:' - @echo '' - @echo ' make ' - @echo '' - @echo ' Targets:' - @echo '' - @awk '/^#/{ comment = substr($$0,3) } /^[a-zA-Z][a-zA-Z0-9_-]+:/{ print " ", $$1, comment; comment = "" }' $(MAKEFILE_LIST) | column -t -s ':' | grep -v 'IGNORE' | sort | uniq diff --git a/lock/types.proto b/lock/types.proto index dc55276..a2eb833 100644 --- a/lock/types.proto +++ b/lock/types.proto @@ -1,19 +1,18 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.lock; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/lock/grpc;lock"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/lock/grpc;lock"; option csharp_namespace = "Neo.FileStorage.API.Lock"; import "refs/types.proto"; // Lock objects protects a list of objects from being deleted. The lifetime of a // lock object is limited similar to regular objects in -// `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) -// attribute. Lock object MUST have expiration epoch. It is impossible to delete -// a lock object via ObjectService.Delete RPC call. +// `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch. +// It is impossible to delete a lock object via ObjectService.Delete RPC call. message Lock { // List of objects to lock. Must not be empty or carry empty IDs. // All members must be of the `REGULAR` type. - repeated neo.fs.v2.refs.ObjectID members = 1 [ json_name = "members" ]; + repeated neo.fs.v2.refs.ObjectID members = 1 [json_name = "members"]; } diff --git a/netmap/service.proto b/netmap/service.proto index c21fb53..922cc3e 100644 --- a/netmap/service.proto +++ b/netmap/service.proto @@ -1,53 +1,53 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.netmap; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap"; option csharp_namespace = "Neo.FileStorage.API.Netmap"; import "netmap/types.proto"; import "refs/types.proto"; import "session/types.proto"; -// `NetmapService` provides methods to work with `Network Map` and the -// information required to build it. The resulting `Network Map` is stored in -// sidechain `Netmap` smart contract, while related information can be obtained -// from other FrostFS nodes. +// `NetmapService` provides methods to work with `Network Map` and the information +// required to build it. The resulting `Network Map` is stored in sidechain +// `Netmap` smart contract, while related information can be obtained from other +// NeoFS nodes. service NetmapService { - // Get NodeInfo structure from the particular node directly. - // Node information can be taken from `Netmap` smart contract. In some cases, - // though, one may want to get recent information directly or to talk to the - // node not yet present in the `Network Map` to find out what API version can - // be used for further communication. This can be also used to check if a node - // is up and running. + // Get NodeInfo structure from the particular node directly. + // Node information can be taken from `Netmap` smart contract. In some cases, though, + // one may want to get recent information directly or to talk to the node not yet + // present in the `Network Map` to find out what API version can be used for + // further communication. This can be also used to check if a node is up and running. // // Statuses: // - **OK** (0, SECTION_SUCCESS): // information about the server has been successfully read; // - Common failures (SECTION_FAILURE_COMMON). - rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); + rpc LocalNodeInfo (LocalNodeInfoRequest) returns (LocalNodeInfoResponse); - // Read recent information about the FrostFS network. + // Read recent information about the NeoFS network. // // Statuses: // - **OK** (0, SECTION_SUCCESS): // information about the current network state has been successfully read; // - Common failures (SECTION_FAILURE_COMMON). - rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse); + rpc NetworkInfo (NetworkInfoRequest) returns (NetworkInfoResponse); - // Returns network map snapshot of the current FrostFS epoch. + // Returns network map snapshot of the current NeoFS epoch. // // Statuses: // - **OK** (0, SECTION_SUCCESS): // information about the current network map has been successfully read; // - Common failures (SECTION_FAILURE_COMMON). - rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse); + rpc NetmapSnapshot (NetmapSnapshotRequest) returns (NetmapSnapshotResponse); } // Get NodeInfo structure directly from a particular node message LocalNodeInfoRequest { // LocalNodeInfo request body is empty. - message Body {} + message Body { + } // Body of the LocalNodeInfo request message Body body = 1; @@ -65,7 +65,7 @@ message LocalNodeInfoRequest { message LocalNodeInfoResponse { // Local Node Info, including API Version in use. message Body { - // Latest FrostFS API version in use + // Latest NeoFS API version in use neo.fs.v2.refs.Version version = 1; // NodeInfo structure with recent information from node itself @@ -86,77 +86,81 @@ message LocalNodeInfoResponse { // Get NetworkInfo structure with the network view from a particular node. message NetworkInfoRequest { - // NetworkInfo request body is empty. - message Body {} - // Body of the NetworkInfo request message - Body body = 1; + // NetworkInfo request body is empty. + message Body { + } + // Body of the NetworkInfo request message + Body body = 1; - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Response with NetworkInfo structure including current epoch and // sidechain magic number. message NetworkInfoResponse { - // Information about the network. - message Body { - // NetworkInfo structure with recent information. - NetworkInfo network_info = 1; - } - // Body of the NetworkInfo response message. - Body body = 1; + // Information about the network. + message Body { + // NetworkInfo structure with recent information. + NetworkInfo network_info = 1; + } + // Body of the NetworkInfo response message. + Body body = 1; - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect response execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect response execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } // Get netmap snapshot request message NetmapSnapshotRequest { - // Get netmap snapshot request body. - message Body {} + // Get netmap snapshot request body. + message Body { + } - // Body of get netmap snapshot request message. - Body body = 1; + // Body of get netmap snapshot request message. + Body body = 1; - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; } // Response with current netmap snapshot message NetmapSnapshotResponse { - // Get netmap snapshot response body - message Body { - // Structure of the requested network map. - Netmap netmap = 1 [ json_name = "netmap" ]; - } + // Get netmap snapshot response body + message Body { + // Structure of the requested network map. + Netmap netmap = 1 [json_name = "netmap"]; + } - // Body of get netmap snapshot response message. - Body body = 1; + // Body of get netmap snapshot response message. + Body body = 1; - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect response execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect response execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } diff --git a/netmap/types.proto b/netmap/types.proto index b76b3c1..e4b5e6d 100644 --- a/netmap/types.proto +++ b/netmap/types.proto @@ -1,10 +1,12 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.netmap; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap"; option csharp_namespace = "Neo.FileStorage.API.Netmap"; +import "refs/types.proto"; + // Operations on filters enum Operation { // No Operation defined @@ -33,12 +35,6 @@ enum Operation { // Logical AND AND = 8; - - // Logical negation - NOT = 9; - - // Matches pattern - LIKE = 10; } // Selector modifier shows how the node set will be formed. By default selector @@ -55,46 +51,46 @@ enum Clause { DISTINCT = 2; } -// This filter will return the subset of nodes from `NetworkMap` or another -// filter's results that will satisfy filter's conditions. +// This filter will return the subset of nodes from `NetworkMap` or another filter's +// results that will satisfy filter's conditions. message Filter { // Name of the filter or a reference to a named filter. '*' means // application to the whole unfiltered NetworkMap. At top level it's used as a // filter name. At lower levels it's considered to be a reference to another // named filter - string name = 1 [ json_name = "name" ]; + string name = 1 [json_name = "name"]; // Key to filter - string key = 2 [ json_name = "key" ]; + string key = 2 [json_name = "key"]; // Filtering operation - Operation op = 3 [ json_name = "op" ]; + Operation op = 3 [json_name = "op"]; // Value to match - string value = 4 [ json_name = "value" ]; + string value = 4 [json_name = "value"]; // List of inner filters. Top level operation will be applied to the whole // list. - repeated Filter filters = 5 [ json_name = "filters" ]; + repeated Filter filters = 5 [json_name = "filters"]; } // Selector chooses a number of nodes from the bucket taking the nearest nodes // to the provided `ContainerID` by hash distance. message Selector { // Selector name to reference in object placement section - string name = 1 [ json_name = "name" ]; + string name = 1 [json_name = "name"]; // How many nodes to select from the bucket - uint32 count = 2 [ json_name = "count" ]; + uint32 count = 2 [json_name = "count"]; // Selector modifier showing how to form a bucket - Clause clause = 3 [ json_name = "clause" ]; + Clause clause = 3 [json_name = "clause"]; // Bucket attribute to select from - string attribute = 4 [ json_name = "attribute" ]; + string attribute = 4 [json_name = "attribute"]; // Filter reference to select from - string filter = 5 [ json_name = "filter" ]; + string filter = 5 [json_name = "filter"]; } // Number of object replicas in a set of nodes from the defined selector. If no @@ -102,16 +98,10 @@ message Selector { // default. message Replica { // How many object replicas to put - uint32 count = 1 [ json_name = "count" ]; + uint32 count = 1 [json_name = "count"]; // Named selector bucket to put replicas - string selector = 2 [ json_name = "selector" ]; - - // Data shards count - uint32 ec_data_count = 3 [ json_name = "ecDataCount" ]; - - // Parity shards count - uint32 ec_parity_count = 4 [ json_name = "ecParityCount" ]; + string selector = 2 [json_name = "selector"]; } // Set of rules to select a subset of nodes from `NetworkMap` able to store @@ -120,45 +110,46 @@ message Replica { message PlacementPolicy { // Rules to set number of object replicas and place each one into a named // bucket - repeated Replica replicas = 1 [ json_name = "replicas" ]; + repeated Replica replicas = 1 [json_name = "replicas"]; - // Container backup factor controls how deep FrostFS will search for nodes + // Container backup factor controls how deep NeoFS will search for nodes // alternatives to include into container's nodes subset - uint32 container_backup_factor = 2 [ json_name = "containerBackupFactor" ]; + uint32 container_backup_factor = 2 [json_name = "containerBackupFactor"]; // Set of Selectors to form the container's nodes subset - repeated Selector selectors = 3 [ json_name = "selectors" ]; + repeated Selector selectors = 3 [json_name = "selectors"]; // List of named filters to reference in selectors - repeated Filter filters = 4 [ json_name = "filters" ]; + repeated Filter filters = 4 [json_name = "filters"]; - // Unique flag defines non-overlapping application for replicas - bool unique = 5 [ json_name = "unique" ]; + // Subnetwork ID to select nodes from. Zero subnet (default) represents + // all of the nodes which didn't explicitly opt out of membership. + refs.SubnetID subnet_id = 5 [json_name = "subnetId"]; } -// FrostFS node description +// NeoFS node description message NodeInfo { - // Public key of the FrostFS node in a binary format - bytes public_key = 1 [ json_name = "publicKey" ]; + // Public key of the NeoFS node in a binary format + bytes public_key = 1 [json_name = "publicKey"]; // Ways to connect to a node - repeated string addresses = 2 [ json_name = "addresses" ]; + repeated string addresses = 2 [json_name = "addresses"]; - // Administrator-defined Attributes of the FrostFS Storage Node. + // Administrator-defined Attributes of the NeoFS Storage Node. // // `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8 // string. Value can't be empty. // // Attributes can be constructed into a chain of attributes: any attribute can - // have a parent attribute and a child attribute (except the first and the - // last one). A string representation of the chain of attributes in FrostFS - // Storage Node configuration uses ":" and "/" symbols, e.g.: + // have a parent attribute and a child attribute (except the first and the last + // one). A string representation of the chain of attributes in NeoFS Storage + // Node configuration uses ":" and "/" symbols, e.g.: // - // `FrostFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` + // `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` // - // Therefore the string attribute representation in the Node configuration - // must use "\:", "\/" and "\\" escaped symbols if any of them appears in an - // attribute's key or value. + // Therefore the string attribute representation in the Node configuration must + // use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's + // key or value. // // Node's attributes are mostly used during Storage Policy evaluation to // calculate object's placement and find a set of nodes satisfying policy @@ -173,6 +164,13 @@ message NodeInfo { // attributes it's a string presenting floating point number with comma or // point delimiter for decimal part. In the Network Map it will be saved as // 64-bit unsigned integer representing number of minimal token fractions. + // * __NEOFS__SUBNET_%s \ + // `True` or `False`. Defines if the node is included in the `%s` subnetwork + // or not. `%s` must be an existing subnetwork's ID (non-negative integer number). + // A node can be included in more than one subnetwork and, therefore, can contain + // more than one subnet attribute. A missing attribute is equivalent to the + // presence of the attribute with `False` value (except default zero subnetwork + // (with `%s` == 0) for which missing attribute means inclusion in that network). // * UN-LOCODE \ // Node's geographic location in // [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html) @@ -201,8 +199,8 @@ message NodeInfo { // [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated // automatically from `UN-LOCODE` attribute. // * Continent \ - // Node's continent name according to the [Seven-Continent - // model](https://en.wikipedia.org/wiki/Continent#Number). Calculated + // Node's continent name according to the [Seven-Continent model] + // (https://en.wikipedia.org/wiki/Continent#Number). Calculated // automatically from `UN-LOCODE` attribute. // * ExternalAddr // Node's preferred way for communications with external clients. @@ -210,25 +208,25 @@ message NodeInfo { // Must contain a comma-separated list of multi-addresses. // // For detailed description of each well-known attribute please see the - // corresponding section in FrostFS Technical Specification. + // corresponding section in NeoFS Technical Specification. message Attribute { // Key of the node attribute - string key = 1 [ json_name = "key" ]; + string key = 1 [json_name = "key"]; // Value of the node attribute - string value = 2 [ json_name = "value" ]; + string value = 2 [json_name = "value"]; // Parent keys, if any. For example for `City` it could be `Region` and // `Country`. - repeated string parents = 3 [ json_name = "parents" ]; + repeated string parents = 3 [json_name = "parents"]; } - // Carries list of the FrostFS node attributes in a key-value form. Key name + // Carries list of the NeoFS node attributes in a key-value form. Key name // must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo // structures with duplicated attribute names or attributes with empty values // will be considered invalid. - repeated Attribute attributes = 3 [ json_name = "attributes" ]; + repeated Attribute attributes = 3 [json_name = "attributes"]; - // Represents the enumeration of various states of the FrostFS node. + // Represents the enumeration of various states of the NeoFS node. enum State { // Unknown state UNSPECIFIED = 0; @@ -243,20 +241,20 @@ message NodeInfo { MAINTENANCE = 3; } - // Carries state of the FrostFS node - State state = 4 [ json_name = "state" ]; + // Carries state of the NeoFS node + State state = 4 [json_name = "state"]; } // Network map structure message Netmap { - // Network map revision number. - uint64 epoch = 1 [ json_name = "epoch" ]; + // Network map revision number. + uint64 epoch = 1 [json_name = "epoch"]; - // Nodes presented in network. - repeated NodeInfo nodes = 2 [ json_name = "nodes" ]; + // Nodes presented in network. + repeated NodeInfo nodes = 2 [json_name = "nodes"]; } -// FrostFS network configuration +// NeoFS network configuration message NetworkConfig { // Single configuration parameter. Key MUST be network-unique. // @@ -274,8 +272,15 @@ message NetworkConfig { // - **ContainerFee** \ // Fee paid for container creation by the container owner. // Value: little-endian integer. Default: 0. + // - **EigenTrustAlpha** \ + // Alpha parameter of EigenTrust algorithm used in the Reputation system. + // Value: decimal floating-point number in UTF-8 string representation. + // Default: 0. + // - **EigenTrustIterations** \ + // Number of EigenTrust algorithm iterations to pass in the Reputation system. + // Value: little-endian integer. Default: 0. // - **EpochDuration** \ - // FrostFS epoch duration measured in Sidechain blocks. + // NeoFS epoch duration measured in Sidechain blocks. // Value: little-endian integer. Default: 0. // - **HomomorphicHashingDisabled** \ // Flag of disabling the homomorphic hashing of objects' payload. @@ -287,71 +292,33 @@ message NetworkConfig { // Flag allowing setting the MAINTENANCE state to storage nodes. // Value: true if any byte != 0. Default: false. // - **MaxObjectSize** \ - // Maximum size of physically stored FrostFS object measured in bytes. + // Maximum size of physically stored NeoFS object measured in bytes. // Value: little-endian integer. Default: 0. - // - // This value refers to the maximum size of a **physically** stored object - // in FrostFS. However, from a user's perspective, the **logical** size of a - // stored object can be significantly larger. The relationship between the - // physical and logical object sizes is governed by the following formula - // - // ```math - // \mathrm{Stored\ Object\ Size} \le - // \frac{ - // \left(\mathrm{Max\ Object\ Size}\right)^2 - // }{ - // \mathrm{Object\ ID\ Size} - // } - // ``` - // - // This arises from the fact that a tombstone, also being an object, stores - // the IDs of inhumed objects and cannot be divided into smaller objects, - // thus having an upper limit for its size. - // - // For example, if: - // * Max Object Size Size = 64 MiB; - // * Object ID Size = 32 B; - // - // then: - // ```math - // \mathrm{Stored\ Object\ Size} \le - // \frac{\left(64\ \mathrm{MiB}\right)^2}{32\ \mathrm{B}} = - // \frac{2^{52}}{2^5}\ \mathrm{B} = - // 2^{47}\ \mathrm{B} = - // 128\ \mathrm{TiB} - // ``` // - **WithdrawFee** \ // Fee paid for withdrawal of funds paid by the account owner. // Value: little-endian integer. Default: 0. - // - **MaxECDataCount** \ - // Maximum number of data shards for EC placement policy. - // Value: little-endian integer. Default: 0. - // - **MaxECParityCount** \ - // Maximum number of parity shards for EC placement policy. - // Value: little-endian integer. Default: 0. message Parameter { // Parameter key. UTF-8 encoded string - bytes key = 1 [ json_name = "key" ]; + bytes key = 1 [json_name = "key"]; // Parameter value - bytes value = 2 [ json_name = "value" ]; + bytes value = 2 [json_name = "value"]; } // List of parameter values - repeated Parameter parameters = 1 [ json_name = "parameters" ]; + repeated Parameter parameters = 1 [json_name = "parameters"]; } -// Information about FrostFS network +// Information about NeoFS network message NetworkInfo { - // Number of the current epoch in the FrostFS network - uint64 current_epoch = 1 [ json_name = "currentEpoch" ]; + // Number of the current epoch in the NeoFS network + uint64 current_epoch = 1 [json_name = "currentEpoch"]; - // Magic number of the sidechain of the FrostFS network - uint64 magic_number = 2 [ json_name = "magicNumber" ]; + // Magic number of the sidechain of the NeoFS network + uint64 magic_number = 2 [json_name = "magicNumber"]; - // MillisecondsPerBlock network parameter of the sidechain of the FrostFS - // network - int64 ms_per_block = 3 [ json_name = "msPerBlock" ]; + // MillisecondsPerBlock network parameter of the sidechain of the NeoFS network + int64 ms_per_block = 3 [json_name = "msPerBlock"]; - // FrostFS network configuration - NetworkConfig network_config = 4 [ json_name = "networkConfig" ]; + // NeoFS network configuration + NetworkConfig network_config = 4 [json_name = "networkConfig"]; } diff --git a/object/service.proto b/object/service.proto index c5e4fc7..7170b31 100644 --- a/object/service.proto +++ b/object/service.proto @@ -1,8 +1,8 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.object; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/object/grpc;object"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/object/grpc;object"; option csharp_namespace = "Neo.FileStorage.API.Object"; import "object/types.proto"; @@ -13,23 +13,20 @@ import "session/types.proto"; // not affect the sidechain and are only served by nodes in p2p style. service ObjectService { // Receive full object structure, including Headers and payload. Response uses - // gRPC stream. First response message carries the object with the requested - // address. Chunk messages are parts of the object's payload if it is needed. - // All messages, except the first one, carry payload chunks. The requested - // object can be restored by concatenation of object message payload and all - // chunks keeping the receiving order. + // gRPC stream. First response message carries the object with the requested address. + // Chunk messages are parts of the object's payload if it is needed. All + // messages, except the first one, carry payload chunks. The requested object can + // be restored by concatenation of object message payload and all chunks + // keeping the receiving order. // // Extended headers can change `Get` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ + // * __NEOFS__NETMAP_EPOCH \ // Will use the requsted version of Network Map for object placement // calculation. - // * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - // (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ - // Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH` - // (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one - // otherwise) of Network Map to find an object until the depth limit is - // reached. + // * __NEOFS__NETMAP_LOOKUP_DEPTH \ + // Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or + // the latest one otherwise) of Network Map to find an object until the depth + // limit is reached. // // Please refer to detailed `XHeader` description. // @@ -45,8 +42,6 @@ service ObjectService { // the requested object has been marked as deleted; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc Get(GetRequest) returns (stream GetResponse); @@ -59,8 +54,7 @@ service ObjectService { // Chunk messages SHOULD be sent in the direct order of fragmentation. // // Extended headers can change `Put` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ + // * __NEOFS__NETMAP_EPOCH \ // Will use the requsted version of Network Map for object placement // calculation. // @@ -73,18 +67,15 @@ service ObjectService { // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ // write access to the container is denied; // - **LOCKED** (2050, SECTION_OBJECT): \ - // placement of an object of type TOMBSTONE that includes at least one - // locked object is prohibited; + // placement of an object of type TOMBSTONE that includes at least one locked + // object is prohibited; // - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ // placement of an object of type LOCK that includes at least one object of // type other than REGULAR is prohibited; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object storage container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - // (for trusted object preparation) session private key does not exist or - // has + // (for trusted object preparation) session private key does not exist or has // been deleted; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. @@ -94,9 +85,8 @@ service ObjectService { // guarantee. Object will be marked for removal and deleted eventually. // // Extended headers can change `Delete` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement + // * __NEOFS__NETMAP_EPOCH \ + // Will use the requsted version of Network Map for object placement // calculation. // // Please refer to detailed `XHeader` description. @@ -107,15 +97,10 @@ service ObjectService { // - Common failures (SECTION_FAILURE_COMMON); // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ // delete access to the object is denied; - // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ - // the object could not be deleted because it has not been \ - // found within the container; // - **LOCKED** (2050, SECTION_OBJECT): \ // deleting a locked object is prohibited; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc Delete(DeleteRequest) returns (DeleteResponse); @@ -124,13 +109,9 @@ service ObjectService { // returned. If `main_only` request field is set, the short header with only // the very minimal information will be returned instead. // - // Max header size is currently not limited by this API, but may be restricted - // on the service level. By default, gRPC uses a message size of 4 MiB. - // // Extended headers can change `Head` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement + // * __NEOFS__NETMAP_EPOCH \ + // Will use the requsted version of Network Map for object placement // calculation. // // Please refer to detailed `XHeader` description. @@ -147,20 +128,17 @@ service ObjectService { // the requested object has been marked as deleted; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc Head(HeadRequest) returns (HeadResponse); // Search objects in container. Search query allows to match by Object - // Header's filed values. Please see the corresponding FrostFS Technical + // Header's filed values. Please see the corresponding NeoFS Technical // Specification section for more details. // // Extended headers can change `Search` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement + // * __NEOFS__NETMAP_EPOCH \ + // Will use the requsted version of Network Map for object placement // calculation. // // Please refer to detailed `XHeader` description. @@ -173,24 +151,20 @@ service ObjectService { // access to operation SEARCH of the object is denied; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // search container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc Search(SearchRequest) returns (stream SearchResponse); // Get byte range of data payload. Range is set as an (offset, length) tuple. // Like in `Get` method, the response uses gRPC stream. Requested range can be - // restored by concatenation of all received payload chunks keeping the - // receiving order. + // restored by concatenation of all received payload chunks keeping the receiving + // order. // // Extended headers can change `GetRange` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement + // * __NEOFS__NETMAP_EPOCH \ + // Will use the requsted version of Network Map for object placement // calculation. - // * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - // (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ + // * __NEOFS__NETMAP_LOOKUP_DEPTH \ // Will try older versions of Network Map to find an object until the depth // limit is reached. // @@ -210,8 +184,6 @@ service ObjectService { // the requested range is out of bounds; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); @@ -222,12 +194,10 @@ service ObjectService { // the request. Note that hash is calculated for XORed data. // // Extended headers can change `GetRangeHash` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH ] \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement + // * __NEOFS__NETMAP_EPOCH \ + // Will use the requsted version of Network Map for object placement // calculation. - // * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - // (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ + // * __NEOFS__NETMAP_LOOKUP_DEPTH \ // Will try older versions of Network Map to find an object until the depth // limit is reached. // @@ -245,96 +215,9 @@ service ObjectService { // the requested range is out of bounds; // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // object container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // provided session token has expired. rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); - - // Put the prepared object into container. - // `ContainerID`, `ObjectID`, `OwnerID`, `PayloadHash` and `PayloadLength` of - // an object MUST be set. - // - // Extended headers can change `Put` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requested version of Network Map for object placement - // calculation. - // - // Please refer to detailed `XHeader` description. - // - // Statuses: - // - **OK** (0, SECTION_SUCCESS): \ - // object has been successfully saved in the container; - // - Common failures (SECTION_FAILURE_COMMON); - // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - // write access to the container is denied; - // - **LOCKED** (2050, SECTION_OBJECT): \ - // placement of an object of type TOMBSTONE that includes at least one - // locked object is prohibited; - // - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ - // placement of an object of type LOCK that includes at least one object of - // type other than REGULAR is prohibited; - // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // object storage container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; - // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - // (for trusted object preparation) session private key does not exist or - // has - // been deleted; - // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - // provided session token has expired. - rpc PutSingle(PutSingleRequest) returns (PutSingleResponse); - - // Patch the object. Request uses gRPC stream. First message must set - // the address of the object that is going to get patched. If the object's - // attributes are patched, then these attrubutes must be set only within the - // first stream message. - // - // If the patch request is performed by NOT the object's owner but if the - // actor has the permission to perform the patch, then `OwnerID` of the object - // is changed. In this case the object's owner loses the object's ownership - // after the patch request is successfully done. - // - // As objects are content-addressable the patching causes new object ID - // generation for the patched object. This object id is set witihn - // `PatchResponse`. But the object id may remain unchanged in such cases: - // 1. The chunk of the applying patch contains the same value as the object's - // payload within the same range; - // 2. The patch that reverts the changes applied by preceding patch; - // 3. The application of the same patches for the object a few times. - // - // Extended headers can change `Patch` behaviour: - // * [ __SYSTEM__NETMAP_EPOCH \ - // (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - // Will use the requsted version of Network Map for object placement - // calculation. - // - // Please refer to detailed `XHeader` description. - // - // Statuses: - // - **OK** (0, SECTION_SUCCESS): \ - // object has been successfully patched and saved in the container; - // - Common failures (SECTION_FAILURE_COMMON); - // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - // write access to the container is denied; - // - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ - // object not found in container; - // - **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ - // the requested object has been marked as deleted. - // - **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ - // the requested range is out of bounds; - // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - // object storage container not found; - // - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - // access to container is denied; - // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - // (for trusted object preparation) session private key does not exist or - // has been deleted; - // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - // provided session token has expired. - rpc Patch(stream PatchRequest) returns (PatchResponse); } // GET object request @@ -387,9 +270,6 @@ message GetResponse { // Meta information of split hierarchy for object assembly. SplitInfo split_info = 3; - - // Meta information for EC object assembly. - ECInfo ec_info = 4; } } // Body of get object response message. @@ -421,17 +301,9 @@ message PutRequest { // Object's Header Header header = 3; - // Number of copies of the object to store within the RPC call. By - // default, object is processed according to the container's placement - // policy. Can be one of: - // 1. A single number; applied to the whole request and is treated as - // a minimal number of nodes that must store an object to complete the - // request successfully. - // 2. An ordered array; every number is treated as a minimal number of - // nodes in a corresponding placement vector that must store an object - // to complete the request successfully. The length MUST equal the - // placement vectors number, otherwise request is considered malformed. - repeated uint32 copies_number = 4; + // Number of the object copies to store within the RPC call. By default + // object is processed according to the container's placement policy. + uint32 copies_number = 4; } // Single message in the request stream. oneof object_part { @@ -481,7 +353,7 @@ message DeleteRequest { message Body { // Address of the object to be deleted neo.fs.v2.refs.Address address = 1; - } + } // Body of delete object request message. Body body = 1; @@ -553,10 +425,10 @@ message HeadRequest { // 3. Check if `ObjectID` signature in `signature` field is correct message HeaderWithSignature { // Full object header - Header header = 1 [ json_name = "header" ]; + Header header = 1 [json_name = "header"]; // Signed `ObjectID` to verify full header's authenticity - neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ]; + neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"]; } // Object HEAD response @@ -565,7 +437,7 @@ message HeadResponse { message Body { // Requested object header, it's part or meta information about split // object. - oneof head { + oneof head{ // Full object's `Header` with `ObjectID` signature HeaderWithSignature header = 1; @@ -573,11 +445,7 @@ message HeadResponse { ShortHeader short_header = 2; // Meta information of split hierarchy. - // Indicates that the object is virtual, manual assembly is required. SplitInfo split_info = 3; - - // Meta information for EC object assembly. - ECInfo ec_info = 4; } } // Body of head object response message. @@ -602,11 +470,11 @@ message SearchRequest { // Version of the Query Language used uint32 version = 2; - // Filter structure checks if the object header field or the attribute - // content matches a value. + // Filter structure checks if the object header field or the attribute content + // matches a value. // // If no filters are set, search request will return all objects of the - // container, including Regular object and Tombstone + // container, including Regular object, Tombstones and Storage Group // objects. Most human users expect to get only object they can directly // work with. In that case, `$Object:ROOT` filter should be used. // @@ -636,19 +504,16 @@ message SearchRequest { // object_id of parent // * $Object:split.splitID \ // 16 byte UUIDv4 used to identify the split object hierarchy parts - // * $Object:ec.parent \ - // If the object is stored according to EC policy, then ec_parent - // attribute is set to return an id list of all related EC chunks. // // There are some well-known filter aliases to match objects by certain // properties: // // * $Object:ROOT \ - // Returns only `REGULAR` type objects that are not split or that are the - // top level root objects in a split hierarchy. This includes objects not + // Returns only `REGULAR` type objects that are not split or that are the top + // level root objects in a split hierarchy. This includes objects not // present physically, like large objects split into smaller objects // without a separate top-level root object. Objects of other types like - // Locks and Tombstones will not be shown. This filter may be + // StorageGroups and Tombstones will not be shown. This filter may be // useful for listing objects like `ls` command of some virtual file // system. This filter is activated if the `key` exists, disregarding the // value and matcher type. @@ -657,17 +522,17 @@ message SearchRequest { // activated if the `key` exists, disregarding the value and matcher type. // // Note: using filters with a key with prefix `$Object:` and match type - // `NOT_PRESENT `is not recommended since this is not a cross-version - // approach. Behavior when processing this kind of filters is undefined. + // `NOT_PRESENT `is not recommended since this is not a cross-version approach. + // Behavior when processing this kind of filters is undefined. message Filter { // Match type to use - MatchType match_type = 1 [ json_name = "matchType" ]; + MatchType match_type = 1 [json_name = "matchType"]; // Attribute or Header fields to match - string key = 2 [ json_name = "key" ]; + string key = 2 [json_name = "key"]; // Value to match - string value = 3 [ json_name = "value" ]; + string value = 3 [json_name = "value"]; } // List of search expressions repeated Filter filters = 3; @@ -750,15 +615,12 @@ message GetRangeResponse { // chunks. message Body { // Requested object range or meta information about split object. - oneof range_part { + oneof range_part{ // Chunked object payload's range. bytes chunk = 1; // Meta information of split hierarchy. SplitInfo split_info = 2; - - // Meta information for EC object assembly. - ECInfo ec_info = 3; } } @@ -826,122 +688,3 @@ message GetRangeHashResponse { // transmission. neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; } - -// Object PUT Single request -message PutSingleRequest { - // PUT Single request body - message Body { - // Prepared object with payload. - Object object = 1; - // Number of copies of the object to store within the RPC call. By default, - // object is processed according to the container's placement policy. - // Every number is treated as a minimal number of - // nodes in a corresponding placement vector that must store an object - // to complete the request successfully. The length MUST equal the placement - // vectors number, otherwise request is considered malformed. - repeated uint32 copies_number = 2; - } - // Body of put single object request message. - Body body = 1; - - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; - - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; -} - -// Object PUT Single response -message PutSingleResponse { - // PUT Single Object response body - message Body {} - // Body of put single object response message. - Body body = 1; - - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; -} - -// Object PATCH request -message PatchRequest { - // PATCH request body - message Body { - // The address of the object that is requested to get patched. - neo.fs.v2.refs.Address address = 1; - - // New attributes for the object. See `replace_attributes` flag usage to - // define how new attributes should be set. - repeated neo.fs.v2.object.Header.Attribute new_attributes = 2; - - // If this flag is set, then the object's attributes will be entirely - // replaced by `new_attributes` list. The empty `new_attributes` list with - // `replace_attributes = true` just resets attributes list for the object. - // - // Default `false` value for this flag means the attributes will be just - // merged. If the incoming `new_attributes` list contains already existing - // key, then it just replaces it while merging the lists. - bool replace_attributes = 3; - - // New split header for the object. This defines how the object will relate - // to other objects in a split operation. - neo.fs.v2.object.Header.Split new_split_header = 5; - - // The patch for the object's payload. - message Patch { - // The range of the source object for which the payload is replaced by the - // patch's chunk. If the range's `length = 0`, then the patch's chunk is - // just appended to the original payload starting from the `offest` - // without any replace. - Range source_range = 1; - - // The chunk that is being appended to or that replaces the original - // payload on the given range. - bytes chunk = 2; - } - - // The patch that is applied for the object. - Patch patch = 4; - } - - // Body for patch request message. - Body body = 1; - - // Carries request meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.RequestMetaHeader meta_header = 2; - - // Carries request verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.RequestVerificationHeader verify_header = 3; -} - -// Object PATCH response -message PatchResponse { - // PATCH response body - message Body { - // The object ID of the saved patched object. - neo.fs.v2.refs.ObjectID object_id = 1; - } - - // Body for patch response message. - Body body = 1; - - // Carries response meta information. Header data is used only to regulate - // message transport and does not affect request execution. - neo.fs.v2.session.ResponseMetaHeader meta_header = 2; - - // Carries response verification information. This header is used to - // authenticate the nodes of the message route and check the correctness of - // transmission. - neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; -} diff --git a/object/types.proto b/object/types.proto index 62a6792..78ed3c5 100644 --- a/object/types.proto +++ b/object/types.proto @@ -1,20 +1,21 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.object; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/object/grpc;object"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/object/grpc;object"; option csharp_namespace = "Neo.FileStorage.API.Object"; import "refs/types.proto"; import "session/types.proto"; // Type of the object payload content. Only `REGULAR` type objects can be split, -// hence `TOMBSTONE` and `LOCK` payload is limited by the -// maximum object size. +// hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum +// object size. // // String presentation of object type is the same as definition: // * REGULAR // * TOMBSTONE +// * STORAGE_GROUP // * LOCK enum ObjectType { // Just a normal object @@ -23,8 +24,8 @@ enum ObjectType { // Used internally to identify deleted objects TOMBSTONE = 1; - // Unused (previously storageGroup information) - // _ = 2; + // StorageGroup information + STORAGE_GROUP = 2; // Object lock LOCK = 3; @@ -52,62 +53,59 @@ enum MatchType { message ShortHeader { // Object format version. Effectively, the version of API library used to // create particular object. - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Epoch when the object was created - uint64 creation_epoch = 2 [ json_name = "creationEpoch" ]; + uint64 creation_epoch = 2 [json_name = "creationEpoch"]; // Object's owner - neo.fs.v2.refs.OwnerID owner_id = 3 [ json_name = "ownerID" ]; + neo.fs.v2.refs.OwnerID owner_id = 3 [json_name = "ownerID"]; // Type of the object payload content - ObjectType object_type = 4 [ json_name = "objectType" ]; + ObjectType object_type = 4 [json_name = "objectType"]; // Size of payload in bytes. // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown - uint64 payload_length = 5 [ json_name = "payloadLength" ]; + uint64 payload_length = 5 [json_name = "payloadLength"]; // Hash of payload bytes - neo.fs.v2.refs.Checksum payload_hash = 6 [ json_name = "payloadHash" ]; + neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"]; // Homomorphic hash of the object payload - neo.fs.v2.refs.Checksum homomorphic_hash = 7 - [ json_name = "homomorphicHash" ]; + neo.fs.v2.refs.Checksum homomorphic_hash = 7 [json_name = "homomorphicHash"]; } // Object Header message Header { // Object format version. Effectively, the version of API library used to // create particular object - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Object's container - neo.fs.v2.refs.ContainerID container_id = 2 [ json_name = "containerID" ]; + neo.fs.v2.refs.ContainerID container_id = 2 [json_name = "containerID"]; // Object's owner - neo.fs.v2.refs.OwnerID owner_id = 3 [ json_name = "ownerID" ]; + neo.fs.v2.refs.OwnerID owner_id = 3 [json_name = "ownerID"]; // Object creation Epoch - uint64 creation_epoch = 4 [ json_name = "creationEpoch" ]; + uint64 creation_epoch = 4 [json_name = "creationEpoch"]; // Size of payload in bytes. // `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown. - uint64 payload_length = 5 [ json_name = "payloadLength" ]; + uint64 payload_length = 5 [json_name = "payloadLength"]; // Hash of payload bytes - neo.fs.v2.refs.Checksum payload_hash = 6 [ json_name = "payloadHash" ]; + neo.fs.v2.refs.Checksum payload_hash = 6 [json_name = "payloadHash"]; // Type of the object payload content - ObjectType object_type = 7 [ json_name = "objectType" ]; + ObjectType object_type = 7 [json_name = "objectType"]; // Homomorphic hash of the object payload - neo.fs.v2.refs.Checksum homomorphic_hash = 8 - [ json_name = "homomorphicHash" ]; + neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"]; // Session token, if it was used during Object creation. Need it to verify // integrity and authenticity out of Request scope. - neo.fs.v2.session.SessionToken session_token = 9 - [ json_name = "sessionToken" ]; + neo.fs.v2.session.SessionToken session_token = 9 [json_name = "sessionToken"]; // `Attribute` is a user-defined Key-Value metadata pair attached to an // object. @@ -116,24 +114,19 @@ message Header { // Objects with duplicated attribute names or attributes with empty values // will be considered invalid. // - // There are some "well-known" attributes starting with `__SYSTEM__` - // (`__NEOFS__` is deprecated) prefix that affect system behaviour: + // There are some "well-known" attributes starting with `__NEOFS__` prefix + // that affect system behaviour: // - // * [ __SYSTEM__UPLOAD_ID ] \ - // (`__NEOFS__UPLOAD_ID` is deprecated) \ + // * __NEOFS__UPLOAD_ID \ // Marks smaller parts of a split bigger object - // * [ __SYSTEM__EXPIRATION_EPOCH ] \ - // (`__NEOFS__EXPIRATION_EPOCH` is deprecated) \ - // The epoch after which object with no LOCKs on it becomes unavailable. - // Locked object continues to be available until each of the LOCKs expire. - // * [ __SYSTEM__TICK_EPOCH ] \ - // (`__NEOFS__TICK_EPOCH` is deprecated) \ + // * __NEOFS__EXPIRATION_EPOCH \ + // Tells GC to delete object after that epoch + // * __NEOFS__TICK_EPOCH \ // Decimal number that defines what epoch must produce // object notification with UTF-8 object address in a // body (`0` value produces notification right after // object put) - // * [ __SYSTEM__TICK_TOPIC ] \ - // (`__NEOFS__TICK_TOPIC` is deprecated) \ + // * __NEOFS__TICK_TOPIC \ // UTF-8 string topic ID that is used for object notification // // And some well-known attributes used by applications only: @@ -141,8 +134,7 @@ message Header { // * Name \ // Human-friendly name // * FileName \ - // File name to be associated with the object on saving. FileName must not - // contain the delimiting symbol '/'. + // File name to be associated with the object on saving // * FilePath \ // Full path to be associated with the object on saving. Should start with a // '/' and use '/' as a delimiting symbol. Trailing '/' should be @@ -156,15 +148,15 @@ message Header { // MIME Content Type of object's payload // // For detailed description of each well-known attribute please see the - // corresponding section in FrostFS Technical Specification. + // corresponding section in NeoFS Technical Specification. message Attribute { // string key to the object attribute - string key = 1 [ json_name = "key" ]; + string key = 1 [json_name = "key"]; // string value of the object attribute - string value = 2 [ json_name = "value" ]; + string value = 2 [json_name = "value"]; } // User-defined object attributes - repeated Attribute attributes = 10 [ json_name = "attributes" ]; + repeated Attribute attributes = 10 [json_name = "attributes"]; // Bigger objects can be split into a chain of smaller objects. Information // about inter-dependencies between spawned objects and how to re-construct @@ -172,84 +164,54 @@ message Header { // must be within the same container. message Split { // Identifier of the origin object. Known only to the minor child. - neo.fs.v2.refs.ObjectID parent = 1 [ json_name = "parent" ]; + neo.fs.v2.refs.ObjectID parent = 1 [json_name = "parent"]; // Identifier of the left split neighbor - neo.fs.v2.refs.ObjectID previous = 2 [ json_name = "previous" ]; + neo.fs.v2.refs.ObjectID previous = 2 [json_name = "previous"]; // `signature` field of the parent object. Used to reconstruct parent. - neo.fs.v2.refs.Signature parent_signature = 3 - [ json_name = "parentSignature" ]; + neo.fs.v2.refs.Signature parent_signature = 3 [json_name = "parentSignature"]; // `header` field of the parent object. Used to reconstruct parent. - Header parent_header = 4 [ json_name = "parentHeader" ]; + Header parent_header = 4 [json_name = "parentHeader"]; // List of identifiers of the objects generated by splitting current one. - repeated neo.fs.v2.refs.ObjectID children = 5 [ json_name = "children" ]; + repeated neo.fs.v2.refs.ObjectID children = 5 [json_name = "children"]; // 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be // unique inside container. All objects participating in the split must have // the same `split_id` value. - bytes split_id = 6 [ json_name = "splitID" ]; + bytes split_id = 6 [json_name = "splitID"]; + } // Position of the object in the split hierarchy - Split split = 11 [ json_name = "split" ]; - - // Erasure code can be applied to any object. - // Information about encoded object structure is stored in `EC` header. - // All objects belonging to a single EC group have the same `parent` field. - message EC { - // Identifier of the origin object. Known to all chunks. - neo.fs.v2.refs.ObjectID parent = 1 [ json_name = "parent" ]; - // Index of this chunk. - uint32 index = 2 [ json_name = "index" ]; - // Total number of chunks in this split. - uint32 total = 3 [ json_name = "total" ]; - // Total length of a parent header. Used to trim padding zeroes. - uint32 header_length = 4 [ json_name = "headerLength" ]; - // Chunk of a parent header. - bytes header = 5 [ json_name = "header" ]; - // As the origin object is EC-splitted its identifier is known to all - // chunks as parent. But parent itself can be a part of Split (does not - // relate to EC-split). In this case parent_split_id should be set. - bytes parent_split_id = 6 [ json_name = "parentSplitID" ]; - // EC-parent's parent ID. parent_split_parent_id is set if EC-parent, - // itself, is a part of Split and if an object ID of its parent is - // presented. The field allows to determine how EC-chunk is placed in Split - // hierarchy. - neo.fs.v2.refs.ObjectID parent_split_parent_id = 7 - [ json_name = "parentSplitParentID" ]; - // EC parent's attributes. - repeated Attribute parent_attributes = 8 [ json_name = "parentAttributes" ]; - } - // Erasure code chunk information. - EC ec = 12 [ json_name = "ec" ]; + Split split = 11 [json_name = "split"]; } // Object structure. Object is immutable and content-addressed. It means -// `ObjectID` will change if the header or the payload changes. It's calculated -// as a hash of header field which contains hash of the object's payload. +// `ObjectID` will change if the header or the payload changes. It's calculated as a +// hash of header field which contains hash of the object's payload. // // For non-regular object types payload format depends on object type specified // in the header. message Object { // Object's unique identifier. - neo.fs.v2.refs.ObjectID object_id = 1 [ json_name = "objectID" ]; + neo.fs.v2.refs.ObjectID object_id = 1 [json_name = "objectID"]; // Signed object_id - neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ]; + neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"]; // Object metadata headers - Header header = 3 [ json_name = "header" ]; + Header header = 3 [json_name = "header"]; // Payload bytes - bytes payload = 4 [ json_name = "payload" ]; + bytes payload = 4 [json_name = "payload"]; } // Meta information of split hierarchy for object assembly. With the last part // one can traverse linked list of split hierarchy back to the first part and -// assemble the original object. With a linking object one can assemble an -// object right from the object parts. +// assemble the original object. With a linking object one can assemble an object +// right from the object parts. message SplitInfo { // 16 byte UUID used to identify the split object hierarchy parts. bytes split_id = 1; @@ -263,17 +225,3 @@ message SplitInfo { // object parts. neo.fs.v2.refs.ObjectID link = 3; } - -// Meta information for the erasure-encoded object. -message ECInfo { - message Chunk { - // Object ID of the chunk. - neo.fs.v2.refs.ObjectID id = 1; - // Index of the chunk. - uint32 index = 2; - // Total number of chunks in this split. - uint32 total = 3; - } - // Chunk stored on the node. - repeated Chunk chunks = 1; -} diff --git a/proto-docs/accounting.md b/proto-docs/accounting.md index a8bfd16..94de765 100644 --- a/proto-docs/accounting.md +++ b/proto-docs/accounting.md @@ -4,21 +4,21 @@ ## Table of Contents - [accounting/service.proto](#accounting/service.proto) - - Services - - [AccountingService](#neo.fs.v2.accounting.AccountingService) - + - Services + - [AccountingService](#neo.fs.v2.accounting.AccountingService) + - Messages - - [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest) - - [BalanceRequest.Body](#neo.fs.v2.accounting.BalanceRequest.Body) - - [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse) - - [BalanceResponse.Body](#neo.fs.v2.accounting.BalanceResponse.Body) - + - [BalanceRequest](#neo.fs.v2.accounting.BalanceRequest) + - [BalanceRequest.Body](#neo.fs.v2.accounting.BalanceRequest.Body) + - [BalanceResponse](#neo.fs.v2.accounting.BalanceResponse) + - [BalanceResponse.Body](#neo.fs.v2.accounting.BalanceResponse.Body) + - [accounting/types.proto](#accounting/types.proto) - Messages - - [Decimal](#neo.fs.v2.accounting.Decimal) - + - [Decimal](#neo.fs.v2.accounting.Decimal) + - [Scalar Value Types](#scalar-value-types) @@ -35,11 +35,11 @@ ### Service "neo.fs.v2.accounting.AccountingService" -Accounting service provides methods for interaction with FrostFS sidechain -via other FrostFS nodes to get information about the account balance. Deposit -and Withdraw operations can't be implemented here, as they require Mainnet -FrostFS smart contract invocation. Transfer operations between internal -FrostFS accounts are possible if both use the same token type. +Accounting service provides methods for interaction with NeoFS sidechain via +other NeoFS nodes to get information about the account balance. Deposit and +Withdraw operations can't be implemented here, as they require Mainnet NeoFS +smart contract invocation. Transfer operations between internal NeoFS +accounts are possible if both use the same token type. ``` rpc Balance(BalanceRequest) returns (BalanceResponse); @@ -48,7 +48,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse); #### Method Balance -Returns the amount of funds in GAS token for the requested FrostFS account. +Returns the amount of funds in GAS token for the requested NeoFS account. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -78,9 +78,9 @@ BalanceRequest message ### Message BalanceRequest.Body To indicate the account for which the balance is requested, its identifier -is used. It can be any existing account in FrostFS sidechain `Balance` -smart contract. If omitted, client implementation MUST set it to the -request's signer `OwnerID`. +is used. It can be any existing account in NeoFS sidechain `Balance` smart +contract. If omitted, client implementation MUST set it to the request's +signer `OwnerID`. | Field | Type | Label | Description | @@ -105,8 +105,7 @@ BalanceResponse message ### Message BalanceResponse.Body The amount of funds in GAS token for the `OwnerID`'s account requested. -Balance is given in the `Decimal` format to avoid precision issues with -rounding. +Balance is given in the `Decimal` format to avoid precision issues with rounding. | Field | Type | Label | Description | @@ -131,7 +130,7 @@ rounding. ### Message Decimal -Standard floating point data type can't be used in FrostFS due to inexactness +Standard floating point data type can't be used in NeoFS due to inexactness of the result when doing lots of small number operations. To solve the lost precision issue, special `Decimal` format is used for monetary computations. @@ -170,3 +169,4 @@ description. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/acl.md b/proto-docs/acl.md index fdc7ade..09762a1 100644 --- a/proto-docs/acl.md +++ b/proto-docs/acl.md @@ -6,15 +6,14 @@ - [acl/types.proto](#acl/types.proto) - Messages - - [BearerToken](#neo.fs.v2.acl.BearerToken) - - [BearerToken.Body](#neo.fs.v2.acl.BearerToken.Body) - - [BearerToken.Body.APEOverride](#neo.fs.v2.acl.BearerToken.Body.APEOverride) - - [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) - - [EACLRecord](#neo.fs.v2.acl.EACLRecord) - - [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) - - [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) - - [EACLTable](#neo.fs.v2.acl.EACLTable) - + - [BearerToken](#neo.fs.v2.acl.BearerToken) + - [BearerToken.Body](#neo.fs.v2.acl.BearerToken.Body) + - [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) + - [EACLRecord](#neo.fs.v2.acl.EACLRecord) + - [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) + - [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) + - [EACLTable](#neo.fs.v2.acl.EACLTable) + - [Scalar Value Types](#scalar-value-types) @@ -39,8 +38,8 @@ like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be used in the similar use cases, like providing authorisation to externally authenticated party. -BearerToken can be issued only by the container's owner and must be signed -using the key associated with the container's `OwnerID`. +BearerToken can be issued only by the container's owner and must be signed using +the key associated with the container's `OwnerID`. | Field | Type | Label | Description | @@ -52,37 +51,15 @@ using the key associated with the container's `OwnerID`. ### Message BearerToken.Body -Bearer Token body structure contains Extended ACL table issued by the -container owner with additional information preventing token abuse. +Bearer Token body structure contains Extended ACL table issued by the container +owner with additional information preventing token abuse. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| 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. - -Deprecated: eACL tables are no longer relevant - `APEOverrides` should be used instead. | +| 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. | | 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. | | lifetime | [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime) | | Token expiration and valid time period parameters | -| allow_impersonate | [bool](#bool) | | AllowImpersonate flag to consider token signer as request owner. If this field is true extended ACL table in token body isn't processed. | -| ape_override | [BearerToken.Body.APEOverride](#neo.fs.v2.acl.BearerToken.Body.APEOverride) | | APE override for the target. | - - - - -### Message BearerToken.Body.APEOverride -APEOverride is the list of APE chains defined for a target. -These chains are meant to serve as overrides to the already defined (or -even undefined) APE chains for the target (see contract `Policy`). - -The server-side processing of the bearer token with set APE overrides -must verify if a client is permitted to override chains for the target, -preventing unauthorized access through the APE mechanism. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| target | [frostfs.v2.ape.ChainTarget](#frostfs.v2.ape.ChainTarget) | | Target for which chains are applied. | -| chains | [frostfs.v2.ape.Chain](#frostfs.v2.ape.Chain) | repeated | The list of APE chains. | @@ -107,7 +84,7 @@ Describes a single eACL rule. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| operation | [Operation](#neo.fs.v2.acl.Operation) | | FrostFS request Verb to match | +| operation | [Operation](#neo.fs.v2.acl.Operation) | | NeoFS request Verb to match | | action | [Action](#neo.fs.v2.acl.Action) | | Rule execution result. Either allows or denies access if filters match. | | filters | [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) | repeated | List of filters to match and see if rule is applicable | | targets | [EACLRecord.Target](#neo.fs.v2.acl.EACLRecord.Target) | repeated | List of target subjects to apply ACL rule to | @@ -175,7 +152,7 @@ keys to match. Extended ACL rules table. A list of ACL rules defined additionally to Basic ACL. Extended ACL rules can be attached to a container and can be updated or may be defined in `BearerToken` structure. Please see the corresponding -FrostFS Technical Specification section for detailed description. +NeoFS Technical Specification section for detailed description. | Field | Type | Label | Description | @@ -211,7 +188,7 @@ Enumeration of possible sources of Headers to apply filters. | HEADER_UNSPECIFIED | 0 | Unspecified header, default value. | | REQUEST | 1 | Filter request headers | | OBJECT | 2 | Filter object headers | -| SERVICE | 3 | Filter service headers. These are not processed by FrostFS nodes and exist for service use only. | +| SERVICE | 3 | Filter service headers. These are not processed by NeoFS nodes and exist for service use only. | @@ -283,3 +260,4 @@ Target role of the access control rule in access control list. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/apemanager.md b/proto-docs/apemanager.md deleted file mode 100644 index c1cb682..0000000 --- a/proto-docs/apemanager.md +++ /dev/null @@ -1,269 +0,0 @@ -# Protocol Documentation - - -## Table of Contents - -- [apemanager/service.proto](#apemanager/service.proto) - - Services - - [APEManagerService](#frostfs.v2.apemanager.APEManagerService) - - - Messages - - [AddChainRequest](#frostfs.v2.apemanager.AddChainRequest) - - [AddChainRequest.Body](#frostfs.v2.apemanager.AddChainRequest.Body) - - [AddChainResponse](#frostfs.v2.apemanager.AddChainResponse) - - [AddChainResponse.Body](#frostfs.v2.apemanager.AddChainResponse.Body) - - [ListChainsRequest](#frostfs.v2.apemanager.ListChainsRequest) - - [ListChainsRequest.Body](#frostfs.v2.apemanager.ListChainsRequest.Body) - - [ListChainsResponse](#frostfs.v2.apemanager.ListChainsResponse) - - [ListChainsResponse.Body](#frostfs.v2.apemanager.ListChainsResponse.Body) - - [RemoveChainRequest](#frostfs.v2.apemanager.RemoveChainRequest) - - [RemoveChainRequest.Body](#frostfs.v2.apemanager.RemoveChainRequest.Body) - - [RemoveChainResponse](#frostfs.v2.apemanager.RemoveChainResponse) - - [RemoveChainResponse.Body](#frostfs.v2.apemanager.RemoveChainResponse.Body) - - -- [Scalar Value Types](#scalar-value-types) - - - - -

Top

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

Top

+ +## audit/types.proto + + + + + + + +### Message DataAuditResult +DataAuditResult keeps record of conducted Data Audits. The detailed report is +generated separately. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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. | +| audit_epoch | [fixed64](#fixed64) | | Epoch number when the Data Audit was conducted | +| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Container under audit | +| public_key | [bytes](#bytes) | | Public key of the auditing InnerRing node in a binary format | +| complete | [bool](#bool) | | Shows if Data Audit process was complete in time or if it was cancelled | +| requests | [uint32](#uint32) | | Number of request done at PoR stage | +| retries | [uint32](#uint32) | | Number of retries done at PoR stage | +| pass_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that passed audit PoR stage | +| fail_sg | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of Storage Groups that failed audit PoR stage | +| hit | [uint32](#uint32) | | Number of sampled objects under the audit placed in an optimal way according to the containers placement policy when checking PoP | +| 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 | +| fail | [uint32](#uint32) | | Number of sampled objects under the audit stored inconsistently with the placement policy or not found at all when checking PoP | +| pass_nodes | [bytes](#bytes) | repeated | List of storage node public keys that passed at least one PDP | +| fail_nodes | [bytes](#bytes) | repeated | List of storage node public keys that failed at least one PDP | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/bootstrap.md b/proto-docs/bootstrap.md new file mode 100644 index 0000000..ad08a7d --- /dev/null +++ b/proto-docs/bootstrap.md @@ -0,0 +1,89 @@ +# Protocol Documentation + + +## Table of Contents + +- [bootstrap/types.proto](#bootstrap/types.proto) + + - Messages + - [NodeInfo](#bootstrap.NodeInfo) + - [NodeInfo.Attribute](#bootstrap.NodeInfo.Attribute) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## bootstrap/types.proto + + + + + + + +### Message NodeInfo +Groups the information about the NeoFS node. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Address | [string](#string) | | Carries network address of the NeoFS node. | +| PublicKey | [bytes](#bytes) | | Carries public key of the NeoFS node in a binary format. | +| Attributes | [NodeInfo.Attribute](#bootstrap.NodeInfo.Attribute) | repeated | Carries list of the NeoFS node attributes in a string key-value format. | +| state | [NodeInfo.State](#bootstrap.NodeInfo.State) | | Carries state of the NeoFS node. | + + + + +### Message NodeInfo.Attribute +Groups attributes of the NeoFS node. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| Key | [string](#string) | | Carries string key to the node attribute. | +| Value | [string](#string) | | Carries string value of the node attribute. | + + + + + + +### NodeInfo.State +Represents the enumeration of various states of the NeoFS node. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| Unknown | 0 | Undefined state. | +| Online | 1 | Active state on the network. | +| Offline | 2 | Network unavailable state. | + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/container.md b/proto-docs/container.md index 7ee5dab..b518a67 100644 --- a/proto-docs/container.md +++ b/proto-docs/container.md @@ -4,38 +4,47 @@ ## Table of Contents - [container/service.proto](#container/service.proto) - - Services - - [ContainerService](#neo.fs.v2.container.ContainerService) - + - Services + - [ContainerService](#neo.fs.v2.container.ContainerService) + - Messages - - [DeleteRequest](#neo.fs.v2.container.DeleteRequest) - - [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body) - - [DeleteResponse](#neo.fs.v2.container.DeleteResponse) - - [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body) - - [GetRequest](#neo.fs.v2.container.GetRequest) - - [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body) - - [GetResponse](#neo.fs.v2.container.GetResponse) - - [GetResponse.Body](#neo.fs.v2.container.GetResponse.Body) - - [ListRequest](#neo.fs.v2.container.ListRequest) - - [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) - - [ListResponse](#neo.fs.v2.container.ListResponse) - - [ListResponse.Body](#neo.fs.v2.container.ListResponse.Body) - - [ListStreamRequest](#neo.fs.v2.container.ListStreamRequest) - - [ListStreamRequest.Body](#neo.fs.v2.container.ListStreamRequest.Body) - - [ListStreamResponse](#neo.fs.v2.container.ListStreamResponse) - - [ListStreamResponse.Body](#neo.fs.v2.container.ListStreamResponse.Body) - - [PutRequest](#neo.fs.v2.container.PutRequest) - - [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body) - - [PutResponse](#neo.fs.v2.container.PutResponse) - - [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body) - + - [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) + - [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body) + - [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) + - [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) + - [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body) + - [DeleteRequest](#neo.fs.v2.container.DeleteRequest) + - [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body) + - [DeleteResponse](#neo.fs.v2.container.DeleteResponse) + - [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body) + - [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) + - [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body) + - [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) + - [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body) + - [GetRequest](#neo.fs.v2.container.GetRequest) + - [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body) + - [GetResponse](#neo.fs.v2.container.GetResponse) + - [GetResponse.Body](#neo.fs.v2.container.GetResponse.Body) + - [ListRequest](#neo.fs.v2.container.ListRequest) + - [ListRequest.Body](#neo.fs.v2.container.ListRequest.Body) + - [ListResponse](#neo.fs.v2.container.ListResponse) + - [ListResponse.Body](#neo.fs.v2.container.ListResponse.Body) + - [PutRequest](#neo.fs.v2.container.PutRequest) + - [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body) + - [PutResponse](#neo.fs.v2.container.PutResponse) + - [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body) + - [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) + - [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body) + - [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) + - [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body) + - [container/types.proto](#container/types.proto) - Messages - - [Container](#neo.fs.v2.container.Container) - - [Container.Attribute](#neo.fs.v2.container.Container.Attribute) - + - [Container](#neo.fs.v2.container.Container) + - [Container.Attribute](#neo.fs.v2.container.Container.Attribute) + - [Scalar Value Types](#scalar-value-types) @@ -53,8 +62,8 @@ ### Service "neo.fs.v2.container.ContainerService" `ContainerService` provides API to interact with `Container` smart contract -in FrostFS sidechain via other FrostFS nodes. All of those actions can be -done equivalently by directly issuing transactions and RPC calls to sidechain +in NeoFS sidechain via other NeoFS nodes. All of those actions can be done +equivalently by directly issuing transactions and RPC calls to sidechain nodes. ``` @@ -62,7 +71,9 @@ rpc Put(PutRequest) returns (PutResponse); rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Get(GetRequest) returns (GetResponse); rpc List(ListRequest) returns (ListResponse); -rpc ListStream(ListStreamRequest) returns (stream ListStreamResponse); +rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse); +rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse); +rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse); ``` @@ -70,15 +81,13 @@ rpc ListStream(ListStreamRequest) returns (stream ListStreamResponse); `Put` invokes `Container` smart contract's `Put` method and returns response immediately. After a new block is issued in sidechain, request is -verified by Inner Ring nodes. After one more block in sidechain, the -container is added into smart contract storage. +verified by Inner Ring nodes. After one more block in sidechain, the container +is added into smart contract storage. Statuses: - **OK** (0, SECTION_SUCCESS): \ request to save the container has been sent to the sidechain; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - container create access denied. +- Common failures (SECTION_FAILURE_COMMON). | Name | Input | Output | | ---- | ----- | ------ | @@ -87,15 +96,13 @@ Statuses: `Delete` invokes `Container` smart contract's `Delete` method and returns response immediately. After a new block is issued in sidechain, request is -verified by Inner Ring nodes. After one more block in sidechain, the -container is added into smart contract storage. +verified by Inner Ring nodes. After one more block in sidechain, the container +is added into smart contract storage. Statuses: - **OK** (0, SECTION_SUCCESS): \ request to remove the container has been sent to the sidechain; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - container delete access denied. +- Common failures (SECTION_FAILURE_COMMON). | Name | Input | Output | | ---- | ----- | ------ | @@ -109,45 +116,127 @@ Statuses: container has been successfully read; - Common failures (SECTION_FAILURE_COMMON); - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - requested container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied. + requested container not found. | Name | Input | Output | | ---- | ----- | ------ | | Get | [GetRequest](#neo.fs.v2.container.GetRequest) | [GetResponse](#neo.fs.v2.container.GetResponse) | #### Method List -Returns all owner's containers from `Container` smart contract storage. +Returns all owner's containers from 'Container` smart contract' storage. Statuses: - **OK** (0, SECTION_SUCCESS): \ container list has been successfully read; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - container list access denied. +- Common failures (SECTION_FAILURE_COMMON). | Name | Input | Output | | ---- | ----- | ------ | | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) | -#### Method ListStream +#### Method SetExtendedACL -Returns all owner's containers from `Container` smart contract storage -via stream. +Invokes 'SetEACL' method of 'Container` smart contract and returns response +immediately. After one more block in sidechain, changes in an Extended ACL are +added into smart contract storage. Statuses: - **OK** (0, SECTION_SUCCESS): \ - container list has been successfully read; -- Common failures (SECTION_FAILURE_COMMON); -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - container list access denied. + request to save container eACL has been sent to the sidechain; +- Common failures (SECTION_FAILURE_COMMON). | Name | Input | Output | | ---- | ----- | ------ | -| ListStream | [ListStreamRequest](#neo.fs.v2.container.ListStreamRequest) | [ListStreamResponse](#neo.fs.v2.container.ListStreamResponse) | +| SetExtendedACL | [SetExtendedACLRequest](#neo.fs.v2.container.SetExtendedACLRequest) | [SetExtendedACLResponse](#neo.fs.v2.container.SetExtendedACLResponse) | +#### Method GetExtendedACL + +Returns Extended ACL table and signature from `Container` smart contract +storage. + +Statuses: +- **OK** (0, SECTION_SUCCESS): \ + container eACL has been successfully read; +- Common failures (SECTION_FAILURE_COMMON); +- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ + container not found; +- **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \ + eACL table not found. + +| Name | Input | Output | +| ---- | ----- | ------ | +| GetExtendedACL | [GetExtendedACLRequest](#neo.fs.v2.container.GetExtendedACLRequest) | [GetExtendedACLResponse](#neo.fs.v2.container.GetExtendedACLResponse) | +#### Method AnnounceUsedSpace + +Announces the space values used by the container for P2P synchronization. + +Statuses: +- **OK** (0, SECTION_SUCCESS): \ + estimation of used space has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + +| Name | Input | Output | +| ---- | ----- | ------ | +| AnnounceUsedSpace | [AnnounceUsedSpaceRequest](#neo.fs.v2.container.AnnounceUsedSpaceRequest) | [AnnounceUsedSpaceResponse](#neo.fs.v2.container.AnnounceUsedSpaceResponse) | + + +### Message AnnounceUsedSpaceRequest +Announce container used space + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceUsedSpaceRequest.Body](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body) | | Body of announce used space request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceUsedSpaceRequest.Body +Container used space announcement body. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| announcements | [AnnounceUsedSpaceRequest.Body.Announcement](#neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement) | repeated | List of announcements. If nodes share several containers, announcements are transferred in a batch. | + + + + +### Message AnnounceUsedSpaceRequest.Body.Announcement +Announcement contains used space information for a single container. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Epoch number for which the container size estimation was produced. | +| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container. | +| used_space | [uint64](#uint64) | | Used space is a sum of object payload sizes of a specified container, stored in the node. It must not include inhumed objects. | + + + + +### Message AnnounceUsedSpaceResponse +Announce container used space + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceUsedSpaceResponse.Body](#neo.fs.v2.container.AnnounceUsedSpaceResponse.Body) | | Body of announce used space response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceUsedSpaceResponse.Body +`AnnounceUsedSpaceResponse` has an empty body because announcements are +one way communication. + + + ### Message DeleteRequest @@ -171,7 +260,7 @@ smart contract, so signing algorithm must be supported by NeoVM. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container to delete from FrostFS | +| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container to delete from NeoFS | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | `ContainerID` signed with the container owner's key according to RFC-6979. | @@ -197,6 +286,58 @@ and done via consensus in Inner Ring nodes. + + +### Message GetExtendedACLRequest +Get Extended ACL + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [GetExtendedACLRequest.Body](#neo.fs.v2.container.GetExtendedACLRequest.Body) | | Body of get extended acl request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message GetExtendedACLRequest.Body +Get Extended ACL request body + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Identifier of the container having Extended ACL | + + + + +### Message GetExtendedACLResponse +Get Extended ACL + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [GetExtendedACLResponse.Body](#neo.fs.v2.container.GetExtendedACLResponse.Body) | | Body of get extended acl response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message GetExtendedACLResponse.Body +Get Extended ACL Response body can be empty if the requested container does +not have Extended ACL Table attached or Extended ACL has not been allowed at +the time of container creation. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL requested, if available | +| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL according to RFC-6979. | +| session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token if Extended ACL was set within a session | + + ### Message GetRequest @@ -296,58 +437,10 @@ List containers response body. | container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` | - - -### Message ListStreamRequest -List containers stream - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [ListStreamRequest.Body](#neo.fs.v2.container.ListStreamRequest.Body) | | Body of list containers stream request message. | -| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message ListStreamRequest.Body -List containers stream request body. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| owner_id | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the container owner. | - - - - -### Message ListStreamResponse -List containers stream - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [ListStreamResponse.Body](#neo.fs.v2.container.ListStreamResponse.Body) | | Body of list containers stream response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message ListStreamResponse.Body -List containers stream response body. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| container_ids | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | repeated | List of `ContainerID`s belonging to the requested `OwnerID` | - - ### Message PutRequest -New FrostFS Container creation request +New NeoFS Container creation request | Field | Type | Label | Description | @@ -369,14 +462,14 @@ additional signature checks. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| container | [Container](#neo.fs.v2.container.Container) | | Container structure to register in FrostFS | +| container | [Container](#neo.fs.v2.container.Container) | | Container structure to register in NeoFS | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. | ### Message PutResponse -New FrostFS Container creation response +New NeoFS Container creation response | Field | Type | Label | Description | @@ -399,6 +492,54 @@ returned here to make sure everything has been done as expected. | ----- | ---- | ----- | ----------- | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Unique identifier of the newly created container | + + + +### Message SetExtendedACLRequest +Set Extended ACL + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [SetExtendedACLRequest.Body](#neo.fs.v2.container.SetExtendedACLRequest.Body) | | Body of set extended acl request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message SetExtendedACLRequest.Body +Set Extended ACL request body does not have separate `ContainerID` +reference. It will be taken from `EACLTable.container_id` field. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| eacl | [neo.fs.v2.acl.EACLTable](#neo.fs.v2.acl.EACLTable) | | Extended ACL table to set for the container | +| signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of stable-marshalled Extended ACL table according to RFC-6979. | + + + + +### Message SetExtendedACLResponse +Set Extended ACL + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [SetExtendedACLResponse.Body](#neo.fs.v2.container.SetExtendedACLResponse.Body) | | Body of set extended acl response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message SetExtendedACLResponse.Body +`SetExtendedACLResponse` has an empty body because the operation is +asynchronous and the update should be reflected in `Container` smart contract's +storage after next block is issued in sidechain. + + @@ -419,8 +560,8 @@ returned here to make sure everything has been done as expected. ### Message Container Container is a structure that defines object placement behaviour. Objects can be stored only within containers. They define placement rule, attributes and -access control information. An ID of a container is a 32 byte long SHA256 -hash of stable-marshalled container message. +access control information. An ID of a container is a 32 byte long SHA256 hash +of stable-marshalled container message. | Field | Type | Label | Description | @@ -437,8 +578,8 @@ hash of stable-marshalled container message. ### Message Container.Attribute `Attribute` is a user-defined Key-Value metadata pair attached to the -container. Container attributes are immutable. They are set at the moment -of container creation and can never be added or updated. +container. Container attributes are immutable. They are set at the moment of +container creation and can never be added or updated. Key name must be a container-unique valid UTF-8 string. Value can't be empty. Containers with duplicated attribute names or attributes with empty @@ -446,22 +587,21 @@ values will be considered invalid. There are some "well-known" attributes affecting system behaviour: -* [ __SYSTEM__NAME ] \ - (`__NEOFS__NAME` is deprecated) \ +* __NEOFS__SUBNET \ + String ID of a container's storage subnet. Any container can be attached to + one subnet only. +* __NEOFS__NAME \ String of a human-friendly container name registered as a domain in NNS contract. -* [ __SYSTEM__ZONE ] \ - (`__NEOFS__ZONE` is deprecated) \ - String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated). - Used as a TLD of a domain name in NNS contract. If no zone is specified, - use default zone: `container`. -* [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \ - (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ - Disables homomorphic hashing for the container if the value equals "true" - string. Any other values are interpreted as missing attribute. Container - could be accepted in a FrostFS network only if the global network hashing - configuration value corresponds with that attribute's value. After - container inclusion, network setting is ignored. +* __NEOFS__ZONE \ + String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS + contract. If no zone is specified, use default zone: `container`. +* __NEOFS__DISABLE_HOMOMORPHIC_HASHING \ + Disables homomorphic hashing for the container if the value equals "true" string. + Any other values are interpreted as missing attribute. Container could be + accepted in a NeoFS network only if the global network hashing configuration + value corresponds with that attribute's value. After container inclusion, network + setting is ignored. And some well-known attributes used by applications only: @@ -501,3 +641,4 @@ And some well-known attributes used by applications only: | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/lock.md b/proto-docs/lock.md index ba23306..3bbbf79 100644 --- a/proto-docs/lock.md +++ b/proto-docs/lock.md @@ -6,8 +6,8 @@ - [lock/types.proto](#lock/types.proto) - Messages - - [Lock](#neo.fs.v2.lock.Lock) - + - [Lock](#neo.fs.v2.lock.Lock) + - [Scalar Value Types](#scalar-value-types) @@ -27,9 +27,8 @@ ### Message Lock Lock objects protects a list of objects from being deleted. The lifetime of a lock object is limited similar to regular objects in -`__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) -attribute. Lock object MUST have expiration epoch. It is impossible to delete -a lock object via ObjectService.Delete RPC call. +`__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch. +It is impossible to delete a lock object via ObjectService.Delete RPC call. | Field | Type | Label | Description | @@ -61,3 +60,4 @@ a lock object via ObjectService.Delete RPC call. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/netmap.md b/proto-docs/netmap.md index b49287c..2c7545d 100644 --- a/proto-docs/netmap.md +++ b/proto-docs/netmap.md @@ -4,38 +4,38 @@ ## Table of Contents - [netmap/service.proto](#netmap/service.proto) - - Services - - [NetmapService](#neo.fs.v2.netmap.NetmapService) - + - Services + - [NetmapService](#neo.fs.v2.netmap.NetmapService) + - Messages - - [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) - - [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) - - [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) - - [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body) - - [NetmapSnapshotRequest](#neo.fs.v2.netmap.NetmapSnapshotRequest) - - [NetmapSnapshotRequest.Body](#neo.fs.v2.netmap.NetmapSnapshotRequest.Body) - - [NetmapSnapshotResponse](#neo.fs.v2.netmap.NetmapSnapshotResponse) - - [NetmapSnapshotResponse.Body](#neo.fs.v2.netmap.NetmapSnapshotResponse.Body) - - [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) - - [NetworkInfoRequest.Body](#neo.fs.v2.netmap.NetworkInfoRequest.Body) - - [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) - - [NetworkInfoResponse.Body](#neo.fs.v2.netmap.NetworkInfoResponse.Body) - + - [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) + - [LocalNodeInfoRequest.Body](#neo.fs.v2.netmap.LocalNodeInfoRequest.Body) + - [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) + - [LocalNodeInfoResponse.Body](#neo.fs.v2.netmap.LocalNodeInfoResponse.Body) + - [NetmapSnapshotRequest](#neo.fs.v2.netmap.NetmapSnapshotRequest) + - [NetmapSnapshotRequest.Body](#neo.fs.v2.netmap.NetmapSnapshotRequest.Body) + - [NetmapSnapshotResponse](#neo.fs.v2.netmap.NetmapSnapshotResponse) + - [NetmapSnapshotResponse.Body](#neo.fs.v2.netmap.NetmapSnapshotResponse.Body) + - [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) + - [NetworkInfoRequest.Body](#neo.fs.v2.netmap.NetworkInfoRequest.Body) + - [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) + - [NetworkInfoResponse.Body](#neo.fs.v2.netmap.NetworkInfoResponse.Body) + - [netmap/types.proto](#netmap/types.proto) - Messages - - [Filter](#neo.fs.v2.netmap.Filter) - - [Netmap](#neo.fs.v2.netmap.Netmap) - - [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) - - [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter) - - [NetworkInfo](#neo.fs.v2.netmap.NetworkInfo) - - [NodeInfo](#neo.fs.v2.netmap.NodeInfo) - - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) - - [PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) - - [Replica](#neo.fs.v2.netmap.Replica) - - [Selector](#neo.fs.v2.netmap.Selector) - + - [Filter](#neo.fs.v2.netmap.Filter) + - [Netmap](#neo.fs.v2.netmap.Netmap) + - [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) + - [NetworkConfig.Parameter](#neo.fs.v2.netmap.NetworkConfig.Parameter) + - [NetworkInfo](#neo.fs.v2.netmap.NetworkInfo) + - [NodeInfo](#neo.fs.v2.netmap.NodeInfo) + - [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) + - [PlacementPolicy](#neo.fs.v2.netmap.PlacementPolicy) + - [Replica](#neo.fs.v2.netmap.Replica) + - [Selector](#neo.fs.v2.netmap.Selector) + - [Scalar Value Types](#scalar-value-types) @@ -52,10 +52,10 @@ ### Service "neo.fs.v2.netmap.NetmapService" -`NetmapService` provides methods to work with `Network Map` and the -information required to build it. The resulting `Network Map` is stored in -sidechain `Netmap` smart contract, while related information can be obtained -from other FrostFS nodes. +`NetmapService` provides methods to work with `Network Map` and the information +required to build it. The resulting `Network Map` is stored in sidechain +`Netmap` smart contract, while related information can be obtained from other +NeoFS nodes. ``` rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); @@ -66,12 +66,11 @@ rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse); #### Method LocalNodeInfo -Get NodeInfo structure from the particular node directly. -Node information can be taken from `Netmap` smart contract. In some cases, -though, one may want to get recent information directly or to talk to the -node not yet present in the `Network Map` to find out what API version can -be used for further communication. This can be also used to check if a node -is up and running. +Get NodeInfo structure from the particular node directly. +Node information can be taken from `Netmap` smart contract. In some cases, though, +one may want to get recent information directly or to talk to the node not yet +present in the `Network Map` to find out what API version can be used for +further communication. This can be also used to check if a node is up and running. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -83,7 +82,7 @@ information about the server has been successfully read; | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) | #### Method NetworkInfo -Read recent information about the FrostFS network. +Read recent information about the NeoFS network. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -95,7 +94,7 @@ information about the current network state has been successfully read; | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) | #### Method NetmapSnapshot -Returns network map snapshot of the current FrostFS epoch. +Returns network map snapshot of the current NeoFS epoch. Statuses: - **OK** (0, SECTION_SUCCESS): @@ -149,7 +148,7 @@ Local Node Info, including API Version in use. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest FrostFS API version in use | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Latest NeoFS API version in use | | node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself | @@ -259,8 +258,8 @@ Information about the network. ### Message Filter -This filter will return the subset of nodes from `NetworkMap` or another -filter's results that will satisfy filter's conditions. +This filter will return the subset of nodes from `NetworkMap` or another filter's +results that will satisfy filter's conditions. | Field | Type | Label | Description | @@ -287,7 +286,7 @@ Network map structure ### Message NetworkConfig -FrostFS network configuration +NeoFS network configuration | Field | Type | Label | Description | @@ -314,8 +313,15 @@ System parameters: - **ContainerFee** \ Fee paid for container creation by the container owner. Value: little-endian integer. Default: 0. +- **EigenTrustAlpha** \ + Alpha parameter of EigenTrust algorithm used in the Reputation system. + Value: decimal floating-point number in UTF-8 string representation. + Default: 0. +- **EigenTrustIterations** \ + Number of EigenTrust algorithm iterations to pass in the Reputation system. + Value: little-endian integer. Default: 0. - **EpochDuration** \ - FrostFS epoch duration measured in Sidechain blocks. + NeoFS epoch duration measured in Sidechain blocks. Value: little-endian integer. Default: 0. - **HomomorphicHashingDisabled** \ Flag of disabling the homomorphic hashing of objects' payload. @@ -327,48 +333,11 @@ System parameters: Flag allowing setting the MAINTENANCE state to storage nodes. Value: true if any byte != 0. Default: false. - **MaxObjectSize** \ - Maximum size of physically stored FrostFS object measured in bytes. + Maximum size of physically stored NeoFS object measured in bytes. Value: little-endian integer. Default: 0. - - This value refers to the maximum size of a **physically** stored object - in FrostFS. However, from a user's perspective, the **logical** size of a - stored object can be significantly larger. The relationship between the - physical and logical object sizes is governed by the following formula - - ```math - \mathrm{Stored\ Object\ Size} \le - \frac{ - \left(\mathrm{Max\ Object\ Size}\right)^2 - }{ - \mathrm{Object\ ID\ Size} - } - ``` - - This arises from the fact that a tombstone, also being an object, stores - the IDs of inhumed objects and cannot be divided into smaller objects, - thus having an upper limit for its size. - - For example, if: - * Max Object Size Size = 64 MiB; - * Object ID Size = 32 B; - - then: - ```math - \mathrm{Stored\ Object\ Size} \le - \frac{\left(64\ \mathrm{MiB}\right)^2}{32\ \mathrm{B}} = - \frac{2^{52}}{2^5}\ \mathrm{B} = - 2^{47}\ \mathrm{B} = - 128\ \mathrm{TiB} - ``` - **WithdrawFee** \ Fee paid for withdrawal of funds paid by the account owner. Value: little-endian integer. Default: 0. -- **MaxECDataCount** \ - Maximum number of data shards for EC placement policy. - Value: little-endian integer. Default: 0. -- **MaxECParityCount** \ - Maximum number of parity shards for EC placement policy. - Value: little-endian integer. Default: 0. | Field | Type | Label | Description | @@ -380,49 +349,49 @@ System parameters: ### Message NetworkInfo -Information about FrostFS network +Information about NeoFS network | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| current_epoch | [uint64](#uint64) | | Number of the current epoch in the FrostFS network | -| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the FrostFS network | -| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the FrostFS network | -| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | FrostFS network configuration | +| current_epoch | [uint64](#uint64) | | Number of the current epoch in the NeoFS network | +| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the NeoFS network | +| ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the NeoFS network | +| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | NeoFS network configuration | ### Message NodeInfo -FrostFS node description +NeoFS node description | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| public_key | [bytes](#bytes) | | Public key of the FrostFS node in a binary format | +| public_key | [bytes](#bytes) | | Public key of the NeoFS node in a binary format | | addresses | [string](#string) | repeated | Ways to connect to a node | -| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the FrostFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid. | -| state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the FrostFS node | +| attributes | [NodeInfo.Attribute](#neo.fs.v2.netmap.NodeInfo.Attribute) | repeated | Carries list of the NeoFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid. | +| state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the NeoFS node | ### Message NodeInfo.Attribute -Administrator-defined Attributes of the FrostFS Storage Node. +Administrator-defined Attributes of the NeoFS Storage Node. `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8 string. Value can't be empty. Attributes can be constructed into a chain of attributes: any attribute can -have a parent attribute and a child attribute (except the first and the -last one). A string representation of the chain of attributes in FrostFS -Storage Node configuration uses ":" and "/" symbols, e.g.: +have a parent attribute and a child attribute (except the first and the last +one). A string representation of the chain of attributes in NeoFS Storage +Node configuration uses ":" and "/" symbols, e.g.: - `FrostFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` + `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2` -Therefore the string attribute representation in the Node configuration -must use "\:", "\/" and "\\" escaped symbols if any of them appears in an -attribute's key or value. +Therefore the string attribute representation in the Node configuration must +use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's +key or value. Node's attributes are mostly used during Storage Policy evaluation to calculate object's placement and find a set of nodes satisfying policy @@ -437,6 +406,13 @@ explicitly set: attributes it's a string presenting floating point number with comma or point delimiter for decimal part. In the Network Map it will be saved as 64-bit unsigned integer representing number of minimal token fractions. +* __NEOFS__SUBNET_%s \ + `True` or `False`. Defines if the node is included in the `%s` subnetwork + or not. `%s` must be an existing subnetwork's ID (non-negative integer number). + A node can be included in more than one subnetwork and, therefore, can contain + more than one subnet attribute. A missing attribute is equivalent to the + presence of the attribute with `False` value (except default zero subnetwork + (with `%s` == 0) for which missing attribute means inclusion in that network). * UN-LOCODE \ Node's geographic location in [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html) @@ -465,8 +441,8 @@ explicitly set: [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated automatically from `UN-LOCODE` attribute. * Continent \ - Node's continent name according to the [Seven-Continent - model](https://en.wikipedia.org/wiki/Continent#Number). Calculated + Node's continent name according to the [Seven-Continent model] + (https://en.wikipedia.org/wiki/Continent#Number). Calculated automatically from `UN-LOCODE` attribute. * ExternalAddr Node's preferred way for communications with external clients. @@ -474,7 +450,7 @@ explicitly set: Must contain a comma-separated list of multi-addresses. For detailed description of each well-known attribute please see the -corresponding section in FrostFS Technical Specification. +corresponding section in NeoFS Technical Specification. | Field | Type | Label | Description | @@ -495,10 +471,10 @@ storage policy definition languages. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | replicas | [Replica](#neo.fs.v2.netmap.Replica) | repeated | Rules to set number of object replicas and place each one into a named bucket | -| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep FrostFS will search for nodes alternatives to include into container's nodes subset | +| container_backup_factor | [uint32](#uint32) | | Container backup factor controls how deep NeoFS will search for nodes alternatives to include into container's nodes subset | | selectors | [Selector](#neo.fs.v2.netmap.Selector) | repeated | Set of Selectors to form the container's nodes subset | | filters | [Filter](#neo.fs.v2.netmap.Filter) | repeated | List of named filters to reference in selectors | -| unique | [bool](#bool) | | Unique flag defines non-overlapping application for replicas | +| subnet_id | [neo.fs.v2.refs.SubnetID](#neo.fs.v2.refs.SubnetID) | | Subnetwork ID to select nodes from. Zero subnet (default) represents all of the nodes which didn't explicitly opt out of membership. | @@ -513,8 +489,6 @@ default. | ----- | ---- | ----- | ----------- | | count | [uint32](#uint32) | | How many object replicas to put | | selector | [string](#string) | | Named selector bucket to put replicas | -| ec_data_count | [uint32](#uint32) | | Data shards count | -| ec_parity_count | [uint32](#uint32) | | Parity shards count | @@ -553,7 +527,7 @@ hash distance. ### NodeInfo.State -Represents the enumeration of various states of the FrostFS node. +Represents the enumeration of various states of the NeoFS node. | Name | Number | Description | | ---- | ------ | ----------- | @@ -580,8 +554,6 @@ Operations on filters | LE | 6 | Less or equal | | OR | 7 | Logical OR | | AND | 8 | Logical AND | -| NOT | 9 | Logical negation | -| LIKE | 10 | Matches pattern | @@ -607,3 +579,4 @@ Operations on filters | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/object.md b/proto-docs/object.md index 14b9ae6..e22f6c0 100644 --- a/proto-docs/object.md +++ b/proto-docs/object.md @@ -4,67 +4,55 @@ ## Table of Contents - [object/service.proto](#object/service.proto) - - Services - - [ObjectService](#neo.fs.v2.object.ObjectService) - + - Services + - [ObjectService](#neo.fs.v2.object.ObjectService) + - Messages - - [DeleteRequest](#neo.fs.v2.object.DeleteRequest) - - [DeleteRequest.Body](#neo.fs.v2.object.DeleteRequest.Body) - - [DeleteResponse](#neo.fs.v2.object.DeleteResponse) - - [DeleteResponse.Body](#neo.fs.v2.object.DeleteResponse.Body) - - [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) - - [GetRangeHashRequest.Body](#neo.fs.v2.object.GetRangeHashRequest.Body) - - [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) - - [GetRangeHashResponse.Body](#neo.fs.v2.object.GetRangeHashResponse.Body) - - [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) - - [GetRangeRequest.Body](#neo.fs.v2.object.GetRangeRequest.Body) - - [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) - - [GetRangeResponse.Body](#neo.fs.v2.object.GetRangeResponse.Body) - - [GetRequest](#neo.fs.v2.object.GetRequest) - - [GetRequest.Body](#neo.fs.v2.object.GetRequest.Body) - - [GetResponse](#neo.fs.v2.object.GetResponse) - - [GetResponse.Body](#neo.fs.v2.object.GetResponse.Body) - - [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) - - [HeadRequest](#neo.fs.v2.object.HeadRequest) - - [HeadRequest.Body](#neo.fs.v2.object.HeadRequest.Body) - - [HeadResponse](#neo.fs.v2.object.HeadResponse) - - [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body) - - [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) - - [PatchRequest](#neo.fs.v2.object.PatchRequest) - - [PatchRequest.Body](#neo.fs.v2.object.PatchRequest.Body) - - [PatchRequest.Body.Patch](#neo.fs.v2.object.PatchRequest.Body.Patch) - - [PatchResponse](#neo.fs.v2.object.PatchResponse) - - [PatchResponse.Body](#neo.fs.v2.object.PatchResponse.Body) - - [PutRequest](#neo.fs.v2.object.PutRequest) - - [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body) - - [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) - - [PutResponse](#neo.fs.v2.object.PutResponse) - - [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body) - - [PutSingleRequest](#neo.fs.v2.object.PutSingleRequest) - - [PutSingleRequest.Body](#neo.fs.v2.object.PutSingleRequest.Body) - - [PutSingleResponse](#neo.fs.v2.object.PutSingleResponse) - - [PutSingleResponse.Body](#neo.fs.v2.object.PutSingleResponse.Body) - - [Range](#neo.fs.v2.object.Range) - - [SearchRequest](#neo.fs.v2.object.SearchRequest) - - [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body) - - [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter) - - [SearchResponse](#neo.fs.v2.object.SearchResponse) - - [SearchResponse.Body](#neo.fs.v2.object.SearchResponse.Body) - + - [DeleteRequest](#neo.fs.v2.object.DeleteRequest) + - [DeleteRequest.Body](#neo.fs.v2.object.DeleteRequest.Body) + - [DeleteResponse](#neo.fs.v2.object.DeleteResponse) + - [DeleteResponse.Body](#neo.fs.v2.object.DeleteResponse.Body) + - [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) + - [GetRangeHashRequest.Body](#neo.fs.v2.object.GetRangeHashRequest.Body) + - [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) + - [GetRangeHashResponse.Body](#neo.fs.v2.object.GetRangeHashResponse.Body) + - [GetRangeRequest](#neo.fs.v2.object.GetRangeRequest) + - [GetRangeRequest.Body](#neo.fs.v2.object.GetRangeRequest.Body) + - [GetRangeResponse](#neo.fs.v2.object.GetRangeResponse) + - [GetRangeResponse.Body](#neo.fs.v2.object.GetRangeResponse.Body) + - [GetRequest](#neo.fs.v2.object.GetRequest) + - [GetRequest.Body](#neo.fs.v2.object.GetRequest.Body) + - [GetResponse](#neo.fs.v2.object.GetResponse) + - [GetResponse.Body](#neo.fs.v2.object.GetResponse.Body) + - [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) + - [HeadRequest](#neo.fs.v2.object.HeadRequest) + - [HeadRequest.Body](#neo.fs.v2.object.HeadRequest.Body) + - [HeadResponse](#neo.fs.v2.object.HeadResponse) + - [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body) + - [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) + - [PutRequest](#neo.fs.v2.object.PutRequest) + - [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body) + - [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) + - [PutResponse](#neo.fs.v2.object.PutResponse) + - [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body) + - [Range](#neo.fs.v2.object.Range) + - [SearchRequest](#neo.fs.v2.object.SearchRequest) + - [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body) + - [SearchRequest.Body.Filter](#neo.fs.v2.object.SearchRequest.Body.Filter) + - [SearchResponse](#neo.fs.v2.object.SearchResponse) + - [SearchResponse.Body](#neo.fs.v2.object.SearchResponse.Body) + - [object/types.proto](#object/types.proto) - Messages - - [ECInfo](#neo.fs.v2.object.ECInfo) - - [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk) - - [Header](#neo.fs.v2.object.Header) - - [Header.Attribute](#neo.fs.v2.object.Header.Attribute) - - [Header.EC](#neo.fs.v2.object.Header.EC) - - [Header.Split](#neo.fs.v2.object.Header.Split) - - [Object](#neo.fs.v2.object.Object) - - [ShortHeader](#neo.fs.v2.object.ShortHeader) - - [SplitInfo](#neo.fs.v2.object.SplitInfo) - + - [Header](#neo.fs.v2.object.Header) + - [Header.Attribute](#neo.fs.v2.object.Header.Attribute) + - [Header.Split](#neo.fs.v2.object.Header.Split) + - [Object](#neo.fs.v2.object.Object) + - [ShortHeader](#neo.fs.v2.object.ShortHeader) + - [SplitInfo](#neo.fs.v2.object.SplitInfo) + - [Scalar Value Types](#scalar-value-types) @@ -92,31 +80,26 @@ rpc Head(HeadRequest) returns (HeadResponse); rpc Search(SearchRequest) returns (stream SearchResponse); rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); -rpc PutSingle(PutSingleRequest) returns (PutSingleResponse); -rpc Patch(stream PatchRequest) returns (PatchResponse); ``` #### Method Get Receive full object structure, including Headers and payload. Response uses -gRPC stream. First response message carries the object with the requested -address. Chunk messages are parts of the object's payload if it is needed. -All messages, except the first one, carry payload chunks. The requested -object can be restored by concatenation of object message payload and all -chunks keeping the receiving order. +gRPC stream. First response message carries the object with the requested address. +Chunk messages are parts of the object's payload if it is needed. All +messages, except the first one, carry payload chunks. The requested object can +be restored by concatenation of object message payload and all chunks +keeping the receiving order. Extended headers can change `Get` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ +* __NEOFS__NETMAP_EPOCH \ Will use the requsted version of Network Map for object placement calculation. -* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ - Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH` - (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one - otherwise) of Network Map to find an object until the depth limit is - reached. +* __NEOFS__NETMAP_LOOKUP_DEPTH \ + Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or + the latest one otherwise) of Network Map to find an object until the depth + limit is reached. Please refer to detailed `XHeader` description. @@ -132,8 +115,6 @@ Statuses: the requested object has been marked as deleted; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -150,8 +131,7 @@ object payload. All messages, except first one, SHOULD be payload chunks. Chunk messages SHOULD be sent in the direct order of fragmentation. Extended headers can change `Put` behaviour: -* [ __SYSTEM__NETMAP_EPOCH \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ +* __NEOFS__NETMAP_EPOCH \ Will use the requsted version of Network Map for object placement calculation. @@ -164,18 +144,15 @@ Statuses: - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ write access to the container is denied; - **LOCKED** (2050, SECTION_OBJECT): \ - placement of an object of type TOMBSTONE that includes at least one - locked object is prohibited; + placement of an object of type TOMBSTONE that includes at least one locked + object is prohibited; - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ placement of an object of type LOCK that includes at least one object of type other than REGULAR is prohibited; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object storage container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - (for trusted object preparation) session private key does not exist or - has + (for trusted object preparation) session private key does not exist or has been deleted; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -189,9 +166,8 @@ Delete the object from a container. There is no immediate removal guarantee. Object will be marked for removal and deleted eventually. Extended headers can change `Delete` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement calculation. Please refer to detailed `XHeader` description. @@ -202,15 +178,10 @@ Statuses: - Common failures (SECTION_FAILURE_COMMON); - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ delete access to the object is denied; -- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ - the object could not be deleted because it has not been \ - found within the container; - **LOCKED** (2050, SECTION_OBJECT): \ deleting a locked object is prohibited; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -223,13 +194,9 @@ Returns the object Headers without data payload. By default full header is returned. If `main_only` request field is set, the short header with only the very minimal information will be returned instead. -Max header size is currently not limited by this API, but may be restricted -on the service level. By default, gRPC uses a message size of 4 MiB. - Extended headers can change `Head` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement calculation. Please refer to detailed `XHeader` description. @@ -246,8 +213,6 @@ Statuses: the requested object has been marked as deleted; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -257,13 +222,12 @@ Statuses: #### Method Search Search objects in container. Search query allows to match by Object -Header's filed values. Please see the corresponding FrostFS Technical +Header's filed values. Please see the corresponding NeoFS Technical Specification section for more details. Extended headers can change `Search` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement calculation. Please refer to detailed `XHeader` description. @@ -276,8 +240,6 @@ Statuses: access to operation SEARCH of the object is denied; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ search container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -288,16 +250,14 @@ Statuses: Get byte range of data payload. Range is set as an (offset, length) tuple. Like in `Get` method, the response uses gRPC stream. Requested range can be -restored by concatenation of all received payload chunks keeping the -receiving order. +restored by concatenation of all received payload chunks keeping the receiving +order. Extended headers can change `GetRange` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement calculation. -* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ +* __NEOFS__NETMAP_LOOKUP_DEPTH \ Will try older versions of Network Map to find an object until the depth limit is reached. @@ -317,8 +277,6 @@ Statuses: the requested range is out of bounds; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. @@ -333,12 +291,10 @@ length) tuples. Hashes order in response corresponds to the ranges order in the request. Note that hash is calculated for XORed data. Extended headers can change `GetRangeHash` behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement +* __NEOFS__NETMAP_EPOCH \ + Will use the requsted version of Network Map for object placement calculation. -* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ +* __NEOFS__NETMAP_LOOKUP_DEPTH \ Will try older versions of Network Map to find an object until the depth limit is reached. @@ -356,107 +312,12 @@ Statuses: the requested range is out of bounds; - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ object container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ provided session token has expired. | Name | Input | Output | | ---- | ----- | ------ | | GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) | -#### Method PutSingle - -Put the prepared object into container. -`ContainerID`, `ObjectID`, `OwnerID`, `PayloadHash` and `PayloadLength` of -an object MUST be set. - -Extended headers can change `Put` behaviour: -* [ __SYSTEM__NETMAP_EPOCH \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requested version of Network Map for object placement - calculation. - -Please refer to detailed `XHeader` description. - -Statuses: -- **OK** (0, SECTION_SUCCESS): \ - object has been successfully saved in the container; -- Common failures (SECTION_FAILURE_COMMON); -- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - write access to the container is denied; -- **LOCKED** (2050, SECTION_OBJECT): \ - placement of an object of type TOMBSTONE that includes at least one - locked object is prohibited; -- **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ - placement of an object of type LOCK that includes at least one object of - type other than REGULAR is prohibited; -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object storage container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; -- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - (for trusted object preparation) session private key does not exist or - has -been deleted; -- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - provided session token has expired. - -| Name | Input | Output | -| ---- | ----- | ------ | -| PutSingle | [PutSingleRequest](#neo.fs.v2.object.PutSingleRequest) | [PutSingleResponse](#neo.fs.v2.object.PutSingleResponse) | -#### Method Patch - -Patch the object. Request uses gRPC stream. First message must set -the address of the object that is going to get patched. If the object's -attributes are patched, then these attrubutes must be set only within the -first stream message. - -If the patch request is performed by NOT the object's owner but if the -actor has the permission to perform the patch, then `OwnerID` of the object -is changed. In this case the object's owner loses the object's ownership -after the patch request is successfully done. - -As objects are content-addressable the patching causes new object ID -generation for the patched object. This object id is set witihn -`PatchResponse`. But the object id may remain unchanged in such cases: -1. The chunk of the applying patch contains the same value as the object's -payload within the same range; -2. The patch that reverts the changes applied by preceding patch; -3. The application of the same patches for the object a few times. - -Extended headers can change `Patch` behaviour: -* [ __SYSTEM__NETMAP_EPOCH \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ - Will use the requsted version of Network Map for object placement - calculation. - -Please refer to detailed `XHeader` description. - -Statuses: -- **OK** (0, SECTION_SUCCESS): \ - object has been successfully patched and saved in the container; -- Common failures (SECTION_FAILURE_COMMON); -- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - write access to the container is denied; -- **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \ - object not found in container; -- **OBJECT_ALREADY_REMOVED** (2052, SECTION_OBJECT): \ - the requested object has been marked as deleted. -- **OUT_OF_RANGE** (2053, SECTION_OBJECT): \ - the requested range is out of bounds; -- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - object storage container not found; -- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ - access to container is denied; -- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - (for trusted object preparation) session private key does not exist or - has been deleted; -- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - provided session token has expired. - -| Name | Input | Output | -| ---- | ----- | ------ | -| Patch | [PatchRequest](#neo.fs.v2.object.PatchRequest) | [PatchResponse](#neo.fs.v2.object.PatchResponse) | @@ -613,7 +474,6 @@ chunks. | ----- | ---- | ----- | ----------- | | chunk | [bytes](#bytes) | | Chunked object payload's range. | | split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | -| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. | @@ -665,7 +525,6 @@ GET Object Response body | init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream | | chunk | [bytes](#bytes) | | Chunked object payload | | split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy for object assembly. | -| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. | @@ -731,8 +590,7 @@ Object HEAD response body | ----- | ---- | ----- | ----------- | | header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) | | Full object's `Header` with `ObjectID` signature | | short_header | [ShortHeader](#neo.fs.v2.object.ShortHeader) | | Short object header | -| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. Indicates that the object is virtual, manual assembly is required. | -| ec_info | [ECInfo](#neo.fs.v2.object.ECInfo) | | Meta information for EC object assembly. | +| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | @@ -753,71 +611,6 @@ following steps: | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` to verify full header's authenticity | - - -### Message PatchRequest -Object PATCH request - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [PatchRequest.Body](#neo.fs.v2.object.PatchRequest.Body) | | Body for patch request message. | -| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message PatchRequest.Body -PATCH request body - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| address | [neo.fs.v2.refs.Address](#neo.fs.v2.refs.Address) | | The address of the object that is requested to get patched. | -| new_attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | New attributes for the object. See `replace_attributes` flag usage to define how new attributes should be set. | -| replace_attributes | [bool](#bool) | | If this flag is set, then the object's attributes will be entirely replaced by `new_attributes` list. The empty `new_attributes` list with `replace_attributes = true` just resets attributes list for the object. - -Default `false` value for this flag means the attributes will be just merged. If the incoming `new_attributes` list contains already existing key, then it just replaces it while merging the lists. | -| patch | [PatchRequest.Body.Patch](#neo.fs.v2.object.PatchRequest.Body.Patch) | | The patch that is applied for the object. | - - - - -### Message PatchRequest.Body.Patch -The patch for the object's payload. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| source_range | [Range](#neo.fs.v2.object.Range) | | The range of the source object for which the payload is replaced by the patch's chunk. If the range's `length = 0`, then the patch's chunk is just appended to the original payload starting from the `offest` without any replace. | -| chunk | [bytes](#bytes) | | The chunk that is being appended to or that replaces the original payload on the given range. | - - - - -### Message PatchResponse -Object PATCH response - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [PatchResponse.Body](#neo.fs.v2.object.PatchResponse.Body) | | Body for patch response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message PatchResponse.Body -PATCH response body - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | The object ID of the saved patched object. | - - ### Message PutRequest @@ -855,7 +648,7 @@ are not set, they will be calculated by a peer node. | object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | ObjectID if available. | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Object signature if available | | header | [Header](#neo.fs.v2.object.Header) | | Object's Header | -| copies_number | [uint32](#uint32) | repeated | Number of copies of the object to store within the RPC call. By default, object is processed according to the container's placement policy. Can be one of: 1. A single number; applied to the whole request and is treated as a minimal number of nodes that must store an object to complete the request successfully. 2. An ordered array; every number is treated as a minimal number of nodes in a corresponding placement vector that must store an object to complete the request successfully. The length MUST equal the placement vectors number, otherwise request is considered malformed. | +| copies_number | [uint32](#uint32) | | Number of the object copies to store within the RPC call. By default object is processed according to the container's placement policy. | @@ -882,51 +675,6 @@ PUT Object response body | object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object | - - -### Message PutSingleRequest -Object PUT Single request - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [PutSingleRequest.Body](#neo.fs.v2.object.PutSingleRequest.Body) | | Body of put single object request message. | -| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message PutSingleRequest.Body -PUT Single request body - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| object | [Object](#neo.fs.v2.object.Object) | | Prepared object with payload. | -| copies_number | [uint32](#uint32) | repeated | Number of copies of the object to store within the RPC call. By default, object is processed according to the container's placement policy. Every number is treated as a minimal number of nodes in a corresponding placement vector that must store an object to complete the request successfully. The length MUST equal the placement vectors number, otherwise request is considered malformed. | - - - - -### Message PutSingleResponse -Object PUT Single response - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| body | [PutSingleResponse.Body](#neo.fs.v2.object.PutSingleResponse.Body) | | Body of put single object response message. | -| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | -| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | - - - - -### Message PutSingleResponse.Body -PUT Single Object response body - - - ### Message Range @@ -968,11 +716,11 @@ Object Search request body ### Message SearchRequest.Body.Filter -Filter structure checks if the object header field or the attribute -content matches a value. +Filter structure checks if the object header field or the attribute content +matches a value. If no filters are set, search request will return all objects of the -container, including Regular object and Tombstone +container, including Regular object, Tombstones and Storage Group objects. Most human users expect to get only object they can directly work with. In that case, `$Object:ROOT` filter should be used. @@ -1002,19 +750,16 @@ prefix to the name. Here is the list of fields available via this prefix: object_id of parent * $Object:split.splitID \ 16 byte UUIDv4 used to identify the split object hierarchy parts -* $Object:ec.parent \ - If the object is stored according to EC policy, then ec_parent - attribute is set to return an id list of all related EC chunks. There are some well-known filter aliases to match objects by certain properties: * $Object:ROOT \ - Returns only `REGULAR` type objects that are not split or that are the - top level root objects in a split hierarchy. This includes objects not + Returns only `REGULAR` type objects that are not split or that are the top + level root objects in a split hierarchy. This includes objects not present physically, like large objects split into smaller objects without a separate top-level root object. Objects of other types like - Locks and Tombstones will not be shown. This filter may be + StorageGroups and Tombstones will not be shown. This filter may be useful for listing objects like `ls` command of some virtual file system. This filter is activated if the `key` exists, disregarding the value and matcher type. @@ -1023,8 +768,8 @@ properties: activated if the `key` exists, disregarding the value and matcher type. Note: using filters with a key with prefix `$Object:` and match type -`NOT_PRESENT `is not recommended since this is not a cross-version -approach. Behavior when processing this kind of filters is undefined. +`NOT_PRESENT `is not recommended since this is not a cross-version approach. +Behavior when processing this kind of filters is undefined. | Field | Type | Label | Description | @@ -1072,30 +817,6 @@ Object Search response body - - -### Message ECInfo -Meta information for the erasure-encoded object. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| chunks | [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk) | repeated | Chunk stored on the node. | - - - - -### Message ECInfo.Chunk - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Object ID of the chunk. | -| index | [uint32](#uint32) | | Index of the chunk. | -| total | [uint32](#uint32) | | Total number of chunks in this split. | - - ### Message Header @@ -1115,7 +836,6 @@ Object Header | session_token | [neo.fs.v2.session.SessionToken](#neo.fs.v2.session.SessionToken) | | Session token, if it was used during Object creation. Need it to verify integrity and authenticity out of Request scope. | | attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | User-defined object attributes | | split | [Header.Split](#neo.fs.v2.object.Header.Split) | | Position of the object in the split hierarchy | -| ec | [Header.EC](#neo.fs.v2.object.Header.EC) | | Erasure code chunk information. | @@ -1128,24 +848,19 @@ Key name must be an object-unique valid UTF-8 string. Value can't be empty. Objects with duplicated attribute names or attributes with empty values will be considered invalid. -There are some "well-known" attributes starting with `__SYSTEM__` -(`__NEOFS__` is deprecated) prefix that affect system behaviour: +There are some "well-known" attributes starting with `__NEOFS__` prefix +that affect system behaviour: -* [ __SYSTEM__UPLOAD_ID ] \ - (`__NEOFS__UPLOAD_ID` is deprecated) \ +* __NEOFS__UPLOAD_ID \ Marks smaller parts of a split bigger object -* [ __SYSTEM__EXPIRATION_EPOCH ] \ - (`__NEOFS__EXPIRATION_EPOCH` is deprecated) \ - The epoch after which object with no LOCKs on it becomes unavailable. - Locked object continues to be available until each of the LOCKs expire. -* [ __SYSTEM__TICK_EPOCH ] \ - (`__NEOFS__TICK_EPOCH` is deprecated) \ +* __NEOFS__EXPIRATION_EPOCH \ + Tells GC to delete object after that epoch +* __NEOFS__TICK_EPOCH \ Decimal number that defines what epoch must produce object notification with UTF-8 object address in a body (`0` value produces notification right after object put) -* [ __SYSTEM__TICK_TOPIC ] \ - (`__NEOFS__TICK_TOPIC` is deprecated) \ +* __NEOFS__TICK_TOPIC \ UTF-8 string topic ID that is used for object notification And some well-known attributes used by applications only: @@ -1167,7 +882,7 @@ And some well-known attributes used by applications only: MIME Content Type of object's payload For detailed description of each well-known attribute please see the -corresponding section in FrostFS Technical Specification. +corresponding section in NeoFS Technical Specification. | Field | Type | Label | Description | @@ -1176,26 +891,6 @@ corresponding section in FrostFS Technical Specification. | value | [string](#string) | | string value of the object attribute | - - -### Message Header.EC -Erasure code can be applied to any object. -Information about encoded object structure is stored in `EC` header. -All objects belonging to a single EC group have the same `parent` field. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| parent | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the origin object. Known to all chunks. | -| index | [uint32](#uint32) | | Index of this chunk. | -| total | [uint32](#uint32) | | Total number of chunks in this split. | -| header_length | [uint32](#uint32) | | Total length of a parent header. Used to trim padding zeroes. | -| header | [bytes](#bytes) | | Chunk of a parent header. | -| parent_split_id | [bytes](#bytes) | | As the origin object is EC-splitted its identifier is known to all chunks as parent. But parent itself can be a part of Split (does not relate to EC-split). In this case parent_split_id should be set. | -| parent_split_parent_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | EC-parent's parent ID. parent_split_parent_id is set if EC-parent, itself, is a part of Split and if an object ID of its parent is presented. The field allows to determine how EC-chunk is placed in Split hierarchy. | -| parent_attributes | [Header.Attribute](#neo.fs.v2.object.Header.Attribute) | repeated | EC parent's attributes. | - - ### Message Header.Split @@ -1219,8 +914,8 @@ must be within the same container. ### Message Object Object structure. Object is immutable and content-addressed. It means -`ObjectID` will change if the header or the payload changes. It's calculated -as a hash of header field which contains hash of the object's payload. +`ObjectID` will change if the header or the payload changes. It's calculated as a +hash of header field which contains hash of the object's payload. For non-regular object types payload format depends on object type specified in the header. @@ -1256,8 +951,8 @@ Short header fields ### Message SplitInfo Meta information of split hierarchy for object assembly. With the last part one can traverse linked list of split hierarchy back to the first part and -assemble the original object. With a linking object one can assemble an -object right from the object parts. +assemble the original object. With a linking object one can assemble an object +right from the object parts. | Field | Type | Label | Description | @@ -1288,18 +983,20 @@ Type of match expression ### ObjectType Type of the object payload content. Only `REGULAR` type objects can be split, -hence `TOMBSTONE` and `LOCK` payload is limited by the -maximum object size. +hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum +object size. String presentation of object type is the same as definition: * REGULAR * TOMBSTONE +* STORAGE_GROUP * LOCK | Name | Number | Description | | ---- | ------ | ----------- | | REGULAR | 0 | Just a normal object | | TOMBSTONE | 1 | Used internally to identify deleted objects | +| STORAGE_GROUP | 2 | StorageGroup information | | LOCK | 3 | Object lock | @@ -1326,3 +1023,4 @@ String presentation of object type is the same as definition: | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/refs.md b/proto-docs/refs.md index 3ad3126..651822f 100644 --- a/proto-docs/refs.md +++ b/proto-docs/refs.md @@ -6,15 +6,16 @@ - [refs/types.proto](#refs/types.proto) - Messages - - [Address](#neo.fs.v2.refs.Address) - - [Checksum](#neo.fs.v2.refs.Checksum) - - [ContainerID](#neo.fs.v2.refs.ContainerID) - - [ObjectID](#neo.fs.v2.refs.ObjectID) - - [OwnerID](#neo.fs.v2.refs.OwnerID) - - [Signature](#neo.fs.v2.refs.Signature) - - [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) - - [Version](#neo.fs.v2.refs.Version) - + - [Address](#neo.fs.v2.refs.Address) + - [Checksum](#neo.fs.v2.refs.Checksum) + - [ContainerID](#neo.fs.v2.refs.ContainerID) + - [ObjectID](#neo.fs.v2.refs.ObjectID) + - [OwnerID](#neo.fs.v2.refs.OwnerID) + - [Signature](#neo.fs.v2.refs.Signature) + - [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) + - [SubnetID](#neo.fs.v2.refs.SubnetID) + - [Version](#neo.fs.v2.refs.Version) + - [Scalar Value Types](#scalar-value-types) @@ -32,7 +33,7 @@ ### Message Address -Objects in FrostFS are addressed by their ContainerID and ObjectID. +Objects in NeoFS are addressed by their ContainerID and ObjectID. String presentation of `Address` is a concatenation of string encoded `ContainerID` and `ObjectID` delimited by '/' character. @@ -65,7 +66,7 @@ Depending on checksum algorithm type, the string presentation may vary: ### Message ContainerID -FrostFS container identifier. Container structures are immutable and +NeoFS container identifier. Container structures are immutable and content-addressed. `ContainerID` is a 32 byte long @@ -90,14 +91,13 @@ with/without paddings are accepted. ### Message ObjectID -FrostFS Object unique identifier. Objects are immutable and -content-addressed. It means `ObjectID` will change if the `header` or the -`payload` changes. +NeoFS Object unique identifier. Objects are immutable and content-addressed. +It means `ObjectID` will change if the `header` or the `payload` changes. `ObjectID` is a 32 byte long [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of -the object's `header` field, which, in it's turn, contains the hash of the -object's payload. +the object's `header` field, which, in it's turn, contains the hash of the object's +payload. String presentation is a [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. @@ -142,7 +142,7 @@ with/without paddings are accepted. ### Message Signature -Signature of something in FrostFS. +Signature of something in NeoFS. | Field | Type | Label | Description | @@ -164,14 +164,28 @@ RFC 6979 signature. | sign | [bytes](#bytes) | | Deterministic ECDSA with SHA-256 hashing | + + +### Message SubnetID +NeoFS subnetwork identifier. + +String representation of a value is base-10 integer. + +JSON representation is an object containing a single `value` number field. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [fixed32](#fixed32) | | 4-byte integer subnetwork identifier. | + + ### Message Version API version used by a node. String presentation is a Semantic Versioning 2.0.0 compatible version string -with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor -number. +with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number. | Field | Type | Label | Description | @@ -198,8 +212,7 @@ Checksum algorithm type. ### SignatureScheme -Signature scheme describes digital signing scheme used for (key, signature) -pair. +Signature scheme describes digital signing scheme used for (key, signature) pair. | Name | Number | Description | | ---- | ------ | ----------- | @@ -231,3 +244,4 @@ pair. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/reputation.md b/proto-docs/reputation.md new file mode 100644 index 0000000..19558f3 --- /dev/null +++ b/proto-docs/reputation.md @@ -0,0 +1,289 @@ +# Protocol Documentation + + +## Table of Contents + +- [reputation/service.proto](#reputation/service.proto) + - Services + - [ReputationService](#neo.fs.v2.reputation.ReputationService) + + - Messages + - [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) + - [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body) + - [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) + - [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body) + - [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) + - [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body) + - [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) + - [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body) + + +- [reputation/types.proto](#reputation/types.proto) + + - Messages + - [GlobalTrust](#neo.fs.v2.reputation.GlobalTrust) + - [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) + - [PeerID](#neo.fs.v2.reputation.PeerID) + - [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust) + - [Trust](#neo.fs.v2.reputation.Trust) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## reputation/service.proto + + + + + + +### Service "neo.fs.v2.reputation.ReputationService" +`ReputationService` provides mechanisms for exchanging trust values with +other NeoFS nodes. Nodes rate each other's reputation based on how good they +process requests and set a trust level based on that rating. The trust +information is passed to the next nodes to check and aggregate unless the +final result is recorded. + +``` +rpc AnnounceLocalTrust(AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse); +rpc AnnounceIntermediateResult(AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse); + +``` + +#### Method AnnounceLocalTrust + +Announce local client trust information to any node in NeoFS network. + +Statuses: +- **OK** (0, SECTION_SUCCESS): +local trust has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + +| Name | Input | Output | +| ---- | ----- | ------ | +| AnnounceLocalTrust | [AnnounceLocalTrustRequest](#neo.fs.v2.reputation.AnnounceLocalTrustRequest) | [AnnounceLocalTrustResponse](#neo.fs.v2.reputation.AnnounceLocalTrustResponse) | +#### Method AnnounceIntermediateResult + +Announce the intermediate result of the iterative algorithm for +calculating the global reputation of the node in NeoFS network. + +Statuses: +- **OK** (0, SECTION_SUCCESS): +intermediate trust estimation has been successfully announced; +- Common failures (SECTION_FAILURE_COMMON). + +| Name | Input | Output | +| ---- | ----- | ------ | +| AnnounceIntermediateResult | [AnnounceIntermediateResultRequest](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest) | [AnnounceIntermediateResultResponse](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse) | + + + + + +### Message AnnounceIntermediateResultRequest +Announce intermediate global trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceIntermediateResultRequest.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body) | | Body of the request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceIntermediateResultRequest.Body +Announce intermediate global trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Iteration execution Epoch number | +| iteration | [uint32](#uint32) | | Iteration sequence number | +| trust | [PeerToPeerTrust](#neo.fs.v2.reputation.PeerToPeerTrust) | | Current global trust value calculated at the specified iteration | + + + + +### Message AnnounceIntermediateResultResponse +Intermediate global trust information announcement response. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceIntermediateResultResponse.Body](#neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body) | | Body of the response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceIntermediateResultResponse.Body +Response to the node's intermediate global trust information announcement has +an empty body because the trust exchange operation is asynchronous. If +Trust information does not pass sanity checks, it is silently ignored. + + + + + +### Message AnnounceLocalTrustRequest +Announce node's local trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceLocalTrustRequest.Body](#neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body) | | Body of the request message. | +| meta_header | [neo.fs.v2.session.RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | Carries request meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) | | Carries request verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceLocalTrustRequest.Body +Announce node's local trust information. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| epoch | [uint64](#uint64) | | Trust assessment Epoch number | +| 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. | + + + + +### Message AnnounceLocalTrustResponse +Node's local trust information announcement response. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body | [AnnounceLocalTrustResponse.Body](#neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body) | | Body of the response message. | +| meta_header | [neo.fs.v2.session.ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) | | Carries response meta information. Header data is used only to regulate message transport and does not affect request execution. | +| verify_header | [neo.fs.v2.session.ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) | | Carries response verification information. This header is used to authenticate the nodes of the message route and check the correctness of transmission. | + + + + +### Message AnnounceLocalTrustResponse.Body +Response to the node's local trust information announcement has an empty body +because the trust exchange operation is asynchronous. If Trust information +does not pass sanity checks, it is silently ignored. + + + + + + + + + +

Top

+ +## reputation/types.proto + + + + + + + +### Message GlobalTrust +Global trust level to NeoFS node. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| 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. | +| body | [GlobalTrust.Body](#neo.fs.v2.reputation.GlobalTrust.Body) | | Message body | +| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of the binary `body` field by the manager. | + + + + +### Message GlobalTrust.Body +Message body structure. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| manager | [PeerID](#neo.fs.v2.reputation.PeerID) | | Node manager ID | +| trust | [Trust](#neo.fs.v2.reputation.Trust) | | Global trust level | + + + + +### Message PeerID +NeoFS unique peer identifier is a 33 byte long compressed public key of the +node, the same as the one stored in the network map. + +String presentation is a +[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. + +JSON value will be data encoded as a string using standard base64 +encoding with paddings. Either +[standard](https://tools.ietf.org/html/rfc4648#section-4) or +[URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding +with/without paddings are accepted. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| public_key | [bytes](#bytes) | | Peer node's public key | + + + + +### Message PeerToPeerTrust +Trust level of a peer to a peer. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| trusting_peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusting peer | +| trust | [Trust](#neo.fs.v2.reputation.Trust) | | Trust level | + + + + +### Message Trust +Trust level to a NeoFS network peer. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| peer | [PeerID](#neo.fs.v2.reputation.PeerID) | | Identifier of the trusted peer | +| value | [double](#double) | | Trust level in [0:1] range | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/service.md b/proto-docs/service.md new file mode 100644 index 0000000..e37ad9f --- /dev/null +++ b/proto-docs/service.md @@ -0,0 +1,125 @@ +# Protocol Documentation + + +## Table of Contents + +- [service/types.proto](#service/types.proto) + + - Messages + - [RequestMetaHeader](#neo.fs.v2.service.RequestMetaHeader) + - [RequestVerificationHeader](#neo.fs.v2.service.RequestVerificationHeader) + - [ResponseMetaHeader](#neo.fs.v2.service.ResponseMetaHeader) + - [ResponseVerificationHeader](#neo.fs.v2.service.ResponseVerificationHeader) + - [XHeader](#neo.fs.v2.service.XHeader) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## service/types.proto + + + + + + + +### Message RequestMetaHeader +Information about the request + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Client API version. | +| epoch | [uint64](#uint64) | | Client local epoch number. Set to 0 if unknown. | +| ttl | [uint32](#uint32) | | Maximum number of nodes in the request route. | +| x_headers | [XHeader](#neo.fs.v2.service.XHeader) | repeated | Request X-Headers. | +| 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 | +| bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | Bearer is a Bearer token of the request | +| origin | [RequestMetaHeader](#neo.fs.v2.service.RequestMetaHeader) | | RequestMetaHeader of the origin request. | + + + + +### Message RequestVerificationHeader +Verification info for request signed by all intermediate nodes + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Body signature. Should be generated once by request initiator. | +| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Request Meta signature is added and signed by any intermediate node | +| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops | +| origin | [RequestVerificationHeader](#neo.fs.v2.service.RequestVerificationHeader) | | Chain of previous hops signatures | + + + + +### Message ResponseMetaHeader +Information about the response + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| version | [neo.fs.v2.refs.Version](#neo.fs.v2.refs.Version) | | Server API version. | +| epoch | [uint64](#uint64) | | Server local epoch number. | +| ttl | [uint32](#uint32) | | Maximum number of nodes in the response route. | +| x_headers | [XHeader](#neo.fs.v2.service.XHeader) | repeated | Response X-Headers. | +| origin | [ResponseMetaHeader](#neo.fs.v2.service.ResponseMetaHeader) | | Carries response meta header of the origin response. | + + + + +### Message ResponseVerificationHeader +Verification info for response signed by all intermediate nodes + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| body_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Body signature. Should be generated once by answering node. | +| meta_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Response Meta signature is added and signed by any intermediate node | +| origin_signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Sign previous hops | +| origin | [ResponseVerificationHeader](#neo.fs.v2.service.ResponseVerificationHeader) | | Chain of previous hops signatures | + + + + +### Message XHeader +Extended headers for Request/Response + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | Key of the X-Header. | +| value | [string](#string) | | Value of the X-Header. | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/session.md b/proto-docs/session.md index 984db48..2cdfd1e 100644 --- a/proto-docs/session.md +++ b/proto-docs/session.md @@ -4,31 +4,31 @@ ## Table of Contents - [session/service.proto](#session/service.proto) - - Services - - [SessionService](#neo.fs.v2.session.SessionService) - + - Services + - [SessionService](#neo.fs.v2.session.SessionService) + - Messages - - [CreateRequest](#neo.fs.v2.session.CreateRequest) - - [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) - - [CreateResponse](#neo.fs.v2.session.CreateResponse) - - [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body) - + - [CreateRequest](#neo.fs.v2.session.CreateRequest) + - [CreateRequest.Body](#neo.fs.v2.session.CreateRequest.Body) + - [CreateResponse](#neo.fs.v2.session.CreateResponse) + - [CreateResponse.Body](#neo.fs.v2.session.CreateResponse.Body) + - [session/types.proto](#session/types.proto) - Messages - - [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) - - [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) - - [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) - - [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) - - [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) - - [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) - - [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) - - [SessionToken](#neo.fs.v2.session.SessionToken) - - [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) - - [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) - - [XHeader](#neo.fs.v2.session.XHeader) - + - [ContainerSessionContext](#neo.fs.v2.session.ContainerSessionContext) + - [ObjectSessionContext](#neo.fs.v2.session.ObjectSessionContext) + - [ObjectSessionContext.Target](#neo.fs.v2.session.ObjectSessionContext.Target) + - [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) + - [RequestVerificationHeader](#neo.fs.v2.session.RequestVerificationHeader) + - [ResponseMetaHeader](#neo.fs.v2.session.ResponseMetaHeader) + - [ResponseVerificationHeader](#neo.fs.v2.session.ResponseVerificationHeader) + - [SessionToken](#neo.fs.v2.session.SessionToken) + - [SessionToken.Body](#neo.fs.v2.session.SessionToken.Body) + - [SessionToken.Body.TokenLifetime](#neo.fs.v2.session.SessionToken.Body.TokenLifetime) + - [XHeader](#neo.fs.v2.session.XHeader) + - [Scalar Value Types](#scalar-value-types) @@ -48,7 +48,7 @@ `SessionService` allows to establish a temporary trust relationship between two peer nodes and generate a `SessionToken` as the proof of trust to be attached in requests for further verification. Please see corresponding -section of FrostFS Technical Specification for details. +section of NeoFS Technical Specification for details. ``` rpc Create(CreateRequest) returns (CreateResponse); @@ -168,7 +168,7 @@ Carries objects involved in the object session. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | 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. | -| 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 FrostFS container referenced by `container` field. Each element MUST have correct format. | +| 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. | @@ -187,7 +187,7 @@ request meta headers are folded in matryoshka style. | session_token | [SessionToken](#neo.fs.v2.session.SessionToken) | | Session token within which the request is sent | | bearer_token | [neo.fs.v2.acl.BearerToken](#neo.fs.v2.acl.BearerToken) | | `BearerToken` with eACL overrides for the request | | origin | [RequestMetaHeader](#neo.fs.v2.session.RequestMetaHeader) | | `RequestMetaHeader` of the origin request | -| magic_number | [uint64](#uint64) | | FrostFS network magic. Must match the value for the network that the server belongs to. | +| magic_number | [uint64](#uint64) | | NeoFS network magic. Must match the value for the network that the server belongs to. | @@ -237,12 +237,12 @@ Verification info for the response signed by all intermediate nodes ### Message SessionToken -FrostFS Session Token. +NeoFS Session Token. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| 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 FrostFS Technical Specification for details. | +| 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. | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signature of `SessionToken` information | @@ -278,27 +278,25 @@ Lifetime parameters of the token. Field names taken from rfc7519. ### Message XHeader -Extended headers for Request/Response. They may contain any user-defined -headers to be interpreted on application level. +Extended headers for Request/Response. They may contain any user-defined headers +to be interpreted on application level. -Key name must be a unique valid UTF-8 string. Value can't be empty. Requests -or Responses with duplicated header names or headers with empty values will -be considered invalid. +Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or +Responses with duplicated header names or headers with empty values will be +considered invalid. -There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__` -is deprecated) prefix that affect system behaviour: +There are some "well-known" headers starting with `__NEOFS__` prefix that +affect system behaviour: -* [ __SYSTEM__NETMAP_EPOCH ] \ - (`__NEOFS__NETMAP_EPOCH` is deprecated) \ +* __NEOFS__NETMAP_EPOCH \ Netmap epoch to use for object placement calculation. The `value` is string encoded `uint64` in decimal presentation. If set to '0' or not set, the current epoch only will be used. -* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ - (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ +* __NEOFS__NETMAP_LOOKUP_DEPTH \ If object can't be found using current epoch's netmap, this header limits how many past epochs the node can look up through. The `value` is string - encoded `uint64` in decimal presentation. If set to '0' or not set, only - the current epoch will be used. + encoded `uint64` in decimal presentation. If set to '0' or not set, only the + current epoch will be used. | Field | Type | Label | Description | @@ -338,7 +336,6 @@ Object request verbs | DELETE | 5 | Refers to object.Delete RPC call | | RANGE | 6 | Refers to object.GetRange RPC call | | RANGEHASH | 7 | Refers to object.GetRangeHash RPC call | -| PATCH | 8 | Refers to object.Patch RPC call | @@ -364,3 +361,4 @@ Object request verbs | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/status.md b/proto-docs/status.md index b00d000..b426326 100644 --- a/proto-docs/status.md +++ b/proto-docs/status.md @@ -6,9 +6,9 @@ - [status/types.proto](#status/types.proto) - Messages - - [Status](#neo.fs.v2.status.Status) - - [Status.Detail](#neo.fs.v2.status.Status.Detail) - + - [Status](#neo.fs.v2.status.Status) + - [Status.Detail](#neo.fs.v2.status.Status.Detail) + - [Scalar Value Types](#scalar-value-types) @@ -26,12 +26,12 @@ ### Message Status -Declares the general format of the status returns of the FrostFS RPC -protocol. Status is present in all response messages. Each RPC of FrostFS -protocol describes the possible outcomes and details of the operation. +Declares the general format of the status returns of the NeoFS RPC protocol. +Status is present in all response messages. Each RPC of NeoFS protocol +describes the possible outcomes and details of the operation. Each status is assigned a one-to-one numeric code. Any unique result of an -operation in FrostFS is unambiguously associated with the code value. +operation in NeoFS is unambiguously associated with the code value. Numerical set of codes is split into 1024-element sections. An enumeration is defined for each section. Values can be referred to in the following ways: @@ -79,17 +79,6 @@ covered by the code. - - -### APEManager -Section of status for APE manager related operations. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| APE_MANAGER_ACCESS_DENIED | 0 | [**5120**] The operation is denied by APE manager. | - - - ### CommonFail @@ -98,11 +87,9 @@ Section of failed statuses independent of the operation. | Name | Number | Description | | ---- | ------ | ----------- | | 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. | -| WRONG_MAGIC_NUMBER | 1 | [**1025**] Wrong magic of the FrostFS network. Details: - [**0**] Magic number of the served FrostFS network (big-endian 64-bit unsigned integer). | +| 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). | | SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. | | NODE_UNDER_MAINTENANCE | 3 | [**1027**] Node is under maintenance. | -| INVALID_ARGUMENT | 4 | [**1028**] Invalid argument error. If the server fails on validation of a request parameter as the client sent it incorrectly, then this code should be used. | -| RESOURCE_EXHAUSTED | 5 | [**1029**] Resource exhausted failure. This code should be used if the operation cannot be performed due to a lack of resources. | @@ -115,7 +102,6 @@ Section of statuses for container-related operations. | ---- | ------ | ----------- | | CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. | | EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. | -| CONTAINER_ACCESS_DENIED | 2 | [**3074**] Container access denied. | @@ -147,7 +133,6 @@ Section identifiers. | SECTION_OBJECT | 2 | Object service-specific errors. | | SECTION_CONTAINER | 3 | Container service-specific errors. | | SECTION_SESSION | 4 | Session service-specific errors. | -| SECTION_APE_MANAGER | 5 | Session service-specific errors. | @@ -166,7 +151,7 @@ Section of statuses for session-related operations. ### Success -Section of FrostFS successful return codes. +Section of NeoFS successful return codes. | Name | Number | Description | | ---- | ------ | ----------- | @@ -196,3 +181,4 @@ Section of FrostFS successful return codes. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/storagegroup.md b/proto-docs/storagegroup.md new file mode 100644 index 0000000..3bc0b5e --- /dev/null +++ b/proto-docs/storagegroup.md @@ -0,0 +1,71 @@ +# Protocol Documentation + + +## Table of Contents + +- [storagegroup/types.proto](#storagegroup/types.proto) + + - Messages + - [StorageGroup](#neo.fs.v2.storagegroup.StorageGroup) + + +- [Scalar Value Types](#scalar-value-types) + + + + +

Top

+ +## storagegroup/types.proto + + + + + + + +### Message StorageGroup +StorageGroup keeps verification information for Data Audit sessions. Objects +that require paid storage guarantees are gathered in `StorageGroups` with +additional information used for the proof of storage. `StorageGroup` only +contains objects from the same container. + +Being an object payload, StorageGroup may have expiration Epoch set with +`__NEOFS__EXPIRATION_EPOCH` well-known attribute. When expired, StorageGroup +will be ignored by InnerRing nodes during Data Audit cycles and will be +deleted by Storage Nodes. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| validation_data_size | [uint64](#uint64) | | Total size of the payloads of objects in the storage group | +| 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. | +| expiration_epoch | [uint64](#uint64) | | DEPRECATED. Last NeoFS epoch number of the storage group lifetime | +| members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | Strictly ordered list of storage group member objects. Members MUST be unique | + + + + + + + +## Scalar Value Types + +| .proto Type | Notes | C++ Type | Java Type | Python Type | +| ----------- | ----- | -------- | --------- | ----------- | +| double | | double | double | float | +| float | | float | float | float | +| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | +| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | +| uint32 | Uses variable-length encoding. | uint32 | int | int/long | +| uint64 | Uses variable-length encoding. | uint64 | long | int/long | +| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | +| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | +| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | +| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | +| sfixed32 | Always four bytes. | int32 | int | int | +| sfixed64 | Always eight bytes. | int64 | long | int/long | +| bool | | bool | boolean | boolean | +| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | +| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/ape.md b/proto-docs/subnet.md similarity index 70% rename from proto-docs/ape.md rename to proto-docs/subnet.md index 9795bc5..a766dc6 100644 --- a/proto-docs/ape.md +++ b/proto-docs/subnet.md @@ -3,65 +3,38 @@ ## Table of Contents -- [ape/types.proto](#ape/types.proto) +- [subnet/types.proto](#subnet/types.proto) - Messages - - [Chain](#frostfs.v2.ape.Chain) - - [ChainTarget](#frostfs.v2.ape.ChainTarget) - + - [SubnetInfo](#neo.fs.v2.subnet.SubnetInfo) + - [Scalar Value Types](#scalar-value-types) - +

Top

-## ape/types.proto +## subnet/types.proto - + -### Message Chain -Chain is a chain of rules defined for a specific target. +### Message SubnetInfo +NeoFS subnetwork description | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| raw | [bytes](#bytes) | | Raw representation of a serizalized rule chain. | - - - - -### Message ChainTarget -ChainTarget is an object to which a rule chain is defined. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| type | [TargetType](#frostfs.v2.ape.TargetType) | | | -| name | [string](#string) | | | +| id | [neo.fs.v2.refs.SubnetID](#neo.fs.v2.refs.SubnetID) | | Unique subnet identifier. Missing ID is equivalent to zero (default subnetwork) ID. | +| owner | [neo.fs.v2.refs.OwnerID](#neo.fs.v2.refs.OwnerID) | | Identifier of the subnetwork owner | - - - -### TargetType -TargetType is a type target to which a rule chain is defined. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| UNDEFINED | 0 | | -| NAMESPACE | 1 | | -| CONTAINER | 2 | | -| USER | 3 | | -| GROUP | 4 | | - - @@ -85,3 +58,4 @@ TargetType is a type target to which a rule chain is defined. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/proto-docs/tombstone.md b/proto-docs/tombstone.md index 467ad55..4657935 100644 --- a/proto-docs/tombstone.md +++ b/proto-docs/tombstone.md @@ -6,8 +6,8 @@ - [tombstone/types.proto](#tombstone/types.proto) - Messages - - [Tombstone](#neo.fs.v2.tombstone.Tombstone) - + - [Tombstone](#neo.fs.v2.tombstone.Tombstone) + - [Scalar Value Types](#scalar-value-types) @@ -26,12 +26,12 @@ ### Message Tombstone Tombstone keeps record of deleted objects for a few epochs until they are -purged from the FrostFS network. +purged from the NeoFS network. | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| expiration_epoch | [uint64](#uint64) | | Last FrostFS epoch number of the tombstone lifetime. It's set by the tombstone creator depending on the current FrostFS network settings. A tombstone object must have the same expiration epoch value in `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) attribute. Otherwise, the tombstone will be rejected by a storage node. | +| 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. A tombstone object must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` attribute. Otherwise, the tombstone will be rejected by a storage node. | | 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. | | members | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | repeated | List of objects to be deleted. | @@ -60,3 +60,4 @@ purged from the FrostFS network. | bool | | bool | boolean | boolean | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | + diff --git a/refs/types.proto b/refs/types.proto index 2464c34..07659f3 100644 --- a/refs/types.proto +++ b/refs/types.proto @@ -1,29 +1,28 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.refs; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/refs/grpc;refs"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/refs/grpc;refs"; option csharp_namespace = "Neo.FileStorage.API.Refs"; -// Objects in FrostFS are addressed by their ContainerID and ObjectID. +// Objects in NeoFS are addressed by their ContainerID and ObjectID. // // String presentation of `Address` is a concatenation of string encoded // `ContainerID` and `ObjectID` delimited by '/' character. message Address { // Container identifier - ContainerID container_id = 1 [ json_name = "containerID" ]; + ContainerID container_id = 1 [json_name = "containerID"]; // Object identifier - ObjectID object_id = 2 [ json_name = "objectID" ]; + ObjectID object_id = 2 [json_name = "objectID"]; } -// FrostFS Object unique identifier. Objects are immutable and -// content-addressed. It means `ObjectID` will change if the `header` or the -// `payload` changes. +// NeoFS Object unique identifier. Objects are immutable and content-addressed. +// It means `ObjectID` will change if the `header` or the `payload` changes. // // `ObjectID` is a 32 byte long // [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of -// the object's `header` field, which, in it's turn, contains the hash of the -// object's payload. +// the object's `header` field, which, in it's turn, contains the hash of the object's +// payload. // // String presentation is a // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. @@ -35,10 +34,10 @@ message Address { // with/without paddings are accepted. message ObjectID { // Object identifier in a binary format - bytes value = 1 [ json_name = "value" ]; + bytes value = 1 [json_name = "value"]; } -// FrostFS container identifier. Container structures are immutable and +// NeoFS container identifier. Container structures are immutable and // content-addressed. // // `ContainerID` is a 32 byte long @@ -55,7 +54,7 @@ message ObjectID { // with/without paddings are accepted. message ContainerID { // Container identifier in a binary format. - bytes value = 1 [ json_name = "value" ]; + bytes value = 1 [json_name = "value"]; } // `OwnerID` is a derivative of a user's main public key. The transformation @@ -75,34 +74,42 @@ message ContainerID { // with/without paddings are accepted. message OwnerID { // Identifier of the container owner in a binary format - bytes value = 1 [ json_name = "value" ]; + bytes value = 1 [json_name = "value"]; +} + +// NeoFS subnetwork identifier. +// +// String representation of a value is base-10 integer. +// +// JSON representation is an object containing a single `value` number field. +message SubnetID { + // 4-byte integer subnetwork identifier. + fixed32 value = 1 [json_name = "value"]; } // API version used by a node. // // String presentation is a Semantic Versioning 2.0.0 compatible version string -// with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor -// number. +// with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number. message Version { // Major API version - uint32 major = 1 [ json_name = "major" ]; + uint32 major = 1 [json_name = "major"]; // Minor API version - uint32 minor = 2 [ json_name = "minor" ]; + uint32 minor = 2 [json_name = "minor"]; } -// Signature of something in FrostFS. +// Signature of something in NeoFS. message Signature { // Public key used for signing - bytes key = 1 [ json_name = "key" ]; + bytes key = 1 [json_name = "key"]; // Signature - bytes sign = 2 [ json_name = "signature" ]; + bytes sign = 2 [json_name = "signature"]; // Scheme contains digital signature scheme identifier - SignatureScheme scheme = 3 [ json_name = "scheme" ]; + SignatureScheme scheme = 3 [json_name = "scheme"]; } -// Signature scheme describes digital signing scheme used for (key, signature) -// pair. +// Signature scheme describes digital signing scheme used for (key, signature) pair. enum SignatureScheme { // ECDSA with SHA-512 hashing (FIPS 186-3) ECDSA_SHA512 = 0; @@ -118,9 +125,9 @@ enum SignatureScheme { // RFC 6979 signature. message SignatureRFC6979 { // Public key used for signing - bytes key = 1 [ json_name = "key" ]; + bytes key = 1 [json_name = "key"]; // Deterministic ECDSA with SHA-256 hashing - bytes sign = 2 [ json_name = "signature" ]; + bytes sign = 2 [json_name = "signature"]; } // Checksum algorithm type. @@ -144,8 +151,8 @@ enum ChecksumType { // Hex encoded string without `0x` prefix message Checksum { // Checksum algorithm type - ChecksumType type = 1 [ json_name = "type" ]; + ChecksumType type = 1 [json_name = "type"]; // Checksum itself - bytes sum = 2 [ json_name = "sum" ]; + bytes sum = 2 [json_name = "sum"]; } diff --git a/reputation/service.proto b/reputation/service.proto new file mode 100644 index 0000000..ecdb60f --- /dev/null +++ b/reputation/service.proto @@ -0,0 +1,128 @@ +syntax = "proto3"; + +package neo.fs.v2.reputation; + +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/reputation/grpc;reputation"; +option csharp_namespace = "Neo.FileStorage.API.Reputation"; + +import "reputation/types.proto"; +import "session/types.proto"; + +// `ReputationService` provides mechanisms for exchanging trust values with +// other NeoFS nodes. Nodes rate each other's reputation based on how good they +// process requests and set a trust level based on that rating. The trust +// information is passed to the next nodes to check and aggregate unless the +// final result is recorded. +service ReputationService { + // Announce local client trust information to any node in NeoFS network. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // local trust has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). + rpc AnnounceLocalTrust (AnnounceLocalTrustRequest) returns (AnnounceLocalTrustResponse); + + // Announce the intermediate result of the iterative algorithm for + // calculating the global reputation of the node in NeoFS network. + // + // Statuses: + // - **OK** (0, SECTION_SUCCESS): + // intermediate trust estimation has been successfully announced; + // - Common failures (SECTION_FAILURE_COMMON). + rpc AnnounceIntermediateResult (AnnounceIntermediateResultRequest) returns (AnnounceIntermediateResultResponse); +} + +// Announce node's local trust information. +message AnnounceLocalTrustRequest { + // Announce node's local trust information. + message Body { + // Trust assessment Epoch number + uint64 epoch = 1; + + // 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. + repeated Trust trusts = 2; + } + + // Body of the request message. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +// Node's local trust information announcement response. +message AnnounceLocalTrustResponse { + // Response to the node's local trust information announcement has an empty body + // because the trust exchange operation is asynchronous. If Trust information + // does not pass sanity checks, it is silently ignored. + message Body { + } + + // Body of the response message. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} + +// Announce intermediate global trust information. +message AnnounceIntermediateResultRequest { + // Announce intermediate global trust information. + message Body { + // Iteration execution Epoch number + uint64 epoch = 1; + + // Iteration sequence number + uint32 iteration = 2; + + // Current global trust value calculated at the specified iteration + PeerToPeerTrust trust = 3; + } + + // Body of the request message. + Body body = 1; + + // Carries request meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.RequestMetaHeader meta_header = 2; + + // Carries request verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.RequestVerificationHeader verify_header = 3; +} + +// Intermediate global trust information announcement response. +message AnnounceIntermediateResultResponse { + // Response to the node's intermediate global trust information announcement has + // an empty body because the trust exchange operation is asynchronous. If + // Trust information does not pass sanity checks, it is silently ignored. + message Body { + } + + // Body of the response message. + Body body = 1; + + // Carries response meta information. Header data is used only to regulate + // message transport and does not affect request execution. + neo.fs.v2.session.ResponseMetaHeader meta_header = 2; + + // Carries response verification information. This header is used to + // authenticate the nodes of the message route and check the correctness of + // transmission. + neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; +} diff --git a/reputation/types.proto b/reputation/types.proto new file mode 100644 index 0000000..11915ae --- /dev/null +++ b/reputation/types.proto @@ -0,0 +1,63 @@ +syntax = "proto3"; + +package neo.fs.v2.reputation; + +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/reputation/grpc;reputation"; +option csharp_namespace = "Neo.FileStorage.API.Reputation"; + +import "refs/types.proto"; + +// NeoFS unique peer identifier is a 33 byte long compressed public key of the +// node, the same as the one stored in the network map. +// +// String presentation is a +// [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. +// +// JSON value will be data encoded as a string using standard base64 +// encoding with paddings. Either +// [standard](https://tools.ietf.org/html/rfc4648#section-4) or +// [URL-safe](https://tools.ietf.org/html/rfc4648#section-5) base64 encoding +// with/without paddings are accepted. +message PeerID { + // Peer node's public key + bytes public_key = 1 [json_name = "publicKey"]; +} + +// Trust level to a NeoFS network peer. +message Trust { + // Identifier of the trusted peer + PeerID peer = 1 [json_name = "peer"]; + + // Trust level in [0:1] range + double value = 2 [json_name = "value"]; +} + +// Trust level of a peer to a peer. +message PeerToPeerTrust { + // Identifier of the trusting peer + PeerID trusting_peer = 1 [json_name = "trustingPeer"]; + + // Trust level + Trust trust = 2 [json_name = "trust"]; +} + +// Global trust level to NeoFS node. +message GlobalTrust { + // Message format version. Effectively, the version of API library used to create + // the message. + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; + // Message body structure. + message Body { + // Node manager ID + PeerID manager = 1 [json_name = "manager"]; + + // Global trust level + Trust trust = 2 [json_name = "trust"]; + } + + // Message body + Body body = 2 [json_name = "body"]; + + // Signature of the binary `body` field by the manager. + neo.fs.v2.refs.Signature signature = 3 [json_name = "signature"]; +} diff --git a/session/service.proto b/session/service.proto index c9a7948..355d3fc 100644 --- a/session/service.proto +++ b/session/service.proto @@ -1,8 +1,8 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.session; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/session/grpc;session"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/session/grpc;session"; option csharp_namespace = "Neo.FileStorage.API.Session"; import "refs/types.proto"; @@ -11,7 +11,7 @@ import "session/types.proto"; // `SessionService` allows to establish a temporary trust relationship between // two peer nodes and generate a `SessionToken` as the proof of trust to be // attached in requests for further verification. Please see corresponding -// section of FrostFS Technical Specification for details. +// section of NeoFS Technical Specification for details. service SessionService { // Open a new session between two peers. // @@ -19,7 +19,7 @@ service SessionService { // - **OK** (0, SECTION_SUCCESS): // session has been successfully opened; // - Common failures (SECTION_FAILURE_COMMON). - rpc Create(CreateRequest) returns (CreateResponse); + rpc Create (CreateRequest) returns (CreateResponse); } // Information necessary for opening a session. diff --git a/session/types.proto b/session/types.proto index 1e5b9db..71c0e54 100644 --- a/session/types.proto +++ b/session/types.proto @@ -1,8 +1,8 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.session; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/session/grpc;session"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/session/grpc;session"; option csharp_namespace = "Neo.FileStorage.API.Session"; import "refs/types.proto"; @@ -36,206 +36,199 @@ message ObjectSessionContext { // Refers to object.GetRangeHash RPC call RANGEHASH = 7; - - // Refers to object.Patch RPC call - PATCH = 8; } // Type of request for which the token is issued - Verb verb = 1 [ json_name = "verb" ]; + Verb verb = 1 [json_name = "verb"]; // Carries objects involved in the object session. message Target { // Indicates which container the session is spread to. Field MUST be set // and correct. - refs.ContainerID container = 1 [ json_name = "container" ]; + refs.ContainerID container = 1 [json_name = "container"]; // Indicates which objects the session is spread to. Objects are expected - // to be stored in the FrostFS container referenced by `container` field. + // to be stored in the NeoFS container referenced by `container` field. // Each element MUST have correct format. - repeated refs.ObjectID objects = 2 [ json_name = "objects" ]; + repeated refs.ObjectID objects = 2 [json_name = "objects"]; } // 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. - Target target = 2 [ json_name = "target" ]; + Target target = 2 [json_name = "target"]; } // Context information for Session Tokens related to ContainerService requests. message ContainerSessionContext { - // Container request verbs - enum Verb { - // Unknown verb - VERB_UNSPECIFIED = 0; + // Container request verbs + enum Verb { + // Unknown verb + VERB_UNSPECIFIED = 0; - // Refers to container.Put RPC call - PUT = 1; + // Refers to container.Put RPC call + PUT = 1; - // Refers to container.Delete RPC call - DELETE = 2; + // Refers to container.Delete RPC call + DELETE = 2; - // Refers to container.SetExtendedACL RPC call - SETEACL = 3; - } - // Type of request for which the token is issued - Verb verb = 1 [ json_name = "verb" ]; + // Refers to container.SetExtendedACL RPC call + SETEACL = 3; + } + // Type of request for which the token is issued + Verb verb = 1 [json_name = "verb"]; - // Spreads the action to all owner containers. - // If set, container_id field is ignored. - bool wildcard = 2 [ json_name = "wildcard" ]; + // Spreads the action to all owner containers. + // If set, container_id field is ignored. + bool wildcard = 2 [json_name = "wildcard"]; - // Particular container to which the action applies. - // Ignored if wildcard flag is set. - refs.ContainerID container_id = 3 [ json_name = "containerID" ]; + // Particular container to which the action applies. + // Ignored if wildcard flag is set. + refs.ContainerID container_id = 3 [json_name = "containerID"]; } -// FrostFS Session Token. +// NeoFS Session Token. message SessionToken { // Session Token body message Body { // Token identifier is a valid UUIDv4 in binary form - bytes id = 1 [ json_name = "id" ]; + bytes id = 1 [json_name = "id"]; // Identifier of the session initiator - neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ]; + neo.fs.v2.refs.OwnerID owner_id = 2 [json_name = "ownerID"]; // Lifetime parameters of the token. Field names taken from rfc7519. message TokenLifetime { // Expiration Epoch - uint64 exp = 1 [ json_name = "exp" ]; + uint64 exp = 1 [json_name = "exp"]; // Not valid before Epoch - uint64 nbf = 2 [ json_name = "nbf" ]; + uint64 nbf = 2 [json_name = "nbf"]; // Issued at Epoch - uint64 iat = 3 [ json_name = "iat" ]; + uint64 iat = 3 [json_name = "iat"]; } // Lifetime of the session - TokenLifetime lifetime = 3 [ json_name = "lifetime" ]; + TokenLifetime lifetime = 3 [json_name = "lifetime"]; // Public key used in session - bytes session_key = 4 [ json_name = "sessionKey" ]; + bytes session_key = 4 [json_name = "sessionKey"]; // Session Context information oneof context { // ObjectService session context - ObjectSessionContext object = 5 [ json_name = "object" ]; + ObjectSessionContext object = 5 [json_name = "object"]; // ContainerService session context - ContainerSessionContext container = 6 [ json_name = "container" ]; + ContainerSessionContext container = 6 [json_name = "container"]; } } // Session Token contains the proof of trust between peers to be attached in // requests for further verification. Please see corresponding section of - // FrostFS Technical Specification for details. - Body body = 1 [ json_name = "body" ]; + // NeoFS Technical Specification for details. + Body body = 1 [json_name = "body"]; // Signature of `SessionToken` information - neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ]; + neo.fs.v2.refs.Signature signature = 2 [json_name = "signature"]; } -// Extended headers for Request/Response. They may contain any user-defined -// headers to be interpreted on application level. +// Extended headers for Request/Response. They may contain any user-defined headers +// to be interpreted on application level. // -// Key name must be a unique valid UTF-8 string. Value can't be empty. Requests -// or Responses with duplicated header names or headers with empty values will -// be considered invalid. +// Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or +// Responses with duplicated header names or headers with empty values will be +// considered invalid. // -// There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__` -// is deprecated) prefix that affect system behaviour: +// There are some "well-known" headers starting with `__NEOFS__` prefix that +// affect system behaviour: // -// * [ __SYSTEM__NETMAP_EPOCH ] \ -// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ +// * __NEOFS__NETMAP_EPOCH \ // Netmap epoch to use for object placement calculation. The `value` is string // encoded `uint64` in decimal presentation. If set to '0' or not set, the // current epoch only will be used. -// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ -// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ +// * __NEOFS__NETMAP_LOOKUP_DEPTH \ // If object can't be found using current epoch's netmap, this header limits // how many past epochs the node can look up through. The `value` is string -// encoded `uint64` in decimal presentation. If set to '0' or not set, only -// the current epoch will be used. +// encoded `uint64` in decimal presentation. If set to '0' or not set, only the +// current epoch will be used. message XHeader { // Key of the X-Header - string key = 1 [ json_name = "key" ]; + string key = 1 [json_name = "key"]; // Value of the X-Header - string value = 2 [ json_name = "value" ]; + string value = 2 [json_name = "value"]; } // Meta information attached to the request. When forwarded between peers, // request meta headers are folded in matryoshka style. message RequestMetaHeader { // Peer's API version used - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Peer's local epoch number. Set to 0 if unknown. - uint64 epoch = 2 [ json_name = "epoch" ]; + uint64 epoch = 2 [json_name = "epoch"]; // Maximum number of intermediate nodes in the request route - uint32 ttl = 3 [ json_name = "ttl" ]; + uint32 ttl = 3 [json_name = "ttl"]; // Request X-Headers - repeated XHeader x_headers = 4 [ json_name = "xHeaders" ]; + repeated XHeader x_headers = 4 [json_name = "xHeaders"]; // Session token within which the request is sent - SessionToken session_token = 5 [ json_name = "sessionToken" ]; + SessionToken session_token = 5 [json_name = "sessionToken"]; // `BearerToken` with eACL overrides for the request - neo.fs.v2.acl.BearerToken bearer_token = 6 [ json_name = "bearerToken" ]; + neo.fs.v2.acl.BearerToken bearer_token = 6 [json_name = "bearerToken"]; // `RequestMetaHeader` of the origin request - RequestMetaHeader origin = 7 [ json_name = "origin" ]; + RequestMetaHeader origin = 7 [json_name = "origin"]; - // FrostFS network magic. Must match the value for the network + // NeoFS network magic. Must match the value for the network // that the server belongs to. - uint64 magic_number = 8 [ json_name = "magicNumber" ]; + uint64 magic_number = 8 [json_name = "magicNumber"]; } // Information about the response message ResponseMetaHeader { // Peer's API version used - neo.fs.v2.refs.Version version = 1 [ json_name = "version" ]; + neo.fs.v2.refs.Version version = 1 [json_name = "version"]; // Peer's local epoch number - uint64 epoch = 2 [ json_name = "epoch" ]; + uint64 epoch = 2 [json_name = "epoch"]; // Maximum number of intermediate nodes in the request route - uint32 ttl = 3 [ json_name = "ttl" ]; + uint32 ttl = 3 [json_name = "ttl"]; // Response X-Headers - repeated XHeader x_headers = 4 [ json_name = "xHeaders" ]; + repeated XHeader x_headers = 4 [json_name = "xHeaders"]; // `ResponseMetaHeader` of the origin request - ResponseMetaHeader origin = 5 [ json_name = "origin" ]; + ResponseMetaHeader origin = 5 [json_name = "origin"]; // Status return - neo.fs.v2.status.Status status = 6 [ json_name = "status" ]; + neo.fs.v2.status.Status status = 6 [json_name = "status"]; } // Verification info for the request signed by all intermediate nodes. message RequestVerificationHeader { // Request Body signature. Should be generated once by the request initiator. - neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ]; + neo.fs.v2.refs.Signature body_signature = 1 [json_name = "bodySignature"]; // Request Meta signature is added and signed by each intermediate node - neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ]; + neo.fs.v2.refs.Signature meta_signature = 2 [json_name = "metaSignature"]; // Signature of previous hops - neo.fs.v2.refs.Signature origin_signature = 3 - [ json_name = "originSignature" ]; + neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"]; // Chain of previous hops signatures - RequestVerificationHeader origin = 4 [ json_name = "origin" ]; + RequestVerificationHeader origin = 4 [json_name = "origin"]; } // Verification info for the response signed by all intermediate nodes message ResponseVerificationHeader { // Response Body signature. Should be generated once by an answering node. - neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ]; + neo.fs.v2.refs.Signature body_signature = 1 [json_name = "bodySignature"]; // Response Meta signature is added and signed by each intermediate node - neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ]; + neo.fs.v2.refs.Signature meta_signature = 2 [json_name = "metaSignature"]; // Signature of previous hops - neo.fs.v2.refs.Signature origin_signature = 3 - [ json_name = "originSignature" ]; + neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"]; // Chain of previous hops signatures - ResponseVerificationHeader origin = 4 [ json_name = "origin" ]; + ResponseVerificationHeader origin = 4 [json_name = "origin"]; } diff --git a/status/types.proto b/status/types.proto index 6a98f84..4c1eb1d 100644 --- a/status/types.proto +++ b/status/types.proto @@ -1,16 +1,16 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.status; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/status/grpc;status"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/status/grpc;status"; option csharp_namespace = "Neo.FileStorage.API.Status"; -// Declares the general format of the status returns of the FrostFS RPC -// protocol. Status is present in all response messages. Each RPC of FrostFS -// protocol describes the possible outcomes and details of the operation. +// Declares the general format of the status returns of the NeoFS RPC protocol. +// Status is present in all response messages. Each RPC of NeoFS protocol +// describes the possible outcomes and details of the operation. // // Each status is assigned a one-to-one numeric code. Any unique result of an -// operation in FrostFS is unambiguously associated with the code value. +// operation in NeoFS is unambiguously associated with the code value. // // Numerical set of codes is split into 1024-element sections. An enumeration // is defined for each section. Values can be referred to in the following ways: @@ -33,134 +33,113 @@ option csharp_namespace = "Neo.FileStorage.API.Status"; // should not expect) useful information in the message. Field `details` // should make the return more detailed. message Status { - // The status code - uint32 code = 1; + // The status code + uint32 code = 1; - // Developer-facing error message - string message = 2; + // Developer-facing error message + string message = 2; - // Return detail. It contains additional information that can be used to - // analyze the response. Each code defines a set of details that can be - // attached to a status. Client should not handle details that are not - // covered by the code. - message Detail { - // Detail ID. The identifier is required to determine the binary format - // of the detail and how to decode it. - uint32 id = 1; + // Return detail. It contains additional information that can be used to + // analyze the response. Each code defines a set of details that can be + // attached to a status. Client should not handle details that are not + // covered by the code. + message Detail { + // Detail ID. The identifier is required to determine the binary format + // of the detail and how to decode it. + uint32 id = 1; - // Binary status detail. Must follow the format associated with ID. - // The possibility of missing a value must be explicitly allowed. - bytes value = 2; - } + // Binary status detail. Must follow the format associated with ID. + // The possibility of missing a value must be explicitly allowed. + bytes value = 2; + } - // Data detailing the outcome of the operation. Must be unique by ID. - repeated Detail details = 3; + // Data detailing the outcome of the operation. Must be unique by ID. + repeated Detail details = 3; } // Section identifiers. enum Section { - // Successful return codes. - SECTION_SUCCESS = 0; + // Successful return codes. + SECTION_SUCCESS = 0; - // Failure codes regardless of the operation. - SECTION_FAILURE_COMMON = 1; + // Failure codes regardless of the operation. + SECTION_FAILURE_COMMON = 1; - // Object service-specific errors. - SECTION_OBJECT = 2; + // Object service-specific errors. + SECTION_OBJECT = 2; - // Container service-specific errors. - SECTION_CONTAINER = 3; + // Container service-specific errors. + SECTION_CONTAINER = 3; - // Session service-specific errors. - SECTION_SESSION = 4; - - // Session service-specific errors. - SECTION_APE_MANAGER = 5; + // Session service-specific errors. + SECTION_SESSION = 4; } -// Section of FrostFS successful return codes. +// Section of NeoFS successful return codes. enum Success { - // [**0**] Default success. Not detailed. - // If the server cannot match successful outcome to the code, it should - // use this code. - OK = 0; + // [**0**] Default success. Not detailed. + // If the server cannot match successful outcome to the code, it should + // use this code. + OK = 0; } // Section of failed statuses independent of the operation. enum CommonFail { - // [**1024**] Internal server error, default failure. Not detailed. - // If the server cannot match failed outcome to the code, it should - // use this code. - 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. + INTERNAL = 0; - // [**1025**] Wrong magic of the FrostFS network. - // Details: - // - [**0**] Magic number of the served FrostFS network (big-endian 64-bit - // unsigned integer). - 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). + WRONG_MAGIC_NUMBER = 1; - // [**1026**] Signature verification failure. - SIGNATURE_VERIFICATION_FAIL = 2; + // [**1026**] Signature verification failure. + SIGNATURE_VERIFICATION_FAIL = 2; - // [**1027**] Node is under maintenance. - NODE_UNDER_MAINTENANCE = 3; - - // [**1028**] Invalid argument error. If the server fails on validation of a - // request parameter as the client sent it incorrectly, then this code should - // be used. - INVALID_ARGUMENT = 4; - - // [**1029**] Resource exhausted failure. This code should be used - // if the operation cannot be performed due to a lack of resources. - RESOURCE_EXHAUSTED = 5; + // [**1027**] Node is under maintenance. + NODE_UNDER_MAINTENANCE = 3; } // Section of statuses for object-related operations. enum Object { - // [**2048**] Access denied by ACL. - // Details: - // - [**0**] Human-readable description (UTF-8 encoded string). - ACCESS_DENIED = 0; + // [**2048**] Access denied by ACL. + // Details: + // - [**0**] Human-readable description (UTF-8 encoded string). + ACCESS_DENIED = 0; - // [**2049**] Object not found. - OBJECT_NOT_FOUND = 1; + // [**2049**] Object not found. + OBJECT_NOT_FOUND = 1; - // [**2050**] Operation rejected by the object lock. - LOCKED = 2; + // [**2050**] Operation rejected by the object lock. + LOCKED = 2; - // [**2051**] Locking an object with a non-REGULAR type rejected. - LOCK_NON_REGULAR_OBJECT = 3; + // [**2051**] Locking an object with a non-REGULAR type rejected. + LOCK_NON_REGULAR_OBJECT = 3; - // [**2052**] Object has been marked deleted. - OBJECT_ALREADY_REMOVED = 4; + // [**2052**] Object has been marked deleted. + OBJECT_ALREADY_REMOVED = 4; - // [**2053**] Invalid range has been requested for an object. - OUT_OF_RANGE = 5; + // [**2053**] Invalid range has been requested for an object. + OUT_OF_RANGE = 5; } // Section of statuses for container-related operations. enum Container { - // [**3072**] Container not found. - CONTAINER_NOT_FOUND = 0; + // [**3072**] Container not found. + CONTAINER_NOT_FOUND = 0; - // [**3073**] eACL table not found. - EACL_NOT_FOUND = 1; - - // [**3074**] Container access denied. - CONTAINER_ACCESS_DENIED = 2; + // [**3073**] eACL table not found. + EACL_NOT_FOUND = 1; } // Section of statuses for session-related operations. enum Session { - // [**4096**] Token not found. - TOKEN_NOT_FOUND = 0; + // [**4096**] Token not found. + TOKEN_NOT_FOUND = 0; - // [**4097**] Token has expired. - TOKEN_EXPIRED = 1; -} - -// Section of status for APE manager related operations. -enum APEManager { - // [**5120**] The operation is denied by APE manager. - APE_MANAGER_ACCESS_DENIED = 0; + // [**4097**] Token has expired. + TOKEN_EXPIRED = 1; } diff --git a/storagegroup/types.proto b/storagegroup/types.proto new file mode 100644 index 0000000..1522f1f --- /dev/null +++ b/storagegroup/types.proto @@ -0,0 +1,34 @@ +syntax = "proto3"; + +package neo.fs.v2.storagegroup; + +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/storagegroup/grpc;storagegroup"; +option csharp_namespace = "Neo.FileStorage.API.StorageGroup"; + +import "refs/types.proto"; + +// StorageGroup keeps verification information for Data Audit sessions. Objects +// that require paid storage guarantees are gathered in `StorageGroups` with +// additional information used for the proof of storage. `StorageGroup` only +// contains objects from the same container. +// +// Being an object payload, StorageGroup may have expiration Epoch set with +// `__NEOFS__EXPIRATION_EPOCH` well-known attribute. When expired, StorageGroup +// will be ignored by InnerRing nodes during Data Audit cycles and will be +// deleted by Storage Nodes. +// +message StorageGroup { + // Total size of the payloads of objects in the storage group + uint64 validation_data_size = 1 [json_name = "validationDataSize"]; + + // 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. + neo.fs.v2.refs.Checksum validation_hash = 2 [json_name = "validationHash"]; + + // DEPRECATED. Last NeoFS epoch number of the storage group lifetime + uint64 expiration_epoch = 3 [json_name = "expirationEpoch", deprecated = true]; + + // Strictly ordered list of storage group member objects. Members MUST be unique + repeated neo.fs.v2.refs.ObjectID members = 4 [json_name = "members"]; +} diff --git a/subnet/types.proto b/subnet/types.proto new file mode 100644 index 0000000..6fe5f36 --- /dev/null +++ b/subnet/types.proto @@ -0,0 +1,18 @@ +syntax = "proto3"; + +package neo.fs.v2.subnet; + +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/subnet/grpc;subnet"; +option csharp_namespace = "Neo.FileStorage.API.Subnet"; + +import "refs/types.proto"; + +// NeoFS subnetwork description +message SubnetInfo { + // Unique subnet identifier. Missing ID is + // equivalent to zero (default subnetwork) ID. + neo.fs.v2.refs.SubnetID id = 1; + + // Identifier of the subnetwork owner + neo.fs.v2.refs.OwnerID owner = 2; +} diff --git a/tombstone/types.proto b/tombstone/types.proto index aac19b0..70ff8db 100644 --- a/tombstone/types.proto +++ b/tombstone/types.proto @@ -1,27 +1,26 @@ -edition = "2023"; +syntax = "proto3"; package neo.fs.v2.tombstone; -option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/tombstone/grpc;tombstone"; +option go_package = "github.com/TrueCloudLab/frostfs-api-go/v2/tombstone/grpc;tombstone"; option csharp_namespace = "Neo.FileStorage.API.Tombstone"; import "refs/types.proto"; // Tombstone keeps record of deleted objects for a few epochs until they are -// purged from the FrostFS network. +// purged from the NeoFS network. message Tombstone { - // Last FrostFS epoch number of the tombstone lifetime. It's set by the - // tombstone creator depending on the current FrostFS network settings. A - // tombstone object must have the same expiration epoch value in - // `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) + // Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone + // creator depending on the current NeoFS network settings. A tombstone object + // must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH` // attribute. Otherwise, the tombstone will be rejected by a storage node. - uint64 expiration_epoch = 1 [ json_name = "expirationEpoch" ]; + uint64 expiration_epoch = 1 [json_name = "expirationEpoch"]; // 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. - bytes split_id = 2 [ json_name = "splitID" ]; + bytes split_id = 2 [json_name = "splitID"]; // List of objects to be deleted. - repeated neo.fs.v2.refs.ObjectID members = 3 [ json_name = "members" ]; + repeated neo.fs.v2.refs.ObjectID members = 3 [json_name = "members"]; }