groups

Documentation

Overview

Package groups contains the domain concept definitions needed to support Magistrala groups functionality.

Index

• Constants
• Variables
• func AvailableActions() []roles.Action
• func BuiltInRoles() map[roles.BuiltInRoleName][]roles.Action
• func NewOperationPerm() svcutil.OperationPerm
• func NewOperationPermissionMap() map[svcutil.Operation]svcutil.Permission
• func NewRolesOperationPermissionMap() map[svcutil.Operation]svcutil.Permission
• type Group
• type HierarchyPage
• type HierarchyPageMeta
• type Member
• type MembersPage
• type Page
• type PageMeta
• type Repository
• type Service
  • func NewService(repo Repository, policy policies.Service, idp magistrala.IDProvider, ...) (Service, error)
• type Status
  • func ToStatus(status string) (Status, error)
  • func (s Status) String() string

Constants

const (
	MaxLevel      = uint64(20)
	MaxPathLength = 20
)

MaxLevel represents the maximum group hierarchy level.

const (
	OpCreateGroup svcutil.Operation = iota
	OpListGroups
	OpViewGroup
	OpUpdateGroup
	OpEnableGroup
	OpDisableGroup
	OpRetrieveGroupHierarchy
	OpAddParentGroup
	OpRemoveParentGroup
	OpViewParentGroup
	OpAddChildrenGroups
	OpRemoveChildrenGroups
	OpRemoveAllChildrenGroups
	OpListChildrenGroups
	OpAddChannels
	OpRemoveChannels
	OpRemoveAllChannels
	OpListChannels
	OpAddThings
	OpRemoveThings
	OpRemoveAllThings
	OpListThings
	OpDeleteGroup
)

const (
	Update     = "update"
	Read       = "read"
	Membership = "membership"
	Delete     = "delete"
	SetChild   = "set_child"
	SetParent  = "set_parent"

	ManageRole      = "manage_role"
	AddRoleUsers    = "add_role_users"
	RemoveRoleUsers = "remove_role_users"
	ViewRoleUsers   = "view_role_users"

	ThingCreate           = "thing_create"
	ChannelCreate         = "channel_create"
	SubgroupCreate        = "subgroup_create"
	SubgroupThingCreate   = "subgroup_thing_create"
	SubgroupChannelCreate = "subgroup_channel_create"

	ThingUpdate           = "thing_update"
	ThingRead             = "thing_read"
	ThingDelete           = "thing_delete"
	ThingSetParentGroup   = "thing_set_parent_group"
	ThingConnectToChannel = "thing_connect_to_channel"

	ThingManageRole      = "thing_manage_role"
	ThingAddRoleUsers    = "thing_add_role_users"
	ThingRemoveRoleUsers = "thing_remove_role_users"
	ThingViewRoleUsers   = "thing_view_role_users"

	ChannelUpdate         = "channel_update"
	ChannelRead           = "channel_read"
	ChannelDelete         = "channel_delete"
	ChannelSetParentGroup = "channel_set_parent_group"
	ChannelConnectToThing = "channel_connect_to_thing"
	ChannelPublish        = "channel_publish"
	ChannelSubscribe      = "channel_subscribe"

	ChannelManageRole      = "channel_manage_role"
	ChannelAddRoleUsers    = "channel_add_role_users"
	ChannelRemoveRoleUsers = "channel_remove_role_users"
	ChannelViewRoleUsers   = "channel_view_role_users"

	SubgroupUpdate     = "subgroup_update"
	SubgroupRead       = "subgroup_read"
	SubgroupMembership = "subgroup_membership"
	SubgroupDelete     = "subgroup_delete"
	SubgroupSetChild   = "subgroup_set_child"
	SubgroupSetParent  = "subgroup_set_parent"

	SubgroupManageRole      = "subgroup_manage_role"
	SubgroupAddRoleUsers    = "subgroup_add_role_users"
	SubgroupRemoveRoleUsers = "subgroup_remove_role_users"
	SubgroupViewRoleUsers   = "subgroup_view_role_users"

	SubgroupThingUpdate           = "subgroup_thing_update"
	SubgroupThingRead             = "subgroup_thing_read"
	SubgroupThingDelete           = "subgroup_thing_delete"
	SubgroupThingSetParentGroup   = "subgroup_thing_set_parent_group"
	SubgroupThingConnectToChannel = "subgroup_thing_connect_to_channel"

	SubgroupThingManageRole      = "subgroup_thing_manage_role"
	SubgroupThingAddRoleUsers    = "subgroup_thing_add_role_users"
	SubgroupThingRemoveRoleUsers = "subgroup_thing_remove_role_users"
	SubgroupThingViewRoleUsers   = "subgroup_thing_view_role_users"

	SubgroupChannelUpdate         = "subgroup_channel_update"
	SubgroupChannelRead           = "subgroup_channel_read"
	SubgroupChannelDelete         = "subgroup_channel_delete"
	SubgroupChannelSetParentGroup = "subgroup_channel_set_parent_group"
	SubgroupChannelConnectToThing = "subgroup_channel_connect_to_thing"
	SubgroupChannelPublish        = "subgroup_channel_publish"
	SubgroupChannelSubscribe      = "subgroup_channel_subscribe"

	SubgroupChannelManageRole      = "subgroup_channel_manage_role"
	SubgroupChannelAddRoleUsers    = "subgroup_channel_add_role_users"
	SubgroupChannelRemoveRoleUsers = "subgroup_channel_remove_role_users"
	SubgroupChannelViewRoleUsers   = "subgroup_channel_view_role_users"
)

const (
	BuiltInRoleAdmin      = "admin"
	BuiltInRoleMembership = "membership"
)

const (
	Disabled = "disabled"
	Enabled  = "enabled"
	All      = "all"
	Unknown  = "unknown"
)

String representation of the possible status values.

Variables

var (
	// ErrInvalidStatus indicates invalid status.
	ErrInvalidStatus = errors.New("invalid groups status")

	// ErrEnableGroup indicates error in enabling group.
	ErrEnableGroup = errors.New("failed to enable group")

	// ErrDisableGroup indicates error in disabling group.
	ErrDisableGroup = errors.New("failed to disable group")
)

Functions

func AvailableActions

func AvailableActions() []roles.Action

func BuiltInRoles

func BuiltInRoles() map[roles.BuiltInRoleName][]roles.Action

func NewOperationPerm

func NewOperationPerm() svcutil.OperationPerm

func NewOperationPermissionMap

func NewOperationPermissionMap() map[svcutil.Operation]svcutil.Permission

func NewRolesOperationPermissionMap

func NewRolesOperationPermissionMap() map[svcutil.Operation]svcutil.Permission

Types

type Group

type Group struct {
	ID          string           `json:"id"`
	Domain      string           `json:"domain_id,omitempty"`
	Parent      string           `json:"parent_id,omitempty"`
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Metadata    clients.Metadata `json:"metadata,omitempty"`
	Level       int              `json:"level,omitempty"`
	Path        string           `json:"path,omitempty"`
	Children    []*Group         `json:"children,omitempty"`
	CreatedAt   time.Time        `json:"created_at"`
	UpdatedAt   time.Time        `json:"updated_at,omitempty"`
	UpdatedBy   string           `json:"updated_by,omitempty"`
	Status      clients.Status   `json:"status"`
	Permissions []string         `json:"permissions,omitempty"`
}

Group represents the group of Clients. Indicates a level in tree hierarchy. Root node is level 1. Path in a tree consisting of group IDs Paths are unique per domain.

type HierarchyPage

type HierarchyPage struct {
	HierarchyPageMeta
	Groups []Group
}

type HierarchyPageMeta

type HierarchyPageMeta struct {
	Level     uint64 `json:"level"`
	Direction int64  `json:"direction"` // ancestors (+1) or descendants (-1)
	// - `true`  - result is JSON tree representing groups hierarchy,
	// - `false` - result is JSON array of groups.
	// ToDo: Tree is build in API layer now, not in service layer. This need to be fine tuned.
	Tree bool `json:"tree"`
}

type Member

type Member struct {
	ID   string `json:"id"`
	Type string `json:"type"`
}

type MembersPage

type MembersPage struct {
	Total   uint64   `json:"total"`
	Offset  uint64   `json:"offset"`
	Limit   uint64   `json:"limit"`
	Members []Member `json:"members"`
}

Memberships contains page related metadata as well as list of memberships that belong to this page.

type Page

type Page struct {
	PageMeta
	Groups []Group
}

Page contains page related metadata as well as list of Groups that belong to the page.

type PageMeta

type PageMeta struct {
	Total      uint64           `json:"total"`
	Offset     uint64           `json:"offset"`
	Limit      uint64           `json:"limit"`
	Name       string           `json:"name,omitempty"`
	ID         string           `json:"id,omitempty"`
	Level      int              `json:"level,omitempty"`
	Path       string           `json:"path,omitempty"`
	DomainID   string           `json:"domain_id,omitempty"`
	Tag        string           `json:"tag,omitempty"`
	Metadata   clients.Metadata `json:"metadata,omitempty"`
	Status     clients.Status   `json:"status,omitempty"`
	Permission string
	ListPerms  bool
}

PageMeta contains page metadata that helps navigation.

type Repository

type Repository interface {
	// Save group.
	Save(ctx context.Context, g Group) (Group, error)

	// Update a group.
	Update(ctx context.Context, g Group) (Group, error)

	// RetrieveByID retrieves group by its id.
	RetrieveByID(ctx context.Context, id string) (Group, error)

	// RetrieveAll retrieves all groups.
	RetrieveAll(ctx context.Context, pm PageMeta) (Page, error)

	// RetrieveByIDs retrieves group by ids and query.
	RetrieveByIDs(ctx context.Context, pm PageMeta, ids ...string) (Page, error)

	RetrieveHierarchy(ctx context.Context, id string, hm HierarchyPageMeta) (HierarchyPage, error)

	// ChangeStatus changes groups status to active or inactive
	ChangeStatus(ctx context.Context, group Group) (Group, error)

	// AssignParentGroup assigns parent group id to a given group id
	AssignParentGroup(ctx context.Context, parentGroupID string, groupIDs ...string) error

	// UnassignParentGroup unassign parent group id fr given group id
	UnassignParentGroup(ctx context.Context, parentGroupID string, groupIDs ...string) error

	UnassignAllChildrenGroup(ctx context.Context, id string) error

	// Delete a group
	Delete(ctx context.Context, groupID string) error

	roles.Repository
}

Repository specifies a group persistence API.

type Service

type Service interface {
	// CreateGroup creates new  group.
	CreateGroup(ctx context.Context, session authn.Session, g Group) (Group, error)

	// UpdateGroup updates the group identified by the provided ID.
	UpdateGroup(ctx context.Context, session authn.Session, g Group) (Group, error)

	// ViewGroup retrieves data about the group identified by ID.
	ViewGroup(ctx context.Context, session authn.Session, id string) (Group, error)

	// ListGroups retrieves
	ListGroups(ctx context.Context, session authn.Session, pm PageMeta) (Page, error)

	// EnableGroup logically enables the group identified with the provided ID.
	EnableGroup(ctx context.Context, session authn.Session, id string) (Group, error)

	// DisableGroup logically disables the group identified with the provided ID.
	DisableGroup(ctx context.Context, session authn.Session, id string) (Group, error)

	// DeleteGroup delete the given group id
	DeleteGroup(ctx context.Context, session authn.Session, id string) error

	RetrieveGroupHierarchy(ctx context.Context, session authn.Session, id string, hm HierarchyPageMeta) (HierarchyPage, error)

	AddParentGroup(ctx context.Context, session authn.Session, id, parentID string) error

	RemoveParentGroup(ctx context.Context, session authn.Session, id string) error

	AddChildrenGroups(ctx context.Context, session authn.Session, id string, childrenGroupIDs []string) error

	RemoveChildrenGroups(ctx context.Context, session authn.Session, id string, childrenGroupIDs []string) error

	RemoveAllChildrenGroups(ctx context.Context, session authn.Session, id string) error

	ListChildrenGroups(ctx context.Context, session authn.Session, id string, pm PageMeta) (Page, error)

	roles.RoleManager
}

func NewService

func NewService(repo Repository, policy policies.Service, idp magistrala.IDProvider, channels grpcChannelsV1.ChannelsServiceClient, things grpcThingsV1.ThingsServiceClient, sidProvider magistrala.IDProvider) (Service, error)

NewService returns a new Clients service implementation.

type Status

type Status uint8

Status represents Group status.

const (
	// EnabledStatus represents enabled Group.
	EnabledStatus Status = iota
	// DisabledStatus represents disabled Group.
	DisabledStatus

	// AllStatus is used for querying purposes to list groups irrespective
	// of their status - both active and inactive. It is never stored in the
	// database as the actual Group status and should always be the largest
	// value in this enumeration.
	AllStatus
)

Possible Group status values.

func ToStatus

func ToStatus(status string) (Status, error)

ToStatus converts string value to a valid Group status.

func (Status) String

func (s Status) String() string

String converts group status to string literal.