@pulumi/pulumi 3.148.1-alpha.x1afa4dd → 3.148.1-alpha.x2b2a8cc

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pulumi/pulumi",
-    "version": "3.148.1-alpha.x1afa4dd",
+    "version": "3.148.1-alpha.x2b2a8cc",
     "description": "Pulumi's Node.js SDK",
     "license": "Apache-2.0",
     "repository": {

package/proto/language_grpc_pb.js

@@ -332,12 +332,13 @@ function deserialize_pulumirpc_RuntimeOptionsResponse(buffer_arg) {
 }
 
 
-// LanguageRuntime is the interface that the planning monitor uses to drive execution of an interpreter responsible
-// for confguring and creating resource objects.
+// The LanguageRuntime service defines a standard interface for [language hosts/runtimes](languages). At a high level, a
+// language runtime provides the ability to execute programs, install and query dependencies, and generate code for a
+// specific language.
 var LanguageRuntimeService = exports.LanguageRuntimeService = {
-  // `Handshake` is the first call made by the engine to a language host. It is used to pass the 
-// engine's address to the language host so that it may establish its own connections back,
-// and to establish protocol configuration that will be used to communicate between the two parties. 
+  // `Handshake` is the first call made by the engine to a language host. It is used to pass the engine's address to
+// the language host so that it may establish its own connections back, and to establish protocol configuration that
+// will be used to communicate between the two parties.
 handshake: {
     path: '/pulumirpc.LanguageRuntime/Handshake',
     requestStream: false,
@@ -349,7 +350,15 @@ handshake: {
     responseSerialize: serialize_pulumirpc_LanguageHandshakeResponse,
     responseDeserialize: deserialize_pulumirpc_LanguageHandshakeResponse,
   },
-  // GetRequiredPlugins computes the complete set of anticipated plugins required by a program.
+  // `GetRequiredPlugins` computes the complete set of anticipated [plugins](plugins) required by a Pulumi program.
+// Among other things, it is intended to be used to pre-install plugins before running a program with
+// [](pulumirpc.LanguageRuntime.Run), to avoid the need to install them on-demand in response to [resource
+// registrations](resource-registration) sent back from the running program to the engine.
+//
+// :::{important}
+// The use of `GetRequiredPlugins` is deprecated in favour of [](pulumirpc.LanguageRuntime.GetRequiredPackages),
+// which returns more granular information about which plugins are required by which packages.
+// :::
 getRequiredPlugins: {
     path: '/pulumirpc.LanguageRuntime/GetRequiredPlugins',
     requestStream: false,
@@ -361,7 +370,15 @@ getRequiredPlugins: {
     responseSerialize: serialize_pulumirpc_GetRequiredPluginsResponse,
     responseDeserialize: deserialize_pulumirpc_GetRequiredPluginsResponse,
   },
-  // GetRequiredPackages computes the complete set of anticipated packages required by a program.
+  // `GetRequiredPackages` computes the complete set of anticipated [packages](pulumirpc.PackageDependency) required
+// by a program. It is used to pre-install packages before running a program with [](pulumirpc.LanguageRuntime.Run),
+// to avoid the need to install them on-demand in response to [resource registrations](resource-registration) sent
+// back from the running program to the engine. Moreover, when importing resources into a stack, it is used to
+// determine which plugins are required to service the import of a given resource, since given the presence of
+// [parameterized providers](parameterized-providers), it is not in general true that a package name corresponds 1:1
+// with a plugin name. It replaces [](pulumirpc.LanguageRuntime.GetRequiredPlugins) in the face of [parameterized
+// providers](parameterized-providers), which as mentioned above can enable multiple instances of the same plugin to
+// provide multiple packages.
 getRequiredPackages: {
     path: '/pulumirpc.LanguageRuntime/GetRequiredPackages',
     requestStream: false,
@@ -373,7 +390,7 @@ getRequiredPackages: {
     responseSerialize: serialize_pulumirpc_GetRequiredPackagesResponse,
     responseDeserialize: deserialize_pulumirpc_GetRequiredPackagesResponse,
   },
-  // Run executes a program and returns its result.
+  // `Run` executes a Pulumi program, returning information about whether or not the program produced an error.
 run: {
     path: '/pulumirpc.LanguageRuntime/Run',
     requestStream: false,
@@ -385,7 +402,7 @@ run: {
     responseSerialize: serialize_pulumirpc_RunResponse,
     responseDeserialize: deserialize_pulumirpc_RunResponse,
   },
-  // GetPluginInfo returns generic information about this plugin, like its version.
+  // `GetPluginInfo` returns information about the [plugin](plugins) implementing this language runtime.
 getPluginInfo: {
     path: '/pulumirpc.LanguageRuntime/GetPluginInfo',
     requestStream: false,
@@ -397,7 +414,11 @@ getPluginInfo: {
     responseSerialize: serialize_pulumirpc_PluginInfo,
     responseDeserialize: deserialize_pulumirpc_PluginInfo,
   },
-  // InstallDependencies will install dependencies for the project, e.g. by running `npm install` for nodejs projects.
+  // `InstallDependencies` accepts a request specifying a Pulumi project and program that can be executed with
+// [](pulumirpc.LanguageRuntime.Run) and installs the dependencies for that program (e.g. by running `npm install`
+// for NodeJS, or `pip install` for Python). Since dependency installation could take a while, and callers may wish
+// to report on its progress, this method returns a stream of [](pulumirpc.InstallDependenciesResponse) messages
+// containing information about standard error and output.
 installDependencies: {
     path: '/pulumirpc.LanguageRuntime/InstallDependencies',
     requestStream: false,
@@ -409,7 +430,8 @@ installDependencies: {
     responseSerialize: serialize_pulumirpc_InstallDependenciesResponse,
     responseDeserialize: deserialize_pulumirpc_InstallDependenciesResponse,
   },
-  // RuntimeOptionsPrompts returns a list of additional prompts to ask during `pulumi new`.
+  // `RuntimeOptionsPrompts` accepts a request specifying a Pulumi project and returns a list of additional prompts to
+// ask during `pulumi new`.
 runtimeOptionsPrompts: {
     path: '/pulumirpc.LanguageRuntime/RuntimeOptionsPrompts',
     requestStream: false,
@@ -421,7 +443,7 @@ runtimeOptionsPrompts: {
     responseSerialize: serialize_pulumirpc_RuntimeOptionsResponse,
     responseDeserialize: deserialize_pulumirpc_RuntimeOptionsResponse,
   },
-  // About returns information about the runtime for this language.
+  // `About` returns information about the language runtime being used.
 about: {
     path: '/pulumirpc.LanguageRuntime/About',
     requestStream: false,
@@ -433,7 +455,8 @@ about: {
     responseSerialize: serialize_pulumirpc_AboutResponse,
     responseDeserialize: deserialize_pulumirpc_AboutResponse,
   },
-  // GetProgramDependencies returns the set of dependencies required by the program.
+  // `GetProgramDependencies` computes the set of language-level dependencies (e.g. NPM packages for NodeJS, or Maven
+// libraries for Java) required by a program.
 getProgramDependencies: {
     path: '/pulumirpc.LanguageRuntime/GetProgramDependencies',
     requestStream: false,
@@ -445,7 +468,11 @@ getProgramDependencies: {
     responseSerialize: serialize_pulumirpc_GetProgramDependenciesResponse,
     responseDeserialize: deserialize_pulumirpc_GetProgramDependenciesResponse,
   },
-  // RunPlugin executes a plugin program and returns its result asynchronously.
+  // `RunPlugin` is used to execute a program written in this host's language that implements a Pulumi
+// [plugin](plugins). It it is plugins what [](pulumirpc.LanguageRuntime.Run) is to programs. Since a plugin is not
+// expected to terminate until instructed/for a long time, this method returns a stream of
+// [](pulumirpc.RunPluginResponse) messages containing information about standard error and output, as well as the
+// exit code of the plugin when it does terminate.
 runPlugin: {
     path: '/pulumirpc.LanguageRuntime/RunPlugin',
     requestStream: false,
@@ -457,7 +484,11 @@ runPlugin: {
     responseSerialize: serialize_pulumirpc_RunPluginResponse,
     responseDeserialize: deserialize_pulumirpc_RunPluginResponse,
   },
-  // GenerateProgram generates a given PCL program into a program for this language.
+  // `GenerateProgram` generates code in this host's language that implements the given [PCL](pcl) program. Unlike
+// [](pulumirpc.LanguageRuntime.GenerateProject), this method *only* generates program code, and does not e.g.
+// generate a `package.json` for a NodeJS project that details how to run that code.
+// [](pulumirpc.LanguageRuntime.GenerateProject), this method underpins ["programgen"](programgen) and the main
+// functionality powering `pulumi convert`.
 generateProgram: {
     path: '/pulumirpc.LanguageRuntime/GenerateProgram',
     requestStream: false,
@@ -469,7 +500,12 @@ generateProgram: {
     responseSerialize: serialize_pulumirpc_GenerateProgramResponse,
     responseDeserialize: deserialize_pulumirpc_GenerateProgramResponse,
   },
-  // GenerateProject generates a given PCL program into a project for this language.
+  // `GenerateProject` generates code in this host's language that implements the given [PCL](pcl) program and wraps
+// it in some language-specific notion of a "project", where a project is a buildable or runnable artifact. In this
+// sense, `GenerateProject`'s output is a superset of that of [](pulumirpc.LanguageRuntime.GenerateProgram). For
+// instance, when generating a NodeJS project, this method might generate a corresponding `package.json` file, as
+// well as the relevant NodeJS program code. Along with [](pulumirpc.LanguageRuntime.GenerateProgram), this method
+// underpins ["programgen"](programgen) and the main functionality powering `pulumi convert`.
 generateProject: {
     path: '/pulumirpc.LanguageRuntime/GenerateProject',
     requestStream: false,
@@ -481,7 +517,8 @@ generateProject: {
     responseSerialize: serialize_pulumirpc_GenerateProjectResponse,
     responseDeserialize: deserialize_pulumirpc_GenerateProjectResponse,
   },
-  // GeneratePackage generates a given pulumi package into a package for this language.
+  // `GeneratePackage` generates code in this host's language that implements an [SDK](sdkgen) ("sdkgen") for the
+// given Pulumi package, as specified by a [schema](schema).
 generatePackage: {
     path: '/pulumirpc.LanguageRuntime/GeneratePackage',
     requestStream: false,
@@ -493,7 +530,11 @@ generatePackage: {
     responseSerialize: serialize_pulumirpc_GeneratePackageResponse,
     responseDeserialize: deserialize_pulumirpc_GeneratePackageResponse,
   },
-  // Pack packs a package into a language specific artifact.
+  // `Pack` accepts a request specifying a generated SDK package and packs it into a language-specific artifact. For
+// instance, in the case of Java, it might produce a JAR file from a list of `.java` sources; in the case of NodeJS,
+// a `.tgz` file might be produced from a list of `.js` sources; and so on. Presently, `Pack` is primarily used in
+// [language conformance tests](language-conformance-tests), though it is intended to be used more widely in future
+// to standardise e.g. provider publishing workflows.
 pack: {
     path: '/pulumirpc.LanguageRuntime/Pack',
     requestStream: false,

package/proto/resource_grpc_pb.js

@@ -294,7 +294,9 @@ registerStackInvokeTransform: {
     responseSerialize: serialize_google_protobuf_Empty,
     responseDeserialize: deserialize_google_protobuf_Empty,
   },
-  registerPackage: {
+  // Registers a package and allocates a packageRef. The same package can be registered multiple times in Pulumi.
+// Multiple requests are idempotent and guaranteed to return the same result.
+registerPackage: {
     path: '/pulumirpc.ResourceMonitor/RegisterPackage',
     requestStream: false,
     responseStream: false,

package/version.js

@@ -13,5 +13,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.version = "3.148.1-alpha.x1afa4dd";
+exports.version = "3.148.1-alpha.x2b2a8cc";
 //# sourceMappingURL=version.js.map