TrueCloudLab/frostfs-api
26
0
Fork 17
Code Issues 11 Pull requests Releases Activity Actions

Compare commits

base: TrueCloudLab:master
Branches Tags
TrueCloudLab:master
TrueCloudLab:feature/compatibility
TrueCloudLab:rebranding
dkirillov:KirillovDenis/poc/impersonate
dkirillov:master
dkirillov:rebranding
..
compare: dkirillov:KirillovDenis/poc/impersonate
Branches Tags
dkirillov:KirillovDenis/poc/impersonate
dkirillov:master
dkirillov:rebranding
TrueCloudLab:master
TrueCloudLab:feature/compatibility
TrueCloudLab:rebranding

1 commit
master ... KirillovDe

Author SHA1 Message Date
Denis Kirillov
a8344d964d [nspcc-dev#241] Add impersonate field to bearer token 
Signed-off-by: Denis Kirillov <d.kirillov@yadro.com>
 2023-02-21 11:18:35 +03:00
60 changed files with 2335 additions and 2390 deletions
Show stats Expand all files Collapse all files

45
.forgejo/ISSUE_TEMPLATE/bug_report.md
View file

@ -1,45 +0,0 @@
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: community, triage, bug
assignees: ''
---
<!--- Provide a general summary of the issue in the Title above -->
## Expected Behavior
<!--- If you're describing a bug, tell us what should happen -->
<!--- If you're suggesting a change/improvement, tell us how it should work -->
## Current Behavior
<!--- If describing a bug, tell us what happens instead of the expected behavior -->
<!--- If suggesting a change/improvement, explain the difference from current behavior -->
## Possible Solution
<!--- Not obligatory -->
<!--- If no reason/fix/additions for the bug can be suggested, -->
<!--- uncomment the following phrase: -->
<!--- No fix can be suggested by a QA engineer. Further solutions shall be up to developers. -->
## Steps to Reproduce (for bugs)
<!--- Provide a link to a live example, or an unambiguous set of steps to -->
<!--- reproduce this bug. -->
1.
## Context
<!--- How has this issue affected you? What are you trying to accomplish? -->
<!--- Providing context helps us come up with a solution that is most useful in the real world -->
## Regression
<!-- Is this issue a regression? (Yes / No) -->
<!-- If Yes, optionally please include version or commit id or PR# that caused this regression, if you have these details. -->
## Your Environment
<!--- Include as many relevant details about the environment you experienced the bug in -->
* Version used:
* Server setup and configuration:
* Operating System and version (`uname -a`):

1
.forgejo/ISSUE_TEMPLATE/config.yml
View file

@ -1 +0,0 @@
blank_issues_enabled: false

20
.forgejo/ISSUE_TEMPLATE/feature_request.md
View file

@ -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.
<!--- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
## Describe the solution you'd like
<!--- A clear and concise description of what you want to happen. -->
## Describe alternatives you've considered
<!--- A clear and concise description of any alternative solutions or features you've considered. -->
## Additional context
<!--- Add any other context or screenshots about the feature request here. -->

19
.forgejo/workflows/dco.yaml
View file

@ -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 }}'

17
.forgejo/workflows/fmt.yaml
View file

@ -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

18
.forgejo/workflows/pre-commit.yaml
View file

@ -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

1
.github/CODEOWNERS vendored Normal file
View file

@ -0,0 +1 @@
* @alexvanin @realloc @fyrchik @anatoly-bogatyrev

0
.forgejo/logo.svg → .github/logo.svg vendored
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.5 KiB

After

Width:  |  Height:  |  Size: 5.5 KiB

0
.forgejo/markdown.tmpl → .github/markdown.tmpl vendored
View file

36
.github/workflows/buf.yml vendored Normal file
View file

@ -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

21
.github/workflows/dco.yml vendored Normal file
View file

@ -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 }}

1
.gitignore vendored
View file

@ -1 +1,2 @@
.idea .idea

24
.pre-commit-config.yaml
View file

@ -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

11
CHANGELOG.md
View file

@ -1,16 +1,5 @@
# Changelog # 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 (안마도, 鞍馬島) ## [2.14.0] - 2022-09-23 - Anmado (안마도, 鞍馬島)
### Added ### Added

1
CODEOWNERS
View file

@ -1 +0,0 @@
.* @alexvanin @realloc @fyrchik @a.bogatyrev

15
CONTRIBUTING.md
View file

