@solace-community/angular-solace-message-client
Version:
Message client to communicate with a Solace messaging broker for sending and receiving messages using the native SMF protocol (Solace Message Format) over web socket. The library is designed to be used in Angular applications.
686 lines (679 loc) • 39.7 kB
TypeScript
import { SessionProperties, Session, Message, MessageConsumerProperties, MessageConsumer, QueueBrowserProperties, Destination, SDTField, MessageDeliveryModeType } from 'solclientjs';
import { Observable, OperatorFunction, BehaviorSubject } from 'rxjs';
import * as i0 from '@angular/core';
import { EnvironmentProviders } from '@angular/core';
/**
* Signature of a function to provide "solclientjs" continuously with a valid "OAuth 2.0 Access Token".
*
* OAuth 2.0 enables secure login to the broker while protecting user credentials.
*
* Returns an Observable that emits the user's access token upon subscription, and then continuously emits it when the token is renewed.
* The Observable should never complete, enabling the connection to the broker to be re-established in the event of a network interruption.
*
* Register this function in {@link SolaceMessageClientConfig#accessToken} and enable OAuth 2.0 authentication scheme in {@link SolaceMessageClientConfig#authenticationScheme}.
*
* **Example:**
*
* ```ts
* import {bootstrapApplication} from '@angular/platform-browser';
* import {provideSolaceMessageClient} from '@solace-community/angular-solace-message-client';
* import {AuthenticationScheme} from 'solclientjs';
* import {inject} from '@angular/core';
*
* bootstrapApplication(AppComponent, {
* providers: [
* provideSolaceMessageClient({
* url: 'wss://YOUR-SOLACE-BROKER-URL:443',
* vpnName: 'YOUR VPN',
* authenticationScheme: AuthenticationScheme.OAUTH2, // enable OAuth 2.0
* accessToken: () => inject(AuthService).accessToken$, // provide access token
* }),
* ],
* });
* ```
*
* The function can call `inject` to get any required dependencies.
*/
type OAuthAccessTokenFn = () => string | Observable<string>;
/**
* Configures the {@link SolaceMessageClient} to connect to the Solace message broker.
*/
interface SolaceMessageClientConfig extends Omit<SessionProperties, 'accessToken'> {
/**
* Specifies the access token for OAuth 2.0 authentication.
*
* Property is ignored if not using OAuth 2.0 authentication scheme.
*
* @see {@link OAuthAccessTokenFn}
*/
accessToken?: string | OAuthAccessTokenFn;
}
/**
* Signature of a function to load the config of Angular Solace Message Client.
*
* The function can call `inject` to get any required dependencies.
*/
type SolaceMessageClientConfigFn = () => SolaceMessageClientConfig | Promise<SolaceMessageClientConfig> | Observable<SolaceMessageClientConfig>;
/**
* Creates a {@link Session} from a given config to connect to the Solace message broker.
*
* You may override the default session provider in order to customize session construction, e.g., in tests, as following:
* `{provide: SolaceSessionProvider, useClass: YourSessionProvider}`
*
* The default provider does the following: `solace.SolclientFactory.createSession(sessionProperties)`.
*/
declare abstract class SolaceSessionProvider {
/**
* Method invoked to create a {@link Session} from given properties.
*/
abstract provide(sessionProperties: SessionProperties): Session;
static ɵfac: i0.ɵɵFactoryDeclaration<SolaceSessionProvider, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<SolaceSessionProvider>;
}
/**
* Enables and configures the Angular Solace Message Client, returning a set of dependency-injection providers to be registered in Angular.
*
* The Solace Message Client provides API to communicate with a Solace messaging broker for sending and receiving messages using the native SMF protocol (Solace Message Format).
*
* ### Setup
*
* ```ts
* import {bootstrapApplication} from '@angular/platform-browser';
* import {provideSolaceMessageClient} from '@solace-community/angular-solace-message-client';
*
* bootstrapApplication(AppComponent, {
* providers: [
* provideSolaceMessageClient({
* url: 'wss://YOUR-SOLACE-BROKER-URL:443',
* vpnName: 'YOUR VPN',
* userName: 'YOUR USERNAME',
* password: 'YOUR PASSWORD',
* })
* ],
* });
* ```
*
* Alternatively, a function can be passed to load the config asynchronously. The function can call `inject` to get any required dependencies.
*
* The connection to the broker will be established when `SolaceMessageClient` is injected for the first time.
*
* ### Usage
*
* **Publish a message to a topic**
*
* ```ts
* import {SolaceMessageClient} from '@solace-community/angular-solace-message-client';
* import {inject} from '@angular/core';
*
* inject(SolaceMessageClient).publish('myhome/kitchen/temperature', '20°C');
* ```
*
* **Receive messages sent to a topic**
*
* ```ts
* import {SolaceMessageClient} from '@solace-community/angular-solace-message-client';
* import {inject} from '@angular/core';
*
* inject(SolaceMessageClient).observe$('myhome/livingroom/temperature').subscribe(envelope => {
* // ...
* });
* ```
*
* ### Connect to Multiple Solace Message Brokers
*
* An application is not limited to connecting to a single Solace Message Broker. Different injection environments can be used to connect to different brokers.
*
* Angular injection environments form a hierarchy, inheriting providers from parent environments. An environment can register new providers or replace inherited providers.
* A child environment is created through routing or programmatically using `createEnvironmentInjector`.
*
* Example for connecting to two different brokers:
*
* ```ts
* import {createEnvironmentInjector, EnvironmentInjector, inject} from '@angular/core';
* import {provideSolaceMessageClient, SolaceMessageClient} from '@solace-community/angular-solace-message-client';
*
* // Create environment to provide message client for broker 1.
* const environment1 = createEnvironmentInjector([provideSolaceMessageClient({url: 'broker-1'})], inject(EnvironmentInjector));
* // Inject message client.
* const messageClient1 = environment1.get(SolaceMessageClient);
* // Publish message to broker 1.
* messageClient1.publish('topic', 'message for broker 1');
*
* // Create environment to provide message client for broker 2.
* const environment2 = createEnvironmentInjector([provideSolaceMessageClient({url: 'broker-2'})], inject(EnvironmentInjector));
* // Inject message client.
* const messageClient2 = environment2.get(SolaceMessageClient);
* // Publish message to broker 2.
* messageClient2.publish('topic', 'message for broker 2');
*
* // Destroy environments to destroy provided `SolaceMessageClient` instances.
* environment1.destroy();
* environment2.destroy();
* ```
*
* ### Logging
*
* The default log level is set to `WARN` so that only warnings and errors are logged.
*
* The default log level can be changed as follows:
*
* ```ts
* import {bootstrapApplication} from '@angular/platform-browser';
* import {provideSolaceMessageClient} from '@solace-community/angular-solace-message-client';
* import {LogLevel} from 'solclientjs';
*
* bootstrapApplication(AppComponent, {
* providers: [
* provideSolaceMessageClient(),
* {provide: LogLevel, useValue: LogLevel.INFO}, // Add this line
* ],
* });
* ```
*
* To change the log level at runtime, add the `angular-solace-message-client#loglevel` entry to session storage
* and reload the application. Supported log levels are: `trace`, `debug`, `info`, `warn`, `error` and `fatal`.
*
* Storage Key: `angular-solace-message-client#loglevel`
* Storage Value: `info`
*
* @param config - Configures {@link SolaceMessageClient}.
* Can be an object or a function to provide the config asynchronously.
* The function can call `inject` to get any required dependencies.
*/
declare function provideSolaceMessageClient(config: SolaceMessageClientConfig | SolaceMessageClientConfigFn): EnvironmentProviders;
/**
* Provides {@link SolaceMessageClient} which does nothing, e.g, useful in tests.
*
* ---
* Usage:
*
* ```ts
* TestBed.configureTestingModule({
* providers: [
* provideNullSolaceMessageClient(),
* ],
* });
* ```
*/
declare function provideNullSolaceMessageClient(): EnvironmentProviders;
/**
* Allows clients to communicate with a Solace messaging broker for sending and receiving messages using the native SMF protocol (Solace Message Format).
*
* This message client establishes a single connection to the broker regardless of the number of subscriptions.
*
* See https://docs.solace.com/API-Developer-Online-Ref-Documentation/js/index.html for more information about the Solace Web API.
*/
declare abstract class SolaceMessageClient {
/**
* An Observable that, when subscribed, emits the current connection state to the broker.
* Upon subscription, emits the current connection state, unless no connect attempt has been made yet. It never completes and
* emits continuously when the connection state changes.
*/
abstract readonly connected$: Observable<boolean>;
/**
* Promise that resolves to the {@link Session} when connected to the message broker, or that rejects if no connection
* could be established, or if no connect attempt has been made yet.
*/
abstract readonly session: Promise<Session>;
/**
* Receives messages published to the given topic. Messages are received in the zone in which subscribed to the Observable.
*
* The Observable never completes, unless invoking {@link disconnect}. If not connected to the broker yet, or if the connect attempt failed, the Observable errors.
*
* You can subscribe to multiple topics simultaneously by using wildcard segments in the topic. Topics are case-sensitive and consist of one or more segments, each
* separated by a forward slash.
*
* **Single-Level Wildcard Character (`*`)**:
* - if a segment contains the asterisk (`*`) character as its only character, this segment is required and acts as a placeholder for any segment value.
* - if a segment ends with the asterisk (`*`) character, this segment acts as a placeholder for segment values starting with the characters before the asterisk.
* The segment to match can have additional characters, must does not have to.
*
* **Multi-Level Wildcard Character (`>`)**:
* - when used as the last segment, it provides a "one or more" wildcard match for any topics with an identical prefix to the subscription.
*
* See https://docs.solace.com/PubSub-Basics/Wildcard-Charaters-Topic-Subs.htm for more information and examples.
*
* If a segment begins with a colon (`:`), it is called a named wildcard segment that acts as a placeholder for any value. The characters after the colon give the segment its name.
* Internally, named wildcard segments are translated to single-level wildcard segments. Named segments can be read from the received message
* For example, the topic 'myhome/:room/temperature' is translated to 'myhome/* /temperature', matching messages sent to topics like 'myhome/kitchen/temperature' or 'myhome/livingroom/temperature'.
* Substituted segment values are then available in {@link MessageEnvelope.params}, or as the second element of the tuple when using {@link mapToBinary} or {@link mapToText}
* RxJS operators.
*
* To map directly to the payload, you can use the following RxJS operators: {@link mapToBinary}, {@link mapToText}.
*
* @param topic - Specifies the topic which to observe.
* Topics are case-sensitive and consist of one or more segments, each separated by a forward slash.
* You can subscribe to the exact topic of a published message, or use wildcards (single-level or multi-level) to subscribe to multiple topics simultaneously.
* As an alternative to the single-level wildcard `*`, named wildcard segments can be used. A named wildcard segment begins with a colon (`:`) followed by a name.
* Substituted segments can be read from the received message.
*
* @param options - Controls how to observe the topic.
* @return Observable that emits when receiving a message published to the given topic. The Observable never completes. If not connected to the broker yet, or if the connect attempt failed, the Observable errors.
*/
abstract observe$(topic: string, options?: ObserveOptions): Observable<MessageEnvelope>;
/**
* Consumes messages from a given topic endpoint or queue endpoint. Messages are received in the zone in which subscribed to the Observable.
*
* Endpoint names are case-sensitive and consist of one or more segments, each separated by a forward slash.
*
* When passing a `string` topic literal (that is, not a {@link MessageConsumerProperties} object), creates a private, non-durable topic endpoint on the broker that subscribes
* to messages published to the given topic. From the consumer's point of view, this is similar to observe a topic using {@link SolaceMessageClient#observe$}, with the difference
* that messages are not lost in the event of short connection interruptions as messages are retained on the broker until transported to the consumer. The lifecycle of a non-durable
* topic endpoint is bound to the client that created it, with an additional 60s in case of unexpected disconnect.
*
* To subscribe to a queue, or to pass a more advanced endpoint configuration, pass a {@link MessageConsumerProperties} object instead.
*
* ## Passing a `string` topic literal is equivalent to passing the following config:
*
* ```ts
* solaceMessageClient.consume$({
* topicEndpointSubscription: SolclientFactory.createTopicDestination('topic'),
* queueDescriptor: new QueueDescriptor({
* type: QueueType.TOPIC_ENDPOINT,
* durable: false,
* }),
* });
* ```
*
* ## To consume messages sent to a durable queue, pass the following config:
* ```ts
* solaceMessageClient.consume$({
* queueDescriptor: new QueueDescriptor({
* type: QueueType.QUEUE,
* name: 'queue',
* }),
* });
* ```
*
* ## Topic vs Topic Endpoint
* A topic is not the same thing as a topic endpoint. Messages cannot be published directly to topic endpoints, but only indirectly via topics.
* A topic is a message property the event broker uses to route a message to its destination. Topic endpoints, unlike topics, are objects that define the storage of messages
* for a consuming application. Topic endpoints are more closely related to queues than to topics.
* For more information, refer to https://solace.com/blog/queues-vs-topic-endpoints.
*
* For topic endpoints, you can subscribe to multiple topics simultaneously by using wildcard segments in the topic.
*
* **Single-Level Wildcard Character (`*`)**:
* - if a segment contains the asterisk (`*`) character as its only character, this segment is required and acts as a placeholder for any segment value.
* - if a segment ends with the asterisk (`*`) character, this segment acts as a placeholder for segment values starting with the characters before the asterisk.
* The segment to match can have additional characters, must does not have to.
*
* **Multi-Level Wildcard Character (`>`)**:
* - when used as the last segment, it provides a "one or more" wildcard match for any topics with an identical prefix to the subscription.
*
* See https://docs.solace.com/PubSub-Basics/Wildcard-Charaters-Topic-Subs.htm for more information and examples.
*
* If a segment begins with a colon (`:`), it is called a named wildcard segment that acts as a placeholder for any value. The characters after the colon give the segment its name.
* Internally, named wildcard segments are translated to single-level wildcard segments. Named segments can be read from the received message
* For example, the topic 'myhome/:room/temperature' is translated to 'myhome/* /temperature', matching messages sent to topics like 'myhome/kitchen/temperature' or 'myhome/livingroom/temperature'.
* Substituted segment values are then available in {@link MessageEnvelope.params}, or as the second element of the tuple when using {@link mapToBinary} or {@link mapToText} RxJS operators.
*
* To map directly to the payload, you can use the following RxJS operators: {@link mapToBinary}, {@link mapToText}.
*
* @param topicOrDescriptor - If specifying a `string` literal, then it is used as the subscription topic to create a topic endpoint for, allowing messages to be reliably received even if the
* connection is unstable. If passing a descriptor object, it is used as the config to connect to a queue or topic endpoint.
* A topic endpoint subscription allows using wildcards (single-level or multi-level) to subscribe to multiple topics simultaneously.
* As an alternative to the single-level wildcard `*`, named wildcard segments can be used. A named wildcard segment begins with a colon (`:`) followed by a name. Substituted segments can be read from the received message.
* @return Observable that emits when receiving a message published to the given endpoint. The Observable never completes. If not connected to the broker yet, or if the connect attempt failed, the Observable errors.
*/
abstract consume$(topicOrDescriptor: string | (MessageConsumerProperties & ConsumeOptions)): Observable<MessageEnvelope>;
/**
* Browses messages in a queue, without removing/consuming the messages. Messages are received in the zone in which subscribed to the Observable.
*
* @param queueOrDescriptor - Specifies the queue to browse, or a descriptor object describing how to connect to the queue browser.
* @return Observable that emits spooled messages in the specified queue. The Observable never completes. If not connected to the broker yet, or if the connect attempt failed, the Observable errors.
*/
abstract browse$(queueOrDescriptor: string | QueueBrowserProperties): Observable<MessageEnvelope>;
/**
* Publishes a message to the given topic or queue destination.
*
* ## Topic Destination
* When sending the message to a topic destination, the broker will transport the message to all subscribers subscribed to the topic at the time of sending the message.
*
* ## Queue Destination
* A queue differs from the topic distribution mechanism that the message is transported to exactly a single consumer, i.e., the message is load balanced to a single consumer
* in round‑robin fashion, or for exclusive queues, it is always transported to the same subscription. When sending a message to a queue, the broker retains the message until
* it is consumed, or until it expires. Refer to the subsequent chapter 'Durability of Endpoints' for more information.
* A queue is typically used in a point-to-point (P2P) messaging environment.
*
* ## Topic vs Topic Endpoint
* A topic is not the same thing as a topic endpoint. Messages cannot be published directly to topic endpoints, but only indirectly via topics.
* A topic is a message property the event broker uses to route a message to its destination. Topic endpoints, unlike topics, are objects that define the storage of messages
* for a consuming application. Topic endpoints are more closely related to queues than to topics.
* For more information, refer to https://solace.com/blog/queues-vs-topic-endpoints.
*
* ## Destination Name
* Destinations case-sensitive and consist of one or more segments, each separated by a forward slash. The destination must be exact, thus not contain wildcards.
*
* ## Payload
* A message may contain unstructured byte data, or a structured container. See {@link Data} for further information.
*
* ## Delivery Mode
* Solace supports two delivery modes, also known as qualities of service (QoS):
* - Direct Messaging (default if not specified)
* - Guaranteed or Persistent Messaging
*
* You can change the message delivery mode via the {@link PublishOptions.deliveryMode} property.
* For more information, refer to the documentation of {@link PublishOptions.deliveryMode}.
*
* ## Durability of Queue Endpoints
* Solace distinguishes between durable und non-durable queues.
*
* When sending the message to a durable queue, the broker retains the message until it is consumed (and also acknowledged) by the consumer, or until
* it expires. In constract, a non-durable queue, also known as a temporary queue, has a shorter lifecycle than a durable queue. It has the lifespan
* of the client that created it, with an additional 60 seconds in case of unexpected disconnect. The 60 seconds provides the client with some time to
* reconnect to the endpoint before it and its contents are deleted from the Solace broker.
*
* Although the terms durable and persistent are related, keep in mind that the concept 'durability' applies to endpoints, whereas 'persistence'
* applies to event messages.
*
* For further information refer to:
* - https://docs.solace.com/PubSub-Basics/Endpoints.htm
* - https://solace.com/blog/solace-endpoints-durable-vs-non-durable
*
* @param destination - Specifies the destination where to send the message to. If of the type `string`, sends it to a topic destination.
* To send a message to a queue, pass a queue {@link Destination} which can be constructed using the {@link SolclientFactory}, as following:
* `SolclientFactory.createDurableQueueDestination('queue')`
* @param data - Specifies optional {@link Data transfer data} to be carried along with this message. A message may contain unstructured byte data,
* or structured data in the form of a {@link SDTField}. Alternatively, to have full control over the message to be published, pass the
* {@link Message} object instead, which you can construct using {@link SolclientFactory#createMessage}.
* For more information, refer to the documentation of {@link Data}.
* @param options - Controls how to publish the message.
* @return A Promise that resolves when the message could be successfully dispatched or that rejects otherwise.
* The Promise resolves immediately if the published message has the delivery mode {@link MessageDeliveryModeType#DIRECT} (direct messaging).
* If the published message has the delivery mode {@link MessageDeliveryModeType#PERSISTENT} (guaranteed or persistent messaging),
* the Promise resolves once acknowledged, i,e., when one-third of the publish window size is reached or one second has elapsed.
* Refer to https://docs.solace.com/API/API-Developer-Guide/Acknowledging-Published-.htm for more information.
*/
abstract publish(destination: string | Destination, data?: Data | Message, options?: PublishOptions): Promise<void>;
/**
* Sends a request to the specified destination and waits for the response to arrive. Replies are received in the zone in which subscribed to the Observable.
*
* - If sending the request to a topic, the request is transported to all subscribers subscribed to the topic at the time of sending the request.
* - If sending the request to a queue, the request is transported to a single subscriber. The request is retained if there was no subscriber
* at the time of sending the request.
* - If not receiving a reply within the specified (or globally set) timeout, then the Observable will error.
* - If not passing a 'replyTo' destination via options object, the API will generate a 'replyTo' destination where to send the reply to.
*
* Note:
* The implementation is based on "solclientjs" {@link Session#sendRequest} which does not support receiving multiple responses
* and requires the replier to include the requestor's `correlationId` in the reply message.
*
* @param destination - Specifies the destination where to send the message to. If of the type `string`, sends it to a topic destination.
* @param data - Specifies optional {@link Data transfer data} to be carried along with this request. The request may contain unstructured byte data,
* or structured data in the form of a {@link SDTField}. Alternatively, to have full control over the message to be published, pass the
* {@link Message} object instead, which you can construct using {@link SolclientFactory#createMessage}.
* For more information, refer to the documentation of {@link Data}.
* @param options - Controls how to publish the request, e.g., to pass a custom 'replyTo' destination.
* @return Observable that emits the received reply and then completes, or that errors if the request could not be dispatched or no reply was received
* within the specified timeout.
*/
abstract request$(destination: string | Destination, data?: Data | Message, options?: RequestOptions): Observable<MessageEnvelope>;
/**
* Replies to the passed request.
*
* @param request - Specifies the request to send a reply for.
* @param data - Specifies optional {@link Data transfer data} to be carried along with the reply. The reply may contain unstructured byte data,
* or structured data in the form of a {@link SDTField}. Alternatively, to have full control over the message to be published, pass the
* {@link Message} object instead, which you can construct using {@link SolclientFactory#createMessage}.
* For more information, refer to the documentation of {@link Data}.
* @param options - Controls how to publish the reply.
* @return A Promise that resolves when dispatched the reply, or that rejects if the reply could not be dispatched.
*/
abstract reply(request: Message, data?: Data | Message, options?: PublishOptions): Promise<void>;
static ɵfac: i0.ɵɵFactoryDeclaration<SolaceMessageClient, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<SolaceMessageClient>;
}
/**
* SolaceMessageClient which does nothing, i.e., can be used in tests.
*/
declare class NullSolaceMessageClient implements SolaceMessageClient {
readonly connected$: BehaviorSubject<boolean>;
observe$(topic: string, options?: ObserveOptions): Observable<MessageEnvelope>;
consume$(topicOrDescriptor: string | (MessageConsumerProperties & ConsumeOptions)): Observable<MessageEnvelope>;
browse$(queueOrDescriptor: string | QueueBrowserProperties): Observable<MessageEnvelope>;
publish(destination: string | Destination, data?: ArrayBufferLike | DataView | string | SDTField | Message, options?: PublishOptions): Promise<void>;
request$(destination: string | Destination, data?: Data | Message, options?: RequestOptions): Observable<MessageEnvelope>;
reply(request: Message, data?: ArrayBufferLike | DataView | string | SDTField | Message, options?: PublishOptions): Promise<void>;
get session(): Promise<Session>;
static ɵfac: i0.ɵɵFactoryDeclaration<NullSolaceMessageClient, never>;
static ɵprov: i0.ɵɵInjectableDeclaration<NullSolaceMessageClient>;
}
/**
* Control how to observe a topic.
*/
interface ObserveOptions {
/**
* Specifies the maximum time (in milliseconds) to wait for the destination to be subscribed.
* If specified, overrides the global timeout as set via {@link SessionProperties#readTimeoutInMsecs}.
*/
subscribeTimeout?: number;
/**
* A lifecycle hook that is called when subscribed to a destination.
*
* Use if you need to wait until the destination is actually subscribed, e.g, if implementing the request/response message exchange pattern,
* or for reading information about the endpoint if consuming messages via {@link SolaceMessageClient#consume$}.
*/
onSubscribed?(): void;
}
/**
* Control how to consume messages.
*/
interface ConsumeOptions {
/**
* A lifecycle hook that is called when subscribed to a destination.
*
* Use if you need to wait until the destination is actually subscribed, e.g, if implementing the request/response message exchange pattern,
* or for reading information about the endpoint if consuming messages via {@link SolaceMessageClient#consume$}.
*
* @param messageConsumer - reference to the message consumer, useful to read generated endpoint names:
* * For non-durable endpoints, if not passing an endpoint name, Solace API generates a name which can be queried by calling {@link MessageConsumer#getDestination};
* The generated descriptor can be queried by calling {@link MessageConsumer#getProperties#queueDescriptor};
* * For durable endpoints, endpoint properties can be retrieved as configured on the broker by calling {@link MessageConsumer#getProperties#queueProperties};
*/
onSubscribed?(messageConsumer: MessageConsumer): void;
}
/**
* Control how to publish a message.
*/
interface PublishOptions {
/**
* Allows intercepting the raw message before it is sent over the network.
*
* Only basic properties can be set via {@link PublishOptions}. To set other properties or properties not yet supported by the API,
* the message can be intercepted and the properties set accordingly.
*/
intercept?: (message: Message) => void;
/**
* Convenience API for setting headers to pass additional information along with the message.
*
* Headers are transported as structured data separate from the payload. To pass a header value
* different to `string`, `boolean` or `number`, pass it as Structured Data Type (SDT) in the
* form of a {@link SDTField}, as following: `SDTField.create(SDTFieldType.INT8, 2);`
*
* Header values are mapped as following to structured data types:
* `string` -> SDTFieldType.STRING
* `boolean` -> SDTFieldType.BOOL
* `number` -> SDTFieldType.INT32
*
* @see Message.setUserPropertyMap
*/
headers?: Map<string, string | boolean | number | SDTField>;
/**
* Specifies the message priority (JMS Priority) for the message.
* Numerical values between 0 and 255 are accepted, use undefined to unset.
*
* If destination queues and topic endpoints for this message
* are configured to respect message priority,
* the values 0 through 9 can be used to affect the priority
* of delivery to consumers of those queues or topic endpoints.
* For the purposes of prioritized message delivery, values larger than 9
* are treated the same as 9.
*/
priority?: number;
/**
* Specifies the guaranteed message TTL, in milliseconds.
*
* The time to live is the number of milliseconds the message may be stored on the
* Solace Message Router before the message is discarded or moved to a Dead Message
* Queue. See {@link Message.setDMQEligible}.
*
* Setting the Time To Live to zero disables TTL for the message.
*
* This property is only valid for Guaranteed messages (Persistent and Non-Persistent).
* It has no effect when used in conjunction with other message types unless the message
* is promoted by the appliance to a Guaranteed message.
*
* The maxium allowed time to live is 3.1536E11 (315360000000) which is
* approximately 10 years.
*/
timeToLive?: number;
/**
* Specifies if to publish a Guaranteed Message DMQ (Dead Message Queue) eligible message.
* When this property is set, when the message expires in the network,
* the message is saved on a appliance dead message queue. Otherwise the expired message is
* discarded. See {@link PublishOptions.setTimeToLive}.
*/
dmqEligible?: boolean;
/**
* Sets the delivery mode of the message.
*
* Solace supports two delivery modes, also known as qualities of service (QoS):
* - Direct Messaging (default if not specified)
* - Guaranteed or Persistent Messaging
*
* For a detailed comparison, refer to https://solace.com/blog/delivery-modes-direct-messaging-vs-persistent-messaging.
*
* ### Direct Messaging (default)
* Direct messaging is over TCP and provides a reliable, but not guaranteed, delivery of messages from the Solace event broker to consuming clients,
* and is the default message delivery system. The broker delivers a message one time at most. It is most appropriate for messaging applications
* that require very high-rate or very low-latency message transmission, i.e., to efficiently publish messages to a large number of clients with matching
* subscriptions.
*
* For more information, refer to https://docs.solace.com/PubSub-Basics/Direct-Messages.htm.
*
* ### Persistent or Guaranteed Messaging
* Persistent messaging is also over TCP but has an additional set of acknowledgments beyond those used by TCP itself. Solace event broker guarantees the message
* never to be lost and to be delivered at least once. Use persistent messaging when data must be received by the consuming application.
*
* Persistent messaging occurs between the publishing application and the broker, and between the broker and the consuming application. If the consuming application
* is not connected or cannot keep up with the publishing application, the messages are stored in endpoints on the broker.
*
* For more information, refer to https://docs.solace.com/PubSub-Basics/Guaranteed-Messages.htm or https://docs.solace.com/PubSub-Basics/Basic-Guaranteed-Messsaging-Operation.htm.
*
* If you experience poor performance when sending guaranteed messages, consider adjusting the size of the publishing window via {@link Session#publisherProperties#windowSize},
* as described here: https://solace.com/blog/understanding-guaranteed-message-publish-window-sizes-and-acknowledgement
*
* @default MessageDeliveryModeType.DIRECT
*/
deliveryMode?: MessageDeliveryModeType;
/**
* Sets the correlation ID which is carried in the message headers unmodified.
*
* A correlation ID is a unique identifier value that is attached to a message that allows referencing to a particular transaction or event chain.
*
* If replying to a request via {@link SolaceMessageClient#reply}, the API will copy the correlation id from the request, thus must not be set manually.
*/
correlationId?: string;
/**
* Sets the correlation key to correlate events from the Solace event broker when sending the message to the broker.
*
* The correlation key is an object that is passed back to the client during the router acknowledgement or rejection.
* Note that the correlation key is not included in the transmitted message and is only used with the local API.
*/
correlationKey?: string | object;
/**
* Sets the destination a replier can reply to in "request-response" communication.
*
* If not passed the API will generate a 'replyTo' destination where to send the reply to.
*/
replyTo?: Destination;
/**
* Marks this message as a reply to a previous request in "request-response" communication.
*
* If replying to a request via {@link SolaceMessageClient#reply}, the API will mark the message as a reply, thus must not be set manually.
*/
markAsReply?: boolean;
}
/**
* Control how to publish a request.
*/
interface RequestOptions extends PublishOptions {
/**
* Specifies the maximum time (in milliseconds) to wait for a response to be received. The minimum value is 100ms.
* If specified, overrides the global timeout as set via {@link SessionProperties#readTimeoutInMsecs}.
*/
requestTimeout?: number;
}
/**
* RxJS operator for mapping a structured text message into its textual representation.
*
* Each message is mapped to a tuple of three elements:
* [<text>, Params, Message].
*
* Note: Messages must be published as {@link MessageType.TEXT} messages, otherwise an error is thrown.
*/
declare function mapToText(): OperatorFunction<MessageEnvelope, [string, Params, Message]>;
/**
* RxJS operator for mapping a message into its binary representation.
*
* Each message is mapped to a tuple of three elements:
* [<binary>, Params, Message].
*
* Backward compatibility note: Using the version10 factory profile or older, the binary attachment is returned as a 'latin1' String:
* Each character has a code in the range * 0-255 representing the value of a single received byte at that position.
*
* Note: Messages must be published as {@link MessageType.BINARY} messages, otherwise an error is thrown.
*/
declare function mapToBinary<T extends Uint8Array | string = Uint8Array>(): OperatorFunction<MessageEnvelope, [T, Params, Message]>;
/**
* Container for substitued values of named wildcard topic segments.
*/
type Params = Map<string, string>;
/**
* Envelope containing the {@link Message} and resolved values for named topic segments, if any.
*/
interface MessageEnvelope {
/**
* Unmodified message as received by the Solace message broker.
*/
message: Message;
/**
* Contains the resolved values of named single-level wildcard segments as specified in the topic.
* For example: If subscribed to the topic `person/:id` and a message is published to the topic `person/5`,
* the resolved id with the value `5` is contained in the segments map.
*/
params: Params;
/**
* Convenience API for accessing headers attached to the message.
*
* @see Message.getUserPropertyMap
*/
headers: Map<string, any>;
}
/**
* Represents the payload of a message.
*
* A message may contain unstructured byte data, or a structured container.
*
* ## Binary Data Message
* By default, data is transported as unstructured bytes in the binary attachment message part.
*
* Supported data types are:
* - ArrayBufferLike, e.g. `ArrayBuffer`, `Uint8Array`, `Uint32Array`, or similar
* - DataView
* - string (latin1-encoded; only supported for backwards compatibility; use `new TextEncoder.encode(...)` instead)
*
* ## Structured Data Message
* Alternatively, you can exchange data using the structured data API by passing it as Structured Data Type (SDT) in the form of a {@link SDTField}
* of the type {@link SDTFieldType#STRING}, {@link SDTFieldType#MAP} or {@link SDTFieldType#STREAM}. Transporting data as structured message is useful
* in a heterogeneous network that has clients that use different hardware architectures and programming languages, allowing exchanging binary data in
* a structured, language- and architecture-independent way.
*
* Example: `SDTField.create(SDTFieldType.STRING, 'payload')`
*
* https://solace.com/blog/inside-solace-message-introduction/
*/
type Data = ArrayBufferLike | DataView | string | SDTField;
export { NullSolaceMessageClient, SolaceMessageClient, SolaceSessionProvider, mapToBinary, mapToText, provideNullSolaceMessageClient, provideSolaceMessageClient };
export type { ConsumeOptions, Data, MessageEnvelope, OAuthAccessTokenFn, ObserveOptions, Params, PublishOptions, RequestOptions, SolaceMessageClientConfig, SolaceMessageClientConfigFn };