add variable and method comments

internal/metal/metal.go

@@ -17,22 +17,27 @@ type Client struct {
 	provider providers.Provider
 }
 
+// GetOrganizationDetails fetches the organization id provided with its memberships.
 func (c *Client) GetOrganizationDetails(ctx context.Context, id gidx.PrefixedID) (*models.OrganizationDetails, error) {
 	return c.provider.GetOrganizationDetails(ctx, id)
 }
 
+// GetProjectDetails fetchs the provided project id with membership information.
 func (c *Client) GetProjectDetails(ctx context.Context, id gidx.PrefixedID) (*models.ProjectDetails, error) {
 	return c.provider.GetProjectDetails(ctx, id)
 }
 
+// GetUserDetails fetches the provided user id.
 func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*models.UserDetails, error) {
 	return c.provider.GetUserDetails(ctx, id)
 }
 
+// GetUserOrganizationRole returns the role for the user in the organization.
 func (c *Client) GetUserOrganizationRole(ctx context.Context, userID, orgID gidx.PrefixedID) (string, error) {
 	return c.provider.GetUserOrganizationRole(ctx, userID, orgID)
 }
 
+// GetUserProjectRole returns the role for the user in the project.
 func (c *Client) GetUserProjectRole(ctx context.Context, userID, projID gidx.PrefixedID) (string, error) {
 	return c.provider.GetUserProjectRole(ctx, userID, projID)
 }

internal/metal/models/doc.go

@@ -0,0 +1,2 @@
+// Package models defines generic models each provider must be able to return.
+package models

internal/metal/models/memberships.go

@@ -1,5 +1,6 @@
 package models
 
