Documentation
¶
Index ¶
- Constants
- func HandleRequestMessage(ctx ServiceContext, method interface{}, payload []byte) (respData []byte, err error)
- type HubClient
- func (hc *HubClient) ClientID() string
- func (hc *HubClient) ConnectWithPassword(password string) error
- func (hc *HubClient) ConnectWithToken(kp, jwtToken string) error
- func (hc *HubClient) ConnectWithTokenFile(keysDir string) error
- func (hc *HubClient) CreateKeyPair() (string, string)
- func (hc *HubClient) Disconnect()
- func (hc *HubClient) LoadCreateKeyPair(clientID, keysDir string) (serializedKP string, pubKey string, err error)
- func (hc *HubClient) MakeAddress(msgType, agentID, thingID, name string, clientID string) string
- func (hc *HubClient) PubAction(agentID string, thingID string, name string, payload []byte) ([]byte, error)
- func (hc *HubClient) PubConfig(agentID string, thingID string, propName string, payload []byte) ([]byte, error)
- func (hc *HubClient) PubEvent(thingID string, eventName string, payload []byte) error
- func (hc *HubClient) PubRPCRequest(agentID string, capability string, methodName string, req interface{}, ...) error
- func (hc *HubClient) PubTD(td *thing.TD) error
- func (hc *HubClient) SplitAddress(addr string) (msgType, agentID, thingID, name string, senderID string, err error)
- func (hc *HubClient) SubActions(thingID string, handler func(msg *thing.ThingValue) (result []byte, err error)) (transports.ISubscription, error)
- func (hc *HubClient) SubConfig(thingID string, handler func(msg *thing.ThingValue) error) (transports.ISubscription, error)
- func (hc *HubClient) SubEvents(agentID string, thingID string, eventName string, ...) (transports.ISubscription, error)
- func (hc *HubClient) SubRPCCapability(capID string, capMethods map[string]interface{}) (transports.ISubscription, error)
- func (hc *HubClient) SubRPCRequest(capabilityID string, ...) (transports.ISubscription, error)
- type ServiceContext
Constants ¶
const KPFileExt = ".key"
KPFileExt defines the filename extension under which public/private keys are stored in the keys directory.
const PubKeyFileExt = ".pub"
PubKeyFileExt defines the filename extension under which public key is stored in the keys directory.
const TokenFileExt = ".token"
TokenFileExt defines the filename extension under which client tokens are stored in the keys directory.
Variables ¶
This section is empty.
Functions ¶
func HandleRequestMessage ¶
func HandleRequestMessage(ctx ServiceContext, method interface{}, payload []byte) (respData []byte, err error)
HandleRequestMessage unmarshal a request message parameters, passes it to the associated method, and marshals the result. Intended to remove boilerplate from RPC service request handlers.
The first argument is always the clientID of the client invoking the request. The second argument and result can be a struct value or reference.
Supported method types are:
- func(string, type1) (type2,error)
- func(string, type1) (error)
- func(string, type1) ()
- func(string) (type,error)
- func(string) (error)
- func(string) ()
where type1 and type2 can be a struct or native type, or a pointer to a struct or native type.
Types ¶
type HubClient ¶
type HubClient struct {
// contains filtered or unexported fields
}
HubClient wrapper around the underlying message bus transport.
func ConnectToHub ¶
func ConnectToHub(fullURL string, clientID string, certDir string, core string) ( hc *HubClient, err error)
ConnectToHub helper function to connect to the Hub using existing token and key files. This assumes that CA cert, user keys and auth token have already been set up and are available in the certDir. The key-pair file is named {certDir}/{clientID}.key The token file is named {certDir}/{clientID}.token
1. If no fullURL is given then use discovery to determine the URL 2. Determine the core to use 3. Load the CA cert 4. Create a hub client 5. Connect using token and key files
fullURL is the scheme://addr:port/[wspath] the server is listening on clientID to connect as. Also used for the key and token file names certDir is the location of the CA cert and key/token files core optional core selection. Fallback is to auto determine based on URL.
func NewHubClient ¶
NewHubClient returns a new Hub Client instance
The keyPair string is optional. If not provided a new set of keys will be created. Use GetKeyPair to retrieve it for saving to file.
Invoke hubClient.ConnectWithXy() to connect
- url of server to connect to.
- clientID of the client that will be connecting
- keyPair is this client's serialized private/public key pair, or "" to create them.
- caCert of server or nil to not verify server cert
- core server to use, "nats" or "mqtt". Default "" will use nats if url starts with "nats" or mqtt otherwise.
func NewHubClientFromTransport ¶
func NewHubClientFromTransport(transport transports.IHubTransport, clientID string) *HubClient
NewHubClientFromTransport returns a new Hub Client instance for the given transport.
- message bus transport to use, eg NatsTransport or MqttTransport instance
- clientID of the client that will be connecting
func (*HubClient) ConnectWithPassword ¶
ConnectWithPassword connects to the Hub server using a login ID and password.
func (*HubClient) ConnectWithToken ¶
ConnectWithToken connects to the Hub server using a user JWT credentials secret The token clientID must match that of the client
kp is the serialized public/private key-pair of this client jwtToken is the token obtained with login or refresh.
func (*HubClient) ConnectWithTokenFile ¶
ConnectWithTokenFile is a convenience function to read token and key from file and connect to the server.
keysDir is the directory with the {clientID}.key and {clientID}.token files.
func (*HubClient) CreateKeyPair ¶
CreateKeyPair create a new serialized public/private key pair for use by this client
func (*HubClient) Disconnect ¶
func (hc *HubClient) Disconnect()
Disconnect the client from the hub and unsubscribe from all topics
func (*HubClient) LoadCreateKeyPair ¶
func (hc *HubClient) LoadCreateKeyPair(clientID, keysDir string) (serializedKP string, pubKey string, err error)
LoadCreateKeyPair loads or creates a public/private key pair using the clientID as filename.
The key-pair is named {clientID}.key, the public key {clientID}.pub
clientID is the clientID to use, or "" to use the connecting ID
keysDir is the location where the keys are stored.
This returns the serialized private and pub keypair, or an error.
func (*HubClient) MakeAddress ¶
MakeAddress creates a message address optionally with wildcards This uses the hiveot topic format: {msgType}/{deviceID}/{thingID}/{name}[/{clientID}] Where '/' is the address separator for MQTT or '.' for Nats Where "+" is the wildcard for MQTT or "*" for Nats
msgType is the message type: "event", "action", "config" or "rpc". agentID is the device or service being addressed. Use "" for wildcard thingID is the ID of the thing managed by the publisher. Use "" for wildcard name is the event or action name. Use "" for wildcard. clientID is the login ID of the sender. Use "" for subscribe.
func (*HubClient) PubAction ¶
func (hc *HubClient) PubAction( agentID string, thingID string, name string, payload []byte) ([]byte, error)
PubAction publishes a request for action from a Thing.
agentID of the device or service that handles the action. thingID is the destination thingID to whom the action applies. name is the name of the action as described in the Thing's TD payload is the optional payload of the action as described in the Thing's TD
This returns the reply data or an error if an error was returned or no reply was received
func (*HubClient) PubConfig ¶
func (hc *HubClient) PubConfig( agentID string, thingID string, propName string, payload []byte) ([]byte, error)
PubConfig publishes a Thing configuration change request
The client's ID is used as the publisher ID of the action.
agentID of the device that handles the action for the thing or service capability thingID is the destination thingID that handles the action propName is the ID of the property to change as described in the TD properties section payload is the optional payload of the action as described in the Thing's TD
This returns the reply data or an error if an error was returned or no reply was received
func (*HubClient) PubEvent ¶
PubEvent publishes a Thing event. The payload is an event value as per TD document. Intended for devices and services to notify of changes to the Things they are the agent for.
'thingID' is the ID of the 'thing' whose event to publish. This is the ID under which the TD document is published that describes the thing. It can be the ID of the sensor, actuator or service.
This will use the client's ID as the agentID of the event. eventName is the ID of the event described in the TD document 'events' section, or one of the predefined events listed above as EventIDXyz
thingID of the Thing whose event is published eventName is one of the predefined events as described in the Thing TD payload is the serialized event value, or nil if the event has no value
func (*HubClient) PubRPCRequest ¶
func (hc *HubClient) PubRPCRequest( agentID string, capability string, methodName string, req interface{}, resp interface{}) error
PubRPCRequest publishes an RPC request to a service and waits for a response. Intended for users and services to invoke RPC to services.
Authorization to use the service capability can depend on the user's role. Check the service documentation for details. When unauthorized then an error will be returned after a short delay.
The client's ID is used as the senderID of the rpc request.
agentID of the service that handles the request capability is the capability to invoke methodName is the name of the request method to invoke req is the request message that will be marshalled or nil if no arguments are expected resp is the expected response message that is unmarshalled, or nil if no response is expected
func (*HubClient) PubTD ¶
PubTD publishes an event with a Thing TD document. The client's authentication ID will be used as the agentID of the event.
func (*HubClient) SplitAddress ¶
func (hc *HubClient) SplitAddress(addr string) (msgType, agentID, thingID, name string, senderID string, err error)
SplitAddress separates an address into its components
addr is a hiveot address eg: msgType/things/deviceID/thingID/name/clientID
func (*HubClient) SubActions ¶
func (hc *HubClient) SubActions(thingID string, handler func(msg *thing.ThingValue) (result []byte, err error)) (transports.ISubscription, error)
SubActions subscribes to actions requested of this client's Things. Intended for use by devices or services to receive requests for its things.
The handler receives an action request message with request payload and returns an optional reply or an error when the request wasn't accepted.
The supported actions are defined in the TD document of the things this binding has published.
thingID is the device thing or service capability to subscribe to, or "" for wildcard cb is the callback to invoke
The handler receives an action request message with request payload and must return a reply payload, which can be nil, or return an error.
func (*HubClient) SubConfig ¶
func (hc *HubClient) SubConfig(thingID string, handler func(msg *thing.ThingValue) error) ( transports.ISubscription, error)
SubConfig subscribes to configuration change requested of this client's Things. Intended for use by devices to receive configuration requests for its things. The device's agentID is the ID used to authenticate with the server, eg, this clientID.
The handler receives an action request message with request payload and returns an optional reply or an error when the request wasn't accepted.
The supported properties are defined in the TD document of the things this binding has published.
thingID is the device thing or service capability to subscribe to, or "" for wildcard cb is the callback to invoke
The handler receives an action request message with request payload and must reply with msg.Reply or msg.Ack, or return an error
func (*HubClient) SubEvents ¶
func (hc *HubClient) SubEvents(agentID string, thingID string, eventName string, handler func(msg *thing.ThingValue)) (transports.ISubscription, error)
SubEvents subscribes to events from a device or service.
Events are passed to the handler in sequential order after the handler returns. For parallel processing, create a goroutine to handle the event and return immediately.
agentID is the ID of the device or service publishing the event, or "" for any agent. thingID is the ID of the Thing whose events to receive, or "" for any Things. eventName is the name of the event, or "" for any event
The handler receives an event value message with data payload.
func (*HubClient) SubRPCCapability ¶
func (hc *HubClient) SubRPCCapability( capID string, capMethods map[string]interface{}) (transports.ISubscription, error)
SubRPCCapability registers RPC capability and handler methods. This returns a subscription object.
Intended for implementing RPC handlers by services.
The typical RPC handler is a method that takes a context, an optional single argument and returns a result and error status. Supported formats are:
func()(error)
func()(resp interface{}, error)
func(ctx *ServiceContext, args interface{})(resp interface{}, error)
func(ctx *ServiceContext, args interface{}) error
func(ctx *ServiceContext)(resp interface{}, error)
Requests from senders are passed sequentially or concurrently, depending on the underlying implementation.
Where:
ctx is a service context which contains the callerID and other information about the sender, if known. args and resp is defined can be any serializable type. This uses the serializer defined in utils/ser. The default is json.
Arguments:
capID is the capability name (equivalent to thingID) to register. capMethods maps method names to their implementation
func (*HubClient) SubRPCRequest ¶
func (hc *HubClient) SubRPCRequest(capabilityID string, handler func(msg *thing.ThingValue) (reply []byte, err error)) ( transports.ISubscription, error)
SubRPCRequest subscribes a client to receive RPC capability method request. Intended for use by services to receive requests for its capabilities.
The capabilityID identifies the interface that is supported. Each capability represents one or more methods that are identified by the actionName. This is similar to the thingID in events and actions.
The handler must reply with msg.Reply or msg.Ack, or return an error.
type ServiceContext ¶
ServiceContext with context provided to services
Source Files
Directories