servers

Documentation

Index

• Constants
• type IMessageServer
• type ProtocolsConfig
  • func NewProtocolsConfig() ProtocolsConfig
• type TransportManager
  • func NewTransportManager(cfg *ProtocolsConfig, serverCert *tls.Certificate, caCert *x509.Certificate, ...) (svc *TransportManager)
  • func (svc *TransportManager) AddTDForms(tdoc *td.TD, includeAffordances bool)
  • func (svc *TransportManager) CloseAll()
  • func (svc *TransportManager) CloseAllClientConnections(clientID string)
  • func (svc *TransportManager) GetConnectURL() (connectURL string)
  • func (svc *TransportManager) GetConnectionByClientID(clientID string) messaging.IConnection
  • func (svc *TransportManager) GetConnectionByConnectionID(clientID, cid string) messaging.IConnection
  • func (svc *TransportManager) GetHiveotEndpoints() map[string]string
  • func (svc *TransportManager) GetProtocolType() string
  • func (svc *TransportManager) GetServer(protocolType string) IMessageServer
  • func (svc *TransportManager) SendNotification(notification *messaging.NotificationMessage)
  • func (svc *TransportManager) Start() (err error)
  • func (svc *TransportManager) StartDiscovery(instanceName string, tdPath string, dirTD string) (err error)
  • func (svc *TransportManager) Stop()

Constants

const (
	DefaultHttpsPort   = 8444
	DefaultMqttTcpPort = 8883
	DefaultMqttWssPort = 8884
)

Types

type IMessageServer

type IMessageServer interface {

	// AddTDForms adds the Forms for using this protocol bindings to the provided TD.
	// This adds the operations for reading/writing properties, events and actions
	// Original forms must be removed first as they are no longer applicable.
	//
	// Use includeAffordances to add forms to every affordance, a massive waste of space.
	AddTDForms(td *td.TD, includeAffordances bool)

	// CloseAllClientConnections close all connections from the given client.
	// Intended to close connections after a logout.
	CloseAllClientConnections(clientID string)

	// GetConnectionByConnectionID returns a client connection on the server
	GetConnectionByConnectionID(clientID, cid string) messaging.IConnection

	// GetConnectionByClientID returns the connection with the given client ID.
	// Intended to find agents to route requests to.
	GetConnectionByClientID(agentID string) messaging.IConnection

	// GetConnectURL returns the full URL to connect to this server .
	GetConnectURL() string

	// GetProtocolType returns the server provided protocol type and scheme, where
	// protocolType is one of the supported protocol identifiers
	GetProtocolType() string

	// SendNotification sends an event or property update notification to connected
	// event subscribers or property observers.
	// The subscription is handled by the underlying transport protocol.
	SendNotification(msg *messaging.NotificationMessage)

	// CloseAll closes all connections but do not stop the server
	CloseAll()

	// Start the server and receive connections abd messages
	Start() error

	// Stop the server after force closing all connections
	Stop()
}

IMessageServer is the interface implemented by all transport protocol bindings

type ProtocolsConfig

type ProtocolsConfig struct {

	// Enable mDNS discovery. Default is true.
	EnableDiscovery bool `yaml:"enableDiscovery,omitempty"`
	// Enable the HiveOT HTTP/Authentication endpoint. Default is true.
	EnableHiveotAuth bool `yaml:"enableHiveotAuth,omitempty"`
	// Enable the HiveOT HTTP/SSE (sse-sc) sub protocol binding. Default is true.
	EnableHiveotSSE bool `yaml:"enableHiveotSSE,omitempty"`
	// EnableHttpBasic. Default is true.
	EnableHttpBasic bool `yaml:"enableHttpBasic,omitempty"`
	// EnableHttpStatic enables a protected static file server, default is false.
	EnableHttpStatic bool `yaml:"enableHttStatic,omitempty"`
	// Enable the HTTP/WSS sub protocol binding. Default is true.
	EnableWSS bool `yaml:"enableWSS,omitempty"`

	// Include forms in each affordance to meet specifications.
	// Note that this is not useful when talking to the Hub as all affordances of
	// all digital twin TD have the same forms with the hub as endpoint.
	// This results in massive duplication of TD content and increases the TD by a lot.
	// Don't use forms unless you really need it.
	IncludeForms bool `yaml:"includeForms,omitempty"`

	// The service discovery instance. The default is the hostname
	DiscoveryInstanceName string `yaml:"instanceName,omitempty"`

	// DirectoryTDPath contains the HTTP path to read the digitwin directory TD
	// Defaults to "/.well-known/wot" as per spec
	// This is published by discovery and served by the http server.
	DirectoryTDPath string `json:"directoryTDPath,omitempty"`

	// Server hostname used in http
	HttpHost string `yaml:"host"`
	// https listening port
	HttpsPort int `yaml:"httpsPort"`

	// Static file server config. Only used when EnableHttpStatic is true
	// HttpStaticBase base path for static file server.
	// Default is /static
	HttpStaticBase string `yaml:"httpStaticBase,omitempty"`
	// HttpStaticDirectory. Storage location of the static file server.
	// Default is {home}/stores/httpstatic
	HttpStaticDirectory string `yaml:"httpStaticDirectory,omitempty"`

	// HiveOT sse subprotocol connection path
	// The full URL is included in discovery record parameters
	// with this URL no forms are needed to connect to the hub
	HiveotSSEPath string `yaml:"hiveotSsePath"`

	// MQTT host interface
	MqttHost string `yaml:"mqttHost"`
	// MQTT tcp port
	MqttTcpPort int `yaml:"mqttTcpPort"`
	// MQTT websocket port
	MqttWssPort int `yaml:"mqttWssPort"`

	// Websocket subprotocol connection path
	// The full URL is included in discovery record parameters
	// with this URL no forms are needed to connect to the hub
	WSSPath string `yaml:"wssPath"`
}

