various changes

README.md

@@ -1,7 +1,7 @@
 [![Go Reference](https://pkg.go.dev/badge/github.com/rschmied/gocmlclient.svg)](https://pkg.go.dev/github.com/rschmied/gocmlclient) [![CodeQL](https://github.com/rschmied/gocmlclient/actions/workflows/codeql.yml/badge.svg)](https://github.com/rschmied/gocmlclient/actions/workflows/codeql.yml) [![Go](https://github.com/rschmied/gocmlclient/actions/workflows/go.yml/badge.svg)](https://github.com/rschmied/gocmlclient/actions/workflows/go.yml) [![Coverage Status](https://coveralls.io/repos/github/rschmied/gocmlclient/badge.svg?branch=main)](https://coveralls.io/github/rschmied/gocmlclient?branch=main) [![Go Report Card](https://goreportcard.com/badge/github.com/rschmied/gocmlclient)](https://goreportcard.com/report/github.com/rschmied/gocmlclient)
 
 # gocmlclient
+
 A CML2 Client in Golang
 
 (c) Ralph Schmieder  2022
-

auth.go

@@ -61,16 +61,25 @@ func (c *Client) authenticate(ctx context.Context, userpass userPass, depth int3
 	return nil
 }
 
+// SetToken sets a specific API token to be used. A token takes precedence over
+// a username/password. However, if the token expires, the username/password are
+// used to authorize the client again. An error is raised if no token and no
+// username/password are provided or if the token expires when no username/password
+// are set.
 func (c *Client) SetToken(token string) {
 	c.apiToken = token
 }
 
+// SetUsernamePassword sets the username and the password to be used with the
+// client for all authentications.
 func (c *Client) SetUsernamePassword(username, password string) {
 	c.userpass = userPass{
 		username, password,
 	}
 }
 
+// SetCACert sets a specific X.509 CA certificate to use with the client.
+// If no cert is set, the system trust anchors are used for cert verification.
 func (c *Client) SetCACert(cert []byte) error {
 	caCertPool := x509.NewCertPool()
 	ok := caCertPool.AppendCertsFromPEM(cert)

cml.go

@@ -23,6 +23,8 @@ type Client struct {
 	useCache         bool
 }
 
+// NewClient returns a new CML client instance. The host must be a valid URL
+// including scheme (https://).
 func NewClient(host string, insecure, useCache bool) *Client {
 	tr := http.DefaultTransport.(*http.Transport)
 	tr.TLSClientConfig = &tls.Config{

go.mod

@@ -3,7 +3,7 @@ module github.com/rschmied/gocmlclient
 go 1.18
 
 require (
-	github.com/Masterminds/semver/v3 v3.1.1
+	github.com/Masterminds/semver/v3 v3.2.0
 	github.com/rschmied/mockresponder v1.0.3
 	github.com/stretchr/testify v1.8.0
 	golang.org/x/sync v0.1.0

go.sum

@@ -1,5 +1,7 @@
 github.com/Masterminds/semver/v3 v3.1.1 h1:hLg3sBzpNErnxhQtUy/mmLR2I9foDujNK030IGemrRc=
 github.com/Masterminds/semver/v3 v3.1.1/go.mod h1:VPu/7SZ7ePZ3QOrcuXROw5FAcLl4a0cBrbBpGY/8hQs=
+github.com/Masterminds/semver/v3 v3.2.0 h1:3MEsd0SM6jqZojhjLWWeBY+Kcjy9i6MQAeY7YgDP83g=
+github.com/Masterminds/semver/v3 v3.2.0/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

iface.go

@@ -222,6 +222,7 @@ func (c *Client) getInterfacesForNode(ctx context.Context, node *Node) error {
 // 	}
 // }
 
+// InterfaceGet returns the interface identified by its `ID` (iface.ID).
 func (c *Client) InterfaceGet(ctx context.Context, iface *Interface) (*Interface, error) {
 
 	if iface, ok := c.getCachedIface(iface); ok {
@@ -234,16 +235,22 @@ func (c *Client) InterfaceGet(ctx context.Context, iface *Interface) (*Interface
 }
 
 // InterfaceCreate creates an interface in the given lab and node.  If the slot
-// is not nil, the request creates all unallocated slots up to and including
-// that slot.
-func (c *Client) InterfaceCreate(ctx context.Context, labID, nodeID string, slot *int) (*Interface, error) {
+// is >= 0, the request creates all unallocated slots up to and including
+// that slot. Conversely, if the slot is < 0 (e.g. -1), the next free slot is used.
+func (c *Client) InterfaceCreate(ctx context.Context, labID, nodeID string, slot int) (*Interface, error) {
+
+	var slotPtr *int
+
+	if slot >= 0 {
+		slotPtr = &slot
+	}
 
 	newIface := struct {
 		Node string `json:"node"`
 		Slot *int   `json:"slot,omitempty"`
 	}{
 		Node: nodeID,
-		Slot: slot,
+		Slot: slotPtr,
 	}
 
 	buf := &bytes.Buffer{}
@@ -260,7 +267,7 @@ func (c *Client) InterfaceCreate(ctx context.Context, labID, nodeID string, slot
 	// one interface
 
 	api := fmt.Sprintf("labs/%s/interfaces", labID)
-	if slot == nil {
+	if slotPtr == nil {
 		result := Interface{}
 		err = c.jsonPost(ctx, api, buf, &result, 0)
 		if err != nil {

iface_test.go

@@ -73,8 +73,7 @@ func TestClient_IfaceWithSlots(t *testing.T) {
 		mr.MockResp{Data: ifaceList, URL: `/interfaces$`},
 	}
 	tc.mr.SetData(data)
-	slot := int(1)
-	iface, err := tc.client.InterfaceCreate(tc.ctx, "lab1", "node1", &slot)
+	iface, err := tc.client.InterfaceCreate(tc.ctx, "lab1", "node1", 1)
 	if assert.NoError(t, err) {
 		assert.Equal(t, "eth1", iface.Label)
 	}

imagedef.go

@@ -22,20 +22,23 @@ import "context"
 
 type ImageDefinition struct {
 	ID            string `json:"id"`
+	SchemaVersion string `json:"schema_version"`
 	NodeDefID     string `json:"node_definition_id"`
 	Description   string `json:"description"`
 	Label         string `json:"label"`
-	DiskImage     string `json:"disk_image"`
+	DiskImage1    string `json:"disk_image"`
+	DiskImage2    string `json:"disk_image_2"`
+	DiskImage3    string `json:"disk_image_3"`
 	ReadOnly      bool   `json:"read_only"`
+	DiskSubfolder string `json:"disk_subfolder"`
 	RAM           *int   `json:"ram"`
 	CPUs          *int   `json:"cpus"`
 	CPUlimit      *int   `json:"cpu_limit"`
 	DataVolume    *int   `json:"data_volume"`
 	BootDiskSize  *int   `json:"boot_disk_size"`
-	DiskSubfolder string `json:"disk_subfolder"`
-	SchemaVersion string `json:"schema_version"`
 }
 
+// GetImageDefs returns a list of image definitions known to the controller.
 func (c *Client) GetImageDefs(ctx context.Context) ([]ImageDefinition, error) {
 	imgDef := []ImageDefinition{}
 	err := c.jsonGet(ctx, "image_definitions", &imgDef, 0)