bus

package
v0.14.2 Latest Latest
Warning

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

 Go to latest Published: Nov 14, 2023 License: MIT Imports: 19 Imported by: 8

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

Source Files

View all Source files

Directories

Path Synopsis
net
cert
token

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.