Skip to content

api/types/container: remove PortSet, PortMap#50681

Draft
thaJeztah wants to merge 6 commits intomoby:masterfrom
thaJeztah:rm_PortSet_PortMap
Draft

api/types/container: remove PortSet, PortMap#50681
thaJeztah wants to merge 6 commits intomoby:masterfrom
thaJeztah:rm_PortSet_PortMap

Conversation

@thaJeztah
Copy link
Member

@thaJeztah thaJeztah commented Aug 9, 2025

The PortSet and PortMap types don't carry a real meaning on their own. Their purpose is defined at locations where they're used, such as Container.ExposedPorts or Container.PortBindings.

Their documentation also shows this;

// PortSet is a collection of structs indexed by [PortRangeProto].
// PortMap is a collection of [PortBinding] indexed by [PortRangeProto].

Which, almost literally, describes what a map is. Substituting the types for their implementation doesn't lose any meaning;

// map[PortRangeProto]struct{} is a collection of structs indexed by [PortRangeProto].
// map[PortRangeProto][]PortBinding is a collection of [PortBinding] indexed by [PortRangeProto].

Neither type has any special handling connected to them (no methods or otherwise), so they are just maps with a fancy name attached. Worse, using the extra indirect induces cognitive load; it's not clear from the type that it's "just" a map, indexed by PortBinding, and it's not clear what (kind of) values are in the map.

There are cases where having a type defined can add value to provide a more in-depth description of their intent, but (as shown above) even that is not the case here.

I'm considering these types to be premature abstraction with no good value. As they are a "straight" copy of a map with the same signature, replacing these types preserves backward compatibility; existing code can assign either a PortSet or PortMap, or a map[PortRangeProto].. with the same signature, but we can deprecate the types to give users a nudge to use a regular map instead. The following shows that they are interchangeable;

type config1 struct {
    ExposedPorts container.PortSet
    PortBindings container.PortMap
}
type config2 struct {
    ExposedPorts map[container.PortRangeProto]struct{}
    PortBindings map[container.PortRangeProto][]container.PortBinding
}

var (
    ports         map[container.PortRangeProto]struct{}
    portBindings  map[container.PortRangeProto][]container.PortBinding
    ports2        container.PortSet
    portBindings2 container.PortMap
)
_ = config1{
    ExposedPorts: ports,
    PortBindings: portBindings,
}
_ = config1{
    ExposedPorts: ports2,
    PortBindings: portBindings2,
}
_ = config2{
    ExposedPorts: ports,
    PortBindings: portBindings,
}
_ = config2{
    ExposedPorts: ports2,
    PortBindings: portBindings2,
}

api/types/container: inline PortSet, PortMap in types

Use the underlying definition in types, instead of the PortSet and PortMap
types as intermediates.

This also shows that there's ambiguity in these definitions, because nat.Port
(container.PortRangeProto) allows either a individual port ("8080/tcp")
or a range of ports ("8080-8090/tcp"). The latter unlikely is supported
by our code.

That behavior was introduced in moby@47272f9, which changed nat.Port to
either be a Port, or a range of ports. However, it's debatable if that should
have modified the existing type or introduced a new type that's only used
for places where a range is expected.

To reduce ambiguity, we need to evaluate where the nat.Port / PortRangeProto
type is used, and if there's any places where it SHOULD accept a range.
For other places, we should consider having an alias with a more suitable
name (PortProto) - at least to be clearer on intent.

- What I did

- How I did it

- How to verify it

- Human readable description for the release notes

- A picture of a cute animal (not mandatory but encouraged)

@thaJeztah thaJeztah force-pushed the rm_PortSet_PortMap branch 2 times, most recently from bc11ee0 to f5d3b32 Compare August 12, 2025 07:50
@thaJeztah
Copy link
Member Author

Fun failure ("page not found"); looks like something fell through and created a generic 404 error;

