add variable and method comments

internal/service/organizations.go

@@ -11,6 +11,7 @@ import (
 
 const organizationEvent = "metalorganization"
 
+// buildOrganizationRelationships compiles all relations into a relationships object to be processed by the processors.
 func (s *service) buildOrganizationRelationships(org *models.OrganizationDetails) (Relationships, error) {
 	relations := Relationships{
 		Resource: org,
@@ -46,6 +47,7 @@ func (s *service) buildOrganizationRelationships(org *models.OrganizationDetails
 	return relations, nil
 }
 
+// IsOrganizationID checks if the provided id has the metal organization prefix.
 func (s *service) IsOrganizationID(id gidx.PrefixedID) bool {
 	if idType, ok := s.idPrefixMap[id.Prefix()]; ok {
 		return idType == TypeOrganization
@@ -54,6 +56,7 @@ func (s *service) IsOrganizationID(id gidx.PrefixedID) bool {
 	return false
 }
 
+// TouchOrganization initializes a sync for the provided organization id for relationships and memberships.
 func (s *service) TouchOrganization(ctx context.Context, id gidx.PrefixedID) error {
 	logger := s.logger.With("organization.id", id.String())
 
@@ -84,6 +87,7 @@ func (s *service) TouchOrganization(ctx context.Context, id gidx.PrefixedID) err
 	return nil
 }
 
+// DeleteOrganization deletes the provided organization id.
 func (s *service) DeleteOrganization(ctx context.Context, id gidx.PrefixedID) error {
 	err := s.publisher.PublishChange(ctx, organizationEvent, events.ChangeMessage{
 		SubjectID: id,

internal/service/process_memberships.go

@@ -10,6 +10,8 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/permissions"
 )
 
+// syncMemberships determines the changes between what is wanted and what is live and executes on the differences.
+// If skipDeletions is true, no deletes will be executed.
 func (s *service) syncMemberships(ctx context.Context, relationships Relationships, skipDeletions bool) (int, int) {
 	if len(relationships.Memberships) == 0 {
 		return 0, 0
@@ -170,6 +172,10 @@ func (s *service) syncMemberships(ctx context.Context, relationships Relationshi
 	return rolesCreated + rolesDeleted, roleAssignments + roleUnassignments
 }
 
+// mapResourceWants processes the provided memberships and returns two maps.
+// A Role Key is computed based on a sorted slice of actions for each role.
+// The first map is of Role Key -> list of actions
+// The second map is of Role Key -> Member ID -> true
 func (s *service) mapResourceWants(memberships []ResourceMemberships) (map[string][]string, map[string]map[gidx.PrefixedID]bool) {
 	roleActionsKey := make(map[string]string)
 
@@ -196,6 +202,10 @@ func (s *service) mapResourceWants(memberships []ResourceMemberships) (map[strin
 	return wantRoles, wantAssignments
 }
 
+// mapResourceDetails fetches the provided ResourceID's live state and returns two maps and an error.
+// A Role Key is computed based on a sorted slice of actions for each role.
+// The first map is of Role Key -> Permissions Resource Role
+// The second map is of Role Key -> Member ID -> true
 func (s *service) mapResourceDetails(ctx context.Context, resourceID gidx.PrefixedID) (map[string]permissions.ResourceRole, map[string]map[gidx.PrefixedID]bool, error) {
 	roles := make(map[string]permissions.ResourceRole)
 	assignments := make(map[string]map[gidx.PrefixedID]bool)

internal/service/process_relationships.go

@@ -9,13 +9,9 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/permissions"
 )
 
-type relationshipStats struct {
-	parentCreated               bool
-	parentsDeleted              int
-	subjectRelationshipsCreated int
-	subjectRelationshipsDeleted int
-}
-
+// processRelationships determines the changes between what is wanted and what is live and executes on the differences.
+// Relationship creations use events.
+// Relationship deletions use the api, as delete events delete all related resources and not just the provided ones.
 func (s *service) processRelationships(ctx context.Context, eventType string, relationships Relationships) int {
 	rlogger := s.logger.With("resource.id", relationships.Resource.PrefixedID())
 
@@ -161,6 +157,7 @@ func (s *service) processRelationships(ctx context.Context, eventType string, re
 	return changes
 }
 
+// mapRelationWants returns the parent relation if provided and a map of Subjects -> relation.
 func (s *service) mapRelationWants(relationships Relationships) (*Relation, map[gidx.PrefixedID]RelationshipType) {
 	var wantParent *Relation
 
@@ -177,6 +174,9 @@ func (s *service) mapRelationWants(relationships Relationships) (*Relation, map[
 	return wantParent, wantSubject
 }
 
+// getRelationshipMap fetches the provided resources relationships, as the source resource and the destination subject.
+// Returned are two maps, the first maps Subject IDs -> Relationship
+// The second map, maps Resource IDs -> relationship
 func (s *service) getRelationshipMap(ctx context.Context, resource IDPrefixableResource, relatedObjectType ObjectType) (map[gidx.PrefixedID]RelationshipType, map[gidx.PrefixedID]RelationshipType, error) {
 	liveResource, err := s.perms.ListResourceRelationships(ctx, resource.PrefixedID(), "")
 	if err != nil {

internal/service/projects.go

@@ -11,6 +11,7 @@ import (
 
 const projectEvent = "metalproject"
 
+// buildProjectRelationships compiles all relations into a relationships object to be processed by the processors.
 func (s *service) buildProjectRelationships(project *models.ProjectDetails) (Relationships, error) {
 	relations := Relationships{
 		Resource: project,
@@ -39,6 +40,7 @@ func (s *service) buildProjectRelationships(project *models.ProjectDetails) (Rel
 	return relations, nil
 }
 
+// IsProjectID checks if the provided id has the metal project prefix.
 func (s *service) IsProjectID(id gidx.PrefixedID) bool {
 	if idType, ok := s.idPrefixMap[id.Prefix()]; ok {
 		return idType == TypeProject
@@ -47,6 +49,7 @@ func (s *service) IsProjectID(id gidx.PrefixedID) bool {
 	return false
 }
 
+// TouchProject initializes a sync for the provided project id for relationships and memberships.
 func (s *service) TouchProject(ctx context.Context, id gidx.PrefixedID) error {
 	logger := s.logger.With("project.id", id.String())
 
@@ -77,6 +80,7 @@ func (s *service) TouchProject(ctx context.Context, id gidx.PrefixedID) error {
 	return nil
 }
 
+// DeleteProject deletes the provided project id.
 func (s *service) DeleteProject(ctx context.Context, id gidx.PrefixedID) error {
 	err := s.publisher.PublishChange(ctx, projectEvent, events.ChangeMessage{
 		SubjectID: id,

internal/service/relationships.go

@@ -5,16 +5,22 @@ import (
 )
 
 const (
-	RelateOwner  RelationshipType = "owner"
+	// RelateOwner is the owner relationship type.
+	RelateOwner RelationshipType = "owner"
+
+	// RelateParent is the parent relationship type.
 	RelateParent RelationshipType = "parent"
 )
 
+// RelationshipType are relationship types.
 type RelationshipType string
 
+// IDPrefixableResource ensures the the interface passed provides prefixed ids.
 type IDPrefixableResource interface {
 	PrefixedID() gidx.PrefixedID
 }
 
+// Relationships defines a resource and all possible relationships and memberships.
 type Relationships struct {
 	Resource             IDPrefixableResource
 	Parent               Relation
@@ -23,11 +29,13 @@ type Relationships struct {
 	Memberships          []ResourceMemberships
 }
 
+// Relation defines a relation to a resource.
 type Relation struct {
 	Relation RelationshipType
 	Resource IDPrefixableResource
 }
 
+// ResourceMemberships defines a member and role.
 type ResourceMemberships struct {
 	Role   string
 	Member IDPrefixableResource

internal/service/service.go

@@ -29,8 +29,10 @@ var DefaultPrefixMap = map[string]ObjectType{
 	TypeUser.Prefix():         TypeUser,
 }
 
+// ObjectType defines a type of object.
 type ObjectType string
 
+// Prefix returns the objects id prefix.
 func (t ObjectType) Prefix() string {
 	switch t {
 	case TypeOrganization:
@@ -44,6 +46,7 @@ func (t ObjectType) Prefix() string {
 	}
 }
 
+// String returns a string fo the object type.
 func (t ObjectType) String() string {
 	return string(t)
 }
@@ -96,6 +99,7 @@ func (r prefixedID) PrefixedID() gidx.PrefixedID {
 	return r.id
 }
 
+// New creates a new service.
 func New(publisher *events.Publisher, metal *metal.Client, perms *permissions.Client, options ...Option) (Service, error) {
 	svc := &service{
 		publisher:   publisher,

internal/service/users.go

@@ -6,6 +6,7 @@ import (
 	"go.infratographer.com/x/gidx"
 )
 
+// IsUser checks the provided id has the metal user prefix.
 func (s *service) IsUser(id gidx.PrefixedID) bool {
 	if idType, ok := s.idPrefixMap[id.Prefix()]; ok {
 		return idType == TypeUser
@@ -14,6 +15,7 @@ func (s *service) IsUser(id gidx.PrefixedID) bool {
 	return false
 }
 
+// IsAssignableResource checks that the provided id is an id which can have memberships assignments.
 func (s *service) IsAssignableResource(id gidx.PrefixedID) bool {
 	if idType, ok := s.idPrefixMap[id.Prefix()]; ok {
 		switch idType {
@@ -27,6 +29,7 @@ func (s *service) IsAssignableResource(id gidx.PrefixedID) bool {
 	return false
 }
 
+// Assignuser assigns the provided users to the given resource ids.
 func (s *service) AssignUser(ctx context.Context, userID gidx.PrefixedID, resourceIDs ...gidx.PrefixedID) error {
 	var totalResources, rolesChanged, assignmentsChanged int
 
@@ -68,6 +71,7 @@ func (s *service) AssignUser(ctx context.Context, userID gidx.PrefixedID, resour
 	return nil
 }
 
+// UnassignUser removes the assignment for the provided user id to the given resources.
 func (s *service) UnassignUser(ctx context.Context, userID gidx.PrefixedID, resourceIDs ...gidx.PrefixedID) error {
 	for _, resourceID := range resourceIDs {
 		rlogger := s.logger.With("user.id", userID, "resource.id", resourceID)
@@ -119,6 +123,7 @@ func (s *service) UnassignUser(ctx context.Context, userID gidx.PrefixedID, reso
 	return nil
 }
 
+// getuserResourceRole fetches the appropriate object types user role for the given resource.
 func (s *service) getUserResourceRole(ctx context.Context, userID, resourceID gidx.PrefixedID) (string, error) {
 	var (
 		role string