Package cool.mqtt.hooks

Interface MQTTCoolHook

All Known Implementing Classes:
SimpleCoolHook
public interface MQTTCoolHook
Interface that defines an MQTT.Cool Hook. By implementing this interface it is possible to create a custom pluggable component for extending the authorization and authentication functionalities of MQTT.Cool.

Hook allows to intercept and authorize the following requests:

  • Session opening.
  • Connection creation.
  • Subscribing/unsubscribing to/from topics.
  • Messages publishing.

In addition, Hook could be notified about the following events:

  • Hook initialization.
  • Session closing.
  • Disconnection.
  • Unsubscription request.
Lastly, Hook can also dynamically extend the set of statically provided MQTT connection settings.

  • Method Summary

    Modifier and Type Method Description
    boolean canConnect​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttConnectOptions connectOptions)
    Checks whether the client is authorized to connect to the MQTT broker hosted at the specified address.
    boolean canOpenSession​(java.lang.String sessionId, java.lang.String user, java.lang.String password, java.util.Map clientContext, java.lang.String clientPrincipal)
    Checks whether the client is authorized to open a new session against MQTT.Cool.
    boolean canPublish​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttMessage message)
    Checks whether the client is authorized to publish the given message to the specified MQTT broker.
    boolean canSubscribe​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttSubscription subscription)
    Checks whether the client is authorized to send the given subscription to the specified MQTT broker.
    void init​(java.io.File configDir)
    Called during the MQTT.Cool initialization process.
    void onDisconnection​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress)
    Called to notify the Hook that a client has been disconnected from the specified MQTT broker.
    void onSessionClose​(java.lang.String sessionId)
    Called to notify the Hook that a session opened against MQTT.Cool has been closed.
    void onUnsubscribe​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, java.lang.String topicFilter)
    Called to notify the Hook that a client, connected to the specified MQTT broker, has been unsubscribed from the given topic filter.
    MqttBrokerConfig resolveAlias​(java.lang.String connectionAlias)
    Gets an MqttBrokerConfig instance corresponding to the connection alias provided by the client while connecting to MQTT.Cool, if no other static entries have been provided in the mqtt_master_connector_conf.xml file for the given alias.

  • Method Details

    • init

      void init​(java.io.File configDir) throws HookException
      Called during the MQTT.Cool initialization process.

      Any setup logic should be implemented here.

      Parameters:
      configDir - the <MQTT.COOL_HOME>/mqtt_connectors directory
      Throws:
      HookException - if the the initialization can't complete successfully; in this case the MQTT.Cool server process will abort

    • resolveAlias

      MqttBrokerConfig resolveAlias​(java.lang.String connectionAlias) throws HookException
      Gets an MqttBrokerConfig instance corresponding to the connection alias provided by the client while connecting to MQTT.Cool, if no other static entries have been provided in the mqtt_master_connector_conf.xml file for the given alias.
      Parameters:
      connectionAlias - the connection alias provided by a client to address a specific MQTT broker
      Returns:
      an MqttBrokerConfig object, or null if this Hook can not supply a valid MQTT broker configuration
      Throws:
      HookException - if this Hook runs against a specific issue while providing an MQTT broker configuration

    • canOpenSession

      boolean canOpenSession​(java.lang.String sessionId, java.lang.String user, java.lang.String password, java.util.Map clientContext, java.lang.String clientPrincipal) throws HookException
      Checks whether the client is authorized to open a new session against MQTT.Cool.

      The requested session is the one carried by the MQTT.Cool connection between the MQTT.Cool JS client and MQTT.Cool, and is not related to the MQTT connection between MQTT.Cool and any MQTT broker. Full client context is passed, together with the client principal, when a client certificate is specified. Note that the Lightstreamer server must be configured appropriately to receive the client principal (see use_client_auth and force_client_auth parameters).

      Parameters:
      sessionId - the unique identifier of client session
      user - the username of the user trying to opening a session; it can be null if no username has been provided
      password - the password of the user trying to opening a session; it can be null if no password has been provided
      clientContext - the key-value map which contains the properties of the client request; available keys are:
      • "REMOTE_IP" - string representation of the remote IP related to the current connection; it may be a proxy address.
      • "REMOTE_PORT" - string representation of the remote port related to the current connection.
      • "USER_AGENT" - the user-agent as declared in the current connection HTTP header.
      • "FORWARDING_INFO" - the comma-separated list of addresses forwarded by intermediaries, obtained from the X-Forwarded-For HTTP header, related to the current connection; intermediate proxies usually set this header to supply connection routing information. Note that if the number of forwards to be considered local to the Server environment has been specified through the skip_local_forwards configuration element, in order to better determine the remote address, then these forwards will not be list.
      • "LOCAL_SERVER" - the name of the specific server socket that handles the current connection, as configured through the http_server or https_server element.
      • "HTTP_HEADERS" - a map object that contains a name-value pair for each header found in the HTTP request that originated the call.
      clientPrincipal - the identification name reported in the client TLS/SSL certificate supplied on the socket connection used to issue the request that originated the call; it can be null if client has not authenticated itself or the authentication has failed
      Returns:
      true if this Hook authorizes the client to open the session
      Throws:
      HookException - if this Hook runs against a specific issue while performing authorization checks (for example, while validating the provided credentials with an external service)

    • onSessionClose

      void onSessionClose​(java.lang.String sessionId)
      Called to notify the Hook that a session opened against MQTT.Cool has been closed.
      Parameters:
      sessionId - the unique identifier of the client session

    • canConnect

      boolean canConnect​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttConnectOptions connectOptions) throws HookException
      Checks whether the client is authorized to connect to the MQTT broker hosted at the specified address.

      For a shared connection, this method is invoked on each connection request made by every joining client, even if a single MQTT connection is actually held to the target MQTT broker.

      Parameters:
      sessionId - the unique identifier of the client session
      clientId - the client identifier as sent by the client, namely:
      • For a dedicated connection, it corresponds to the actual client identifier being used to connect to the target MQTT broker.
      • For a shared connection, it is an empty ("") string, as the actual client identifier is determined through the connection parameters specified in the mqtt_master_connector_conf.xml file, or by the MqttBrokerConfig instance provided by the resolveAlias(String) method.
      brokerAddress - the address of the MQTT broker to connect to
      connectOptions - the set of options being used to connect to the target MQTT broker
      Returns:
      true if this Hook authorizes the client to connect to the target MQTT broker
      Throws:
      HookException - if this Hook runs against a specific issue while performing authorization checks

    • onDisconnection

      void onDisconnection​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress)
      Called to notify the Hook that a client has been disconnected from the specified MQTT broker.

      Note that the method is also invoked in case of session interruption (for example, due to any network issue) while the client is currently connected: if it is the case, both onSessionClose and onDisconnection will be triggered.

      Parameters:
      sessionId - the unique identifier of the client session
      clientId - the client identifier as sent by the client (and detailed in canConnect(java.lang.String, java.lang.String, java.lang.String, cool.mqtt.hooks.MqttConnectOptions))
      brokerAddress - the address of the MQTT broker disconnected from

    • canPublish

      boolean canPublish​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttMessage message) throws HookException
      Checks whether the client is authorized to publish the given message to the specified MQTT broker.
      Parameters:
      sessionId - the unique identifier of the client session
      clientId - the client identifier as sent by the client (and detailed in canConnect(java.lang.String, java.lang.String, java.lang.String, cool.mqtt.hooks.MqttConnectOptions))
      brokerAddress - the address of the MQTT broker connected to
      message - the message being requested to be published to the specified MQTT broker
      Returns:
      true if this Hook authorizes the client to publish the given message
      Throws:
      HookException - if this Hook runs against a specific issue while performing authorization checks

    • canSubscribe

      boolean canSubscribe​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, MqttSubscription subscription) throws HookException
      Checks whether the client is authorized to send the given subscription to the specified MQTT broker.
      Parameters:
      sessionId - the unique identifier of the client session
      clientId - the client identifier as sent by the client (and detailed in canConnect(java.lang.String, java.lang.String, java.lang.String, cool.mqtt.hooks.MqttConnectOptions))
      brokerAddress - the address of the MQTT broker connected to
      subscription - the subscription being requested to be sent to the specified MQTT broker
      Returns:
      true if this Hook authorizes the client to send the given subscription
      Throws:
      HookException - if this Hook runs against a specific issue while performing authorization checks

    • onUnsubscribe

      void onUnsubscribe​(java.lang.String sessionId, java.lang.String clientId, java.lang.String brokerAddress, java.lang.String topicFilter)
      Called to notify the Hook that a client, connected to the specified MQTT broker, has been unsubscribed from the given topic filter.
      Parameters:
      sessionId - the unique identifier of the client session
      clientId - the client identifier as sent by the client (and detailed in canConnect(java.lang.String, java.lang.String, java.lang.String, cool.mqtt.hooks.MqttConnectOptions))
      brokerAddress - the address of the MQTT broker connected to
      topicFilter - the topic filter unsubscribed from