Solace PubSub+ Message Broker Interactions

The following sections contain details of how the Solace REST messaging feature interacts with the Solace PubSub+ message broker.

Solace PubSub+ Message Broker Message VPN Selection

Each Message VPN is configured with its own set of TCP ports to support REST clients. Therefore, Message VPNs are selected by connecting to the correct TCP port configured on the message broker.

The table below summarizes how REST clients can select Message VPNs and be authenticated.

Message VPN Selection through REST Protocol

PRTCL

Transport

Auth Scheme

Message VPN

Username

REST

HTTP & HTTPS

Basic

TCP port (either plain-text or SSL port)

HTTP Header: Authorization

None

TCP port (either plain-text or SSL port)

Not provided.

HTTPS

Client Certificate

TCP port (SSL port)

Common Name

Frequency: once, on connect

The Common Name in the Client Certificate Subject field holds the Username.

Client Authentication

The REST protocol supports both basic and SSL authentication for clients.

Basic Client Authentication

For HTTP basic authentication, the HTTP client provides an "Authorization" HTTP header whose value is a “username:password” pair is encoded into a single base64 string, which spans the “:”. If no password is required, then the “username” is encoded into a base64 string without the “:”.

Sequential HTTP POST requests to the message broker using the same persistent HTTP/1.1 connection may each provide their own "Authorization" header. If a subsequent HTTP POST request has no "Authorization" header, or if the "Authorization" header value matches that of the preceding "Authorization" header, then the message broker does not re-authenticate the REST producer client.

If an HTTP POST request has a different "Authorization" header value from the preceding "Authorization" header, then the HTTP connection is re-authenticated according to the new "Authorization" header. This may result in the HTTP connection being attributed to a different message broker client session. (It may be necessary for the message broker to re-authenticate client connections if the HTTP connections are coming through an HTTP proxy or switch that is multiplexing from some number of connections from the actual HTTP client to a smaller number of HTTP connections to the message broker.) Refer to Solace PubSub+ Message Broker Message VPN Selection for further details.

If the first HTTP POST request of a new connection contains no "Authorization" header, then the message broker will authenticate with the client username named default.

A username can contain up to 189 alphanumeric characters (not case-sensitive). The “_” and “-” characters are also permitted, but the ? and * characters are not allowed.  The maximum length for a password is 128 bytes; there are no character restrictions imposed by REST messaging.

SSL – Client Certificate

After an HTTPS connection is established, the Solace Message VPN for the connection is already determined based on the TCP port.

When a Client Certificate authentication scheme with SSL transport is used, the username is taken from the Common Name of the certificate. In this case, an HTTP Authorization Header should not be provided, because only one authentication scheme should be used. If an HTTP Authorization Header is provided, it is ignored.

Solace Client Name

An HTTP client may optionally provide a "Solace-Client-Name" HTTP header specifying the client name in each HTTP POST request. This name uniquely identifies a Solace client session; if the same Solace client name is already in use with an existing Solace client session, then the message broker will log out one of the client sessions contending for the name. On subsequent HTTP POST requests on the same persistent HTTP/1.1 connection, if the HTTP client does not support a "Solace-Client-Name", the message broker treats the client names as being unchanged.

The HTTP client may provide a different "Solace-Client-Name" on subsequent HTTP POST requests. This will change the client name for the message broker's client sessions without re-authenticating the client. However, the proviso that the Solace client name must be unique remains true on client name changes: if an HTTP client changes the "Solace-Client-Name" to a client name already in use, then the message broker will log out one of the client sessions contending for that name.

If an HTTP client does not provide a "Solace-Client-name" HTTP header in the first HTTP POST request on an HTTP connection, the message broker will generate a unique client name for that HTTP connection during authentication.

In all HTTP responses, the message broker will send the "Solace-Client-Name" HTTP header containing the client name associated with the client session.

Solace PubSub+ Message Broker Client Sessions

The message broker considers a sequence of HTTP POST requests received on the same persistent HTTP/1.1 connection, with the same (implicit or explicit) authentication and client name parameters, to belong to the same client session for the purposes of client statistics and event logging.

An HTTP client may provide "Authorization" and "Solace-Client-Name" HTTP headers on any HTTP POST request.

Interactions with Solace Messaging APIs

Solace APIs – Accessing HTTP Content Type and Content Encoding

As explained in Section HTTP Content Entity Headers and Message Payload Types, the HTTP “Content-Type” and “Content-Encoding” headers are preserved in the resulting Solace message. These fields are also accessible by Solace Enterprise APIs. This means uses of the following APIs can set and retrieve these fields from a Solace message.

  • Solace JMS messaging API
  • Solace Java messaging API
  • Solace Java RTO messaging API
  • Solace C messaging API
  • Solace .NET messaging API

The Solace JMS messaging API is a standardized API and therefore has a unique way of accessing these Solace message fields. This is shown in its own section below. The other Solace APIs have a common way of accessing these fields so the Solace Java messaging API is used as an example but this is equally applicable to the other APIs.

HTTP Content Type and Content Encoding Access Using JMS

In the Solace JMS messaging API, the HTTP headers Content Type and Content-Encoding are accessed as follows:

MessageConsumer consumer = session.createConsumer(queue);
Message msg = consumer.receive();
String httpContentType = msg.getStringProperty(
           SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_TYPE);
String httpContentEncoding = msg.getStringProperty(
SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_ENCODING);
Setting the properties when sending a message would follow a similar pattern as show here:
Message msg = session. createTextMessage();
msg.setStringProperty(
           SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_TYPE,
“application/json”);
msg.setStringProperty(
SupportedProperty.SOLACE_JMS_PROP_HTTP_CONTENT_ENCODING,
“gzip”);

HTTP Content Type and Content Encoding Access Using Other Solace APIs

This section applies to the following Solace APIs:

  • Solace Java  Messaging API
  • Solace Java RTO Messaging API
  • Solace C Messaging API
  • Solace .NET Messaging API

In these APIs, the HTTP headers Content Type and Content-Encoding are accessed as regular message properties as is done with other message properties such as delivery mode. The example uses the .NET API for illustration:

public static void HandleMessageEvent(Object source,
MessageEventArgs args)
{
    IMessage message = args.Message;
 
    // Process the message
    Console.WriteLine(“HTTP Content Type”);
    Console.WriteLine(message.HTTPContentType);
    Console.WriteLine(“HTTP Content Encoding”);
    Console.WriteLine(message.HTTPContentEncoding);
 
    message.Dispose();
}

Setting the properties when sending a message would follow a similar pattern as show here:

IMessage message = ContextFactory.Instance.CreateMessage();
message.HTTPContentType = “application/json”;
message.HTTPContentEncoding = “gzip”;

JMS Interactions – Text Messages

The Solace JMS implementation is flexible and allows for several encoding formats for text messages. Specifically, the JMS message property “Text Messages are XML” controls whether published text messages can have an XML payload. By default, this field is set to false so that it is disabled. A disabled state is recommended for JMS clients to inter-operate with REST clients. Therefore, you should disable this property in the Solace JNDI configuration. For information on how to set this property, refer to XML Payload.