Contact Free trial Login

WebSockets Connector Reference - Mule 4

Support Version: Select

WebSockets Connector Version 1.0

Anypoint Connector for WebSockets (WebSockets Connector) provides communication through the WebSockets protocol, allowing external systems to open connections to the server (inbound sockets) or to establish connections to external systems (outbound socket). In both cases, full duplex traffic is supported.

Configurations


Default Configuration

Configure the name and connection types for the default configuration.

Parameters

Name Type Description Default Value Required

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

The connection types to provide to this configuration.

x

Name

String

The identifier of this element used to reference it in other components

x

Connection Types

Connection

Configure the server, client, and reconnection parameters for the connection.

Parameters
Name Type Description Default Value Required

Server Settings

Client Settings

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Operations

Anypoint Connector for WebSockets (WebSockets Connector) supports the following operations:

Broadcast

<websocket:broadcast>

Sends the content to all active WebSockets that match the path, socketType, and groups criteria. In the case of the path, the configured base path is not considered, as you can target both inbound and outbound sockets.

The message is sent to all the matching sockets, even though it’s possible that delivery to some of them fail. The operation returns a list of BroadcastFailure that contains details of each failure. If none fail, an empty list is returned.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Content

Binary

The content to send

#[payload]

Path

String

The path of the sockets to match

x

Socket Type

Enumeration, one of:

  • INBOUND

  • OUTBOUND

  • ALL

The type of sockets to match

ALL

Groups

Array of String

Matches sockets that belong to any of these groups

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Target Variable

String

The name of a variable to store the operation’s output

Target Value

String

An expression to evaluate against the operation’s output and store the expression outcome in the target variable

#[payload]

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

Array of Broadcast Failure

For Configurations

Throws

  • WEBSOCKET:CONNECTIVITY

  • WEBSOCKET:RETRY_EXHAUSTED

Bulk Close Sockets

<websocket:bulk-close-sockets>

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Socket Type

Enumeration, one of:

  • INBOUND

  • OUTBOUND

  • ALL

ALL

Groups

Array of String

Close Code

Enumeration, one of:

  • NORMAL_CLOSURE

  • ENDPOINT_GOING_DOWN

  • PROTOCOL_ERROR

  • INVALID_DATA

  • MESSAGE_TOO_LARGE

NORMAL_CLOSURE

Reason

String

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Reconnection Strategy

A retry strategy in case of connectivity errors

For Configurations

Throws

  • WEBSOCKET:CONNECTIVITY

  • WEBSOCKET:RETRY_EXHAUSTED

Close Socket

<websocket:close-socket>

This operation closes the socket.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Socket Id

String

The ID of the socket to close

x

Close Code

Enumeration, one of:

  • NORMAL_CLOSURE

  • ENDPOINT_GOING_DOWN

  • PROTOCOL_ERROR

  • INVALID_DATA

  • MESSAGE_TOO_LARGE

The close code

NORMAL_CLOSURE

Reason

String

The closing reason phrase

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Reconnection Strategy

A retry strategy in case of connectivity errors

For Configurations

Throws

  • WEBSOCKET:CONNECTIVITY

  • WEBSOCKET:NO_SUCH_SOCKET

  • WEBSOCKET:RETRY_EXHAUSTED

Open Outbound Socket

<websocket:open-outbound-socket>

This operation opens a new outbound socket.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Socket Id

String

Default Groups

Array of String

The groups to which the socket should initially subscribe

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Path

String

Path where the request is sent

URL

String

URL where to send the request

Headers

Object

HTTP headers the message should include

URI Parameters

Object

URI parameters to use to create the request

Query Parameters

Object

Query parameters the request should include

Target Variable

String

The name of a variable to store the operation’s output

Target Value

String

An expression to evaluate against the operation’s output and store the expression outcome in the target variable

#[payload]

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

String

Attributes Type

For Configurations

