things

README

Things

Things service provides an HTTP API for managing platform resources: things and channels. Through this API clients are able to do the following actions:

• provision new things
• create new channels
• "connect" things into the channels

For an in-depth explanation of the aforementioned scenarios, as well as thorough understanding of Magistrala, please check out the official documentation.

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_THINGS_LOG_LEVEL	Log level for Things (debug, info, warn, error)	info
MG_THINGS_HTTP_HOST	Things service HTTP host	localhost
MG_THINGS_HTTP_PORT	Things service HTTP port	9000
MG_THINGS_SERVER_CERT	Path to the PEM encoded server certificate file	""
MG_THINGS_SERVER_KEY	Path to the PEM encoded server key file	""
MG_THINGS_AUTH_GRPC_HOST	Things service gRPC host	localhost
MG_THINGS_AUTH_GRPC_PORT	Things service gRPC port	7000
MG_THINGS_AUTH_GRPC_SERVER_CERT	Path to the PEM encoded server certificate file	""
MG_THINGS_AUTH_GRPC_SERVER_KEY	Path to the PEM encoded server key file	""
MG_THINGS_DB_HOST	Database host address	localhost
MG_THINGS_DB_PORT	Database host port	5432
MG_THINGS_DB_USER	Database user	magistrala
MG_THINGS_DB_PASS	Database password	magistrala
MG_THINGS_DB_NAME	Name of the database used by the service	things
MG_THINGS_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
MG_THINGS_DB_SSL_CERT	Path to the PEM encoded certificate file	""
MG_THINGS_DB_SSL_KEY	Path to the PEM encoded key file	""
MG_THINGS_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file	""
MG_THINGS_CACHE_URL	Cache database URL	redis://localhost:6379/0
MG_THINGS_CACHE_KEY_DURATION	Cache key duration in seconds	3600
MG_THINGS_ES_URL	Event store URL	localhost:6379
MG_THINGS_ES_PASS	Event store password	""
MG_THINGS_ES_DB	Event store instance name	0
MG_THINGS_STANDALONE_ID	User ID for standalone mode (no gRPC communication with Auth)	""
MG_THINGS_STANDALONE_TOKEN	User token for standalone mode that should be passed in auth header	""
MG_JAEGER_URL	Jaeger server URL	http://jaeger:4318/v1/traces
MG_AUTH_GRPC_URL	Auth service gRPC URL	localhost:7001
MG_AUTH_GRPC_TIMEOUT	Auth service gRPC request timeout in seconds	1s
MG_AUTH_GRPC_CLIENT_TLS	Enable TLS for gRPC client	false
MG_AUTH_GRPC_CA_CERT	Path to the CA certificate file	""
MG_SEND_TELEMETRY	Send telemetry to magistrala call home server.	true
MG_THINGS_INSTANCE_ID	Things instance ID	""

Note that if you want things service to have only one user locally, you should use MG_THINGS_STANDALONE env vars. By specifying these, you don't need auth service in your deployment for users' authorization.

Deployment

The service itself is distributed as Docker container. Check the things 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 things
make things

# copy binary to bin
make install

