// Copyright IBM Corp. 2015, 2025
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";
package hashicorp.nomad.plugins.base.proto;
option go_package = "proto";

import "plugins/shared/hclspec/hcl_spec.proto";

// BasePlugin is the methods that all Nomad plugins must support.
service BasePlugin {

  // PluginInfo describes the type and version of a plugin.
  rpc PluginInfo(PluginInfoRequest) returns (PluginInfoResponse) {}

  // ConfigSchema returns the schema for parsing the plugins configuration.
  rpc ConfigSchema(ConfigSchemaRequest) returns (ConfigSchemaResponse) {}

  // SetConfig is used to set the configuration.
  rpc SetConfig(SetConfigRequest) returns (SetConfigResponse) {}
}

// PluginType enumerates the type of plugins Nomad supports
enum PluginType {
  UNKNOWN = 0;
  DRIVER = 2;
  DEVICE = 3;
}

// PluginInfoRequest is used to request the plugins basic information.
message PluginInfoRequest {}

// PluginInfoResponse returns basic information about the plugin such
// that Nomad can decide whether to load the plugin or not.
message PluginInfoResponse {
  // type indicates what type of plugin this is.
  PluginType type = 1;

  // plugin_api_versions indicates the versions of the Nomad Plugin API
  // this plugin supports.
  repeated string plugin_api_versions = 2;

  // plugin_version is the semver version of this individual plugin.
  // This is divorce from Nomad’s development and versioning.
  string plugin_version = 3;

  // name is the name of the plugin
  string name = 4;
}

// ConfigSchemaRequest is used to request the configurations schema.
message ConfigSchemaRequest {}

// ConfigSchemaResponse returns the plugins configuration schema.
message ConfigSchemaResponse {
  // spec is the plugins configuration schema
  hashicorp.nomad.plugins.shared.hclspec.Spec spec = 1;
}

// SetConfigRequest is used to set the configuration
message SetConfigRequest {
  // msgpack_config is the configuration encoded as MessagePack.
  bytes msgpack_config = 1;

  // nomad_config is the nomad client configuration sent to all plugins.
  NomadConfig nomad_config = 2;

  // plugin_api_version is the api version to use.
  string plugin_api_version = 3;
}

// NomadConfig is the client configuration sent to all plugins
message NomadConfig {
    // driver specific configuration sent to all plugins
    NomadDriverConfig driver = 1;
}

// NomadDriverConfig is the driver specific client configuration sent to all
// driver plugins
message NomadDriverConfig {
    // ClientMaxPort is the upper range of the ports that the client uses for
    // communicating with plugin subsystems over loopback
    // buf:lint:ignore FIELD_LOWER_SNAKE_CASE
    uint32 ClientMaxPort = 1;

    // ClientMinPort is the lower range of the ports that the client uses for
    // communicating with plugin subsystems over loopback
    // buf:lint:ignore FIELD_LOWER_SNAKE_CASE
    uint32 ClientMinPort = 2;

    // Topology is the complex hardware topology detected by the client
    // combined with client configuration.
    ClientTopology Topology = 3;
}

// numalib/Topology
message ClientTopology {
    repeated uint32 node_ids = 1;
    ClientTopologySLIT distances = 2;
    repeated ClientTopologyCore cores = 3;
    uint64 override_total_compute = 4;
    uint64 override_withold_compute = 5;
}

// numalib/SLIT
message ClientTopologySLIT {
    // dimension is the row and column size of the slit matrix
    uint32 dimension = 1;

    // values is the flattened matrix of slit values
    repeated uint32 values = 2 [packed=true];
}

enum CoreGrade {
  Performance = 0;
  Efficiency = 1;
}

// numalib/Core
message ClientTopologyCore {
  uint32 socket_id = 1;
  uint32 node_id = 2;
  uint32 core_id = 3;
  CoreGrade core_grade = 4;
  bool disable = 5;
  uint64 base_speed = 6;
  uint64 max_speed = 7;
  uint64 guess_speed = 8;
}

// SetConfigResponse is used to respond to setting the configuration
message SetConfigResponse {}
