/*
	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 "github.com/containerd/containerd/api/types/platform.proto";
import "google/rpc/status.proto";
import "google/protobuf/empty.proto";
import weak "gogoproto/gogo.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);
}

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 [(gogoproto.nullable) = false];

	// 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 [(gogoproto.nullable) = false];
}

message ServerResponse {
	string uuid = 1 [(gogoproto.customname) = "UUID"];
}