README
¶
service 
The robµlab service library is a convenience wrapper for easy microservice creation.
How to add to your project?
Run this in your project
$ burrow get github.com/embeddedenterprises/service
and use the library in your sourcecode like this.
package main
import (
"os"
"github.com/EmbeddedEnterprises/service"
"github.com/jcelliott/turnpike"
"github.com/op/go-logging"
)
func main() {
srv := service.New(service.Config{
Name: "example",
Serialization: turnpike.MSGPACK,
Version: "0.1.0",
Description: "Simple example microservice from the documentation.",
URL: "ws://localhost:8000/ws",
})
srv.Connect()
// register and subscribe here
srv.Run()
os.Exit(service.ExitSuccess)
}
How to view logging output
The robµlab service library uses the system logging daemon to store log files. You can use the following command under systemd machines to view a robµlab service's log messages:
$ journalctl --user -e -f -t com.robulab.<name>
Running the example
First you have to start a crossbar broker in the background.
$ docker run -p 127.0.0.1:8080:8080 --name crossbar --rm crossbario/crossbar:latest
The you can run the example service like this:
$ burrow run --example simple -- -b ws://localhost:8080/ws
You can view the logging output of the example by issuing
$ journalctl --user -e -f -t com.robulab.example.simple
Documentation
¶
Index ¶
Constants ¶
const ( // ExitSuccess indicates that the service terminated without an error. ExitSuccess int = iota // ExitArgument indicates that the service terminated early as an argument was missing or malformed. ExitArgument // ExitService indicates that the service implementation ran into an unhandled error and could not be recovered. ExitService // ExitConnect indicates that the service failed to connect to the broker. ExitConnect // ExitRegistration indicates that the service failed to register or subscribe for a given topic or method. ExitRegistration )
const EnvBrokerURL string = "SERVICE_BROKER_URL"
EnvBrokerURL defines the environment variable name for the broker url definition.
const EnvLogFormat string = "SERVICE_LOGFORMAT"
EnvLogFormat defines the environment variable name for the logging format string definition.
const EnvPassword string = "SERVICE_PASSWORD"
EnvPassword defines the environment variable name for the password the service is using to authenticate on the broker.
const EnvUsername string = "SERVICE_USERNAME"
EnvUsername defines the environment variable name for the username the service is using to authenticate on the broker.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Name string
Version string
Description string
Serialization turnpike.Serialization
URL string
Realm string
User string
Password string
}
Config holds the default configuration that is applied to a `Service` instance when the configuration is not overridden by a cli argument or an environment variable. The cli argument always has priority!
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is the holder of an inner error and a translated `ErrorKind`. Instances may be created with `NewError` or `NewErrorFrom`.
func NewErrorFrom ¶
NewErrorFrom translates an inner to a given error kind and holds the inner error.
type ErrorKind ¶
type ErrorKind int
ErrorKind describes the type of an error that occurred during the execution of the microservice. It can be used as a basic set of errors that are used by implementors of this service library.
const ( // ErrorBadArgument indicates that a given argument does not meet its requirements. ErrorBadArgument ErrorKind = iota // ErrorNotAvailable indicates that a requested resource is not available. ErrorNotAvailable // ErrorNotEnoughData indicates that the provided data is not enough. ErrorNotEnoughData // ErrorUnexpectedData indicates that the provided data is in an unexpected format. ErrorUnexpectedData // ErrorTooMuchData indicates that the provided data is too much. ErrorTooMuchData // ErrorOutOfRange indicates that a given index is out of range. ErrorOutOfRange // ErrorTimedOut indicates that a request has timed out. ErrorTimedOut // ErrorPermissionDenied indicates that the access to a resource was denied. ErrorPermissionDenied // ErrorNotFound indicates that a given resource could not be found. ErrorNotFound // ErrorUnreachableLineReached indicates that this code should not be reached as it is not implemented. ErrorUnreachableLineReached // ErrorThisWorksOnMyMachine indicates that this code needs complicated state to work. Contact your // system administrator for details. ErrorThisWorksOnMyMachine // ErrorItsNotABugItsAFeature indicates that the current behavior is intended. If you did not expect this to // happen, contact your system administrator. ErrorItsNotABugItsAFeature // ErrorAKittenDies indicates that something was nil... ErrorAKittenDies )
type EventSubscription ¶ added in v0.9.0
type EventSubscription struct {
Handler turnpike.EventHandler
Options map[string]interface{}
}
EventSubscription holds a tuple of a `turnpike.EventHandler` and an options map that can be used in the `SubscribeAll` function to subcribe to multiple topics at once.
type HandlerRegistration ¶ added in v0.8.0
type HandlerRegistration struct {
Handler turnpike.MethodHandler
Options map[string]interface{}
}
HandlerRegistration holds a tuple of a `turnpike.MethodHandler` and an options map that can be used in the `RegisterAll` function to register multiple method handlers at once.
type RegistrationError ¶ added in v0.8.0
RegistrationError describes an error that occurred during the registration of a remote procedure call. The struct holds the inner error and the procedure name that failed to register.
type Service ¶
type Service struct {
Logger *logging.Logger
Client *turnpike.Client
// contains filtered or unexported fields
}
Service is a struct that holds all state that is needed to run the service. An instance of this struct is the main object that is used to communicate with the broker backend. Use the `New` function to create a service instance. The instance will give you access to the `Logger` and `Client` object.
func New ¶
New creates a new service instance from the provided default configuration. The configuration can be overridden with command line arguments or environment variables. The main function of your microservice will most likely look like this:
func main() {
srv := service.New(service.Config{
Name: "example",
Serialization: turnpike.MSGPACK,
Version: "0.1.0",
Description: "Simple example microservice from the documentation.",
URL: "ws://localhost:8000/ws",
})
srv.Connect()
// register and subscribe here
srv.Run()
os.Exit(service.ExitSuccess)
}
You can look in the `examples` of the source repository for a more detailed example.
This function can exit the program early when ¶
1. A version print was requested by the command line interface.
2. An error occurred while parsing the command line arguments.
3. An internal error occurrs that cannot be recovered.
func (*Service) Connect ¶
func (srv *Service) Connect()
Connect establishes a connection with the broker and must be called before `Run`!
This function may exit the program early when ¶
1. Logger creation failed.
2. The client failed to join the realm.
func (*Service) RegisterAll ¶ added in v0.8.0
func (srv *Service) RegisterAll(procedures map[string]HandlerRegistration) *RegistrationError
RegisterAll can be used to register multiple remote procedure calls at once. You can use it like this:
options := make(map[string]interface{})
procedures := map[string]service.HandlerRegistration{
"example.get_magic": service.HandlerRegistration{handler.GetMagic, options},
"example.do_stuff": service.HandlerRegistration{handler.DoStuff, options},
"example.set_something": service.HandlerRegistration{handler.SetSomething, options},
}
if err := util.App.RegisterAll(procedures); err != nil {
util.Log.Criticalf(
"Failed to register procedure '%s' in broker: %s",
err.ProcedureName,
err,
)
os.Exit(service.EXIT_REGISTRATION)
}
func (*Service) Run ¶
func (srv *Service) Run()
Run starts the microservice. This function blocks until the user interrupts the process with a SIGINT. It can be considered as the main loop of the service. This function may be only called once.
This function can exit the program early when ¶
1. The client failed to leave the realm.
2. The client connection failed to close.
func (*Service) SubscribeAll ¶ added in v0.8.0
func (srv *Service) SubscribeAll(procedures map[string]EventSubscription) *SubscriptionError
SubscribeAll can be used to subscribe to multiple topics at once. You can use it like this:
options := make(map[string]interface{})
procedures := map[string]service.HandlerRegistration{
"example.goo_happened": service.EventSubscriptions{handler.GooHappened, options},
"example.gesus_joined": service.EventSubscriptions{handler.GesusJoined, options},
"example.no_more_mate": service.EventSubscriptions{handler.NoMoreMate, options},
}
if err := util.App.SubscribeAll(procedures); err != nil {
util.Log.Criticalf(
"Failed to subscribe to topic '%s' in broker: %s",
err.Topic,
err,
)
os.Exit(service.EXIT_REGISTRATION)
}
type SubscriptionError ¶ added in v0.9.0
SubscriptionError describes an error that occurred during the subscription on a topic. The struct holds the inner error and the topic name that failed to subscribe.
Source Files
Directories