BoxLang 🚀 A New JVM Dynamic Language Learn More...

AdvancedSocket

v2.0.0 Projects

AdvancedSocket

AdvancedSockets aims to help handling connectivity issues from the client side when using ColdFusion's WebSockets.

Below is a simple example of how to implement. The data attributes defined in the body are the default values and do not have to be set but can be overridden. For more information on how and where they are set refer to the Attributes / Properties section.

<body data-auto-connect    = "true"
      data-name            = "ws"
      data-channels        = "channelname"
      data-debug           = "true"
      data-do-message      = "doMessage"
      data-online-timer    = "30"
      data-offline-timer   = "5"
      data-reconnect-timer = ".5"
      data-ping-url        = "/ping/">

   <div id="status-message"></div>

   <cfwebsocket name      = "ws"
                onMessage = "AdvancedSocket.onMessage"
                onOpen    = "AdvancedSocket.onOpen"
                onClose   = "AdvancedSocket.onClose"
                onError   = "AdvancedSocket.onError">
   
   <invalidTag src="dist/advancedsocket.min.js"></script>
   
   <invalidTag>
       function doMessage( obj ){
           console.log( obj );
       }
   </script>
</body>

Properties / Attributes

  • autoConnect
    Controls the auto connect feature of the AdvancedSocket.
    Defaults to true but can be managed by the data-auto-connect attribute in the body tag. It also requires a pingURL to be defined.
  • ipApiLookup
    Controls the ip api lookup feature.
    Defaults to false but can be managed by the data-api-lookup attribute in the body tag.
  • ipApiService
    The ip api service that is used when feature is enabled.
    Defaults to ip-api.com but can be managed by the data-api-service attribute in the body tag. Please note, this only allows for either ip-api.com or ipapi.com. At the current moment ip-api.com does not require a key as HTTPS calls are not enabled. Once we support this feature, then an API Key will be required. ipapi.com does allow for HTTPS requests.

[!IMPORTANT] Please review the sites for these services for more information.

  • ipApiKey
    The api key for the ip api service.
    Can be managed by the data-api-key attribute in the body tag. Currently, this is only required for ipapi.com.
  • name
    The name of your global websocket variable name.
    Defaults to ws but can be managed by the data-name attribute in the body tag.
  • channels
    Comma separated list of channels to subscribe to.
    Managed by the data-channels attribute in the body tag.
  • clientID
    The subscriber ID returned from ColdFusion on a succesful connection. This is used when the autoConnect feature is enabled to make sure that we are still an active subscriber.
  • clientInfo
    This is a key-value object that is passed when creating a connection. By default AdvancedSocket uses a third party request to find out additional geo-based data of the request. This is also used to pass in a username and any additional info you may want to.
  • doMessage
    Defines the global function to run on a succesful message. Defaults to doMessage. If the function is not defined or does not exists a log message will be displayed (if debug is enabled).
    Defaults to doMessage but can be managed by the data-do-message attribute in the body tag.
  • timer
    Used for the check AdvancedSocket.checkConnection setTimeout
  • pingURL
    The URL that will be used to ping if we are still a good connection. Should return a JSON object with a success value of true or false.
    Managed by the data-ping-url attribute in the body tag.
  • onlineTimer
    The timeout value to ping if autoConnect is enabled while we have a good connection.
    Defaults to 30 seconds but can be managed by the data-online-timer attribute in the body tag.
  • offlineTimer
    The timeout value to ping if autoConnect is enabled while we have a bad connection.
    Defaults to 5 seconds but can be managed by the data-offline-timer attribute in the body tag.
  • reconnectTimer
    The timeout value call a reconnect attempt when a FORCE-RECONNECT value is received from the server.
    Defaults to 500ms but can be managed by the data-reconnect-timer attribute in the body tag.
  • timerCount
    The timeout value that is used on reconnect calls. It is automally updated to either the online or offline value based on current state.
  • debug
    Boolean value to display log messages.
    Defaults to false but can be managed by the data-debug attribute in the body tag.
  • statusLabel
    The status document element defined by an id of status-message.
    Defaults to status-message but can be managed by the data-status-label attribute in the body tag.

Functions

  • init
    Initializes the AdvancedSocket with options defined in the body's data attributes.
  • checkConnection
    Sets up timer and request first ping() call if autoConnect is enabled.
  • dispatchEvent
    Creates and dispatches custom events.
  • forceReconnect
    Fired when a FORCE-RECONNECT message is received and executes CFWebSocketWrapper.closeConnection() and CFWebSocketWrapper.openConnection() which execute onOpen() when the socket is open again.
  • getIPInfo
    Calls the IP API Service if enabled and adds the result to the subscribers information on connection under clientInfo.geo.
  • handleConnectionError
    Handles a connection error event.
  • handleGoodConnection
    Handles a good connection event.
  • handleRequireConnection
    Handles a require connection event.
  • handleOffline
    Handles an offline event.
  • handleOnline
    Handles an online event.
  • ping
    Polls request to the server to check if connection is still valid. Expects an application/json response as follows:
{ "success" : true|false }
  • processAuthentication Handles an authentication request and logs error or continues on success.
  • processMessage
    On FORCE-RECONNECT messages fires the forceReconnect() based on the reconnectCount and forwards the message to the Global Function defined in the options.
  • setTimer
    Handles setting the timer that fires off the check connection event using window.setTimeout
  • setupListeners
    Handles setting the listeners for connection events.
  • subscribe
    Loops thru the defined channels and executes the CFWebSocketWrapper.subscribe() function for each.
  • onClose [ executed from CFWebSocketWrapper ]
    Fired on connection close
  • onError [ executed from CFWebSocketWrapper ]
    Fired on connection errors
  • onMessage [ executed from CFWebSocketWrapper ]
    Handles messages received and routes based on reqType. If none match, it routes to processMessage().
    • welcome
      Sets clientID and executes connecting()
    • authenticate
      Executes processAuthentication()
    • subscribe
      Executes connected()
  • onOpen [ executed from CFWebSocketWrapper ]
    Fired onced the connection is open. If authentication is required, it calls the CFWebSocketWrapper.authenticate() function if not passes to the getIPInfo() if feature enabled or subscribe() if not.
  • disconnected :metal: (overwrite to customize)
    Fired when a socket is disconnected. Updates the status label.
  • connecting :metal: (overwrite to customize)
    Fired when the socket is connecting. Updates the status label.
  • connected :metal: (overwrite to customize)
    Fired when the socket is connected. Updates the status label.
  • doLog
    Outputs console logs if debug is set to true. This can be defined with the body data-debug attribute.

Use It

$ box install advancedsocket

How do I do this?

Collaborators 0

No collaborators yet.

Links

     

Stats

  • {{ getFullDate("2019-06-12T14:33:01Z") }}
  • {{ getFullDate("2024-10-05T04:08:32Z") }}
  • 1,970
  • 36
Report Abuse