Skip to content

Commit facc18e

Browse files
authored
Send a loader target to providers during handshake (#23645)
Add a schema loader service address to the provider handshake, mirroring the existing mapper target. The host already serves a workspace-scoped loader via `Host.Loader`; this threads its address through to providers as the `ProviderHandshakeRequest.LoaderTarget` field so providers can load the schemas of other Pulumi packages the same way the engine does. An end-to-end test boots a real provider, confirms it receives a usable loader target at handshake time, and verifies the target stays usable for ordinary resource operations by loading a schema back through a `Create`.
1 parent 8cb5331 commit facc18e

12 files changed

Lines changed: 438 additions & 131 deletions

File tree

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
component: engine
2+
kind: feat
3+
body: Send the address of a schema loader service to resource providers as part of the provider handshake
4+
time: 2026-06-18T00:00:00+00:00
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
// Copyright 2026, Pulumi Corporation.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package schema
16+
17+
import (
18+
"context"
19+
"os"
20+
"os/exec"
21+
"path/filepath"
22+
"runtime"
23+
"testing"
24+
25+
"github.com/stretchr/testify/assert"
26+
"github.com/stretchr/testify/require"
27+
28+
pkghost "github.com/pulumi/pulumi/pkg/v3/host"
29+
"github.com/pulumi/pulumi/sdk/v3/go/common/apitype"
30+
"github.com/pulumi/pulumi/sdk/v3/go/common/env"
31+
"github.com/pulumi/pulumi/sdk/v3/go/common/resource"
32+
"github.com/pulumi/pulumi/sdk/v3/go/common/resource/plugin"
33+
"github.com/pulumi/pulumi/sdk/v3/go/common/testing/diagtest"
34+
"github.com/pulumi/pulumi/sdk/v3/go/common/tokens"
35+
"github.com/pulumi/pulumi/sdk/v3/go/common/workspace"
36+
)
37+
38+
// TestLoaderServerFromContext_RealProvider verifies the full loader handshake loop against a real provider binary,
39+
// and that the loader target stays usable for ordinary resource operations rather than just at handshake time:
40+
//
41+
// 1. The host boots the test provider and sends it a loader target as part of the handshake.
42+
// 2. A Create on the provider dials that target and asks the engine's loader for the "loadtest" schema.
43+
// 3. The engine's loader boots a second instance of the same provider and retrieves the schema it serves via
44+
// GetSchema, which the first instance returns as the created resource's state.
45+
//
46+
// Uses t.Setenv, so it cannot be parallel.
47+
func TestLoaderServerFromContext_RealProvider(t *testing.T) {
48+
// Build the test provider into the plugin layout of a fake PULUMI_HOME, where both the host's plugin loader and
49+
// the schema loader's plugin resolution will find it.
50+
home := t.TempDir()
51+
binName := "pulumi-resource-loadtest"
52+
if runtime.GOOS == "windows" {
53+
binName += ".exe"
54+
}
55+
pluginDir := filepath.Join(home, "plugins", "resource-loadtest-v1.0.0")
56+
require.NoError(t, os.MkdirAll(pluginDir, 0o755))
57+
58+
build := exec.Command("go", "build", "-o", filepath.Join(pluginDir, binName), "./testdata/loader-provider")
59+
build.Env = append(os.Environ(), "CGO_ENABLED=0")
60+
out, err := build.CombinedOutput()
61+
require.NoError(t, err, "building test provider: %s", out)
62+
63+
t.Setenv("PULUMI_HOME", home)
64+
65+
sink := diagtest.LogSink(t)
66+
pluginHost, err := pkghost.New(context.WithoutCancel(t.Context()), sink, sink, nil, nil,
67+
NewLoaderServerFromContext, nil)
68+
require.NoError(t, err)
69+
defer func() { require.NoError(t, pluginHost.Close()) }()
70+
pctx, err := plugin.NewContext(t.Context(), sink, sink, pluginHost, nil, t.TempDir(), nil, false, nil)
71+
require.NoError(t, err)
72+
defer pctx.Close()
73+
74+
p, err := pctx.Host.Provider(pctx, workspace.PluginDescriptor{
75+
Name: "loadtest",
76+
Kind: apitype.ResourcePlugin,
77+
}, env.Global())
78+
require.NoError(t, err)
79+
80+
typ := tokens.Type("pulumi:providers:loadtest")
81+
_, err = p.Configure(t.Context(), plugin.ConfigureRequest{Type: &typ})
82+
require.NoError(t, err)
83+
84+
res, err := p.Create(t.Context(), plugin.CreateRequest{
85+
URN: resource.NewURN("test", "test", "", "loadtest:index:Res", "res"),
86+
Properties: resource.PropertyMap{},
87+
})
88+
require.NoError(t, err)
89+
assert.Equal(t, resource.PropertyMap{
90+
"schema": resource.NewProperty(`{"name":"loadtest","version":"1.0.0"}`),
91+
}, res.Properties)
92+
}
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
// Copyright 2026, Pulumi Corporation.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// loader-provider is a test resource provider used to verify that the engine sends a working loader target as part
16+
// of the provider handshake, and that the loader stays usable across the provider's lifecycle. It plays both sides
17+
// of the loading flow: it serves its own schema via GetSchema, and its Create method dials the loader service
18+
// received during the handshake to load that same schema back.
19+
package main
20+
21+
import (
22+
"context"
23+
"fmt"
24+
"os"
25+
26+
"google.golang.org/grpc"
27+
"google.golang.org/grpc/credentials/insecure"
28+
"google.golang.org/protobuf/types/known/emptypb"
29+
"google.golang.org/protobuf/types/known/structpb"
30+
31+
"github.com/pulumi/pulumi/sdk/v3/go/common/util/rpcutil"
32+
pulumirpc "github.com/pulumi/pulumi/sdk/v3/proto/go"
33+
"github.com/pulumi/pulumi/sdk/v3/proto/go/codegen"
34+
)
35+
36+
// schemaJSON is the schema this provider both advertises via GetSchema and loads back through the handshake loader.
37+
// It carries a top-level version so the loader returns it verbatim rather than defaulting the version.
38+
const schemaJSON = `{"name":"loadtest","version":"1.0.0"}`
39+
40+
type loaderProvider struct {
41+
pulumirpc.UnimplementedResourceProviderServer
42+
43+
loader codegen.LoaderClient
44+
}
45+
46+
func (p *loaderProvider) Handshake(
47+
ctx context.Context, req *pulumirpc.ProviderHandshakeRequest,
48+
) (*pulumirpc.ProviderHandshakeResponse, error) {
49+
if req.LoaderTarget == nil || *req.LoaderTarget == "" {
50+
return nil, fmt.Errorf("no loader target received during handshake")
51+
}
52+
53+
conn, err := grpc.NewClient(*req.LoaderTarget,
54+
grpc.WithTransportCredentials(insecure.NewCredentials()))
55+
if err != nil {
56+
return nil, fmt.Errorf("dial loader at %v: %w", *req.LoaderTarget, err)
57+
}
58+
59+
p.loader = codegen.NewLoaderClient(conn)
60+
return &pulumirpc.ProviderHandshakeResponse{}, nil
61+
}
62+
63+
func (p *loaderProvider) GetPluginInfo(ctx context.Context, req *emptypb.Empty) (*pulumirpc.PluginInfo, error) {
64+
return &pulumirpc.PluginInfo{Version: "1.0.0"}, nil
65+
}
66+
67+
func (p *loaderProvider) Configure(
68+
ctx context.Context, req *pulumirpc.ConfigureRequest,
69+
) (*pulumirpc.ConfigureResponse, error) {
70+
return &pulumirpc.ConfigureResponse{}, nil
71+
}
72+
73+
func (p *loaderProvider) GetSchema(
74+
ctx context.Context, req *pulumirpc.GetSchemaRequest,
75+
) (*pulumirpc.GetSchemaResponse, error) {
76+
return &pulumirpc.GetSchemaResponse{Schema: schemaJSON}, nil
77+
}
78+
79+
func (p *loaderProvider) Create(
80+
ctx context.Context, req *pulumirpc.CreateRequest,
81+
) (*pulumirpc.CreateResponse, error) {
82+
res, err := p.loader.GetSchema(ctx, &codegen.GetSchemaRequest{Package: "loadtest", Version: "1.0.0"})
83+
if err != nil {
84+
return nil, fmt.Errorf("load schema: %w", err)
85+
}
86+
87+
props, err := structpb.NewStruct(map[string]any{"schema": string(res.Schema)})
88+
if err != nil {
89+
return nil, err
90+
}
91+
return &pulumirpc.CreateResponse{Id: "created", Properties: props}, nil
92+
}
93+
94+
func main() {
95+
handle, err := rpcutil.ServeWithOptions(rpcutil.ServeOptions{
96+
Init: func(srv *grpc.Server) error {
97+
pulumirpc.RegisterResourceProviderServer(srv, &loaderProvider{})
98+
return nil
99+
},
100+
})
101+
if err != nil {
102+
fmt.Printf("fatal: %v\n", err)
103+
os.Exit(1)
104+
}
105+
106+
fmt.Printf("%d\n", handle.Port)
107+
108+
if err := <-handle.Done; err != nil {
109+
fmt.Printf("fatal: %v\n", err)
110+
os.Exit(1)
111+
}
112+
}

‎proto/pulumi/provider.proto‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,10 @@ message ProviderHandshakeRequest {
278278
// The target of a [](codegen.Mapper) service the provider can use to retrieve mappings from other ecosystems to
279279
// Pulumi. May be empty on older engines.
280280
optional string mapper_target = 8;
281+
282+
// The target of a [](codegen.Loader) service the provider can use to load the schemas of other Pulumi packages.
283+
// May be empty on older engines.
284+
optional string loader_target = 9;
281285
}
282286

283287
// `ProviderHandshakeResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Handshake) call.

‎sdk/go/common/resource/plugin/provider.go‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,10 @@ type ProviderHandshakeRequest struct {
7171
// The target of a codegen.Mapper service the provider can use to retrieve mappings from other ecosystems to
7272
// Pulumi. May be nil on older engines.
7373
MapperTarget *string
74+
75+
// The target of a codegen.Loader service the provider can use to load the schemas of other Pulumi packages.
76+
// May be nil on older engines.
77+
LoaderTarget *string
7478
}
7579

7680
// The type of responses sent as part of a Handshake call.

‎sdk/go/common/resource/plugin/provider_plugin.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,7 @@ func NewProvider(host Host, ctx *Context, spec workspace.PluginDescriptor,
187187

188188
prefix := fmt.Sprintf("%v (resource)", pkg)
189189
mapperAddr := mapperTarget(ctx)
190+
loaderAddr := loaderTarget(ctx)
190191

191192
if attachPort != nil {
192193
port := *attachPort
@@ -204,6 +205,7 @@ func NewProvider(host Host, ctx *Context, spec workspace.PluginDescriptor,
204205
SupportsRefreshBeforeUpdate: supportsRefreshBeforeUpdate,
205206
InvokeWithPreview: true,
206207
MapperTarget: mapperAddr,
208+
LoaderTarget: loaderAddr,
207209
}
208210
return handshake(ctx, bin, prefix, conn, req)
209211
}
@@ -268,6 +270,7 @@ func NewProvider(host Host, ctx *Context, spec workspace.PluginDescriptor,
268270
SupportsRefreshBeforeUpdate: supportsRefreshBeforeUpdate,
269271
InvokeWithPreview: true,
270272
MapperTarget: mapperAddr,
273+
LoaderTarget: loaderAddr,
271274
}
272275
return handshake(ctx, bin, prefix, conn, req)
273276
}
@@ -331,6 +334,15 @@ func mapperTarget(ctx *Context) *string {
331334
return nil
332335
}
333336

337+
// loaderTarget returns the context's loader address as an optional handshake field, nil when the context has no
338+
// loader service.
339+
func loaderTarget(ctx *Context) *string {
340+
if addr := ctx.LoaderAddr(); addr != "" {
341+
return &addr
342+
}
343+
return nil
344+
}
345+
334346
func handshake(
335347
ctx context.Context,
336348
bin string,
@@ -348,6 +360,7 @@ func handshake(
348360
SupportsRefreshBeforeUpdate: req.SupportsRefreshBeforeUpdate,
349361
InvokeWithPreview: req.InvokeWithPreview,
350362
MapperTarget: req.MapperTarget,
363+
LoaderTarget: req.LoaderTarget,
351364
})
352365
if err != nil {
353366
status, ok := status.FromError(err)
@@ -395,6 +408,7 @@ func providerPluginDialOptions(ctx *Context, pkg tokens.Package, path string) []
395408
// NewProviderFromPath creates a new provider by loading the plugin binary located at `path`.
396409
func NewProviderFromPath(host Host, ctx *Context, path string) (Provider, error) {
397410
mapperAddr := mapperTarget(ctx)
411+
loaderAddr := loaderTarget(ctx)
398412
handshake := func(
399413
ctx context.Context, bin string, prefix string, conn *grpc.ClientConn,
400414
) (*ProviderHandshakeResponse, error) {
@@ -408,6 +422,7 @@ func NewProviderFromPath(host Host, ctx *Context, path string) (Provider, error)
408422
SupportsRefreshBeforeUpdate: supportsRefreshBeforeUpdate,
409423
InvokeWithPreview: true,
410424
MapperTarget: mapperAddr,
425+
LoaderTarget: loaderAddr,
411426
}
412427
return handshake(ctx, bin, prefix, conn, req)
413428
}
@@ -536,6 +551,7 @@ func (p *provider) Handshake(ctx context.Context, req ProviderHandshakeRequest)
536551
SupportsRefreshBeforeUpdate: req.SupportsRefreshBeforeUpdate,
537552
InvokeWithPreview: req.InvokeWithPreview,
538553
MapperTarget: req.MapperTarget,
554+
LoaderTarget: req.LoaderTarget,
539555
})
540556
if err != nil {
541557
return nil, err

‎sdk/go/common/resource/plugin/provider_server.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ func (p *providerServer) Handshake(
153153
SupportsRefreshBeforeUpdate: req.SupportsRefreshBeforeUpdate,
154154
InvokeWithPreview: req.InvokeWithPreview,
155155
MapperTarget: req.MapperTarget,
156+
LoaderTarget: req.LoaderTarget,
156157
})
157158
if err != nil {
158159
return nil, err

‎sdk/nodejs/proto/provider_pb.d.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,11 @@ export class ProviderHandshakeRequest extends jspb.Message {
3737
getMapperTarget(): string | undefined;
3838
setMapperTarget(value: string): ProviderHandshakeRequest;
3939

40+
hasLoaderTarget(): boolean;
41+
clearLoaderTarget(): void;
42+
getLoaderTarget(): string | undefined;
43+
setLoaderTarget(value: string): ProviderHandshakeRequest;
44+
4045
serializeBinary(): Uint8Array;
4146
toObject(includeInstance?: boolean): ProviderHandshakeRequest.AsObject;
4247
static toObject(includeInstance: boolean, msg: ProviderHandshakeRequest): ProviderHandshakeRequest.AsObject;
@@ -57,6 +62,7 @@ export namespace ProviderHandshakeRequest {
5762
supportsRefreshBeforeUpdate: boolean,
5863
invokeWithPreview: boolean,
5964
mapperTarget?: string,
65+
loaderTarget?: string,
6066
}
6167
}
6268

0 commit comments

Comments
 (0)