types: add gws field to Route for ECMP suppor

Add a GWs []net.IP field to the Route struct to enable ECMP
(Equal-Cost Multi-Path) routing via multiple next hops.

When both GW and GWs are set, GW is treated as an additional next
hop appended after GWs. The NextHops() method returns the combined
list for use by plugin implementations.

Also document the gws field and its merge behavior in SPEC.md.

Signed-off-by: Yusho Yamaguchi <ys-yamaguchi@kddi.com>

Author: yushoyamaguchi

SPEC.md

@@ -585,6 +585,7 @@ Plugins must output a JSON object with the following keys upon a successful `ADD
 - `routes`: Routes created by this attachment:
     - `dst`: The destination of the route, in CIDR notation
     - `gw`: The next hop address. If unset, a value in `gateway` in the `ips` array may be used.
+    - `gws` (list of strings, optional): A list of next hop addresses for ECMP (Equal-Cost Multi-Path) routing. Each entry is an IP address string. If both `gw` and `gws` are set, `gw` is treated as an additional next hop appended after the entries in `gws`.
     - `mtu` (uint): The MTU (Maximum transmission unit) along the path to the destination.
     - `advmss` (uint): The MSS (Maximal Segment Size) to advertise to these destinations when establishing TCP connections.
     - `priority` (uint): The priority of route, lower is higher.

pkg/types/types.go

@@ -180,6 +180,7 @@ func (d *DNS) Copy() *DNS {
 type Route struct {
 	Dst      net.IPNet
 	GW       net.IP
+	GWs      []net.IP
 	MTU      int
 	AdvMSS   int
 	Priority int
@@ -198,7 +199,7 @@ func (r *Route) String() string {
 		scope = fmt.Sprintf("%d", *r.Scope)
 	}
 
-	return fmt.Sprintf("{Dst:%+v GW:%v MTU:%d AdvMSS:%d Priority:%d Table:%s Scope:%s}", r.Dst, r.GW, r.MTU, r.AdvMSS, r.Priority, table, scope)
+	return fmt.Sprintf("{Dst:%+v GW:%v GWs:%v MTU:%d AdvMSS:%d Priority:%d Table:%s Scope:%s}", r.Dst, r.GW, r.GWs, r.MTU, r.AdvMSS, r.Priority, table, scope)
 }
 
 func (r *Route) Copy() *Route {
@@ -215,6 +216,11 @@ func (r *Route) Copy() *Route {
 		Scope:    r.Scope,
 	}
 
+	if len(r.GWs) > 0 {
+		route.GWs = make([]net.IP, len(r.GWs))
+		copy(route.GWs, r.GWs)
+	}
+
 	if r.Table != nil {
 		table := *r.Table
 		route.Table = &table
@@ -228,6 +234,22 @@ func (r *Route) Copy() *Route {
 	return route
 }
 
+// NextHops returns the combined gateway list for ECMP routing.
+// If GW is set and not already present in GWs, it is appended after GWs.
+func (r *Route) NextHops() []net.IP {
+	gws := make([]net.IP, len(r.GWs))
+	copy(gws, r.GWs)
+	if r.GW != nil {
+		for _, gw := range r.GWs {
+			if gw.Equal(r.GW) {
+				return gws
+			}
+		}
+		gws = append(gws, r.GW)
+	}
+	return gws
+}
+
 // Well known error codes
 // see https://github.com/containernetworking/cni/blob/main/SPEC.md#error
 const (
@@ -277,13 +299,14 @@ func (e *Error) Print() error {
 
 // JSON (un)marshallable types
 type route struct {
-	Dst      IPNet  `json:"dst"`
-	GW       net.IP `json:"gw,omitempty"`
-	MTU      int    `json:"mtu,omitempty"`
-	AdvMSS   int    `json:"advmss,omitempty"`
-	Priority int    `json:"priority,omitempty"`
-	Table    *int   `json:"table,omitempty"`
-	Scope    *int   `json:"scope,omitempty"`
+	Dst      IPNet    `json:"dst"`
+	GW       net.IP   `json:"gw,omitempty"`
+	GWs      []net.IP `json:"gws,omitempty"`
+	MTU      int      `json:"mtu,omitempty"`
+	AdvMSS   int      `json:"advmss,omitempty"`
+	Priority int      `json:"priority,omitempty"`
+	Table    *int     `json:"table,omitempty"`
+	Scope    *int     `json:"scope,omitempty"`
 }
 
 func (r *Route) UnmarshalJSON(data []byte) error {
@@ -294,6 +317,7 @@ func (r *Route) UnmarshalJSON(data []byte) error {
 
 	r.Dst = net.IPNet(rt.Dst)
 	r.GW = rt.GW
+	r.GWs = rt.GWs
 	r.MTU = rt.MTU
 	r.AdvMSS = rt.AdvMSS
 	r.Priority = rt.Priority
@@ -307,6 +331,7 @@ func (r Route) MarshalJSON() ([]byte, error) {
 	rt := route{
 		Dst:      IPNet(r.Dst),
 		GW:       r.GW,
+		GWs:      r.GWs,
 		MTU:      r.MTU,
 		AdvMSS:   r.AdvMSS,
 		Priority: r.Priority,

pkg/types/types_test.go

@@ -107,6 +107,19 @@ var _ = Describe("Types", func() {
 			Expect(unmarshaled).To(Equal(example))
 		})
 
+		It("marshals and unmarshals gws to JSON", func() {
+			example.GWs = []net.IP{net.ParseIP("1.2.3.2"), net.ParseIP("1.2.3.3")}
+			jsonBytes, err := json.Marshal(example)
+			Expect(err).NotTo(HaveOccurred())
+			Expect(jsonBytes).To(MatchJSON(`{ "dst": "1.2.3.0/24", "gw": "1.2.3.1", "gws": ["1.2.3.2", "1.2.3.3"], "mtu": 1500, "advmss": 1340, "priority": 100, "table": 50, "scope": 253 }`))
+
+			var unmarshaled types.Route
+			Expect(json.Unmarshal(jsonBytes, &unmarshaled)).To(Succeed())
+			Expect(unmarshaled.GWs).To(HaveLen(2))
+			Expect(unmarshaled.GWs[0].String()).To(Equal("1.2.3.2"))
+			Expect(unmarshaled.GWs[1].String()).To(Equal("1.2.3.3"))
+		})
+
 		Context("when the json data is not valid", func() {
 			Specify("UnmarshalJSON returns an error", func() {
 				route := new(types.Route)
@@ -116,7 +129,38 @@ var _ = Describe("Types", func() {
 		})
 
 		It("formats as a string with a hex mask", func() {
-			Expect(example.String()).To(Equal(`{Dst:{IP:1.2.3.0 Mask:ffffff00} GW:1.2.3.1 MTU:1500 AdvMSS:1340 Priority:100 Table:50 Scope:253}`))
+			Expect(example.String()).To(Equal(`{Dst:{IP:1.2.3.0 Mask:ffffff00} GW:1.2.3.1 GWs:[] MTU:1500 AdvMSS:1340 Priority:100 Table:50 Scope:253}`))
+		})
+
+		It("NextHops returns only GWs when GW is nil", func() {
+			example.GW = nil
+			example.GWs = []net.IP{net.ParseIP("1.2.3.2"), net.ParseIP("1.2.3.3")}
+			gws := example.NextHops()
+			Expect(gws).To(HaveLen(2))
+			Expect(gws[0].String()).To(Equal("1.2.3.2"))
+			Expect(gws[1].String()).To(Equal("1.2.3.3"))
+		})
+
+		It("NextHops appends GW after GWs when both are set", func() {
+			example.GWs = []net.IP{net.ParseIP("1.2.3.2"), net.ParseIP("1.2.3.3")}
+			gws := example.NextHops()
+			Expect(gws).To(HaveLen(3))
+			Expect(gws[0].String()).To(Equal("1.2.3.2"))
+			Expect(gws[1].String()).To(Equal("1.2.3.3"))
+			Expect(gws[2].String()).To(Equal("1.2.3.1"))
+		})
+
+		It("NextHops returns empty slice when both GW and GWs are unset", func() {
+			example.GW = nil
+			Expect(example.NextHops()).To(BeEmpty())
+		})
+
+		It("NextHops does not append GW if already present in GWs", func() {
+			example.GWs = []net.IP{net.ParseIP("1.2.3.2"), example.GW}
+			gws := example.NextHops()
+			Expect(gws).To(HaveLen(2))
+			Expect(gws[0].String()).To(Equal("1.2.3.2"))
+			Expect(gws[1].String()).To(Equal("1.2.3.1"))
 		})
 	})