+// Membership contains metal membership details.
 type Membership[T any] struct {
 	ID     string       `json:"id"`
 	User   *UserDetails `json:"user"`

internal/metal/models/projects.go

@@ -2,6 +2,7 @@ package models
 
 import "go.infratographer.com/x/gidx"
 
+// ProjectDetails contains project and membership information.
 type ProjectDetails struct {
 	ID           string                        `json:"id"`
 	Name         string                        `json:"name"`
@@ -9,6 +10,7 @@ type ProjectDetails struct {
 	Organization *OrganizationDetails          `json:"organization"`
 }
 
+// PrefixedID returns the prefixed id for the project.
 func (d *ProjectDetails) PrefixedID() gidx.PrefixedID {
 	if d.ID == "" {
 		return gidx.NullPrefixedID

internal/metal/models/users.go

@@ -8,10 +8,14 @@ import (
 )
 
 const (
-	MetalUserIssuer         = "https://auth.equinix.com/"
+	// MetalUserIssuer is the issuer that is used for metal api token users.
+	MetalUserIssuer = "https://auth.equinix.com/"
+
+	// MetaluserIssuerIDPrefix is the issuer id prefix added by the issuer.
 	MetalUserIssuerIDPrefix = "auth|"
 )
 
+// UserDetails contains the user information.
 type UserDetails struct {
 	id            *gidx.PrefixedID
 	ID            string                 `json:"id"`
@@ -21,6 +25,7 @@ type UserDetails struct {
 	Roles         []string               `json:"roles"`
 }
 
+// PrefixedID returns the identity prefixed id for the user.
 func (d *UserDetails) PrefixedID() gidx.PrefixedID {
 	if d.id != nil {
 		return *d.id
@@ -44,6 +49,7 @@ func (d *UserDetails) PrefixedID() gidx.PrefixedID {
 	return *d.id
 }
 
+// GenerateSubjectID builds a identity prefixed id with the provided prefix for the issuer and subject.
 func GenerateSubjectID(prefix, iss, sub string) (gidx.PrefixedID, error) {
 	// Concatenate the iss and sub values, then hash them
 	issSub := iss + sub

internal/metal/providers/emapi/client.go

@@ -25,12 +25,14 @@ const (
 	staffHeaderValue = "true"
 )
 
+// DefaultHTTPClient is the default http client used if no client is provided.
 var DefaultHTTPClient = &http.Client{
 	Timeout: defaultHTTPTimeout,
 }
 
 var _ providers.Provider = &Client{}
 
+// Client is the client to interact with the equinix metal api.
 type Client struct {
 	logger        *zap.SugaredLogger
 	httpClient    *http.Client
@@ -39,6 +41,8 @@ type Client struct {
 	consumerToken string
 }
 
+// Do executes the provided request.
+// If the out value is provided, the response will attempt to be json decoded.
 func (c *Client) Do(req *http.Request, out any) (*http.Response, error) {
 	if c.authToken != "" {
 		req.Header.Set(authHeader, c.authToken)
@@ -68,6 +72,7 @@ func (c *Client) Do(req *http.Request, out any) (*http.Response, error) {
 	return resp, nil
 }
 
+// DoRequest creates a new request from the provided parameters and executes the request.
 func (c *Client) DoRequest(ctx context.Context, method, path string, body io.Reader, out any) (*http.Response, error) {
 	path = strings.TrimPrefix(path, c.baseURL.Path)
 

internal/metal/providers/emapi/config.go

@@ -17,6 +17,7 @@ type Config struct {
 	ConsumerToken string
 }
 
+// Populated checks if any field has been populated.
 func (c Config) Populated() bool {
 	return c.AuthToken != "" || c.ConsumerToken != "" || c.BaseURL != ""
 }

internal/metal/providers/emapi/doc.go

@@ -0,0 +1,2 @@
+// Package emapi implement a metal provider which fetches details from the Equinix Metal API.
+package emapi

internal/metal/providers/emapi/errors.go

@@ -2,4 +2,5 @@ package emapi
 
 import "errors"
 
+// ErrBaseURLRequired is returned if no base url is provided.
 var ErrBaseURLRequired = errors.New("emapi base url required")

internal/metal/providers/emapi/memberships.go

@@ -4,10 +4,13 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// Roles contains a list of roles.
 type Roles []string
 
+// Memberships contains a list of memberships
 type Memberships []*Membership
 
+// ToDetailsWithOrganizationDetails convers the memberships to generic membership models with organization details.
 func (m Memberships) ToDetailsWithOrganizationDetails(orgDetails *models.OrganizationDetails) []*models.Membership[models.OrganizationDetails] {
 	memberships := make([]*models.Membership[models.OrganizationDetails], len(m))
 
@@ -28,6 +31,7 @@ func (m Memberships) ToDetailsWithOrganizationDetails(orgDetails *models.Organiz
 	return memberships
 }
 
+// ToDetailsWithProjectDetails convers the memberships to generic membership models with project details.
 func (m Memberships) ToDetailsWithProjectDetails(projDetails *models.ProjectDetails) []*models.Membership[models.ProjectDetails] {
 	memberships := make([]*models.Membership[models.ProjectDetails], len(m))
 
@@ -48,6 +52,7 @@ func (m Memberships) ToDetailsWithProjectDetails(projDetails *models.ProjectDeta
 	return memberships
 }
 
+// Membership contains membership information.
 type Membership struct {
 	client *Client
 
@@ -57,6 +62,7 @@ type Membership struct {
 	User  *User  `json:"user"`
 }
 
+// ToDetailsWithOrganizationDetails convers the membership to generic membership model with organization details.
 func (m *Membership) ToDetailsWithOrganizationDetails(orgDetails *models.OrganizationDetails) *models.Membership[models.OrganizationDetails] {
 	if m.ID == "" {
 		return nil
@@ -70,6 +76,7 @@ func (m *Membership) ToDetailsWithOrganizationDetails(orgDetails *models.Organiz
 	}
 }
 
+// ToDetailsWithOrganizationDetails convers the membership to generic membership model with organization details.
 func (m *Membership) ToDetailsWithProjectDetails(projDetails *models.ProjectDetails) *models.Membership[models.ProjectDetails] {
 	if m.ID == "" {
 		return nil

internal/metal/providers/emapi/organizations.go

@@ -14,8 +14,10 @@ const (
 	organizationsPath = "/organizations"
 )
 
+// Organizations contains a list of organizations.
 type Organizations []*Organization
 
+// ToDetails converts to a generic model organization details.
 func (o Organizations) ToDetails() []*models.OrganizationDetails {
 	orgs := make([]*models.OrganizationDetails, len(o))
 
@@ -36,6 +38,7 @@ func (o Organizations) ToDetails() []*models.OrganizationDetails {
 	return orgs
 }
 
+// Organization contains organization information.
 type Organization struct {
 	client *Client
 
@@ -47,6 +50,7 @@ type Organization struct {
 	Projects    Projects    `json:"projects"`
 }
 
+// ToDetails converts the object to a generic orgnization details.
 func (o *Organization) ToDetails() *models.OrganizationDetails {
 	var id string
 
@@ -69,6 +73,7 @@ func (o *Organization) ToDetails() *models.OrganizationDetails {
 	return details
 }
 
+// getOrganizationWithMemberships fetches an organization from the equinix metal api with membership user information.
 func (c *Client) getOrganizationWithMemberships(ctx context.Context, id string) (*Organization, error) {
 	var org Organization
 
@@ -80,6 +85,7 @@ func (c *Client) getOrganizationWithMemberships(ctx context.Context, id string)
 	return &org, nil
 }
 
+// GetOrganizationDetails fetches the organization id provided with its memberships.
 func (c *Client) GetOrganizationDetails(ctx context.Context, id gidx.PrefixedID) (*models.OrganizationDetails, error) {
 	org, err := c.getOrganizationWithMemberships(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {

internal/metal/providers/emapi/projects.go

@@ -14,8 +14,10 @@ const (
 	projectsPath = "/projects"
 )
 
+// Projects contains a list of projects.
 type Projects []*Project
 
+// ToDetails converts the objects to generic project details.
 func (p Projects) ToDetails() []*models.ProjectDetails {
 	projects := make([]*models.ProjectDetails, len(p))
 
@@ -36,6 +38,7 @@ func (p Projects) ToDetails() []*models.ProjectDetails {
 	return projects
 }
 
+// Project contains project information.
 type Project struct {
 	client *Client
 
@@ -47,6 +50,7 @@ type Project struct {
 	Organization *Organization `json:"organization"`
 }
 
+// ToDetails converts the project to generic project details.
 func (p *Project) ToDetails() *models.ProjectDetails {
 	var id string
 
@@ -69,6 +73,7 @@ func (p *Project) ToDetails() *models.ProjectDetails {
 	return details
 }
 
+// getProjectWithMemberships fetches the provided project with membership information.
 func (c *Client) getProjectWithMemberships(ctx context.Context, id string) (*Project, error) {
 	var project Project
 
@@ -80,6 +85,7 @@ func (c *Client) getProjectWithMemberships(ctx context.Context, id string) (*Pro
 	return &project, nil
 }
 
+// GetProjectDetails fetchs the provided project id with membership information.
 func (c *Client) GetProjectDetails(ctx context.Context, id gidx.PrefixedID) (*models.ProjectDetails, error) {
 	project, err := c.getProjectWithMemberships(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {

internal/metal/providers/emapi/users.go

@@ -14,8 +14,10 @@ const (
 	usersPath = "/users"
 )
 
+// Users contains a list of users.
 type Users []*User
 
+// ToDetails converts the objects to generic user details.
 func (u Users) ToDetails() []*models.UserDetails {
 	users := make([]*models.UserDetails, len(u))
 
@@ -36,6 +38,7 @@ func (u Users) ToDetails() []*models.UserDetails {
 	return users
 }
 
+// User contains user information.
 type User struct {
 	client *Client
 
@@ -46,6 +49,7 @@ type User struct {
 	Projects Projects `json:"projects"`
 }
 
+// ToDetails converts the user to generic user details.
 func (u *User) ToDetails() *models.UserDetails {
 	var id string
 
@@ -65,6 +69,7 @@ func (u *User) ToDetails() *models.UserDetails {
 	}
 }
 
+// getUser fetches the provided user.
 func (c *Client) getUser(ctx context.Context, id string) (*User, error) {
 	var user User
 
@@ -76,6 +81,7 @@ func (c *Client) getUser(ctx context.Context, id string) (*User, error) {
 	return &user, nil
 }
 
+// GetUserDetails fetches the provided user id.
 func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*models.UserDetails, error) {
 	user, err := c.getUser(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {
@@ -85,10 +91,12 @@ func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*model
 	return user.ToDetails(), nil
 }
 
+// GetUserOrganizationRole returns collaborator for all organizations.
 func (c *Client) GetUserOrganizationRole(ctx context.Context, userID, orgID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }
 
+// GetUserProjectRole returns collaborator for all projects.
 func (c *Client) GetUserProjectRole(ctx context.Context, userID, projectID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }

internal/metal/providers/emgql/client.go

@@ -14,12 +14,14 @@ const (
 	defaultHTTPTimeout = 5 * time.Second
 )
 
+// DefaultHTTPClient is the default http client used if no client is provided.
 var DefaultHTTPClient = &http.Client{
 	Timeout: defaultHTTPTimeout,
 }
 
 var _ providers.Provider = &Client{}
 
+// Client is the client to interact with the equinix metal graphql service.
 type Client struct {
 	logger     *zap.SugaredLogger
 	httpClient *http.Client

internal/metal/providers/emgql/config.go

@@ -2,11 +2,11 @@ package emgql
 
 // Config provides configuration for connecting to the Equinix Metal API provider.
 type Config struct {
-
 	// BaseURL is the baseurl to use when connecting to the Equinix Metal API Provider.
 	BaseURL string
 }
 
+// Populated checks if any field has been populated.
 func (c Config) Populated() bool {
 	return c.BaseURL != ""
 }

internal/metal/providers/emgql/doc.go

@@ -0,0 +1,2 @@
+// Package emgql implements a metal provider which fetches details from the Equinix Metal GraphQL.
+package emgql

internal/metal/providers/emgql/organizations.go

@@ -3,10 +3,12 @@ package emgql
 import (
 	"context"
 
-	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 	"go.infratographer.com/x/gidx"
+
+	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// GetOrganizationDetails fetches the organization id provided with its memberships.
 func (c *Client) GetOrganizationDetails(ctx context.Context, id gidx.PrefixedID) (*models.OrganizationDetails, error) {
 	return nil, nil
 }

internal/metal/providers/emgql/projects.go

@@ -3,10 +3,12 @@ package emgql
 import (
 	"context"
 
-	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 	"go.infratographer.com/x/gidx"
+
+	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// GetProjectDetails fetchs the provided project id with membership information.
 func (c *Client) GetProjectDetails(ctx context.Context, id gidx.PrefixedID) (*models.ProjectDetails, error) {
 	return nil, nil
 }

internal/metal/providers/emgql/users.go

@@ -8,14 +8,17 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// GetUserDetails fetches the provided user id.
 func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*models.UserDetails, error) {
 	return nil, nil
 }
 
+// GetUserOrganizationRole returns collaborator for all organizations.
 func (c *Client) GetUserOrganizationRole(ctx context.Context, userID, orgID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }
 
+// GetUserProjectRole returns collaborator for all projects.
 func (c *Client) GetUserProjectRole(ctx context.Context, userID, projID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }

internal/metal/providers/provider.go

@@ -1,3 +1,4 @@
+// Package providers defines the provider interface for fetching metal resources.
 package providers
 
 import (
@@ -8,6 +9,7 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// Provider defines the provider implementation.
 type Provider interface {
 	GetOrganizationDetails(ctx context.Context, id gidx.PrefixedID) (*models.OrganizationDetails, error)
 	GetProjectDetails(ctx context.Context, id gidx.PrefixedID) (*models.ProjectDetails, error)