things

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 13, 2024 License: Apache-2.0 Imports: 7 Imported by: 0

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 Mainflux, 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
MF_THINGS_LOG_LEVEL Log level for Things (debug, info, warn, error) error
MF_THINGS_DB_HOST Database host address localhost
MF_THINGS_DB_PORT Database host port 5432
MF_THINGS_DB_USER Database user mainflux
MF_THINGS_DB_PASS Database password mainflux
MF_THINGS_DB Name of the database used by the service things
MF_THINGS_DB_SSL_MODE Database connection SSL mode (disable, require, verify-ca, verify-full) disable
MF_THINGS_DB_SSL_CERT Path to the PEM encoded certificate file
MF_THINGS_DB_SSL_KEY Path to the PEM encoded key file
MF_THINGS_DB_SSL_ROOT_CERT Path to the PEM encoded root certificate file
MF_THINGS_CLIENT_TLS Flag that indicates if TLS should be turned on false
MF_THINGS_CA_CERTS Path to trusted CAs in PEM format
MF_THINGS_CACHE_URL Cache database URL localhost:6379
MF_THINGS_CACHE_PASS Cache database password
MF_THINGS_CACHE_DB Cache instance name 0
MF_THINGS_ES_URL Event store URL localhost:6379
MF_THINGS_ES_PASS Event store password
MF_THINGS_ES_DB Event store instance name 0
MF_THINGS_HTTP_PORT Things service HTTP port 8182
MF_THINGS_AUTH_HTTP_PORT Things service Auth HTTP port 8989
MF_THINGS_AUTH_GRPC_PORT Things service Auth gRPC port 8181
MF_THINGS_SERVER_CERT Path to server certificate in pem format
MF_THINGS_SERVER_KEY Path to server key in pem format
MF_THINGS_STANDALONE_EMAIL User email for standalone mode (no gRPC communication with users)
MF_THINGS_STANDALONE_TOKEN User token for standalone mode that should be passed in auth header
MF_JAEGER_URL Jaeger server URL localhost:6831
MF_AUTH_GRPC_URL Auth service gRPC URL localhost:8181
MF_AUTH_GRPC_TIMEOUT Auth service gRPC request timeout in seconds 1s

Note that if you want things service to have only one user locally, you should use MF_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 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/MainfluxLabs/mainflux

cd mainflux

# compile the things
make things

# copy binary to bin
make install

# set the environment variables and run the service
MF_THINGS_LOG_LEVEL=[Things log level] \
MF_THINGS_DB_HOST=[Database host address] \
MF_THINGS_DB_PORT=[Database host port] \
MF_THINGS_DB_USER=[Database user] \
MF_THINGS_DB_PASS=[Database password] \
MF_THINGS_DB=[Name of the database used by the service] \
MF_THINGS_DB_SSL_MODE=[SSL mode to connect to the database with] \
MF_THINGS_DB_SSL_CERT=[Path to the PEM encoded certificate file] \
MF_THINGS_DB_SSL_KEY=[Path to the PEM encoded key file] \
MF_THINGS_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file] \
MF_HTTP_ADAPTER_CA_CERTS=[Path to trusted CAs in PEM format] \
MF_THINGS_CACHE_URL=[Cache database URL] \
MF_THINGS_CACHE_PASS=[Cache database password] \
MF_THINGS_CACHE_DB=[Cache instance name] \
MF_THINGS_ES_URL=[Event store URL] \
MF_THINGS_ES_PASS=[Event store password] \
MF_THINGS_ES_DB=[Event store instance name] \
MF_THINGS_HTTP_PORT=[Things service HTTP port] \
MF_THINGS_AUTH_HTTP_PORT=[Things service Auth HTTP port] \
MF_THINGS_AUTH_GRPC_PORT=[Things service Auth gRPC port] \
MF_THINGS_SERVER_CERT=[Path to server certificate] \
MF_THINGS_SERVER_KEY=[Path to server key] \
MF_THINGS_STANDALONE_EMAIL=[User email for standalone mode (no gRPC communication with auth)] \
MF_THINGS_STANDALONE_TOKEN=[User token for standalone mode that should be passed in auth header] \
MF_JAEGER_URL=[Jaeger server URL] \
MF_AUTH_GRPC_URL=[Auth service gRPC URL] \
MF_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout in seconds] \
$GOBIN/mainfluxlabs-things

Setting MF_THINGS_CA_CERTS expects a file in PEM format of trusted CAs. This will enable TLS against the Users 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 MF_THINGS_STANDALONE_EMAIL and MF_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 Mainflux things service functionality.

