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 that should be used	0
MF_THINGS_ES_URL	Event store URL	localhost:6379
MF_THINGS_ES_PASS	Event store password
MF_THINGS_ES_DB	Event store instance that should be used	0
MF_THINGS_HTTP_PORT	Things service HTTP port	8180
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	8181
MF_THINGS_SERVER_KEY	Path to server key in pem format	8181
MF_USERS_URL	Users service URL	localhost:8181
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_THINGS_USERS_TIMEOUT	Users gRPC request timeout in seconds	1

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 that should be used]
      MF_THINGS_HTTP_PORT: [Service HTTP port]
      MF_THINGS_AUTH_HTTP_PORT: [Service auth HTTP port]
      MF_THINGS_AUTH_GRPC_PORT: [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_USERS_URL: [Users service URL]
      MF_THINGS_SECRET: [String used for signing tokens]
      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_THINGS_USERS_TIMEOUT: [Users 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
go get github.com/mainflux/mainflux

cd $GOPATH/src/github.com/mainflux/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 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 that should be used] MF_THINGS_HTTP_PORT=[Service HTTP port] MF_THINGS_AUTH_HTTP_PORT=[Service auth HTTP port] MF_THINGS_AUTH_GRPC_PORT=[Service auth gRPC port] MF_USERS_URL=[Users service URL] 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_THINGS_USERS_TIMEOUT=[Users 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 IdentityProvider
• type PageMetadata
• type Service
  • func New(users mainflux.UsersServiceClient, things ThingRepository, ...) Service
• type Thing
• type ThingCache
• type ThingRepository
• type ThingsPage

Variables

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

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

	// 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")
)

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 the channel. Successful operation is indicated by unique
	// identifier accompanied by nil error response. A non-nil error is
	// returned to indicate operation failure.
	Save(context.Context, Channel) (string, error)

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

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

	// RetrieveAll retrieves the subset of channels owned by the specified user.
	RetrieveAll(context.Context, string, uint64, uint64, string) (ChannelsPage, error)

	// RetrieveByThing retrieves the subset of channels owned by the specified
	// user and have specified thing connected to them.
	RetrieveByThing(context.Context, string, string, uint64, uint64) (ChannelsPage, error)

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

	// Connect adds thing to the channel's list of connected things.
	Connect(context.Context, string, string, string) error

	// Disconnect removes thing from the channel's list of connected
	// things.
	Disconnect(context.Context, string, string, 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(context.Context, string, 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(context.Context, string, 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 IdentityProvider

type IdentityProvider interface {
	// ID generates the unique identifier.
	ID() (string, error)
}

IdentityProvider specifies an API for generating unique identifiers.

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 {
	// AddThing adds new thing to the user identified by the provided key.
	AddThing(context.Context, string, Thing) (Thing, error)

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

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

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

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

	// ListThingsByChannel retrieves data about subset of things that are
	// connected to specified channel and belong to the user identified by
	// the provided key.
	ListThingsByChannel(context.Context, string, string, uint64, uint64) (ThingsPage, error)

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

	// CreateChannel adds new channel to the user identified by the provided key.
	CreateChannel(context.Context, string, Channel) (Channel, error)

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

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

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

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

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

	// Connect adds thing to the channel's list of connected things.
	Connect(context.Context, string, string, string) error

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

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

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

	// Identify returns thing ID for given thing key.
	Identify(context.Context, 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(users mainflux.UsersServiceClient, things ThingRepository, channels ChannelRepository, ccache ChannelCache, tcache ThingCache, idp IdentityProvider) Service

New instantiates the things service implementation.

type Thing

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

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 the thing. Successful operation is indicated by non-nil
	// error response.
	Save(context.Context, Thing) (string, error)

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

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

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

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

	// RetrieveAll retrieves the subset of things owned by the specified user.
	RetrieveAll(context.Context, string, uint64, uint64, string) (ThingsPage, error)

	// RetrieveByChannel retrieves the subset of things owned by the specified
	// user and connected to specified channel.
	RetrieveByChannel(context.Context, string, string, uint64, uint64) (ThingsPage, error)

	// Remove removes the thing having the provided identifier, that is owned
	// by the specified user.
	Remove(context.Context, string, string) 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.