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 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	8180
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_SINGLE_USER_EMAIL	User email for single user mode (no gRPC communication with users)
MF_THINGS_SINGLE_USER_TOKEN	User token for single user mode that should be passed in auth header
MF_JAEGER_URL	Jaeger server URL	localhost:6831
MF_AUTHN_GRPC_URL	AuthN service gRPC URL	localhost:8181
MF_AUTHN_GRPC_TIMEOUT	AuthN 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_SINGLE_USER env vars. By specifying these, you don't need users service in your deployment as it won't be used for authorization.

Deployment

The service itself is distributed as Docker container. The following snippet provides a compose file template that can be used to deploy the service container locally:

version: "2"
services:
  things:
    image: mainflux/things:[version]
    container_name: [instance name]
    ports:
      - [host machine port]:[configured HTTP port]
    environment:
      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_THINGS_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 that should be used]
      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: [String path to server cert in pem format]
      MF_THINGS_SERVER_KEY: [String path to server key in pem format]
      MF_THINGS_SINGLE_USER_EMAIL: [User email for single user mode (no gRPC communication with users)]
      MF_THINGS_SINGLE_USER_TOKEN: [User token for single user mode that should be passed in auth header]
      MF_JAEGER_URL: [Jaeger server URL]
      MF_AUTHN_GRPC_URL: [AuthN service gRPC URL]
      MF_AUTHN_GRPC_TIMEOUT: [AuthN service gRPC request timeout in seconds]

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

# download the latest version of the service
git clone https://gitee.com/shtemmi/iotflux

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_SINGLE_USER_EMAIL=[User email for single user mode (no gRPC communication with users)] \
MF_THINGS_SINGLE_USER_TOKEN=[User token for single user mode that should be passed in auth header] \
MF_JAEGER_URL=[Jaeger server URL] \
MF_AUTHN_GRPC_URL=[AuthN service gRPC URL] \
MF_AUTHN_GRPC_TIMEOUT=[AuthN service gRPC request timeout in seconds] \
$GOBIN/mainflux-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.

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

• Variables
• type Channel
• type ChannelCache
• type ChannelRepository
• type ChannelsPage
• type Metadata
• type Page
• type PageMetadata
• type Service
  • func New(auth mainflux.AuthNServiceClient, things ThingRepository, ...) Service
• type Thing
• type ThingCache
• type ThingRepository

Variables

var (
	// ErrUnauthorizedAccess indicates missing or invalid credentials provided
	// when accessing a protected resource.
	ErrUnauthorizedAccess = errors.New("missing or invalid credentials provided")

	// ErrCreateUUID indicates error in creating uuid for entity creation
	ErrCreateUUID = errors.New("uuid creation failed")

	// ErrCreateEntity indicates error in creating entity or entities
	ErrCreateEntity = errors.New("create entity failed")

	// ErrUpdateEntity indicates error in updating entity or entities
	ErrUpdateEntity = errors.New("update entity failed")

	// ErrViewEntity indicates error in viewing entity or entities
	ErrViewEntity = errors.New("view entity failed")

	// ErrRemoveEntity indicates error in removing entity
	ErrRemoveEntity = errors.New("remove entity failed")

	// ErrConnect indicates error in adding connection
	ErrConnect = errors.New("add connection failed")

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

var (
	// ErrMalformedEntity indicates malformed entity specification (e.g.
	// invalid username or password).
	ErrMalformedEntity = errors.New("malformed entity specification")

	// ErrNotFound indicates a non-existent entity request.
	ErrNotFound = errors.New("non-existent entity")

	// ErrConflict indicates that entity already exists.
	ErrConflict = errors.New("entity already exists")

	// ErrScanMetadata indicates problem with metadata in db
	ErrScanMetadata = errors.New("failed to scan metadata in db")

	// ErrSelectEntity indicates error while reading entity from database
	ErrSelectEntity = errors.New("select entity from db error")

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

Types

type Channel

type Channel struct {
	ID       string
	Owner    string
	Name     string
	Metadata map[string]interface{}
}

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

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, owner, id string) (Channel, error)

	// RetrieveAll retrieves the subset of channels owned by the specified user.
	RetrieveAll(ctx context.Context, owner string, offset, limit uint64, name string, m Metadata) (ChannelsPage, error)

	// RetrieveByThing retrieves the subset of channels owned by the specified
	// user and have specified thing connected or not connected to them.
	RetrieveByThing(ctx context.Context, owner, thing string, offset, limit uint64, connected bool) (ChannelsPage, error)

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

	// Connect adds things to the channel's list of connected things.
	Connect(ctx context.Context, owner string, chIDs, thIDs []string) error

	// Disconnect removes thing from the channel's list of connected
	// things.
	Disconnect(ctx context.Context, owner, chanID, thingID string) error

	// HasThing determines whether the thing with the provided access key, is
	// "connected" to the specified channel. If that's the case, it returns
	// thing's ID.
	HasThing(ctx context.Context, chanID, key string) (string, error)

	// HasThingByID determines whether the thing with the provided ID, is
	// "connected" to the specified channel. If that's the case, then
	// returned error will be nil.
	HasThingByID(ctx context.Context, chanID, thingID string) 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 Metadata

type Metadata map[string]interface{}

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

type Page

type Page struct {
	PageMetadata
	Things []Thing
}

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

type PageMetadata

type PageMetadata struct {
	Total  uint64
	Offset uint64
	Limit  uint64
	Name   string
}

PageMetadata contains page metadata that helps navigation.

type Service

type Service interface {
	// CreateThings adds a list of 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, offset, limit uint64, name string, metadata Metadata) (Page, 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, channel string, offset, limit uint64, connected bool) (Page, error)

	// RemoveThing removes the thing identified with the provided ID, that
	// belongs to the user identified by the provided key.
	RemoveThing(ctx context.Context, token, id string) error

	// CreateChannels adds a list of 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, offset, limit uint64, name string, m Metadata) (ChannelsPage, error)

	// ListChannelsByThing retrieves data about subset of channels that have
	// specified thing connected or not connected to them and belong to the user identified by
	// the provided key.
	ListChannelsByThing(ctx context.Context, token, thing string, offset, limit uint64, connected bool) (ChannelsPage, error)

	// RemoveChannel removes the thing identified by the provided ID, that
	// belongs to the user identified by the provided key.
	RemoveChannel(ctx context.Context, token, id string) error

	// Connect adds things to the channel's list of connected things.
	Connect(ctx context.Context, token string, chIDs, thIDs []string) error

	// Disconnect removes thing from the channel's list of connected
	// things.
	Disconnect(ctx context.Context, token, chanID, thingID string) error

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

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

	// Identify returns thing ID for given thing key.
	Identify(ctx context.Context, key string) (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 New

func New(auth mainflux.AuthNServiceClient, things ThingRepository, channels ChannelRepository, ccache ChannelCache, tcache ThingCache, up mainflux.UUIDProvider) Service

New instantiates the things service implementation.

type Thing

type Thing struct {
	ID       string
	Owner    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, owner, id string) (Thing, error)

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

	// RetrieveAll retrieves the subset of things owned by the specified user.
	RetrieveAll(ctx context.Context, owner string, offset, limit uint64, name string, m Metadata) (Page, error)

	// RetrieveByChannel retrieves the subset of things owned by the specified
	// user and connected or not connected to specified channel.
	RetrieveByChannel(ctx context.Context, owner, channel string, offset, limit uint64, connected bool) (Page, error)

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

ThingRepository specifies a thing persistence API.