control.md

Protocol Documentation

Table of Contents

• control/service.proto

• Services

  • ControlService

• Messages

  • DropObjectsRequest
  • DropObjectsRequest.Body
  • DropObjectsResponse
  • DropObjectsResponse.Body
  • DumpShardRequest
  • DumpShardRequest.Body
  • DumpShardResponse
  • DumpShardResponse.Body
  • HealthCheckRequest
  • HealthCheckRequest.Body
  • HealthCheckResponse
  • HealthCheckResponse.Body
  • ListShardsRequest
  • ListShardsRequest.Body
  • ListShardsResponse
  • ListShardsResponse.Body
  • NetmapSnapshotRequest
  • NetmapSnapshotRequest.Body
  • NetmapSnapshotResponse
  • NetmapSnapshotResponse.Body
  • RestoreShardRequest
  • RestoreShardRequest.Body
  • RestoreShardResponse
  • RestoreShardResponse.Body
  • SetNetmapStatusRequest
  • SetNetmapStatusRequest.Body
  • SetNetmapStatusResponse
  • SetNetmapStatusResponse.Body
  • SetShardModeRequest
  • SetShardModeRequest.Body
  • SetShardModeResponse
  • SetShardModeResponse.Body
  • SynchronizeTreeRequest
  • SynchronizeTreeRequest.Body
  • SynchronizeTreeResponse
  • SynchronizeTreeResponse.Body

• control/types.proto

  • Messages
    • Netmap
    • NodeInfo
    • NodeInfo.Attribute
    • ShardInfo
    • Signature

• Scalar Value Types

Top

control/service.proto

Service "control.ControlService"

ControlService provides an interface for internal work with the storage node.

rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
rpc NetmapSnapshot(NetmapSnapshotRequest) returns (NetmapSnapshotResponse);
rpc SetNetmapStatus(SetNetmapStatusRequest) returns (SetNetmapStatusResponse);
rpc DropObjects(DropObjectsRequest) returns (DropObjectsResponse);
rpc ListShards(ListShardsRequest) returns (ListShardsResponse);
rpc SetShardMode(SetShardModeRequest) returns (SetShardModeResponse);
rpc DumpShard(DumpShardRequest) returns (DumpShardResponse);
rpc RestoreShard(RestoreShardRequest) returns (RestoreShardResponse);
rpc SynchronizeTree(SynchronizeTreeRequest) returns (SynchronizeTreeResponse);

Method HealthCheck

Performs health check of the storage node.

Name	Input	Output
HealthCheck	HealthCheckRequest	HealthCheckResponse

Method NetmapSnapshot

Returns network map snapshot of the current NeoFS epoch.

Name	Input	Output
NetmapSnapshot	NetmapSnapshotRequest	NetmapSnapshotResponse

Method SetNetmapStatus

Sets status of the storage node in NeoFS network map.

Name	Input	Output
SetNetmapStatus	SetNetmapStatusRequest	SetNetmapStatusResponse

Method DropObjects

Mark objects to be removed from node's local object storage.

Name	Input	Output
DropObjects	DropObjectsRequest	DropObjectsResponse

Method ListShards

Returns list that contains information about all shards of a node.

Name	Input	Output
ListShards	ListShardsRequest	ListShardsResponse

Method SetShardMode

Sets mode of the shard.

Name	Input	Output
SetShardMode	SetShardModeRequest	SetShardModeResponse

Method DumpShard

Dump objects from the shard.

Name	Input	Output
DumpShard	DumpShardRequest	DumpShardResponse

Method RestoreShard

Restore objects from dump.

Name	Input	Output
RestoreShard	RestoreShardRequest	RestoreShardResponse

Method SynchronizeTree

Synchronizes all log operations for the specified tree.

Name	Input	Output
SynchronizeTree	SynchronizeTreeRequest	SynchronizeTreeResponse

Message DropObjectsRequest

Request to drop the objects.

Field	Type	Label	Description
body	DropObjectsRequest.Body		Body of the request message.
signature	Signature		Body signature.

Message DropObjectsRequest.Body

Request body structure.

Field	Type	Label	Description
address_list	bytes	repeated	List of object addresses to be removed. in NeoFS API binary format.

Message DropObjectsResponse

Response to request to drop the objects.

Field	Type	Label	Description
body	DropObjectsResponse.Body		Body of the response message.
signature	Signature		Body signature.

