pulumi/sdk/proto/provider.proto

// Licensed to Pulumi Corporation ("Pulumi") under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// Pulumi licenses this file to You 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";

import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";

package lumirpc;

// TODO: figure out "transactionality" and possibly "tainting".

// ResourceProvider is a service that understands how to create, read, update, or delete resources for types defined
// within a single MuPackage.  It is driven by the overall Mu toolchain in response to blueprints and graphs.
service ResourceProvider {
    // Check validates that the given property bag is valid for a resource of the given type.
    rpc Check(CheckRequest) returns (CheckResponse) {}
    // Name names a given resource.  Sometimes this will be assigned by a developer, and so the provider
    // simply fetches it from the property bag; other times, the provider will assign this based on its own algorithm.
    // In any case, resources with the same name must be safe to use interchangeably with one another.
    rpc Name(NameRequest) returns (NameResponse) {}
    // Create allocates a new instance of the provided resource and returns its unique ID afterwards.  (The input ID
    // must be blank.)  If this call fails, the resource must not have been created (i.e., it is "transacational").
    rpc Create(CreateRequest) returns (CreateResponse) {}
    // Get reads the instance state identified by ID, returning a populated resource object, or an error if not found.
    rpc Get(GetRequest) returns (GetResponse) {}
    // InspectChange checks what impacts a hypothetical update will have on the resource's properties.
    rpc InspectChange(InspectChangeRequest) returns (InspectChangeResponse) {}
    // Update updates an existing resource with new values.
    rpc Update(UpdateRequest) returns (google.protobuf.Empty) {}
    // Delete tears down an existing resource with the given ID.  If it fails, the resource is assumed to still exist.
    rpc Delete(DeleteRequest) returns (google.protobuf.Empty) {}
}

message CheckRequest {
    string type = 1;                       // the type token of the resource.
    google.protobuf.Struct properties = 2; // the full properties to use for validation.
    map<string, bool> unknowns = 3;        // the optional set of properties whose values are unknown.
}

message CheckResponse {
    repeated CheckFailure failures = 1; // the name of the resource.
}

message CheckFailure {
    string property = 1; // the property that failed validation.
    string reason = 2;   // the reason that the property failed validation.
}

message NameRequest {
    string type = 1;                       // the type token of the resource.
    google.protobuf.Struct properties = 2; // the full properties to use for name creation.
    map<string, bool> unknowns = 3;        // the optional set of properties whose values are unknown.
}

message NameResponse {
    string name = 1; // the name of the resource.
}

message CreateRequest {
    string type = 1;                       // the type token of the resource.
    google.protobuf.Struct properties = 2; // the properties to set during creation.
}

message CreateResponse {
    string id = 1;                      // the ID of the resource created.
    google.protobuf.Struct outputs = 2; // any properties populated at creation time.
}

message GetRequest {
    string id = 1;   // the ID of the resource to read.
    string type = 2; // the type token of the resource.
}

message GetResponse {
    google.protobuf.Struct properties = 1; // the properties read from the resource.
}

message InspectChangeRequest {
    string id = 1;                   // the ID of the resource to inspect.
    string type = 2;                 // the type token of the resource to inspect.
    google.protobuf.Struct olds = 3; // the old values of properties to inspect.
    google.protobuf.Struct news = 4; // the new values of properties to inspect.
    map<string, bool> unknowns = 5;  // the optional set of properties whose values are unknown.
}

message InspectChangeResponse {
    repeated string replaces = 1;       // if this update requires a replacement, the set of properties triggering it.
    google.protobuf.Struct changes = 2; // the set of properties that will be changed (but don't require a replacement).
}

message UpdateRequest {
    string id = 1;                   // the ID of the resource to update.
    string type = 2;                 // the type token of the resource to update.
    google.protobuf.Struct olds = 3; // the old values of properties to update.
    google.protobuf.Struct news = 4; // the new values of properties to update.
}

message DeleteRequest {
    string id = 1;   // the ID of the resource to delete.
    string type = 2; // the type token of the resource to update.
}