syntax = "proto3";

package containerd.v1;

import "gogoproto/gogo.proto";
import "google/protobuf/empty.proto";
import "github.com/containerd/containerd/api/types/mount/mount.proto";
import "github.com/containerd/containerd/api/types/descriptor/descriptor.proto";

// Images is a service that allows one to register images with containerd.
//
// In containerd, an image is merely the mapping of a name to a content root,
// described by a descriptor. The behavior and state of image is purely
// dictated by the type of the descriptor.
//
// From the perspective of this service, these references are mostly shallow,
// in that the existence of the required content won't be validated until
// required by consuming services.
//
// As such, this can really be considered a "metadata service".
service Images {
	// Get returns an image by name.
	rpc Get(GetRequest) returns (GetResponse);

	// Put assigns the name to a given target image based on the provided
	// image.
	rpc Put(PutRequest) returns (google.protobuf.Empty);

	// List returns a list of all images known to containerd.
	rpc List(ListRequest) returns (ListResponse);

	// Delete deletes the image by name.
	rpc Delete(DeleteRequest) returns (google.protobuf.Empty);
}

message Image {
	string name = 1;
	types.Descriptor target = 2 [(gogoproto.nullable) = false];
}

message GetRequest {
	string name = 1;

	// TODO(stevvooe): Consider that we may want to have multiple images under
	// the same name or multiple names for the same image. This mapping could
	// be truly many to many but we'll need a way to identify an entry.
	//
	// For now, we consider it unique but an intermediary index could be
	// created to allow for a dispatch of images.
}

message GetResponse {
	Image image = 1;
}

message PutRequest {
	Image image = 1 [(gogoproto.nullable) = false];
}

message ListRequest {
	// TODO(stevvooe): empty for now, need to ad filtration
	// Some common use cases we might consider:
	//
	// 1. Select by multiple names.
	// 2. Select by platform.
	// 3. Select by annotations.
}

message ListResponse {
	repeated Image images = 1 [(gogoproto.nullable) = false];

	// TODO(stevvooe): Add pagination.
}

message DeleteRequest {
	string name = 1;
}