bus

package
Version: v0.13.0 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2020 License: MIT Imports: 19 Imported by: 3

Documentation

Index

Constants

View Source
const (
	// KeyState is the key of the authetication state in the capability map
	KeyState = "__qi_auth_state"
	// KeyUser is the key for the user name in the capability map
	KeyUser = "auth_user"
	// KeyToken is the key for the user token in the capability map
	KeyToken = "auth_token"
	// KeyNewToken is the key with the new token sent in the capability map
	KeyNewToken = "auth_newToken"

	// StateError indicates an authentication failure.
	StateError uint32 = 1
	// StateContinue indicates a new token generation procedure.
	StateContinue uint32 = 2
	// StateDone indicates an authentication success.
	StateDone uint32 = 3
)

Variables

View Source
var ErrActionNotFound = errors.New("Action not found")

ErrActionNotFound is returned with a message refers to an unknown action.

View Source
var ErrCancelled = errors.New("Cancelled")

ErrCancelled is returned when the call was cancelled.

View Source
var (
	// ErrCapabilityTooLong is returned when a capability map.
	ErrCapabilityTooLong = errors.New("capability map too long")
)
View Source
var ErrNotAuthenticated = errors.New("Not authenticated")

ErrNotAuthenticated is returned with a message tries to contact a service without prior authentication.

View Source
var ErrNotYetImplemented = errors.New("Not supported")

ErrNotYetImplemented is returned when a feature is not yet implemented.

View Source
var ErrObjectNotFound = errors.New("Object not found")

ErrObjectNotFound is returned with a message refers to an unknown object.

View Source
var ErrServiceNotFound = errors.New("Service not found")

ErrServiceNotFound is returned with a message refers to an unknown service.

View Source
var ErrTerminate = errors.New("Object terminated")

ErrTerminate is returned with an object lifetime ends while clients subscribes to its signals.

View Source
var ErrWrongObjectID = errors.New("Wrong object ID")

ErrWrongObjectID is returned when a method argument is given the wrong object ID.

Functions

func Authenticate

func Authenticate(endpoint net.EndPoint) error

Authenticate runs the authentication procedure of a given connection. If the clients fails to authenticate itself, it returns an error. In response the connection shall be closed.

func AuthenticateUser

func AuthenticateUser(endpoint net.EndPoint, user, token string) error

AuthenticateUser trigger an authentication procedure using the user and token. If user or token is empty, it is not included in the request.

func Authentication

func Authentication(endpoint net.EndPoint, prefered CapabilityMap) error

Authentication runs the authentication procedure. The prefered CapabilityMap is updated with the negociated capabilities. If a new token was issued, it is store in the KeyNewToken entry of the prefered capapbility map.

func GetMetaObject

func GetMetaObject(client Client, serviceID uint32, objectID uint32) (m object.MetaObject, err error)

GetMetaObject queries the meta object of the remote object.

func ObjectReference

func ObjectReference(p Proxy) object.ObjectReference

func WriteCapabilityMap

func WriteCapabilityMap(m CapabilityMap, out io.Writer) error

WriteCapabilityMap marshals the capability map.

Types

type Activation

type Activation struct {
	ServiceID uint32
	ObjectID  uint32
	Session   Session
	Terminate func()
	Service   Service
}

Activation is sent during activation: it informs the object of the context in which the object is being used.

type Actor

type Actor interface {
	Receiver
	Activate(activation Activation) error
	OnTerminate()
}

Actor interface used by Server to manipulate services.

func NewClientObject

func NewClientObject(remoteID uint32, from Channel) Actor

NewClientObject returns an Actor which forwards messages to a remote object.

WARNING: Why this can't work correctly: - Pb 1: the client side does not know its public object id. this means for methods like MetaObject(id uint32), it can't correctly compare its object id with the one embedded in the payload. in other words: rewritting the header is not enougth for actions which includes the object id (ex: metaObject, terminate, register event, ...). Work around: do not check object id in such cases. - Pb 2: the client side does not know its public object id. this means it cannot share this id with different services. in other words: each time the object is shared with a service it must register again to this service using the 2^31 tricks.

The obvious solution is to inform the remote object of its true identity. This can be done using a new method LendObjectID() uint32 to the services: those services would dedicate an id on demand and route the traffic at this stage. The process would go like: 1. client side request the service to lend her an object id. 2. service allocate an id for the client and setup a route. 3. client side can share its "official" reference to anyone.

