pulumi/proto/pulumi/language.proto

// Copyright 2016-2023, Pulumi Corporation.
//
// 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";

import "pulumi/codegen/hcl.proto";
import "pulumi/plugin.proto";
import "google/protobuf/empty.proto";

package pulumirpc;

option go_package = "github.com/pulumi/pulumi/sdk/v3/proto/go;pulumirpc";

// LanguageRuntime is the interface that the planning monitor uses to drive execution of an interpreter responsible
// for confguring and creating resource objects.
service LanguageRuntime {
    // GetRequiredPlugins computes the complete set of anticipated plugins required by a program.
    rpc GetRequiredPlugins(GetRequiredPluginsRequest) returns (GetRequiredPluginsResponse) {}
    // Run executes a program and returns its result.
    rpc Run(RunRequest) returns (RunResponse) {}
    // GetPluginInfo returns generic information about this plugin, like its version.
    rpc GetPluginInfo(google.protobuf.Empty) returns (PluginInfo) {}

    // InstallDependencies will install dependencies for the project, e.g. by running `npm install` for nodejs projects.
    rpc InstallDependencies(InstallDependenciesRequest) returns (stream  InstallDependenciesResponse) {}

    // About returns information about the runtime for this language.
    rpc About(google.protobuf.Empty) returns (AboutResponse) {}

    // GetProgramDependencies returns the set of dependencies required by the program.
    rpc GetProgramDependencies(GetProgramDependenciesRequest) returns (GetProgramDependenciesResponse) {}

    // RunPlugin executes a plugin program and returns its result asynchronously.
    rpc RunPlugin(RunPluginRequest) returns (stream RunPluginResponse) {}

    // GenerateProgram generates a given PCL program into a program for this language.
    rpc GenerateProgram(GenerateProgramRequest) returns (GenerateProgramResponse) {}

    // GenerateProject generates a given PCL program into a project for this language.
    rpc GenerateProject(GenerateProjectRequest) returns (GenerateProjectResponse) {}

    // GeneratePackage generates a given pulumi package into a package for this language.
    rpc GeneratePackage(GeneratePackageRequest) returns (GeneratePackageResponse) {}
}

// AboutResponse returns runtime information about the language.
message AboutResponse {
    string executable = 1; // the primary executable for the runtime of this language.
    string version = 2; // the version of the runtime for this language.
    map<string, string> metadata = 3; // other information about this language.
}

message GetProgramDependenciesRequest {
    string project = 1; // the project name.
    string pwd = 2;     // the program's working directory.
    string program = 3; // the path to the program.
    bool transitiveDependencies = 4; // if transitive dependencies should be included in the result.
}

message DependencyInfo {
    string name = 1; // The name of the dependency.
    string version = 2; // The version of the dependency.
}

message GetProgramDependenciesResponse {
    repeated DependencyInfo dependencies = 1; // the dependencies of this program
}

message GetRequiredPluginsRequest {
    string project = 1; // the project name.
    string pwd = 2;     // the program's working directory.
    string program = 3; // the path to the program.
}

message GetRequiredPluginsResponse {
    repeated PluginDependency plugins = 1; // a list of plugins required by this program.
}

// RunRequest asks the interpreter to execute a program.
message RunRequest {
    string project = 1;             // the project name.
    string stack = 2;               // the name of the stack being deployed into.
    string pwd = 3;                 // the program's working directory.
    string program = 4;             // the path to the program to execute.
    repeated string args = 5;       // any arguments to pass to the program.
    map<string, string> config = 6; // the configuration variables to apply before running.
    bool dryRun = 7;                // true if we're only doing a dryrun (preview).
    int32 parallel = 8;             // the degree of parallelism for resource operations (<=1 for serial).
    string monitor_address = 9;     // the address for communicating back to the resource monitor.
    bool queryMode = 10;            // true if we're only doing a query.
    repeated string configSecretKeys = 11; // the configuration keys that have secret values.
    string organization = 12;       // the organization of the stack being deployed into.
}

// RunResponse is the response back from the interpreter/source back to the monitor.
message RunResponse {
    // An unhandled error if any occurred.
    string error = 1;

    // An error happened.  And it was reported to the user.  Work should stop immediately
    // with nothing further to print to the user.  This corresponds to a "result.Bail()"
    // value in the 'go' layer.
    bool bail = 2;
}

message InstallDependenciesRequest {
    string directory = 1; // the program's working directory.
    bool is_terminal = 2; // if we are running in a terminal and should use ANSI codes
}

message InstallDependenciesResponse {
    bytes stdout = 1; // a line of stdout text.
    bytes stderr = 2; // a line of stderr text.
}

message RunPluginRequest{
    string pwd = 1; // the program's working directory.
    string program = 2; // the path to the program to execute.
    repeated string args = 3; // any arguments to pass to the program.
    repeated string env = 4; // any environment variables to set as part of the program.
}

message RunPluginResponse {
    oneof output {
        bytes stdout = 1; // a line of stdout text.
        bytes stderr = 2; // a line of stderr text.
        int32 exitcode = 3; // the exit code of the provider.
    }
}

message GenerateProgramRequest {
    // the PCL source of the project.
    map<string, string> source = 1;
}

message GenerateProgramResponse {
    // any diagnostics from code generation.
    repeated pulumirpc.codegen.Diagnostic diagnostics = 1;
    // the generated program source code.
    map<string, bytes> source = 2;
}

message GenerateProjectRequest {
    // the directory to generate the project in.
    string directory = 1;
    // the JSON-encoded pulumi project file.
    string project = 2;
    // the PCL source of the project.
    map<string, string> source = 3;
}

message GenerateProjectResponse {
}

message GeneratePackageRequest {
    // the directory to generate the package in.
    string directory = 1;
    // the JSON-encoded schema.
    string schema = 2;
    // extra files to copy to the package output.
    map<string, bytes> extraFiles = 3;
}

message GeneratePackageResponse {
}