allow the API to toggle switch ports

.gitignore

@@ -5,3 +5,4 @@ vendor
 generate
 coverage.out
 __debug_bin
+.mirrord

.golangci.yaml

@@ -3,4 +3,8 @@ run:
   deadline: 10m
 linters:
   disable:
-    - musttag
+    - musttag
+  enable:
+    - testifylint
+    - unused
+fast: true

Makefile

@@ -53,7 +53,7 @@ protoc:
 .PHONY: mini-lab-push
 mini-lab-push:
 	make
-	docker build -f Dockerfile.dev -t metalstack/metal-api:latest .
+	docker build -f Dockerfile -t metalstack/metal-api:latest .
 	kind --name metal-control-plane load docker-image metalstack/metal-api:latest
 	kubectl --kubeconfig=$(MINI_LAB_KUBECONFIG) patch deployments.apps -n metal-control-plane metal-api --patch='{"spec":{"template":{"spec":{"containers":[{"name": "metal-api","imagePullPolicy":"IfNotPresent","image":"metalstack/metal-api:latest"}]}}}}'
 	kubectl --kubeconfig=$(MINI_LAB_KUBECONFIG) delete pod -n metal-control-plane -l app=metal-api

cmd/metal-api/internal/metal/network.go

@@ -6,6 +6,33 @@ import (
 	"strings"
 )
 
+// SwitchPortStatus is a type alias for a string that represents the status of a switch port.
+// Valid values are defined as constants in this package.
+type SwitchPortStatus string
+
+// SwitchPortStatus defines the possible statuses for a switch port.
+// UNKNOWN indicates the status is not known.
+// UP indicates the port is up and operational.
+// DOWN indicates the port is down and not operational.
+const (
+	SwitchPortStatusUnknown SwitchPortStatus = "UNKNOWN"
+	SwitchPortStatusUp      SwitchPortStatus = "UP"
+	SwitchPortStatusDown    SwitchPortStatus = "DOWN"
+)
+
+// IsConcrete returns true if the SwitchPortStatus is UP or DOWN,
+// which are concrete, known statuses. It returns false if the status
+// is UNKNOWN, which indicates the status is not known.
+func (s SwitchPortStatus) IsConcrete() bool {
+	return s == SwitchPortStatusUp || s == SwitchPortStatusDown
+}
+
+// IsValid returns true if the SwitchPortStatus is a known valid value
+// (UP, DOWN, UNKNOWN).
+func (s SwitchPortStatus) IsValid() bool {
+	return s == SwitchPortStatusUp || s == SwitchPortStatusDown || s == SwitchPortStatusUnknown
+}
+
 // A MacAddress is the type for mac addresses. When using a
 // custom type, we cannot use strings directly.
 type MacAddress string
