/*
Copyright 2023 The Kubernetes 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.
*/

// To regenerate api.pb.go run `hack/update-codegen.sh protobindings`

syntax = "proto3";

package v1alpha3;
option go_package = "k8s.io/kubelet/pkg/apis/dra/v1alpha3";

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "k8s.io/api/resource/v1alpha2/generated.proto";

option (gogoproto.goproto_stringer_all) = false;
option (gogoproto.stringer_all) =  true;
option (gogoproto.goproto_getters_all) = true;
option (gogoproto.marshaler_all) = true;
option (gogoproto.sizer_all) = true;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.goproto_unrecognized_all) = false;

service Node {
  // NodePrepareResources prepares several ResourceClaims
  // for use on the node. If an error is returned, the
  // response is ignored. Failures for individual claims
  // can be reported inside NodePrepareResourcesResponse.
  rpc NodePrepareResources (NodePrepareResourcesRequest)
    returns (NodePrepareResourcesResponse) {}

  // NodeUnprepareResources is the opposite of NodePrepareResources.
  // The same error handling rules apply,
  rpc NodeUnprepareResources (NodeUnprepareResourcesRequest)
    returns (NodeUnprepareResourcesResponse) {}

  // NodeListAndWatchResources returns a stream of NodeResourcesResponse objects.
  // At the start and whenever resource availability changes, the
  // plugin must send one such object with all information to the Kubelet.
  rpc NodeListAndWatchResources(NodeListAndWatchResourcesRequest)
    returns (stream NodeListAndWatchResourcesResponse) {}
}

message NodePrepareResourcesRequest {
     // The list of ResourceClaims that are to be prepared.
     repeated Claim claims = 1;
}

message NodePrepareResourcesResponse {
    // The ResourceClaims for which preparation was done
    // or attempted, with claim_uid as key.
    //
    // It is an error if some claim listed in NodePrepareResourcesRequest
    // does not get prepared. NodePrepareResources
    // will be called again for those that are missing.
    map<string, NodePrepareResourceResponse> claims = 1;
}

message NodePrepareResourceResponse {
    // These are the additional devices that kubelet must
    // make available via the container runtime. A resource
    // may have zero or more devices.
    repeated string cdi_devices = 1 [(gogoproto.customname) = "CDIDevices"];
    // If non-empty, preparing the ResourceClaim failed.
    // cdi_devices is ignored in that case.
    string error = 2;
}

message NodeUnprepareResourcesRequest {
    // The list of ResourceClaims that are to be unprepared.
    repeated Claim claims = 1;
}

message NodeUnprepareResourcesResponse {
    // The ResourceClaims for which preparation was reverted.
    // The same rules as for NodePrepareResourcesResponse.claims
    // apply.
    map<string, NodeUnprepareResourceResponse> claims = 1;
}

message NodeUnprepareResourceResponse {
    // If non-empty, unpreparing the ResourceClaim failed.
    string error = 1;
}

message NodeListAndWatchResourcesRequest {
}

message NodeListAndWatchResourcesResponse {
    repeated k8s.io.api.resource.v1alpha2.ResourceModel resources = 1;
}

message Claim {
    // The ResourceClaim namespace (ResourceClaim.meta.Namespace).
    // This field is REQUIRED.
    string namespace = 1;
    // The UID of the Resource claim (ResourceClaim.meta.UUID).
    // This field is REQUIRED.
    string uid = 2;
    // The name of the Resource claim (ResourceClaim.meta.Name)
    // This field is REQUIRED.
    string name = 3;
    // Resource handle (AllocationResult.ResourceHandles[*].Data)
    // This field is REQUIRED.
    string resource_handle = 4;
    // Structured parameter resource handle (AllocationResult.ResourceHandles[*].StructuredData).
    // This field is OPTIONAL. If present, it needs to be used
    // instead of resource_handle. It will only have a single entry.
    //
    // Using "repeated" instead of "optional" is a workaround for https://github.com/gogo/protobuf/issues/713.
    repeated k8s.io.api.resource.v1alpha2.StructuredResourceHandle structured_resource_handle = 5;
}
