Messaging configuration for M5

Messaging broker configuration

A messaging broker is a long-running Zero application which hosts a broker to serve messaging clients. It will normally also host the messaging kicker, if one is required. It can optionally host messaging receiver or Connection API client code but this would probably be restricted to development scenarios.

Messaging broker configuration

To start a broker you need zero.messaging.broker and the following config:

/config/messaging/broker/name = "myBroker" # Unique broker name
/config/messaging/broker/port = 9091 # could be SSL or not

Optional configuration for inbound SSL (based on M5 inbound HTTPS config):

/config/messaging/broker/sslconfig = {
   "keyStore" : "config/broker.jks",
   "keyStoreType" : "JKS",
   "keyStorePassword" : "123456"
}

Messaging authentication configuration

Uses User service configuration.

Messaging authorization configuration

proposed

securing a queue

@include "security/messaging_rule.config"{
   "conditions": "(/event/queue == destabcde101) && (/event/method == POST)",
   "users" : ["user1"]
}

securing a topic

@include "security/messaging_rule.config"{
   "conditions": "(/event/topic == topic1) && (/event/method == POST)",
   "users" : ["user1"]
}

Notes:

• method can be POST, GET.
• Not distinguishing between queues or topics. (recent changes do distinguish)
• Need to think about templates, including single rule to cover queue and associated store-and-forward queues. (in latest version but may need to handle more complex scenarios)

Messaging bridge configuration (store-and-forward)

To set up a bridge you need a remote broker connection configuration with additional bridgeCredentials in broker connection definition map:

/config/connection/messaging/broker1 = {
  "hostname" : "localhost",
  "port" : 9091,
  "bridgeCredentials" : {
    "userid" : "userid",
    "password" : "password" # Can be XOR encoded
  }
}

The zero.messaging.broker component will automatically create pipes and flows to remote brokers when a store-and-forward queue is discovered. Store-and-forward queue names begin with storeAndForward: and have one of the following forms:

• storeAndForward: brokerConnectionName /queue/ queueName
• storeAndForward: brokerConnectionName /topic/ topicName

e.g. Creating storeAndForward:broker1/queue/myQueue will cause a flow to be set up to myQueue using the broker1 connection.

Notes:

• Store-and-forward queues are always queues, whether the target is a queue or a topic.
• The Connection API generates the store-and-forward queue name automatically - the destination configuration names the target queue/topic and the name of the broker connection.

Messaging client configuration

A messaging client is a Zero application using the Connection API to POST or GET messages and/or handles message events (i.e. is a messaging receiver) and/or hosts a messaging kicker.

Most messaging clients follow norms for Zero request processing and so need not be long running. However a messaging kicker requires a long-running application and so may often be deployed in the same application as its broker.

Messaging client broker connection configuration

Broker connection configurations are used by messaging connection protocol, the messaging kicker and receiver and by the broker to set up bridges/pipes to remote brokers.

/config/connection/messaging/broker1 = {
  "hostname" : "localhost",
  "port" : 9091
}

Question Why don't we need a trust store password or type for client configuration?

Note Messaging clients and their home brokers must have common understanding of the logical broker names if store-and-forward is to work, but it is not necessary to have globally unique logical broker names.

Messaging client home broker configuration

Home broker client connection configuration required for messaging kicker, receiver and store-and-forward through Connection API.

/config/messaging/homeBroker = "broker1"

Note This nominates a home broker connection definition within /config/connection/messaging

Messaging protocol destination configuration for Connection API

To use the messaging protocol you need zero.messaging.connection and configure the messaging protocol in the for destinations.

/config/connection/destinations += {
 "destination1" : {
   "connection" : {
     "protocol" : "messaging",
     "config" : {
       "connectionConfig" : "broker1",
       "queue" : "queue1"
     }
   }
 }
}

Note that connectionConfig references a broker configuration under /config/messaging/connection. For direct connections (i.e. not store-and-forward), the broker configuration must be defined in the client application. For store-and-foward scenarios, this broker configuration must be defined in the client's home broker.

Messaging kicker configuration

To use the messaging kicker you need zero.messaging.kicker, add a home broker configuration and configure at least one kicker:

/config/timers/queue1Kicker = { "period" : 5 }

/config/handlers += [{
   "events" : "timer",
   "handler" : "zero.messaging.kicker.QueueKicker.class",
   "conditions" : "/event/_taskName =~ queue1Kicker",
   "instanceData": {
         "queueName" : "queue1", 
         "receiverURL" : "http://localhost:8080/messaging/QueueReceiver", # receiver is in the test client app
         "config" : { 
            # Optional outbound HTTP/HTTP protocol config goes here (see CoreDevelopersGuideConnectionProtocolsHTTP)
         }
      }
}]

For secured brokers, a kicker requires a userid and password:

/config/messaging/client/kickerCredentials = {
  "userid" : "userid",
  "password" : "password" # Can be XOR encoded
}

Note A messaging kicker must use the same home broker as the receiver it kicks.

Messaging receiver configuration

To use the messaging kicker you need zero.messaging.receiver. Messaging receiver requires home broker configuration.

For secured brokers, a receiver requires a userid and password:

/config/messaging/client/receiverCredentials = {
  "userid" : "userid",
  "password" : "password" # Can be XOR encoded
}

Also requires one or more handlers for the message event, e.g:

/config/handlers += [{
  "events" : "message",
  "handler" : "messageHandler.groovy",
  "conditions" : "/request/messaging/queue =~ queue1"
}]

Note A messaging receiver must use the same home broker as the messaging kicker that is kicking it.

GlobalContext keys for message event