manager

README

Mainflux manager

Mainflux manager provides an HTTP API for managing platform resources: users, devices, applications and channels. Through this API clients are able to do the following actions:

• register new accounts and obtain access tokens
• provision new clients (i.e. devices & applications)
• create new channels
• "connect" clients into the channels

For 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
MANAGER_DB_CLUSTER	comma-separated Cassandra contact points	127.0.0.1
MANAGER_DB_KEYSPACE	name of the Cassandra keyspace	manager
MANAGER_SECRET	string used for signing tokens	manager

Deployment

Before proceeding to deployment, make sure to check out the Apache Cassandra 3.0.x documentation. Developers are advised to get acquainted with basic architectural concepts, data modeling techniques and deployment strategies.

Prior to deploying the service, make sure to set up the database and create the keyspace that will be used by the service.

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:
  manager:
    image: mainflux/manager:[version]
    container_name: [instance name]
    ports:
      - [host machine port]:8180
    environment:
      MANAGER_DB_CLUSTER: [comma-separated Cassandra endpoints]
      MANAGER_DB_KEYSPACE: [name of Cassandra keyspace]
      MANAGER_SECRET: [string used for signing tokens]

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/cmd/manager

# compile the app; make sure to set the proper GOOS value
CGO_ENABLED=0 GOOS=[platform identifier] go build -ldflags "-s" -a -installsuffix cgo -o app

# set the environment variables and run the service
MANAGER_DB_CLUSTER=[comma-separated Cassandra endpoints] MANAGER_DB_KEYSPACE=[name of Cassandra keyspace] MANAGER_SECRET=[string used for signing tokens] app

Usage

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

Documentation

Overview

Package manager contains the domain concept definitions needed to support Mainflux manager service functionality.

Index

• Variables
• type Channel
• type ChannelRepository
• type Client
  • func (c *Client) Validate() error
• type ClientRepository
• type Hasher
• type IdentityProvider
• type Service
  • func NewService(users UserRepository, clients ClientRepository, channels ChannelRepository, ...) Service
• type User
  • func (u *User) Validate() error
• type UserRepository

Variables

var (
	// ErrConflict indicates usage of the existing email during account
	// registration.
	ErrConflict error = errors.New("email already taken")

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

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

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

Types

type Channel

type Channel struct {
	Owner     string   `json:"-"`
	ID        string   `json:"id"`
	Name      string   `json:"name,omitempty"`
	Connected []string `json:"connected"`
}

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

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

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

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

	// All retrieves the channels owned by the specified user.
	All(string) []Channel

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

	// HasClient determines whether the client with the provided identifier, is
	// "connected" to the specified channel.
	HasClient(string, string) bool
}

ChannelRepository specifies a channel persistence API.

type Client

type Client struct {
	Owner string            `json:"-"`
	ID    string            `json:"id"`
	Type  string            `json:"type"`
	Name  string            `json:"name,omitempty"`
	Key   string            `json:"key"`
	Meta  map[string]string `json:"meta,omitempty"`
}

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

func (*Client) Validate

func (c *Client) Validate() error

Validate returns an error if client representation is invalid.

type ClientRepository

type ClientRepository interface {
	// Id generates new resource identifier.
	Id() string

	// Save persists the client. Successful operation is indicated by non-nil
	// error response.
	Save(Client) error

	// Update performs an update to the existing client. A non-nil error is
	// returned to indicate operation failure.
	Update(Client) error

	// One retrieves the client having the provided identifier, that is owned
	// by the specified user.
	One(string, string) (Client, error)

	// All retrieves the clients owned by the specified user.
	All(string) []Client

	// Remove removes the client having the provided identifier, that is owned
	// by the specified user.
	Remove(string, string) error
}

ClientRepository specifies a client persistence API.

type Hasher

type Hasher interface {
	// Hash generates the hashed string from plain-text.
	Hash(string) (string, error)

	// Compare compares plain-text version to the hashed one. An error should
	// indicate failed comparison.
	Compare(string, string) error
}

Hasher specifies an API for generating hashes of an arbitrary textual content.

type IdentityProvider

type IdentityProvider interface {
	// TemporaryKey generates the temporary access token.
	TemporaryKey(string) (string, error)

	// PermanentKey generates the non-expiring access token.
	PermanentKey(string) (string, error)

	// Identity extracts the entity identifier given its secret key.
	Identity(string) (string, error)
}

IdentityProvider specifies an API for identity management via security tokens.

type Service

type Service interface {
	// Register creates new user account. In case of the failed registration, a
	// non-nil error value is returned.
	Register(User) error

	// Login authenticates the user given its credentials. Successful
	// authentication generates new access token. Failed invocations are
	// identified by the non-nil error values in the response.
	Login(User) (string, error)

	// Identity retrieves Client ID for a given client token
	Identity(string) (string, error)

	// AddClient adds new client to the user identified by the provided key.
	AddClient(string, Client) (string, error)

	// UpdateClient updates the client identified by the provided ID, that
	// belongs to the user identified by the provided key.
	UpdateClient(string, Client) error

	// ViewClient retrieves data about the client identified with the provided
	// ID, that belongs to the user identified by the provided key.
	ViewClient(string, string) (Client, error)

	// ListClients retrieves data about all clients that belongs to the user
	// identified by the provided key.
	ListClients(string) ([]Client, error)

	// RemoveClient removes the client identified with the provided ID, that
	// belongs to the user identified by the provided key.
	RemoveClient(string, string) error

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

	// UpdateChannel updates the channel identified by the provided ID, that
	// belongs to the user identified by the provided key.
	UpdateChannel(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(string, string) (Channel, error)

	// ListChannels retrieves data about all clients that belongs to the user
	// identified by the provided key.
	ListChannels(string) ([]Channel, error)

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

	// CanAccess determines whether or not the channel can be accessed with the
	// provided key.
	CanAccess(string, string) bool
}

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(users UserRepository, clients ClientRepository, channels ChannelRepository,
	hasher Hasher, idp IdentityProvider) Service

NewService instantiates the domain service implementation.

type User

type User struct {
	Email    string
	Password string
}

User represents a Mainflux user account. Each user is identified given its email and password.

func (*User) Validate

func (u *User) Validate() error

Validate returns an error if user representation is invalid.

type UserRepository

type UserRepository interface {
	// Save persists the user account. A non-nil error is returned to indicate
	// operation failure.
	Save(User) error

	// One retrieves user by its unique identifier (i.e. email).
	One(string) (User, error)
}

UserRepository specifies an account persistence API.