Message DropObjectsResponse.Body

Response body structure.

Message DumpShardRequest

DumpShard request.

Field	Type	Label	Description
body	DumpShardRequest.Body		Body of dump shard request message.
signature	Signature		Body signature.

Message DumpShardRequest.Body

Request body structure.

Field	Type	Label	Description
shard_ID	bytes		ID of the shard.
filepath	string		Path to the output.
ignore_errors	bool		Flag indicating whether object read errors should be ignored.

Message DumpShardResponse

DumpShard response.

Field	Type	Label	Description
body	DumpShardResponse.Body		Body of dump shard response message.
signature	Signature		Body signature.

Message DumpShardResponse.Body

Response body structure.

Message HealthCheckRequest

Health check request.

Field	Type	Label	Description
body	HealthCheckRequest.Body		Body of health check request message.
signature	Signature		Body signature.

Message HealthCheckRequest.Body

Health check request body.

Message HealthCheckResponse

Health check request.

Field	Type	Label	Description
body	HealthCheckResponse.Body		Body of health check response message.
signature	Signature		Body signature.

Message HealthCheckResponse.Body

Health check response body

Field	Type	Label	Description
netmap_status	NetmapStatus		Status of the storage node in NeoFS network map.
health_status	HealthStatus		Health status of storage node application.

Message ListShardsRequest

Request to list all shards of the node.

Field	Type	Label	Description
body	ListShardsRequest.Body		Body of the request message.
signature	Signature		Body signature.

Message ListShardsRequest.Body

Request body structure.

Message ListShardsResponse

ListShards response.

Field	Type	Label	Description
body	ListShardsResponse.Body		Body of the response message.
signature	Signature		Body signature.

Message ListShardsResponse.Body

Response body structure.

Field	Type	Label	Description
shards	ShardInfo	repeated	List of the node's shards.

Message NetmapSnapshotRequest

Get netmap snapshot request.

Field	Type	Label	Description
body	NetmapSnapshotRequest.Body		Body of get netmap snapshot request message.
signature	Signature		Body signature.

Message NetmapSnapshotRequest.Body

Get netmap snapshot request body.

Message NetmapSnapshotResponse

Get netmap snapshot request.

Field	Type	Label	Description
body	NetmapSnapshotResponse.Body		Body of get netmap snapshot response message.
signature	Signature		Body signature.

Message NetmapSnapshotResponse.Body

Get netmap snapshot response body

Field	Type	Label	Description
netmap	Netmap		Structure of the requested network map.

Message RestoreShardRequest

RestoreShard request.

Field	Type	Label	Description
body	RestoreShardRequest.Body		Body of restore shard request message.
signature	Signature		Body signature.

Message RestoreShardRequest.Body

Request body structure.

Field	Type	Label	Description
shard_ID	bytes		ID of the shard.
filepath	string		Path to the output.
ignore_errors	bool		Flag indicating whether object read errors should be ignored.

Message RestoreShardResponse

RestoreShard response.

Field	Type	Label	Description
body	RestoreShardResponse.Body		Body of restore shard response message.
signature	Signature		Body signature.

Message RestoreShardResponse.Body

Response body structure.

Message SetNetmapStatusRequest

Set netmap status request.

Field	Type	Label	Description
body	SetNetmapStatusRequest.Body		Body of set netmap status request message.
signature	Signature		Body signature.

Message SetNetmapStatusRequest.Body

Set netmap status request body.

Field	Type	Label	Description
status	NetmapStatus		New storage node status in NeoFS network map.

Message SetNetmapStatusResponse

Set netmap status response.

Field	Type	Label	Description
body	SetNetmapStatusResponse.Body		Body of set netmap status response message.
signature	Signature		Body signature.

Message SetNetmapStatusResponse.Body

Set netmap status response body

Message SetShardModeRequest

Request to set mode of the shard.

Field	Type	Label	Description
body	SetShardModeRequest.Body		Body of set shard mode request message.
signature	Signature		Body signature.

Message SetShardModeRequest.Body

Request body structure.

Field	Type	Label	Description
shard_ID	bytes		ID of the shard.
mode	ShardMode		Mode that requested to be set.
resetErrorCounter	bool		Flag signifying whether error counter should be set to 0.

Message SetShardModeResponse

SetShardMode response.

