invitations

README

Invitation Service

Invitation service is responsible for sending invitations to users to join a domain.

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Variable	Description	Default
MG_INVITATION_LOG_LEVEL	Log level for the Invitation service	debug
MG_USERS_URL	Users service URL	http://localhost:9002
MG_DOMAINS_URL	Domains service URL	http://localhost:8189
MG_INVITATIONS_HTTP_HOST	Invitation service HTTP listening host	localhost
MG_INVITATIONS_HTTP_PORT	Invitation service HTTP listening port	9020
MG_INVITATIONS_HTTP_SERVER_CERT	Invitation service server certificate	""
MG_INVITATIONS_HTTP_SERVER_KEY	Invitation service server key	""
MG_AUTH_GRPC_URL	Auth service gRPC URL	localhost:8181
MG_AUTH_GRPC_TIMEOUT	Auth service gRPC request timeout in seconds	1s
MG_AUTH_GRPC_CLIENT_CERT	Path to client certificate in PEM format	""
MG_AUTH_GRPC_CLIENT_KEY	Path to client key in PEM format	""
MG_AUTH_GRPC_CLIENT_CA_CERTS	Path to trusted CAs in PEM format	""
MG_INVITATIONS_DB_HOST	Invitation service database host	localhost
MG_INVITATIONS_DB_USER	Invitation service database user	magistrala
MG_INVITATIONS_DB_PASS	Invitation service database password	magistrala
MG_INVITATIONS_DB_PORT	Invitation service database port	5432
MG_INVITATIONS_DB_NAME	Invitation service database name	invitations
MG_INVITATIONS_DB_SSL_MODE	Invitation service database SSL mode	disable
MG_INVITATIONS_DB_SSL_CERT	Invitation service database SSL certificate	""
MG_INVITATIONS_DB_SSL_KEY	Invitation service database SSL key	""
MG_INVITATIONS_DB_SSL_ROOT_CERT	Invitation service database SSL root certificate	""
MG_INVITATIONS_INSTANCE_ID	Invitation service instance ID

Deployment

The service itself is distributed as Docker container. Check the invitation service section in docker-compose file to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the http
make invitation

# copy binary to bin
make install

# set the environment variables and run the service
MG_INVITATION_LOG_LEVEL=info \
MG_INVITATIONS_ENDPOINT=/invitations \
MG_USERS_URL="http://localhost:9002" \
MG_DOMAINS_URL="http://localhost:8189" \
MG_INVITATIONS_HTTP_HOST=localhost \
MG_INVITATIONS_HTTP_PORT=9020 \
MG_INVITATIONS_HTTP_SERVER_CERT="" \
MG_INVITATIONS_HTTP_SERVER_KEY="" \
MG_AUTH_GRPC_URL=localhost:8181 \
MG_AUTH_GRPC_TIMEOUT=1s \
MG_AUTH_GRPC_CLIENT_CERT="" \
MG_AUTH_GRPC_CLIENT_KEY="" \
MG_AUTH_GRPC_CLIENT_CA_CERTS="" \
MG_INVITATIONS_DB_HOST=localhost \
MG_INVITATIONS_DB_USER=magistrala \
MG_INVITATIONS_DB_PASS=magistrala \
MG_INVITATIONS_DB_PORT=5432 \
MG_INVITATIONS_DB_NAME=invitations \
MG_INVITATIONS_DB_SSL_MODE=disable \
MG_INVITATIONS_DB_SSL_CERT="" \
MG_INVITATIONS_DB_SSL_KEY="" \
MG_INVITATIONS_DB_SSL_ROOT_CERT="" \
$GOBIN/magistrala-invitation

Usage

For more information about service capabilities and its usage, please check out the API documentation.

Documentation

Overview

Package invitations provides the API to manage invitations.

An invitation is a request to join a domain.

Index

• func CheckRelation(relation string) error
• type Invitation
• type InvitationPage
  • func (page InvitationPage) MarshalJSON() ([]byte, error)
• type Page
• type Repository
• type Service
  • func NewService(token magistrala.TokenServiceClient, repo Repository, sdk mgsdk.SDK) Service
• type State
  • func ToState(status string) (State, error)
  • func (s State) MarshalJSON() ([]byte, error)
  • func (s State) String() string
  • func (s *State) UnmarshalJSON(data []byte) error

Functions

func CheckRelation

func CheckRelation(relation string) error

CheckRelation checks if the given relation is valid. It returns an error if the relation is empty or invalid.

Types

type Invitation