func ObjectObject

func ObjectObject(impl ObjectImplementor) Actor

ObjectObject returns an object using ObjectImplementor

func ServiceAuthenticate

func ServiceAuthenticate(auth Authenticator) Actor

ServiceAuthenticate represents the servie server (serivce zero) used to authenticate a new connection.

func ServiceZeroObject

func ServiceZeroObject(impl ServiceZeroImplementor) Actor

ServiceZeroObject returns an object using ServiceZeroImplementor

type Authenticator

type Authenticator interface {
	Authenticate(user, token string) bool
}

Authenticator decides if a user/token tuple is valid. It is used to construct the service server (i.e. service zero).

func Dictionary

func Dictionary(passwords map[string]string) Authenticator

Dictionary is an Authenticator which reads its permission from a dictionnary.

type BasicObject

type BasicObject interface {
	Actor
	SignalHandler
}

BasicObject implements the common behavior to all objects (including the signal/properties subscriptions) in an abstract way.

func NewBasicObject

func NewBasicObject(obj Actor, meta object.MetaObject,
	onPropertyChange func(string, []byte) error) BasicObject

NewBasicObject returns an BasicObject which implements Actor. It handles all the generic methods and signals common to all objects. onPropertyChange is called each time a property is udpated.

type Cache

type Cache struct {
	Names    map[string]uint32
	Services map[uint32]object.MetaObject
	Endpoint net.EndPoint
}

Cache implements Session interface without connecting to a service directory.

func NewCache

func NewCache(e net.EndPoint) *Cache

NewCache returns a new cache.

func NewCachedSession

func NewCachedSession(addr string) (*Cache, error)

NewCachedSession authenticate to the address and returns a Cache object which can act as a Session.

func (*Cache) AddService

func (s *Cache) AddService(name string, serviceID uint32,
	meta object.MetaObject)

AddService manually associates the service name with a service id and a meta objects.

func (*Cache) Lookup

func (s *Cache) Lookup(name string, serviceID uint32) error

Lookup query the given service id for its meta object and add it to the cache.

func (*Cache) Object

func (s *Cache) Object(ref object.ObjectReference) (o Proxy, err error)

Object creates an object from a reference.

func (*Cache) Proxy

func (s *Cache) Proxy(name string, objectID uint32) (Proxy, error)

Proxy returns a proxy object to the desired service.

func (*Cache) Terminate

func (s *Cache) Terminate() error

Terminate closes the connection.

type CapabilityMap

type CapabilityMap map[string]value.Value

CapabilityMap is a data structure exchanged between the server and the client during the authentication procedure. It is used as a negociation medium between the client an the server to decides which features are supported and to verify the client credentials.

func ClientCap

func ClientCap(user, token string) CapabilityMap

ClientCap returns a CapabilityMap based on the default settings. FIXME: get ride of the special case

func DefaultCap

func DefaultCap() CapabilityMap

DefaultCap returns a CapabilityMap based on default settings.

func ReadCapabilityMap

func ReadCapabilityMap(in io.Reader) (m CapabilityMap, err error)

ReadCapabilityMap unmarshals the capability map.

func (CapabilityMap) Authenticated

func (c CapabilityMap) Authenticated() bool

Authenticated return true if the authentication procedure has been completed with success.

func (CapabilityMap) MetaObjectCache

func (c CapabilityMap) MetaObjectCache() bool

func (CapabilityMap) ObjectPtrUID

func (c CapabilityMap) ObjectPtrUID() bool

func (CapabilityMap) RemoteCancelableCalls

func (c CapabilityMap) RemoteCancelableCalls() bool

func (CapabilityMap) SetAuthenticated

func (c CapabilityMap) SetAuthenticated()

SetAuthenticated force the done status in the capability map.

type Channel

type Channel interface {
	Cap() CapabilityMap
	EndPoint() net.EndPoint
	Send(msg *net.Message) error
	SendError(msg *net.Message, err error) error
	SendReply(msg *net.Message, response []byte) error
	Authenticate() error
	Authenticated() bool
	SetAuthenticated()
}

func NewChannel

func NewChannel(e net.EndPoint, c CapabilityMap) Channel

NewChannel retuns a channel

func NewContext

func NewContext(e net.EndPoint) Channel

NewContext retuns a non authenticate context.

func SelectEndPoint

func SelectEndPoint(addrs []string, user, token string) (addr string, channel Channel, err error)