Index

Constants

View Source 
const (
	Viewer = "viewer"
	Editor = "editor"
	Admin  = "admin"
)

Variables

View Source 
var (
	// ErrRetrieveGroupThings indicates failure to retrieve group things.
	ErrRetrieveGroupThings = errors.New("failed to retrieve group things")

	// ErrRetrieveGroupChannels indicates failure to retrieve group channels.
	ErrRetrieveGroupChannels = errors.New("failed to retrieve group channels")
)
View Source 
var (
	// ErrConnect indicates error in adding connection
	ErrConnect = errors.New("add connection failed")

	// ErrDisconnect indicates error in removing connection
	ErrDisconnect = errors.New("remove connection failed")

	// ErrEntityConnected indicates error while checking connection in database
	ErrEntityConnected = errors.New("check thing-channel connection in database error")
)

Functions

This section is empty.

Types

type Backup 

type Backup struct {
	Things      []Thing
	Channels    []Channel
	Connections []Connection
	Groups      []Group
	GroupRoles  []GroupMembers
}

type Channel 

type Channel struct {
	ID       string
	OwnerID  string
	GroupID  string
	Name     string
	Profile  map[string]interface{}
	Metadata map[string]interface{}
}

Channel represents a Mainflux "communication group". This group contains the things that can exchange messages between each other.

type ChannelCache 

type ChannelCache interface {
	// Connect channel thing connection.
	Connect(context.Context, string, string) error

	// HasThing checks if thing is connected to channel.
	HasThing(context.Context, string, string) bool

	// Disconnects thing from channel.
	Disconnect(context.Context, string, string) error

	// Removes channel from cache.
	Remove(context.Context, string) error
}

ChannelCache contains channel-thing connection caching interface.

type ChannelRepository 

type ChannelRepository interface {
	// Save persists multiple channels. Channels are saved using a transaction. If one channel
	// fails then none will be saved. Successful operation is indicated by non-nil
	// error response.
	Save(ctx context.Context, chs ...Channel) ([]Channel, error)

	// Update performs an update to the existing channel. A non-nil error is
	// returned to indicate operation failure.
	Update(ctx context.Context, c Channel) error

	// RetrieveByID retrieves the channel having the provided identifier, that is owned
	// by the specified user.
	RetrieveByID(ctx context.Context, id string) (Channel, error)

	// RetrieveByOwner retrieves the subset of channels owned by the specified user.
	RetrieveByOwner(ctx context.Context, owner string, pm PageMetadata) (ChannelsPage, error)

	// RetrieveByThing retrieves the channel connected to the given thing id.
	RetrieveByThing(ctx context.Context, thID string) (Channel, error)

	// Remove removes the channels having the provided identifiers, that is owned
	// by the specified user.
	Remove(ctx context.Context, owner string, id ...string) error

	// Connect connects a list of things to a channel.
	Connect(ctx context.Context, chID string, thIDs []string) error

	// Disconnect disconnects a list of things from a channel.
	Disconnect(ctx context.Context, chID string, thIDs []string) error

	// RetrieveConnByThingKey retrieves connections IDs by ThingKey
	RetrieveConnByThingKey(ctx context.Context, key string) (Connection, error)

	// RetrieveAll retrieves all channels for all users.
	RetrieveAll(ctx context.Context) ([]Channel, error)

	// RetrieveByAdmin  retrieves all channels for all users with pagination.
	RetrieveByAdmin(ctx context.Context, pm PageMetadata) (ChannelsPage, error)

	// RetrieveAllConnections retrieves all connections between channels and things for all users.
	RetrieveAllConnections(ctx context.Context) ([]Connection, error)
}

ChannelRepository specifies a channel persistence API.

type ChannelsPage 

type ChannelsPage struct {
	PageMetadata
	Channels []Channel
}

ChannelsPage contains page related metadata as well as list of channels that belong to this page.

type Connection 

type Connection struct {
	ChannelID string
	ThingID   string
}

Connection represents a connection between a channel and a thing.

type Group 