@@ -18,6 +45,103 @@ type Nic struct {
 	Vrf        string     `rethinkdb:"vrf" json:"vrf"`
 	Neighbors  Nics       `rethinkdb:"neighbors" json:"neighbors"`
 	Hostname   string     `rethinkdb:"hostname" json:"hostname"`
+	State      *NicState  `rethinkdb:"state" json:"state"`
+}
+
+// NicState represents the desired and actual state of a network interface
+// controller (NIC). The Desired field indicates the intended state of the
+// NIC, while Actual indicates its current operational state. The Desired
+// state will be removed when the actuale state is equal to the desired state.
+type NicState struct {
+	Desired *SwitchPortStatus `rethinkdb:"desired" json:"desired"`
+	Actual  SwitchPortStatus  `rethinkdb:"actual" json:"actual"`
+}
+
+// SetState updates the NicState with the given SwitchPortStatus. It returns
+// a new NicState and a bool indicating if the state was changed.
+//
+// If the given status matches the current Actual state, it checks if Desired
+// is set and matches too. If so, Desired is set to nil since the desired
+// state has been reached.
+//
+// If the given status differs from the current Actual state, Desired is left
+// unchanged if it differes from the new state so the desired state is still tracked.
+// The Actual state is updated to the given status.
+//
+// This allows tracking both the desired and actual states, while clearing
+// Desired once the desired state is achieved.
+func (ns *NicState) SetState(s SwitchPortStatus) (NicState, bool) {
+	if ns == nil {
+		return NicState{
+			Actual:  s,
+			Desired: nil,
+		}, true
+	}
+	if ns.Actual == s {
+		if ns.Desired != nil {
+			if *ns.Desired == s {
+				// we now have the desired state, so set the desired state to nil
+				return NicState{
+					Actual:  s,
+					Desired: nil,
+				}, true
+			} else {
+				// we already have the reported state, but the desired one is different
+				// so nothing changed
+				return *ns, false
+			}
+		}
+		// nothing changed
+		return *ns, false
+	}
+	// we got another state as we had before
+	if ns.Desired != nil {
+		if *ns.Desired == s {
+			// we now have the desired state, so set the desired state to nil
+			return NicState{
+				Actual:  s,
+				Desired: nil,
+			}, true
+		} else {
+			// we already have the reported state, but the desired one is different
+			// so nothing changed
+			return NicState{
+				Actual:  s,
+				Desired: ns.Desired,
+			}, true
+		}
+	}
+	return NicState{
+		Actual:  s,
+		Desired: nil,
+	}, true
+}
+
+// WantState sets the desired state for the NIC. It returns a new NicState
+// struct with the desired state set and a bool indicating if the state changed.
+// If the current state already matches the desired state, it returns a state
+// with a cleared desired field.
+func (ns *NicState) WantState(s SwitchPortStatus) (NicState, bool) {
+	if ns == nil {
+		return NicState{
+			Actual:  SwitchPortStatusUnknown,
+			Desired: &s,
+		}, true
+	}
+	if ns.Actual == s {
+		// we want a state we already have
+		if ns.Desired != nil {
+			return NicState{
+				Actual:  s,
+				Desired: nil,
+			}, true
+		}
+		return *ns, false
+	}
+	return NicState{
+		Actual:  ns.Actual,
+		Desired: &s,
+	}, true
 }
 
 // GetIdentifier returns the identifier of a nic.

cmd/metal-api/internal/service/switch-service.go

@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"net/http"
 	"sort"
+	"strings"
 	"time"
 
 	"github.com/avast/retry-go/v4"
@@ -104,6 +105,17 @@ func (r *switchResource) webService() *restful.WebService {
 		Returns(http.StatusConflict, "Conflict", httperrors.HTTPErrorResponse{}).
 		DefaultReturns("Error", httperrors.HTTPErrorResponse{}))
 
+	ws.Route(ws.POST("/{id}/port").
+		To(admin(r.toggleSwitchPort)).
+		Operation("toggleSwitchPort").
+		Param(ws.PathParameter("id", "identifier of the switch").DataType("string")).
+		Doc("toggles the port of the switch with a nicname to the given state").
+		Metadata(restfulspec.KeyOpenAPITags, tags).
+		Reads(v1.SwitchPortToggleRequest{}).
+		Returns(http.StatusOK, "OK", v1.SwitchResponse{}).
+		Returns(http.StatusConflict, "Conflict", httperrors.HTTPErrorResponse{}).
+		DefaultReturns("Error", httperrors.HTTPErrorResponse{}))
+
 	ws.Route(ws.POST("/{id}/notify").
 		To(editor(r.notifySwitch)).
 		Doc("notify the metal-api about a configuration change of a switch").
@@ -244,9 +256,107 @@ func (r *switchResource) notifySwitch(request *restful.Request, response *restfu
 		return
 	}
 
+	oldSwitch, err := r.ds.FindSwitch(id)
+	if err != nil {
+		r.sendError(request, response, defaultError(err))
+		return
+	}
+
+	newSwitch := *oldSwitch
+	switchUpdated := false
+	for i, nic := range newSwitch.Nics {
+		state, has := requestPayload.PortStates[strings.ToLower(nic.Name)]
+		if has {
+			reported := metal.SwitchPortStatus(state)
+			newstate, changed := nic.State.SetState(reported)
+			if changed {
+				newSwitch.Nics[i].State = &newstate
+				switchUpdated = true
+			}
+		} else {
+			// this should NEVER happen; if the switch reports the state of an unknown port
+			// we log this and ignore it, but something is REALLY wrong in this case
+			r.log.Error("unknown switch port", "id", id, "nic", nic.Name)
+		}
+	}
+
+	if switchUpdated {
+		if err := r.ds.UpdateSwitch(oldSwitch, &newSwitch); err != nil {
+			r.sendError(request, response, defaultError(err))
+			return
+		}
+	}
+
 	r.send(request, response, http.StatusOK, v1.NewSwitchNotifyResponse(&newSS))
 }
 
