Add rawsetenv message type for provider plugins

Providers can now send rawsetenv messages to inject environment
variables into dependent services without the automatic service name
prefix. This enables use cases where applications require exact
variable names that cannot be altered.

Closes #13727

Signed-off-by: Yohta Kimura <38206553+rajyan@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/examples/provider.go

@@ -96,6 +96,7 @@ func up(options options, args []string) {
 		fmt.Printf(`{ "type": "info", "message": "Processing ... %d%%" }%s`, i*100/options.size, lineSeparator)
 	}
 	fmt.Printf(`{ "type": "setenv", "message": "URL=https://magic.cloud/%s" }%s`, servicename, lineSeparator)
+	fmt.Printf(`{ "type": "rawsetenv", "message": "CLOUD_REGION=us-east-1" }%s`, lineSeparator)
 }
 
 func down(_ *cobra.Command, _ []string) {

docs/extension.md

@@ -56,7 +56,8 @@ JSON messages MUST include a `type` and a `message` attribute.
 `type` can be either:
 - `info`: Reports status updates to the user. Compose will render message as the service state in the progress UI
 - `error`: Lets the user know something went wrong with details about the error. Compose will render the message as the reason for the service failure.
-- `setenv`: Lets the plugin tell Compose how dependent services can access the created resource. See next section for further details.
+- `setenv`: Lets the plugin tell Compose how dependent services can access the created resource. The variable is automatically prefixed with the service name. See next section for further details.
+- `rawsetenv`: Same as `setenv`, but the variable is injected as-is without the service name prefix. Useful when applications require exact variable names that cannot be altered.
 - `debug`: Those messages could help debugging the provider, but are not rendered to the user by default. They are rendered when Compose is started with `--verbose` flag.
 
 ```mermaid
@@ -99,6 +100,16 @@ automatically prefixing it with the service name. For example, if `awesomecloud
 Then the `app` service, which depends on the service managed by the provider, will receive a `DATABASE_URL` environment variable injected
 into its runtime environment.
 
+When the provider command sends a `rawsetenv` JSON message, Compose injects the variable as-is without any prefix:
+```json
+{"type": "rawsetenv", "message": "SECRET_KEY=xxx"}
+```
+The `app` service will receive `SECRET_KEY` exactly as specified, regardless of the provider service name.
+This is useful when injecting secrets or configuration values that must match exact variable names expected by
+applications or frameworks. Unlike `setenv`, which avoids collisions through automatic prefixing, `rawsetenv` keys
+are the provider's responsibility to keep unique. If multiple providers emit the same `rawsetenv` key, the last one
+to run will overwrite previous values.
+
 > __Note:__  The `compose up` provider command _MUST_ be idempotent. If resource is already running, the command _MUST_ set
 > the same environment variables to ensure consistent configuration of dependent services.
 

pkg/compose/plugins.go

@@ -48,10 +48,16 @@ const (
 	ErrorType                 = "error"
 	InfoType                  = "info"
 	SetEnvType                = "setenv"
+	RawSetEnvType             = "rawsetenv"
 	DebugType                 = "debug"
 	providerMetadataDirectory = "compose/providers"
 )
 
+type pluginVariables struct {
+	prefixed types.Mapping
+	raw      types.Mapping
+}
+
 var mux sync.Mutex
 
 func (s *composeService) runPlugin(ctx context.Context, project *types.Project, service types.ServiceConfig, command string) error {
@@ -70,7 +76,7 @@ func (s *composeService) runPlugin(ctx context.Context, project *types.Project,
 		return nil
 	}
 
-	variables, err := s.executePlugin(cmd, command, service)
+	vars, err := s.executePlugin(cmd, command, service)
 	if err != nil {
 		return err
 	}
@@ -84,16 +90,19 @@ func (s *composeService) runPlugin(ctx context.Context, project *types.Project,
 	for name, s := range project.Services {
 		if _, ok := s.DependsOn[service.Name]; ok {
 			prefix := strings.ToUpper(service.Name) + "_"
-			for key, val := range variables {
+			for key, val := range vars.prefixed {
 				s.Environment[prefix+key] = &val
 			}
+			for key, val := range vars.raw {
+				s.Environment[key] = &val
+			}
 			project.Services[name] = s
 		}
 	}
 	return nil
 }
 
-func (s *composeService) executePlugin(cmd *exec.Cmd, command string, service types.ServiceConfig) (types.Mapping, error) { //nolint:gocyclo
+func (s *composeService) executePlugin(cmd *exec.Cmd, command string, service types.ServiceConfig) (pluginVariables, error) { //nolint:gocyclo
 	var action string
 	switch command {
 	case "up":
@@ -106,23 +115,26 @@ func (s *composeService) executePlugin(cmd *exec.Cmd, command string, service ty
 		s.events.On(stoppingEvent(service.Name))
 		action = "stop"
 	default:
-		return nil, fmt.Errorf("unsupported plugin command: %s", command)
+		return pluginVariables{}, fmt.Errorf("unsupported plugin command: %s", command)
 	}
 
 	stdout, err := cmd.StdoutPipe()
 	if err != nil {
-		return nil, err
+		return pluginVariables{}, err
 	}
 
 	err = cmd.Start()
 	if err != nil {
-		return nil, err
+		return pluginVariables{}, err
 	}
 
 	decoder := json.NewDecoder(stdout)
 	defer func() { _ = stdout.Close() }()
 
-	variables := types.Mapping{}
+	vars := pluginVariables{
+		prefixed: types.Mapping{},
+		raw:      types.Mapping{},
+	}
 
 	for {
 		var msg JsonMessage
@@ -131,31 +143,37 @@ func (s *composeService) executePlugin(cmd *exec.Cmd, command string, service ty
 			break
 		}
 		if err != nil {
-			return nil, err
+			return pluginVariables{}, err
 		}
 		switch msg.Type {
 		case ErrorType:
 			s.events.On(newEvent(service.Name, api.Error, firstLine(msg.Message)))
-			return nil, errors.New(msg.Message)
+			return pluginVariables{}, errors.New(msg.Message)
 		case InfoType:
 			s.events.On(newEvent(service.Name, api.Working, firstLine(msg.Message)))
 		case SetEnvType:
 			key, val, found := strings.Cut(msg.Message, "=")
 			if !found {
-				return nil, fmt.Errorf("invalid response from plugin: %s", msg.Message)
+				return pluginVariables{}, fmt.Errorf("invalid response from plugin: %s", msg.Message)
 			}
-			variables[key] = val
+			vars.prefixed[key] = val
+		case RawSetEnvType:
+			key, val, found := strings.Cut(msg.Message, "=")
+			if !found {
+				return pluginVariables{}, fmt.Errorf("invalid response from plugin: %s", msg.Message)
+			}
+			vars.raw[key] = val
 		case DebugType:
 			logrus.Debugf("%s: %s", service.Name, msg.Message)
 		default:
-			return nil, fmt.Errorf("invalid response from plugin: %s", msg.Type)
+			return pluginVariables{}, fmt.Errorf("invalid response from plugin: %s", msg.Type)
 		}
 	}
 
 	err = cmd.Wait()
 	if err != nil {
 		s.events.On(errorEvent(service.Name, err.Error()))
-		return nil, fmt.Errorf("failed to %s service provider: %s", action, err.Error())
+		return pluginVariables{}, fmt.Errorf("failed to %s service provider: %s", action, err.Error())
 	}
 	switch command {
 	case "up":
@@ -165,7 +183,7 @@ func (s *composeService) executePlugin(cmd *exec.Cmd, command string, service ty
 	case "stop":
 		s.events.On(stoppedEvent(service.Name))
 	}
-	return variables, nil
+	return vars, nil
 }
 
 func (s *composeService) getPluginBinaryPath(provider string) (path string, err error) {

pkg/e2e/fixtures/providers/rawsetenv.yaml

@@ -0,0 +1,13 @@
+services:
+  test:
+    image: alpine
+    command: env
+    depends_on:
+      - secrets
+  secrets:
+    provider:
+      type: example-provider
+      options:
+        name: secrets
+        type: test1
+        size: 1

pkg/e2e/providers_test.go

@@ -76,6 +76,27 @@ func TestDependsOnMultipleProviders(t *testing.T) {
 	env := getEnv(res.Combined())
 	assert.Check(t, slices.Contains(env, "PROVIDER1_URL=https://magic.cloud/provider1"), env)
 	assert.Check(t, slices.Contains(env, "PROVIDER2_URL=https://magic.cloud/provider2"), env)
+	assert.Check(t, slices.Contains(env, "CLOUD_REGION=us-east-1"), env)
+}
+
+func TestProviderRawSetEnv(t *testing.T) {
+	provider, err := findExecutable("example-provider")
+	assert.NilError(t, err)
+
+	path := fmt.Sprintf("%s%s%s", os.Getenv("PATH"), string(os.PathListSeparator), filepath.Dir(provider))
+	c := NewParallelCLI(t, WithEnv("PATH="+path))
+	const projectName = "rawsetenv"
+	t.Cleanup(func() {
+		c.cleanupWithDown(t, projectName)
+	})
+
+	res := c.RunDockerComposeCmd(t, "-f", "fixtures/providers/rawsetenv.yaml", "--project-name", projectName, "up")
+	res.Assert(t, icmd.Success)
+	env := getEnv(res.Combined(), false)
+	// setenv: prefixed with service name
+	assert.Check(t, slices.Contains(env, "SECRETS_URL=https://magic.cloud/secrets"), env)
+	// rawsetenv: injected as-is without prefix
+	assert.Check(t, slices.Contains(env, "CLOUD_REGION=us-east-1"), env)
 }
 
 func getEnv(out string) []string {