SelectEndPoint connect to a remote peer using the list of addresses. It tries local addresses first and refuses to connect invalid IP addresses such as test ranges (198.18.0.x). User and token are user during Authentication. If user and token are empty, the file .qiloop-auth.conf is read.

type Client

type Client interface {

	// Call initiates a remote procedure call. If cancel is
	// closed, the call is cancelled. cancel can be nil.
	// ErrCancelled is returned if the call was cancelled.
	Call(cancel <-chan struct{}, serviceID, objectID, methodID uint32, payload []byte) ([]byte, error)

	// Subscribe registers to a signal or a property. Returns a
	// cancel callback, a channel to receive the payload and an
	// error.
	Subscribe(serviceID, objectID, actionID uint32) (cancel func(), events chan []byte, err error)

	// OnDisconnect registers a callback which is called when the
	// network connection is closed. If the closure of the network
	// connection is initiated by the remote side, a non nil error
	// is passed to the call back. A nil callback returns nil.
	OnDisconnect(cb func(error)) error

	// Signal state machine: count the number of subscription to a
	// given signal in order to mutualize the calls to
	// RegisterEvent and UnregisterEvent.
	State(signal string, increment int) int

	// returns the underlying channel
	Channel() Channel
}

Client represents a client connection to a service.

func DirectClient

func DirectClient(obj Actor) Client

DirectClient creates a pipe and connect obj to a client.

func NewClient

func NewClient(channel Channel) Client

NewClient returns a new client.

type EventTrace

type EventTrace struct {
	Id            uint32
	Kind          int32
	SlotId        uint32
	Arguments     value.Value
	Timestamp     Timeval
	UserUsTime    int64
	SystemUsTime  int64
	CallerContext uint32
	CalleeContext uint32
}

EventTrace is serializable

type Mail

type Mail struct {
	Msg  *net.Message
	From Channel
}

Mail contains a message to which one can respond.

func NewMail

func NewMail(msg *net.Message, from Channel) Mail

NewMail returns a new Mail

type MailBox

type MailBox chan Mail

MailBox is a FIFO for messages

func NewMailBox

func NewMailBox(r Receiver) MailBox

NewMailBox creates a mailbox and a goroutine which uses the Receiver to handle the incomming messages.

type MetaMethod

type MetaMethod struct {
	Uid                 uint32
	ReturnSignature     string
	Name                string
	ParametersSignature string
	Description         string
	Parameters          []MetaMethodParameter
	ReturnDescription   string
}

MetaMethod is serializable

type MetaMethodParameter

type MetaMethodParameter struct {
	Name        string
	Description string
}

MetaMethodParameter is serializable

type MetaObject

type MetaObject struct {
	Methods     map[uint32]MetaMethod
	Signals     map[uint32]MetaSignal
	Properties  map[uint32]MetaProperty
	Description string
}

MetaObject is serializable

type MetaProperty

type MetaProperty struct {
	Uid       uint32
	Name      string
	Signature string
}

MetaProperty is serializable

type MetaSignal

type MetaSignal struct {
	Uid       uint32
	Name      string
	Signature string
}

MetaSignal is serializable

type MethodStatistics

type MethodStatistics struct {
	Count  uint32
	Wall   MinMaxSum
	User   MinMaxSum
	System MinMaxSum
}

MethodStatistics is serializable

type MinMaxSum

type MinMaxSum struct {
	MinValue       float32
	MaxValue       float32
	CumulatedValue float32
}

MinMaxSum is serializable

type Namespace

type Namespace interface {
	Reserve(name string) (uint32, error)
	Remove(serviceID uint32) error
	Enable(serviceID uint32) error
	Resolve(name string) (uint32, error)
	Session(s Server) Session
}

Namespace is used by a server to register new services. It allows custom name resolution. An implementation connects to the servide directory. Custom implementation is possible to allow interroperability with various naming services.

func PrivateNamespace

func PrivateNamespace() Namespace

PrivateNamespace implements Namespace without relying on a service directory. Used for testing purpose.

type No

type No struct{}

No is an Authenticator which refuses anything.

func (No) Authenticate

func (n No) Authenticate(user, token string) bool

Authenticate returns false

type ObjectImplementor