+// toggleSwitchPort handles a request to toggle the state of a port on a switch. It reads the request body, validates the requested status is concrete, finds the switch, updates its NIC state if needed, and returns the updated switch on success.
+// toggleSwitchPort handles a request to toggle the state of a port on a switch. It reads the request body to get the switch ID, NIC name and desired state. It finds the switch, updates the state of the matching NIC if needed, and returns the updated switch on success.
+func (r *switchResource) toggleSwitchPort(request *restful.Request, response *restful.Response) {
+	var requestPayload v1.SwitchPortToggleRequest
+	err := request.ReadEntity(&requestPayload)
+	if err != nil {
+		r.sendError(request, response, httperrors.BadRequest(err))
+		return
+	}
+
+	desired := metal.SwitchPortStatus(requestPayload.Status)
+
+	if !desired.IsConcrete() {
+		r.sendError(request, response, httperrors.BadRequest(fmt.Errorf("the status %q must be concrete", requestPayload.Status)))
+		return
+	}
+
+	id := request.PathParameter("id")
+	oldSwitch, err := r.ds.FindSwitch(id)
+	if err != nil {
+		r.sendError(request, response, defaultError(err))
+		return
+	}
+
+	newSwitch := *oldSwitch
+	updated := false
+	found := false
+
+	// Updates the state of a NIC on the switch if the requested state change is valid
+	//
+	// Loops through each NIC on the switch and checks if the name matches the
+	// requested NIC. If a match is found, it tries to update the NIC's state to
+	// the requested state. If the state change is valid, it sets the new state on
+	// the NIC and marks that an update was made.
+	for i, nic := range newSwitch.Nics {
+		// compre nic-names case-insensitive
+		if strings.EqualFold(nic.Name, requestPayload.NicName) {
+			found = true
+			newstate, changed := nic.State.WantState(desired)
+			if changed {
+				newSwitch.Nics[i].State = &newstate
+				updated = true
+				break
+			}
+		}
+	}
+	if !found {
+		r.sendError(request, response, httperrors.NotFound(fmt.Errorf("the nic %q does not exist in this switch", requestPayload.NicName)))
+		return
+	}
+
+	if updated {
+		if err := r.ds.UpdateSwitch(oldSwitch, &newSwitch); err != nil {
+			r.sendError(request, response, defaultError(err))
+			return
+		}
+	}
+
+	resp, err := makeSwitchResponse(&newSwitch, r.ds)
+	if err != nil {
+		r.sendError(request, response, defaultError(err))
+		return
+	}
+
+	r.send(request, response, http.StatusOK, resp)
+}
+
 func (r *switchResource) updateSwitch(request *restful.Request, response *restful.Response) {
 	var requestPayload v1.SwitchUpdateRequest
 	err := request.ReadEntity(&requestPayload)
@@ -732,6 +842,14 @@ func makeSwitchNics(s *metal.Switch, ips metal.IPsMap, machines metal.Machines)
 			Identifier: n.Identifier,
 			Vrf:        n.Vrf,
 			BGPFilter:  filter,
+			Actual:     v1.SwitchPortStatusUnknown,
+		}
+		if n.State != nil {
+			if n.State.Desired != nil {
+				nic.Actual = v1.SwitchPortStatus(*n.State.Desired)
+			} else {
+				nic.Actual = v1.SwitchPortStatus(n.State.Actual)
+			}
 		}
 		nics = append(nics, nic)
 	}