# set the environment variables and run the service
MG_THINGS_LOG_LEVEL=[Things log level] \
MG_THINGS_STANDALONE_ID=[User ID for standalone mode (no gRPC communication with auth)] \
MG_THINGS_STANDALONE_TOKEN=[User token for standalone mode that should be passed in auth header] \
MG_THINGS_CACHE_KEY_DURATION=[Cache key duration in seconds] \
MG_THINGS_HTTP_HOST=[Things service HTTP host] \
MG_THINGS_HTTP_PORT=[Things service HTTP port] \
MG_THINGS_HTTP_SERVER_CERT=[Path to server certificate in pem format] \
MG_THINGS_HTTP_SERVER_KEY=[Path to server key in pem format] \
MG_THINGS_AUTH_GRPC_HOST=[Things service gRPC host] \
MG_THINGS_AUTH_GRPC_PORT=[Things service gRPC port] \
MG_THINGS_AUTH_GRPC_SERVER_CERT=[Path to server certificate in pem format] \
MG_THINGS_AUTH_GRPC_SERVER_KEY=[Path to server key in pem format] \
MG_THINGS_DB_HOST=[Database host address] \
MG_THINGS_DB_PORT=[Database host port] \
MG_THINGS_DB_USER=[Database user] \
MG_THINGS_DB_PASS=[Database password] \
MG_THINGS_DB_NAME=[Name of the database used by the service] \
MG_THINGS_DB_SSL_MODE=[SSL mode to connect to the database with] \
MG_THINGS_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
MG_THINGS_DB_SSL_KEY=[Path to the PEM encoded key file] \
MG_THINGS_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
MG_THINGS_CACHE_URL=[Cache database URL] \
MG_THINGS_ES_URL=[Event store URL] \
MG_THINGS_ES_PASS=[Event store password] \
MG_THINGS_ES_DB=[Event store instance name] \
MG_AUTH_GRPC_URL=[Auth service gRPC URL] \
MG_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout in seconds] \
MG_AUTH_GRPC_CLIENT_TLS=[Enable TLS for gRPC client] \
MG_AUTH_GRPC_CA_CERT=[Path to trusted CA certificate file] \
MG_JAEGER_URL=[Jaeger server URL] \
MG_SEND_TELEMETRY=[Send telemetry to magistrala call home server] \
MG_THINGS_INSTANCE_ID=[Things instance ID] \
$GOBIN/magistrala-things

Setting MG_THINGS_CA_CERTS expects a file in PEM format of trusted CAs. This will enable TLS against the Auth gRPC endpoint trusting only those CAs that are provided.

In constrained environments, sometimes it makes sense to run Things service as a standalone to reduce network traffic and simplify deployment. This means that Things service operates only using a single user and is able to authorize it without gRPC communication with Auth service. To run service in a standalone mode, set MG_THINGS_STANDALONE_EMAIL and MG_THINGS_STANDALONE_TOKEN.

Usage

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

Documentation

Overview

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

This package defines the core domain concepts and types necessary to handle things in the context of a Magistrala things service. It abstracts the underlying complexities of user management and provides a structured approach to working with things.

Copyright (c) Abstract Machines SPDX-License-Identifier: Apache-2.0

Index

• Constants
• Variables
• type AuthzReq
• type Cache
• type Client
  • func (client Client) MarshalJSON() ([]byte, error)
• type ClientRepository
• type ClientsPage
• type Credentials
• type MembersPage
• type Metadata
• type Page
• type Repository
• type Role
  • func ToRole(status string) (Role, error)
  • func (r Role) MarshalJSON() ([]byte, error)
  • func (cs Role) String() string
  • func (r *Role) UnmarshalJSON(data []byte) error
• type Service
  • func NewService(policyEvaluator policies.Evaluator, policyService policies.Service, ...) Service
• type Status
  • func ToStatus(status string) (Status, error)
  • func (s Status) MarshalJSON() ([]byte, error)
  • func (s Status) String() string
  • func (s *Status) UnmarshalJSON(data []byte) error

Constants

const (
	Admin = "admin"
	User  = "user"
)

String representation of the possible role values.

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

String representation of the possible status values.

Variables

var (
	// ErrEnableClient indicates error in enabling client.
	ErrEnableClient = errors.New("failed to enable client")

	// ErrDisableClient indicates error in disabling client.
	ErrDisableClient = errors.New("failed to disable client")
)

Types

type AuthzReq

type AuthzReq struct {
	ChannelID  string
	ClientID   string
	ClientKey  string
	Permission string
}

type Cache