type Group struct {
	ID          string
	OwnerID     string
	OrgID       string
	Name        string
	Description string
	Metadata    GroupMetadata
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Group represents the group information.

type GroupMembers 

type GroupMembers struct {
	GroupID  string
	MemberID string
	Email    string
	Role     string
}

type GroupMetadata 

type GroupMetadata map[string]interface{}

GroupMetadata defines the Metadata type.

type GroupPage 

type GroupPage struct {
	PageMetadata
	Groups []Group
}

GroupPage contains page related metadata as well as list of groups that belong to this page.

type GroupRepository 

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

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

	// Remove a groups
	Remove(ctx context.Context, groupIDs ...string) error

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

	// RetrieveByIDs retrieves groups by their ids
	RetrieveByIDs(ctx context.Context, groupIDs []string) (GroupPage, error)

	// RetrieveByOwner retrieves all groups.
	RetrieveByOwner(ctx context.Context, ownerID, orgID string, pm PageMetadata) (GroupPage, error)

	// RetrieveThingsByGroup retrieves page of things that are assigned to a group identified by ID.
	RetrieveThingsByGroup(ctx context.Context, groupID string, pm PageMetadata) (ThingsPage, error)

	// RetrieveChannelsByGroup retrieves page of channels that are assigned to a group identified by ID.
	RetrieveChannelsByGroup(ctx context.Context, groupID string, pm PageMetadata) (ChannelsPage, error)

	// RetrieveAll retrieves all groups.
	RetrieveAll(ctx context.Context) ([]Group, error)

	// RetrieveByAdmin retrieves all groups with pagination.
	RetrieveByAdmin(ctx context.Context, orgID string, pm PageMetadata) (GroupPage, error)
}

GroupRepository specifies a group persistence API.

type GroupRoles 

type GroupRoles struct {
	MemberID string
	Role     string
}

type GroupRolesPage 

type GroupRolesPage struct {
	PageMetadata
	GroupRoles []GroupMembers
}

type Groups 

type Groups interface {
	// CreateGroups adds groups to the user identified by the provided key.
	CreateGroups(ctx context.Context, token string, groups ...Group) ([]Group, error)

	// UpdateGroup updates the group identified by the provided ID.
	UpdateGroup(ctx context.Context, token string, g Group) (Group, error)

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

	// ListGroups retrieves groups.
	ListGroups(ctx context.Context, token, orgID string, pm PageMetadata) (GroupPage, error)

	// ListGroupsByIDs retrieves groups by their IDs.
	ListGroupsByIDs(ctx context.Context, ids []string) ([]Group, error)

	// ListThingsByGroup retrieves page of things that are assigned to a group identified by ID.
	ListThingsByGroup(ctx context.Context, token string, groupID string, pm PageMetadata) (ThingsPage, error)

	// ListChannelsByGroup retrieves page of channels that are assigned to a group identified by ID.
	ListChannelsByGroup(ctx context.Context, token string, groupID string, pm PageMetadata) (ChannelsPage, error)

	// ViewGroupByThing retrieves group that thing belongs to.
	ViewGroupByThing(ctx context.Context, token, thingID string) (Group, error)

	// RemoveGroups removes the groups identified with the provided IDs.
	RemoveGroups(ctx context.Context, token string, ids ...string) error

	// ViewGroupByChannel retrieves group that channel belongs to.
	ViewGroupByChannel(ctx context.Context, token, channelID string) (Group, error)
}

type Identity 

type Identity struct {
	ID    string
	Email string
}

Identity contains ID and Email.

type Metadata 

type Metadata map[string]interface{}

Metadata to be used for Mainflux thing or channel for customized describing of particular thing or channel.

type Notifier 

type Notifier struct {
	ID       string
	GroupID  string
	Contacts []string
}

type PageMetadata 