type ObjectImplementor interface {
	// Activate is called before any other method.
	// It shall be used to initialize the interface.
	// activation provides runtime informations.
	// activation.Terminate() unregisters the object.
	// activation.Session can access other services.
	// helper enables signals and properties updates.
	// Properties must be initialized using helper,
	// during the Activate call.
	Activate(activation Activation, helper ObjectSignalHelper) error
	OnTerminate()
	RegisterEvent(msg *net.Message, c Channel) error
	UnregisterEvent(msg *net.Message, c Channel) error
	MetaObject(objectID uint32) (object.MetaObject, error)
	Terminate(objectID uint32) error
	Property(name value.Value) (value.Value, error)
	SetProperty(name value.Value, value value.Value) error
	Properties() ([]string, error)
	RegisterEventWithSignature(objectID uint32, actionID uint32, handler uint64, P3 string) (uint64, error)
	IsStatsEnabled() (bool, error)
	EnableStats(enabled bool) error
	Stats() (map[uint32]MethodStatistics, error)
	ClearStats() error
	IsTraceEnabled() (bool, error)
	EnableTrace(traced bool) error
	Tracer(msg *net.Message, from Channel) Channel
}

ObjectImplementor interface of the service implementation

type ObjectProxy

type ObjectProxy interface {
	IsStatsEnabled() (bool, error)
	EnableStats(enabled bool) error
	Stats() (map[uint32]MethodStatistics, error)
	ClearStats() error
	IsTraceEnabled() (bool, error)
	EnableTrace(traced bool) error
	SubscribeTraceObject() (unsubscribe func(), updates chan EventTrace, err error)
	object.Object
	// Proxy returns a proxy.
	Proxy() Proxy
}

ObjectProxy represents a proxy object to the service

func MakeObject

func MakeObject(proxy Proxy) ObjectProxy

MakeObject converts a Proxy into an ObjectProxy.

func Object

func Object(session Session) (ObjectProxy, error)

Object returns a proxy to a remote service

type ObjectSignalHelper

type ObjectSignalHelper interface {
	SignalTraceObject(event EventTrace) error
}

ObjectSignalHelper provided to Object a companion object

type Params

type Params struct {
	// contains filtered or unexported fields
}

Params represents a tuple of values to be sent

func NewParams

func NewParams(sig string, args ...interface{}) Params

NewParams returns a

func (*Params) Signature

func (p *Params) Signature() string

func (*Params) Write

func (p *Params) Write(e encoding.Encoder) error

type Proxy

type Proxy interface {
	// CallID send a call message.
	// ErrCancelled is returned if the call was cancelled.
	CallID(action uint32, payload []byte) ([]byte, error)

	// Call is the remote procedure call primitive. It searches
	// for a method with a signature compatible with args and fill
	// resp with the response from the call.
	Call2(method string, args Params, resp Response) error

	// SubscribeID returns a channel with the values of a
	// signal. Subscribe calls RegisterEvent and UnregisterEvent on
	// behalf of the user.
	SubscribeID(action uint32) (cancel func(), events chan []byte, err error)

	// MetaObject can be used to introspect the proyx.
	MetaObject() *object.MetaObject

	// ServiceID returns the related service identifier
	ServiceID() uint32
	// ServiceID returns object identifier within the service
	// namespace.
	ObjectID() uint32

	// WithContext returns a Proxy with a lifespan associated with the
	// context. It can be used for deadline and canceallations.
	WithContext(ctx context.Context) Proxy

	// OnDisconnect registers a callback which is called when the
	// network connection is closed. If the closure of the network
	// connection is initiated by the remote side, a non nil error
	// is passed to the call back. A nil callback returns nil.
	OnDisconnect(cb func(error)) error

	// ProxyService returns a reference to a remote service which can be used
	// to create client side objects.
	ProxyService(s Session) Service
}

Proxy represents a reference to a remote service. It allows to call methods and subscribe signals.

func NewProxy

func NewProxy(client Client, meta object.MetaObject, service, object uint32) Proxy

NewProxy construct a Proxy. TODO: return a *proxy instead of a proxy.

type Receiver

type Receiver interface {
	Receive(m *net.Message, from Channel) error
}

Receiver handles incomming messages.

type Response

type Response struct {
	// contains filtered or unexported fields
}

func NewResponse

func NewResponse(signature string, instance interface{}) Response

func (*Response) Read

func (o *Response) Read(d encoding.Decoder) error

func (*Response) Signature

func (o *Response) Signature() string

Signature returns the signature of the value.

type Router

type Router struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Router dispatch the incomming messages. A Router shall be Activated before calling NewService.