type Invitation struct {
	InvitedBy   string    `json:"invited_by"`
	UserID      string    `json:"user_id"`
	DomainID    string    `json:"domain_id"`
	Token       string    `json:"token,omitempty"`
	Relation    string    `json:"relation,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at,omitempty"`
	ConfirmedAt time.Time `json:"confirmed_at,omitempty"`
	RejectedAt  time.Time `json:"rejected_at,omitempty"`
	Resend      bool      `json:"resend,omitempty"`
}

Invitation is an invitation to join a domain.

type InvitationPage

type InvitationPage struct {
	Total       uint64       `json:"total"`
	Offset      uint64       `json:"offset"`
	Limit       uint64       `json:"limit"`
	Invitations []Invitation `json:"invitations"`
}

InvitationPage is a page of invitations.

func (InvitationPage) MarshalJSON

func (page InvitationPage) MarshalJSON() ([]byte, error)

type Page

type Page struct {
	Offset            uint64 `json:"offset" db:"offset"`
	Limit             uint64 `json:"limit" db:"limit"`
	InvitedBy         string `json:"invited_by,omitempty" db:"invited_by,omitempty"`
	UserID            string `json:"user_id,omitempty" db:"user_id,omitempty"`
	DomainID          string `json:"domain_id,omitempty" db:"domain_id,omitempty"`
	Relation          string `json:"relation,omitempty" db:"relation,omitempty"`
	InvitedByOrUserID string `db:"invited_by_or_user_id,omitempty"`
	State             State  `json:"state,omitempty"`
}

Page is a page of invitations.

type Repository

type Repository interface {
	// Create creates an invitation.
	Create(ctx context.Context, invitation Invitation) (err error)

	// Retrieve returns an invitation.
	Retrieve(ctx context.Context, userID, domainID string) (Invitation, error)

	// RetrieveAll returns a list of invitations based on the given page.
	RetrieveAll(ctx context.Context, page Page) (invitations InvitationPage, err error)

	// UpdateToken updates an invitation by setting the token.
	UpdateToken(ctx context.Context, invitation Invitation) (err error)

	// UpdateConfirmation updates an invitation by setting the confirmation time.
	UpdateConfirmation(ctx context.Context, invitation Invitation) (err error)

	// UpdateRejection updates an invitation by setting the rejection time.
	UpdateRejection(ctx context.Context, invitation Invitation) (err error)

	// Delete deletes an invitation.
	Delete(ctx context.Context, userID, domainID string) (err error)
}

type Service

type Service interface {
	// SendInvitation sends an invitation to the given user.
	// Only domain administrators and platform administrators can send invitations.
	SendInvitation(ctx context.Context, session authn.Session, invitation Invitation) (err error)

	// ViewInvitation returns an invitation.
	// People who can view invitations are:
	// - the invited user: they can view their own invitations
	// - the user who sent the invitation
	// - domain administrators
	// - platform administrators
	ViewInvitation(ctx context.Context, session authn.Session, userID, domainID string) (invitation Invitation, err error)

	// ListInvitations returns a list of invitations.
	// People who can list invitations are:
	// - platform administrators can list all invitations
	// - domain administrators can list invitations for their domain
	// By default, it will list invitations the current user has sent or received.
	ListInvitations(ctx context.Context, session authn.Session, page Page) (invitations InvitationPage, err error)

	// AcceptInvitation accepts an invitation by adding the user to the domain.
	AcceptInvitation(ctx context.Context, session authn.Session, domainID string) (err error)

	// DeleteInvitation deletes an invitation.
	// People who can delete invitations are:
	// - the invited user: they can delete their own invitations
	// - the user who sent the invitation
	// - domain administrators
	// - platform administrators
	DeleteInvitation(ctx context.Context, session authn.Session, userID, domainID string) (err error)

	// RejectInvitation rejects an invitation.
	// People who can reject invitations are:
	// - the invited user: they can reject their own invitations
	RejectInvitation(ctx context.Context, session authn.Session, domainID string) (err error)
}

Service is an interface that defines methods for managing invitations.

func NewService

func NewService(token magistrala.TokenServiceClient, repo Repository, sdk mgsdk.SDK) Service

type State

type State uint8

State represents invitation state.

const (
	All      State = iota // All is used for querying purposes to list invitations irrespective of their state - both pending and accepted.
	Pending               // Pending is the state of an invitation that has not been accepted yet.
	Accepted              // Accepted is the state of an invitation that has been accepted.
	Rejected              // Rejected is the state of an invitation that has been rejected.
)

func ToState

func ToState(status string) (State, error)

ToState converts string value to a valid invitation state.

func (State) MarshalJSON

func (s State) MarshalJSON() ([]byte, error)

func (State) String

func (s State) String() string

String converts invitation state to string literal.

func (*State) UnmarshalJSON

func (s *State) UnmarshalJSON(data []byte) error

Custom Unmarshaler for Client/Groups.