WebSocket Gateway Service¶

Summary¶

Stream real-time information between your Murano Solution and a web application

WebSocket endpoint scripts are developed within your application Endpoints tab.

Each WebSocket connection and messages will trigger the execution of the deployed scripts.
Tips: the websocket upgrade endpoints support the same headers, query & path parameters capability as the Webservice service.

IMPORTANT: A single WebSocket connection has a limitation of 5 incoming messages per second.

Operations

Events

Operations¶

close¶

Description

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

Responses

• Returns nil for Connection closed

• Returns {object} when Fail to close connection. More information available in the operation response.

  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¶

Description

Close all WebSocket connection for this solution

Responses

• Returns number for Number of connections closed

• Returns {object} when Fail to close connection. More information available in the operation response.

  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¶

Description

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

Arguments

Responses

• Returns {object} when Websocket connection information

  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=-]+$	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.

• Returns {object} when Fail to get active connections. More information available in the operation response.

  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¶

Description

Retrieve the list of WebSocket connection IDs for this solution

Responses

• Returns {[ string ]} when A list of websocket connection IDs

  WebSocket information {object}

  Name	Type	Description

• Returns {object} when Fail to get active connections. More information available in the operation response.

  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¶

Description

Send a message to a WebSocket connection by providing the destination socket_id.
The message fields requires to be a string (Mind serializing Lua table with the to_json function).

When reply from a WebSocket event you can directly send messages to the active connection by using websocketInfo.send("message") instead.
In this case, if the given message is a lua table the value is automatically serialized into JSON string.

Arguments

Responses

• Returns nil for Message successfully sent

• Returns {object} when Fail to send message. More information available in the operation response.

  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¶

Description

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

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