Throws

  • WEBSOCKET:BASIC_AUTHENTICATION

  • WEBSOCKET:CONNECTIVITY

  • WEBSOCKET:FORBIDDEN

  • WEBSOCKET:INTERNAL_SERVER_ERROR

  • WEBSOCKET:INVALID_SOCKET_ID

  • WEBSOCKET:NO_SUCH_SOCKET

  • WEBSOCKET:NON_UNIQUE_SOCKET_ID

  • WEBSOCKET:NOT_FOUND

  • WEBSOCKET:REMOTELY_CLOSED

  • WEBSOCKET:RETRY_EXHAUSTED

  • WEBSOCKET:SERVICE_UNAVAILABLE

  • WEBSOCKET:UNAUTHORIZED

Send

<websocket:send>

Sends the content through a specified socket.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Socket Id

String

The ID of the socket through which to send data

x

Content

Binary

The content to send

#[payload]

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Reconnection Strategy

A retry strategy in case of connectivity errors

For Configurations

Throws

  • WEBSOCKET:CONNECTIVITY

  • WEBSOCKET:NO_SUCH_SOCKET

  • WEBSOCKET:RETRY_EXHAUSTED

Sources

On New Inbound Message

<websocket:inbound-listener>

Exposes an endpoint through which external systems can connect through a WebSocket. This source triggers the owning flow each time one of those WebSockets sends information to this server. Additionally, any websocket:on-inbound-connection component with a matching path triggers when a socket connection is established.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Path

String

Relative path from the path set in the configuration

x

Default Groups

Array of String

The groups to which newly created sockets should initially subscribe

Output Mime Type

String

The MIME type of the payload that this operation outputs

Output Encoding

String

The encoding of the payload that this operation outputs

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Primary Node Only

Boolean

Whether this source should be executed only on the primary node when running in a cluster

Streaming Strategy

Configure to use repeatable streams

Redelivery Policy

Defines a policy for processing the redelivery of the same message

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

Any

Attributes Type

For Configurations

On New Inbound Connection

<websocket:on-inbound-connection>

Triggers when an inbound WebSocket connection is established.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Path

String

Relative path from the path set in the configuration

x

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Primary Node Only

Boolean

Whether this source should be executed only on the primary node when running in a cluster

Redelivery Policy

Defines a policy for processing the redelivery of the same message

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

String

Attributes Type

For Configurations

On Socket Closed

<websocket:on-socket-closed>

Triggers when a WebSocket is closed.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Path

String

Relative path from the path set in the configuration

x

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Primary Node Only

Boolean

Whether this source should be executed only on the primary node when running in a cluster

Redelivery Policy

Defines a policy for processing the redelivery of the same message

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

Closed Connection Event

Attributes Type

For Configurations

On New Outbound Message

<websocket:outbound-listener>

Triggers when an outbound socket receives a message.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use

x

Path

String

Relative path from the path set in the configuration

x

Output Mime Type

String

The MIME type of the payload that this operation outputs

Output Encoding

String

The encoding of the payload that this operation outputs

Config Ref

ConfigurationProvider

The name of the configuration to use to execute this component

x

Primary Node Only

Boolean

Whether this source should be executed only on the primary node when running in a cluster

Streaming Strategy

Configure to use repeatable streams

Redelivery Policy

Defines a policy for processing the redelivery of the same message

Reconnection Strategy

A retry strategy in case of connectivity errors

Output

Type

Any

Attributes Type

For Configurations

Types

WebSocket Server Settings

Field Type Description Default Value Required

Listener Base Path

String

Base path to use for all resources served through this config.

/

Listener Config

String

Reference to the http:listener-config used to expose the inbound endpoint

x

Idle Socket Timeout

Number

Timeout for automatically closing idle WebSockets

15

Idle Socket Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Time unit that qualifies the #idleSocketTimeout

MINUTES

WebSocket Client Settings

Field Type Description Default Value Required

Host

String

Host where the requests is sent

Port

Number

Port where the requests is sent. If the protocol attribute is WS (default), then the default value is 80. If the protocol attribute is WSS, then the default value is 443.