func NewProtocolsConfig

func NewProtocolsConfig() ProtocolsConfig

NewProtocolsConfig creates the default configuration of communication protocols This enables https and mdns

type TransportManager

type TransportManager struct {

	// PreferredProtocolType to publish in discovery
	PreferredProtocolType string
	// contains filtered or unexported fields
}

TransportManager aggregates multiple transport protocol servers and manages the connection and session management.

This implements the ITransportBinding interface like the protocols it manages.

Incoming requests and response are passed to the provided handlers. To send an asynchronous request or a response use the SendRequest/SendResponse methods, or SendNotification to broadcast using the binding's way of handling subscriptions.

func NewTransportManager

func NewTransportManager(cfg *ProtocolsConfig,
	serverCert *tls.Certificate,
	caCert *x509.Certificate,
	authenticator messaging.IAuthenticator,
	notifHandler messaging.NotificationHandler,
	reqHandler messaging.RequestHandler,
	respHandler messaging.ResponseHandler,
) (svc *TransportManager)

NewTransportManager creates a new instance of the transport protocol manager. The transport manager implements the ITransportBinding API.

The authenticator is used to validate connections and set security scheme in AddTDForms.

func (*TransportManager) AddTDForms

func (svc *TransportManager) AddTDForms(tdoc *td.TD, includeAffordances bool)

AddTDForms adds forms to the given TD for all available transports This also adds the security scheme as supported by the authenticator.

func (*TransportManager) CloseAll

func (svc *TransportManager) CloseAll()

CloseAll closes all client connections

func (*TransportManager) CloseAllClientConnections

func (svc *TransportManager) CloseAllClientConnections(clientID string)

CloseAllClientConnections close all connections from the given client. Intended to close connections after a logout.

func (*TransportManager) GetConnectURL

func (svc *TransportManager) GetConnectURL() (connectURL string)

GetConnectURL returns URL of the protocol. If protocolType is empty then the 'preferred' protocol type is used. This returns an empty URL if the protocol is not supported.

func (*TransportManager) GetConnectionByClientID

func (svc *TransportManager) GetConnectionByClientID(clientID string) messaging.IConnection

GetConnectionByClientID returns the first connection belonging to the given clientID. Intended to send requests to an agent which only have a single connection. If a protocol isn't available the default https url is returned

func (*TransportManager) GetConnectionByConnectionID

func (svc *TransportManager) GetConnectionByConnectionID(clientID, cid string) messaging.IConnection

GetConnectionByConnectionID returns the connection of the given ID If a protocol isn't available the default https url is returned

func (*TransportManager) GetHiveotEndpoints

func (svc *TransportManager) GetHiveotEndpoints() map[string]string

GetHiveotEndpoints return available endpoints

func (*TransportManager) GetProtocolType

func (svc *TransportManager) GetProtocolType() string

GetProtocolType returns the preferred protocol

func (*TransportManager) GetServer

func (svc *TransportManager) GetServer(protocolType string) IMessageServer

GetServer returns the server for the given protocol type This returns nil if the protocol is not active.

func (*TransportManager) SendNotification

func (svc *TransportManager) SendNotification(notification *messaging.NotificationMessage)

SendNotification broadcast an event or property change to subscribers clients

func (*TransportManager) Start

func (svc *TransportManager) Start() (err error)

Start starts the transport protocol manager and listens for incoming connections and messages.

This returns an error if any server fails to start.

Discovery has to be started separately with StartDiscovery, if desired, and must be provided with the Directory TD document to serve.

The transport manager implements the ITransportBinding API.

func (*TransportManager) StartDiscovery

func (svc *TransportManager) StartDiscovery(instanceName string, tdPath string, dirTD string) (err error)

StartDiscovery starts the introduction and exploration discovery of the directory TD document.

instanceName alternate service instance, "" is hiveot. Intended for testing.

This serves two discovery mechanisms. 1. The WoT discovery through the directory TD and Thing forms 2. The HiveOT discovery through the use of connection URLs and Request/Response message envelopes without the need for forms.

func (*TransportManager) Stop

func (svc *TransportManager) Stop()

Stop the protocol servers in reverse order