type Cache interface {
	// Save stores pair client secret, client id.
	Save(ctx context.Context, clientSecret, clientID string) error

	// ID returns client ID for given client secret.
	ID(ctx context.Context, clientSecret string) (string, error)

	// Removes client from cache.
	Remove(ctx context.Context, clientID string) error
}

Cache contains client caching interface.

type Client

type Client struct {
	ID          string      `json:"id"`
	Name        string      `json:"name,omitempty"`
	Tags        []string    `json:"tags,omitempty"`
	Domain      string      `json:"domain_id,omitempty"`
	Credentials Credentials `json:"credentials,omitempty"`
	Metadata    Metadata    `json:"metadata,omitempty"`
	CreatedAt   time.Time   `json:"created_at,omitempty"`
	UpdatedAt   time.Time   `json:"updated_at,omitempty"`
	UpdatedBy   string      `json:"updated_by,omitempty"`
	Status      Status      `json:"status,omitempty"` // 1 for enabled, 0 for disabled
	Permissions []string    `json:"permissions,omitempty"`
	Identity    string      `json:"identity,omitempty"`
}

func (Client) MarshalJSON

func (client Client) MarshalJSON() ([]byte, error)

type ClientRepository

type ClientRepository struct {
	DB postgres.Database
}

type ClientsPage

type ClientsPage struct {
	Page
	Clients []Client
}

ClientsPage contains page related metadata as well as list.

type Credentials

type Credentials struct {
	Identity string `json:"identity,omitempty"` // username or generated login ID
	Secret   string `json:"secret,omitempty"`   // password or token
}

Credentials represent client credentials: its "identity" which can be a username, email, generated name; and "secret" which can be a password or access token.

type MembersPage

type MembersPage struct {
	Page
	Members []Client
}

type Metadata

type Metadata map[string]interface{}

Metadata represents arbitrary JSON.

type Page

type Page struct {
	Total      uint64   `json:"total"`
	Offset     uint64   `json:"offset"`
	Limit      uint64   `json:"limit"`
	Name       string   `json:"name,omitempty"`
	Id         string   `json:"id,omitempty"`
	Order      string   `json:"order,omitempty"`
	Dir        string   `json:"dir,omitempty"`
	Metadata   Metadata `json:"metadata,omitempty"`
	Domain     string   `json:"domain,omitempty"`
	Tag        string   `json:"tag,omitempty"`
	Permission string   `json:"permission,omitempty"`
	Status     Status   `json:"status,omitempty"`
	IDs        []string `json:"ids,omitempty"`
	Identity   string   `json:"identity,omitempty"`
	ListPerms  bool     `json:"-"`
}

type Repository

type Repository interface {
	// RetrieveByID retrieves client by its unique ID.
	RetrieveByID(ctx context.Context, id string) (Client, error)

	// RetrieveAll retrieves all clients.
	RetrieveAll(ctx context.Context, pm Page) (ClientsPage, error)

	// SearchClients retrieves clients based on search criteria.
	SearchClients(ctx context.Context, pm Page) (ClientsPage, error)

	// RetrieveAllByIDs retrieves for given client IDs .
	RetrieveAllByIDs(ctx context.Context, pm Page) (ClientsPage, error)

	// Update updates the client name and metadata.
	Update(ctx context.Context, client Client) (Client, error)

	// UpdateTags updates the client tags.
	UpdateTags(ctx context.Context, client Client) (Client, error)

	// UpdateIdentity updates identity for client with given id.
	UpdateIdentity(ctx context.Context, client Client) (Client, error)

	// UpdateSecret updates secret for client with given identity.
	UpdateSecret(ctx context.Context, client Client) (Client, error)

	// ChangeStatus changes client status to enabled or disabled
	ChangeStatus(ctx context.Context, client Client) (Client, error)

	// Delete deletes client with given id
	Delete(ctx context.Context, id string) error

	// Save persists the client account. A non-nil error is returned to indicate
	// operation failure.
	Save(ctx context.Context, client ...Client) ([]Client, error)

	// RetrieveBySecret retrieves a client based on the secret (key).
	RetrieveBySecret(ctx context.Context, key string) (Client, error)
}

