mirror of
https://github.com/docker/compose.git
synced 2026-11-17 13:45:39 +00:00
Some checks are pending
ci / validate (lint) (push) Waiting to run
ci / validate (relay-lint) (push) Waiting to run
ci / validate (relay-test) (push) Waiting to run
ci / validate (validate-docs) (push) Waiting to run
ci / validate (validate-go-mod) (push) Waiting to run
ci / validate (validate-headers) (push) Waiting to run
ci / validate (validate-mocks) (push) Waiting to run
ci / binary (push) Waiting to run
ci / binary-finalize (push) Blocked by required conditions
ci / bin-image-test (push) Waiting to run
ci / relay-image-test (push) Waiting to run
ci / test (push) Waiting to run
ci / e2e (plugin, oldstable, graphdriver) (push) Waiting to run
ci / e2e (standalone, oldstable, graphdriver) (push) Waiting to run
ci / e2e (plugin, stable, containerd) (push) Waiting to run
ci / e2e (plugin, stable, graphdriver) (push) Waiting to run
ci / e2e (standalone, stable, containerd) (push) Waiting to run
ci / e2e (standalone, stable, graphdriver) (push) Waiting to run
ci / coverage (push) Blocked by required conditions
ci / ci-ok (push) Blocked by required conditions
ci / release (push) Blocked by required conditions
merge / bin-image-prepare (push) Waiting to run
merge / bin-image (push) Blocked by required conditions
merge / relay-image (push) Waiting to run
merge / module-image (push) Waiting to run
Scorecards supply-chain security / Scorecards analysis (push) Waiting to run
zizmor / zizmor (push) Waiting to run
The CLI refuses combinations such as --wait with --attach, or --detach with --abort-on-container-exit, --exit-code-from or --watch. The library did not: an integrator setting Start.Wait together with Start.Attach got an interactive session in which the wait was silently dropped, and the session-only options were silently ignored when Attach is nil. Add UpOptions.Validate, called first thing by Up, which returns an *IncompatibleOptionsError matching api.ErrIncompatibleOptions. The CLI is unchanged. Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
137 lines
5.2 KiB
Go
137 lines
5.2 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 api
|
|
|
|
import (
|
|
"errors"
|
|
"fmt"
|
|
"slices"
|
|
"strings"
|
|
)
|
|
|
|
// IncompatibleOptionsError reports options, or option values, that were
|
|
// requested together but cannot be honored together. It is returned, before any side effect, by
|
|
// UpOptions.Validate and therefore by Compose.Up.
|
|
//
|
|
// It matches ErrIncompatibleOptions with errors.Is, and callers needing the
|
|
// details can retrieve it with errors.As:
|
|
//
|
|
// var incompatible *api.IncompatibleOptionsError
|
|
// if errors.As(err, &incompatible) {
|
|
// log.Printf("conflict between %v: %s", incompatible.Options, incompatible.Reason)
|
|
// }
|
|
type IncompatibleOptionsError struct {
|
|
// Options names the conflicting option fields, as Go selectors relative to
|
|
// the options type that was validated (e.g. "Start.Wait").
|
|
Options []string
|
|
// Reason explains why the options, as set, cannot be honored together.
|
|
Reason string
|
|
}
|
|
|
|
func (e *IncompatibleOptionsError) Error() string {
|
|
return fmt.Sprintf("%s (%s): %s", ErrIncompatibleOptions, strings.Join(e.Options, ", "), e.Reason)
|
|
}
|
|
|
|
// Unwrap makes errors.Is(err, ErrIncompatibleOptions) hold.
|
|
func (e *IncompatibleOptionsError) Unwrap() error {
|
|
return ErrIncompatibleOptions
|
|
}
|
|
|
|
func incompatible(reason string, options ...string) error {
|
|
return &IncompatibleOptionsError{Options: options, Reason: reason}
|
|
}
|
|
|
|
// Validate checks that the options requested for Up can be honored together.
|
|
// It is a pure function, called by Up before it does anything, and can also be
|
|
// called by integrators to fail early. It returns nil, or an error matching
|
|
// ErrIncompatibleOptions describing every conflict found.
|
|
//
|
|
// Up has two modes, selected by Start.Attach: detached (nil) returns once the
|
|
// containers are started, interactive (set) keeps running a foreground session.
|
|
// Validate only checks the combinations listed below: Wait with Attach, and
|
|
// OnExit, ExitCodeFrom or Watch without Attach. Other mode-specific fields
|
|
// (e.g. Services, AttachTo, NavigationMenu) are not checked and may be ignored
|
|
// in the mode they do not apply to.
|
|
//
|
|
// With a single conflict the error is an *IncompatibleOptionsError. With
|
|
// several, the conflicts are reported together as an error joined with
|
|
// errors.Join: errors.Is(err, ErrIncompatibleOptions) still holds, but
|
|
// errors.As to *IncompatibleOptionsError only yields the first conflict. To
|
|
// inspect all of them, walk the joined error through its Unwrap() []error
|
|
// method.
|
|
//
|
|
// The compose CLI refuses the same combinations, with messages naming its
|
|
// flags; Validate is the safety net for programs using the library directly.
|
|
func (o UpOptions) Validate() error {
|
|
var errs []error
|
|
errs = append(errs, validateWaitIsDetached(o.Start)...)
|
|
errs = append(errs, validateDetachedHasNoSession(o.Start)...)
|
|
switch len(errs) {
|
|
case 0:
|
|
return nil
|
|
case 1:
|
|
return errs[0]
|
|
default:
|
|
return errors.Join(errs...)
|
|
}
|
|
}
|
|
|
|
// validateWaitIsDetached: Wait blocks until the services are running|healthy
|
|
// and then returns, which only happens in detached mode. In an interactive
|
|
// session that check would be silently dropped.
|
|
// CLI: --wait implies --detach and is incompatible with --attach and
|
|
// --attach-dependencies.
|
|
func validateWaitIsDetached(s StartOptions) []error {
|
|
if s.Wait && s.Attach != nil {
|
|
return []error{incompatible("Wait returns once services are running or healthy, which is detached mode, while Attach starts an interactive session",
|
|
"Start.Wait", "Start.Attach")}
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// validateDetachedHasNoSession: the cascade policy, the exit code selection
|
|
// and watch are all features of the interactive session, they have no effect
|
|
// when Attach is nil. Every such option set is reported. When Wait is set, it
|
|
// is the reason why the session cannot be started, so it is part of the conflict.
|
|
// CLI: --detach is incompatible with --abort-on-container-exit,
|
|
// --abort-on-container-failure, --exit-code-from (which implies
|
|
// --abort-on-container-exit) and --watch.
|
|
func validateDetachedHasNoSession(s StartOptions) []error {
|
|
if s.Attach != nil {
|
|
return nil
|
|
}
|
|
reason := "Attach is nil (detached mode), so no interactive session runs to honor "
|
|
options := []string{"Start.Attach"}
|
|
if s.Wait {
|
|
reason = "Wait implies detached mode and Attach is nil, so no interactive session runs to honor "
|
|
options = []string{"Start.Wait", "Start.Attach"}
|
|
}
|
|
conflict := func(field string) error {
|
|
return incompatible(reason+field, append(slices.Clone(options), "Start."+field)...)
|
|
}
|
|
var errs []error
|
|
if s.OnExit != CascadeIgnore {
|
|
errs = append(errs, conflict("OnExit"))
|
|
}
|
|
if s.ExitCodeFrom != "" {
|
|
errs = append(errs, conflict("ExitCodeFrom"))
|
|
}
|
|
if s.Watch {
|
|
errs = append(errs, conflict("Watch"))
|
|
}
|
|
return errs
|
|
}
|