From f5efe67ea3ff2e9c054f37df0ea274096809c410 Mon Sep 17 00:00:00 2001 From: Nicolas De Loof Date: Wed, 28 Oct 2026 15:56:05 +0100 Subject: [PATCH] feat(api): a typed error for a service with no running container Exec, port, export, commit and attach fail with "service X is not running" when they find no container to act on. A program driving Compose as a library could only recognise that failure by matching the message. Return a ServiceNotRunningError, which matches the new ErrNotRunning and carries the service and the replica index. The message is unchanged. Signed-off-by: Nicolas De Loof --- pkg/api/errors.go | 33 ++++++++++++++++++++++++++++++++ pkg/api/errors_test.go | 14 ++++++++++++++ pkg/compose/containers.go | 6 +----- pkg/compose/containers_test.go | 35 ++++++++++++++++++++++++++++++++++ 4 files changed, 83 insertions(+), 5 deletions(-) diff --git a/pkg/api/errors.go b/pkg/api/errors.go index d75de13bf..af88b79c8 100644 --- a/pkg/api/errors.go +++ b/pkg/api/errors.go @@ -18,6 +18,7 @@ package api import ( "errors" + "fmt" ) const ( @@ -48,6 +49,9 @@ var ( // ErrIncompatibleOptions is returned when a set of options that cannot be // honored together is requested. See IncompatibleOptionsError. ErrIncompatibleOptions = errors.New("incompatible options") + // ErrNotRunning is returned when an operation targets a service, or a + // replica of it, that has no running container. See ServiceNotRunningError. + ErrNotRunning = errors.New("not running") // ErrInvalidOption is returned when an option is set to a value it does // not accept. See InvalidOptionError. ErrInvalidOption = errors.New("invalid option") @@ -98,6 +102,35 @@ func IsErrIncompatibleOptions(err error) bool { return errors.Is(err, ErrIncompatibleOptions) } +// ServiceNotRunningError reports that an operation which acts on one container +// of a service (exec, port, export, commit, attach…) found no matching +// container, that is no running one for most of them. It +// matches ErrNotRunning with errors.Is, and callers needing the details can +// retrieve it with errors.As. +type ServiceNotRunningError struct { + // Service is the name of the service that was targeted. + Service string + // Index is the replica that was asked for, 0 when none in particular was. + Index int +} + +func (e *ServiceNotRunningError) Error() string { + if e.Index > 0 { + return fmt.Sprintf("service %q is not running container #%d", e.Service, e.Index) + } + return fmt.Sprintf("service %q is not running", e.Service) +} + +// Unwrap makes errors.Is(err, ErrNotRunning) hold. +func (e *ServiceNotRunningError) Unwrap() error { + return ErrNotRunning +} + +// IsErrNotRunning returns true if the unwrapped error is ErrNotRunning +func IsErrNotRunning(err error) bool { + return errors.Is(err, ErrNotRunning) +} + // IsErrInvalidOption returns true if the unwrapped error is ErrInvalidOption func IsErrInvalidOption(err error) bool { return errors.Is(err, ErrInvalidOption) diff --git a/pkg/api/errors_test.go b/pkg/api/errors_test.go index d221db3fd..2b2af519c 100644 --- a/pkg/api/errors_test.go +++ b/pkg/api/errors_test.go @@ -51,3 +51,17 @@ func TestIsUnknown(t *testing.T) { assert.Assert(t, !IsUnknownError(errors.New("another error"))) } + +func TestServiceNotRunningError(t *testing.T) { + err := fmt.Errorf("exec: %w", &ServiceNotRunningError{Service: "web"}) + assert.Assert(t, IsErrNotRunning(err)) + assert.Assert(t, !IsNotFoundError(err)) + assert.ErrorContains(t, err, `service "web" is not running`) + + var notRunning *ServiceNotRunningError + assert.Assert(t, errors.As(err, ¬Running)) + assert.Equal(t, notRunning.Service, "web") + + assert.Error(t, &ServiceNotRunningError{Service: "web", Index: 3}, `service "web" is not running container #3`) + assert.Assert(t, !IsErrNotRunning(errors.New("another error"))) +} diff --git a/pkg/compose/containers.go b/pkg/compose/containers.go index fbaf425be..fb41fc075 100644 --- a/pkg/compose/containers.go +++ b/pkg/compose/containers.go @@ -18,7 +18,6 @@ package compose import ( "context" - "fmt" "slices" "sort" "strconv" @@ -118,10 +117,7 @@ func (s *composeService) getSpecifiedContainer(ctx context.Context, projectName } containers := res.Items if len(containers) < 1 { - if containerIndex > 0 { - return container.Summary{}, fmt.Errorf("service %q is not running container #%d", serviceName, containerIndex) - } - return container.Summary{}, fmt.Errorf("service %q is not running", serviceName) + return container.Summary{}, &api.ServiceNotRunningError{Service: serviceName, Index: containerIndex} } // Sort by container number first, then put one-off containers at the end diff --git a/pkg/compose/containers_test.go b/pkg/compose/containers_test.go index ae85cb373..5db835369 100644 --- a/pkg/compose/containers_test.go +++ b/pkg/compose/containers_test.go @@ -17,10 +17,13 @@ package compose import ( + "errors" "testing" "github.com/compose-spec/compose-go/v2/types" "github.com/moby/moby/api/types/container" + "github.com/moby/moby/client" + "go.uber.org/mock/gomock" "gotest.tools/v3/assert" "github.com/docker/compose/v5/pkg/api" @@ -69,3 +72,35 @@ func TestIsOrphaned(t *testing.T) { }) } } + +// TestGetSpecifiedContainerNotRunning pins the error of an operation that +// targets a service with no running container: callers must be able to tell it +// from any other failure without matching the message, which stays the same. +func TestGetSpecifiedContainerNotRunning(t *testing.T) { + tests := []struct { + name string + index int + message string + }{ + {name: "any replica", index: 0, message: `service "web" is not running`}, + {name: "given replica", index: 2, message: `service "web" is not running container #2`}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + mockCtrl := gomock.NewController(t) + apiClient, cli := prepareMocks(mockCtrl) + tested, err := NewComposeService(cli) + assert.NilError(t, err) + apiClient.EXPECT().ContainerList(gomock.Any(), gomock.Any()).Return(client.ContainerListResult{}, nil) + + _, err = tested.(*composeService).getSpecifiedContainer(t.Context(), testProject, oneOffExclude, false, "web", tt.index) + assert.Error(t, err, tt.message) + assert.Assert(t, errors.Is(err, api.ErrNotRunning), "got %v", err) + + var notRunning *api.ServiceNotRunningError + assert.Assert(t, errors.As(err, ¬Running)) + assert.Equal(t, notRunning.Service, "web") + assert.Equal(t, notRunning.Index, tt.index) + }) + } +}