Skip to content

Commit b575fdb

Browse files
ndeloofndeloof
committed
introduce (reconcilation) Plan
String() is designed to make it easy to compare coomputed plan vs expectations Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
1 parent b8ba1da commit b575fdb

File tree

2 files changed

+303
-0
lines changed

2 files changed

+303
-0
lines changed

‎pkg/compose/plan.go‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
/*
2+
Copyright 2020 Docker Compose CLI authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package compose
18+
19+
import (
20+
"fmt"
21+
"strconv"
22+
"strings"
23+
"time"
24+
25+
"github.com/compose-spec/compose-go/v2/types"
26+
"github.com/moby/moby/api/types/container"
27+
)
28+
29+
// OperationType identifies the kind of atomic operation in a reconciliation plan.
30+
// Each operation maps to exactly one Docker API call.
31+
type OperationType int
32+
33+
const (
34+
// Network operations
35+
OpCreateNetwork OperationType = iota
36+
OpRemoveNetwork
37+
OpDisconnectNetwork
38+
OpConnectNetwork
39+
40+
// Volume operations
41+
OpCreateVolume
42+
OpRemoveVolume
43+
44+
// Container operations
45+
OpCreateContainer
46+
OpStartContainer
47+
OpStopContainer
48+
OpRemoveContainer
49+
OpRenameContainer
50+
)
51+
52+
// String returns the human-readable name of an OperationType.
53+
func (o OperationType) String() string {
54+
switch o {
55+
case OpCreateNetwork:
56+
return "CreateNetwork"
57+
case OpRemoveNetwork:
58+
return "RemoveNetwork"
59+
case OpDisconnectNetwork:
60+
return "DisconnectNetwork"
61+
case OpConnectNetwork:
62+
return "ConnectNetwork"
63+
case OpCreateVolume:
64+
return "CreateVolume"
65+
case OpRemoveVolume:
66+
return "RemoveVolume"
67+
case OpCreateContainer:
68+
return "CreateContainer"
69+
case OpStartContainer:
70+
return "StartContainer"
71+
case OpStopContainer:
72+
return "StopContainer"
73+
case OpRemoveContainer:
74+
return "RemoveContainer"
75+
case OpRenameContainer:
76+
return "RenameContainer"
77+
default:
78+
return fmt.Sprintf("Unknown(%d)", int(o))
79+
}
80+
}
81+
82+
// Operation describes a single atomic action to be performed by the executor.
83+
// It carries all the data needed to execute the operation without further
84+
// decision-making.
85+
type Operation struct {
86+
Type OperationType
87+
ResourceID string // e.g. "service:web:1", "network:backend", "volume:data"
88+
Cause string // why this operation is needed
89+
90+
// Resource-specific data (only the relevant fields are set per operation type)
91+
Service *types.ServiceConfig // for container operations
92+
Container *container.Summary // existing container (for stop/remove)
93+
Inherited *container.Summary // container to inherit anonymous volumes from (for create-as-replacement)
94+
Number int // container replica number (for create)
95+
Name string // target container/resource name
96+
Network *types.NetworkConfig // for network operations
97+
Volume *types.VolumeConfig // for volume operations
98+
Timeout *time.Duration // for stop operations
99+
}
100+
101+
// PlanNode is a single node in the reconciliation DAG. It represents one
102+
// atomic operation and its dependencies on other nodes.
103+
type PlanNode struct {
104+
ID int // numeric identifier (#1, #2, ...)
105+
Operation Operation
106+
DependsOn []*PlanNode // prerequisite operations
107+
Group string // event grouping key (e.g. "recreate:web:1"); empty for ungrouped nodes
108+
}
109+
110+
// Plan is a directed acyclic graph of operations produced by the reconciler.
111+
// Nodes are stored in topological order (dependencies before dependents).
112+
type Plan struct {
113+
Nodes []*PlanNode
114+
nextID int
115+
}
116+
117+
// addNode appends a new node to the plan and returns it.
118+
func (p *Plan) addNode(op Operation, group string, deps ...*PlanNode) *PlanNode {
119+
p.nextID++
120+
node := &PlanNode{
121+
ID: p.nextID,
122+
Operation: op,
123+
DependsOn: deps,
124+
Group: group,
125+
}
126+
p.Nodes = append(p.Nodes, node)
127+
return node
128+
}
129+
130+
// String renders the plan as a human-readable graph for testing and debugging.
131+
//
132+
// Format per line: [dep1,dep2] -> #id resource, operation, cause [group]
133+
//
134+
// Examples:
135+
//
136+
// [] -> #1 network:default, CreateNetwork, not found
137+
// [1] -> #2 service:web:1, CreateContainer, no existing container
138+
// [2] -> #3 service:web:1, StopContainer, replaced by #2 [recreate:web:1]
139+
func (p *Plan) String() string {
140+
var sb strings.Builder
141+
for _, node := range p.Nodes {
142+
deps := make([]string, len(node.DependsOn))
143+
for i, d := range node.DependsOn {
144+
deps[i] = strconv.Itoa(d.ID)
145+
}
146+
fmt.Fprintf(&sb, "[%s] -> #%d %s, %s, %s",
147+
strings.Join(deps, ","),
148+
node.ID,
149+
node.Operation.ResourceID,
150+
node.Operation.Type,
151+
node.Operation.Cause,
152+
)
153+
if node.Group != "" {
154+
fmt.Fprintf(&sb, " [%s]", node.Group)
155+
}
156+
sb.WriteByte('\n')
157+
}
158+
return sb.String()
159+
}
160+
161+
// IsEmpty returns true if the plan contains no operations.
162+
func (p *Plan) IsEmpty() bool {
163+
return len(p.Nodes) == 0
164+
}

‎pkg/compose/plan_test.go‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
/*
2+
Copyright 2020 Docker Compose CLI authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package compose
18+
19+
import (
20+
"testing"
21+
22+
"gotest.tools/v3/assert"
23+
)
24+
25+
func TestOperationTypeString(t *testing.T) {
26+
tests := []struct {
27+
op OperationType
28+
want string
29+
}{
30+
{OpCreateNetwork, "CreateNetwork"},
31+
{OpRemoveNetwork, "RemoveNetwork"},
32+
{OpDisconnectNetwork, "DisconnectNetwork"},
33+
{OpConnectNetwork, "ConnectNetwork"},
34+
{OpCreateVolume, "CreateVolume"},
35+
{OpRemoveVolume, "RemoveVolume"},
36+
{OpCreateContainer, "CreateContainer"},
37+
{OpStartContainer, "StartContainer"},
38+
{OpStopContainer, "StopContainer"},
39+
{OpRemoveContainer, "RemoveContainer"},
40+
{OpRenameContainer, "RenameContainer"},
41+
{OperationType(999), "Unknown(999)"},
42+
}
43+
for _, tt := range tests {
44+
assert.Equal(t, tt.op.String(), tt.want)
45+
}
46+
}
47+
48+
func TestPlanStringEmpty(t *testing.T) {
49+
p := &Plan{}
50+
assert.Equal(t, p.String(), "")
51+
assert.Assert(t, p.IsEmpty())
52+
}
53+
54+
func TestPlanStringNoDeps(t *testing.T) {
55+
p := &Plan{}
56+
p.addNode(Operation{
57+
Type: OpCreateNetwork,
58+
ResourceID: "network:default",
59+
Cause: "not found",
60+
}, "")
61+
p.addNode(Operation{
62+
Type: OpCreateVolume,
63+
ResourceID: "volume:data",
64+
Cause: "not found",
65+
}, "")
66+
67+
expected := "[] -> #1 network:default, CreateNetwork, not found\n" +
68+
"[] -> #2 volume:data, CreateVolume, not found\n"
69+
assert.Equal(t, p.String(), expected)
70+
assert.Assert(t, !p.IsEmpty())
71+
}
72+
73+
func TestPlanStringWithDeps(t *testing.T) {
74+
p := &Plan{}
75+
nw := p.addNode(Operation{
76+
Type: OpCreateNetwork,
77+
ResourceID: "network:default",
78+
Cause: "not found",
79+
}, "")
80+
vol := p.addNode(Operation{
81+
Type: OpCreateVolume,
82+
ResourceID: "volume:data",
83+
Cause: "not found",
84+
}, "")
85+
p.addNode(Operation{
86+
Type: OpCreateContainer,
87+
ResourceID: "service:db:1",
88+
Cause: "no existing container",
89+
}, "", nw, vol)
90+
91+
expected := "[] -> #1 network:default, CreateNetwork, not found\n" +
92+
"[] -> #2 volume:data, CreateVolume, not found\n" +
93+
"[1,2] -> #3 service:db:1, CreateContainer, no existing container\n"
94+
assert.Equal(t, p.String(), expected)
95+
}
96+
97+
func TestPlanStringWithGroup(t *testing.T) {
98+
p := &Plan{}
99+
create := p.addNode(Operation{
100+
Type: OpCreateContainer,
101+
ResourceID: "service:web:1",
102+
Cause: "config hash changed (tmpName)",
103+
}, "recreate:web:1")
104+
stop := p.addNode(Operation{
105+
Type: OpStopContainer,
106+
ResourceID: "service:web:1",
107+
Cause: "replaced by #1",
108+
}, "recreate:web:1", create)
109+
remove := p.addNode(Operation{
110+
Type: OpRemoveContainer,
111+
ResourceID: "service:web:1",
112+
Cause: "replaced by #1",
113+
}, "recreate:web:1", stop)
114+
p.addNode(Operation{
115+
Type: OpRenameContainer,
116+
ResourceID: "service:web:1",
117+
Cause: "finalize recreate",
118+
}, "recreate:web:1", remove)
119+
120+
expected := "[] -> #1 service:web:1, CreateContainer, config hash changed (tmpName) [recreate:web:1]\n" +
121+
"[1] -> #2 service:web:1, StopContainer, replaced by #1 [recreate:web:1]\n" +
122+
"[2] -> #3 service:web:1, RemoveContainer, replaced by #1 [recreate:web:1]\n" +
123+
"[3] -> #4 service:web:1, RenameContainer, finalize recreate [recreate:web:1]\n"
124+
assert.Equal(t, p.String(), expected)
125+
}
126+
127+
func TestPlanAddNodeAutoIncrements(t *testing.T) {
128+
p := &Plan{}
129+
n1 := p.addNode(Operation{Type: OpCreateNetwork, ResourceID: "a", Cause: "x"}, "")
130+
n2 := p.addNode(Operation{Type: OpCreateVolume, ResourceID: "b", Cause: "y"}, "")
131+
n3 := p.addNode(Operation{Type: OpCreateContainer, ResourceID: "c", Cause: "z"}, "", n1, n2)
132+
133+
assert.Equal(t, n1.ID, 1)
134+
assert.Equal(t, n2.ID, 2)
135+
assert.Equal(t, n3.ID, 3)
136+
assert.Equal(t, len(n3.DependsOn), 2)
137+
assert.Equal(t, n3.DependsOn[0].ID, 1)
138+
assert.Equal(t, n3.DependsOn[1].ID, 2)
139+
}

0 commit comments

Comments
 (0)