@ -3,8 +3,8 @@
First, thank you for contributing! We love and encourage pull requests from First, thank you for contributing! We love and encourage pull requests from
everyone. Please follow the guidelines: everyone. Please follow the guidelines:
- Check the open [issues](https://git.frostfs.info/TrueCloudLab/frostfs-api/issues) and - Check the open [issues](https://github.com/TrueCloudLab/frostfs-api/issues) and
[pull requests](https://git.frostfs.info/TrueCloudLab/frostfs-api/pulls) for existing [pull requests](https://github.com/TrueCloudLab/frostfs-api/pulls) for existing
discussions. discussions.
- Open an issue first, to discuss a new feature or enhancement. - 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 send a pull request. We encourage pull requests to discuss code changes. Here
are the steps in details: are the steps in details:
### Set up your repository ### Set up your GitHub Repository
Fork [NeoFS node upstream](https://github.com/TrueCloudLab/frostfs-api/fork) source
Fork [FrostFS upstream](https://git.frostfs.info/TrueCloudLab/frostfs-api/fork) source
repository to your own personal repository. Copy the URL of your fork (you will repository to your own personal repository. Copy the URL of your fork (you will
need it for the `git clone` command below). need it for the `git clone` command below).
```sh ```sh
$ git clone https://git.frostfs.info/TrueCloudLab/frostfs-api $ git clone https://github.com/TrueCloudLab/frostfs-api
``` ```
### Set up git remote as ``upstream`` ### Set up git remote as ``upstream``
```sh ```sh
$ cd frostfs-api $ 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 fetch upstream
$ git merge upstream/master $ git merge upstream/master
... ...
@ -87,7 +86,7 @@ $ git push origin feature/123-something_awesome
``` ```
### Create a Pull Request ### 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 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 detailed steps on how to create a pull request. After a Pull Request gets peer
reviewed and approved, it will be merged. reviewed and approved, it will be merged.

30
Makefile Executable file → Normal file
View file

@ -1,35 +1,21 @@
#!/usr/bin/make -f #!/usr/bin/make -f
SHELL=bash 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: # Regenerate documentation for proto files:
doc: doc:
@for f in `find . -type f -name '*.proto' -exec dirname {} \; | sort -u `; do \ @for f in `find . -type f -name '*.proto' -exec dirname {} \; | sort -u `; do \
echo "⇒ Documentation for $$(basename $$f)"; \ echo "⇒ Documentation for $$(basename $$f)"; \
protoc \ protoc \
--doc_opt=.forgejo/markdown.tmpl,$${f}.md \ --doc_opt=.github/markdown.tmpl,$${f}.md \
--proto_path=.:/usr/local/include \ --proto_path=.:/usr/local/include \
--doc_out=proto-docs/ $${f}/*.proto; \ --doc_out=proto-docs/ $${f}/*.proto; \
done 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

9
README.md
View file

@ -1,18 +1,19 @@
<p align="center"> <p align="center">
<img src="./.forgejo/logo.svg" width="500px" alt="FrostFS"> <img src="./.github/logo.svg" width="500px" alt="FrostFS">
</p> </p>
<p align="center"> <p align="center">
<a href="https://frostfs.info">FrostFS</a> API language-agnostic protocol definitions <a href="https://objectstorage.info">FrostFS</a> API language-agnostic protocol definitions
</p> </p>
--- ---
![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 ## Overview
FrostFS-API repository is the basis for language-specific libraries, e.g.: 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 Those libraries contain compiled protocol buffers definitions, wrapped with
language-specific code. Use them to integrate applications with FrostFS. language-specific code. Use them to integrate applications with FrostFS.

23
accounting/service.proto
View file

@ -2,20 +2,20 @@ syntax = "proto3";
package neo.fs.v2.accounting; 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"; option csharp_namespace = "Neo.FileStorage.API.Accounting";
import "accounting/types.proto"; import "accounting/types.proto";
import "refs/types.proto"; import "refs/types.proto";
import "session/types.proto"; import "session/types.proto";
// Accounting service provides methods for interaction with FrostFS sidechain // Accounting service provides methods for interaction with NeoFS sidechain via
// via other FrostFS nodes to get information about the account balance. Deposit // other NeoFS nodes to get information about the account balance. Deposit and
// and Withdraw operations can't be implemented here, as they require Mainnet // Withdraw operations can't be implemented here, as they require Mainnet NeoFS
// FrostFS smart contract invocation. Transfer operations between internal // smart contract invocation. Transfer operations between internal NeoFS
// FrostFS accounts are possible if both use the same token type. // accounts are possible if both use the same token type.
service AccountingService { 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: // Statuses:
// - **OK** (0, SECTION_SUCCESS): // - **OK** (0, SECTION_SUCCESS):
@ -27,9 +27,9 @@ service AccountingService {
// BalanceRequest message // BalanceRequest message
message BalanceRequest { message BalanceRequest {
// To indicate the account for which the balance is requested, its identifier // To indicate the account for which the balance is requested, its identifier
// is used. It can be any existing account in FrostFS sidechain `Balance` // is used. It can be any existing account in NeoFS sidechain `Balance` smart
// smart contract. If omitted, client implementation MUST set it to the // contract. If omitted, client implementation MUST set it to the request's
// request's signer `OwnerID`. // signer `OwnerID`.
message Body { message Body {
// Valid user identifier in `OwnerID` format for which the balance is // Valid user identifier in `OwnerID` format for which the balance is
// requested. Required field. // requested. Required field.
@ -51,8 +51,7 @@ message BalanceRequest {
// BalanceResponse message // BalanceResponse message
message BalanceResponse { message BalanceResponse {
// The amount of funds in GAS token for the `OwnerID`'s account requested. // 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 // Balance is given in the `Decimal` format to avoid precision issues with rounding.
// rounding.
message Body { message Body {
// Amount of funds in GAS token for the requested account. // Amount of funds in GAS token for the requested account.
Decimal balance = 1; Decimal balance = 1;

4
accounting/types.proto
View file

@ -2,10 +2,10 @@ syntax = "proto3";
package neo.fs.v2.accounting; 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"; 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 // of the result when doing lots of small number operations. To solve the lost
// precision issue, special `Decimal` format is used for monetary computations. // precision issue, special `Decimal` format is used for monetary computations.
// //

47
acl/types.proto
View file

@ -2,11 +2,10 @@ syntax = "proto3";
package neo.fs.v2.acl; 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"; option csharp_namespace = "Neo.FileStorage.API.Acl";
import "refs/types.proto"; import "refs/types.proto";
import "ape/types.proto";
// Target role of the access control rule in access control list. // Target role of the access control rule in access control list.
enum Role { enum Role {
@ -20,8 +19,7 @@ enum Role {
// container or an inner ring node // container or an inner ring node
SYSTEM = 2; SYSTEM = 2;
// Others target rule is applied if sender is neither a user nor a system // Others target rule is applied if sender is neither a user nor a system target
// target
OTHERS = 3; OTHERS = 3;
} }
@ -89,14 +87,14 @@ enum HeaderType {
// Filter object headers // Filter object headers
OBJECT = 2; 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. // exist for service use only.
SERVICE = 3; SERVICE = 3;
} }
// Describes a single eACL rule. // Describes a single eACL rule.
message EACLRecord { message EACLRecord {
// FrostFS request Verb to match // NeoFS request Verb to match
Operation operation = 1 [json_name = "operation"]; Operation operation = 1 [json_name = "operation"];
// Rule execution result. Either allows or denies access if filters match. // Rule execution result. Either allows or denies access if filters match.
@ -165,7 +163,7 @@ message EACLRecord {
// Extended ACL rules table. A list of ACL rules defined additionally to Basic // 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 // 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 // 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 { message EACLTable {
// eACL format version. Effectively, the version of API library used to create // eACL format version. Effectively, the version of API library used to create
// eACL Table. // eACL Table.
@ -185,19 +183,16 @@ message EACLTable {
// used in the similar use cases, like providing authorisation to externally // used in the similar use cases, like providing authorisation to externally
// authenticated party. // authenticated party.
// //
// BearerToken can be issued only by the container's owner and must be signed // BearerToken can be issued only by the container's owner and must be signed using
// using the key associated with the container's `OwnerID`. // the key associated with the container's `OwnerID`.
message BearerToken { message BearerToken {
// Bearer Token body structure contains Extended ACL table issued by the // Bearer Token body structure contains Extended ACL table issued by the container
// container owner with additional information preventing token abuse. // owner with additional information preventing token abuse.
message Body { message Body {
// Table of Extended ACL rules to use instead of the ones attached to the // 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 // container. If it contains `container_id` field, bearer token is only
// valid for this specific container. Otherwise, any container of the same // valid for this specific container. Otherwise, any container of the same owner
// owner is allowed. // is allowed.
//
// Deprecated: eACL tables are no longer relevant - `APEOverrides` should be
// used instead.
EACLTable eacl_table = 1 [json_name="eaclTable"]; EACLTable eacl_table = 1 [json_name="eaclTable"];
// `OwnerID` defines to whom the token was issued. It must match the request // `OwnerID` defines to whom the token was issued. It must match the request
@ -221,25 +216,7 @@ message BearerToken {
// AllowImpersonate flag to consider token signer as request owner. // AllowImpersonate flag to consider token signer as request owner.
// If this field is true extended ACL table in token body isn't processed. // If this field is true extended ACL table in token body isn't processed.
bool allow_impersonate = 4 [ json_name = "allowImpersonate" ]; bool AllowImpersonate = 4 [json_name="allow_impersonate"];
// 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" ];
} }
// Bearer Token body // Bearer Token body
Body body = 1 [json_name="body"]; Body body = 1 [json_name="body"];

33
ape/types.proto
View file

@ -1,33 +0,0 @@
syntax = "proto3";
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;
}
}

171
apemanager/service.proto
View file

@ -1,171 +0,0 @@
syntax = "proto3";
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;
}

59
audit/types.proto Normal file
View file

@ -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"];
}

10
buf.yaml Normal file
View file

@ -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

210
container/service.proto
View file

@ -2,42 +2,39 @@ syntax = "proto3";
package neo.fs.v2.container; 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"; option csharp_namespace = "Neo.FileStorage.API.Container";
import "acl/types.proto";
import "container/types.proto"; import "container/types.proto";
import "refs/types.proto"; import "refs/types.proto";
import "session/types.proto"; import "session/types.proto";
// `ContainerService` provides API to interact with `Container` smart contract // `ContainerService` provides API to interact with `Container` smart contract
// in FrostFS sidechain via other FrostFS nodes. All of those actions can be // in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
// done equivalently by directly issuing transactions and RPC calls to sidechain // equivalently by directly issuing transactions and RPC calls to sidechain
// nodes. // nodes.
service ContainerService { service ContainerService {
// `Put` invokes `Container` smart contract's `Put` method and returns // `Put` invokes `Container` smart contract's `Put` method and returns
// response immediately. After a new block is issued in sidechain, request is // response immediately. After a new block is issued in sidechain, request is
// verified by Inner Ring nodes. After one more block in sidechain, the // verified by Inner Ring nodes. After one more block in sidechain, the container
// container is added into smart contract storage. // is added into smart contract storage.
// //
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// request to save the container has been sent to the sidechain; // request to save the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON).
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container create access denied.
rpc Put(PutRequest) returns (PutResponse); rpc Put(PutRequest) returns (PutResponse);
// `Delete` invokes `Container` smart contract's `Delete` method and returns // `Delete` invokes `Container` smart contract's `Delete` method and returns
// response immediately. After a new block is issued in sidechain, request is // response immediately. After a new block is issued in sidechain, request is
// verified by Inner Ring nodes. After one more block in sidechain, the // verified by Inner Ring nodes. After one more block in sidechain, the container
// container is added into smart contract storage. // is added into smart contract storage.
// //
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// request to remove the container has been sent to the sidechain; // request to remove the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON).
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container delete access denied.
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
// Returns container structure from `Container` smart contract storage. // Returns container structure from `Container` smart contract storage.
@ -47,34 +44,50 @@ service ContainerService {
// container has been successfully read; // container has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// requested container not found; // requested container not found.
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied.
rpc Get(GetRequest) returns (GetResponse); 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: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **OK** (0, SECTION_SUCCESS): \
// container list has been successfully read; // container list has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON).
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container list access denied.
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
// Returns all owner's containers from `Container` smart contract storage // Invokes 'SetEACL' method of 'Container` smart contract and returns response
// via stream. // immediately. After one more block in sidechain, changes in an Extended ACL are
// added into smart contract storage.
// //
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): \ // - **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); // - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container list access denied. // container not found;
rpc ListStream(ListStreamRequest) returns (stream ListStreamResponse); // - **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 { message PutRequest {
// Container creation request has container structure's signature as a // Container creation request has container structure's signature as a
// separate field. It's not stored in sidechain, just verified on container // 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 // the stable-marshalled container strucutre, hence there is no need for
// additional signature checks. // additional signature checks.
message Body { message Body {
// Container structure to register in FrostFS // Container structure to register in NeoFS
container.Container container = 1; container.Container container = 1;
// Signature of a stable-marshalled container according to RFC-6979. // Signature of a stable-marshalled container according to RFC-6979.
@ -101,7 +114,7 @@ message PutRequest {
neo.fs.v2.session.RequestVerificationHeader verify_header = 3; neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
} }
// New FrostFS Container creation response // New NeoFS Container creation response
message PutResponse { message PutResponse {
// Container put response body contains information about the newly registered // Container put response body contains information about the newly registered
// container as seen by `Container` smart contract. `ContainerID` can be // 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` // the container owner's intent. The signature will be verified by `Container`
// smart contract, so signing algorithm must be supported by NeoVM. // smart contract, so signing algorithm must be supported by NeoVM.
message Body { 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; neo.fs.v2.refs.ContainerID container_id = 1;
// `ContainerID` signed with the container owner's key according to // `ContainerID` signed with the container owner's key according to RFC-6979.
// RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2; neo.fs.v2.refs.SignatureRFC6979 signature = 2;
} }
// Body of container delete request message. // Body of container delete request message.
@ -257,14 +269,18 @@ message ListResponse {
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
} }
// List containers stream // Set Extended ACL
message ListStreamRequest { message SetExtendedACLRequest {
// List containers stream request body. // Set Extended ACL request body does not have separate `ContainerID`
// reference. It will be taken from `EACLTable.container_id` field.
message Body { message Body {
// Identifier of the container owner. // Extended ACL table to set for the container
neo.fs.v2.refs.OwnerID owner_id = 1; 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; Body body = 1;
// Carries request meta information. Header data is used only to regulate // 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; neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
} }
// List containers stream // Set Extended ACL
message ListStreamResponse { message SetExtendedACLResponse {
// List containers stream response body. // `SetExtendedACLResponse` has an empty body because the operation is
message Body { // asynchronous and the update should be reflected in `Container` smart contract's
// List of `ContainerID`s belonging to the requested `OwnerID` // storage after next block is issued in sidechain.
repeated refs.ContainerID container_ids = 1; 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; Body body = 1;
// Carries response meta information. Header data is used only to regulate // Carries response meta information. Header data is used only to regulate

44
container/types.proto
View file

@ -2,7 +2,7 @@ syntax = "proto3";
package neo.fs.v2.container; 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"; option csharp_namespace = "Neo.FileStorage.API.Container";
import "netmap/types.proto"; import "netmap/types.proto";
@ -10,8 +10,8 @@ import "refs/types.proto";
// Container is a structure that defines object placement behaviour. Objects can // Container is a structure that defines object placement behaviour. Objects can
// be stored only within containers. They define placement rule, attributes and // 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 // access control information. An ID of a container is a 32 byte long SHA256 hash
// hash of stable-marshalled container message. // of stable-marshalled container message.
message Container { message Container {
// Container format version. Effectively, the version of API library used to // Container format version. Effectively, the version of API library used to
// create the container. // create the container.
@ -23,13 +23,13 @@ message Container {
// Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s // 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 // `BasicACL` contains access control rules for the owner, system and others groups,
// groups, as well as permission bits for `BearerToken` and `Extended ACL` // as well as permission bits for `BearerToken` and `Extended ACL`
uint32 basic_acl = 4 [json_name = "basicACL"]; uint32 basic_acl = 4 [json_name = "basicACL"];
// `Attribute` is a user-defined Key-Value metadata pair attached to the // `Attribute` is a user-defined Key-Value metadata pair attached to the
// container. Container attributes are immutable. They are set at the moment // container. Container attributes are immutable. They are set at the moment of
// of container creation and can never be added or updated. // container creation and can never be added or updated.
// //
// Key name must be a container-unique valid UTF-8 string. Value can't be // 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 // 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: // There are some "well-known" attributes affecting system behaviour:
// //
// * [ __SYSTEM__NAME ] \ // * __NEOFS__SUBNET \
// (`__NEOFS__NAME` is deprecated) \ // 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 // String of a human-friendly container name registered as a domain in
// NNS contract. // NNS contract.
// * [ __SYSTEM__ZONE ] \ // * __NEOFS__ZONE \
// (`__NEOFS__ZONE` is deprecated) \ // String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS
// String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated). // contract. If no zone is specified, use default zone: `container`.
// Used as a TLD of a domain name in NNS contract. If no zone is specified, // * __NEOFS__DISABLE_HOMOMORPHIC_HASHING \
// use default zone: `container`. // Disables homomorphic hashing for the container if the value equals "true" string.
// * [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \ // Any other values are interpreted as missing attribute. Container could be
// (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ // accepted in a NeoFS network only if the global network hashing configuration
// Disables homomorphic hashing for the container if the value equals "true" // value corresponds with that attribute's value. After container inclusion, network
// string. Any other values are interpreted as missing attribute. Container // setting is ignored.
// 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.
// //
// And some well-known attributes used by applications only: // And some well-known attributes used by applications only:
// //
@ -71,6 +70,5 @@ message Container {
repeated Attribute attributes = 5 [json_name = "attributes"]; repeated Attribute attributes = 5 [json_name = "attributes"];
// Placement policy for the object inside the container // Placement policy for the object inside the container
neo.fs.v2.netmap.PlacementPolicy placement_policy = 6 neo.fs.v2.netmap.PlacementPolicy placement_policy = 6 [json_name = "placementPolicy"];
[ json_name = "placementPolicy" ];
} }

13
doc/release_instructions.md
View file

@ -1,6 +1,6 @@
# Release instructions # 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. list for a new release.
## Pre-release checks ## 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 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 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, 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. available.
## Release commit ## Release commit
@ -38,7 +38,7 @@ Release v2.9.0 - Anmyeondo (안면도, 安眠島)
Use `vX.Y.Z` tag following the semantic versioning standard. For pre-release Use `vX.Y.Z` tag following the semantic versioning standard. For pre-release
versions use `vX.Y.Z-rc.N` scheme. 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 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` 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 $ 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 `<version> <Romanized codename> (<Hangeul, Hanja Release title has to follow `<version> <Romanized codename> (<Hangeul, Hanja
codename> )` scheme for major releases and just `<version>` for regular point codename> )` scheme for major releases and just `<version>` for regular point
@ -58,5 +58,6 @@ releases.
## Post-release actions ## Post-release actions
* Close corresponding X.Y.Z milestone * Close corresponding X.Y.Z Github milestone
* Make announcements in Matrix and Discord channels * Make announcements in Matrix and Discord channels
* Update [NeoFS Technical Specification](https://github.com/nspcc-dev/neofs-spec)

11
help.mk
View file

@ -1,11 +0,0 @@
.PHONY: help
# Show this help prompt
help:
@echo ' Usage:'
@echo ''
@echo ' make <target>'
@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

7
lock/types.proto
View file

@ -2,16 +2,15 @@ syntax = "proto3";
package neo.fs.v2.lock; 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"; option csharp_namespace = "Neo.FileStorage.API.Lock";
import "refs/types.proto"; import "refs/types.proto";
// Lock objects protects a list of objects from being deleted. The lifetime of a // Lock objects protects a list of objects from being deleted. The lifetime of a
// lock object is limited similar to regular objects in // lock object is limited similar to regular objects in
// `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) // `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch.
// attribute. Lock object MUST have expiration epoch. It is impossible to delete // It is impossible to delete a lock object via ObjectService.Delete RPC call.
// a lock object via ObjectService.Delete RPC call.
message Lock { message Lock {
// List of objects to lock. Must not be empty or carry empty IDs. // List of objects to lock. Must not be empty or carry empty IDs.
// All members must be of the `REGULAR` type. // All members must be of the `REGULAR` type.

36
netmap/service.proto
View file

@ -2,24 +2,23 @@ syntax = "proto3";
package neo.fs.v2.netmap; 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"; option csharp_namespace = "Neo.FileStorage.API.Netmap";
import "netmap/types.proto"; import "netmap/types.proto";
import "refs/types.proto"; import "refs/types.proto";
import "session/types.proto"; import "session/types.proto";
// `NetmapService` provides methods to work with `Network Map` and the // `NetmapService` provides methods to work with `Network Map` and the information
// information required to build it. The resulting `Network Map` is stored in // required to build it. The resulting `Network Map` is stored in sidechain
// sidechain `Netmap` smart contract, while related information can be obtained // `Netmap` smart contract, while related information can be obtained from other
// from other FrostFS nodes. // NeoFS nodes.
service NetmapService { service NetmapService {
// Get NodeInfo structure from the particular node directly. // Get NodeInfo structure from the particular node directly.
// Node information can be taken from `Netmap` smart contract. In some cases, // Node information can be taken from `Netmap` smart contract. In some cases, though,
// though, one may want to get recent information directly or to talk to the // one may want to get recent information directly or to talk to the node not yet
// node not yet present in the `Network Map` to find out what API version can // present in the `Network Map` to find out what API version can be used for
// be used for further communication. This can be also used to check if a node // further communication. This can be also used to check if a node is up and running.
// is up and running.
// //
// Statuses: // Statuses:
// - **OK** (0, SECTION_SUCCESS): // - **OK** (0, SECTION_SUCCESS):
@ -27,7 +26,7 @@ service NetmapService {
// - Common failures (SECTION_FAILURE_COMMON). // - 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: // Statuses:
// - **OK** (0, SECTION_SUCCESS): // - **OK** (0, SECTION_SUCCESS):
@ -35,7 +34,7 @@ service NetmapService {
// - Common failures (SECTION_FAILURE_COMMON). // - 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: // Statuses:
// - **OK** (0, SECTION_SUCCESS): // - **OK** (0, SECTION_SUCCESS):
@ -47,7 +46,8 @@ service NetmapService {
// Get NodeInfo structure directly from a particular node // Get NodeInfo structure directly from a particular node
message LocalNodeInfoRequest { message LocalNodeInfoRequest {
// LocalNodeInfo request body is empty. // LocalNodeInfo request body is empty.
message Body {} message Body {
}
// Body of the LocalNodeInfo request message // Body of the LocalNodeInfo request message
Body body = 1; Body body = 1;
@ -65,7 +65,7 @@ message LocalNodeInfoRequest {
message LocalNodeInfoResponse { message LocalNodeInfoResponse {
// Local Node Info, including API Version in use. // Local Node Info, including API Version in use.
message Body { message Body {
// Latest FrostFS API version in use // Latest NeoFS API version in use
neo.fs.v2.refs.Version version = 1; neo.fs.v2.refs.Version version = 1;
// NodeInfo structure with recent information from node itself // NodeInfo structure with recent information from node itself
@ -87,7 +87,8 @@ message LocalNodeInfoResponse {
// Get NetworkInfo structure with the network view from a particular node. // Get NetworkInfo structure with the network view from a particular node.
message NetworkInfoRequest { message NetworkInfoRequest {
// NetworkInfo request body is empty. // NetworkInfo request body is empty.
message Body {} message Body {
}
// Body of the NetworkInfo request message // Body of the NetworkInfo request message
Body body = 1; Body body = 1;
@ -125,7 +126,8 @@ message NetworkInfoResponse {
// Get netmap snapshot request // Get netmap snapshot request
message NetmapSnapshotRequest { message NetmapSnapshotRequest {
// Get netmap snapshot request body. // Get netmap snapshot request body.
message Body {} message Body {
}
// Body of get netmap snapshot request message. // Body of get netmap snapshot request message.
Body body = 1; Body body = 1;
@ -138,6 +140,7 @@ message NetmapSnapshotRequest {
// authenticate the nodes of the message route and check the correctness of // authenticate the nodes of the message route and check the correctness of
// transmission. // transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3; neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
} }
// Response with current netmap snapshot // Response with current netmap snapshot
@ -159,4 +162,5 @@ message NetmapSnapshotResponse {
// authenticate the nodes of the message route and check the correctness of // authenticate the nodes of the message route and check the correctness of
// transmission. // transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
} }

127
netmap/types.proto
View file

@ -2,9 +2,11 @@ syntax = "proto3";
package neo.fs.v2.netmap; 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"; option csharp_namespace = "Neo.FileStorage.API.Netmap";
import "refs/types.proto";
// Operations on filters // Operations on filters
enum Operation { enum Operation {
// No Operation defined // No Operation defined
@ -33,12 +35,6 @@ enum Operation {
// Logical AND // Logical AND
AND = 8; AND = 8;
// Logical negation
NOT = 9;
// Matches pattern
LIKE = 10;
} }
// Selector modifier shows how the node set will be formed. By default selector // Selector modifier shows how the node set will be formed. By default selector
@ -55,8 +51,8 @@ enum Clause {
DISTINCT = 2; DISTINCT = 2;
} }
// This filter will return the subset of nodes from `NetworkMap` or another // This filter will return the subset of nodes from `NetworkMap` or another filter's
// filter's results that will satisfy filter's conditions. // results that will satisfy filter's conditions.
message Filter { message Filter {
// Name of the filter or a reference to a named filter. '*' means // 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 // application to the whole unfiltered NetworkMap. At top level it's used as a
@ -106,12 +102,6 @@ message Replica {
// Named selector bucket to put replicas // Named selector bucket to put replicas
string selector = 2 [json_name = "selector"]; 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" ];
} }
// Set of rules to select a subset of nodes from `NetworkMap` able to store // Set of rules to select a subset of nodes from `NetworkMap` able to store
@ -122,7 +112,7 @@ message PlacementPolicy {
// bucket // 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 // alternatives to include into container's nodes subset
uint32 container_backup_factor = 2 [json_name = "containerBackupFactor"]; uint32 container_backup_factor = 2 [json_name = "containerBackupFactor"];
@ -132,33 +122,34 @@ message PlacementPolicy {
// List of named filters to reference in 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 // Subnetwork ID to select nodes from. Zero subnet (default) represents
bool unique = 5 [ json_name = "unique" ]; // 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 { message NodeInfo {
// Public key of the FrostFS node in a binary format // Public key of the NeoFS node in a binary format
bytes public_key = 1 [json_name = "publicKey"]; bytes public_key = 1 [json_name = "publicKey"];
// Ways to connect to a node // 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 // `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8
// string. Value can't be empty. // string. Value can't be empty.
// //
// Attributes can be constructed into a chain of attributes: any attribute can // 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 // have a parent attribute and a child attribute (except the first and the last
// last one). A string representation of the chain of attributes in FrostFS // one). A string representation of the chain of attributes in NeoFS Storage
// Storage Node configuration uses ":" and "/" symbols, e.g.: // 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 // Therefore the string attribute representation in the Node configuration must
// must use "\:", "\/" and "\\" escaped symbols if any of them appears in an // use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's
// attribute's key or value. // key or value.
// //
// Node's attributes are mostly used during Storage Policy evaluation to // Node's attributes are mostly used during Storage Policy evaluation to
// calculate object's placement and find a set of nodes satisfying policy // 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 // 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 // point delimiter for decimal part. In the Network Map it will be saved as
// 64-bit unsigned integer representing number of minimal token fractions. // 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 \ // * UN-LOCODE \
// Node's geographic location in // Node's geographic location in
// [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html) // [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 // [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated
// automatically from `UN-LOCODE` attribute. // automatically from `UN-LOCODE` attribute.
// * Continent \ // * Continent \
// Node's continent name according to the [Seven-Continent // Node's continent name according to the [Seven-Continent model]
// model](https://en.wikipedia.org/wiki/Continent#Number). Calculated // (https://en.wikipedia.org/wiki/Continent#Number). Calculated
// automatically from `UN-LOCODE` attribute. // automatically from `UN-LOCODE` attribute.
// * ExternalAddr // * ExternalAddr
// Node's preferred way for communications with external clients. // Node's preferred way for communications with external clients.
@ -210,7 +208,7 @@ message NodeInfo {
// Must contain a comma-separated list of multi-addresses. // Must contain a comma-separated list of multi-addresses.
// //
// For detailed description of each well-known attribute please see the // 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 { message Attribute {
// Key of the node attribute // Key of the node attribute
string key = 1 [json_name = "key"]; string key = 1 [json_name = "key"];
@ -222,13 +220,13 @@ message NodeInfo {
// `Country`. // `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 // 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 // structures with duplicated attribute names or attributes with empty values
// will be considered invalid. // 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 { enum State {
// Unknown state // Unknown state
UNSPECIFIED = 0; UNSPECIFIED = 0;
@ -243,7 +241,7 @@ message NodeInfo {
MAINTENANCE = 3; MAINTENANCE = 3;
} }
// Carries state of the FrostFS node // Carries state of the NeoFS node
State state = 4 [json_name = "state"]; State state = 4 [json_name = "state"];
} }
@ -256,7 +254,7 @@ message Netmap {
repeated NodeInfo nodes = 2 [json_name = "nodes"]; repeated NodeInfo nodes = 2 [json_name = "nodes"];
} }
// FrostFS network configuration // NeoFS network configuration
message NetworkConfig { message NetworkConfig {
// Single configuration parameter. Key MUST be network-unique. // Single configuration parameter. Key MUST be network-unique.
// //
@ -274,8 +272,15 @@ message NetworkConfig {
// - **ContainerFee** \ // - **ContainerFee** \
// Fee paid for container creation by the container owner. // Fee paid for container creation by the container owner.
// Value: little-endian integer. Default: 0. // 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** \ // - **EpochDuration** \
// FrostFS epoch duration measured in Sidechain blocks. // NeoFS epoch duration measured in Sidechain blocks.
// Value: little-endian integer. Default: 0. // Value: little-endian integer. Default: 0.
// - **HomomorphicHashingDisabled** \ // - **HomomorphicHashingDisabled** \
// Flag of disabling the homomorphic hashing of objects' payload. // Flag of disabling the homomorphic hashing of objects' payload.
@ -287,48 +292,11 @@ message NetworkConfig {
// Flag allowing setting the MAINTENANCE state to storage nodes. // Flag allowing setting the MAINTENANCE state to storage nodes.
// Value: true if any byte != 0. Default: false. // Value: true if any byte != 0. Default: false.
// - **MaxObjectSize** \ // - **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. // 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** \ // - **WithdrawFee** \
// Fee paid for withdrawal of funds paid by the account owner. // Fee paid for withdrawal of funds paid by the account owner.
// Value: little-endian integer. Default: 0. // 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 { message Parameter {
// Parameter key. UTF-8 encoded string // Parameter key. UTF-8 encoded string
bytes key = 1 [json_name = "key"]; bytes key = 1 [json_name = "key"];
@ -340,18 +308,17 @@ message NetworkConfig {
repeated Parameter parameters = 1 [json_name = "parameters"]; repeated Parameter parameters = 1 [json_name = "parameters"];
} }
// Information about FrostFS network // Information about NeoFS network
message NetworkInfo { message NetworkInfo {
// Number of the current epoch in the FrostFS network // Number of the current epoch in the NeoFS network
uint64 current_epoch = 1 [json_name = "currentEpoch"]; uint64 current_epoch = 1 [json_name = "currentEpoch"];
// Magic number of the sidechain of the FrostFS network // Magic number of the sidechain of the NeoFS network
uint64 magic_number = 2 [json_name = "magicNumber"]; uint64 magic_number = 2 [json_name = "magicNumber"];
// MillisecondsPerBlock network parameter of the sidechain of the FrostFS // MillisecondsPerBlock network parameter of the sidechain of the NeoFS network
// network
int64 ms_per_block = 3 [json_name = "msPerBlock"]; int64 ms_per_block = 3 [json_name = "msPerBlock"];
// FrostFS network configuration // NeoFS network configuration
NetworkConfig network_config = 4 [json_name = "networkConfig"]; NetworkConfig network_config = 4 [json_name = "networkConfig"];
} }

331
object/service.proto
View file

@ -2,7 +2,7 @@ syntax = "proto3";
package neo.fs.v2.object; 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"; option csharp_namespace = "Neo.FileStorage.API.Object";
import "object/types.proto"; 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. // not affect the sidechain and are only served by nodes in p2p style.
service ObjectService { service ObjectService {
// Receive full object structure, including Headers and payload. Response uses // Receive full object structure, including Headers and payload. Response uses
// gRPC stream. First response message carries the object with the requested // gRPC stream. First response message carries the object with the requested address.
// address. Chunk messages are parts of the object's payload if it is needed. // Chunk messages are parts of the object's payload if it is needed. All
// All messages, except the first one, carry payload chunks. The requested // messages, except the first one, carry payload chunks. The requested object can
// object can be restored by concatenation of object message payload and all // be restored by concatenation of object message payload and all chunks
// chunks keeping the receiving order. // keeping the receiving order.
// //
// Extended headers can change `Get` behaviour: // Extended headers can change `Get` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requsted version of Network Map for object placement // Will use the requsted version of Network Map for object placement
// calculation. // calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ // * __NEOFS__NETMAP_LOOKUP_DEPTH \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ // Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or
// Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH` // the latest one otherwise) of Network Map to find an object until the depth
// (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one // limit is reached.
// otherwise) of Network Map to find an object until the depth limit is
// reached.
// //
// Please refer to detailed `XHeader` description. // Please refer to detailed `XHeader` description.
// //
@ -45,8 +42,6 @@ service ObjectService {
// the requested object has been marked as deleted; // the requested object has been marked as deleted;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Get(GetRequest) returns (stream GetResponse); rpc Get(GetRequest) returns (stream GetResponse);
@ -59,8 +54,7 @@ service ObjectService {
// Chunk messages SHOULD be sent in the direct order of fragmentation. // Chunk messages SHOULD be sent in the direct order of fragmentation.
// //
// Extended headers can change `Put` behaviour: // Extended headers can change `Put` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requsted version of Network Map for object placement // Will use the requsted version of Network Map for object placement
// calculation. // calculation.
// //
@ -73,18 +67,15 @@ service ObjectService {
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// write access to the container is denied; // write access to the container is denied;
// - **LOCKED** (2050, SECTION_OBJECT): \ // - **LOCKED** (2050, SECTION_OBJECT): \
// placement of an object of type TOMBSTONE that includes at least one // placement of an object of type TOMBSTONE that includes at least one locked
// locked object is prohibited; // object is prohibited;
// - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ // - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
// placement of an object of type LOCK that includes at least one object of // placement of an object of type LOCK that includes at least one object of
// type other than REGULAR is prohibited; // type other than REGULAR is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object storage container not found; // object storage container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ // - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
// (for trusted object preparation) session private key does not exist or // (for trusted object preparation) session private key does not exist or has
// has
// been deleted; // been deleted;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
@ -94,9 +85,8 @@ service ObjectService {
// guarantee. Object will be marked for removal and deleted eventually. // guarantee. Object will be marked for removal and deleted eventually.
// //
// Extended headers can change `Delete` behaviour: // Extended headers can change `Delete` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ // Will use the requsted version of Network Map for object placement
// Will use the requested version of Network Map for object placement
// calculation. // calculation.
// //
// Please refer to detailed `XHeader` description. // Please refer to detailed `XHeader` description.
@ -107,15 +97,10 @@ service ObjectService {
// - Common failures (SECTION_FAILURE_COMMON); // - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \ // - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// delete access to the object is denied; // 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): \ // - **LOCKED** (2050, SECTION_OBJECT): \
// deleting a locked object is prohibited; // deleting a locked object is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
@ -125,9 +110,8 @@ service ObjectService {
// the very minimal information will be returned instead. // the very minimal information will be returned instead.
// //
// Extended headers can change `Head` behaviour: // Extended headers can change `Head` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ // Will use the requsted version of Network Map for object placement
// Will use the requested version of Network Map for object placement
// calculation. // calculation.
// //
// Please refer to detailed `XHeader` description. // Please refer to detailed `XHeader` description.
@ -144,20 +128,17 @@ service ObjectService {
// the requested object has been marked as deleted; // the requested object has been marked as deleted;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Head(HeadRequest) returns (HeadResponse); rpc Head(HeadRequest) returns (HeadResponse);
// Search objects in container. Search query allows to match by Object // 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. // Specification section for more details.
// //
// Extended headers can change `Search` behaviour: // Extended headers can change `Search` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ // Will use the requsted version of Network Map for object placement
// Will use the requested version of Network Map for object placement
// calculation. // calculation.
// //
// Please refer to detailed `XHeader` description. // Please refer to detailed `XHeader` description.
@ -170,24 +151,20 @@ service ObjectService {
// access to operation SEARCH of the object is denied; // access to operation SEARCH of the object is denied;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// search container not found; // search container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc Search(SearchRequest) returns (stream SearchResponse); rpc Search(SearchRequest) returns (stream SearchResponse);
// Get byte range of data payload. Range is set as an (offset, length) tuple. // 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 // Like in `Get` method, the response uses gRPC stream. Requested range can be
// restored by concatenation of all received payload chunks keeping the // restored by concatenation of all received payload chunks keeping the receiving
// receiving order. // order.
// //
// Extended headers can change `GetRange` behaviour: // Extended headers can change `GetRange` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ // Will use the requsted version of Network Map for object placement
// Will use the requested version of Network Map for object placement
// calculation. // calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ // * __NEOFS__NETMAP_LOOKUP_DEPTH \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// Will try older versions of Network Map to find an object until the depth // Will try older versions of Network Map to find an object until the depth
// limit is reached. // limit is reached.
// //
@ -207,8 +184,6 @@ service ObjectService {
// the requested range is out of bounds; // the requested range is out of bounds;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
@ -219,12 +194,10 @@ service ObjectService {
// the request. Note that hash is calculated for XORed data. // the request. Note that hash is calculated for XORed data.
// //
// Extended headers can change `GetRangeHash` behaviour: // Extended headers can change `GetRangeHash` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \ // Will use the requsted version of Network Map for object placement
// Will use the requested version of Network Map for object placement
// calculation. // calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ // * __NEOFS__NETMAP_LOOKUP_DEPTH \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// Will try older versions of Network Map to find an object until the depth // Will try older versions of Network Map to find an object until the depth
// limit is reached. // limit is reached.
// //
@ -242,96 +215,9 @@ service ObjectService {
// the requested range is out of bounds; // the requested range is out of bounds;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ // - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found; // object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ // - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired. // provided session token has expired.
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); 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 // GET object request
@ -384,9 +270,6 @@ message GetResponse {
// Meta information of split hierarchy for object assembly. // Meta information of split hierarchy for object assembly.
SplitInfo split_info = 3; SplitInfo split_info = 3;
// Meta information for EC object assembly.
ECInfo ec_info = 4;
} }
} }
// Body of get object response message. // Body of get object response message.
@ -418,17 +301,9 @@ message PutRequest {
// Object's Header // Object's Header
Header header = 3; Header header = 3;
// Number of copies of the object to store within the RPC call. By // Number of the object copies to store within the RPC call. By default
// default, object is processed according to the container's placement // object is processed according to the container's placement policy.
// policy. Can be one of: uint32 copies_number = 4;
// 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;
} }
// Single message in the request stream. // Single message in the request stream.
oneof object_part { oneof object_part {
@ -571,9 +446,6 @@ message HeadResponse {
// Meta information of split hierarchy. // Meta information of split hierarchy.
SplitInfo split_info = 3; SplitInfo split_info = 3;
// Meta information for EC object assembly.
ECInfo ec_info = 4;
} }
} }
// Body of head object response message. // Body of head object response message.
@ -598,11 +470,11 @@ message SearchRequest {
// Version of the Query Language used // Version of the Query Language used
uint32 version = 2; uint32 version = 2;
// Filter structure checks if the object header field or the attribute // Filter structure checks if the object header field or the attribute content
// content matches a value. // matches a value.
// //
// If no filters are set, search request will return all objects of the // 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 // objects. Most human users expect to get only object they can directly
// work with. In that case, `$Object:ROOT` filter should be used. // work with. In that case, `$Object:ROOT` filter should be used.
// //
@ -632,19 +504,16 @@ message SearchRequest {
// object_id of parent // object_id of parent
// * $Object:split.splitID \ // * $Object:split.splitID \
// 16 byte UUIDv4 used to identify the split object hierarchy parts // 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 // There are some well-known filter aliases to match objects by certain
// properties: // properties:
// //
// * $Object:ROOT \ // * $Object:ROOT \
// Returns only `REGULAR` type objects that are not split or that are the // Returns only `REGULAR` type objects that are not split or that are the top
// top level root objects in a split hierarchy. This includes objects not // level root objects in a split hierarchy. This includes objects not
// present physically, like large objects split into smaller objects // present physically, like large objects split into smaller objects
// without a separate top-level root object. Objects of other types like // 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 // useful for listing objects like `ls` command of some virtual file
// system. This filter is activated if the `key` exists, disregarding the // system. This filter is activated if the `key` exists, disregarding the
// value and matcher type. // value and matcher type.
@ -653,8 +522,8 @@ message SearchRequest {
// activated if the `key` exists, disregarding the value and matcher type. // activated if the `key` exists, disregarding the value and matcher type.
// //
// Note: using filters with a key with prefix `$Object:` and match 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 // `NOT_PRESENT `is not recommended since this is not a cross-version approach.
// approach. Behavior when processing this kind of filters is undefined. // Behavior when processing this kind of filters is undefined.
message Filter { message Filter {
// Match type to use // Match type to use
MatchType match_type = 1 [json_name = "matchType"]; MatchType match_type = 1 [json_name = "matchType"];
@ -752,9 +621,6 @@ message GetRangeResponse {
// Meta information of split hierarchy. // Meta information of split hierarchy.
SplitInfo split_info = 2; SplitInfo split_info = 2;
// Meta information for EC object assembly.
ECInfo ec_info = 3;
} }
} }
@ -822,118 +688,3 @@ message GetRangeHashResponse {
// transmission. // transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3; 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;
// 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;
}

97
object/types.proto
View file

@ -2,19 +2,20 @@ syntax = "proto3";
package neo.fs.v2.object; 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"; option csharp_namespace = "Neo.FileStorage.API.Object";
import "refs/types.proto"; import "refs/types.proto";
import "session/types.proto"; import "session/types.proto";
// Type of the object payload content. Only `REGULAR` type objects can be split, // Type of the object payload content. Only `REGULAR` type objects can be split,
// hence `TOMBSTONE` and `LOCK` payload is limited by the // hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum
// maximum object size. // object size.
// //
// String presentation of object type is the same as definition: // String presentation of object type is the same as definition:
// * REGULAR // * REGULAR
// * TOMBSTONE // * TOMBSTONE
// * STORAGE_GROUP
// * LOCK // * LOCK
enum ObjectType { enum ObjectType {
// Just a normal object // Just a normal object
@ -23,8 +24,8 @@ enum ObjectType {
// Used internally to identify deleted objects // Used internally to identify deleted objects
TOMBSTONE = 1; TOMBSTONE = 1;
// Unused (previously storageGroup information) // StorageGroup information
// _ = 2; STORAGE_GROUP = 2;
// Object lock // Object lock
LOCK = 3; LOCK = 3;
@ -71,8 +72,7 @@ message ShortHeader {
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 // Homomorphic hash of the object payload
neo.fs.v2.refs.Checksum homomorphic_hash = 7 neo.fs.v2.refs.Checksum homomorphic_hash = 7 [json_name = "homomorphicHash"];
[ json_name = "homomorphicHash" ];
} }
// Object Header // Object Header
@ -101,13 +101,11 @@ message Header {
ObjectType object_type = 7 [json_name = "objectType"]; ObjectType object_type = 7 [json_name = "objectType"];
// Homomorphic hash of the object payload // Homomorphic hash of the object payload
neo.fs.v2.refs.Checksum homomorphic_hash = 8 neo.fs.v2.refs.Checksum homomorphic_hash = 8 [json_name = "homomorphicHash"];
[ json_name = "homomorphicHash" ];
// Session token, if it was used during Object creation. Need it to verify // Session token, if it was used during Object creation. Need it to verify
// integrity and authenticity out of Request scope. // integrity and authenticity out of Request scope.
neo.fs.v2.session.SessionToken session_token = 9 neo.fs.v2.session.SessionToken session_token = 9 [json_name = "sessionToken"];
[ json_name = "sessionToken" ];
// `Attribute` is a user-defined Key-Value metadata pair attached to an // `Attribute` is a user-defined Key-Value metadata pair attached to an
// object. // object.
@ -116,24 +114,19 @@ message Header {
// Objects with duplicated attribute names or attributes with empty values // Objects with duplicated attribute names or attributes with empty values
// will be considered invalid. // will be considered invalid.
// //
// There are some "well-known" attributes starting with `__SYSTEM__` // There are some "well-known" attributes starting with `__NEOFS__` prefix
// (`__NEOFS__` is deprecated) prefix that affect system behaviour: // that affect system behaviour:
// //
// * [ __SYSTEM__UPLOAD_ID ] \ // * __NEOFS__UPLOAD_ID \
// (`__NEOFS__UPLOAD_ID` is deprecated) \
// Marks smaller parts of a split bigger object // Marks smaller parts of a split bigger object
// * [ __SYSTEM__EXPIRATION_EPOCH ] \ // * __NEOFS__EXPIRATION_EPOCH \
// (`__NEOFS__EXPIRATION_EPOCH` is deprecated) \ // Tells GC to delete object after that epoch
// The epoch after which object with no LOCKs on it becomes unavailable. // * __NEOFS__TICK_EPOCH \
// Locked object continues to be available until each of the LOCKs expire.
// * [ __SYSTEM__TICK_EPOCH ] \
// (`__NEOFS__TICK_EPOCH` is deprecated) \
// Decimal number that defines what epoch must produce // Decimal number that defines what epoch must produce
// object notification with UTF-8 object address in a // object notification with UTF-8 object address in a
// body (`0` value produces notification right after // body (`0` value produces notification right after
// object put) // object put)
// * [ __SYSTEM__TICK_TOPIC ] \ // * __NEOFS__TICK_TOPIC \
// (`__NEOFS__TICK_TOPIC` is deprecated) \
// UTF-8 string topic ID that is used for object notification // UTF-8 string topic ID that is used for object notification
// //
// And some well-known attributes used by applications only: // And some well-known attributes used by applications only:
@ -155,7 +148,7 @@ message Header {
// MIME Content Type of object's payload // MIME Content Type of object's payload
// //
// For detailed description of each well-known attribute please see the // 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 { message Attribute {
// string key to the object attribute // string key to the object attribute
string key = 1 [json_name = "key"]; string key = 1 [json_name = "key"];
@ -177,8 +170,7 @@ message Header {
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. // `signature` field of the parent object. Used to reconstruct parent.
neo.fs.v2.refs.Signature parent_signature = 3 neo.fs.v2.refs.Signature parent_signature = 3 [json_name = "parentSignature"];
[ json_name = "parentSignature" ];
// `header` field of the parent object. Used to reconstruct parent. // `header` field of the parent object. Used to reconstruct parent.
Header parent_header = 4 [json_name = "parentHeader"]; Header parent_header = 4 [json_name = "parentHeader"];
@ -190,44 +182,15 @@ message Header {
// unique inside container. All objects participating in the split must have // unique inside container. All objects participating in the split must have
// the same `split_id` value. // 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 // Position of the object in the split hierarchy
Split split = 11 [json_name = "split"]; 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" ];
} }
// Object structure. Object is immutable and content-addressed. It means // Object structure. Object is immutable and content-addressed. It means
// `ObjectID` will change if the header or the payload changes. It's calculated // `ObjectID` will change if the header or the payload changes. It's calculated as a
// as a hash of header field which contains hash of the object's payload. // hash of header field which contains hash of the object's payload.
// //
// For non-regular object types payload format depends on object type specified // For non-regular object types payload format depends on object type specified
// in the header. // in the header.
@ -247,8 +210,8 @@ message Object {
// Meta information of split hierarchy for object assembly. With the last part // 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 // 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 // assemble the original object. With a linking object one can assemble an object
// object right from the object parts. // right from the object parts.
message SplitInfo { message SplitInfo {
// 16 byte UUID used to identify the split object hierarchy parts. // 16 byte UUID used to identify the split object hierarchy parts.
bytes split_id = 1; bytes split_id = 1;
@ -262,17 +225,3 @@ message SplitInfo {
// object parts. // object parts.
neo.fs.v2.refs.ObjectID link = 3; 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;
}

24
proto-docs/accounting.md
View file

@ -35,11 +35,11 @@
<a name="neo.fs.v2.accounting.AccountingService"></a> <a name="neo.fs.v2.accounting.AccountingService"></a>
### Service "neo.fs.v2.accounting.AccountingService" ### Service "neo.fs.v2.accounting.AccountingService"
Accounting service provides methods for interaction with FrostFS sidechain Accounting service provides methods for interaction with NeoFS sidechain via
via other FrostFS nodes to get information about the account balance. Deposit other NeoFS nodes to get information about the account balance. Deposit and
and Withdraw operations can't be implemented here, as they require Mainnet Withdraw operations can't be implemented here, as they require Mainnet NeoFS
FrostFS smart contract invocation. Transfer operations between internal smart contract invocation. Transfer operations between internal NeoFS
FrostFS accounts are possible if both use the same token type. accounts are possible if both use the same token type.
``` ```
rpc Balance(BalanceRequest) returns (BalanceResponse); rpc Balance(BalanceRequest) returns (BalanceResponse);
@ -48,7 +48,7 @@ rpc Balance(BalanceRequest) returns (BalanceResponse);
#### Method Balance #### 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: Statuses:
- **OK** (0, SECTION_SUCCESS): - **OK** (0, SECTION_SUCCESS):
@ -78,9 +78,9 @@ BalanceRequest message
### Message BalanceRequest.Body ### Message BalanceRequest.Body
To indicate the account for which the balance is requested, its identifier To indicate the account for which the balance is requested, its identifier
is used. It can be any existing account in FrostFS sidechain `Balance` is used. It can be any existing account in NeoFS sidechain `Balance` smart
smart contract. If omitted, client implementation MUST set it to the contract. If omitted, client implementation MUST set it to the request's
request's signer `OwnerID`. signer `OwnerID`.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -105,8 +105,7 @@ BalanceResponse message
### Message BalanceResponse.Body ### Message BalanceResponse.Body
The amount of funds in GAS token for the `OwnerID`'s account requested. 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 Balance is given in the `Decimal` format to avoid precision issues with rounding.
rounding.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -131,7 +130,7 @@ rounding.
<a name="neo.fs.v2.accounting.Decimal"></a> <a name="neo.fs.v2.accounting.Decimal"></a>
### Message Decimal ### 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 of the result when doing lots of small number operations. To solve the lost
precision issue, special `Decimal` format is used for monetary computations. precision issue, special `Decimal` format is used for monetary computations.
@ -170,3 +169,4 @@ description.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

40
proto-docs/acl.md
View file

@ -8,7 +8,6 @@
- Messages - Messages
- [BearerToken](#neo.fs.v2.acl.BearerToken) - [BearerToken](#neo.fs.v2.acl.BearerToken)
- [BearerToken.Body](#neo.fs.v2.acl.BearerToken.Body) - [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) - [BearerToken.Body.TokenLifetime](#neo.fs.v2.acl.BearerToken.Body.TokenLifetime)
- [EACLRecord](#neo.fs.v2.acl.EACLRecord) - [EACLRecord](#neo.fs.v2.acl.EACLRecord)
- [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter) - [EACLRecord.Filter](#neo.fs.v2.acl.EACLRecord.Filter)
@ -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 used in the similar use cases, like providing authorisation to externally
authenticated party. authenticated party.
BearerToken can be issued only by the container's owner and must be signed BearerToken can be issued only by the container's owner and must be signed using
using the key associated with the container's `OwnerID`. the key associated with the container's `OwnerID`.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -52,37 +51,15 @@ using the key associated with the container's `OwnerID`.
<a name="neo.fs.v2.acl.BearerToken.Body"></a> <a name="neo.fs.v2.acl.BearerToken.Body"></a>
### Message BearerToken.Body ### Message BearerToken.Body
Bearer Token body structure contains Extended ACL table issued by the Bearer Token body structure contains Extended ACL table issued by the container
container owner with additional information preventing token abuse. owner with additional information preventing token abuse.
| Field | Type | Label | Description | | 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. | 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. |
| 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. | | 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 | | 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. |
<a name="neo.fs.v2.acl.BearerToken.Body.APEOverride"></a>
### 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. |
<a name="neo.fs.v2.acl.BearerToken.Body.TokenLifetime"></a> <a name="neo.fs.v2.acl.BearerToken.Body.TokenLifetime"></a>
@ -107,7 +84,7 @@ Describes a single eACL rule.
| Field | Type | Label | Description | | 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. | | 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 | | 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 | | 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 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 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 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 | | Field | Type | Label | Description |
@ -211,7 +188,7 @@ Enumeration of possible sources of Headers to apply filters.
| HEADER_UNSPECIFIED | 0 | Unspecified header, default value. | | HEADER_UNSPECIFIED | 0 | Unspecified header, default value. |
| REQUEST | 1 | Filter request headers | | REQUEST | 1 | Filter request headers |
| OBJECT | 2 | Filter object 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.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

269
proto-docs/apemanager.md
View file

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

74
proto-docs/audit.md Normal file
View file

@ -0,0 +1,74 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [audit/types.proto](#audit/types.proto)
- Messages
- [DataAuditResult](#neo.fs.v2.audit.DataAuditResult)
- [Scalar Value Types](#scalar-value-types)
<a name="audit/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## audit/types.proto
<!-- end services -->
<a name="neo.fs.v2.audit.DataAuditResult"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

89
proto-docs/bootstrap.md Normal file
View file

@ -0,0 +1,89 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [bootstrap/types.proto](#bootstrap/types.proto)
- Messages
- [NodeInfo](#bootstrap.NodeInfo)
- [NodeInfo.Attribute](#bootstrap.NodeInfo.Attribute)
- [Scalar Value Types](#scalar-value-types)
<a name="bootstrap/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## bootstrap/types.proto
<!-- end services -->
<a name="bootstrap.NodeInfo"></a>
### 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. |
<a name="bootstrap.NodeInfo.Attribute"></a>
### 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. |
<!-- end messages -->
<a name="bootstrap.NodeInfo.State"></a>
### 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. |
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

289
proto-docs/container.md
View file

@ -8,10 +8,19 @@
- [ContainerService](#neo.fs.v2.container.ContainerService) - [ContainerService](#neo.fs.v2.container.ContainerService)
- Messages - Messages
- [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](#neo.fs.v2.container.DeleteRequest)
- [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body) - [DeleteRequest.Body](#neo.fs.v2.container.DeleteRequest.Body)
- [DeleteResponse](#neo.fs.v2.container.DeleteResponse) - [DeleteResponse](#neo.fs.v2.container.DeleteResponse)
- [DeleteResponse.Body](#neo.fs.v2.container.DeleteResponse.Body) - [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](#neo.fs.v2.container.GetRequest)
- [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body) - [GetRequest.Body](#neo.fs.v2.container.GetRequest.Body)
- [GetResponse](#neo.fs.v2.container.GetResponse) - [GetResponse](#neo.fs.v2.container.GetResponse)
@ -24,6 +33,10 @@
- [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body) - [PutRequest.Body](#neo.fs.v2.container.PutRequest.Body)
- [PutResponse](#neo.fs.v2.container.PutResponse) - [PutResponse](#neo.fs.v2.container.PutResponse)
- [PutResponse.Body](#neo.fs.v2.container.PutResponse.Body) - [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) - [container/types.proto](#container/types.proto)
@ -49,8 +62,8 @@
### Service "neo.fs.v2.container.ContainerService" ### Service "neo.fs.v2.container.ContainerService"
`ContainerService` provides API to interact with `Container` smart contract `ContainerService` provides API to interact with `Container` smart contract
in FrostFS sidechain via other FrostFS nodes. All of those actions can be in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
done equivalently by directly issuing transactions and RPC calls to sidechain equivalently by directly issuing transactions and RPC calls to sidechain
nodes. nodes.
``` ```
@ -58,6 +71,9 @@ rpc Put(PutRequest) returns (PutResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse); rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Get(GetRequest) returns (GetResponse); rpc Get(GetRequest) returns (GetResponse);
rpc List(ListRequest) returns (ListResponse); rpc List(ListRequest) returns (ListResponse);
rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
rpc GetExtendedACL(GetExtendedACLRequest) returns (GetExtendedACLResponse);
rpc AnnounceUsedSpace(AnnounceUsedSpaceRequest) returns (AnnounceUsedSpaceResponse);
``` ```
@ -65,15 +81,13 @@ rpc List(ListRequest) returns (ListResponse);
`Put` invokes `Container` smart contract's `Put` method and returns `Put` invokes `Container` smart contract's `Put` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, the verified by Inner Ring nodes. After one more block in sidechain, the container
container is added into smart contract storage. is added into smart contract storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
request to save the container has been sent to the sidechain; request to save the container has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON).
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container create access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -82,15 +96,13 @@ Statuses:
`Delete` invokes `Container` smart contract's `Delete` method and returns `Delete` invokes `Container` smart contract's `Delete` method and returns
response immediately. After a new block is issued in sidechain, request is response immediately. After a new block is issued in sidechain, request is
verified by Inner Ring nodes. After one more block in sidechain, the verified by Inner Ring nodes. After one more block in sidechain, the container
container is added into smart contract storage. is added into smart contract storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
request to remove the container has been sent to the sidechain; request to remove the container has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON).
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container delete access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -104,9 +116,7 @@ Statuses:
container has been successfully read; container has been successfully read;
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON);
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
requested container not found; requested container not found.
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
@ -118,16 +128,115 @@ Returns all owner's containers from 'Container` smart contract' storage.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): \ - **OK** (0, SECTION_SUCCESS): \
container list has been successfully read; container list has been successfully read;
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON).
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
container list access denied.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
| List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) | | List | [ListRequest](#neo.fs.v2.container.ListRequest) | [ListResponse](#neo.fs.v2.container.ListResponse) |
#### Method SetExtendedACL
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): \
request to save container eACL has been sent to the sidechain;
- Common failures (SECTION_FAILURE_COMMON).
| Name | Input | Output |
| ---- | ----- | ------ |
| 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) |
<!-- end services --> <!-- end services -->
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest"></a>
### 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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body"></a>
### 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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceRequest.Body.Announcement"></a>
### 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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceResponse"></a>
### 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. |
<a name="neo.fs.v2.container.AnnounceUsedSpaceResponse.Body"></a>
### Message AnnounceUsedSpaceResponse.Body
`AnnounceUsedSpaceResponse` has an empty body because announcements are
one way communication.
<a name="neo.fs.v2.container.DeleteRequest"></a> <a name="neo.fs.v2.container.DeleteRequest"></a>
### Message DeleteRequest ### Message DeleteRequest
@ -151,7 +260,7 @@ smart contract, so signing algorithm must be supported by NeoVM.
| Field | Type | Label | Description | | 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. | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | `ContainerID` signed with the container owner's key according to RFC-6979. |
@ -177,6 +286,58 @@ and done via consensus in Inner Ring nodes.
<a name="neo.fs.v2.container.GetExtendedACLRequest"></a>
### 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. |
<a name="neo.fs.v2.container.GetExtendedACLRequest.Body"></a>
### 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 |
<a name="neo.fs.v2.container.GetExtendedACLResponse"></a>
### 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. |
<a name="neo.fs.v2.container.GetExtendedACLResponse.Body"></a>
### 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 |
<a name="neo.fs.v2.container.GetRequest"></a> <a name="neo.fs.v2.container.GetRequest"></a>
### Message GetRequest ### Message GetRequest
@ -279,7 +440,7 @@ List containers response body.
<a name="neo.fs.v2.container.PutRequest"></a> <a name="neo.fs.v2.container.PutRequest"></a>
### Message PutRequest ### Message PutRequest
New FrostFS Container creation request New NeoFS Container creation request
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -301,14 +462,14 @@ additional signature checks.
| Field | Type | Label | Description | | 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. | | signature | [neo.fs.v2.refs.SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) | | Signature of a stable-marshalled container according to RFC-6979. |
<a name="neo.fs.v2.container.PutResponse"></a> <a name="neo.fs.v2.container.PutResponse"></a>
### Message PutResponse ### Message PutResponse
New FrostFS Container creation response New NeoFS Container creation response
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -331,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 | | container_id | [neo.fs.v2.refs.ContainerID](#neo.fs.v2.refs.ContainerID) | | Unique identifier of the newly created container |
<a name="neo.fs.v2.container.SetExtendedACLRequest"></a>
### 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. |
<a name="neo.fs.v2.container.SetExtendedACLRequest.Body"></a>
### 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. |
<a name="neo.fs.v2.container.SetExtendedACLResponse"></a>
### 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. |
<a name="neo.fs.v2.container.SetExtendedACLResponse.Body"></a>
### 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.
<!-- end messages --> <!-- end messages -->
<!-- end enums --> <!-- end enums -->
@ -351,8 +560,8 @@ returned here to make sure everything has been done as expected.
### Message Container ### Message Container
Container is a structure that defines object placement behaviour. Objects can Container is a structure that defines object placement behaviour. Objects can
be stored only within containers. They define placement rule, attributes and 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 access control information. An ID of a container is a 32 byte long SHA256 hash
hash of stable-marshalled container message. of stable-marshalled container message.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -369,8 +578,8 @@ hash of stable-marshalled container message.
### Message Container.Attribute ### Message Container.Attribute
`Attribute` is a user-defined Key-Value metadata pair attached to the `Attribute` is a user-defined Key-Value metadata pair attached to the
container. Container attributes are immutable. They are set at the moment container. Container attributes are immutable. They are set at the moment of
of container creation and can never be added or updated. container creation and can never be added or updated.
Key name must be a container-unique valid UTF-8 string. Value can't be 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 empty. Containers with duplicated attribute names or attributes with empty
@ -378,22 +587,21 @@ values will be considered invalid.
There are some "well-known" attributes affecting system behaviour: There are some "well-known" attributes affecting system behaviour:
* [ __SYSTEM__NAME ] \ * __NEOFS__SUBNET \
(`__NEOFS__NAME` is deprecated) \ 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 String of a human-friendly container name registered as a domain in
NNS contract. NNS contract.
* [ __SYSTEM__ZONE ] \ * __NEOFS__ZONE \
(`__NEOFS__ZONE` is deprecated) \ String of a zone for `__NEOFS__NAME`. Used as a TLD of a domain name in NNS
String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated). contract. If no zone is specified, use default zone: `container`.
Used as a TLD of a domain name in NNS contract. If no zone is specified, * __NEOFS__DISABLE_HOMOMORPHIC_HASHING \
use default zone: `container`. Disables homomorphic hashing for the container if the value equals "true" string.
* [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \ Any other values are interpreted as missing attribute. Container could be
(`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \ accepted in a NeoFS network only if the global network hashing configuration
Disables homomorphic hashing for the container if the value equals "true" value corresponds with that attribute's value. After container inclusion, network
string. Any other values are interpreted as missing attribute. Container setting is ignored.
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.
And some well-known attributes used by applications only: And some well-known attributes used by applications only:
@ -433,3 +641,4 @@ And some well-known attributes used by applications only:
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

6
proto-docs/lock.md
View file

@ -27,9 +27,8 @@
### Message Lock ### Message Lock
Lock objects protects a list of objects from being deleted. The lifetime of a Lock objects protects a list of objects from being deleted. The lifetime of a
lock object is limited similar to regular objects in lock object is limited similar to regular objects in
`__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated) `__NEOFS__EXPIRATION_EPOCH` attribute. Lock object MUST have expiration epoch.
attribute. Lock object MUST have expiration epoch. It is impossible to delete It is impossible to delete a lock object via ObjectService.Delete RPC call.
a lock object via ObjectService.Delete RPC call.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -61,3 +60,4 @@ a lock object via ObjectService.Delete RPC call.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

135
proto-docs/netmap.md
View file

@ -52,10 +52,10 @@
<a name="neo.fs.v2.netmap.NetmapService"></a> <a name="neo.fs.v2.netmap.NetmapService"></a>
### Service "neo.fs.v2.netmap.NetmapService" ### Service "neo.fs.v2.netmap.NetmapService"
`NetmapService` provides methods to work with `Network Map` and the `NetmapService` provides methods to work with `Network Map` and the information
information required to build it. The resulting `Network Map` is stored in required to build it. The resulting `Network Map` is stored in sidechain
sidechain `Netmap` smart contract, while related information can be obtained `Netmap` smart contract, while related information can be obtained from other
from other FrostFS nodes. NeoFS nodes.
``` ```
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse); rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
@ -67,11 +67,10 @@ rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse);
#### Method LocalNodeInfo #### Method LocalNodeInfo
Get NodeInfo structure from the particular node directly. Get NodeInfo structure from the particular node directly.
Node information can be taken from `Netmap` smart contract. In some cases, Node information can be taken from `Netmap` smart contract. In some cases, though,
though, one may want to get recent information directly or to talk to the one may want to get recent information directly or to talk to the node not yet
node not yet present in the `Network Map` to find out what API version can present in the `Network Map` to find out what API version can be used for
be used for further communication. This can be also used to check if a node further communication. This can be also used to check if a node is up and running.
is up and running.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **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) | | LocalNodeInfo | [LocalNodeInfoRequest](#neo.fs.v2.netmap.LocalNodeInfoRequest) | [LocalNodeInfoResponse](#neo.fs.v2.netmap.LocalNodeInfoResponse) |
#### Method NetworkInfo #### Method NetworkInfo
Read recent information about the FrostFS network. Read recent information about the NeoFS network.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **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) | | NetworkInfo | [NetworkInfoRequest](#neo.fs.v2.netmap.NetworkInfoRequest) | [NetworkInfoResponse](#neo.fs.v2.netmap.NetworkInfoResponse) |
#### Method NetmapSnapshot #### Method NetmapSnapshot
Returns network map snapshot of the current FrostFS epoch. Returns network map snapshot of the current NeoFS epoch.
Statuses: Statuses:
- **OK** (0, SECTION_SUCCESS): - **OK** (0, SECTION_SUCCESS):
@ -149,7 +148,7 @@ Local Node Info, including API Version in use.
| Field | Type | Label | Description | | 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 | | node_info | [NodeInfo](#neo.fs.v2.netmap.NodeInfo) | | NodeInfo structure with recent information from node itself |
@ -259,8 +258,8 @@ Information about the network.
<a name="neo.fs.v2.netmap.Filter"></a> <a name="neo.fs.v2.netmap.Filter"></a>
### Message Filter ### Message Filter
This filter will return the subset of nodes from `NetworkMap` or another This filter will return the subset of nodes from `NetworkMap` or another filter's
filter's results that will satisfy filter's conditions. results that will satisfy filter's conditions.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -287,7 +286,7 @@ Network map structure
<a name="neo.fs.v2.netmap.NetworkConfig"></a> <a name="neo.fs.v2.netmap.NetworkConfig"></a>
### Message NetworkConfig ### Message NetworkConfig
FrostFS network configuration NeoFS network configuration
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -314,8 +313,15 @@ System parameters:
- **ContainerFee** \ - **ContainerFee** \
Fee paid for container creation by the container owner. Fee paid for container creation by the container owner.
Value: little-endian integer. Default: 0. 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** \ - **EpochDuration** \
FrostFS epoch duration measured in Sidechain blocks. NeoFS epoch duration measured in Sidechain blocks.
Value: little-endian integer. Default: 0. Value: little-endian integer. Default: 0.
- **HomomorphicHashingDisabled** \ - **HomomorphicHashingDisabled** \
Flag of disabling the homomorphic hashing of objects' payload. Flag of disabling the homomorphic hashing of objects' payload.
@ -327,48 +333,11 @@ System parameters:
Flag allowing setting the MAINTENANCE state to storage nodes. Flag allowing setting the MAINTENANCE state to storage nodes.
Value: true if any byte != 0. Default: false. Value: true if any byte != 0. Default: false.
- **MaxObjectSize** \ - **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. 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** \ - **WithdrawFee** \
Fee paid for withdrawal of funds paid by the account owner. Fee paid for withdrawal of funds paid by the account owner.
Value: little-endian integer. Default: 0. 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 | | Field | Type | Label | Description |
@ -380,49 +349,49 @@ System parameters:
<a name="neo.fs.v2.netmap.NetworkInfo"></a> <a name="neo.fs.v2.netmap.NetworkInfo"></a>
### Message NetworkInfo ### Message NetworkInfo
Information about FrostFS network Information about NeoFS network
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| current_epoch | [uint64](#uint64) | | Number of the current epoch in the FrostFS network | | current_epoch | [uint64](#uint64) | | Number of the current epoch in the NeoFS network |
| magic_number | [uint64](#uint64) | | Magic number of the sidechain of the FrostFS 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 FrostFS network | | ms_per_block | [int64](#int64) | | MillisecondsPerBlock network parameter of the sidechain of the NeoFS network |
| network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | FrostFS network configuration | | network_config | [NetworkConfig](#neo.fs.v2.netmap.NetworkConfig) | | NeoFS network configuration |
<a name="neo.fs.v2.netmap.NodeInfo"></a> <a name="neo.fs.v2.netmap.NodeInfo"></a>
### Message NodeInfo ### Message NodeInfo
FrostFS node description NeoFS node description
| Field | Type | Label | 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 | | 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. | | 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 FrostFS node | | state | [NodeInfo.State](#neo.fs.v2.netmap.NodeInfo.State) | | Carries state of the NeoFS node |
<a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a> <a name="neo.fs.v2.netmap.NodeInfo.Attribute"></a>
### Message NodeInfo.Attribute ### 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 `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8
string. Value can't be empty. string. Value can't be empty.
Attributes can be constructed into a chain of attributes: any attribute can 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 have a parent attribute and a child attribute (except the first and the last
last one). A string representation of the chain of attributes in FrostFS one). A string representation of the chain of attributes in NeoFS Storage
Storage Node configuration uses ":" and "/" symbols, e.g.: 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 Therefore the string attribute representation in the Node configuration must
must use "\:", "\/" and "\\" escaped symbols if any of them appears in an use "\:", "\/" and "\\" escaped symbols if any of them appears in an attribute's
attribute's key or value. key or value.
Node's attributes are mostly used during Storage Policy evaluation to Node's attributes are mostly used during Storage Policy evaluation to
calculate object's placement and find a set of nodes satisfying policy 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 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 point delimiter for decimal part. In the Network Map it will be saved as
64-bit unsigned integer representing number of minimal token fractions. 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 \ * UN-LOCODE \
Node's geographic location in Node's geographic location in
[UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html) [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 [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated
automatically from `UN-LOCODE` attribute. automatically from `UN-LOCODE` attribute.
* Continent \ * Continent \
Node's continent name according to the [Seven-Continent Node's continent name according to the [Seven-Continent model]
model](https://en.wikipedia.org/wiki/Continent#Number). Calculated (https://en.wikipedia.org/wiki/Continent#Number). Calculated
automatically from `UN-LOCODE` attribute. automatically from `UN-LOCODE` attribute.
* ExternalAddr * ExternalAddr
Node's preferred way for communications with external clients. Node's preferred way for communications with external clients.
@ -474,7 +450,7 @@ explicitly set:
Must contain a comma-separated list of multi-addresses. Must contain a comma-separated list of multi-addresses.
For detailed description of each well-known attribute please see the 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 | | Field | Type | Label | Description |
@ -495,10 +471,10 @@ storage policy definition languages.
| Field | Type | Label | Description | | 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 | | 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 | | 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 | | 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. |
<a name="neo.fs.v2.netmap.Replica"></a> <a name="neo.fs.v2.netmap.Replica"></a>
@ -513,8 +489,6 @@ default.
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| count | [uint32](#uint32) | | How many object replicas to put | | count | [uint32](#uint32) | | How many object replicas to put |
| selector | [string](#string) | | Named selector bucket to put replicas | | 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 |
<a name="neo.fs.v2.netmap.Selector"></a> <a name="neo.fs.v2.netmap.Selector"></a>
@ -553,7 +527,7 @@ hash distance.
<a name="neo.fs.v2.netmap.NodeInfo.State"></a> <a name="neo.fs.v2.netmap.NodeInfo.State"></a>
### NodeInfo.State ### 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 | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
@ -580,8 +554,6 @@ Operations on filters
| LE | 6 | Less or equal | | LE | 6 | Less or equal |
| OR | 7 | Logical OR | | OR | 7 | Logical OR |
| AND | 8 | Logical AND | | AND | 8 | Logical AND |
| NOT | 9 | Logical negation |
| LIKE | 10 | Matches pattern |
<!-- end enums --> <!-- end enums -->
@ -607,3 +579,4 @@ Operations on filters
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

409
proto-docs/object.md
View file

@ -30,20 +30,11 @@
- [HeadResponse](#neo.fs.v2.object.HeadResponse) - [HeadResponse](#neo.fs.v2.object.HeadResponse)
- [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body) - [HeadResponse.Body](#neo.fs.v2.object.HeadResponse.Body)
- [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) - [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](#neo.fs.v2.object.PutRequest)
- [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body) - [PutRequest.Body](#neo.fs.v2.object.PutRequest.Body)
- [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init) - [PutRequest.Body.Init](#neo.fs.v2.object.PutRequest.Body.Init)
- [PutResponse](#neo.fs.v2.object.PutResponse) - [PutResponse](#neo.fs.v2.object.PutResponse)
- [PutResponse.Body](#neo.fs.v2.object.PutResponse.Body) - [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) - [Range](#neo.fs.v2.object.Range)
- [SearchRequest](#neo.fs.v2.object.SearchRequest) - [SearchRequest](#neo.fs.v2.object.SearchRequest)
- [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body) - [SearchRequest.Body](#neo.fs.v2.object.SearchRequest.Body)
@ -55,11 +46,8 @@
- [object/types.proto](#object/types.proto) - [object/types.proto](#object/types.proto)
- Messages - Messages
- [ECInfo](#neo.fs.v2.object.ECInfo)
- [ECInfo.Chunk](#neo.fs.v2.object.ECInfo.Chunk)
- [Header](#neo.fs.v2.object.Header) - [Header](#neo.fs.v2.object.Header)
- [Header.Attribute](#neo.fs.v2.object.Header.Attribute) - [Header.Attribute](#neo.fs.v2.object.Header.Attribute)
- [Header.EC](#neo.fs.v2.object.Header.EC)
- [Header.Split](#neo.fs.v2.object.Header.Split) - [Header.Split](#neo.fs.v2.object.Header.Split)
- [Object](#neo.fs.v2.object.Object) - [Object](#neo.fs.v2.object.Object)
- [ShortHeader](#neo.fs.v2.object.ShortHeader) - [ShortHeader](#neo.fs.v2.object.ShortHeader)
@ -92,31 +80,26 @@ rpc Head(HeadRequest) returns (HeadResponse);
rpc Search(SearchRequest) returns (stream SearchResponse); rpc Search(SearchRequest) returns (stream SearchResponse);
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse); rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse); rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
rpc Patch(stream PatchRequest) returns (PatchResponse);
``` ```
#### Method Get #### Method Get
Receive full object structure, including Headers and payload. Response uses Receive full object structure, including Headers and payload. Response uses
gRPC stream. First response message carries the object with the requested gRPC stream. First response message carries the object with the requested address.
address. Chunk messages are parts of the object's payload if it is needed. Chunk messages are parts of the object's payload if it is needed. All
All messages, except the first one, carry payload chunks. The requested messages, except the first one, carry payload chunks. The requested object can
object can be restored by concatenation of object message payload and all be restored by concatenation of object message payload and all chunks
chunks keeping the receiving order. keeping the receiving order.
Extended headers can change `Get` behaviour: Extended headers can change `Get` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
Will use the requsted version of Network Map for object placement Will use the requsted version of Network Map for object placement
calculation. calculation.
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ * __NEOFS__NETMAP_LOOKUP_DEPTH \
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \ Will try older versions (starting from `__NEOFS__NETMAP_EPOCH` if specified or
Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH` the latest one otherwise) of Network Map to find an object until the depth
(`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one limit is reached.
otherwise) of Network Map to find an object until the depth limit is
reached.
Please refer to detailed `XHeader` description. Please refer to detailed `XHeader` description.
@ -132,8 +115,6 @@ Statuses:
the requested object has been marked as deleted; the requested object has been marked as deleted;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. 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. Chunk messages SHOULD be sent in the direct order of fragmentation.
Extended headers can change `Put` behaviour: Extended headers can change `Put` behaviour:
* [ __SYSTEM__NETMAP_EPOCH \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
Will use the requsted version of Network Map for object placement Will use the requsted version of Network Map for object placement
calculation. calculation.
@ -164,18 +144,15 @@ Statuses:
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
write access to the container is denied; write access to the container is denied;
- **LOCKED** (2050, SECTION_OBJECT): \ - **LOCKED** (2050, SECTION_OBJECT): \
placement of an object of type TOMBSTONE that includes at least one placement of an object of type TOMBSTONE that includes at least one locked
locked object is prohibited; object is prohibited;
- **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \ - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
placement of an object of type LOCK that includes at least one object of placement of an object of type LOCK that includes at least one object of
type other than REGULAR is prohibited; type other than REGULAR is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object storage container not found; object storage container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \ - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
(for trusted object preparation) session private key does not exist or (for trusted object preparation) session private key does not exist or has
has
been deleted; been deleted;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. 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. guarantee. Object will be marked for removal and deleted eventually.
Extended headers can change `Delete` behaviour: Extended headers can change `Delete` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ Will use the requsted version of Network Map for object placement
Will use the requested version of Network Map for object placement
calculation. calculation.
Please refer to detailed `XHeader` description. Please refer to detailed `XHeader` description.
@ -202,15 +178,10 @@ Statuses:
- Common failures (SECTION_FAILURE_COMMON); - Common failures (SECTION_FAILURE_COMMON);
- **ACCESS_DENIED** (2048, SECTION_OBJECT): \ - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
delete access to the object is denied; 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): \ - **LOCKED** (2050, SECTION_OBJECT): \
deleting a locked object is prohibited; deleting a locked object is prohibited;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -224,9 +195,8 @@ returned. If `main_only` request field is set, the short header with only
the very minimal information will be returned instead. the very minimal information will be returned instead.
Extended headers can change `Head` behaviour: Extended headers can change `Head` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ Will use the requsted version of Network Map for object placement
Will use the requested version of Network Map for object placement
calculation. calculation.
Please refer to detailed `XHeader` description. Please refer to detailed `XHeader` description.
@ -243,8 +213,6 @@ Statuses:
the requested object has been marked as deleted; the requested object has been marked as deleted;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -254,13 +222,12 @@ Statuses:
#### Method Search #### Method Search
Search objects in container. Search query allows to match by Object 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. Specification section for more details.
Extended headers can change `Search` behaviour: Extended headers can change `Search` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ Will use the requsted version of Network Map for object placement
Will use the requested version of Network Map for object placement
calculation. calculation.
Please refer to detailed `XHeader` description. Please refer to detailed `XHeader` description.
@ -273,8 +240,6 @@ Statuses:
access to operation SEARCH of the object is denied; access to operation SEARCH of the object is denied;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
search container not found; search container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -285,16 +250,14 @@ Statuses:
Get byte range of data payload. Range is set as an (offset, length) tuple. 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 Like in `Get` method, the response uses gRPC stream. Requested range can be
restored by concatenation of all received payload chunks keeping the restored by concatenation of all received payload chunks keeping the receiving
receiving order. order.
Extended headers can change `GetRange` behaviour: Extended headers can change `GetRange` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ Will use the requsted version of Network Map for object placement
Will use the requested version of Network Map for object placement
calculation. calculation.
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ * __NEOFS__NETMAP_LOOKUP_DEPTH \
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
Will try older versions of Network Map to find an object until the depth Will try older versions of Network Map to find an object until the depth
limit is reached. limit is reached.
@ -314,8 +277,6 @@ Statuses:
the requested range is out of bounds; the requested range is out of bounds;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
@ -330,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. the request. Note that hash is calculated for XORed data.
Extended headers can change `GetRangeHash` behaviour: Extended headers can change `GetRangeHash` behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \ Will use the requsted version of Network Map for object placement
Will use the requested version of Network Map for object placement
calculation. calculation.
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ * __NEOFS__NETMAP_LOOKUP_DEPTH \
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
Will try older versions of Network Map to find an object until the depth Will try older versions of Network Map to find an object until the depth
limit is reached. limit is reached.
@ -353,107 +312,12 @@ Statuses:
the requested range is out of bounds; the requested range is out of bounds;
- **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \ - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
object container not found; object container not found;
- **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
access to container is denied;
- **TOKEN_EXPIRED** (4097, SECTION_SESSION): \ - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
provided session token has expired. provided session token has expired.
| Name | Input | Output | | Name | Input | Output |
| ---- | ----- | ------ | | ---- | ----- | ------ |
| GetRangeHash | [GetRangeHashRequest](#neo.fs.v2.object.GetRangeHashRequest) | [GetRangeHashResponse](#neo.fs.v2.object.GetRangeHashResponse) | | 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) |
<!-- end services --> <!-- end services -->
@ -610,7 +474,6 @@ chunks.
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| chunk | [bytes](#bytes) | | Chunked object payload's range. | | chunk | [bytes](#bytes) | | Chunked object payload's range. |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | | 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. |
<a name="neo.fs.v2.object.GetRequest"></a> <a name="neo.fs.v2.object.GetRequest"></a>
@ -662,7 +525,6 @@ GET Object Response body
| init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream | | init | [GetResponse.Body.Init](#neo.fs.v2.object.GetResponse.Body.Init) | | Initial part of the object stream |
| chunk | [bytes](#bytes) | | Chunked object payload | | chunk | [bytes](#bytes) | | Chunked object payload |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy for object assembly. | | 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. |
<a name="neo.fs.v2.object.GetResponse.Body.Init"></a> <a name="neo.fs.v2.object.GetResponse.Body.Init"></a>
@ -729,7 +591,6 @@ Object HEAD response body
| header | [HeaderWithSignature](#neo.fs.v2.object.HeaderWithSignature) | | Full object's `Header` with `ObjectID` signature | | 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 | | short_header | [ShortHeader](#neo.fs.v2.object.ShortHeader) | | Short object header |
| split_info | [SplitInfo](#neo.fs.v2.object.SplitInfo) | | Meta information of split hierarchy. | | 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. |
<a name="neo.fs.v2.object.HeaderWithSignature"></a> <a name="neo.fs.v2.object.HeaderWithSignature"></a>
@ -750,71 +611,6 @@ following steps:
| signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` to verify full header's authenticity | | signature | [neo.fs.v2.refs.Signature](#neo.fs.v2.refs.Signature) | | Signed `ObjectID` to verify full header's authenticity |
<a name="neo.fs.v2.object.PatchRequest"></a>
### 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. |
<a name="neo.fs.v2.object.PatchRequest.Body"></a>
### 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. |
<a name="neo.fs.v2.object.PatchRequest.Body.Patch"></a>
### 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. |
<a name="neo.fs.v2.object.PatchResponse"></a>
### 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. |
<a name="neo.fs.v2.object.PatchResponse.Body"></a>
### 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. |
<a name="neo.fs.v2.object.PutRequest"></a> <a name="neo.fs.v2.object.PutRequest"></a>
### Message PutRequest ### Message PutRequest
@ -852,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. | | 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 | | 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 | | 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. |
<a name="neo.fs.v2.object.PutResponse"></a> <a name="neo.fs.v2.object.PutResponse"></a>
@ -879,51 +675,6 @@ PUT Object response body
| object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object | | object_id | [neo.fs.v2.refs.ObjectID](#neo.fs.v2.refs.ObjectID) | | Identifier of the saved object |
<a name="neo.fs.v2.object.PutSingleRequest"></a>
### 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. |
<a name="neo.fs.v2.object.PutSingleRequest.Body"></a>
### 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. |
<a name="neo.fs.v2.object.PutSingleResponse"></a>
### 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. |
<a name="neo.fs.v2.object.PutSingleResponse.Body"></a>
### Message PutSingleResponse.Body
PUT Single Object response body
<a name="neo.fs.v2.object.Range"></a> <a name="neo.fs.v2.object.Range"></a>
### Message Range ### Message Range
@ -965,11 +716,11 @@ Object Search request body
<a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a> <a name="neo.fs.v2.object.SearchRequest.Body.Filter"></a>
### Message SearchRequest.Body.Filter ### Message SearchRequest.Body.Filter
Filter structure checks if the object header field or the attribute Filter structure checks if the object header field or the attribute content
content matches a value. matches a value.
If no filters are set, search request will return all objects of the 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 objects. Most human users expect to get only object they can directly
work with. In that case, `$Object:ROOT` filter should be used. work with. In that case, `$Object:ROOT` filter should be used.
@ -999,19 +750,16 @@ prefix to the name. Here is the list of fields available via this prefix:
object_id of parent object_id of parent
* $Object:split.splitID \ * $Object:split.splitID \
16 byte UUIDv4 used to identify the split object hierarchy parts 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 There are some well-known filter aliases to match objects by certain
properties: properties:
* $Object:ROOT \ * $Object:ROOT \
Returns only `REGULAR` type objects that are not split or that are the Returns only `REGULAR` type objects that are not split or that are the top
top level root objects in a split hierarchy. This includes objects not level root objects in a split hierarchy. This includes objects not
present physically, like large objects split into smaller objects present physically, like large objects split into smaller objects
without a separate top-level root object. Objects of other types like 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 useful for listing objects like `ls` command of some virtual file
system. This filter is activated if the `key` exists, disregarding the system. This filter is activated if the `key` exists, disregarding the
value and matcher type. value and matcher type.
@ -1020,8 +768,8 @@ properties:
activated if the `key` exists, disregarding the value and matcher type. activated if the `key` exists, disregarding the value and matcher type.
Note: using filters with a key with prefix `$Object:` and match 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 `NOT_PRESENT `is not recommended since this is not a cross-version approach.
approach. Behavior when processing this kind of filters is undefined. Behavior when processing this kind of filters is undefined.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -1069,30 +817,6 @@ Object Search response body
<!-- end services --> <!-- end services -->
<a name="neo.fs.v2.object.ECInfo"></a>
### 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. |
<a name="neo.fs.v2.object.ECInfo.Chunk"></a>
### 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. |
<a name="neo.fs.v2.object.Header"></a> <a name="neo.fs.v2.object.Header"></a>
### Message Header ### Message Header
@ -1112,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. | | 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 | | 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 | | 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. |
<a name="neo.fs.v2.object.Header.Attribute"></a> <a name="neo.fs.v2.object.Header.Attribute"></a>
@ -1125,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 Objects with duplicated attribute names or attributes with empty values
will be considered invalid. will be considered invalid.
There are some "well-known" attributes starting with `__SYSTEM__` There are some "well-known" attributes starting with `__NEOFS__` prefix
(`__NEOFS__` is deprecated) prefix that affect system behaviour: that affect system behaviour:
* [ __SYSTEM__UPLOAD_ID ] \ * __NEOFS__UPLOAD_ID \
(`__NEOFS__UPLOAD_ID` is deprecated) \
Marks smaller parts of a split bigger object Marks smaller parts of a split bigger object
* [ __SYSTEM__EXPIRATION_EPOCH ] \ * __NEOFS__EXPIRATION_EPOCH \
(`__NEOFS__EXPIRATION_EPOCH` is deprecated) \ Tells GC to delete object after that epoch
The epoch after which object with no LOCKs on it becomes unavailable. * __NEOFS__TICK_EPOCH \
Locked object continues to be available until each of the LOCKs expire.
* [ __SYSTEM__TICK_EPOCH ] \
(`__NEOFS__TICK_EPOCH` is deprecated) \
Decimal number that defines what epoch must produce Decimal number that defines what epoch must produce
object notification with UTF-8 object address in a object notification with UTF-8 object address in a
body (`0` value produces notification right after body (`0` value produces notification right after
object put) object put)
* [ __SYSTEM__TICK_TOPIC ] \ * __NEOFS__TICK_TOPIC \
(`__NEOFS__TICK_TOPIC` is deprecated) \
UTF-8 string topic ID that is used for object notification UTF-8 string topic ID that is used for object notification
And some well-known attributes used by applications only: And some well-known attributes used by applications only:
@ -1164,7 +882,7 @@ And some well-known attributes used by applications only:
MIME Content Type of object's payload MIME Content Type of object's payload
For detailed description of each well-known attribute please see the 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 | | Field | Type | Label | Description |
@ -1173,26 +891,6 @@ corresponding section in FrostFS Technical Specification.
| value | [string](#string) | | string value of the object attribute | | value | [string](#string) | | string value of the object attribute |
<a name="neo.fs.v2.object.Header.EC"></a>
### 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. |
<a name="neo.fs.v2.object.Header.Split"></a> <a name="neo.fs.v2.object.Header.Split"></a>
### Message Header.Split ### Message Header.Split
@ -1216,8 +914,8 @@ must be within the same container.
### Message Object ### Message Object
Object structure. Object is immutable and content-addressed. It means Object structure. Object is immutable and content-addressed. It means
`ObjectID` will change if the header or the payload changes. It's calculated `ObjectID` will change if the header or the payload changes. It's calculated as a
as a hash of header field which contains hash of the object's payload. hash of header field which contains hash of the object's payload.
For non-regular object types payload format depends on object type specified For non-regular object types payload format depends on object type specified
in the header. in the header.
@ -1253,8 +951,8 @@ Short header fields
### Message SplitInfo ### Message SplitInfo
Meta information of split hierarchy for object assembly. With the last part 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 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 assemble the original object. With a linking object one can assemble an object
object right from the object parts. right from the object parts.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -1285,18 +983,20 @@ Type of match expression
### ObjectType ### ObjectType
Type of the object payload content. Only `REGULAR` type objects can be split, Type of the object payload content. Only `REGULAR` type objects can be split,
hence `TOMBSTONE` and `LOCK` payload is limited by the hence `TOMBSTONE`, `STORAGE_GROUP` and `LOCK` payload is limited by the maximum
maximum object size. object size.
String presentation of object type is the same as definition: String presentation of object type is the same as definition:
* REGULAR * REGULAR
* TOMBSTONE * TOMBSTONE
* STORAGE_GROUP
* LOCK * LOCK
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| REGULAR | 0 | Just a normal object | | REGULAR | 0 | Just a normal object |
| TOMBSTONE | 1 | Used internally to identify deleted objects | | TOMBSTONE | 1 | Used internally to identify deleted objects |
| STORAGE_GROUP | 2 | StorageGroup information |
| LOCK | 3 | Object lock | | LOCK | 3 | Object lock |
@ -1323,3 +1023,4 @@ String presentation of object type is the same as definition:
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

38
proto-docs/refs.md
View file

@ -13,6 +13,7 @@
- [OwnerID](#neo.fs.v2.refs.OwnerID) - [OwnerID](#neo.fs.v2.refs.OwnerID)
- [Signature](#neo.fs.v2.refs.Signature) - [Signature](#neo.fs.v2.refs.Signature)
- [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979) - [SignatureRFC6979](#neo.fs.v2.refs.SignatureRFC6979)
- [SubnetID](#neo.fs.v2.refs.SubnetID)
- [Version](#neo.fs.v2.refs.Version) - [Version](#neo.fs.v2.refs.Version)
@ -32,7 +33,7 @@
<a name="neo.fs.v2.refs.Address"></a> <a name="neo.fs.v2.refs.Address"></a>
### Message Address ### 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 String presentation of `Address` is a concatenation of string encoded
`ContainerID` and `ObjectID` delimited by '/' character. `ContainerID` and `ObjectID` delimited by '/' character.
@ -65,7 +66,7 @@ Depending on checksum algorithm type, the string presentation may vary:
<a name="neo.fs.v2.refs.ContainerID"></a> <a name="neo.fs.v2.refs.ContainerID"></a>
### Message ContainerID ### Message ContainerID
FrostFS container identifier. Container structures are immutable and NeoFS container identifier. Container structures are immutable and
content-addressed. content-addressed.
`ContainerID` is a 32 byte long `ContainerID` is a 32 byte long
@ -90,14 +91,13 @@ with/without paddings are accepted.
<a name="neo.fs.v2.refs.ObjectID"></a> <a name="neo.fs.v2.refs.ObjectID"></a>
### Message ObjectID ### Message ObjectID
FrostFS Object unique identifier. Objects are immutable and NeoFS Object unique identifier. Objects are immutable and content-addressed.
content-addressed. It means `ObjectID` will change if the `header` or the It means `ObjectID` will change if the `header` or the `payload` changes.
`payload` changes.
`ObjectID` is a 32 byte long `ObjectID` is a 32 byte long
[SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of [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 the object's `header` field, which, in it's turn, contains the hash of the object's
object's payload. payload.
String presentation is a String presentation is a
[base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
@ -142,7 +142,7 @@ with/without paddings are accepted.
<a name="neo.fs.v2.refs.Signature"></a> <a name="neo.fs.v2.refs.Signature"></a>
### Message Signature ### Message Signature
Signature of something in FrostFS. Signature of something in NeoFS.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -164,14 +164,28 @@ RFC 6979 signature.
| sign | [bytes](#bytes) | | Deterministic ECDSA with SHA-256 hashing | | sign | [bytes](#bytes) | | Deterministic ECDSA with SHA-256 hashing |
<a name="neo.fs.v2.refs.SubnetID"></a>
### 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. |
<a name="neo.fs.v2.refs.Version"></a> <a name="neo.fs.v2.refs.Version"></a>
### Message Version ### Message Version
API version used by a node. API version used by a node.
String presentation is a Semantic Versioning 2.0.0 compatible version string 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 with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number.
number.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -198,8 +212,7 @@ Checksum algorithm type.
<a name="neo.fs.v2.refs.SignatureScheme"></a> <a name="neo.fs.v2.refs.SignatureScheme"></a>
### SignatureScheme ### SignatureScheme
Signature scheme describes digital signing scheme used for (key, signature) Signature scheme describes digital signing scheme used for (key, signature) pair.
pair.
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
@ -231,3 +244,4 @@ pair.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

289
proto-docs/reputation.md Normal file
View file

@ -0,0 +1,289 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="reputation/service.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## reputation/service.proto
<a name="neo.fs.v2.reputation.ReputationService"></a>
### 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) |
<!-- end services -->
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultRequest"></a>
### 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. |
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultRequest.Body"></a>
### 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 |
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse"></a>
### 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. |
<a name="neo.fs.v2.reputation.AnnounceIntermediateResultResponse.Body"></a>
### 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.
<a name="neo.fs.v2.reputation.AnnounceLocalTrustRequest"></a>
### 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. |
<a name="neo.fs.v2.reputation.AnnounceLocalTrustRequest.Body"></a>
### 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. |
<a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse"></a>
### 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. |
<a name="neo.fs.v2.reputation.AnnounceLocalTrustResponse.Body"></a>
### 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.
<!-- end messages -->
<!-- end enums -->
<a name="reputation/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## reputation/types.proto
<!-- end services -->
<a name="neo.fs.v2.reputation.GlobalTrust"></a>
### 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. |
<a name="neo.fs.v2.reputation.GlobalTrust.Body"></a>
### 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 |
<a name="neo.fs.v2.reputation.PeerID"></a>
### 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 |
<a name="neo.fs.v2.reputation.PeerToPeerTrust"></a>
### 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 |
<a name="neo.fs.v2.reputation.Trust"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

125
proto-docs/service.md Normal file
View file

@ -0,0 +1,125 @@
# Protocol Documentation
<a name="top"></a>
## 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)
<a name="service/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## service/types.proto
<!-- end services -->
<a name="neo.fs.v2.service.RequestMetaHeader"></a>
### 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. |
<a name="neo.fs.v2.service.RequestVerificationHeader"></a>
### 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 |
<a name="neo.fs.v2.service.ResponseMetaHeader"></a>
### 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. |
<a name="neo.fs.v2.service.ResponseVerificationHeader"></a>
### 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 |
<a name="neo.fs.v2.service.XHeader"></a>
### 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. |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

36
proto-docs/session.md
View file

@ -48,7 +48,7 @@
`SessionService` allows to establish a temporary trust relationship between `SessionService` allows to establish a temporary trust relationship between
two peer nodes and generate a `SessionToken` as the proof of trust to be two peer nodes and generate a `SessionToken` as the proof of trust to be
attached in requests for further verification. Please see corresponding 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); rpc Create(CreateRequest) returns (CreateResponse);
@ -168,7 +168,7 @@ Carries objects involved in the object session.
| Field | Type | Label | Description | | 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. | | 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. |
<a name="neo.fs.v2.session.RequestMetaHeader"></a> <a name="neo.fs.v2.session.RequestMetaHeader"></a>
@ -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 | | 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 | | 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 | | 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. |
<a name="neo.fs.v2.session.RequestVerificationHeader"></a> <a name="neo.fs.v2.session.RequestVerificationHeader"></a>
@ -237,12 +237,12 @@ Verification info for the response signed by all intermediate nodes
<a name="neo.fs.v2.session.SessionToken"></a> <a name="neo.fs.v2.session.SessionToken"></a>
### Message SessionToken ### Message SessionToken
FrostFS Session Token. NeoFS Session Token.
| Field | Type | Label | Description | | 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 | | 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.
<a name="neo.fs.v2.session.XHeader"></a> <a name="neo.fs.v2.session.XHeader"></a>
### Message XHeader ### Message XHeader
Extended headers for Request/Response. They may contain any user-defined Extended headers for Request/Response. They may contain any user-defined headers
headers to be interpreted on application level. to be interpreted on application level.
Key name must be a unique valid UTF-8 string. Value can't be empty. Requests Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
or Responses with duplicated header names or headers with empty values will Responses with duplicated header names or headers with empty values will be
be considered invalid. considered invalid.
There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__` There are some "well-known" headers starting with `__NEOFS__` prefix that
is deprecated) prefix that affect system behaviour: affect system behaviour:
* [ __SYSTEM__NETMAP_EPOCH ] \ * __NEOFS__NETMAP_EPOCH \
(`__NEOFS__NETMAP_EPOCH` is deprecated) \
Netmap epoch to use for object placement calculation. The `value` is string 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 encoded `uint64` in decimal presentation. If set to '0' or not set, the
current epoch only will be used. current epoch only will be used.
* [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ * __NEOFS__NETMAP_LOOKUP_DEPTH \
(`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
If object can't be found using current epoch's netmap, this header limits 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 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 encoded `uint64` in decimal presentation. If set to '0' or not set, only the
the current epoch will be used. current epoch will be used.
| Field | Type | Label | Description | | Field | Type | Label | Description |
@ -338,7 +336,6 @@ Object request verbs
| DELETE | 5 | Refers to object.Delete RPC call | | DELETE | 5 | Refers to object.Delete RPC call |
| RANGE | 6 | Refers to object.GetRange RPC call | | RANGE | 6 | Refers to object.GetRange RPC call |
| RANGEHASH | 7 | Refers to object.GetRangeHash RPC call | | RANGEHASH | 7 | Refers to object.GetRangeHash RPC call |
| PATCH | 8 | Refers to object.Patch RPC call |
<!-- end enums --> <!-- end enums -->
@ -364,3 +361,4 @@ Object request verbs
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

27
proto-docs/status.md
View file

@ -26,12 +26,12 @@
<a name="neo.fs.v2.status.Status"></a> <a name="neo.fs.v2.status.Status"></a>
### Message Status ### Message Status
Declares the general format of the status returns of the FrostFS RPC Declares the general format of the status returns of the NeoFS RPC protocol.
protocol. Status is present in all response messages. Each RPC of FrostFS Status is present in all response messages. Each RPC of NeoFS protocol
protocol describes the possible outcomes and details of the operation. describes the possible outcomes and details of the operation.
Each status is assigned a one-to-one numeric code. Any unique result of an 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 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: is defined for each section. Values can be referred to in the following ways:
@ -79,17 +79,6 @@ covered by the code.
<!-- end messages --> <!-- end messages -->
<a name="neo.fs.v2.status.APEManager"></a>
### 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. |
<a name="neo.fs.v2.status.CommonFail"></a> <a name="neo.fs.v2.status.CommonFail"></a>
### CommonFail ### CommonFail
@ -98,10 +87,9 @@ Section of failed statuses independent of the operation.
| Name | Number | Description | | 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. | | 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. | | SIGNATURE_VERIFICATION_FAIL | 2 | [**1026**] Signature verification failure. |
| NODE_UNDER_MAINTENANCE | 3 | [**1027**] Node is under maintenance. | | 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. |
@ -114,7 +102,6 @@ Section of statuses for container-related operations.
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
| CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. | | CONTAINER_NOT_FOUND | 0 | [**3072**] Container not found. |
| EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. | | EACL_NOT_FOUND | 1 | [**3073**] eACL table not found. |
| CONTAINER_ACCESS_DENIED | 2 | [**3074**] Container access denied. |
@ -146,7 +133,6 @@ Section identifiers.
| SECTION_OBJECT | 2 | Object service-specific errors. | | SECTION_OBJECT | 2 | Object service-specific errors. |
| SECTION_CONTAINER | 3 | Container service-specific errors. | | SECTION_CONTAINER | 3 | Container service-specific errors. |
| SECTION_SESSION | 4 | Session service-specific errors. | | SECTION_SESSION | 4 | Session service-specific errors. |
| SECTION_APE_MANAGER | 5 | Session service-specific errors. |
@ -165,7 +151,7 @@ Section of statuses for session-related operations.
<a name="neo.fs.v2.status.Success"></a> <a name="neo.fs.v2.status.Success"></a>
### Success ### Success
Section of FrostFS successful return codes. Section of NeoFS successful return codes.
| Name | Number | Description | | Name | Number | Description |
| ---- | ------ | ----------- | | ---- | ------ | ----------- |
@ -195,3 +181,4 @@ Section of FrostFS successful return codes.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

71
proto-docs/storagegroup.md Normal file
View file

@ -0,0 +1,71 @@
# Protocol Documentation
<a name="top"></a>
## Table of Contents
- [storagegroup/types.proto](#storagegroup/types.proto)
- Messages
- [StorageGroup](#neo.fs.v2.storagegroup.StorageGroup)
- [Scalar Value Types](#scalar-value-types)
<a name="storagegroup/types.proto"></a>
<p align="right"><a href="#top">Top</a></p>
## storagegroup/types.proto
<!-- end services -->
<a name="neo.fs.v2.storagegroup.StorageGroup"></a>
### 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 |
<!-- end messages -->
<!-- end enums -->
## Scalar Value Types
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| ----------- | ----- | -------- | --------- | ----------- |
| <a name="double" /> double | | double | double | float |
| <a name="float" /> float | | float | float | float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long |
| <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

46
proto-docs/ape.md → proto-docs/subnet.md
View file

@ -3,65 +3,38 @@
## Table of Contents ## Table of Contents
- [ape/types.proto](#ape/types.proto) - [subnet/types.proto](#subnet/types.proto)
- Messages - Messages
- [Chain](#frostfs.v2.ape.Chain) - [SubnetInfo](#neo.fs.v2.subnet.SubnetInfo)
- [ChainTarget](#frostfs.v2.ape.ChainTarget)
- [Scalar Value Types](#scalar-value-types) - [Scalar Value Types](#scalar-value-types)
<a name="ape/types.proto"></a> <a name="subnet/types.proto"></a>
<p align="right"><a href="#top">Top</a></p> <p align="right"><a href="#top">Top</a></p>
## ape/types.proto ## subnet/types.proto
<!-- end services --> <!-- end services -->
<a name="frostfs.v2.ape.Chain"></a> <a name="neo.fs.v2.subnet.SubnetInfo"></a>
### Message Chain ### Message SubnetInfo
Chain is a chain of rules defined for a specific target. NeoFS subnetwork description
| Field | Type | Label | Description | | Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- | | ----- | ---- | ----- | ----------- |
| raw | [bytes](#bytes) | | Raw representation of a serizalized rule chain. | | 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 |
<a name="frostfs.v2.ape.ChainTarget"></a>
### 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) | | |
<!-- end messages --> <!-- end messages -->
<a name="frostfs.v2.ape.TargetType"></a>
### TargetType
TargetType is a type target to which a rule chain is defined.
| Name | Number | Description |
| ---- | ------ | ----------- |
| UNDEFINED | 0 | |
| NAMESPACE | 1 | |
| CONTAINER | 2 | |
| USER | 3 | |
| GROUP | 4 | |
<!-- end enums --> <!-- end enums -->
@ -85,3 +58,4 @@ TargetType is a type target to which a rule chain is defined.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

5
proto-docs/tombstone.md
View file

@ -26,12 +26,12 @@
### Message Tombstone ### Message Tombstone
Tombstone keeps record of deleted objects for a few epochs until they are 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 | | 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. | | 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. | | 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.
| <a name="bool" /> bool | | bool | boolean | boolean | | <a name="bool" /> bool | | bool | boolean | boolean |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | | <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | | <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |

33
refs/types.proto
View file

@ -2,10 +2,10 @@ syntax = "proto3";
package neo.fs.v2.refs; 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"; 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 // String presentation of `Address` is a concatenation of string encoded
// `ContainerID` and `ObjectID` delimited by '/' character. // `ContainerID` and `ObjectID` delimited by '/' character.
@ -16,14 +16,13 @@ message Address {
ObjectID object_id = 2 [json_name = "objectID"]; ObjectID object_id = 2 [json_name = "objectID"];
} }
// FrostFS Object unique identifier. Objects are immutable and // NeoFS Object unique identifier. Objects are immutable and content-addressed.
// content-addressed. It means `ObjectID` will change if the `header` or the // It means `ObjectID` will change if the `header` or the `payload` changes.
// `payload` changes.
// //
// `ObjectID` is a 32 byte long // `ObjectID` is a 32 byte long
// [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of // [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 // the object's `header` field, which, in it's turn, contains the hash of the object's
// object's payload. // payload.
// //
// String presentation is a // String presentation is a
// [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string. // [base58](https://tools.ietf.org/html/draft-msporny-base58-02) encoded string.
@ -38,7 +37,7 @@ message ObjectID {
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. // content-addressed.
// //
// `ContainerID` is a 32 byte long // `ContainerID` is a 32 byte long
@ -78,11 +77,20 @@ message OwnerID {
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. // API version used by a node.
// //
// String presentation is a Semantic Versioning 2.0.0 compatible version string // 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 // with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor number.
// number.
message Version { message Version {
// Major API version // Major API version
uint32 major = 1 [json_name = "major"]; uint32 major = 1 [json_name = "major"];
@ -91,7 +99,7 @@ message 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 { message Signature {
// Public key used for signing // Public key used for signing
bytes key = 1 [json_name = "key"]; bytes key = 1 [json_name = "key"];
@ -101,8 +109,7 @@ message Signature {
SignatureScheme scheme = 3 [json_name = "scheme"]; SignatureScheme scheme = 3 [json_name = "scheme"];
} }
// Signature scheme describes digital signing scheme used for (key, signature) // Signature scheme describes digital signing scheme used for (key, signature) pair.
// pair.
enum SignatureScheme { enum SignatureScheme {
// ECDSA with SHA-512 hashing (FIPS 186-3) // ECDSA with SHA-512 hashing (FIPS 186-3)
ECDSA_SHA512 = 0; ECDSA_SHA512 = 0;

128
reputation/service.proto Normal file
View file

@ -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;
}

63
reputation/types.proto Normal file
View file

@ -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"];
}

4
session/service.proto
View file

@ -2,7 +2,7 @@ syntax = "proto3";
package neo.fs.v2.session; 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"; option csharp_namespace = "Neo.FileStorage.API.Session";
import "refs/types.proto"; import "refs/types.proto";
@ -11,7 +11,7 @@ import "session/types.proto";
// `SessionService` allows to establish a temporary trust relationship between // `SessionService` allows to establish a temporary trust relationship between
// two peer nodes and generate a `SessionToken` as the proof of trust to be // two peer nodes and generate a `SessionToken` as the proof of trust to be
// attached in requests for further verification. Please see corresponding // 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 { service SessionService {
// Open a new session between two peers. // Open a new session between two peers.
// //

43
session/types.proto
View file

@ -2,7 +2,7 @@ syntax = "proto3";
package neo.fs.v2.session; 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"; option csharp_namespace = "Neo.FileStorage.API.Session";
import "refs/types.proto"; import "refs/types.proto";
@ -36,9 +36,6 @@ message ObjectSessionContext {
// Refers to object.GetRangeHash RPC call // Refers to object.GetRangeHash RPC call
RANGEHASH = 7; RANGEHASH = 7;
// Refers to object.Patch RPC call
PATCH = 8;
} }
// Type of request for which the token is issued // Type of request for which the token is issued
Verb verb = 1 [json_name = "verb"]; Verb verb = 1 [json_name = "verb"];
@ -50,7 +47,7 @@ message ObjectSessionContext {
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 // 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. // Each element MUST have correct format.
repeated refs.ObjectID objects = 2 [json_name = "objects"]; repeated refs.ObjectID objects = 2 [json_name = "objects"];
} }
@ -88,7 +85,7 @@ message ContainerSessionContext {
refs.ContainerID container_id = 3 [json_name = "containerID"]; refs.ContainerID container_id = 3 [json_name = "containerID"];
} }
// FrostFS Session Token. // NeoFS Session Token.
message SessionToken { message SessionToken {
// Session Token body // Session Token body
message Body { message Body {
@ -126,34 +123,32 @@ message SessionToken {
} }
// Session Token contains the proof of trust between peers to be attached in // Session Token contains the proof of trust between peers to be attached in
// requests for further verification. Please see corresponding section of // requests for further verification. Please see corresponding section of
// FrostFS Technical Specification for details. // NeoFS Technical Specification for details.
Body body = 1 [json_name = "body"]; Body body = 1 [json_name = "body"];
// Signature of `SessionToken` information // 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 // Extended headers for Request/Response. They may contain any user-defined headers
// headers to be interpreted on application level. // to be interpreted on application level.
// //
// Key name must be a unique valid UTF-8 string. Value can't be empty. Requests // Key name must be a unique valid UTF-8 string. Value can't be empty. Requests or
// or Responses with duplicated header names or headers with empty values will // Responses with duplicated header names or headers with empty values will be
// be considered invalid. // considered invalid.
// //
// There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__` // There are some "well-known" headers starting with `__NEOFS__` prefix that
// is deprecated) prefix that affect system behaviour: // affect system behaviour:
// //
// * [ __SYSTEM__NETMAP_EPOCH ] \ // * __NEOFS__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Netmap epoch to use for object placement calculation. The `value` is string // 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 // encoded `uint64` in decimal presentation. If set to '0' or not set, the
// current epoch only will be used. // current epoch only will be used.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \ // * __NEOFS__NETMAP_LOOKUP_DEPTH \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// If object can't be found using current epoch's netmap, this header limits // 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 // 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 // encoded `uint64` in decimal presentation. If set to '0' or not set, only the
// the current epoch will be used. // current epoch will be used.
message XHeader { message XHeader {
// Key of the X-Header // Key of the X-Header
string key = 1 [json_name = "key"]; string key = 1 [json_name = "key"];
@ -186,7 +181,7 @@ message RequestMetaHeader {
// `RequestMetaHeader` of the origin request // `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. // that the server belongs to.
uint64 magic_number = 8 [json_name = "magicNumber"]; uint64 magic_number = 8 [json_name = "magicNumber"];
} }
@ -219,8 +214,7 @@ message RequestVerificationHeader {
// Request Meta signature is added and signed by each intermediate node // 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 // Signature of previous hops
neo.fs.v2.refs.Signature origin_signature = 3 neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"];
[ json_name = "originSignature" ];
// Chain of previous hops signatures // Chain of previous hops signatures
RequestVerificationHeader origin = 4 [json_name = "origin"]; RequestVerificationHeader origin = 4 [json_name = "origin"];
@ -233,8 +227,7 @@ message ResponseVerificationHeader {
// Response Meta signature is added and signed by each intermediate node // 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 // Signature of previous hops
neo.fs.v2.refs.Signature origin_signature = 3 neo.fs.v2.refs.Signature origin_signature = 3 [json_name = "originSignature"];
[ json_name = "originSignature" ];
// Chain of previous hops signatures // Chain of previous hops signatures
ResponseVerificationHeader origin = 4 [json_name = "origin"]; ResponseVerificationHeader origin = 4 [json_name = "origin"];

33
status/types.proto
View file

@ -2,15 +2,15 @@ syntax = "proto3";
package neo.fs.v2.status; 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"; option csharp_namespace = "Neo.FileStorage.API.Status";
// Declares the general format of the status returns of the FrostFS RPC // Declares the general format of the status returns of the NeoFS RPC protocol.
// protocol. Status is present in all response messages. Each RPC of FrostFS // Status is present in all response messages. Each RPC of NeoFS protocol
// protocol describes the possible outcomes and details of the operation. // describes the possible outcomes and details of the operation.
// //
// Each status is assigned a one-to-one numeric code. Any unique result of an // 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 // 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: // is defined for each section. Values can be referred to in the following ways:
@ -73,12 +73,9 @@ enum Section {
// Session service-specific errors. // Session service-specific errors.
SECTION_SESSION = 4; SECTION_SESSION = 4;
// Session service-specific errors.
SECTION_APE_MANAGER = 5;
} }
// Section of FrostFS successful return codes. // Section of NeoFS successful return codes.
enum Success { enum Success {
// [**0**] Default success. Not detailed. // [**0**] Default success. Not detailed.
// If the server cannot match successful outcome to the code, it should // If the server cannot match successful outcome to the code, it should
@ -93,9 +90,9 @@ enum CommonFail {
// use this code. // use this code.
INTERNAL = 0; INTERNAL = 0;
// [**1025**] Wrong magic of the FrostFS network. // [**1025**] Wrong magic of the NeoFS network.
// Details: // Details:
// - [**0**] Magic number of the served FrostFS network (big-endian 64-bit // - [**0**] Magic number of the served NeoFS network (big-endian 64-bit
// unsigned integer). // unsigned integer).
WRONG_MAGIC_NUMBER = 1; WRONG_MAGIC_NUMBER = 1;
@ -104,11 +101,6 @@ enum CommonFail {
// [**1027**] Node is under maintenance. // [**1027**] Node is under maintenance.
NODE_UNDER_MAINTENANCE = 3; 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;
} }
// Section of statuses for object-related operations. // Section of statuses for object-related operations.
@ -141,9 +133,6 @@ enum Container {
// [**3073**] eACL table not found. // [**3073**] eACL table not found.
EACL_NOT_FOUND = 1; EACL_NOT_FOUND = 1;
// [**3074**] Container access denied.
CONTAINER_ACCESS_DENIED = 2;
} }
// Section of statuses for session-related operations. // Section of statuses for session-related operations.
@ -154,9 +143,3 @@ enum Session {
// [**4097**] Token has expired. // [**4097**] Token has expired.
TOKEN_EXPIRED = 1; 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;
}

34
storagegroup/types.proto Normal file
View file

@ -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"];
}

18
subnet/types.proto Normal file
View file

@ -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;
}

11
tombstone/types.proto
View file

@ -2,18 +2,17 @@ syntax = "proto3";
package neo.fs.v2.tombstone; 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"; option csharp_namespace = "Neo.FileStorage.API.Tombstone";
import "refs/types.proto"; import "refs/types.proto";
// Tombstone keeps record of deleted objects for a few epochs until they are // 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 { message Tombstone {
// Last FrostFS epoch number of the tombstone lifetime. It's set by the // Last NeoFS epoch number of the tombstone lifetime. It's set by the tombstone
// tombstone creator depending on the current FrostFS network settings. A // creator depending on the current NeoFS network settings. A tombstone object
// tombstone object must have the same expiration epoch value in // must have the same expiration epoch value in `__NEOFS__EXPIRATION_EPOCH`
// `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated)
// attribute. Otherwise, the tombstone will be rejected by a storage node. // 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"];