TrueCloudLab/frostfs-sdk-java
19
1
Fork 3
Code Issues 8 Pull requests Releases Packages 6 Activity Actions

[#1] add client environment

Browse source 
add client cut
code cleanup
Signed-off-by: Ori Bruk <o.bruk@yadro.com>
This commit is contained in:
Ori Bruk 2024-07-22 19:13:52 +03:00
parent dc0eef770c
commit b0db7df192
95 changed files with 1202 additions and 560 deletions
Download patch file Download diff file Expand all files Collapse all files

106
protos/pom.xml Normal file
View file

@ -0,0 +1,106 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>info.FrostFS.sdk</groupId>
<artifactId>FrostFS-sdk-java</artifactId>
<version>0.1.0</version>
</parent>
<artifactId>protos</artifactId>
<properties>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
<protobuf.version>3.23.0</protobuf.version>
<grpc.version>1.65.1</grpc.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-netty</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-protobuf</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-stub</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-services</artifactId>
<version>${grpc.version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>javax.annotation</groupId>
<artifactId>javax.annotation-api</artifactId>
<version>1.3.2</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>${protobuf.version}</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-bom</artifactId>
<version>${grpc.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.6.2</version>
</extension>
</extensions>
<plugins>
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.6.1</version>
<configuration>
<!-- artifact to download binary protobuf compiler -->
<protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
<!-- make maven using GRPC plugin for compile-custom and
test-compile-custom goals -->
<pluginId>grpc-java</pluginId>
<!-- artifact to download GRPC protobuf compiler plugin -->
<pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
</configuration>
<executions>
<execution>
<goals>
<!-- compile .proto files located under main directory -->
<goal>compile</goal>
<goal>compile-custom</goal>
<!-- compile .proto files located under test directory -->
<goal>test-compile</goal>
<goal>test-compile-custom</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

71
protos/src/main/proto/accounting/service.proto Normal file
View file

@ -0,0 +1,71 @@
syntax = "proto3";
package neo.fs.v2.accounting;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting";
option java_package = "frostFS.accounting";
import "accounting/types.proto";
import "refs/types.proto";
import "session/types.proto";
// Accounting service provides methods for interaction with NeoFS sidechain via
// other NeoFS nodes to get information about the account balance. Deposit and
// Withdraw operations can't be implemented here, as they require Mainnet NeoFS
// smart contract invocation. Transfer operations between internal NeoFS
// accounts are possible if both use the same token type.
service AccountingService {
// Returns the amount of funds in GAS token for the requested NeoFS account.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS):
// balance has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON).
rpc Balance(BalanceRequest) returns (BalanceResponse);
}
// BalanceRequest message
message BalanceRequest {
// To indicate the account for which the balance is requested, its identifier
// is used. It can be any existing account in NeoFS sidechain `Balance` smart
// contract. If omitted, client implementation MUST set it to the request's
// signer `OwnerID`.
message Body {
// Valid user identifier in `OwnerID` format for which the balance is
// requested. Required field.
neo.fs.v2.refs.OwnerID owner_id = 1;
}
// Body of the balance 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;
}
// BalanceResponse message
message BalanceResponse {
// The amount of funds in GAS token for the `OwnerID`'s account requested.
// Balance is given in the `Decimal` format to avoid precision issues with
// rounding.
message Body {
// Amount of funds in GAS token for the requested account.
Decimal balance = 1;
}
// Body of the balance 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;
}

22
protos/src/main/proto/accounting/types.proto Normal file
View file

@ -0,0 +1,22 @@
syntax = "proto3";
package neo.fs.v2.accounting;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/accounting/grpc;accounting";
option java_package = "frostFS.accounting";
// Standard floating point data type can't be used in NeoFS due to inexactness
// of the result when doing lots of small number operations. To solve the lost
// precision issue, special `Decimal` format is used for monetary computations.
//
// Please see [The General Decimal Arithmetic
// Specification](http://speleotrove.com/decimal/) for detailed problem
// description.
message Decimal {
// Number in the smallest Token fractions.
int64 value = 1 [ json_name = "value" ];
// Precision value indicating how many smallest fractions can be in one
// integer.
uint32 precision = 2 [ json_name = "precision" ];
}

227
protos/src/main/proto/acl/types.proto Normal file
View file

@ -0,0 +1,227 @@
syntax = "proto3";
package neo.fs.v2.acl;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/acl/grpc;acl";
option java_package = "frostFS.acl";
import "refs/types.proto";
// Target role of the access control rule in access control list.
enum Role {
// Unspecified role, default value
ROLE_UNSPECIFIED = 0;
// User target rule is applied if sender is the owner of the container
USER = 1;
// System target rule is applied if sender is a storage node within the
// container or an inner ring node
SYSTEM = 2;
// Others target rule is applied if sender is neither a user nor a system
// target
OTHERS = 3;
}
// MatchType is an enumeration of match types.
enum MatchType {
// Unspecified match type, default value.
MATCH_TYPE_UNSPECIFIED = 0;
// Return true if strings are equal
STRING_EQUAL = 1;
// Return true if strings are different
STRING_NOT_EQUAL = 2;
}
// Request's operation type to match if the rule is applicable to a particular
// request.
enum Operation {
// Unspecified operation, default value
OPERATION_UNSPECIFIED = 0;
// Get
GET = 1;
// Head
HEAD = 2;
// Put
PUT = 3;
// Delete
DELETE = 4;
// Search
SEARCH = 5;
// GetRange
GETRANGE = 6;
// GetRangeHash
GETRANGEHASH = 7;
}
// Rule execution result action. Either allows or denies access if the rule's
// filters match.
enum Action {
// Unspecified action, default value
ACTION_UNSPECIFIED = 0;
// Allow action
ALLOW = 1;
// Deny action
DENY = 2;
}
// Enumeration of possible sources of Headers to apply filters.
enum HeaderType {
// Unspecified header, default value.
HEADER_UNSPECIFIED = 0;
// Filter request headers
REQUEST = 1;
// Filter object headers
OBJECT = 2;
// Filter service headers. These are not processed by NeoFS nodes and
// exist for service use only.
SERVICE = 3;
}
// Describes a single eACL rule.
message EACLRecord {
// NeoFS request Verb to match
Operation operation = 1 [ json_name = "operation" ];
// Rule execution result. Either allows or denies access if filters match.
Action action = 2 [ json_name = "action" ];
// Filter to check particular properties of the request or the object.
//
// By default `key` field refers to the corresponding object's `Attribute`.
// Some Object's header fields can also be accessed by adding `$Object:`
// prefix to the name. Here is the list of fields available via this prefix:
//
// * $Object:version \
// version
// * $Object:objectID \
// object_id
// * $Object:containerID \
// container_id
// * $Object:ownerID \
// owner_id
// * $Object:creationEpoch \
// creation_epoch
// * $Object:payloadLength \
// payload_length
// * $Object:payloadHash \
// payload_hash
// * $Object:objectType \
// object_type
// * $Object:homomorphicHash \
// homomorphic_hash
//
// Please note, that if request or response does not have object's headers of
// full object (Range, RangeHash, Search, Delete), it will not be possible to
// filter by object header fields or user attributes. From the well-known list
// only `$Object:objectID` and `$Object:containerID` will be available, as
// it's possible to take that information from the requested address.
message Filter {
// Define if Object or Request header will be used
HeaderType header_type = 1 [ json_name = "headerType" ];
// Match operation type
MatchType match_type = 2 [ json_name = "matchType" ];
// Name of the Header to use
string key = 3 [ json_name = "key" ];
// Expected Header Value or pattern to match
string value = 4 [ json_name = "value" ];
}
// List of filters to match and see if rule is applicable
repeated Filter filters = 3 [ json_name = "filters" ];
// Target to apply ACL rule. Can be a subject's role class or a list of public
// keys to match.
message Target {
// Target subject's role class
Role role = 1 [ json_name = "role" ];
// List of public keys to identify target subject
repeated bytes keys = 2 [ json_name = "keys" ];
}
// List of target subjects to apply ACL rule to
repeated Target targets = 4 [ json_name = "targets" ];
}
// Extended ACL rules table. A list of ACL rules defined additionally to Basic
// ACL. Extended ACL rules can be attached to a container and can be updated
// or may be defined in `BearerToken` structure. Please see the corresponding
// NeoFS Technical Specification section for detailed description.
message EACLTable {
// eACL format version. Effectively, the version of API library used to create
// eACL Table.
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Identifier of the container that should use given access control rules
neo.fs.v2.refs.ContainerID container_id = 2 [ json_name = "containerID" ];
// List of Extended ACL rules
repeated EACLRecord records = 3 [ json_name = "records" ];
}
// BearerToken allows to attach signed Extended ACL rules to the request in
// `RequestMetaHeader`. If container's Basic ACL rules allow, the attached rule
// set will be checked instead of one attached to the container itself. Just
// like [JWT](https://jwt.io), it has a limited lifetime and scope, hence can be
// used in the similar use cases, like providing authorisation to externally
// authenticated party.
//
// BearerToken can be issued only by the container's owner and must be signed
// using the key associated with the container's `OwnerID`.
message BearerToken {
// Bearer Token body structure contains Extended ACL table issued by the
// container owner with additional information preventing token abuse.
message Body {
// Table of Extended ACL rules to use instead of the ones attached to the
// container. If it contains `container_id` field, bearer token is only
// valid for this specific container. Otherwise, any container of the same
// owner is allowed.
EACLTable eacl_table = 1 [ json_name = "eaclTable" ];
// `OwnerID` defines to whom the token was issued. It must match the request
// originator's `OwnerID`. If empty, any token bearer will be accepted.
neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ];
// Lifetime parameters of the token. Field names taken from
// [rfc7519](https://tools.ietf.org/html/rfc7519).
message TokenLifetime {
// Expiration Epoch
uint64 exp = 1 [ json_name = "exp" ];
// Not valid before Epoch
uint64 nbf = 2 [ json_name = "nbf" ];
// Issued at Epoch
uint64 iat = 3 [ json_name = "iat" ];
}
// Token expiration and valid time period parameters
TokenLifetime lifetime = 3 [ json_name = "lifetime" ];
// AllowImpersonate flag to consider token signer as request owner.
// If this field is true extended ACL table in token body isn't processed.
bool allow_impersonate = 4 [ json_name = "allowImpersonate" ];
}
// Bearer Token body
Body body = 1 [ json_name = "body" ];
// Signature of BearerToken body
neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ];
}

172
protos/src/main/proto/apemanager/service.proto Normal file
View file

@ -0,0 +1,172 @@
syntax = "proto3";
package frostfs.v2.apemanager;
import "apemanager/types.proto";
import "session/types.proto";
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager";
option java_package = "frostFS.apemanager";
// `APEManagerService` provides API to manage rule chains within sidechain's
// `Policy` smart contract.
service APEManagerService {
// Add a rule chain for a specific target to `Policy` smart contract.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// the chain has been successfully added;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container (as target) not found;
// - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
// the operation is denied by the service.
rpc AddChain(AddChainRequest) returns (AddChainResponse);
// Remove a rule chain for a specific target from `Policy` smart contract.
// RemoveChain is an idempotent operation: removal of non-existing rule chain
// also means success.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// the chain has been successfully removed;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container (as target) not found;
// - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
// the operation is denied by the service.
rpc RemoveChain(RemoveChainRequest) returns (RemoveChainResponse);
// List chains defined for a specific target from `Policy` smart contract.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// chains have been successfully listed;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container (as target) not found;
// - **APE_MANAGER_ACCESS_DENIED** (5120, SECTION_APE_MANAGER): \
// the operation is denied by the service.
rpc ListChains(ListChainsRequest) returns (ListChainsResponse);
}
message AddChainRequest {
message Body {
// A target for which a rule chain is added.
ChainTarget target = 1;
// The chain to set for the target.
Chain chain = 2;
}
// The request's body.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
message AddChainResponse {
message Body {
// Chain ID assigned for the added rule chain.
// If chain ID is left empty in the request, then
// it will be generated.
bytes chain_id = 1;
}
// The response's body.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
message RemoveChainRequest {
message Body {
// Target for which a rule chain is removed.
ChainTarget target = 1;
// Chain ID assigned for the rule chain.
bytes chain_id = 2;
}
// The request's body.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
message RemoveChainResponse {
// Since RemoveChain is an idempotent operation, then the only indicator that
// operation could not be performed is an error returning to a client.
message Body {}
// The response's body.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
message ListChainsRequest {
message Body {
// Target for which rule chains are listed.
ChainTarget target = 1;
}
// The request's body.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
message ListChainsResponse {
message Body {
// The list of chains defined for the reqeusted target.
repeated Chain chains = 1;
}
// The response's body.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}

34
protos/src/main/proto/apemanager/types.proto Normal file
View file

@ -0,0 +1,34 @@
syntax = "proto3";
package frostfs.v2.apemanager;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/apemanager/grpc;apemanager";
option java_package = "frostFS.apemanager";
// TargetType is a type target to which a rule chain is defined.
enum TargetType {
UNDEFINED = 0;
NAMESPACE = 1;
CONTAINER = 2;
USER = 3;
GROUP = 4;
}
// ChainTarget is an object to which a rule chain is defined.
message ChainTarget {
TargetType type = 1;
string name = 2;
}
// Chain is a chain of rules defined for a specific target.
message Chain {
oneof kind {
// Raw representation of a serizalized rule chain.
bytes raw = 1;
}
}

431
protos/src/main/proto/container/service.proto Normal file
View file

@ -0,0 +1,431 @@
syntax = "proto3";
package neo.fs.v2.container;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container/grpc;container";
option java_package = "frostFS.container";
import "acl/types.proto";
import "container/types.proto";
import "refs/types.proto";
import "session/types.proto";
// `ContainerService` provides API to interact with `Container` smart contract
// in NeoFS sidechain via other NeoFS nodes. All of those actions can be done
// equivalently by directly issuing transactions and RPC calls to sidechain
// nodes.
service ContainerService {
// `Put` invokes `Container` smart contract's `Put` method and returns
// response immediately. After a new block is issued in sidechain, request is
// verified by Inner Ring nodes. After one more block in sidechain, the
// container is added into smart contract storage.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// request to save the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container create access denied.
rpc Put(PutRequest) returns (PutResponse);
// `Delete` invokes `Container` smart contract's `Delete` method and returns
// response immediately. After a new block is issued in sidechain, request is
// verified by Inner Ring nodes. After one more block in sidechain, the
// container is added into smart contract storage.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// request to remove the container has been sent to the sidechain;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container delete access denied.
rpc Delete(DeleteRequest) returns (DeleteResponse);
// Returns container structure from `Container` smart contract storage.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// container has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// requested container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied.
rpc Get(GetRequest) returns (GetResponse);
// Returns all owner's containers from 'Container` smart contract' storage.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// container list has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// container list access denied.
rpc List(ListRequest) returns (ListResponse);
// 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);
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// set container eACL access denied.
rpc SetExtendedACL(SetExtendedACLRequest) returns (SetExtendedACLResponse);
// Returns Extended ACL table and signature from `Container` smart contract
// storage.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// container eACL has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// container not found;
// - **EACL_NOT_FOUND** (3073, SECTION_CONTAINER): \
// eACL table not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container eACL is denied.
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 NeoFS Container creation request
message PutRequest {
// Container creation request has container structure's signature as a
// separate field. It's not stored in sidechain, just verified on container
// creation by `Container` smart contract. `ContainerID` is a SHA256 hash of
// the stable-marshalled container strucutre, hence there is no need for
// additional signature checks.
message Body {
// Container structure to register in NeoFS
container.Container container = 1;
// Signature of a stable-marshalled container according to RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2;
}
// Body of container put 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;
}
// New NeoFS Container creation response
message PutResponse {
// Container put response body contains information about the newly registered
// container as seen by `Container` smart contract. `ContainerID` can be
// calculated beforehand from the container structure and compared to the one
// returned here to make sure everything has been done as expected.
message Body {
// Unique identifier of the newly created container
neo.fs.v2.refs.ContainerID container_id = 1;
}
// Body of container put 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;
}
// Container removal request
message DeleteRequest {
// Container removal request body has signed `ContainerID` as a proof of
// the container owner's intent. The signature will be verified by `Container`
// smart contract, so signing algorithm must be supported by NeoVM.
message Body {
// Identifier of the container to delete from NeoFS
neo.fs.v2.refs.ContainerID container_id = 1;
// `ContainerID` signed with the container owner's key according to
// RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2;
}
// Body of container delete request message.
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;
}
// `DeleteResponse` has an empty body because delete operation is asynchronous
// and done via consensus in Inner Ring nodes.
message DeleteResponse {
// `DeleteResponse` has an empty body because delete operation is asynchronous
// and done via consensus in Inner Ring nodes.
message Body {}
// Body of container delete 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 container structure
message GetRequest {
// Get container structure request body.
message Body {
// Identifier of the container to get
neo.fs.v2.refs.ContainerID container_id = 1;
}
// Body of container get 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 container structure
message GetResponse {
// Get container response body does not have container structure signature. It
// has been already verified upon container creation.
message Body {
// Requested container structure
Container container = 1;
// Signature of a stable-marshalled container according to RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2;
// Session token if the container has been created within the session
neo.fs.v2.session.SessionToken session_token = 3;
}
// Body of container get 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;
}
// List containers
message ListRequest {
// List containers request body.
message Body {
// Identifier of the container owner
neo.fs.v2.refs.OwnerID owner_id = 1;
}
// Body of list containers 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;
}
// List containers
message ListResponse {
// List containers response body.
message Body {
// List of `ContainerID`s belonging to the requested `OwnerID`
repeated refs.ContainerID container_ids = 1;
}
// Body of list containers 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;
}
// Set Extended ACL
message SetExtendedACLRequest {
// Set Extended ACL request body does not have separate `ContainerID`
// reference. It will be taken from `EACLTable.container_id` field.
message Body {
// Extended ACL table to set for the container
neo.fs.v2.acl.EACLTable eacl = 1;
// Signature of stable-marshalled Extended ACL table according to RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2;
}
// Body of set 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;
}
// Set Extended ACL
message SetExtendedACLResponse {
// `SetExtendedACLResponse` has an empty body because the operation is
// asynchronous and the update should be reflected in `Container` smart
// contract's storage after next block is issued in sidechain.
message Body {}
// Body of set extended acl response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Get Extended ACL
message GetExtendedACLRequest {
// Get Extended ACL request body
message Body {
// Identifier of the container having Extended ACL
neo.fs.v2.refs.ContainerID container_id = 1;
}
// Body of get extended acl request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Get Extended ACL
message GetExtendedACLResponse {
// Get Extended ACL Response body can be empty if the requested container does
// not have Extended ACL Table attached or Extended ACL has not been allowed
// at the time of container creation.
message Body {
// Extended ACL requested, if available
neo.fs.v2.acl.EACLTable eacl = 1;
// Signature of stable-marshalled Extended ACL according to RFC-6979.
neo.fs.v2.refs.SignatureRFC6979 signature = 2;
// Session token if Extended ACL was set within a session
neo.fs.v2.session.SessionToken session_token = 3;
}
// Body of get extended acl response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Announce container used space
message AnnounceUsedSpaceRequest {
// Container used space announcement body.
message Body {
// Announcement contains used space information for a single container.
message Announcement {
// Epoch number for which the container size estimation was produced.
uint64 epoch = 1;
// Identifier of the container.
neo.fs.v2.refs.ContainerID container_id = 2;
// Used space is a sum of object payload sizes of a specified
// container, stored in the node. It must not include inhumed objects.
uint64 used_space = 3;
}
// List of announcements. If nodes share several containers,
// announcements are transferred in a batch.
repeated Announcement announcements = 1;
}
// Body of announce used space request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Announce container used space
message AnnounceUsedSpaceResponse {
// `AnnounceUsedSpaceResponse` has an empty body because announcements are
// one way communication.
message Body {}
// Body of announce used space response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// 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;
}

76
protos/src/main/proto/container/types.proto Normal file
View file

@ -0,0 +1,76 @@
syntax = "proto3";
package neo.fs.v2.container;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/container/grpc;container";
option java_package = "frostFS.container";
import "netmap/types.proto";
import "refs/types.proto";
// Container is a structure that defines object placement behaviour. Objects can
// be stored only within containers. They define placement rule, attributes and
// access control information. An ID of a container is a 32 byte long SHA256
// hash of stable-marshalled container message.
message Container {
// Container format version. Effectively, the version of API library used to
// create the container.
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Identifier of the container owner
neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ];
// Nonce is a 16 byte UUIDv4, used to avoid collisions of `ContainerID`s
bytes nonce = 3 [ json_name = "nonce" ];
// `BasicACL` contains access control rules for the owner, system and others
// groups, as well as permission bits for `BearerToken` and `Extended ACL`
uint32 basic_acl = 4 [ json_name = "basicACL" ];
// `Attribute` is a user-defined Key-Value metadata pair attached to the
// container. Container attributes are immutable. They are set at the moment
// of container creation and can never be added or updated.
//
// 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
// values will be considered invalid.
//
// There are some "well-known" attributes affecting system behaviour:
//
// * [ __SYSTEM__NAME ] \
// (`__NEOFS__NAME` is deprecated) \
// String of a human-friendly container name registered as a domain in
// NNS contract.
// * [ __SYSTEM__ZONE ] \
// (`__NEOFS__ZONE` is deprecated) \
// String of a zone for `__SYSTEM__NAME` (`__NEOFS__NAME` is deprecated).
// Used as a TLD of a domain name in NNS contract. If no zone is specified,
// use default zone: `container`.
// * [ __SYSTEM__DISABLE_HOMOMORPHIC_HASHING ] \
// (`__NEOFS__DISABLE_HOMOMORPHIC_HASHING` is deprecated) \
// Disables homomorphic hashing for the container if the value equals "true"
// string. Any other values are interpreted as missing attribute. Container
// could be accepted in a NeoFS network only if the global network hashing
// configuration value corresponds with that attribute's value. After
// container inclusion, network setting is ignored.
//
// And some well-known attributes used by applications only:
//
// * Name \
// Human-friendly name
// * Timestamp \
// User-defined local time of container creation in Unix Timestamp format
message Attribute {
// Attribute name key
string key = 1 [ json_name = "key" ];
// Attribute value
string value = 2 [ json_name = "value" ];
}
// Attributes represent immutable container's meta data
repeated Attribute attributes = 5 [ json_name = "attributes" ];
// Placement policy for the object inside the container
neo.fs.v2.netmap.PlacementPolicy placement_policy = 6
[ json_name = "placementPolicy" ];
}

19
protos/src/main/proto/lock/types.proto Normal file
View file

@ -0,0 +1,19 @@
syntax = "proto3";
package neo.fs.v2.lock;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/lock/grpc;lock";
option java_package = "frostFS.lock";
import "refs/types.proto";
// Lock objects protects a list of objects from being deleted. The lifetime of a
// lock object is limited similar to regular objects in
// `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated)
// attribute. Lock object MUST have expiration epoch. It is impossible to delete
// a lock object via ObjectService.Delete RPC call.
message Lock {
// List of objects to lock. Must not be empty or carry empty IDs.
// All members must be of the `REGULAR` type.
repeated neo.fs.v2.refs.ObjectID members = 1 [ json_name = "members" ];
}

162
protos/src/main/proto/netmap/service.proto Normal file
View file

@ -0,0 +1,162 @@
syntax = "proto3";
package neo.fs.v2.netmap;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap";
option java_package = "frostFS.netmap";
import "netmap/types.proto";
import "refs/types.proto";
import "session/types.proto";
// `NetmapService` provides methods to work with `Network Map` and the
// information required to build it. The resulting `Network Map` is stored in
// sidechain `Netmap` smart contract, while related information can be obtained
// from other NeoFS nodes.
service NetmapService {
// Get NodeInfo structure from the particular node directly.
// Node information can be taken from `Netmap` smart contract. In some cases,
// though, one may want to get recent information directly or to talk to the
// node not yet present in the `Network Map` to find out what API version can
// be used for further communication. This can be also used to check if a node
// is up and running.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS):
// information about the server has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON).
rpc LocalNodeInfo(LocalNodeInfoRequest) returns (LocalNodeInfoResponse);
// Read recent information about the NeoFS network.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS):
// information about the current network state has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON).
rpc NetworkInfo(NetworkInfoRequest) returns (NetworkInfoResponse);
// Returns network map snapshot of the current NeoFS epoch.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS):
// information about the current network map has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON).
rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse);
}
// Get NodeInfo structure directly from a particular node
message LocalNodeInfoRequest {
// LocalNodeInfo request body is empty.
message Body {}
// Body of the LocalNodeInfo 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;
}
// Local Node Info, including API Version in use
message LocalNodeInfoResponse {
// Local Node Info, including API Version in use.
message Body {
// Latest NeoFS API version in use
neo.fs.v2.refs.Version version = 1;
// NodeInfo structure with recent information from node itself
NodeInfo node_info = 2;
}
// Body of the balance response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect response execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response 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 NetworkInfo structure with the network view from a particular node.
message NetworkInfoRequest {
// NetworkInfo request body is empty.
message Body {}
// Body of the NetworkInfo request message
Body body = 1;
// 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;
}
// Response with NetworkInfo structure including current epoch and
// sidechain magic number.
message NetworkInfoResponse {
// Information about the network.
message Body {
// NetworkInfo structure with recent information.
NetworkInfo network_info = 1;
}
// Body of the NetworkInfo response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect response execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.ResponseVerificationHeader verify_header = 3;
}
// Get netmap snapshot request
message NetmapSnapshotRequest {
// Get netmap snapshot request body.
message Body {}
// Body of get netmap snapshot request message.
Body body = 1;
// Carries request meta information. Header data is used only to regulate
// message transport and does not affect request execution.
neo.fs.v2.session.RequestMetaHeader meta_header = 2;
// Carries request verification information. This header is used to
// authenticate the nodes of the message route and check the correctness of
// transmission.
neo.fs.v2.session.RequestVerificationHeader verify_header = 3;
}
// Response with current netmap snapshot
message NetmapSnapshotResponse {
// Get netmap snapshot response body
message Body {
// Structure of the requested network map.
Netmap netmap = 1 [ json_name = "netmap" ];
}
// Body of get netmap snapshot response message.
Body body = 1;
// Carries response meta information. Header data is used only to regulate
// message transport and does not affect response execution.
neo.fs.v2.session.ResponseMetaHeader meta_header = 2;
// Carries response 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;
}

323
protos/src/main/proto/netmap/types.proto Normal file
View file

@ -0,0 +1,323 @@
syntax = "proto3";
package neo.fs.v2.netmap;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/netmap/grpc;netmap";
option java_package = "frostFS.netmap";
// Operations on filters
enum Operation {
// No Operation defined
OPERATION_UNSPECIFIED = 0;
// Equal
EQ = 1;
// Not Equal
NE = 2;
// Greater then
GT = 3;
// Greater or equal
GE = 4;
// Less then
LT = 5;
// Less or equal
LE = 6;
// Logical OR
OR = 7;
// Logical AND
AND = 8;
// Logical negation
NOT = 9;
}
// Selector modifier shows how the node set will be formed. By default selector
// just groups nodes into a bucket by attribute, selecting nodes only by their
// hash distance.
enum Clause {
// No modifier defined. Nodes will be selected from the bucket randomly
CLAUSE_UNSPECIFIED = 0;
// SAME will select only nodes having the same value of bucket attribute
SAME = 1;
// DISTINCT will select nodes having different values of bucket attribute
DISTINCT = 2;
}
// This filter will return the subset of nodes from `NetworkMap` or another
// filter's results that will satisfy filter's conditions.
message Filter {
// Name of the filter or a reference to a named filter. '*' means
// application to the whole unfiltered NetworkMap. At top level it's used as a
// filter name. At lower levels it's considered to be a reference to another
// named filter
string name = 1 [ json_name = "name" ];
// Key to filter
string key = 2 [ json_name = "key" ];
// Filtering operation
Operation op = 3 [ json_name = "op" ];
// Value to match
string value = 4 [ json_name = "value" ];
// List of inner filters. Top level operation will be applied to the whole
// list.
repeated Filter filters = 5 [ json_name = "filters" ];
}
// Selector chooses a number of nodes from the bucket taking the nearest nodes
// to the provided `ContainerID` by hash distance.
message Selector {
// Selector name to reference in object placement section
string name = 1 [ json_name = "name" ];
// How many nodes to select from the bucket
uint32 count = 2 [ json_name = "count" ];
// Selector modifier showing how to form a bucket
Clause clause = 3 [ json_name = "clause" ];
// Bucket attribute to select from
string attribute = 4 [ json_name = "attribute" ];
// Filter reference to select from
string filter = 5 [ json_name = "filter" ];
}
// Number of object replicas in a set of nodes from the defined selector. If no
// selector set, the root bucket containing all possible nodes will be used by
// default.
message Replica {
// How many object replicas to put
uint32 count = 1 [ json_name = "count" ];
// Named selector bucket to put replicas
string selector = 2 [ json_name = "selector" ];
// Data shards count
uint32 ec_data_count = 3 [ json_name = "ecDataCount" ];
// Parity shards count
uint32 ec_parity_count = 4 [ json_name = "ecParityCount" ];
}
// Set of rules to select a subset of nodes from `NetworkMap` able to store
// container's objects. The format is simple enough to transpile from different
// storage policy definition languages.
message PlacementPolicy {
// Rules to set number of object replicas and place each one into a named
// bucket
repeated Replica replicas = 1 [ json_name = "replicas" ];
// Container backup factor controls how deep NeoFS will search for nodes
// alternatives to include into container's nodes subset
uint32 container_backup_factor = 2 [ json_name = "containerBackupFactor" ];
// Set of Selectors to form the container's nodes subset
repeated Selector selectors = 3 [ json_name = "selectors" ];
// List of named filters to reference in selectors
repeated Filter filters = 4 [ json_name = "filters" ];
// Unique flag defines non-overlapping application for replicas
bool unique = 5 [ json_name = "unique" ];
}
// NeoFS node description
message NodeInfo {
// Public key of the NeoFS node in a binary format
bytes public_key = 1 [ json_name = "publicKey" ];
// Ways to connect to a node
repeated string addresses = 2 [ json_name = "addresses" ];
// Administrator-defined Attributes of the NeoFS Storage Node.
//
// `Attribute` is a Key-Value metadata pair. Key name must be a valid UTF-8
// string. Value can't be empty.
//
// Attributes can be constructed into a chain of attributes: any attribute can
// have a parent attribute and a child attribute (except the first and the
// last one). A string representation of the chain of attributes in NeoFS
// Storage Node configuration uses ":" and "/" symbols, e.g.:
//
// `NEOFS_NODE_ATTRIBUTE_1=key1:val1/key2:val2`
//
// Therefore the string attribute representation in the Node configuration
// must use "\:", "\/" and "\\" escaped symbols if any of them appears in an
// attribute's key or value.
//
// Node's attributes are mostly used during Storage Policy evaluation to
// calculate object's placement and find a set of nodes satisfying policy
// requirements. There are some "well-known" node attributes common to all the
// Storage Nodes in the network and used implicitly with default values if not
// explicitly set:
//
// * Capacity \
// Total available disk space in Gigabytes.
// * Price \
// Price in GAS tokens for storing one GB of data during one Epoch. In node
// attributes it's a string presenting floating point number with comma or
// point delimiter for decimal part. In the Network Map it will be saved as
// 64-bit unsigned integer representing number of minimal token fractions.
// * UN-LOCODE \
// Node's geographic location in
// [UN/LOCODE](https://www.unece.org/cefact/codesfortrade/codes_index.html)
// format approximated to the nearest point defined in the standard.
// * CountryCode \
// Country code in
// [ISO 3166-1_alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
// format. Calculated automatically from `UN-LOCODE` attribute.
// * Country \
// Country short name in English, as defined in
// [ISO-3166](https://www.iso.org/obp/ui/#search). Calculated automatically
// from `UN-LOCODE` attribute.
// * Location \
// Place names are given, whenever possible, in their national language
// versions as expressed in the Roman alphabet using the 26 characters of
// the character set adopted for international trade data interchange,
// written without diacritics . Calculated automatically from `UN-LOCODE`
// attribute.
// * SubDivCode \
// Country's administrative subdivision where node is located. Calculated
// automatically from `UN-LOCODE` attribute based on `SubDiv` field.
// Presented in [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)
// format.
// * SubDiv \
// Country's administrative subdivision name, as defined in
// [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2). Calculated
// automatically from `UN-LOCODE` attribute.
// * Continent \
// Node's continent name according to the [Seven-Continent model]
// (https://en.wikipedia.org/wiki/Continent#Number). Calculated
// automatically from `UN-LOCODE` attribute.
// * ExternalAddr
// Node's preferred way for communications with external clients.
// Clients SHOULD use these addresses if possible.
// Must contain a comma-separated list of multi-addresses.
//
// For detailed description of each well-known attribute please see the
// corresponding section in NeoFS Technical Specification.
message Attribute {
// Key of the node attribute
string key = 1 [ json_name = "key" ];
// Value of the node attribute
string value = 2 [ json_name = "value" ];
// Parent keys, if any. For example for `City` it could be `Region` and
// `Country`.
repeated string parents = 3 [ json_name = "parents" ];
}
// Carries list of the NeoFS node attributes in a key-value form. Key name
// must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo
// structures with duplicated attribute names or attributes with empty values
// will be considered invalid.
repeated Attribute attributes = 3 [ json_name = "attributes" ];
// Represents the enumeration of various states of the NeoFS node.
enum State {
// Unknown state
UNSPECIFIED = 0;
// Active state in the network
ONLINE = 1;
// Network unavailable state
OFFLINE = 2;
// Maintenance state
MAINTENANCE = 3;
}
// Carries state of the NeoFS node
State state = 4 [ json_name = "state" ];
}
// Network map structure
message Netmap {
// Network map revision number.
uint64 epoch = 1 [ json_name = "epoch" ];
// Nodes presented in network.
repeated NodeInfo nodes = 2 [ json_name = "nodes" ];
}
// NeoFS network configuration
message NetworkConfig {
// Single configuration parameter. Key MUST be network-unique.
//
// System parameters:
// - **AuditFee** \
// Fee paid by the storage group owner to the Inner Ring member.
// Value: little-endian integer. Default: 0.
// - **BasicIncomeRate** \
// Cost of storing one gigabyte of data for a period of one epoch. Paid by
// container owner to container nodes.
// Value: little-endian integer. Default: 0.
// - **ContainerAliasFee** \
// Fee paid for named container's creation by the container owner.
// Value: little-endian integer. Default: 0.
// - **ContainerFee** \
// Fee paid for container creation by the container owner.
// Value: little-endian integer. Default: 0.
// - **EpochDuration** \
// NeoFS epoch duration measured in Sidechain blocks.
// Value: little-endian integer. Default: 0.
// - **HomomorphicHashingDisabled** \
// Flag of disabling the homomorphic hashing of objects' payload.
// Value: true if any byte != 0. Default: false.
// - **InnerRingCandidateFee** \
// Fee for entrance to the Inner Ring paid by the candidate.
// Value: little-endian integer. Default: 0.
// - **MaintenanceModeAllowed** \
// Flag allowing setting the MAINTENANCE state to storage nodes.
// Value: true if any byte != 0. Default: false.
// - **MaxObjectSize** \
// Maximum size of physically stored NeoFS object measured in bytes.
// Value: little-endian integer. Default: 0.
// - **WithdrawFee** \
// Fee paid for withdrawal of funds paid by the account owner.
// Value: little-endian integer. Default: 0.
// - **MaxECDataCount** \
// Maximum number of data shards for EC placement policy.
// Value: little-endian integer. Default: 0.
// - **MaxECParityCount** \
// Maximum number of parity shards for EC placement policy.
// Value: little-endian integer. Default: 0.
message Parameter {
// Parameter key. UTF-8 encoded string
bytes key = 1 [ json_name = "key" ];
// Parameter value
bytes value = 2 [ json_name = "value" ];
}
// List of parameter values
repeated Parameter parameters = 1 [ json_name = "parameters" ];
}
// Information about NeoFS network
message NetworkInfo {
// Number of the current epoch in the NeoFS network
uint64 current_epoch = 1 [ json_name = "currentEpoch" ];
// Magic number of the sidechain of the NeoFS network
uint64 magic_number = 2 [ json_name = "magicNumber" ];
// MillisecondsPerBlock network parameter of the sidechain of the NeoFS
// network
int64 ms_per_block = 3 [ json_name = "msPerBlock" ];
// NeoFS network configuration
NetworkConfig network_config = 4 [ json_name = "networkConfig" ];
}

816
protos/src/main/proto/object/service.proto Normal file
View file

@ -0,0 +1,816 @@
syntax = "proto3";
package neo.fs.v2.object;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/object/grpc;object";
option java_package = "frostFS.object";
import "object/types.proto";
import "refs/types.proto";
import "session/types.proto";
// `ObjectService` provides API for manipulating objects. Object operations do
// not affect the sidechain and are only served by nodes in p2p style.
service ObjectService {
// Receive full object structure, including Headers and payload. Response uses
// gRPC stream. First response message carries the object with the requested
// address. Chunk messages are parts of the object's payload if it is needed.
// All messages, except the first one, carry payload chunks. The requested
// object can be restored by concatenation of object message payload and all
// chunks keeping the receiving order.
//
// Extended headers can change `Get` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requsted version of Network Map for object placement
// calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// Will try older versions (starting from `__SYSTEM__NETMAP_EPOCH`
// (`__NEOFS__NETMAP_EPOCH` is deprecated) if specified or the latest one
// otherwise) of Network Map to find an object until the depth limit is
// reached.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// object has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// read access to the object 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;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc Get(GetRequest) returns (stream GetResponse);
// Put the object into container. Request uses gRPC stream. First message
// SHOULD be of PutHeader type. `ContainerID` and `OwnerID` of an object
// SHOULD be set. Session token SHOULD be obtained before `PUT` operation (see
// session package). Chunk messages are considered by server as a part of an
// object payload. All messages, except first one, SHOULD be payload chunks.
// Chunk messages SHOULD be sent in the direct order of fragmentation.
//
// Extended headers can change `Put` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// 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 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 Put(stream PutRequest) returns (PutResponse);
// Delete the object from a container. There is no immediate removal
// guarantee. Object will be marked for removal and deleted eventually.
//
// Extended headers can change `Delete` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// object has been successfully marked to be removed from the container;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// delete access to the object is denied;
// - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
// the object could not be deleted because it has not been \
// found within the container;
// - **LOCKED** (2050, SECTION_OBJECT): \
// deleting a locked object is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc Delete(DeleteRequest) returns (DeleteResponse);
// Returns the object Headers without data payload. By default full header is
// returned. If `main_only` request field is set, the short header with only
// the very minimal information will be returned instead.
//
// Extended headers can change `Head` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// object header has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// access to operation HEAD of the object 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;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc Head(HeadRequest) returns (HeadResponse);
// Search objects in container. Search query allows to match by Object
// Header's filed values. Please see the corresponding NeoFS Technical
// Specification section for more details.
//
// Extended headers can change `Search` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// objects have been successfully selected;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// access to operation SEARCH of the object is denied;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// search container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc Search(SearchRequest) returns (stream SearchResponse);
// Get byte range of data payload. Range is set as an (offset, length) tuple.
// Like in `Get` method, the response uses gRPC stream. Requested range can be
// restored by concatenation of all received payload chunks keeping the
// receiving order.
//
// Extended headers can change `GetRange` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// Will try older versions of Network Map to find an object until the depth
// limit is reached.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// data range of the object payload has been successfully read;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// access to operation RANGE of the object 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 container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc GetRange(GetRangeRequest) returns (stream GetRangeResponse);
// Returns homomorphic or regular hash of object's payload range after
// applying XOR operation with the provided `salt`. Ranges are set of (offset,
// length) tuples. Hashes order in response corresponds to the ranges order in
// the request. Note that hash is calculated for XORed data.
//
// Extended headers can change `GetRangeHash` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// Will try older versions of Network Map to find an object until the depth
// limit is reached.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// data range of the object payload has been successfully hashed;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// access to operation RANGEHASH of the object is denied;
// - **OBJECT_NOT_FOUND** (2049, SECTION_OBJECT): \
// object not found in container;
// - **OUT_OF_RANGE** (2053, SECTION_OBJECT): \
// the requested range is out of bounds;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc GetRangeHash(GetRangeHashRequest) returns (GetRangeHashResponse);
// Put the prepared object into container.
// `ContainerID`, `ObjectID`, `OwnerID`, `PayloadHash` and `PayloadLength` of
// an object MUST be set.
//
// Extended headers can change `Put` behaviour:
// * [ __SYSTEM__NETMAP_EPOCH \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Will use the requested version of Network Map for object placement
// calculation.
//
// Please refer to detailed `XHeader` description.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS): \
// object has been successfully saved in the container;
// - Common failures (SECTION_FAILURE_COMMON);
// - **ACCESS_DENIED** (2048, SECTION_OBJECT): \
// write access to the container is denied;
// - **LOCKED** (2050, SECTION_OBJECT): \
// placement of an object of type TOMBSTONE that includes at least one
// locked object is prohibited;
// - **LOCK_NON_REGULAR_OBJECT** (2051, SECTION_OBJECT): \
// placement of an object of type LOCK that includes at least one object of
// type other than REGULAR is prohibited;
// - **CONTAINER_NOT_FOUND** (3072, SECTION_CONTAINER): \
// object storage container not found;
// - **CONTAINER_ACCESS_DENIED** (3074, SECTION_CONTAINER): \
// access to container is denied;
// - **TOKEN_NOT_FOUND** (4096, SECTION_SESSION): \
// (for trusted object preparation) session private key does not exist or
// has
// been deleted;
// - **TOKEN_EXPIRED** (4097, SECTION_SESSION): \
// provided session token has expired.
rpc PutSingle(PutSingleRequest) returns (PutSingleResponse);
}
// GET object request
message GetRequest {
// GET Object request body
message Body {
// Address of the requested object
neo.fs.v2.refs.Address address = 1;
// If `raw` flag is set, request will work only with objects that are
// physically stored on the peer node
bool raw = 2;
}
// Body of get 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;
}
// GET object response
message GetResponse {
// GET Object Response body
message Body {
// Initial part of the `Object` structure stream. Technically it's a
// set of all `Object` structure's fields except `payload`.
message Init {
// Object's unique identifier.
neo.fs.v2.refs.ObjectID object_id = 1;
// Signed `ObjectID`
neo.fs.v2.refs.Signature signature = 2;
// Object metadata headers
Header header = 3;
}
// Single message in the response stream.
oneof object_part {
// Initial part of the object stream
Init init = 1;
// Chunked object payload
bytes chunk = 2;
// Meta information of split hierarchy for object assembly.
SplitInfo split_info = 3;
// Meta information for EC object assembly.
ECInfo ec_info = 4;
}
}
// Body of get object response message.
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;
}
// PUT object request
message PutRequest {
// PUT request body
message Body {
// Newly created object structure parameters. If some optional parameters
// are not set, they will be calculated by a peer node.
message Init {
// ObjectID if available.
neo.fs.v2.refs.ObjectID object_id = 1;
// Object signature if available
neo.fs.v2.refs.Signature signature = 2;
// Object's Header
Header header = 3;
// Number of copies of the object to store within the RPC call. By
// default, object is processed according to the container's placement
// policy. Can be one of:
// 1. A single number; applied to the whole request and is treated as
// a minimal number of nodes that must store an object to complete the
// request successfully.
// 2. An ordered array; every number is treated as a minimal number of
// nodes in a corresponding placement vector that must store an object
// to complete the request successfully. The length MUST equal the
// placement vectors number, otherwise request is considered malformed.
repeated uint32 copies_number = 4;
}
// Single message in the request stream.
oneof object_part {
// Initial part of the object stream
Init init = 1;
// Chunked object payload
bytes chunk = 2;
}
}
// Body of put 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;
}
// PUT Object response
message PutResponse {
// PUT Object response body
message Body {
// Identifier of the saved object
neo.fs.v2.refs.ObjectID object_id = 1;
}
// Body of put 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 DELETE request
message DeleteRequest {
// Object DELETE request body
message Body {
// Address of the object to be deleted
neo.fs.v2.refs.Address address = 1;
}
// Body of delete object request message.
Body body = 1;
// 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;
}
// DeleteResponse body is empty because we cannot guarantee permanent object
// removal in distributed system.
message DeleteResponse {
// Object DELETE Response has an empty body.
message Body {
// Address of the tombstone created for the deleted object
neo.fs.v2.refs.Address tombstone = 1;
}
// Body of delete 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 HEAD request
message HeadRequest {
// Object HEAD request body
message Body {
// Address of the object with the requested Header
neo.fs.v2.refs.Address address = 1;
// Return only minimal header subset
bool main_only = 2;
// If `raw` flag is set, request will work only with objects that are
// physically stored on the peer node
bool raw = 3;
}
// Body of head 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;
}
// Tuple of a full object header and signature of an `ObjectID`. \
// Signed `ObjectID` is present to verify full header's authenticity through the
// following steps:
//
// 1. Calculate `SHA-256` of the marshalled `Header` structure
// 2. Check if the resulting hash matches `ObjectID`
// 3. Check if `ObjectID` signature in `signature` field is correct
message HeaderWithSignature {
// Full object header
Header header = 1 [ json_name = "header" ];
// Signed `ObjectID` to verify full header's authenticity
neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ];
}
// Object HEAD response
message HeadResponse {
// Object HEAD response body
message Body {
// Requested object header, it's part or meta information about split
// object.
oneof head {
// Full object's `Header` with `ObjectID` signature
HeaderWithSignature header = 1;
// Short object header
ShortHeader short_header = 2;
// Meta information of split hierarchy.
SplitInfo split_info = 3;
// Meta information for EC object assembly.
ECInfo ec_info = 4;
}
}
// Body of head 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 Search request
message SearchRequest {
// Object Search request body
message Body {
// Container identifier were to search
neo.fs.v2.refs.ContainerID container_id = 1;
// Version of the Query Language used
uint32 version = 2;
// Filter structure checks if the object header field or the attribute
// content matches a value.
//
// If no filters are set, search request will return all objects of the
// container, including Regular object and Tombstone
// objects. Most human users expect to get only object they can directly
// work with. In that case, `$Object:ROOT` filter should be used.
//
// By default `key` field refers to the corresponding object's `Attribute`.
// Some Object's header fields can also be accessed by adding `$Object:`
// prefix to the name. Here is the list of fields available via this prefix:
//
// * $Object:version \
// version
// * $Object:objectID \
// object_id
// * $Object:containerID \
// container_id
// * $Object:ownerID \
// owner_id
// * $Object:creationEpoch \
// creation_epoch
// * $Object:payloadLength \
// payload_length
// * $Object:payloadHash \
// payload_hash
// * $Object:objectType \
// object_type
// * $Object:homomorphicHash \
// homomorphic_hash
// * $Object:split.parent \
// object_id of parent
// * $Object:split.splitID \
// 16 byte UUIDv4 used to identify the split object hierarchy parts
//
// There are some well-known filter aliases to match objects by certain
// properties:
//
// * $Object:ROOT \
// Returns only `REGULAR` type objects that are not split or that are the
// top level root objects in a split hierarchy. This includes objects not
// present physically, like large objects split into smaller objects
// without a separate top-level root object. Objects of other types like
// Locks and Tombstones will not be shown. This filter may be
// useful for listing objects like `ls` command of some virtual file
// system. This filter is activated if the `key` exists, disregarding the
// value and matcher type.
// * $Object:PHY \
// Returns only objects physically stored in the system. This filter is
// activated if the `key` exists, disregarding the value and matcher type.
//
// Note: using filters with a key with prefix `$Object:` and match type
// `NOT_PRESENT `is not recommended since this is not a cross-version
// approach. Behavior when processing this kind of filters is undefined.
message Filter {
// Match type to use
MatchType match_type = 1 [ json_name = "matchType" ];
// Attribute or Header fields to match
string key = 2 [ json_name = "key" ];
// Value to match
string value = 3 [ json_name = "value" ];
}
// List of search expressions
repeated Filter filters = 3;
}
// Body of search 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;
}
// Search response
message SearchResponse {
// Object Search response body
message Body {
// List of `ObjectID`s that match the search query
repeated neo.fs.v2.refs.ObjectID id_list = 1;
}
// Body of search 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 payload range.Ranges of zero length SHOULD be considered as invalid.
message Range {
// Offset of the range from the object payload start
uint64 offset = 1;
// Length in bytes of the object payload range
uint64 length = 2;
}
// Request part of object's payload
message GetRangeRequest {
// Byte range of object's payload request body
message Body {
// Address of the object containing the requested payload range
neo.fs.v2.refs.Address address = 1;
// Requested payload range
Range range = 2;
// If `raw` flag is set, request will work only with objects that are
// physically stored on the peer node.
bool raw = 3;
}
// Body of get range 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;
}
// Get part of object's payload
message GetRangeResponse {
// Get Range response body uses streams to transfer the response. Because
// object payload considered a byte sequence, there is no need to have some
// initial preamble message. The requested byte range is sent as a series
// chunks.
message Body {
// Requested object range or meta information about split object.
oneof range_part {
// Chunked object payload's range.
bytes chunk = 1;
// Meta information of split hierarchy.
SplitInfo split_info = 2;
// Meta information for EC object assembly.
ECInfo ec_info = 3;
}
}
// Body of get range 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;
}
// Get hash of object's payload part
message GetRangeHashRequest {
// Get hash of object's payload part request body.
message Body {
// Address of the object that containing the requested payload range
neo.fs.v2.refs.Address address = 1;
// List of object's payload ranges to calculate homomorphic hash
repeated Range ranges = 2;
// Binary salt to XOR object's payload ranges before hash calculation
bytes salt = 3;
// Checksum algorithm type
neo.fs.v2.refs.ChecksumType type = 4;
}
// Body of get range hash 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;
}
// Get hash of object's payload part
message GetRangeHashResponse {
// Get hash of object's payload part response body.
message Body {
// Checksum algorithm type
neo.fs.v2.refs.ChecksumType type = 1;
// List of range hashes in a binary format
repeated bytes hash_list = 2;
}
// Body of get range hash 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 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;
}

266
protos/src/main/proto/object/types.proto Normal file
View file

@ -0,0 +1,266 @@
syntax = "proto3";
package neo.fs.v2.object;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/object/grpc;object";
option java_package = "frostFS.object";
import "refs/types.proto";
import "session/types.proto";
// Type of the object payload content. Only `REGULAR` type objects can be split,
// hence `TOMBSTONE` and `LOCK` payload is limited by the
// maximum object size.
//
// String presentation of object type is the same as definition:
// * REGULAR
// * TOMBSTONE
// * LOCK
enum ObjectType {
// Just a normal object
REGULAR = 0;
// Used internally to identify deleted objects
TOMBSTONE = 1;
// Unused (previously storageGroup information)
// _ = 2;
// Object lock
LOCK = 3;
}
// Type of match expression
enum MatchType {
// Unknown. Not used
MATCH_TYPE_UNSPECIFIED = 0;
// Full string match
STRING_EQUAL = 1;
// Full string mismatch
STRING_NOT_EQUAL = 2;
// Lack of key
NOT_PRESENT = 3;
// String prefix match
COMMON_PREFIX = 4;
}
// Short header fields
message ShortHeader {
// Object format version. Effectively, the version of API library used to
// create particular object.
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Epoch when the object was created
uint64 creation_epoch = 2 [ json_name = "creationEpoch" ];
// Object's owner
neo.fs.v2.refs.OwnerID owner_id = 3 [ json_name = "ownerID" ];
// Type of the object payload content
ObjectType object_type = 4 [ json_name = "objectType" ];
// Size of payload in bytes.
// `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown
uint64 payload_length = 5 [ json_name = "payloadLength" ];
// Hash of payload bytes
neo.fs.v2.refs.Checksum payload_hash = 6 [ json_name = "payloadHash" ];
// Homomorphic hash of the object payload
neo.fs.v2.refs.Checksum homomorphic_hash = 7
[ json_name = "homomorphicHash" ];
}
// Object Header
message Header {
// Object format version. Effectively, the version of API library used to
// create particular object
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Object's container
neo.fs.v2.refs.ContainerID container_id = 2 [ json_name = "containerID" ];
// Object's owner
neo.fs.v2.refs.OwnerID owner_id = 3 [ json_name = "ownerID" ];
// Object creation Epoch
uint64 creation_epoch = 4 [ json_name = "creationEpoch" ];
// Size of payload in bytes.
// `0xFFFFFFFFFFFFFFFF` means `payload_length` is unknown.
uint64 payload_length = 5 [ json_name = "payloadLength" ];
// Hash of payload bytes
neo.fs.v2.refs.Checksum payload_hash = 6 [ json_name = "payloadHash" ];
// Type of the object payload content
ObjectType object_type = 7 [ json_name = "objectType" ];
// Homomorphic hash of the object payload
neo.fs.v2.refs.Checksum homomorphic_hash = 8
[ json_name = "homomorphicHash" ];
// Session token, if it was used during Object creation. Need it to verify
// integrity and authenticity out of Request scope.
neo.fs.v2.session.SessionToken session_token = 9
[ json_name = "sessionToken" ];
// `Attribute` is a user-defined Key-Value metadata pair attached to an
// object.
//
// Key name must be an object-unique valid UTF-8 string. Value can't be empty.
// Objects with duplicated attribute names or attributes with empty values
// will be considered invalid.
//
// There are some "well-known" attributes starting with `__SYSTEM__`
// (`__NEOFS__` is deprecated) prefix that affect system behaviour:
//
// * [ __SYSTEM__UPLOAD_ID ] \
// (`__NEOFS__UPLOAD_ID` is deprecated) \
// Marks smaller parts of a split bigger object
// * [ __SYSTEM__EXPIRATION_EPOCH ] \
// (`__NEOFS__EXPIRATION_EPOCH` is deprecated) \
// The epoch after which object with no LOCKs on it becomes unavailable.
// Locked object continues to be available until each of the LOCKs expire.
// * [ __SYSTEM__TICK_EPOCH ] \
// (`__NEOFS__TICK_EPOCH` is deprecated) \
// Decimal number that defines what epoch must produce
// object notification with UTF-8 object address in a
// body (`0` value produces notification right after
// object put)
// * [ __SYSTEM__TICK_TOPIC ] \
// (`__NEOFS__TICK_TOPIC` is deprecated) \
// UTF-8 string topic ID that is used for object notification
//
// And some well-known attributes used by applications only:
//
// * Name \
// Human-friendly name
// * FileName \
// File name to be associated with the object on saving
// * FilePath \
// Full path to be associated with the object on saving. Should start with a
// '/' and use '/' as a delimiting symbol. Trailing '/' should be
// interpreted as a virtual directory marker. If an object has conflicting
// FilePath and FileName, FilePath should have higher priority, because it
// is used to construct the directory tree. FilePath with trailing '/' and
// non-empty FileName attribute should not be used together.
// * Timestamp \
// User-defined local time of object creation in Unix Timestamp format
// * Content-Type \
// MIME Content Type of object's payload
//
// For detailed description of each well-known attribute please see the
// corresponding section in NeoFS Technical Specification.
message Attribute {
// string key to the object attribute
string key = 1 [ json_name = "key" ];
// string value of the object attribute
string value = 2 [ json_name = "value" ];
}
// User-defined object attributes
repeated Attribute attributes = 10 [ json_name = "attributes" ];
// Bigger objects can be split into a chain of smaller objects. Information
// about inter-dependencies between spawned objects and how to re-construct
// the original one is in the `Split` headers. Parent and children objects
// must be within the same container.
message Split {
// Identifier of the origin object. Known only to the minor child.
neo.fs.v2.refs.ObjectID parent = 1 [ json_name = "parent" ];
// Identifier of the left split neighbor
neo.fs.v2.refs.ObjectID previous = 2 [ json_name = "previous" ];
// `signature` field of the parent object. Used to reconstruct parent.
neo.fs.v2.refs.Signature parent_signature = 3
[ json_name = "parentSignature" ];
// `header` field of the parent object. Used to reconstruct parent.
Header parent_header = 4 [ json_name = "parentHeader" ];
// List of identifiers of the objects generated by splitting current one.
repeated neo.fs.v2.refs.ObjectID children = 5 [ json_name = "children" ];
// 16 byte UUIDv4 used to identify the split object hierarchy parts. Must be
// unique inside container. All objects participating in the split must have
// the same `split_id` value.
bytes split_id = 6 [ json_name = "splitID" ];
}
// Position of the object in the split hierarchy
Split split = 11 [ json_name = "split" ];
// Erasure code can be applied to any object.
// Information about encoded object structure is stored in `EC` header.
// All objects belonging to a single EC group have the same `parent` field.
message EC {
// Identifier of the origin object. Known to all chunks.
neo.fs.v2.refs.ObjectID parent = 1 [ json_name = "parent" ];
// Index of this chunk.
uint32 index = 2 [ json_name = "index" ];
// Total number of chunks in this split.
uint32 total = 3 [ json_name = "total" ];
// Total length of a parent header. Used to trim padding zeroes.
uint32 header_length = 4 [ json_name = "headerLength" ];
// Chunk of a parent header.
bytes header = 5 [ json_name = "header" ];
}
// Erasure code chunk information.
EC ec = 12 [ json_name = "ec" ];
}
// Object structure. Object is immutable and content-addressed. It means
// `ObjectID` will change if the header or the payload changes. It's calculated
// as a hash of header field which contains hash of the object's payload.
//
// For non-regular object types payload format depends on object type specified
// in the header.
message Object {
// Object's unique identifier.
neo.fs.v2.refs.ObjectID object_id = 1 [ json_name = "objectID" ];
// Signed object_id
neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ];
// Object metadata headers
Header header = 3 [ json_name = "header" ];
// Payload bytes
bytes payload = 4 [ json_name = "payload" ];
}
// Meta information of split hierarchy for object assembly. With the last part
// one can traverse linked list of split hierarchy back to the first part and
// assemble the original object. With a linking object one can assemble an
// object right from the object parts.
message SplitInfo {
// 16 byte UUID used to identify the split object hierarchy parts.
bytes split_id = 1;
// The identifier of the last object in split hierarchy parts. It contains
// split header with the original object header.
neo.fs.v2.refs.ObjectID last_part = 2;
// The identifier of a linking object for split hierarchy parts. It contains
// split header with the original object header and a sorted list of
// object parts.
neo.fs.v2.refs.ObjectID link = 3;
}
// Meta information for the erasure-encoded object.
message ECInfo {
message Chunk {
// Object ID of the chunk.
neo.fs.v2.refs.ObjectID id = 1;
// Index of the chunk.
uint32 index = 2;
// Total number of chunks in this split.
uint32 total = 3;
}
// Chunk stored on the node.
repeated Chunk chunks = 1;
}

150
protos/src/main/proto/refs/types.proto Normal file
View file

@ -0,0 +1,150 @@
syntax = "proto3";
package neo.fs.v2.refs;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/refs/grpc;refs";
option java_package = "frostFS.refs";
// Objects in NeoFS are addressed by their ContainerID and ObjectID.
//
// String presentation of `Address` is a concatenation of string encoded
// `ContainerID` and `ObjectID` delimited by '/' character.
message Address {
// Container identifier
ContainerID container_id = 1 [ json_name = "containerID" ];
// Object identifier
ObjectID object_id = 2 [ json_name = "objectID" ];
}
// NeoFS Object unique identifier. Objects are immutable and content-addressed.
// It means `ObjectID` will change if the `header` or the `payload` changes.
//
// `ObjectID` is a 32 byte long
// [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
// the object's `header` field, which, in it's turn, contains the hash of the
// object's payload.
//
// 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 ObjectID {
// Object identifier in a binary format
bytes value = 1 [ json_name = "value" ];
}
// NeoFS container identifier. Container structures are immutable and
// content-addressed.
//
// `ContainerID` is a 32 byte long
// [SHA256](https://csrc.nist.gov/publications/detail/fips/180/4/final) hash of
// stable-marshalled container message.
//
// 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 ContainerID {
// Container identifier in a binary format.
bytes value = 1 [ json_name = "value" ];
}
// `OwnerID` is a derivative of a user's main public key. The transformation
// algorithm is the same as for Neo3 wallet addresses. Neo3 wallet address can
// be directly used as `OwnerID`.
//
// `OwnerID` is a 25 bytes sequence starting with Neo version prefix byte
// followed by 20 bytes of ScrptHash and 4 bytes of checksum.
//
// String presentation is a [Base58
// Check](https://en.bitcoin.it/wiki/Base58Check_encoding) 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 OwnerID {
// Identifier of the container owner in a binary format
bytes value = 1 [ json_name = "value" ];
}
// API version used by a node.
//
// String presentation is a Semantic Versioning 2.0.0 compatible version string
// with 'v' prefix. i.e. `vX.Y`, where `X` is the major number, `Y` is the minor
// number.
message Version {
// Major API version
uint32 major = 1 [ json_name = "major" ];
// Minor API version
uint32 minor = 2 [ json_name = "minor" ];
}
// Signature of something in NeoFS.
message Signature {
// Public key used for signing
bytes key = 1 [ json_name = "key" ];
// Signature
bytes sign = 2 [ json_name = "signature" ];
// Scheme contains digital signature scheme identifier
SignatureScheme scheme = 3 [ json_name = "scheme" ];
}
// Signature scheme describes digital signing scheme used for (key, signature)
// pair.
enum SignatureScheme {
// ECDSA with SHA-512 hashing (FIPS 186-3)
ECDSA_SHA512 = 0;
// Deterministic ECDSA with SHA-256 hashing (RFC 6979)
ECDSA_RFC6979_SHA256 = 1;
// Deterministic ECDSA with SHA-256 hashing using WalletConnect API.
// Here the algorithm is the same, but the message format differs.
ECDSA_RFC6979_SHA256_WALLET_CONNECT = 2;
}
// RFC 6979 signature.
message SignatureRFC6979 {
// Public key used for signing
bytes key = 1 [ json_name = "key" ];
// Deterministic ECDSA with SHA-256 hashing
bytes sign = 2 [ json_name = "signature" ];
}
// Checksum algorithm type.
enum ChecksumType {
// Unknown. Not used
CHECKSUM_TYPE_UNSPECIFIED = 0;
// Tillich-Zemor homomorphic hash function
TZ = 1;
// SHA-256
SHA256 = 2;
}
// Checksum message.
// Depending on checksum algorithm type, the string presentation may vary:
//
// * TZ \
// Hex encoded string without `0x` prefix
// * SHA256 \
// Hex encoded string without `0x` prefix
message Checksum {
// Checksum algorithm type
ChecksumType type = 1 [ json_name = "type" ];
// Checksum itself
bytes sum = 2 [ json_name = "sum" ];
}

69
protos/src/main/proto/session/service.proto Normal file
View file

@ -0,0 +1,69 @@
syntax = "proto3";
package neo.fs.v2.session;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/session/grpc;session";
option java_package = "frostFS.session";
import "refs/types.proto";
import "session/types.proto";
// `SessionService` allows to establish a temporary trust relationship between
// two peer nodes and generate a `SessionToken` as the proof of trust to be
// attached in requests for further verification. Please see corresponding
// section of NeoFS Technical Specification for details.
service SessionService {
// Open a new session between two peers.
//
// Statuses:
// - **OK** (0, SECTION_SUCCESS):
// session has been successfully opened;
// - Common failures (SECTION_FAILURE_COMMON).
rpc Create(CreateRequest) returns (CreateResponse);
}
// Information necessary for opening a session.
message CreateRequest {
// Session creation request body
message Body {
// Session initiating user's or node's key derived `OwnerID`
neo.fs.v2.refs.OwnerID owner_id = 1;
// Session expiration `Epoch`
uint64 expiration = 2;
}
// Body of a create session token 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;
}
// Information about the opened session.
message CreateResponse {
// Session creation response body
message Body {
// Identifier of a newly created session
bytes id = 1;
// Public key used for session
bytes session_key = 2;
}
// Body of create session token 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;
}

238
protos/src/main/proto/session/types.proto Normal file
View file

@ -0,0 +1,238 @@
syntax = "proto3";
package neo.fs.v2.session;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/session/grpc;session";
option java_package = "frostFS.session";
import "refs/types.proto";
import "acl/types.proto";
import "status/types.proto";
// Context information for Session Tokens related to ObjectService requests
message ObjectSessionContext {
// Object request verbs
enum Verb {
// Unknown verb
VERB_UNSPECIFIED = 0;
// Refers to object.Put RPC call
PUT = 1;
// Refers to object.Get RPC call
GET = 2;
// Refers to object.Head RPC call
HEAD = 3;
// Refers to object.Search RPC call
SEARCH = 4;
// Refers to object.Delete RPC call
DELETE = 5;
// Refers to object.GetRange RPC call
RANGE = 6;
// Refers to object.GetRangeHash RPC call
RANGEHASH = 7;
}
// Type of request for which the token is issued
Verb verb = 1 [ json_name = "verb" ];
// Carries objects involved in the object session.
message Target {
// Indicates which container the session is spread to. Field MUST be set
// and correct.
refs.ContainerID container = 1 [ json_name = "container" ];
// 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.
repeated refs.ObjectID objects = 2 [ json_name = "objects" ];
}
// Object session target. MUST be correctly formed and set. If `objects`
// field is not empty, then the session applies only to these elements,
// otherwise, to all objects from the specified container.
Target target = 2 [ json_name = "target" ];
}
// Context information for Session Tokens related to ContainerService requests.
message ContainerSessionContext {
// Container request verbs
enum Verb {
// Unknown verb
VERB_UNSPECIFIED = 0;
// Refers to container.Put RPC call
PUT = 1;
// Refers to container.Delete RPC call
DELETE = 2;
// Refers to container.SetExtendedACL RPC call
SETEACL = 3;
}
// Type of request for which the token is issued
Verb verb = 1 [ json_name = "verb" ];
// Spreads the action to all owner containers.
// If set, container_id field is ignored.
bool wildcard = 2 [ json_name = "wildcard" ];
// Particular container to which the action applies.
// Ignored if wildcard flag is set.
refs.ContainerID container_id = 3 [ json_name = "containerID" ];
}
// NeoFS Session Token.
message SessionToken {
// Session Token body
message Body {
// Token identifier is a valid UUIDv4 in binary form
bytes id = 1 [ json_name = "id" ];
// Identifier of the session initiator
neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ];
// Lifetime parameters of the token. Field names taken from rfc7519.
message TokenLifetime {
// Expiration Epoch
uint64 exp = 1 [ json_name = "exp" ];
// Not valid before Epoch
uint64 nbf = 2 [ json_name = "nbf" ];
// Issued at Epoch
uint64 iat = 3 [ json_name = "iat" ];
}
// Lifetime of the session
TokenLifetime lifetime = 3 [ json_name = "lifetime" ];
// Public key used in session
bytes session_key = 4 [ json_name = "sessionKey" ];
// Session Context information
oneof context {
// ObjectService session context
ObjectSessionContext object = 5 [ json_name = "object" ];
// ContainerService session context
ContainerSessionContext container = 6 [ json_name = "container" ];
}
}
// Session Token contains the proof of trust between peers to be attached in
// requests for further verification. Please see corresponding section of
// NeoFS Technical Specification for details.
Body body = 1 [ json_name = "body" ];
// Signature of `SessionToken` information
neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ];
}
// Extended headers for Request/Response. They may contain any user-defined
// headers to be interpreted on application level.
//
// Key name must be a unique valid UTF-8 string. Value can't be empty. Requests
// or Responses with duplicated header names or headers with empty values will
// be considered invalid.
//
// There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__`
// is deprecated) prefix that affect system behaviour:
//
// * [ __SYSTEM__NETMAP_EPOCH ] \
// (`__NEOFS__NETMAP_EPOCH` is deprecated) \
// Netmap epoch to use for object placement calculation. The `value` is string
// encoded `uint64` in decimal presentation. If set to '0' or not set, the
// current epoch only will be used.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
// (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
// If object can't be found using current epoch's netmap, this header limits
// how many past epochs the node can look up through. The `value` is string
// encoded `uint64` in decimal presentation. If set to '0' or not set, only
// the current epoch will be used.
message XHeader {
// Key of the X-Header
string key = 1 [ json_name = "key" ];
// Value of the X-Header
string value = 2 [ json_name = "value" ];
}
// Meta information attached to the request. When forwarded between peers,
// request meta headers are folded in matryoshka style.
message RequestMetaHeader {
// Peer's API version used
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Peer's local epoch number. Set to 0 if unknown.
uint64 epoch = 2 [ json_name = "epoch" ];
// Maximum number of intermediate nodes in the request route
uint32 ttl = 3 [ json_name = "ttl" ];
// Request X-Headers
repeated XHeader x_headers = 4 [ json_name = "xHeaders" ];
// Session token within which the request is sent
SessionToken session_token = 5 [ json_name = "sessionToken" ];
// `BearerToken` with eACL overrides for the request
neo.fs.v2.acl.BearerToken bearer_token = 6 [ json_name = "bearerToken" ];
// `RequestMetaHeader` of the origin request
RequestMetaHeader origin = 7 [ json_name = "origin" ];
// NeoFS network magic. Must match the value for the network
// that the server belongs to.
uint64 magic_number = 8 [ json_name = "magicNumber" ];
}
// Information about the response
message ResponseMetaHeader {
// Peer's API version used
neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];
// Peer's local epoch number
uint64 epoch = 2 [ json_name = "epoch" ];
// Maximum number of intermediate nodes in the request route
uint32 ttl = 3 [ json_name = "ttl" ];
// Response X-Headers
repeated XHeader x_headers = 4 [ json_name = "xHeaders" ];
// `ResponseMetaHeader` of the origin request
ResponseMetaHeader origin = 5 [ json_name = "origin" ];
// Status return
neo.fs.v2.status.Status status = 6 [ json_name = "status" ];
}
// Verification info for the request signed by all intermediate nodes.
message RequestVerificationHeader {
// Request Body signature. Should be generated once by the request initiator.
neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ];
// Request Meta signature is added and signed by each intermediate node
neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ];
// Signature of previous hops
neo.fs.v2.refs.Signature origin_signature = 3
[ json_name = "originSignature" ];
// Chain of previous hops signatures
RequestVerificationHeader origin = 4 [ json_name = "origin" ];
}
// Verification info for the response signed by all intermediate nodes
message ResponseVerificationHeader {
// Response Body signature. Should be generated once by an answering node.
neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ];
// Response Meta signature is added and signed by each intermediate node
neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ];
// Signature of previous hops
neo.fs.v2.refs.Signature origin_signature = 3
[ json_name = "originSignature" ];
// Chain of previous hops signatures
ResponseVerificationHeader origin = 4 [ json_name = "origin" ];
}

157
protos/src/main/proto/status/types.proto Normal file
View file

@ -0,0 +1,157 @@
syntax = "proto3";
package neo.fs.v2.status;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/status/grpc;status";
option java_package = "frostFS.status";
// Declares the general format of the status returns of the NeoFS RPC protocol.
// Status is present in all response messages. Each RPC of NeoFS protocol
// describes the possible outcomes and details of the operation.
//
// Each status is assigned a one-to-one numeric code. Any unique result of an
// operation in NeoFS is unambiguously associated with the code value.
//
// Numerical set of codes is split into 1024-element sections. An enumeration
// is defined for each section. Values can be referred to in the following ways:
//
// * numerical value ranging from 0 to 4,294,967,295 (global code);
//
// * values from enumeration (local code). The formula for the ratio of the
// local code (`L`) of a defined section (`S`) to the global one (`G`):
// `G = 1024 * S + L`.
//
// All outcomes are divided into successful and failed, which corresponds
// to the success or failure of the operation. The definition of success
// follows the semantics of RPC and the description of its purpose.
// The server must not attach code that is the opposite of the outcome type.
//
// See the set of return codes in the description for calls.
//
// Each status can carry a developer-facing error message. It should be a human
// readable text in English. The server should not transmit (and the client
// should not expect) useful information in the message. Field `details`
// should make the return more detailed.
message Status {
// The status code
uint32 code = 1;
// Developer-facing error message
string message = 2;
// Return detail. It contains additional information that can be used to
// analyze the response. Each code defines a set of details that can be
// attached to a status. Client should not handle details that are not
// covered by the code.
message Detail {
// Detail ID. The identifier is required to determine the binary format
// of the detail and how to decode it.
uint32 id = 1;
// Binary status detail. Must follow the format associated with ID.
// The possibility of missing a value must be explicitly allowed.
bytes value = 2;
}
// Data detailing the outcome of the operation. Must be unique by ID.
repeated Detail details = 3;
}
// Section identifiers.
enum Section {
// Successful return codes.
SECTION_SUCCESS = 0;
// Failure codes regardless of the operation.
SECTION_FAILURE_COMMON = 1;
// Object service-specific errors.
SECTION_OBJECT = 2;
// Container service-specific errors.
SECTION_CONTAINER = 3;
// Session service-specific errors.
SECTION_SESSION = 4;
// Session service-specific errors.
SECTION_APE_MANAGER = 5;
}
// Section of NeoFS successful return codes.
enum Success {
// [**0**] Default success. Not detailed.
// If the server cannot match successful outcome to the code, it should
// use this code.
OK = 0;
}
// Section of failed statuses independent of the operation.
enum CommonFail {
// [**1024**] Internal server error, default failure. Not detailed.
// If the server cannot match failed outcome to the code, it should
// use this code.
INTERNAL = 0;
// [**1025**] Wrong magic of the NeoFS network.
// Details:
// - [**0**] Magic number of the served NeoFS network (big-endian 64-bit
// unsigned integer).
WRONG_MAGIC_NUMBER = 1;
// [**1026**] Signature verification failure.
SIGNATURE_VERIFICATION_FAIL = 2;
// [**1027**] Node is under maintenance.
NODE_UNDER_MAINTENANCE = 3;
}
// Section of statuses for object-related operations.
enum Object {
// [**2048**] Access denied by ACL.
// Details:
// - [**0**] Human-readable description (UTF-8 encoded string).
ACCESS_DENIED = 0;
// [**2049**] Object not found.
OBJECT_NOT_FOUND = 1;
// [**2050**] Operation rejected by the object lock.
LOCKED = 2;
// [**2051**] Locking an object with a non-REGULAR type rejected.
LOCK_NON_REGULAR_OBJECT = 3;
// [**2052**] Object has been marked deleted.
OBJECT_ALREADY_REMOVED = 4;
// [**2053**] Invalid range has been requested for an object.
OUT_OF_RANGE = 5;
}
// Section of statuses for container-related operations.
enum Container {
// [**3072**] Container not found.
CONTAINER_NOT_FOUND = 0;
// [**3073**] eACL table not found.
EACL_NOT_FOUND = 1;
// [**3074**] Container access denied.
CONTAINER_ACCESS_DENIED = 2;
}
// Section of statuses for session-related operations.
enum Session {
// [**4096**] Token not found.
TOKEN_NOT_FOUND = 0;
// [**4097**] Token has expired.
TOKEN_EXPIRED = 1;
}
// Section of status for APE manager related operations.
enum APEManager {
// [**5120**] The operation is denied by APE manager.
APE_MANAGER_ACCESS_DENIED = 0;
}

27
protos/src/main/proto/tombstone/types.proto Normal file
View file

@ -0,0 +1,27 @@
syntax = "proto3";
package neo.fs.v2.tombstone;
option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/tombstone/grpc;tombstone";
option java_package = "frostFS.tombstone";
import "refs/types.proto";
// Tombstone keeps record of deleted objects for a few epochs until they are
// purged from the NeoFS network.
message Tombstone {
// 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
// `__SYSTEM__EXPIRATION_EPOCH` (`__NEOFS__EXPIRATION_EPOCH` is deprecated)
// attribute. Otherwise, the tombstone will be rejected by a storage node.
uint64 expiration_epoch = 1 [ json_name = "expirationEpoch" ];
// 16 byte UUID used to identify the split object hierarchy parts. Must be
// unique inside a container. All objects participating in the split must
// have the same `split_id` value.
bytes split_id = 2 [ json_name = "splitID" ];
// List of objects to be deleted.
repeated neo.fs.v2.refs.ObjectID members = 3 [ json_name = "members" ];
}