Base Path

String

Base path to use for all outbound sockets that reference this config

/

Protocol

Enumeration, one of:

  • WS

  • WSS

Protocol to use for outbound communication. Valid values are WS and WSS. Default value is WS. When using WSS, the HTTP communication is secured using TLS/SSL. If WSS is configured as the protocol, then the user can customize the TLS/SSL configuration by defining the tls:context parameter. If tls:context is not defined, then the default JVM certificates are used to establish communication.

WS

Tls Context

Tls

Reference to a TLS config element that enables WSS for outbound sockets

Default Headers

Array of Header

Default HTTP headers the message should include

Default Query Params

Array of Query Param

Default query parameters the request should include

Connection Idle Timeout

Number

A timeout for idle connections to be closed. If not specified, there is no timeout.

Connection Idle Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Timeout unit that qualifies the #connectionIdleTimeout

MINUTES

Follow Redirects

Boolean

Specifies whether or not to follow redirects.

true

Preserve Headers Case

Boolean

By default, header keys are stored internally in lower-case. This is to improve performance of headers handling and is functionally correct as specified in the RFC.

If a server expects headers in a specific case, set this flag to `true` to preserve the case of the header keys.

false

Max Connections

Number

The maximum number of outbound connections that will be kept open at the same time. By default the number of connections is unlimited.

-1

Proxy Config

One of:

Reusable configuration element for outbound connections through a proxy. A proxy element must define host name and port attributes, and, optionally, can define a username and a password.

Authentication

HttpRequestAuthentication

Authentication method to use for the HTTP request

Tls

Field Type Description Default Value Required

Enabled Protocols

String

A comma-separated list of protocols enabled for this context

Enabled Cipher Suites

String

A comma-separated list of cipher suites enabled for this context

Trust Store

Key Store

Revocation Check

Trust Store

Field Type Description Default Value Required

Path

String

The location (which will be resolved relative to the current classpath and file system, if possible) of the trust store

Password

String

The password used to protect the trust store

Type

String

The type of store used

Algorithm

String

The algorithm used by the trust store

Insecure

Boolean

If set to true, no certificate validations are performed, which renders connections vulnerable to attacks. Use at your own risk.

Key Store

Field Type Description Default Value Required

Path

String

The location (which will be resolved relative to the current classpath and file system, if possible) of the key store

Type

String

The type of store used

Alias

String

When the key store contains many private keys, this attribute indicates the alias of the key to use. If not defined, the first key in the file is used by default.

Key Password

String

The password used to protect the private key

Password

String

The password used to protect the key store

Algorithm

String

The algorithm used by the key store

Standard Revocation Check

Field Type Description Default Value Required

Only End Entities

Boolean

Verify only the last element of the certificate chain

Prefer Crls

Boolean

Try CRL (instead of OCSP) first

No Fallback

Boolean

Do not use the secondary checking method (the one not selected before)

Soft Fail

Boolean

Avoid verification failure when the revocation server can not be reached or is busy

Custom Ocsp Responder

Field Type Description Default Value Required

Url

String

The URL of the OCSP responder

Cert Alias

String

Alias of the signing certificate for the OCSP response (must be in the trust store), if present

CRL File

Field Type Description Default Value Required

Path

String

The path to the CRL file.

Field Type Description Default Value Required

Key

String

x

Value

String

x

Query Param

Field Type Description Default Value Required

Key

String

x

Value

String

x

Reconnection

Field Type Description Default Value Required

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

The reconnection strategy to use.

Reconnect

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect

Blocking

Boolean

If false, the reconnection strategy will run in a separate, non-blocking thread

Count

Number

How many reconnection attempts to make.

Reconnect Forever

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect

Blocking

Boolean

If false, the reconnection strategy will run in a separate, non-blocking thread

Inbound WebSocket Attributes

Field Type Description Default Value Required

Version

String

HTTP version of the request

x

Local Address

String

Local host address from the server

