add variable and method comments

internal/permissions/assignments.go

@@ -8,20 +8,24 @@ import (
 	"go.infratographer.com/x/gidx"
 )
 
+// RoleAssign is the role assignment request body.
 type RoleAssign struct {
 	SubjectID string `json:"subject_id"`
 }
 
+// RoleAssignResponse is the response from a role assignment.
 type RoleAssignResponse struct {
 	Success bool `json:"success"`
 }
 
+// roleAssignmentData is the response from listing a role assignment
 type roleAssignmentData struct {
 	Data []struct {
 		SubjectID string `json:"subject_id"`
 	} `json:"data"`
 }
 
+// AssignRole assigns the provided member ID to the given role ID.
 func (c *Client) AssignRole(ctx context.Context, roleID gidx.PrefixedID, memberID gidx.PrefixedID) error {
 	path := fmt.Sprintf("/api/v1/roles/%s/assignments", roleID.String())
 
@@ -45,6 +49,7 @@ func (c *Client) AssignRole(ctx context.Context, roleID gidx.PrefixedID, memberI
 	return nil
 }
 
+// UnassignRole removes the provided member ID from the given role ID.
 func (c *Client) UnassignRole(ctx context.Context, roleID gidx.PrefixedID, memberID gidx.PrefixedID) error {
 	path := fmt.Sprintf("/api/v1/roles/%s/assignments", roleID.String())
 
@@ -68,6 +73,7 @@ func (c *Client) UnassignRole(ctx context.Context, roleID gidx.PrefixedID, membe
 	return nil
 }
 
+// ListRoleAssignments lists all assignments for the given role.
 func (c *Client) ListRoleAssignments(ctx context.Context, roleID gidx.PrefixedID) ([]gidx.PrefixedID, error) {
 	path := fmt.Sprintf("/api/v1/roles/%s/assignments", roleID.String())
 
@@ -91,6 +97,7 @@ func (c *Client) ListRoleAssignments(ctx context.Context, roleID gidx.PrefixedID
 	return assignments, nil
 }
 
+// RoleHasAssignment gets the assignments for the given role and check for the provided member id.
 func (c *Client) RoleHasAssignment(ctx context.Context, roleID gidx.PrefixedID, memberID gidx.PrefixedID) (bool, error) {
 	assignments, err := c.ListRoleAssignments(ctx, roleID)
 	if err != nil {

internal/permissions/client.go

@@ -21,6 +21,7 @@ var defaultHTTPClient = &http.Client{
 	Timeout: 5 * time.Second,
 }
 
+// Client is the permissions client.
 type Client struct {
 	logger *zap.SugaredLogger
 
@@ -32,6 +33,8 @@ type Client struct {
 	allowURL *url.URL
 }
 
+// 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.token != "" {
 		req.Header.Set(echo.HeaderAuthorization, "Bearer "+c.token)
@@ -55,6 +58,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/permissions/config.go

@@ -18,6 +18,7 @@ type Config struct {
 	BearerToken string
 }
 
+// MustViperFlags registers command flags along with the viper bindings.
 func MustViperFlags(v *viper.Viper, flags *pflag.FlagSet) {
 	flags.String("permissions-baseurl", "", "permissions base url")
 	viperx.MustBindFlag(v, "permissions.baseurl", flags.Lookup("permissions-baseurl"))

internal/permissions/doc.go

@@ -0,0 +1,2 @@
+// Package permissions implements a Permissions API client for fetching and manipulating relationships and role assignments.
+package permissions

internal/permissions/errors.go

@@ -3,9 +3,18 @@ package permissions
 import "errors"
 
 var (
-	ErrRoleNotFound                       = errors.New("role not found")
-	ErrAssignmentFailed                   = errors.New("assignment failed")
-	ErrUnassignmentFailed                 = errors.New("unassignment failed")
-	ErrUnexpectedRoleDeleteFailed         = errors.New("unknown role delete error")
+	// ErrRoleNotFound is returned when no role is found for a given list of actions.
+	ErrRoleNotFound = errors.New("role not found")
+
+	// ErrAssignmentFailed is returned when a user assignment to a role fails.
+	ErrAssignmentFailed = errors.New("assignment failed")
+
+	// ErrUnassignmentFailed is returned when a user assignment is removed from a role fails.
+	ErrUnassignmentFailed = errors.New("unassignment failed")
+
+	// ErrUnexpectedRoleDeleteFailed is returned when an unknown error is returned when deleting a role.
+	ErrUnexpectedRoleDeleteFailed = errors.New("unknown role delete error")
+
+	// ErrUnexpectedRelationshipDeleteFailed is returned when an unknown error is returned when deleting a relationship.
 	ErrUnexpectedRelationshipDeleteFailed = errors.New("unknown relationship delete error")
 )

internal/permissions/options.go

@@ -4,8 +4,10 @@ import (
 	"go.uber.org/zap"
 )
 
+// Option is a client configuration option definition.
 type Option func(*Client) error
 
+// WithLogger sets the logger for the client.
 func WithLogger(logger *zap.SugaredLogger) Option {
 	return func(c *Client) error {
 		c.logger = logger

internal/permissions/relationships.go

@@ -15,21 +15,25 @@ type resourceRelationship struct {
 	SubjectID  string `json:"subject_id"`
 }
 
+// ResourceRelationship defines the resource to subject relationship.
 type ResourceRelationship struct {
 	ResourceID gidx.PrefixedID
 	Relation   string
 	SubjectID  gidx.PrefixedID
 }
 
+// ResourceRelationshipRequest defines the request to relate to a subject.
 type ResourceRelationshipRequest struct {
 	Relation  string `json:"relation"`
 	SubjectID string `json:"subject_id"`
 }
 
+// ResourceRelationshipDeleteResponse defines the response for a delete of a relationship.
 type ResourceRelationshipDeleteResponse struct {
 	Success bool `json:"success"`
 }
 
+// DeleteResourceRelationship deletes the provided resources relationship to the given subject id.
 func (c *Client) DeleteResourceRelationship(ctx context.Context, resourceID gidx.PrefixedID, relation string, relatedResourceID gidx.PrefixedID) error {
 	path := fmt.Sprintf("/api/v1/resources/%s/relationships", resourceID.String())
 
@@ -54,6 +58,9 @@ func (c *Client) DeleteResourceRelationship(ctx context.Context, resourceID gidx
 	return nil
 }
 
+// ListResourceRelationships returns resources related to the given id.
+// If relatedResourceType is not provied, relations to subjects are returned.
+// If relatedResourceType is provided, relations to the given resource are returned which match the given type.
 func (c *Client) ListResourceRelationships(ctx context.Context, resourceID gidx.PrefixedID, relatedResourceType string) ([]ResourceRelationship, error) {
 	query := url.Values{
 		"resourceType": []string{relatedResourceType},

internal/permissions/roles.go

@@ -9,25 +9,31 @@ import (
 	"golang.org/x/exp/slices"
 )
 
+// ResourceRoleCreate is the role create request.
 type ResourceRoleCreate struct {
 	Actions []string `json:"actions"`
 }
 
+// ResourceRoleCreateResponse is the role creation response.
 type ResourceRoleCreateResponse struct {
 	ID string `json:"id"`
 }
 
+// ResourceRoleDeleteResponse is the role deletion response.
 type ResourceRoleDeleteResponse struct {
 	Success bool `json:"success"`
 }
 
+// ResourceRoles is a listg of resource roles.
 type ResourceRoles []ResourceRole
 
+// ResourceRole contains the role id and its actions.
 type ResourceRole struct {
 	ID      gidx.PrefixedID `json:"id"`
 	Actions []string        `json:"actions"`
 }
 
+// CreateRole creates a role on the given resource id with the provided actions.
 func (c *Client) CreateRole(ctx context.Context, resourceID gidx.PrefixedID, actions []string) (gidx.PrefixedID, error) {
 	path := fmt.Sprintf("/api/v1/resources/%s/roles", resourceID.String())
 
@@ -52,6 +58,7 @@ func (c *Client) CreateRole(ctx context.Context, resourceID gidx.PrefixedID, act
 	return roleID, nil
 }
 
+// DeleteRole deletes the provided role.
 func (c *Client) DeleteRole(ctx context.Context, roleID gidx.PrefixedID) error {
 	path := fmt.Sprintf("/api/v1/roles/%s", roleID.String())
 
@@ -68,6 +75,7 @@ func (c *Client) DeleteRole(ctx context.Context, roleID gidx.PrefixedID) error {
 	return nil
 }
 
+// ListResourceRoles fetches all roles assigned to the provided resource.
 func (c *Client) ListResourceRoles(ctx context.Context, resourceID gidx.PrefixedID) (ResourceRoles, error) {
 	path := fmt.Sprintf("/api/v1/resources/%s/roles", resourceID.String())
 
@@ -82,6 +90,7 @@ func (c *Client) ListResourceRoles(ctx context.Context, resourceID gidx.Prefixed
 	return response.Data, nil
 }
 
+// FindResourceRoleByActions fetches roles assigned to the provided resource and finds the first role where the actions match the provided actions.
 func (c *Client) FindResourceRoleByActions(ctx context.Context, resourceID gidx.PrefixedID, actions []string) (ResourceRole, error) {
 	roles, err := c.ListResourceRoles(ctx, resourceID)
 	if err != nil {