types: add gws field to Route for ECMP support

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` : A list of next hop addresses for ECMP (Equal-Cost Multi-Path) routing. Each entry is an IP address string.
     - `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
@@ -277,13 +283,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 +301,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 +315,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,8 +129,9 @@ 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}`))
 		})
+
 	})
 
 	Describe("Error type", func() {