add mapstructure tags to types,

improve function documentation

access-types.go

@@ -1,10 +1,10 @@
 package proxmoxaas_common_lib
 
 type Pool struct {
-	PoolID           string          `json:"poolid"`
-	Groups           []Group         `json:"groups"`
-	Resources        map[string]any  `json:"resources"`
-	Templates        Templates       `json:"templates"`
+	PoolID           string          `json:"poolid" mapstructure:"poolid"`
+	Groups           []Group         `json:"groups" mapstructure:"groups"`
+	Resources        map[string]any  `json:"resources" mapstructure:"resources"`
+	Templates        Templates       `json:"templates" mapstructure:"templates"`
 	AllowedNodes     map[string]bool `json:"nodes-allowed" mapstructure:"nodes-allowed"`
 	AllowedVMIDRange VMID            `json:"vmid-allowed" mapstructure:"vmid-allowed"`
 	AllowedBackups   Backups         `json:"backups-allowed" mapstructure:"backups-allowed"`
@@ -14,32 +14,32 @@ type Pool struct {
 // proxmox realms are formatted without realm values
 // I assume that backends store groups by ID only and only proxmox will append the realm string
 type Groupname struct {
-	GroupID string `json:"gid"`
-	Realm   string `json:"realm"`
+	GroupID string `json:"gid" mapstructure:"gid"`
+	Realm   string `json:"realm" mapstructure:"realm"`
 }
 
 type Group struct {
-	Groupname Groupname `json:"groupname"`
-	Role      string    `json:"role"` // role in owner pool
-	Users     []User    `json:"users"`
+	Groupname Groupname `json:"groupname" mapstructure:"groupname"`
+	Role      string    `json:"role" mapstructure:"role"` // role in owner pool
+	Users     []User    `json:"users" mapstructure:"users"`
 }
 
 type Username struct { // ie userid@realm
-	UserID string `json:"uid"`
-	Realm  string `json:"realm"`
+	UserID string `json:"uid" mapstructure:"uid"`
+	Realm  string `json:"realm" mapstructure:"realm"`
 }
 
 type User struct {
-	Username Username `json:"username"`
-	CN       string   `json:"cn"` // aka first name
-	SN       string   `json:"sn"` // aka last name
-	Mail     string   `json:"mail"`
-	Password string   `json:"password"` // only used for POST requests
+	Username Username `json:"username" mapstructure:"username"`
+	CN       string   `json:"cn" mapstructure:"cn"` // aka first name
+	SN       string   `json:"sn" mapstructure:"sn"` // aka last name
+	Mail     string   `json:"mail" mapstructure:"mail"`
+	Password string   `json:"password" mapstructure:"password"` // only used for POST requests
 }
 
 type VMID struct {
-	Min int `json:"min"`
-	Max int `json:"max"`
+	Min int `json:"min" mapstructure:"min"`
+	Max int `json:"max" mapstructure:"max"`
 }
 
 type Backups struct {
@@ -49,40 +49,40 @@ type Backups struct {
 
 type Templates struct {
 	Instances struct {
-		LXC  map[string]ResourceTemplate `json:"lxc"`
-		QEMU map[string]ResourceTemplate `json:"qemu"`
+		LXC  map[string]ResourceTemplate `json:"lxc" mapstructure:"lxc"`
+		QEMU map[string]ResourceTemplate `json:"qemu" mapstructure:"qemu"`
 	} `json:"instances"`
 }
 
 type SimpleResource struct {
 	Limits struct {
-		Global SimpleLimit            `json:"global"`
-		Nodes  map[string]SimpleLimit `json:"nodes"`
+		Global SimpleLimit            `json:"global" mapstructure:"global"`
+		Nodes  map[string]SimpleLimit `json:"nodes" mapstructure:"nodes"`
 	} `json:"limits"`
 }
 
 type SimpleLimit struct {
-	Max int `json:"max"`
+	Max int `json:"max" mapstructure:"max"`
 }
 
 type MatchResource struct {
 	Limits struct {
-		Global []MatchLimit            `json:"global"`
-		Nodes  map[string][]MatchLimit `json:"nodes"`
+		Global []MatchLimit            `json:"global" mapstructure:""`
+		Nodes  map[string][]MatchLimit `json:"nodes" mapstructure:""`
 	} `json:"limits"`
 }
 
 type MatchLimit struct {
-	Match string `json:"match"`
-	Name  string `json:"name"`
-	Max   int    `json:"max"`
+	Match string `json:"match" mapstructure:""`
+	Name  string `json:"name" mapstructure:""`
+	Max   int    `json:"max" mapstructure:""`
 }
 
 type ResourceTemplate struct {
-	Value    string `json:"value"`
+	Value    string `json:"value" mapstructure:"value"`
 	Resource struct {
-		Enabled bool   `json:"enabled"`
-		Name    string `json:"name"`
-		Amount  int    `json:"amount"`
-	} `json:"resource"`
+		Enabled bool   `json:"enabled" mapstructure:"enabled"`
+		Name    string `json:"name" mapstructure:"name"`
+		Amount  int    `json:"amount" mapstructure:"amount"`
+	} `json:"resource" mapstructure:"resource"`
 }

access-utils.go

@@ -5,15 +5,21 @@ import (
 	"regexp"
 )
 
+// Converts input groupname object to string representation.
+// Uses the format gid-realm.
 func (g Groupname) ToString() string {
 	return fmt.Sprintf("%s-%s", g.GroupID, g.Realm)
 }
 
+// Converts input username object to string representation.
+// Uses the format uid@realm.
 func (u Username) ToString() string {
 	return fmt.Sprintf("%s-%s", u.UserID, u.Realm)
 }
 
-// returns an error if the groupname format was not correct
+// Parses input groupname string to gid and realm.
+// Assumes the format gid-realm or gid if realm is implicitly pve.
+// Returns an error if the groupname format was not correct.
 func ParseGroupname(groupname string) (Groupname, error) {
 	g := Groupname{}
 	// <groupid>-<realm>
@@ -36,7 +42,9 @@ func ParseGroupname(groupname string) (Groupname, error) {
 	}
 }
 
-// returns an error if the username format was not correct
+// Parses input username string to uid and realm.
+// Assumes the format uid@realm.
+// Returns an error if the username format was not correct.
 func ParseUsername(username string) (Username, error) {
 	u := Username{}
 	m := regexp.MustCompilePOSIX("([[:alnum:]]+)@([[:alnum:]]+)")

resource-types.go

@@ -5,13 +5,13 @@ type Cluster struct {
 }
 
 type Node struct {
-	Name      string                   `json:"name"`
-	Cores     uint64                   `json:"cores"`
-	Memory    uint64                   `json:"memory"`
-	Swap      uint64                   `json:"swap"`
-	Devices   map[DeviceBus]*Device    `json:"devices"`
-	Instances map[InstanceID]*Instance `json:"instances"`
-	Proctypes []string                 `json:"cpus"`
+	Name      string                   `json:"name" mapstructure:"name"`
+	Cores     uint64                   `json:"cores" mapstructure:"cores"`
+	Memory    uint64                   `json:"memory" mapstructure:"memory"`
+	Swap      uint64                   `json:"swap" mapstructure:"swap"`
+	Devices   map[DeviceBus]*Device    `json:"devices" mapstructure:"devices"`
+	Instances map[InstanceID]*Instance `json:"instances" mapstructure:"instances"`
+	Proctypes []string                 `json:"cpus" mapstructure:"cpus"`
 }
 
 type InstanceID uint64
@@ -21,17 +21,17 @@ const VM InstanceType = "VM"
 const CT InstanceType = "CT"
 
 type Instance struct {
-	Type     InstanceType         `json:"type"`
-	Name     string               `json:"name"`
+	Type     InstanceType         `json:"type" mapstructure:"type"`
+	Name     string               `json:"name" mapstructure:"name"`
 	Proctype string               `json:"cpu" mapstructure:"cpu"`
-	Cores    uint64               `json:"cores"`
-	Memory   uint64               `json:"memory"`
-	Swap     uint64               `json:"swap"`
-	Volumes  map[VolumeID]*Volume `json:"volumes"`
-	Nets     map[NetID]*Net       `json:"nets"`
-	Devices  map[DeviceID]*Device `json:"devices"`
-	Boot     BootOrder            `json:"boot"`
-	Pool     string               `json:"pool"` // todo: this should be actual pool
+	Cores    uint64               `json:"cores" mapstructure:"cores"`
+	Memory   uint64               `json:"memory" mapstructure:"memory"`
+	Swap     uint64               `json:"swap" mapstructure:"swap"`
+	Volumes  map[VolumeID]*Volume `json:"volumes" mapstructure:"volumes"`
+	Nets     map[NetID]*Net       `json:"nets" mapstructure:"nets"`
+	Devices  map[DeviceID]*Device `json:"devices" mapstructure:"devices"`
+	Boot     BootOrder            `json:"boot" mapstructure:"boot"`
+	Pool     string               `json:"pool" mapstructure:"pool"` // todo: this should be actual pool
 }
 
 var VolumeTypes = []string{
@@ -45,43 +45,43 @@ var VolumeTypes = []string{
 
 type VolumeID string
 type Volume struct {
-	Volume_ID VolumeID `json:"volume_id"`
-	Type      string   `json:"type"`
-	Storage   string   `json:"storage"`
-	Format    string   `json:"format"`
-	Size      uint64   `json:"size"`
-	File      string   `json:"file"`
-	MP        string   `json:"mp"`
+	Volume_ID VolumeID `json:"volume_id" mapstructure:"volume_id"`
+	Type      string   `json:"type" mapstructure:"type"`
+	Storage   string   `json:"storage" mapstructure:"storage"`
+	Format    string   `json:"format" mapstructure:"format"`
+	Size      uint64   `json:"size" mapstructure:"size"`
+	File      string   `json:"file" mapstructure:"file"`
+	MP        string   `json:"mp" mapstructure:"mp"`
 }
 
 type NetID string
 type Net struct {
-	Net_ID NetID  `json:"net_id"`
-	Value  string `json:"value"`
-	Rate   uint64 `json:"rate"`
-	VLAN   uint64 `json:"vlan"`
+	Net_ID NetID  `json:"net_id" mapstructure:"net_id"`
+	Value  string `json:"value" mapstructure:"value"`
+	Rate   uint64 `json:"rate" mapstructure:"rate"`
+	VLAN   uint64 `json:"vlan" mapstructure:"vlan"`
 }
 
 type DeviceID string
 type DeviceBus string
 type Device struct {
-	Device_ID   DeviceID                 `json:"device_id"`
-	Device_Bus  DeviceBus                `json:"device_bus"`
-	Device_Name string                   `json:"device_name"`
-	Vendor_Name string                   `json:"vendor_name"`
-	Functions   map[FunctionID]*Function `json:"functions"`
-	Reserved    bool                     `json:"reserved"`
+	Device_ID   DeviceID                 `json:"device_id" mapstructure:"device_id"`
+	Device_Bus  DeviceBus                `json:"device_bus" mapstructure:"device_bus"`
+	Device_Name string                   `json:"device_name" mapstructure:"device_name"`
+	Vendor_Name string                   `json:"vendor_name" mapstructure:"vendor_name"`
+	Functions   map[FunctionID]*Function `json:"functions" mapstructure:"functions"`
+	Reserved    bool                     `json:"reserved" mapstructure:"reserved"`
 }
 
 type FunctionID string
 type Function struct {
-	Function_ID   FunctionID `json:"function_id"`
-	Function_Name string     `json:"subsystem_device_name"`
-	Vendor_Name   string     `json:"subsystem_vendor_name"`
-	Reserved      bool       `json:"reserved"`
+	Function_ID   FunctionID `json:"function_id" mapstructure:"function_id"`
+	Function_Name string     `json:"subsystem_device_name" mapstructure:"subsystem_device_name"`
+	Vendor_Name   string     `json:"subsystem_vendor_name" mapstructure:"subsystem_vendor_name"`
+	Reserved      bool       `json:"reserved" mapstructure:"reserved"`
 }
 
 type BootOrder struct {
-	Enabled  []any `json:"enabled"`
-	Disabled []any `json:"disabled"`
+	Enabled  []any `json:"enabled" mapstructure:"enabled"`
+	Disabled []any `json:"disabled" mapstructure:"disabled"`
 }