type PageMetadata struct {
	Total    uint64
	Offset   uint64                 `json:"offset,omitempty"`
	Limit    uint64                 `json:"limit,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Order    string                 `json:"order,omitempty"`
	Dir      string                 `json:"dir,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

PageMetadata contains page metadata that helps navigation.

type Policies 

type Policies interface {
	// CreateRolesByGroup creates policies of the group identified by the provided ID.
	CreateRolesByGroup(ctx context.Context, token, groupID string, gps ...GroupRoles) error

	// ListRolesByGroup retrieves a page of policies for a group that is identified by the provided ID.
	ListRolesByGroup(ctx context.Context, token, groupID string, pm PageMetadata) (GroupRolesPage, error)

	// UpdateRolesByGroup updates policies of the group identified by the provided ID.
	UpdateRolesByGroup(ctx context.Context, token, groupID string, gps ...GroupRoles) error

	// RemoveRolesByGroup removes policies of the group identified by the provided ID.
	RemoveRolesByGroup(ctx context.Context, token, groupID string, memberIDs ...string) error
}

type Profile 

type Profile struct {
	ContentType string      `json:"content_type"`
	Write       bool        `json:"write"`
	WebhookID   string      `json:"webhook_id"`
	Transformer Transformer `json:"transformer"`
	SmtpID      string      `json:"smtp_id"`
	SmppID      string      `json:"smpp_id"`
}

type RolesRepository 

type RolesRepository interface {
	// SaveRolesByGroup saves group roles by group ID.
	SaveRolesByGroup(ctx context.Context, groupID string, gps ...GroupRoles) error

	// RetrieveRole retrieves group role by group ID.
	RetrieveRole(ctc context.Context, gp GroupMembers) (string, error)

	// RetrieveRolesByGroup retrieves page of group roles by groupID.
	RetrieveRolesByGroup(ctx context.Context, groupID string, pm PageMetadata) (GroupRolesPage, error)

	// RetrieveAllRolesByGroup retrieves all group roles by group ID. This is used for backup.
	RetrieveAllRolesByGroup(ctx context.Context) ([]GroupMembers, error)

	// RemoveRolesByGroup removes group roles by group ID.
	RemoveRolesByGroup(ctx context.Context, groupID string, memberIDs ...string) error

	// UpdateRolesByGroup updates group roles by group ID.
	UpdateRolesByGroup(ctx context.Context, groupID string, gps ...GroupRoles) error
}

type Service 

type Service interface {
	// CreateThings adds things to the user identified by the provided key.
	CreateThings(ctx context.Context, token string, things ...Thing) ([]Thing, error)

	// UpdateThing updates the thing identified by the provided ID, that
	// belongs to the user identified by the provided key.
	UpdateThing(ctx context.Context, token string, thing Thing) error

	// UpdateKey updates key value of the existing thing. A non-nil error is
	// returned to indicate operation failure.
	UpdateKey(ctx context.Context, token, id, key string) error

	// ViewThing retrieves data about the thing identified with the provided
	// ID, that belongs to the user identified by the provided key.
	ViewThing(ctx context.Context, token, id string) (Thing, error)

	// ListThings retrieves data about subset of things that belongs to the
	// user identified by the provided key.
	ListThings(ctx context.Context, token string, pm PageMetadata) (ThingsPage, error)

	// ListThingsByIDs retrieves data about subset of things that are identified
	ListThingsByIDs(ctx context.Context, ids []string) (ThingsPage, error)

	// ListThingsByChannel retrieves data about subset of things that are
	// connected or not connected to specified channel and belong to the user identified by
	// the provided key.
	ListThingsByChannel(ctx context.Context, token, chID string, pm PageMetadata) (ThingsPage, error)

	// RemoveThings removes the things identified with the provided IDs, that
	// belongs to the user identified by the provided key.
	RemoveThings(ctx context.Context, token string, id ...string) error

	// CreateChannels adds channels to the user identified by the provided key.
	CreateChannels(ctx context.Context, token string, channels ...Channel) ([]Channel, error)

	// UpdateChannel updates the channel identified by the provided ID, that
	// belongs to the user identified by the provided key.
	UpdateChannel(ctx context.Context, token string, channel Channel) error

	// ViewChannel retrieves data about the channel identified by the provided
	// ID, that belongs to the user identified by the provided key.
	ViewChannel(ctx context.Context, token, id string) (Channel, error)

	// ListChannels retrieves data about subset of channels that belongs to the
	// user identified by the provided key.
	ListChannels(ctx context.Context, token string, pm PageMetadata) (ChannelsPage, error)

	// ViewChannelByThing retrieves data about channel that have
	// specified thing connected or not connected to it and belong to the user identified by
	// the provided key.
	ViewChannelByThing(ctx context.Context, token, thID string) (Channel, error)

	// RemoveChannels removes the things identified by the provided IDs, that
	// belongs to the user identified by the provided key.
	RemoveChannels(ctx context.Context, token string, ids ...string) error

	// ViewChannelProfile retrieves channel profile.
	ViewChannelProfile(ctx context.Context, chID string) (Profile, error)

	// Connect connects a list of things to a channel.
	Connect(ctx context.Context, token, chID string, thIDs []string) error

	// Disconnect disconnects a list of things from a channel.
	Disconnect(ctx context.Context, token, chID string, thIDs []string) error

	// GetConnByKey determines whether the channel can be accessed using the
	// provided key and returns thing's id if access is allowed.
	GetConnByKey(ctx context.Context, key string) (Connection, error)

	// IsChannelOwner determines whether the channel can be accessed by
	// the given user and returns error if it cannot.
	IsChannelOwner(ctx context.Context, owner, chanID string) error

	// CanAccessGroup determines whether the thing can be accessed by
	// the given user and returns error if it cannot.
	CanAccessGroup(ctx context.Context, token, groupID, action string) error

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

	// Backup retrieves all things, channels and connections for all users. Only accessible by admin.
	Backup(ctx context.Context, token string) (Backup, error)

	// Restore adds things, channels and connections from a backup. Only accessible by admin.
	Restore(ctx context.Context, token string, backup Backup) error

	Groups

	Policies
}

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

func New 

func New(auth protomfx.AuthServiceClient, users protomfx.UsersServiceClient, things ThingRepository, channels ChannelRepository, groups GroupRepository, roles RolesRepository, ccache ChannelCache, tcache ThingCache, idp uuid.IDProvider) Service

New instantiates the things service implementation.

type Thing 

type Thing struct {
	ID       string
	OwnerID  string
	GroupID  string
	Name     string
	Key      string
	Metadata Metadata
}

Thing represents a Mainflux thing. Each thing is owned by one user, and it is assigned with the unique identifier and (temporary) access key.

type ThingCache 

type ThingCache interface {
	// Save stores pair thing key, thing id.
	Save(context.Context, string, string) error

	// ID returns thing ID for given key.
	ID(context.Context, string) (string, error)

	// Removes thing from cache.
	Remove(context.Context, string) error
}

ThingCache contains thing caching interface.

type ThingRepository 

type ThingRepository interface {
	// Save persists multiple things. Things are saved using a transaction. If one thing
	// fails then none will be saved. Successful operation is indicated by non-nil
	// error response.
	Save(ctx context.Context, ths ...Thing) ([]Thing, error)

	// Update performs an update to the existing thing. A non-nil error is
	// returned to indicate operation failure.
	Update(ctx context.Context, t Thing) error

	// UpdateKey updates key value of the existing thing. A non-nil error is
	// returned to indicate operation failure.
	UpdateKey(ctx context.Context, owner, id, key string) error

	// RetrieveByID retrieves the thing having the provided identifier, that is owned
	// by the specified user.
	RetrieveByID(ctx context.Context, id string) (Thing, error)

	// RetrieveByKey returns thing ID for given thing key.
	RetrieveByKey(ctx context.Context, key string) (string, error)

	// RetrieveByOwner retrieves the subset of things owned by the specified user
	RetrieveByOwner(ctx context.Context, owner string, pm PageMetadata) (ThingsPage, error)

	// RetrieveByIDs retrieves the subset of things specified by given thing ids.
	RetrieveByIDs(ctx context.Context, thingIDs []string, pm PageMetadata) (ThingsPage, error)

	// RetrieveByChannel retrieves the subset of things owned by the specified
	// user and connected or not connected to specified channel.
	RetrieveByChannel(ctx context.Context, chID string, pm PageMetadata) (ThingsPage, error)

	// Remove removes the things having the provided identifiers, that is owned
	// by the specified user.
	Remove(ctx context.Context, owner string, ids ...string) error

	// RetrieveAll retrieves all things for all users.
	RetrieveAll(ctx context.Context) ([]Thing, error)

	// RetrieveByAdmin retrieves all things for all users with pagination.
	RetrieveByAdmin(ctx context.Context, pm PageMetadata) (ThingsPage, error)
}

ThingRepository specifies a thing persistence API.

type ThingsPage 

type ThingsPage struct {
	PageMetadata
	Things []Thing
}

ThingsPage contains page related metadata as well as list of things that belong to this page.

type Transformer 

type Transformer struct {
	ValueFields  []string `json:"value_fields"`
	TimeField    string   `json:"time_field"`
	TimeFormat   string   `json:"time_format"`
	TimeLocation string   `json:"time_location"`
}

Source Files

View all Source files

Directories

Path Synopsis
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
 Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
grpc
Package grpc contains implementation of things service gRPC API.
 Package grpc contains implementation of things service gRPC API.
http
Package http contains implementation of things service HTTP API.
 Package http contains implementation of things service HTTP API.
Package postgres contains repository implementations using PostgreSQL as the underlying database.
 Package postgres contains repository implementations using PostgreSQL as the underlying database.
Package redis contains cache implementations using Redis as the underlying database.
 Package redis contains cache implementations using Redis as the underlying database.
Package standalone contains implementation for auth service in single-user scenario.
 Package standalone contains implementation for auth service in single-user scenario.
Package tracing contains middlewares that will add spans to existing traces.
 Package tracing contains middlewares that will add spans to existing traces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.