/*
   Copyright The containerd Authors.

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
*/

syntax = "proto3";

package containerd.services.introspection.v1;

import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";
import "types/introspection.proto";
import "types/platform.proto";

option go_package = "github.com/containerd/containerd/api/services/introspection/v1;introspection";

service Introspection {
  // Plugins returns a list of plugins in containerd.
  //
  // Clients can use this to detect features and capabilities when using
  // containerd.
  rpc Plugins(PluginsRequest) returns (PluginsResponse);
  // Server returns information about the containerd server
  rpc Server(google.protobuf.Empty) returns (ServerResponse);
  // PluginInfo returns information directly from a plugin if the plugin supports it
  rpc PluginInfo(PluginInfoRequest) returns (PluginInfoResponse);
}

message Plugin {
  // Type defines the type of plugin.
  //
  // See package plugin for a list of possible values. Non core plugins may
  // define their own values during registration.
  string type = 1;

  // ID identifies the plugin uniquely in the system.
  string id = 2;

  // Requires lists the plugin types required by this plugin.
  repeated string requires = 3;

  // Platforms enumerates the platforms this plugin will support.
  //
  // If values are provided here, the plugin will only be operable under the
  // provided platforms.
  //
  // If this is empty, the plugin will work across all platforms.
  //
  // If the plugin prefers certain platforms over others, they should be
  // listed from most to least preferred.
  repeated types.Platform platforms = 4;

  // Exports allows plugins to provide values about state or configuration to
  // interested parties.
  //
  // One example is exposing the configured path of a snapshotter plugin.
  map<string, string> exports = 5;

  // Capabilities allows plugins to communicate feature switches to allow
  // clients to detect features that may not be on be default or may be
  // different from version to version.
  //
  // Use this sparingly.
  repeated string capabilities = 6;

  // InitErr will be set if the plugin fails initialization.
  //
  // This means the plugin may have been registered but a non-terminal error
  // was encountered during initialization.
  //
  // Plugins that have this value set cannot be used.
  google.rpc.Status init_err = 7;
}

message PluginsRequest {
  // Filters contains one or more filters using the syntax defined in the
  // containerd filter package.
  //
  // The returned result will be those that match any of the provided
  // filters. Expanded, plugins that match the following will be
  // returned:
  //
  //	filters[0] or filters[1] or ... or filters[n-1] or filters[n]
  //
  // If filters is zero-length or nil, all items will be returned.
  repeated string filters = 1;
}

message PluginsResponse {
  repeated Plugin plugins = 1;
}

message ServerResponse {
  string uuid = 1;
  uint64 pid = 2;
  uint64 pidns = 3; // PID namespace, such as 4026531836
  repeated DeprecationWarning deprecations = 4;
}

message DeprecationWarning {
  string id = 1;
  string message = 2;
  google.protobuf.Timestamp last_occurrence = 3;
}

message PluginInfoRequest {
  string type = 1;
  string id = 2;

  // Options may be used to request extra dynamic information from
  // a plugin.
  // This object is determined by the plugin and the plugin may return
  // NotImplemented or InvalidArgument if it is not supported
  google.protobuf.Any options = 3;
}

message PluginInfoResponse {
  Plugin plugin = 1;
  google.protobuf.Any extra = 2;
}
