frostfs-api/state/service.proto

syntax = "proto3";
package state;
option go_package = "github.com/nspcc-dev/neofs-api-go/state";
option csharp_namespace = "NeoFS.API.State";

import "service/meta.proto";
import "service/verify.proto";
import "bootstrap/types.proto";
import "github.com/gogo/protobuf/gogoproto/gogo.proto";

option (gogoproto.stable_marshaler_all) = true;

// Status service provides node's healthcheck and status info.
// TODO: decide how to describe auth and were contains permissions.
service Status {
    // Netmap request allows to receive current [bootstrap.SpreadMap](bootstrap.md#bootstrap.SpreadMap)
    rpc Netmap(NetmapRequest) returns (bootstrap.SpreadMap);
    // Metrics request allows to receive metrics in prometheus format
    rpc Metrics(MetricsRequest) returns (MetricsResponse);
    // HealthCheck request allows to check health status of the node.
    // If node unhealthy field Status would contains detailed info.
    rpc HealthCheck(HealthRequest) returns (HealthResponse);
    // DumpConfig request allows dumping settings for the current node.
    // To permit access, used server config options.
    // The request should be signed.
    rpc DumpConfig(DumpRequest) returns (DumpResponse);
    // DumpVars returns debug variables for the current node.
    // To permit access, used server config options.
    // The request should be signed.
    rpc DumpVars(DumpVarsRequest) returns (DumpVarsResponse);
    // ChangeState allows to change current node state of node.
    // To permit access, used server config options.
    // The request should be signed.
    rpc ChangeState(ChangeStateRequest) returns (ChangeStateResponse);
}

// NetmapRequest message to request current node netmap
message NetmapRequest {
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// MetricsRequest message to request node metrics
message MetricsRequest {
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// MetricsResponse contains [][]byte,
// every []byte is marshaled MetricFamily proto message
// from github.com/prometheus/client_model/metrics.proto
message MetricsResponse {
    repeated bytes Metrics = 1;
}

// HealthRequest message to check current state
message HealthRequest {
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// HealthResponse message with current state
message HealthResponse {
    // Healthy is true when node alive and healthy
    bool Healthy  = 1;
    // Status contains detailed information about health status
    string Status = 2;
}

// DumpRequest message to fetch current server config.
message DumpRequest {
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// DumpResponse message contains current server config.
// Config stored in JSON encoded into slice of bytes.
message DumpResponse {
    bytes Config = 1;
}

// DumpVarsRequest message to fetch current server debug variables.
message DumpVarsRequest {
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// DumpVarsResponse message contains current server debug variables.
// Variables stored in JSON encoded into slice of bytes.
message DumpVarsResponse {
    bytes Variables = 1;
}

// ChangeStateRequest contains a new state of node.
message ChangeStateRequest {
    enum State {
        // Unknown is default value. Does nothing.
        Unknown = 0;
        // Online used when need to set node to the online state.
        Online = 1;
        // Offline used when need to set node to the offline state.
        Offline = 2;
    }

    // State is a new state of node.
    State state = 1;
    // RequestMetaHeader contains information about request meta headers (should be embedded into message)
    service.RequestMetaHeader Meta           = 98 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
    // RequestVerificationHeader is a set of signatures of every NeoFS Node that processed request (should be embedded into message)
    service.RequestVerificationHeader Verify = 99 [(gogoproto.embed) = true, (gogoproto.nullable) = false];
}

// ChangeStateResponse is an empty response, that returns when RPC invoked without errors.
message ChangeStateResponse {}