Field	Type	Label	Description
body	SetShardModeResponse.Body		Body of set shard mode response message.
signature	Signature		Body signature.

Message SetShardModeResponse.Body

Response body structure.

Message SynchronizeTreeRequest

SynchronizeTree request.

Field	Type	Label	Description
body	SynchronizeTreeRequest.Body		Body of restore shard request message.
signature	Signature		Body signature.

Message SynchronizeTreeRequest.Body

Request body structure.

Field	Type	Label	Description
container_id	bytes
tree_id	string
height	uint64		Starting height for the synchronization. Can be omitted.

Message SynchronizeTreeResponse

SynchronizeTree response.

Field	Type	Label	Description
body	SynchronizeTreeResponse.Body		Body of restore shard response message.
signature	Signature		Body signature.

Message SynchronizeTreeResponse.Body

Response body structure.

Top

control/types.proto

Message Netmap

Network map structure.

Field	Type	Label	Description
epoch	uint64		Network map revision number.
nodes	NodeInfo	repeated	Nodes presented in network.

Message NodeInfo

NeoFS node description.

Field	Type	Label	Description
public_key	bytes		Public key of the NeoFS node in a binary format.
addresses	string	repeated	Ways to connect to a node.
attributes	NodeInfo.Attribute	repeated	Carries list of the NeoFS node attributes in a key-value form. Key name must be a node-unique valid UTF-8 string. Value can't be empty. NodeInfo structures with duplicated attribute names or attributes with empty values will be considered invalid.
state	NetmapStatus		Carries state of the NeoFS node.

Message NodeInfo.Attribute

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.

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.
• Subnet
  String ID of Node's storage subnet. There can be only one subnet served by the Storage Node.
• Locode
  Node's geographic location in UN/LOCODE format approximated to the nearest point defined in standard.
• Country
  Country code in ISO 3166-1_alpha-2 format. Calculated automatically from Locode attribute
• Region
  Country's administative subdivision where node is located. Calculated automatically from Locode attribute based on SubDiv field. Presented in ISO 3166-2 format.
• City
  City, town, village or rural area name where node is located written without diacritics . Calculated automatically from Locode attribute.

For detailed description of each well-known attribute please see the corresponding section in NeoFS Technical specification.

Field	Type	Label	Description
key	string		Key of the node attribute.
value	string		Value of the node attribute.
parents	string	repeated	Parent keys, if any. For example for City it could be Region and Country.

Message ShardInfo

Shard description.

Field	Type	Label	Description
shard_ID	bytes		ID of the shard.
metabase_path	string		Path to shard's metabase.
blobstor_path	string		Path to shard's blobstor.
writecache_path	string		Path to shard's write-cache, empty if disabled.
mode	ShardMode		Work mode of the shard.
errorCount	uint32		Amount of errors occured.
pilorama_path	string		Path to shard's pilorama storage.

Message Signature

Signature of some message.

Field	Type	Label	Description
key	bytes		Public key used for signing.
sign	bytes		Binary signature.

HealthStatus

Health status of the storage node application.

Name	Number	Description
HEALTH_STATUS_UNDEFINED	0	Undefined status, default value.
STARTING	1	Storage node application is starting.
READY	2	Storage node application is started and serves all services.
SHUTTING_DOWN	3	Storage node application is shutting down.

NetmapStatus

Status of the storage node in the NeoFS network map.

Name	Number	Description
STATUS_UNDEFINED	0	Undefined status, default value.
ONLINE	1	Node is online.
OFFLINE	2	Node is offline.
MAINTENANCE	3	Node is maintained by the owner.

ShardMode

Work mode of the shard.

Name	Number	Description
SHARD_MODE_UNDEFINED	0	Undefined mode, default value.
READ_WRITE	1	Read-write.
READ_ONLY	2	Read-only.
DEGRADED	3	Degraded.
DEGRADED_READ_ONLY	4	DegradedReadOnly.

Scalar Value Types

.proto Type	Notes	C++ Type	Java Type	Python Type
double		double	double	float
float		float	float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long
uint32	Uses variable-length encoding.	uint32	int	int/long
uint64	Uses variable-length encoding.	uint64	long	int/long
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long
sfixed32	Always four bytes.	int32	int	int
sfixed64	Always eight bytes.	int64	long	int/long
bool		bool	boolean	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str