refactor(inspect): move the read-only operations to internal/inspect

ps, ls, top, port, volumes, events and viz only read the state of a
project: they need the Docker API, the list of the project's containers
and the concurrency bound, nothing else of composeService.

They now live in internal/inspect, which declares that need as a Backend
interface. composeService implements it in a new file of pkg/compose and
forwards the seven api.Inspector methods, so no other file of pkg/compose
changes, and neither does the behavior: the service-level tests stay in
pkg/compose and run unchanged through the forwarders.

The few tiny helpers the operations share with the rest of pkg/compose
(canonical container name, concurrency-limited errgroup, project filter)
are copied for now: the shared kernel they belong to is a later step.

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
This commit is contained in:
Nicolas De Loof 2026-10-13 08:49:03 +02:00 • committed by Guillaume Lours
parent 72f134f20c
commit c22ab50a61
13 changed files with 404 additions and 72 deletions

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -27,9 +27,9 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) Events(ctx context.Context, projectName string, options api.EventsOptions) error {
func (s *Service) Events(ctx context.Context, projectName string, options api.EventsOptions) error {
projectName = strings.ToLower(projectName)
res := s.apiClient().Events(ctx, client.EventsListOptions{
res := s.backend.APIClient().Events(ctx, client.EventsListOptions{
Filters: projectFilter(projectName),
Since: options.Since,
Until: options.Until,

105
internal/inspect/inspect.go Normal file
View file

@ -0,0 +1,105 @@
/*
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 inspect implements the read-only operations that report on a
// project and its resources: ps, ls, top, port, volumes, events and viz.
package inspect
import (
"context"
"slices"
"strings"
"github.com/moby/moby/api/types/container"
"github.com/moby/moby/client"
"golang.org/x/sync/errgroup"
"github.com/docker/compose/v5/pkg/api"
)
// OneOff tells whether the containers of `compose run` are part of a listing.
type OneOff int
const (
// OneOffInclude lists the one-off containers along with the services' ones.
OneOffInclude OneOff = iota
// OneOffExclude leaves the one-off containers out.
OneOffExclude
)
// Backend is what the operations need from the engine they report on.
type Backend interface {
// APIClient talks to the Docker daemon.
APIClient() client.APIClient
// MaxConcurrency bounds the daemon calls made in parallel, 0 meaning no bound.
MaxConcurrency() int
// Containers lists the containers of a project, narrowed to services when given.
Containers(ctx context.Context, projectName string, oneOff OneOff, all bool, services ...string) ([]container.Summary, error)
// SpecifiedContainer returns the container of a service, the replica with
// the given index when it is above zero.
SpecifiedContainer(ctx context.Context, projectName string, oneOff OneOff, all bool, serviceName string, index int) (container.Summary, error)
}
// Service runs the inspection operations on a Backend.
type Service struct {
backend Backend
}
// New creates a Service reporting on the given Backend.
func New(backend Backend) *Service {
return &Service{backend: backend}
}
func projectFilter(projectName string) client.Filters {
return make(client.Filters).Add("label", api.ProjectLabel+"="+projectName)
}
// inServices keeps the containers of the given services.
func inServices(containers []container.Summary, services []string) []container.Summary {
var filtered []container.Summary
for _, ctr := range containers {
if slices.Contains(services, ctr.Labels[api.ServiceLabel]) {
filtered = append(filtered, ctr)
}
}
return filtered
}
// limitedGroup returns an errgroup running at most maxConcurrency goroutines at once.
func limitedGroup(ctx context.Context, maxConcurrency int) (*errgroup.Group, context.Context) {
eg, ctx := errgroup.WithContext(ctx)
if maxConcurrency > 0 {
eg.SetLimit(maxConcurrency)
}
return eg, ctx
}
// canonicalContainerName returns the name a container goes by, without the
// leading slash nor the link aliases.
func canonicalContainerName(c container.Summary) string {
if len(c.Names) == 0 {
// corner case, sometime happens on removal. return short ID as a safeguard value
return c.ID[:12]
}
// Names return container canonical name /foo + link aliases /linked_by/foo
for _, name := range c.Names {
if strings.LastIndex(name, "/") == 0 {
return name[1:]
}
}
return strings.TrimPrefix(c.Names[0], "/")
}

View file

@ -0,0 +1,114 @@
/*
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 inspect
import (
"context"
"testing"
"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"
"github.com/docker/compose/v5/pkg/mocks"
)
// fakeBackend serves canned containers and records how it was asked for them.
type fakeBackend struct {
apiClient client.APIClient
listed []container.Summary
oneOff OneOff
all bool
services []string
index int
}
func (f *fakeBackend) APIClient() client.APIClient { return f.apiClient }
func (f *fakeBackend) MaxConcurrency() int { return 2 }
func (f *fakeBackend) Containers(_ context.Context, _ string, oneOff OneOff, all bool, services ...string) ([]container.Summary, error) {
f.oneOff, f.all, f.services = oneOff, all, services
return f.listed, nil
}
func (f *fakeBackend) SpecifiedContainer(_ context.Context, _ string, oneOff OneOff, all bool, serviceName string, index int) (container.Summary, error) {
f.oneOff, f.all, f.services, f.index = oneOff, all, []string{serviceName}, index
return f.listed[0], nil
}
func summary(service, id string) container.Summary {
return container.Summary{
ID: id,
Names: []string{"/" + id},
Labels: map[string]string{api.ServiceLabel: service},
}
}
func TestPsOneOffContainersOnlyWithAll(t *testing.T) {
for _, all := range []bool{false, true} {
ctrl := gomock.NewController(t)
apiClient := mocks.NewMockAPIClient(ctrl)
apiClient.EXPECT().ContainerInspect(gomock.Any(), "web1", gomock.Any()).Return(client.ContainerInspectResult{}, nil)
backend := &fakeBackend{apiClient: apiClient, listed: []container.Summary{summary("web", "web1")}}
got, err := New(backend).Ps(t.Context(), "proj", api.PsOptions{All: all})
assert.NilError(t, err)
assert.Equal(t, len(got), 1)
assert.Equal(t, got[0].Service, "web")
assert.Equal(t, backend.all, all)
if all {
assert.Equal(t, backend.oneOff, OneOffInclude)
} else {
assert.Equal(t, backend.oneOff, OneOffExclude)
}
}
}
func TestPsKeepsTheRequestedServices(t *testing.T) {
ctrl := gomock.NewController(t)
apiClient := mocks.NewMockAPIClient(ctrl)
apiClient.EXPECT().ContainerInspect(gomock.Any(), "db1", gomock.Any()).Return(client.ContainerInspectResult{}, nil)
backend := &fakeBackend{apiClient: apiClient, listed: []container.Summary{summary("web", "web1"), summary("db", "db1")}}
got, err := New(backend).Ps(t.Context(), "proj", api.PsOptions{Services: []string{"db"}})
assert.NilError(t, err)
assert.Equal(t, len(got), 1)
assert.Equal(t, got[0].ID, "db1")
}
func TestPortsAsksForTheReplica(t *testing.T) {
backend := &fakeBackend{listed: []container.Summary{summary("web", "web2")}}
_, err := New(backend).Ports(t.Context(), "proj", "web", 0, api.PortOptions{Index: 2})
assert.NilError(t, err)
assert.DeepEqual(t, backend.services, []string{"web"})
assert.Equal(t, backend.index, 2)
assert.Equal(t, backend.oneOff, OneOffInclude)
assert.Equal(t, backend.all, false)
}
func TestCanonicalContainerName(t *testing.T) {
assert.Equal(t, canonicalContainerName(container.Summary{Names: []string{"/proj-web-1", "/other/web"}}), "proj-web-1")
assert.Equal(t, canonicalContainerName(container.Summary{Names: []string{"/linked_by/web"}}), "linked_by/web")
assert.Equal(t, canonicalContainerName(container.Summary{ID: "0123456789abcdef"}), "0123456789ab")
}

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -30,8 +30,8 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) List(ctx context.Context, options api.ListOptions) ([]api.Stack, error) {
list, err := s.apiClient().ContainerList(ctx, client.ContainerListOptions{
func (s *Service) List(ctx context.Context, options api.ListOptions) ([]api.Stack, error) {
list, err := s.backend.APIClient().ContainerList(ctx, client.ContainerListOptions{
Filters: make(client.Filters).Add("label", api.ProjectLabel).Add("label", api.ConfigHashLabel),
All: options.All,
})

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"fmt"

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -26,9 +26,9 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) Ports(ctx context.Context, projectName string, serviceName string, port uint16, options api.PortOptions) (api.PortPublishers, error) {
func (s *Service) Ports(ctx context.Context, projectName string, serviceName string, port uint16, options api.PortOptions) (api.PortPublishers, error) {
projectName = strings.ToLower(projectName)
ctr, err := s.getSpecifiedContainer(ctx, projectName, oneOffInclude, false, serviceName, options.Index)
ctr, err := s.backend.SpecifiedContainer(ctx, projectName, OneOffInclude, false, serviceName, options.Index)
if err != nil {
return nil, err
}

View file

@ -0,0 +1,61 @@
/*
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 inspect
import (
"testing"
"github.com/moby/moby/api/types/container"
"gotest.tools/v3/assert"
)
// TestContainerPublishersPreservesTieOrder guards against containerPublishers
// reordering same-PrivatePort entries (e.g. a dual-stack publish exposing the
// same target port on both an IPv4 and an IPv6 host address): Ports() picks
// publishers[0] as *the* answer for a single-port lookup, so a sort that
// merely orders by PrivatePort must not additionally scramble ties.
//
// sort.Slice's pdqsort falls back to a (stable) insertion sort for slices of
// <=12 elements, so a small fixture can't tell a stable sort from an unstable
// one; this uses enough tied groups to force the quicksort partitioning path.
func TestContainerPublishersPreservesTieOrder(t *testing.T) {
var ports []container.PortSummary
privatePorts := []int{80, 53, 443}
for _, pp := range privatePorts {
for i := range 5 {
ports = append(ports, container.PortSummary{
PrivatePort: uint16(pp),
PublicPort: uint16(i), // tags each tied entry with its input position
Type: "tcp",
})
}
}
ports = append(ports, container.PortSummary{PrivatePort: 22, PublicPort: 0, Type: "tcp"})
ctr := container.Summary{ID: "123", Ports: ports}
got := containerPublishers(ctr)
lastPosByTargetPort := map[int]int{}
for _, p := range got {
pos := p.PublishedPort
if prev, ok := lastPosByTargetPort[p.TargetPort]; ok {
assert.Assert(t, pos > prev, "tied entries for private port %d out of input order: got position %d after %d", p.TargetPort, pos, prev)
}
lastPosByTargetPort[p.TargetPort] = pos
}
}

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -27,22 +27,22 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) Ps(ctx context.Context, projectName string, options api.PsOptions) ([]api.ContainerSummary, error) {
func (s *Service) Ps(ctx context.Context, projectName string, options api.PsOptions) ([]api.ContainerSummary, error) {
projectName = strings.ToLower(projectName)
oneOff := oneOffExclude
oneOff := OneOffExclude
if options.All {
oneOff = oneOffInclude
oneOff = OneOffInclude
}
containers, err := s.getContainers(ctx, projectName, oneOff, options.All, options.Services...)
containers, err := s.backend.Containers(ctx, projectName, oneOff, options.All, options.Services...)
if err != nil {
return nil, err
}
if len(options.Services) != 0 {
containers = containers.filter(isService(options.Services...))
containers = inServices(containers, options.Services)
}
summary := make([]api.ContainerSummary, len(containers))
eg, ctx := newLimitedErrgroup(ctx, s.maxConcurrency)
eg, ctx := limitedGroup(ctx, s.backend.MaxConcurrency())
for i, ctr := range containers {
eg.Go(func() error {
var err error
@ -55,8 +55,8 @@ func (s *composeService) Ps(ctx context.Context, projectName string, options api
// containerSummary builds the api summary for a container, inspecting it to
// retrieve its health and exit code
func (s *composeService) containerSummary(ctx context.Context, ctr container.Summary) (api.ContainerSummary, error) {
inspect, err := s.apiClient().ContainerInspect(ctx, ctr.ID, client.ContainerInspectOptions{})
func (s *Service) containerSummary(ctx context.Context, ctr container.Summary) (api.ContainerSummary, error) {
inspect, err := s.backend.APIClient().ContainerInspect(ctx, ctr.ID, client.ContainerInspectOptions{})
if err != nil {
return api.ContainerSummary{}, err
}
@ -64,7 +64,7 @@ func (s *composeService) containerSummary(ctx context.Context, ctr container.Sum
mounts, localVolumes := containerMounts(ctr)
return api.ContainerSummary{
ID: ctr.ID,
Name: getCanonicalContainerName(ctr),
Name: canonicalContainerName(ctr),
Names: ctr.Names,
Image: ctr.Image,
Project: ctr.Labels[api.ProjectLabel],

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -25,27 +25,26 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) Top(ctx context.Context, projectName string, services []string) ([]api.ContainerProcSummary, error) {
func (s *Service) Top(ctx context.Context, projectName string, services []string) ([]api.ContainerProcSummary, error) {
projectName = strings.ToLower(projectName)
var containers Containers
containers, err := s.getContainers(ctx, projectName, oneOffInclude, false)
containers, err := s.backend.Containers(ctx, projectName, OneOffInclude, false)
if err != nil {
return nil, err
}
if len(services) > 0 {
containers = containers.filter(isService(services...))
containers = inServices(containers, services)
}
summary := make([]api.ContainerProcSummary, len(containers))
eg, ctx := newLimitedErrgroup(ctx, s.maxConcurrency)
eg, ctx := limitedGroup(ctx, s.backend.MaxConcurrency())
for i, ctr := range containers {
eg.Go(func() error {
topContent, err := s.apiClient().ContainerTop(ctx, ctr.ID, client.ContainerTopOptions{
topContent, err := s.backend.APIClient().ContainerTop(ctx, ctr.ID, client.ContainerTopOptions{
Arguments: []string{},
})
if err != nil {
return err
}
name := getCanonicalContainerName(ctr)
name := canonicalContainerName(ctr)
s := api.ContainerProcSummary{
ID: ctr.ID,
Name: name,

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -29,7 +29,7 @@ import (
// maps a service with the services it depends on
type vizGraph map[*types.ServiceConfig][]*types.ServiceConfig
func (s *composeService) Viz(_ context.Context, project *types.Project, options api.VizOptions) (string, error) {
func (s *Service) Viz(_ context.Context, project *types.Project, options api.VizOptions) (string, error) {
graph := make(vizGraph)
for _, service := range project.Services {
graph[&service] = make([]*types.ServiceConfig, 0, len(service.DependsOn))

View file

@ -14,7 +14,7 @@
limitations under the License.
*/
package compose
package inspect
import (
"context"
@ -26,8 +26,8 @@ import (
"github.com/docker/compose/v5/pkg/api"
)
func (s *composeService) Volumes(ctx context.Context, projectName string, options api.VolumesOptions) ([]api.VolumesSummary, error) {
allContainers, err := s.apiClient().ContainerList(ctx, client.ContainerListOptions{
func (s *Service) Volumes(ctx context.Context, projectName string, options api.VolumesOptions) ([]api.VolumesSummary, error) {
allContainers, err := s.backend.APIClient().ContainerList(ctx, client.ContainerListOptions{
Filters: projectFilter(projectName),
})
if err != nil {
@ -47,7 +47,7 @@ func (s *composeService) Volumes(ctx context.Context, projectName string, option
containers = allContainers.Items
}
volumesResponse, err := s.apiClient().VolumeList(ctx, client.VolumeListOptions{
volumesResponse, err := s.backend.APIClient().VolumeList(ctx, client.VolumeListOptions{
Filters: projectFilter(projectName),
})
if err != nil {

91
pkg/compose/inspect.go Normal file
View file

@ -0,0 +1,91 @@
/*
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 (
"context"
"github.com/compose-spec/compose-go/v2/types"
"github.com/moby/moby/api/types/container"
"github.com/moby/moby/client"
"github.com/docker/compose/v5/internal/inspect"
"github.com/docker/compose/v5/pkg/api"
)
// The read-only operations live in internal/inspect: composeService serves
// them by handing that package the engine it reports on.
func (s *composeService) inspector() *inspect.Service {
return inspect.New(inspectBackend{s})
}
func (s *composeService) List(ctx context.Context, options api.ListOptions) ([]api.Stack, error) {
return s.inspector().List(ctx, options)
}
func (s *composeService) Ps(ctx context.Context, projectName string, options api.PsOptions) ([]api.ContainerSummary, error) {
return s.inspector().Ps(ctx, projectName, options)
}
func (s *composeService) Top(ctx context.Context, projectName string, services []string) ([]api.ContainerProcSummary, error) {
return s.inspector().Top(ctx, projectName, services)
}
func (s *composeService) Ports(ctx context.Context, projectName string, serviceName string, port uint16, options api.PortOptions) (api.PortPublishers, error) {
return s.inspector().Ports(ctx, projectName, serviceName, port, options)
}
func (s *composeService) Volumes(ctx context.Context, projectName string, options api.VolumesOptions) ([]api.VolumesSummary, error) {
return s.inspector().Volumes(ctx, projectName, options)
}
func (s *composeService) Events(ctx context.Context, projectName string, options api.EventsOptions) error {
return s.inspector().Events(ctx, projectName, options)
}
func (s *composeService) Viz(ctx context.Context, project *types.Project, options api.VizOptions) (string, error) {
return s.inspector().Viz(ctx, project, options)
}
// inspectBackend is the engine of a composeService, as internal/inspect sees it.
type inspectBackend struct {
s *composeService
}
func (b inspectBackend) APIClient() client.APIClient {
return b.s.apiClient()
}
func (b inspectBackend) MaxConcurrency() int {
return b.s.maxConcurrency
}
func (b inspectBackend) Containers(ctx context.Context, projectName string, oneOff inspect.OneOff, all bool, services ...string) ([]container.Summary, error) {
return b.s.getContainers(ctx, projectName, toOneOff(oneOff), all, services...)
}
func (b inspectBackend) SpecifiedContainer(ctx context.Context, projectName string, oneOff inspect.OneOff, all bool, serviceName string, index int) (container.Summary, error) {
return b.s.getSpecifiedContainer(ctx, projectName, toOneOff(oneOff), all, serviceName, index)
}
func toOneOff(v inspect.OneOff) oneOff {
if v == inspect.OneOffExclude {
return oneOffExclude
}
return oneOffInclude
}

View file

@ -106,41 +106,3 @@ func TestPorts(t *testing.T) {
})
}
}
// TestContainerPublishersPreservesTieOrder guards against containerPublishers
// reordering same-PrivatePort entries (e.g. a dual-stack publish exposing the
// same target port on both an IPv4 and an IPv6 host address): Ports() picks
// publishers[0] as *the* answer for a single-port lookup, so a sort that
// merely orders by PrivatePort must not additionally scramble ties.
//
// sort.Slice's pdqsort falls back to a (stable) insertion sort for slices of
// <=12 elements, so a small fixture can't tell a stable sort from an unstable
// one; this uses enough tied groups to force the quicksort partitioning path.
func TestContainerPublishersPreservesTieOrder(t *testing.T) {
var ports []container.PortSummary
privatePorts := []int{80, 53, 443}
for _, pp := range privatePorts {
for i := range 5 {
ports = append(ports, container.PortSummary{
PrivatePort: uint16(pp),
PublicPort: uint16(i), // tags each tied entry with its input position
Type: "tcp",
})
}
}
ports = append(ports, container.PortSummary{PrivatePort: 22, PublicPort: 0, Type: "tcp"})
ctr := testContainer("web", "123", false)
ctr.Ports = ports
got := containerPublishers(ctr)
lastPosByTargetPort := map[int]int{}
for _, p := range got {
pos := p.PublishedPort
if prev, ok := lastPosByTargetPort[p.TargetPort]; ok {
assert.Assert(t, pos > prev, "tied entries for private port %d out of input order: got position %d after %d", p.TargetPort, pos, prev)
}
lastPosByTargetPort[p.TargetPort] = pos
}
}