feat: add ExpectedRack APIs (Create, Update, Get)

This adds `ExpectedRack` REST APIs to create, update, and get `ExpectedRack` instances, which is similar to the work for adding expected switch and power shelf API calls as well in #220. Tried to pattern match as much as possible again.

Tests included!

Signed-off-by: Chet Nichols III <chetn@nvidia.com>

Author: chet

api/pkg/api/handler/expectedrack.go

@@ -0,0 +1,243 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * 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 model
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+
+	validation "github.com/go-ozzo/ozzo-validation/v4"
+	validationis "github.com/go-ozzo/ozzo-validation/v4/is"
+
+	"github.com/NVIDIA/ncx-infra-controller-rest/api/pkg/api/model/util"
+	cdbm "github.com/NVIDIA/ncx-infra-controller-rest/db/pkg/db/model"
+)
+
+// APIExpectedRackCreateRequest is the data structure to capture request to create a new ExpectedRack
+type APIExpectedRackCreateRequest struct {
+	// SiteID is the ID of the Site the rack belongs to
+	SiteID string `json:"siteId"`
+	// RackID is the operator-supplied identifier for the rack (string, not UUID).
+	// Unique per Site.
+	RackID string `json:"rackId"`
+	// RackProfileID identifies the rack profile this rack conforms to
+	RackProfileID string `json:"rackProfileId"`
+	// Name is the optional human-readable name of the expected rack
+	Name *string `json:"name"`
+	// Description is the optional human-readable description of the expected rack
+	Description *string `json:"description"`
+	// Labels carries arbitrary key/value pairs. Well-known keys (chassis.*,
+	// location.*) are used to convey chassis identity and physical location.
+	Labels map[string]string `json:"labels"`
+}
+
+// Validate ensure the values passed in request are acceptable
+func (ercr *APIExpectedRackCreateRequest) Validate() error {
+	err := validation.ValidateStruct(ercr,
+		validation.Field(&ercr.SiteID,
+			validation.Required.Error(validationErrorValueRequired),
+			validationis.UUID.Error(validationErrorInvalidUUID)),
+		validation.Field(&ercr.RackID,
+			validation.Required.Error(validationErrorValueRequired),
+			validation.Match(util.NotAllWhitespaceRegexp).Error("RackID consists only of whitespace")),
+		validation.Field(&ercr.RackProfileID,
+			validation.Required.Error(validationErrorValueRequired),
+			validation.Match(util.NotAllWhitespaceRegexp).Error("RackProfileID consists only of whitespace")),
+		validation.Field(&ercr.Name,
+			validation.NilOrNotEmpty.Error("Name cannot be empty")),
+		validation.Field(&ercr.Description,
+			validation.NilOrNotEmpty.Error("Description cannot be empty")),
+	)
+
+	if err != nil {
+		return err
+	}
+
+	if err := util.ValidateLabels(ercr.Labels); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// APIExpectedRackUpdateRequest is the data structure to capture user request to update an ExpectedRack
+type APIExpectedRackUpdateRequest struct {
+	// ID is required for batch updates (must be empty or match path value for single update).
+	ID *string `json:"id"`
+	// RackID is the optional new operator-supplied rack identifier
+	RackID *string `json:"rackId"`
+	// RackProfileID is the optional new rack profile ID
+	RackProfileID *string `json:"rackProfileId"`
+	// Name is the optional new human-readable name of the expected rack
+	Name *string `json:"name"`
+	// Description is the optional new human-readable description of the expected rack
+	Description *string `json:"description"`
+	// Labels carries arbitrary key/value pairs. Well-known keys (chassis.*,
+	// location.*) are used to convey chassis identity and physical location.
+	Labels map[string]string `json:"labels"`
+}
+
+// Validate ensure the values passed in request are acceptable
+func (erur *APIExpectedRackUpdateRequest) Validate() error {
+	if erur.ID != nil {
+		if *erur.ID == "" {
+			return validation.Errors{
+				"id": errors.New("ID cannot be empty"),
+			}
+		}
+		if _, err := uuid.Parse(*erur.ID); err != nil {
+			return validation.Errors{
+				"id": errors.New("ID must be a valid UUID"),
+			}
+		}
+	}
+
+	err := validation.ValidateStruct(erur,
+		validation.Field(&erur.RackID,
+			validation.NilOrNotEmpty.Error("RackID cannot be empty"),
+			validation.When(erur.RackID != nil && *erur.RackID != "",
+				validation.Match(util.NotAllWhitespaceRegexp).Error("RackID consists only of whitespace"))),
+		validation.Field(&erur.RackProfileID,
+			validation.NilOrNotEmpty.Error("RackProfileID cannot be empty"),
+			validation.When(erur.RackProfileID != nil && *erur.RackProfileID != "",
+				validation.Match(util.NotAllWhitespaceRegexp).Error("RackProfileID consists only of whitespace"))),
+		validation.Field(&erur.Name,
+			validation.NilOrNotEmpty.Error("Name cannot be empty")),
+		validation.Field(&erur.Description,
+			validation.NilOrNotEmpty.Error("Description cannot be empty")),
+	)
+
+	if err != nil {
+		return err
+	}
+
+	if err := util.ValidateLabels(erur.Labels); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// APIExpectedRack is the data structure to capture API representation of an ExpectedRack
+type APIExpectedRack struct {
+	// ID is the unique identifier (UUID) of the expected rack
+	ID uuid.UUID `json:"id"`
+	// SiteID is the ID of the Site this rack belongs to
+	SiteID uuid.UUID `json:"siteId"`
+	// Site is the site information
+	Site *APISite `json:"site,omitempty"`
+	// RackID is the operator-supplied identifier for the rack
+	RackID string `json:"rackId"`
+	// RackProfileID identifies the rack profile this rack conforms to
+	RackProfileID string `json:"rackProfileId"`
+	// Name is the optional human-readable name of the expected rack
+	Name string `json:"name"`
+	// Description is the optional human-readable description of the expected rack
+	Description string `json:"description"`
+	// Labels carries arbitrary key/value pairs. Well-known keys (chassis.*,
+	// location.*) are used to convey chassis identity and physical location.
+	Labels map[string]string `json:"labels"`
+	// Created indicates the ISO datetime string for when the ExpectedRack was created
+	Created time.Time `json:"created"`
+	// Updated indicates the ISO datetime string for when the ExpectedRack was last updated
+	Updated time.Time `json:"updated"`
+}
+
+// NewAPIExpectedRack accepts a DB layer ExpectedRack object and returns an API object
+func NewAPIExpectedRack(dbModel *cdbm.ExpectedRack) *APIExpectedRack {
+	if dbModel == nil {
+		return nil
+	}
+
+	apier := &APIExpectedRack{
+		ID:            dbModel.ID,
+		SiteID:        dbModel.SiteID,
+		RackID:        dbModel.RackID,
+		RackProfileID: dbModel.RackProfileID,
+		Name:          dbModel.Name,
+		Description:   dbModel.Description,
+		Labels:        dbModel.Labels,
+		Created:       dbModel.Created,
+		Updated:       dbModel.Updated,
+	}
+
+	if dbModel.Site != nil {
+		site := NewAPISite(*dbModel.Site, []cdbm.StatusDetail{}, nil)
+		apier.Site = &site
+	}
+
+	return apier
+}
+
+// APIReplaceAllExpectedRacksRequest is the data structure to capture user request
+// to replace the full set of ExpectedRacks for a Site with the provided list.
+type APIReplaceAllExpectedRacksRequest struct {
+	// SiteID is the ID of the Site whose ExpectedRacks should be replaced
+	SiteID string `json:"siteId"`
+	// ExpectedRacks is the list of ExpectedRack create requests to use as the
+	// replacement set for the Site. May be empty to clear all ExpectedRacks
+	// for the Site.
+	ExpectedRacks []*APIExpectedRackCreateRequest `json:"expectedRacks"`
+}
+
+// Validate ensure the values passed in request are acceptable
+func (rar *APIReplaceAllExpectedRacksRequest) Validate() error {
+	err := validation.ValidateStruct(rar,
+		validation.Field(&rar.SiteID,
+			validation.Required.Error(validationErrorValueRequired),
+			validationis.UUID.Error(validationErrorInvalidUUID)),
+	)
+	if err != nil {
+		return err
+	}
+
+	// Validate every entry and ensure they all reference the same Site as the top-level SiteID
+	for i, er := range rar.ExpectedRacks {
+		if er == nil {
+			return validation.Errors{
+				"expectedRacks": errors.New("ExpectedRack entry cannot be null"),
+			}
+		}
+		if err := er.Validate(); err != nil {
+			return validation.Errors{
+				"expectedRacks": fmt.Errorf("entry %d: %w", i, err),
+			}
+		}
+		if er.SiteID != rar.SiteID {
+			return validation.Errors{
+				"expectedRacks": fmt.Errorf("entry %d: siteId does not match top-level siteId", i),
+			}
+		}
+	}
+
+	// Ensure rack IDs are unique within the request
+	seen := make(map[string]bool, len(rar.ExpectedRacks))
+	for i, er := range rar.ExpectedRacks {
+		if seen[er.RackID] {
+			return validation.Errors{
+				"expectedRacks": fmt.Errorf("entry %d: duplicate rackId %q", i, er.RackID),
+			}
+		}
+		seen[er.RackID] = true
+	}
+
+	return nil
+}