=== Failed
=== FAIL: amd64.integration-cli TestDockerCLICpSuite/TestCpFromCaseD (0.25s)
    docker_cli_cp_from_container_test.go:164: assertion failed: 
        Command:  /usr/local/cli-integration/docker wait e38f57ace471643a98f12da8cf5879aef0eaf6c3b0bb606217a91fd3d830b510
        time="2025-08-12T07:56:51Z" level=error msg="error waiting for container: context canceled"
        ExitCode: 1
        Error:    exit status 1
        Stdout:   
        Stderr:   Error response from daemon: page not found
        
        
        Failures:
        ExitCode was 1 expected 0
        Expected no error
    --- FAIL: TestDockerCLICpSuite/TestCpFromCaseD (0.25s)

The `PortSet` and `PortMap` types don't carry a real meaning on their
own. Their purpose is defined at locations where they're used, such as
`Container.ExposedPorts` or `Container.PortBindings`.

Their documentation also shows this;

    // PortSet is a collection of structs indexed by [PortRangeProto].
    // PortMap is a collection of [PortBinding] indexed by [PortRangeProto].

Which, almost literally, describes what a map is. Substituting the types
for their implementation doesn't lose any meaning;

    // map[PortRangeProto]struct{} is a collection of structs indexed by [PortRangeProto].
    // map[PortRangeProto][]PortBinding is a collection of [PortBinding] indexed by [PortRangeProto].

Neither type has any special handling connected to them (no methods or
otherwise), so they are just maps with a fancy name attached. Worse,
using the extra indirect induces cognitive load; it's not clear from
the type that it's "just" a map, indexed by `PortBinding`, and it's
not clear what (kind of) values are in the map.

There are cases where having a type defined can add value to provide
a more in-depth description of their intent, but (as shown above) even
that is not the case here.

I'm considering these types to be premature abstraction with no good
value. As they are a "straight" copy of a map with the same signature,
replacing these types preserves backward compatibility; existing code
can assign either a `PortSet` or `PortMap`, or a `map[PortRangeProto]..`
with the same signature, but we can deprecate the types to give users
a nudge to use a regular map instead. The following shows that they are
interchangeable;

	type config1 struct {
		ExposedPorts container.PortSet
		PortBindings container.PortMap
	}
	type config2 struct {
		ExposedPorts map[container.PortRangeProto]struct{}
		PortBindings map[container.PortRangeProto][]container.PortBinding
	}

	var (
		ports         map[container.PortRangeProto]struct{}
		portBindings  map[container.PortRangeProto][]container.PortBinding
		ports2        container.PortSet
		portBindings2 container.PortMap
	)
	_ = config1{
		ExposedPorts: ports,
		PortBindings: portBindings,
	}
	_ = config1{
		ExposedPorts: ports2,
		PortBindings: portBindings2,
	}
	_ = config2{
		ExposedPorts: ports,
		PortBindings: portBindings,
	}
	_ = config2{
		ExposedPorts: ports2,
		PortBindings: portBindings2,
	}

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Use the underlying definition in types, instead of the `PortSet` and `PortMap`
types as intermediates.

This also shows that there's ambiguity in these definitions, because `nat.Port`
(`container.PortRangeProto`) allows either a individual port ("8080/tcp")
or a range of ports ("8080-8090/tcp"). The latter unlikely is supported
by our code.

That behavior was introduced in [moby/moby@47272f9], which changed `nat.Port` to
either be a Port, or a range of ports. However, it's debatable if that should
have modified the existing type or introduced a new type that's only used
for places where a range is expected.

To reduce ambiguity, we need to evaluate where the `nat.Port` / `PortRangeProto`
type is used, and if there's any places where it SHOULD accept a range.
For other places, we should consider having an alias with a more suitable
name (`PortProto`) - at least to be clearer on intent.

[moby/moby@47272f9]: moby@47272f9

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This one may need more discussion; we could keep it for convenience

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant