frostfs-api/netmap/service.proto

syntax = "proto3";

package neo.fs.v2.netmap;

option go_package = "github.com/nspcc-dev/neofs-api-go/v2/netmap/grpc;netmap";
option csharp_namespace = "Neo.FileStorage.API.Netmap";

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

// `NetmapService` provides methods to work with `Network Map` and the information
// required to build it. The resulting `Network Map` is stored in sidechain
// `Netmap` smart contract, while related information can be obtained from other
// 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;

}