Skip to content

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

Name Tag Summary
websocket.close() Close a WebSocket connection
websocket.closeAll() Close all WebSocket connection
websocket.info() Get WebSocket
websocket.list() List WebSockets connections
websocket.send() Send a message to a WebSocket connection

Events

Name Summary
websocket_info WebSocket request information

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

Name Type Description
socket_id ^[a-zA-Z0-9=-]+$ The WebSocket connection ID, provided in the websocket connection data websocketInfo .

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

Name Type Description
socket_id ^[a-zA-Z0-9=-]+$ The WebSocket connection ID, provided in the websocket connection data websocketInfo .

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

Name Type Description
socket_id ^[a-zA-Z0-9=-]+$ 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

  • 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

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.

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

Last update: December 7, 2021
Back to top