FederationClient

The base constructor function for any postal.federation 'proxy' objects that are used to communicate to remote instances of postal (via whatever transport they use internally). FederationClient provides the majority of the behavior which any derived Client instance can use. postal.xframe uses a library called riveter for the inheritance mechanisms available on the FederationClient constructor. This means the FederationClient constructor can be 'extended' into a 'derived' constructor. Derived types must provide an implementation for send, otherwise an exception will be thrown. In most scenarios, constructor extensions of FederationClient will provide both a send and a shouldProcess implementation.

FederationClient instance members

Member	Description
transportName	placeholder value. It's there primarily as a reminder that you need to provide this instance value in your derived constructors.
target	An object representing the 'remote' target, or its transport-specific proxy - which contains the means to write-to or send a message to the remote. For example, in postal.xframe, target is the contentWindow of an iframe. In postal.socketio, target is the SocketNamespace used to emit events, etc.
options	An object which contains transport-specific options for a derived type. For example, in postal.xframe, options might include the targetUrl which should be passed to the window.postMessage() call, etc. If a federation plugin existed for something like rabbitMQ, options might include exchange and topic information for how to connect to the broker.
pings	An object which is used to track pings to remote instances. When postal.federation's signalReady() method is invoked, it sends federation.ping messages over any available transports. Each ping message has a ticket ID. The ticket ID is added to the pings property as the key, with the value being an object containing the ticket ID and a callback (which is optional) that is invoked when the corresponding remote instance returns a federation.pong message, replying to the ping.
instanceId	A string value representing the remote postal.instanceId() value.
handshakeComplete	A boolean indicating if the remote instance has replied to a federation.ping message with a federation.pong response. Instances where this value is false will not be sent messages until it is true.

FederationClient prototype members

Member	Description
sendPing( [ callback ] )	Sends a federation.ping message to the remote instance, optionally taking a callback argument that gets invoked once the remote instance responds with a federation.pong message.
sendPong( origPackingSlip )	Sends a federation.pong to the remote instance, taking the original packing slip (which came on the ping message) as the origPackingSlip argument. The original packing slip contains the ping ticket ID, which needs to be returned in the federation.pong response message.
sendBundle( slips )	Sends a message which can contain 1-n number of packing slips (the slips argument is an array of packing slips). This is provided to keep cross-transport chattiness to a minimum when executing the ping/pong handshake, though it will be made available for more intelligent throttling in the future.
sendMessage( envelope )	Takes a postal message envelope as the envelope argument, and sends it to the remote instance.
onMessage( packingSlip )	When a message arrives from the remote instance and has been unwrapped from the transport, the packing slip is passed here (as the packingSlip argument). If the instance's shouldProcess() method returns true, then the packing slip is passed up to the postal.fedx.onFederatedMsg() method.
shouldProcess()	The default implementation provided in FederationClient simply returns true. However, it is intended that any transport plugins for postal.federation override this with an implementation that can inspect the state of the instance and determine if the message should be processed. For example, postal.xframe's XFrameClient uses this method to determine if the remote instance represents an origin that is allowed to federate/communicate with this instance.
send( msg )	The default implementation throws an exception, as this method needs to be overridden in every transport plugin. This method should wrap the transport-specific behavior necessary to publish a message to the remote instance. For example, postal.xframe's XFrameClient provides an implementation of send which wraps the call to remoteWindow.postMessage().