x

Remote Address

String

Remote host address from the sender

x

Client Certificate

Any

Client certificate (if two-way TLS is enabled)

Socket Id

String

The socket ID

x

Socket Type

Enumeration, one of:

  • INBOUND

  • OUTBOUND

The socket type

x

Groups

Array of String

The groups on which this socket is subscribed

x

Path

String

Full path where the request was received

x

Request Uri

String

Full URI of the request

x

Scheme

Enumeration, one of:

  • WS

  • WSS

HTTP scheme of the request.

x

Query Params

Object

Query parameters map built from the parsed string

x

Headers

Object

Headers map built from the parsed string

x

Uri Params

Object

URI parameters extracted from the request path

x

Method

String

HTTP method of the request

x

Query String

String

Query string of the request

x

Repeatable In Memory Stream

Field Type Description Default Value Required

Initial Buffer Size

Number

The amount of memory to allocate to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then the buffer expands according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize.

Buffer Size Increment

Number

This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full.

Max Buffer Size

Number

The maximum amount of memory to use. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower than or equal to zero means no limit.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which all these attributes are expressed

Repeatable File Store Stream

Field Type Description Default Value Required

In Memory Size

Number

Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed then it will start to buffer the content on disk.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which maxInMemorySize is expressed

Redelivery Policy

Field Type Description Default Value Required

Max Redelivery Count

Number

The maximum number of times a message can be redelivered and processed unsuccessfully before triggering a process-failed-message

Message Digest Algorithm

String

The secure hashing algorithm to use.

SHA-256

Message Identifier

Defines which strategy is used to identify the messages

Object Store

ObjectStore

The object store where the redelivery counter for each message is stored

Redelivery Policy Message Identifier

Field Type Description Default Value Required

Use Secure Hash

Boolean

Whether to use a secure hash algorithm to identify a redelivered message

Id Expression

String

Defines one or more expressions to use to determine when a message has been redelivered. This property can be set only if useSecureHash is false.

WebSocket Attributes

Field Type Description Default Value Required

Socket Id

String

The socket ID

x

Socket Type

Enumeration, one of:

  • INBOUND

  • OUTBOUND

The socket type

x

Groups

Array of String

The groups to which this socket is subscribed

x

Path

String

Full path where the request was received

x

Request Uri

String

Full URI of the request

x

Scheme

Enumeration, one of:

  • WS

  • WSS

HTTP scheme of the request.

x

Query Params

Object

Query parameters map built from the parsed string

x

Headers

Object

Headers map built from the parsed string

x

Uri Params

Object

URI parameters extracted from the request path

x

Method

String

HTTP method of the request

x

Query String

String

Query string of the request

x

Closed Connection Event

Field Type Description Default Value Required

Code

Enumeration, one of:

  • NORMAL_CLOSURE

  • ENDPOINT_GOING_DOWN

  • PROTOCOL_ERROR

  • INVALID_DATA

  • MESSAGE_TOO_LARGE

The close code

x

Reason

String

The phrase with the reason the socket was closed

Broadcast Failure

Field Type Description Default Value Required

Error Message

String

Exception

Any

Socket Id

String

Type

Enumeration, one of:

  • INBOUND

  • OUTBOUND

Uri

String

Proxy

Field Type Description Default Value Required

Host

String

Host where the proxy requests is sent

x

Port

Number

Port where the proxy requests is sent

x

Username

String

The username to authenticate against the proxy

Password

String

The password to authenticate against the proxy

Non Proxy Hosts

String

A list of comma-separated hosts against which the proxy should not be used

NTLM Proxy

Field Type Description Default Value Required

Ntlm Domain

String

The domain to authenticate against the proxy

x

Host

String

Host where the proxy requests is sent

x

Port

Number

Port where the proxy requests is sent

x

Username

String

The username to authenticate against the proxy

Password

String

The password to authenticate against the proxy

Non Proxy Hosts

String

A list of comma-separated hosts against which the proxy should not be used