TEP-0090: Add Matrix Package

[TEP-0090][tep-0090] proposed executing a `PipelineTask` in parallel `TaskRuns` and `Runs` with substitutions from combinations of `Parameters` in a `Matrix`. In this change, we add the matrix package which generates the combinations of the `Parameters` in a `Matrix`. The types added are internal, and there are no user-facing changes in this PR. [tep-0090]: https://github.com/tektoncd/community/blob/main/teps/0090-matrix.md
tektoncd · Jun 3, 2022 · 8e99f73 · 8e99f73
1 parent 6078270
commit 8e99f73
Show file tree

Hide file tree

Showing 4 changed files with 473 additions and 0 deletions.
diff --git a/pkg/matrix/matrix.go b/pkg/matrix/matrix.go
@@ -0,0 +1,63 @@
+/*
+Copyright 2022 The Tekton 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 matrix
+
+import (
+	"strconv"
+
+	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
+)
+
+// FanOut produces combinations of Parameters of type String from a slice of Parameters of type Array.
+func FanOut(params []v1beta1.Param) Combinations {
+	var combinations []*Combination
+	for _, parameter := range params {
+		combinations = distributeParameter(parameter, combinations)
+	}
+	return combinations
+}
+
+func distributeParameter(param v1beta1.Param, existingCombinations Combinations) Combinations {
+	var expandedCombinations Combinations
+
+	// when there are no existing combinations, this is the first parameter in the matrix, so we initialize the
+	// combinations with the first Parameter
+	if len(existingCombinations) == 0 {
+		for i, value := range param.Value.ArrayVal {
+			expandedCombinations = append(expandedCombinations, createCombination(i, param.Name, value, []v1beta1.Param{}))
+		}
+		return expandedCombinations
+	}
+
+	// when there are existing combinations, this is a non-first parameter in the matrix, and we need to distribute
+	// it among the existing combinations
+	count := 0
+	for _, value := range param.Value.ArrayVal {
+		for _, combination := range existingCombinations {
+			expandedCombinations = append(expandedCombinations, createCombination(count, param.Name, value, combination.Params))
+			count++
+		}
+	}
+	return expandedCombinations
+}
+
+func createCombination(i int, name string, value string, parameters []v1beta1.Param) *Combination {
+	return &Combination{
+		MatrixID: strconv.Itoa(i),
+		Params: append(parameters, v1beta1.Param{
+			Name:  name,
+			Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: value},
+		}),
+	}
+}
diff --git a/pkg/matrix/matrix_test.go b/pkg/matrix/matrix_test.go
@@ -0,0 +1,153 @@
+/*
+Copyright 2022 The Tekton 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 matrix
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
+)
+
+func Test_FanOut(t *testing.T) {
+	tests := []struct {
+		name             string
+		matrix           []v1beta1.Param
+		wantCombinations Combinations
+	}{{
+		name: "single array in matrix",
+		matrix: []v1beta1.Param{{
+			Name:  "platform",
+			Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeArray, ArrayVal: []string{"linux", "mac", "windows"}},
+		}},
+		wantCombinations: Combinations{{
+			MatrixID: "0",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "linux"},
+			}},
+		}, {
+			MatrixID: "1",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "mac"},
+			}},
+		}, {
+			MatrixID: "2",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "windows"},
+			}},
+		}},
+	}, {
+		name: "multiple arrays in matrix",
+		matrix: []v1beta1.Param{{
+			Name:  "platform",
+			Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeArray, ArrayVal: []string{"linux", "mac", "windows"}},
+		}, {
+			Name:  "browser",
+			Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeArray, ArrayVal: []string{"chrome", "safari", "firefox"}},
+		}},
+		wantCombinations: Combinations{{
+			MatrixID: "0",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "linux"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "chrome"},
+			}},
+		}, {
+			MatrixID: "1",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "mac"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "chrome"},
+			}},
+		}, {
+			MatrixID: "2",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "windows"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "chrome"},
+			}},
+		}, {
+			MatrixID: "3",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "linux"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "safari"},
+			}},
+		}, {
+			MatrixID: "4",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "mac"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "safari"},
+			}},
+		}, {
+			MatrixID: "5",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "windows"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "safari"},
+			}},
+		}, {
+			MatrixID: "6",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "linux"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "firefox"},
+			}},
+		}, {
+			MatrixID: "7",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "mac"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "firefox"},
+			}},
+		}, {
+			MatrixID: "8",
+			Params: []v1beta1.Param{{
+				Name:  "platform",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "windows"},
+			}, {
+				Name:  "browser",
+				Value: v1beta1.ArrayOrString{Type: v1beta1.ParamTypeString, StringVal: "firefox"},
+			}},
+		}},
+	}}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotCombinations := FanOut(tt.matrix)
+			if d := cmp.Diff(tt.wantCombinations, gotCombinations); d != "" {
+				t.Errorf("Combinations of Parameters did not match the expected Combinations: %s", d)
+			}
+		})
+	}
+}
diff --git a/pkg/matrix/matrix_types.go b/pkg/matrix/matrix_types.go
@@ -0,0 +1,37 @@
+/*
+   Copyright 2022 The Tekton 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 matrix
+
+import "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
+
+// Combinations is a slice of combinations of Parameters from a Matrix.
+type Combinations []*Combination
+
+// Combination is a specific combination of Parameters from a Matrix.
+type Combination struct {
+	// MatrixID is an identification of a combination from Parameters in a Matrix.
+	MatrixID string
+
+	// Params is a specific combination of Parameters in a Matrix.
+	Params []v1beta1.Param
+}
+
+// ToMap converts a list of Combinations to a map where the key is the matrixId and the values are Parameters.
+func (combinations Combinations) ToMap() map[string][]v1beta1.Param {
+	m := map[string][]v1beta1.Param{}
+	for _, combination := range combinations {
+		m[combination.MatrixID] = combination.Params
+	}
+	return m
+}