compose/pkg/compose/plugins.go
Nicolas De Loof c4a0e9bf88 feat: get-relay-info tells providers where to bind for the relay
A provider running its service LOCALLY has to pick the address its
published endpoint binds, and on a standalone Linux engine no address
is both relay-reachable and off the LAN (#14257):
host.docker.internal resolves there to the bridge gateway, which a
loopback-only listener cannot accept, while the wildcard exposes the
port on every host interface. The bundled example provider worked
around it by binding 0.0.0.0.

The new get-relay-info message closes that gap, with compose owning
the platform knowledge so the provider just binds what is announced.
Compose answers with one JSON line listing the networks the relay
would join — the dependents' networks, exactly as selected for the
relay deployment — each with the address a locally-run endpoint should
bind to be reachable from the relay: the network's engine-assigned
gateway on a standalone engine (an address the host owns on that
bridge, reachable from the relay but not from the LAN), and 127.0.0.1
under Docker Desktop — the networks live inside the VM there, and the
host's own loopback is, factually, where a host process is reached
through the Desktop proxy. Resolution is lazy (Desktop detection and
network inspects run only when a provider asks — a remote-resource
provider never does) and best-effort: a missing gateway means "bind
elsewhere".

Compose also announces the message types it accepts in the
COMPOSE_PROVIDER_MESSAGES environment variable of the provider
process: an unknown message stays a fatal protocol error by design
(a provider REQUIRING an unsupported message must fail loudly), and
the announcement is how a provider adapts instead of failing. The
example provider binds the first announced gateway, falling back to
the wildcard only when none is announced; through it,
TestProviderPublishEndpoint exercises the gateway path on Linux CI
and the loopback path on Docker Desktop.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
2026-09-24 14:41:28 +02:00

517 lines
17 KiB
Go

/*
Copyright 2020 Docker Compose CLI authors
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.
*/
package compose
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"sync"
"github.com/compose-spec/compose-go/v2/types"
"github.com/containerd/errdefs"
"github.com/docker/cli/cli-plugins/manager"
"github.com/docker/cli/cli/config"
"github.com/sirupsen/logrus"
"github.com/spf13/cobra"
"github.com/docker/compose/v5/pkg/api"
)
type JsonMessage struct {
Type string `json:"type"`
Message string `json:"message,omitempty"`
}
const (
ErrorType = "error"
InfoType = "info"
SetEnvType = "setenv"
RawSetEnvType = "rawsetenv"
DebugType = "debug"
PublishEndpointType = "publish-endpoint"
providerMetadataDirectory = "compose/providers"
// GetServiceConfigType is a message the provider sends to receive, on
// its stdin, one JSON line holding the resolved canonical configuration
// of the service it manages — answered from the in-memory model.
GetServiceConfigType = "get-service-config"
// GetRelayInfoType is a message the provider sends to receive, on its
// stdin, one JSON line describing the project networks the relay
// standing in for this service would join, with each network's gateway
// address. Only meaningful for a provider running its service LOCALLY:
// the gateway is an address the host owns on the network's bridge, so
// an endpoint bound to it is reachable from the relay without being
// exposed on the LAN. A provider backing the service with a remote
// resource has no use for it.
GetRelayInfoType = "get-relay-info"
// ComposeProviderMessagesEnv announces to the provider process, as a
// comma-separated list, every message type this compose accepts on the
// provider's stdout — so a provider can adapt to the compose it runs
// under instead of emitting a message that would fail the command
// (an unknown message type is a protocol error by design: a provider
// REQUIRING an unsupported message must fail rather than degrade
// silently).
ComposeProviderMessagesEnv = "COMPOSE_PROVIDER_MESSAGES"
)
// providerMessageTypes is the COMPOSE_PROVIDER_MESSAGES value: every message
// type executePlugin's loop accepts. Keep in sync with its switch.
var providerMessageTypes = strings.Join([]string{
ErrorType,
InfoType,
SetEnvType,
RawSetEnvType,
DebugType,
PublishEndpointType,
GetServiceConfigType,
GetRelayInfoType,
}, ",")
type pluginVariables struct {
prefixed types.Mapping
raw types.Mapping
// endpoints are "port=host:port" publish-endpoint messages: container
// port the consumers know, mapped to where the provider's resource
// actually listens. When present, compose deploys a relay container
// under the service's name on the consumers' networks.
endpoints map[int]string
}
var mux sync.Mutex
func (s *composeService) runPlugin(ctx context.Context, project *types.Project, service types.ServiceConfig, command string) error {
provider := *service.Provider
plugin, err := s.getPluginBinaryPath(provider.Type)
if err != nil {
return err
}
cmd, err := s.setupPluginCommand(ctx, project, service, plugin, command)
if err != nil {
return err
}
if cmd == nil {
return nil
}
variables, err := s.executePlugin(ctx, project, cmd, command, service)
if err != nil {
return err
}
if command == "stop" {
return nil
}
isUp := command == "up"
deployRelay := isUp && len(variables.endpoints) > 0
// project.Services is shared state mutated by every concurrent provider
// run: the env-var injection below writes it, and the relay's network
// selection reads it — both belong under the mutex. The Docker API work
// in ensureServiceRelay does not: holding the lock across it would make
// every concurrent provider wait on the slowest one (image pull
// included), so the relay is deployed after the lock is released.
mux.Lock()
for name, s := range project.Services {
if _, ok := s.DependsOn[service.Name]; ok {
prefix := strings.ToUpper(service.Name) + "_"
for key, val := range variables.prefixed {
s.Environment[prefix+key] = &val
}
for key, val := range variables.raw {
if existing, ok := s.Environment[key]; ok && (existing == nil || *existing != val) {
logrus.Warnf("provider %q overrides environment variable %q in service %q", service.Name, key, name)
}
s.Environment[key] = &val
}
project.Services[name] = s
}
}
var networkKeys []string
if deployRelay {
networkKeys = relayNetworks(project, service)
}
mux.Unlock()
if isUp {
if deployRelay {
return s.ensureServiceRelay(ctx, project, service, variables.endpoints, networkKeys)
}
// The provider published no endpoint on this run — whether it never
// did, or stopped doing so since a previous up deployed a relay for
// it. Either way there is nothing to route to, so any relay left
// over from an earlier run must go: routing to whatever upstream it
// still holds would be silently wrong instead of just absent.
return s.removeServiceRelay(ctx, project.Name, service.Name)
}
return nil
}
// parseEndpointMessage decodes a publish-endpoint payload: "80=host:port".
func parseEndpointMessage(message string) (int, string, error) {
portPart, upstream, found := strings.Cut(message, "=")
if !found {
return 0, "", fmt.Errorf("publish-endpoint %q: want port=host:port", message)
}
port, err := strconv.Atoi(portPart)
if err != nil || port < 1 || port > 65535 {
return 0, "", fmt.Errorf("publish-endpoint %q: invalid port", message)
}
if _, _, err := net.SplitHostPort(upstream); err != nil {
return 0, "", fmt.Errorf("publish-endpoint %q: invalid endpoint: %w", message, err)
}
return port, upstream, nil
}
func (s *composeService) executePlugin(ctx context.Context, project *types.Project, cmd *exec.Cmd, command string, service types.ServiceConfig) (pluginVariables, error) {
var action string
switch command {
case "up":
s.events.On(creatingEvent(service.Name))
action = "create"
case "down":
s.events.On(removingEvent(service.Name))
action = "remove"
case "stop":
s.events.On(stoppingEvent(service.Name))
action = "stop"
default:
return pluginVariables{}, fmt.Errorf("unsupported plugin command: %s", command)
}
stdout, err := cmd.StdoutPipe()
if err != nil {
return pluginVariables{}, err
}
stdin, err := cmd.StdinPipe()
if err != nil {
return pluginVariables{}, err
}
// Answers are written from their own goroutine: writing a config larger
// than the OS pipe buffer from the read loop would deadlock against a
// provider that emits stdout before draining its stdin. Every answer is
// the same serialized service, so completion order is irrelevant; the
// mutex keeps individual writes atomic. Write failures are not reported
// from here — a provider missing its answer reads EOF once stdin closes.
var stdinMu sync.Mutex
var answers sync.WaitGroup
processExited := false
// Closing stdin on exit unblocks a provider waiting for a response the
// loop will never produce (e.g. a request emitted after an error). An
// answer dispatched but not yet written must land before the close —
// but only once the process has exited can a write not block forever
// (a dead peer turns it into EPIPE); on error paths the provider may
// still be alive and not reading, so close first to error the write
// out instead of hanging the wait.
defer func() {
if processExited {
answers.Wait()
_ = stdin.Close()
} else {
_ = stdin.Close()
answers.Wait()
}
}()
err = cmd.Start()
if err != nil {
return pluginVariables{}, err
}
// Error paths return before the normal cmd.Wait below and would leave
// the provider as a zombie (and possibly running): reap it — kill
// first, as it may be misbehaving or blocked, which also errors out
// any in-flight answer write. Runs before the stdin/answers defer
// above (LIFO).
defer func() {
if !processExited {
_ = cmd.Process.Kill()
_ = cmd.Wait()
}
}()
decoder := json.NewDecoder(stdout)
defer func() { _ = stdout.Close() }()
variables := pluginVariables{
prefixed: types.Mapping{},
raw: types.Mapping{},
endpoints: map[int]string{},
}
for {
var msg JsonMessage
err = decoder.Decode(&msg)
if errors.Is(err, io.EOF) {
break
}
if err != nil {
return pluginVariables{}, err
}
if err := s.handlePluginMessage(ctx, project, service, msg, &variables, stdin, &stdinMu, &answers); err != nil {
return pluginVariables{}, err
}
}
err = cmd.Wait()
processExited = true
if err != nil {
s.events.On(errorEvent(service.Name, err.Error()))
return pluginVariables{}, fmt.Errorf("failed to %s service provider: %s", action, err.Error())
}
switch command {
case "up":
s.events.On(createdEvent(service.Name))
case "down":
s.events.On(removedEvent(service.Name))
case "stop":
s.events.On(stoppedEvent(service.Name))
}
return variables, nil
}
// handlePluginMessage processes one provider message, mutating variables in
// place; a returned error is terminal for the run (the provider is killed
// and the command fails). An unknown message type IS such an error: a
// provider requiring a message this compose does not support must fail
// loudly, not degrade silently — providers adapt through the
// COMPOSE_PROVIDER_MESSAGES announcement instead.
func (s *composeService) handlePluginMessage(ctx context.Context, project *types.Project, service types.ServiceConfig, msg JsonMessage,
variables *pluginVariables, stdin io.WriteCloser, stdinMu *sync.Mutex, answers *sync.WaitGroup,
) error {
switch msg.Type {
case ErrorType:
s.events.On(newEvent(service.Name, api.Error, firstLine(msg.Message)))
return 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 fmt.Errorf("invalid message from plugin: %s", msg.Message)
}
variables.prefixed[key] = val
case RawSetEnvType:
key, val, found := strings.Cut(msg.Message, "=")
if !found {
return fmt.Errorf("invalid message from plugin: %s", msg.Message)
}
variables.raw[key] = val
case GetServiceConfigType:
payload, err := json.Marshal(service)
if err != nil {
return fmt.Errorf("failed to answer get-service-config: %w", err)
}
answerProvider(stdin, stdinMu, answers, payload)
case GetRelayInfoType:
// resolved lazily, on request only: the network inspects cost
// nothing to providers that never ask (remote-resource providers),
// and the networks exist by the time an up runs
payload, err := json.Marshal(s.relayInfo(ctx, project, service))
if err != nil {
return fmt.Errorf("failed to answer get-relay-info: %w", err)
}
answerProvider(stdin, stdinMu, answers, payload)
case PublishEndpointType:
port, upstream, err := parseEndpointMessage(msg.Message)
if err != nil {
return fmt.Errorf("invalid message from plugin: %w", err)
}
variables.endpoints[port] = upstream
case DebugType:
logrus.Debugf("%s: %s", service.Name, msg.Message)
default:
return fmt.Errorf("invalid message from plugin: %s", msg.Type)
}
return nil
}
// answerProvider dispatches one JSON-line answer to the provider's stdin
// from its own goroutine: writing a payload larger than the OS pipe buffer
// from the read loop would deadlock against a provider that emits stdout
// before draining its stdin. The mutex keeps individual writes atomic; a
// write failure is not reported — a provider missing its answer reads EOF
// once stdin closes.
func answerProvider(stdin io.WriteCloser, stdinMu *sync.Mutex, answers *sync.WaitGroup, payload []byte) {
payload = append(payload, '\n')
answers.Add(1)
go func() {
defer answers.Done()
stdinMu.Lock()
defer stdinMu.Unlock()
_, _ = stdin.Write(payload)
}()
}
func (s *composeService) getPluginBinaryPath(provider string) (path string, err error) {
if provider == "compose" {
return "", errors.New("'compose' is not a valid provider type")
}
plugin, err := manager.GetPlugin(provider, s.dockerCli, &cobra.Command{})
if err == nil {
path = plugin.Path
}
if errdefs.IsNotFound(err) {
// A plain LookPath honors Windows executable-resolution semantics
// (PATHEXT: .exe, but also .com/.bat/.cmd), so provider executables
// need not be compiled binaries. Callers must not append a hardcoded
// ".exe": it restricts the lookup instead of helping it.
path, err = exec.LookPath(provider)
}
return path, err
}
func (s *composeService) setupPluginCommand(ctx context.Context, project *types.Project, service types.ServiceConfig, path, command string) (*exec.Cmd, error) {
cmdOptionsMetadata := s.getPluginMetadata(path, service.Provider.Type, project)
var currentCommandMetadata CommandMetadata
switch command {
case "up":
currentCommandMetadata = cmdOptionsMetadata.Up
case "down":
currentCommandMetadata = cmdOptionsMetadata.Down
case "stop":
if cmdOptionsMetadata.Stop == nil {
return nil, nil
}
currentCommandMetadata = *cmdOptionsMetadata.Stop
}
provider := *service.Provider
commandMetadataIsEmpty := cmdOptionsMetadata.IsEmpty()
if err := currentCommandMetadata.CheckRequiredParameters(provider); !commandMetadataIsEmpty && err != nil {
return nil, err
}
args := []string{"compose", "--project-name=" + project.Name, command}
for k, v := range provider.Options {
for _, value := range v {
if _, ok := currentCommandMetadata.GetParameter(k); commandMetadataIsEmpty || ok {
args = append(args, fmt.Sprintf("--%s=%s", k, value))
}
}
}
args = append(args, service.Name)
cmd := exec.CommandContext(ctx, path, args...)
err := s.prepareShellOut(ctx, project.Environment, cmd)
if err != nil {
return nil, err
}
cmd.Env = append(cmd.Env, ComposeProviderMessagesEnv+"="+providerMessageTypes)
return cmd, nil
}
func (s *composeService) getPluginMetadata(path, command string, project *types.Project) ProviderMetadata {
cmd := exec.Command(path, "compose", "metadata")
err := s.prepareShellOut(context.Background(), project.Environment, cmd)
if err != nil {
logrus.Debugf("failed to prepare plugin metadata command: %v", err)
return ProviderMetadata{}
}
stdout := &bytes.Buffer{}
cmd.Stdout = stdout
if err := cmd.Run(); err != nil {
logrus.Debugf("failed to start plugin metadata command: %v", err)
return ProviderMetadata{}
}
var metadata ProviderMetadata
if err := json.Unmarshal(stdout.Bytes(), &metadata); err != nil {
output, _ := io.ReadAll(stdout)
logrus.Debugf("failed to decode plugin metadata: %v - %s", err, output)
return ProviderMetadata{}
}
// Save metadata into docker home directory to be used by Docker LSP tool
// Just log the error as it's not a critical error for the main flow
metadataDir := filepath.Join(config.Dir(), providerMetadataDirectory)
if err := os.MkdirAll(metadataDir, 0o700); err == nil {
metadataFilePath := filepath.Join(metadataDir, command+".json")
if err := os.WriteFile(metadataFilePath, stdout.Bytes(), 0o600); err != nil {
logrus.Debugf("failed to save plugin metadata: %v", err)
}
} else {
logrus.Debugf("failed to create plugin metadata directory: %v", err)
}
return metadata
}
type ProviderMetadata struct {
Description string `json:"description"`
Up CommandMetadata `json:"up"`
Down CommandMetadata `json:"down"`
Stop *CommandMetadata `json:"stop,omitempty"`
}
func (p ProviderMetadata) IsEmpty() bool {
return p.Description == "" && p.Up.Parameters == nil && p.Down.Parameters == nil
}
type CommandMetadata struct {
Parameters []ParameterMetadata `json:"parameters"`
}
type ParameterMetadata struct {
Name string `json:"name"`
Description string `json:"description"`
Required bool `json:"required"`
Type string `json:"type"`
Default string `json:"default,omitempty"`
}
func (c CommandMetadata) GetParameter(paramName string) (ParameterMetadata, bool) {
for _, p := range c.Parameters {
if p.Name == paramName {
return p, true
}
}
return ParameterMetadata{}, false
}
func (c CommandMetadata) CheckRequiredParameters(provider types.ServiceProviderConfig) error {
for _, p := range c.Parameters {
if p.Required {
if _, ok := provider.Options[p.Name]; !ok {
return fmt.Errorf("required parameter %q is missing from provider %q definition", p.Name, provider.Type)
}
}
}
return nil
}
// firstLine returns the first line of s, stripping any trailing newlines.
func firstLine(s string) string {
s = strings.TrimRight(s, "\n")
if before, _, ok := strings.Cut(s, "\n"); ok {
return before
}
return s
}