Repository is the interface that wraps the basic methods for a client repository.

type Role

type Role uint8

Role represents Client role.

const (
	UserRole Role = iota
	AdminRole

	// AllRole is used for querying purposes to list clients irrespective
	// of their role - both admin and user. It is never stored in the
	// database as the actual Client role and should always be the largest
	// value in this enumeration.
	AllRole
)

Possible Client role values.

func ToRole

func ToRole(status string) (Role, error)

ToRole converts string value to a valid Client role.

func (Role) MarshalJSON

func (r Role) MarshalJSON() ([]byte, error)

func (Role) String

func (cs Role) String() string

String converts client role to string literal.

func (*Role) UnmarshalJSON

func (r *Role) UnmarshalJSON(data []byte) error

type Service

type Service interface {
	// CreateClients creates new client. In case of the failed registration, a
	// non-nil error value is returned.
	CreateClients(ctx context.Context, session authn.Session, client ...Client) ([]Client, error)

	// View retrieves client info for a given client ID and an authorized token.
	View(ctx context.Context, session authn.Session, id string) (Client, error)

	// ViewPerms retrieves permissions on the client id for the given authorized token.
	ViewPerms(ctx context.Context, session authn.Session, id string) ([]string, error)

	// ListClients retrieves clients list for a valid auth token.
	ListClients(ctx context.Context, session authn.Session, reqUserID string, pm Page) (ClientsPage, error)

	// ListClientsByGroup retrieves data about subset of clients that are
	// connected or not connected to specified channel and belong to the user identified by
	// the provided key.
	ListClientsByGroup(ctx context.Context, session authn.Session, groupID string, pm Page) (MembersPage, error)

	// Update updates the client's name and metadata.
	Update(ctx context.Context, session authn.Session, client Client) (Client, error)

	// UpdateTags updates the client's tags.
	UpdateTags(ctx context.Context, session authn.Session, client Client) (Client, error)

	// UpdateSecret updates the client's secret
	UpdateSecret(ctx context.Context, session authn.Session, id, key string) (Client, error)

	// Enable logically enableds the client identified with the provided ID
	Enable(ctx context.Context, session authn.Session, id string) (Client, error)

	// Disable logically disables the client identified with the provided ID
	Disable(ctx context.Context, session authn.Session, id string) (Client, error)

	// Share add share policy to client id with given relation for given user ids
	Share(ctx context.Context, session authn.Session, id string, relation string, userids ...string) error

	// Unshare remove share policy to client id with given relation for given user ids
	Unshare(ctx context.Context, session authn.Session, id string, relation string, userids ...string) error

	// Identify returns client ID for given client key.
	Identify(ctx context.Context, key string) (string, error)

	// Authorize used for Clients authorization.
	Authorize(ctx context.Context, req AuthzReq) (string, error)

	// Delete deletes client with given ID.
	Delete(ctx context.Context, session authn.Session, id string) error
}

Service specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func NewService

func NewService(policyEvaluator policies.Evaluator, policyService policies.Service, c Repository, tcache Cache, idp magistrala.IDProvider) Service

NewService returns a new Things service implementation.

type Status

type Status uint8

Status represents Client status.

const (
	// EnabledStatus represents enabled Client.
	EnabledStatus Status = iota
	// DisabledStatus represents disabled Client.
	DisabledStatus
	// DeletedStatus represents a client that will be deleted.
	DeletedStatus

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

Possible Client status values.

func ToStatus

func ToStatus(status string) (Status, error)

ToStatus converts string value to a valid Client status.

func (Status) MarshalJSON

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

Custom Marshaller for Client.

func (Status) String

func (s Status) String() string

String converts client/group status to string literal.

func (*Status) UnmarshalJSON

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

Custom Unmarshaler for Client.