frostfs-api/netmap/service.proto

syntax = "proto3";

package frost.fs.netmap;

import "netmap/types.proto";
import "refs/types.proto";
import "session/types.proto";

// `NetmapService` provides methods to work with `Network Map` and the
// information required to build it. The resulting `Network Map` is stored in
// sidechain `Netmap` smart contract, while related information can be obtained
// from other FrostFS nodes.
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 FrostFS 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 FrostFS 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.
  frost.fs.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.
  frost.fs.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 FrostFS API version in use
    frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.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.
  frost.fs.session.ResponseVerificationHeader verify_header = 3;
}