func NewRouter

func NewRouter(authenticator Actor, namespace Namespace, session Session) *Router

NewRouter construct a router with the service zero passed.

func (*Router) Add

func (r *Router) Add(serviceID uint32, s ServiceReceiver) error

Add Add a service ot a router. This does not call the Activate() method on the service.

func (*Router) Receive

func (r *Router) Receive(m *net.Message, from Channel) error

Receive process a message. The message will be replied if the router can not found the destination.

func (*Router) Remove

func (r *Router) Remove(serviceID uint32) error

Remove removes a service from a router.

func (*Router) Terminate

func (r *Router) Terminate() error

Terminate terminates all the services.

type Server

type Server interface {
	// NewService register a new service to the service directory.
	NewService(name string, object Actor) (Service, error)
	// Session returns a local session object which can be used to
	// access the server without authentication.
	Session() Session
	// Terminate stops the server.
	Terminate() error
	// Returns a channel to wait for the server terminaison.
	WaitTerminate() chan error

	// Client returns a direct Client.
	Client() Client
}

Server represents a local server. A server can provide with clients already connected.

func NewServer

func NewServer(listener net.Listener, auth Authenticator,
	namespace Namespace, service1 Actor) (Server, error)

NewServer creates a new server which respond to incomming connection requests.

func StandAloneServer

func StandAloneServer(listener net.Listener, auth Authenticator,
	namespace Namespace) (Server, error)

StandAloneServer starts a new server

type Service

type Service interface {
	ServiceID() uint32
	Add(o Actor) (uint32, error)
	Remove(objectID uint32) error
	Terminate() error
}

Service represents a running service.

func NewServiceReference

func NewServiceReference(s Session, e net.EndPoint, serviceID uint32) Service

NewServiceReference returns a remove reference to a service. This service can be used to create client side objects.

type ServiceReceiver

type ServiceReceiver interface {
	Service
	Receiver
}

ServiceReceiver represents the service used by the Server.

func NewService

func NewService(o Actor, activation Activation) (ServiceReceiver, error)

NewService returns a service basedon the given object.

type ServiceZeroImplementor

type ServiceZeroImplementor interface {
	// Activate is called before any other method.
	// It shall be used to initialize the interface.
	// activation provides runtime informations.
	// activation.Terminate() unregisters the object.
	// activation.Session can access other services.
	// helper enables signals and properties updates.
	// Properties must be initialized using helper,
	// during the Activate call.
	Activate(activation Activation, helper ServiceZeroSignalHelper) error
	OnTerminate()
	Authenticate(capability map[string]value.Value) (map[string]value.Value, error)
}

ServiceZeroImplementor interface of the service implementation

type ServiceZeroProxy

type ServiceZeroProxy interface {
	Authenticate(capability map[string]value.Value) (map[string]value.Value, error)
	// Proxy returns a proxy.
	Proxy() Proxy
}

ServiceZeroProxy represents a proxy object to the service

func ServiceServer

func ServiceServer(session Session) (ServiceZeroProxy, error)

ServiceServer retruns a proxy to the authenticating service (ID 0)

func ServiceZero

func ServiceZero(session Session) (ServiceZeroProxy, error)

ServiceZero returns a proxy to a remote service

type ServiceZeroSignalHelper

type ServiceZeroSignalHelper interface{}

ServiceZeroSignalHelper provided to ServiceZero a companion object

type Session

type Session interface {
	Proxy(name string, objectID uint32) (Proxy, error)
	Object(ref object.ObjectReference) (Proxy, error)
	Terminate() error
}

Session represents a connection to a bus: it is used to instanciate proxies to services and create new services.

type SignalHandler

type SignalHandler interface {
	UpdateSignal(signal uint32, data []byte) error
	UpdateProperty(property uint32, signature string, data []byte) error
}

SignalHandler is an helper object for service implementation: it is passed during the activation call to allow a service implementor to manipilate its signals and properties.

type Timeval

type Timeval struct {
	Tv_sec  int64
	Tv_usec int64
}

Timeval is serializable

type Tracer

type Tracer interface {
	Trace(msg *net.Message, id uint32)
}

Tracer records the arrival or departure of the message.

type Yes

type Yes struct{}

Yes is an Authenticator which accepts anything.

func (Yes) Authenticate

func (y Yes) Authenticate(user, token string) bool

Authenticate returns true

Directories

Path Synopsis
net

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL