WebSocket Gateway Service

WebSocket Gateway of the custom API acception WSS protocol.
WebSocket endpoints can be configured from Murano portal interface under your solution routes or from exosite-cli tools.
Each WebSocket connection and messages will trigger the execution of your Murano script.
Note that WebSocket endpoints must be fixed (e.g., /lightbulb rather than /lightbulb/{id} or /lightbulb?id=<id>). IMPORTANT: A single WebSocket connection have a limitation of 5 incoming messages per seconds.

Operations

Events

Operations


close

Close a WebSocket connection and disconnect the client.
From a WebSocket endpoint script you can directly close the active connection by using websocketInfo.close() instead.
From any other script the service_ip and socket_id parameters are required.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
socket_id ^[a-zA-Z0-9]{24}$ The WebSocket connection ID, provided in the websocket connection data websocketInfo .
Responses
Connection closed - nil

Connection closed

Error response - object
Name Type Description
type string Error type
error string Error message
status integer Response code
Example
-- In a websocket Endpoint script:
websocketInfo.close()
-- In the eventHandler script:
local data = {
  ["socket_id"] = websocketInfo.socket_id
} Websocket.close(data)

closeAll

Close all WebSocket connection for this solution

Responses
Number of connections closed - number

Number of connections closed

Error response - object
Name Type Description
type string Error type
error string Error message
status integer Response code
Example
local socket_ids = Websocket.closeAll();

info

Get a WebSocket connection info. If the connection has been closed, an error is returned.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
socket_id ^[a-zA-Z0-9]{24}$ The WebSocket connection ID, provided in the websocket connection data websocketInfo .
Responses
WebSocket information - object
Name Type Description
uri string(uri) The full URI of WebSocket HTTP upgrade request
type "open", "data", "close" The state of WebSocket connection and type of event being triggered.
From the WebSocket endpoint script, if the state == 'close'
websocketInfo.send(..) and websocketInfo.close(..) functions are not usable.
route string The endpoint path, matching the custom API endpoint configuration
headers object The WebSocket HTTP upgrade request headers
message string The WebSocket message content
socket_id ^[a-zA-Z0-9]{24}$ Unique socket ID representing this websocket connection.
timestamp integer Message reception timestamp
parameters object The WebSocket HTTP upgrade request query parameters as a Map containing both from path and query parameters.
Path parameters are set on the Murano portal routes by using '/myendpoint/{pathParameterName}'. Query parameters are dynamically set from the url parameters following the format '/myendpoint?queryParameterNameOne=hello&queryParameterNameTwo=world'.
message_type "data-text", "data-binary" The WebSocket message type. 'data-binary' being based on a base64 encoding.
Error response - object
Name Type Description
type string Error type
error string Error message
status integer Response code
Example
local data = {
  ["socket_id"] = websocketInfo.socket_id
} local info = Websocket.info(data)

list

Retrieve the list of WebSocket connection IDs for this solution

Responses
WebSocket information - [ string ]
Name Type Description
Error response - object
Name Type Description
type string Error type
error string Error message
status integer Response code
Example
local socket_ids = Websocket.list();

send

Send a message to a WebSocket connection.
From a WebSocket endpoint script you can directly reply to the active connection by using websocketInfo.send("message") instead.
From any other script the _serviceip and _socketid parameters are required.

Arguments
parameters - object - Object containing service call parameters.
Name Type Description
socket_id ^[a-zA-Z0-9]{24}$ The WebSocket connection ID, provided in the websocket connection data websocketInfo.
Automatically set when calling websocketInfo.send("message") from Murano endpoint script.
type "data-text", "data-binary" Data type used to transmit message to websocket client. 'data-binary' being based on a base64 encoding.
Default: "data-text"
message string Content of the message
Responses
Message successfully sent - nil

Message successfully sent

Error response - object
Name Type Description
type string Error type
error string Error message
status integer Response code
Example
-- In a websocket Endpoint script:
websocketInfo.send("hello world")
-- In the eventHandler script:
local data = {
  ["socket_id"] = websocketInfo.socket_id,
  message = "hello world"
} Websocket.send(data)

Events


websocket_info

An WSS request has reached your custom API endpoint and triggers the websocket eventHandler script execution.
All requests trigger the same eventHandler script. However, for your convenience, Murano provides out-of-the-box endpoint routing wrapper triggering endpoint scripts. So when writing an endpoint script, you simply can use the websocketInfo.send("message") or websocketInfo.close() functions.

However, if you want to set you own endpoint routing mechanism you can directly edit your solution webSocket websocket_info eventHandler script.
Important! Any endpoint script modification will reset the default routing mechanism and eventHandler script changes will be lost.

Arguments
websocketInfo - object - WebSocket information
Name Type Description
uri string(uri) The full URI of WebSocket HTTP upgrade request
type "open", "data", "close" The state of WebSocket connection and type of event being triggered.
From the WebSocket endpoint script, if the state == 'close'
websocketInfo.send(..) and websocketInfo.close(..) functions are not usable.
route string The endpoint path, matching the custom API endpoint configuration
headers object The WebSocket HTTP upgrade request headers
message string The WebSocket message content
socket_id ^[a-zA-Z0-9]{24}$ Unique socket ID representing this websocket connection.
timestamp integer Message reception timestamp
parameters object The WebSocket HTTP upgrade request query parameters as a Map containing both from path and query parameters.
Path parameters are set on the Murano portal routes by using '/myendpoint/{pathParameterName}'. Query parameters are dynamically set from the url parameters following the format '/myendpoint?queryParameterNameOne=hello&queryParameterNameTwo=world'.
message_type "data-text", "data-binary" The WebSocket message type. 'data-binary' being based on a base64 encoding.
Example
-- In a WebSocket Endpoint script:
if (websocketInfo.type == "open") then

  -- Reply to the connection

  websocketInfo.send("Welcome")
elseif (websocketInfo.type == "data") then

  -- Print the incoming message and close the connection

  print(websocketInfo.message)
  websocketInfo.close()
end

-- Same behavior in EventHandler script:
function handle_websocket_websocket_info (websocketInfo)

  local responseData = {
    ["socket_id"] = websocketInfo.socket_id
  }
  if (websocketInfo.type == "open") then
    responseData.message = "Welcome"
    Websocket.send(responseData)
  elseif (websocketInfo.type == "data") then
    print(websocketInfo.message)
    Websocket.close(responseData)
  end

end