NGS

Share JetStream as a Service

Using the add export, generate activation and add import commands of the nsc tool, a durable JetStream Consumer may be made available to other accounts as a service.

Note: A service provider may choose to make their service available to any account in NGS (public export) or to selected accounts only (private export). Private export is shown in this guide.

A service-style JetStream Consumer, also known as a Pull JS Consumer, does message delivery to a dynamic subject specified by each consuming application when the application makes a message consumption request.

Note: Zero, one or many message deliveries may be streamed to a consuming application as a result of a single consumption request. The rate and frequency of message delivery with a Pull JS Consumer is inherently controlled by each of the consuming client applications based on its own client capacity.

Restock Events Scenario

For illustration, we consider a stream of business event notifications from a system (within ACCTC) handling retail inventory signals and restocking. These event messages trigger actions in multiple downstream systems. Restock events are ingested into a JetStream named RESTOCKEVENTS.

A supply-chain application in ACCTB needs to reliably see and process the restock events.

ACCTC has set up a JetStream Consumer named RESTOCKEVENTS-C1 for ACCTB's application to receive restock events. The steps below show how to grant ACCTB access to use the service in its event processing application.

See also ngs-xacct-demo/js-consumer-service for scenario scripts and JetStream configuration.

JetStream Shared as Service

As the service provider account (ACCTC)

Publish Restock Events

You may use the NATS command-line tool to provide a mock Restock service that publishes Restock Requested event notifications.

nats request --context ACCTC retail.v1.restock.requested 'Restock for item 5678 pronto!'
15:24:42 Sending request on "retail.v1.restock.requested"
15:24:42 Received on "_INBOX.AFIRFuyu54agRhhiaXNEMG.OK9qWFoT" rtt 21.060591ms
{"stream":"RESTOCKEVENTS", "domain":"ngs", "seq":9}

Note: This is an optional step. Cross-account grants may be made at any time and do not depend on an extant JetStream.

Note: ACCTB will not receive any messages until the following steps are complete.

Make ACCTC Restock Events eligible for consumption by other accounts

Add private exports of the following Restock Events services in ACCTC with the nsc add export command:

ExportGrantSubjectExport Required
Request message deliveryservice$JS.API.CONSUMER.MSG.NEXT.RESTOCKEVENTS.RESTOCKEVENTS-C1Yes
Acknowledge a delivered messageservice$JS.ACK.RESTOCKEVENTS.RESTOCKEVENTS-C1.>Yes
Request JetStream consumer statusservice$JS.API.CONSUMER.INFO.RESTOCKEVENTS.RESTOCKEVENTS-C1Optional
nsc add export --private --account ACCTC --name RESTOCKEVENTS-GRANT-NEXT --subject '$JS.API.CONSUMER.MSG.NEXT.RESTOCKEVENTS.RESTOCKEVENTS-C1' --service --response-type Stream
nsc add export --private --account ACCTC --name RESTOCKEVENTS-GRANT-ACK --subject '$JS.ACK.RESTOCKEVENTS.RESTOCKEVENTS-C1.>' --service
nsc add export --private --account ACCTC --name RESTOCKEVENTS-GRANT-INFO --subject '$JS.API.CONSUMER.INFO.RESTOCKEVENTS.RESTOCKEVENTS-C1' --service

Note: Request message delivery service export should include --response-type Stream to allow multiple messages to be delivered to the client's reply subject in response.

Note: an export only makes a subject eligible to be imported into another account's namespace. Other accounts must explicitly import the subject. If the export is private (as here), other accounts must be in possession of an import grant activation token generated and provided by the exporter.

Specifically allow ACCTB access to the Restock Events service

Generate grant activation tokens for ACCTB with the nsc generate activation command:

nsc generate activation --output-file RESTOCKEVENTS-GRANT-NEXT-ACCTB.tok --account ACCTC --subject '$JS.API.CONSUMER.MSG.NEXT.RESTOCKEVENTS.RESTOCKEVENTS-C1' --target-account AD7T74QPICDLJYKEJQ37RKP2VXUJYUUIHZ7XMGMWFEOZNKVO3VBF46F7
nsc generate activation --output-file RESTOCKEVENTS-GRANT-ACK-ACCTB.tok --account ACCTC --subject '$JS.ACK.RESTOCKEVENTS.RESTOCKEVENTS-C1.>' --target-account AD7T74QPICDLJYKEJQ37RKP2VXUJYUUIHZ7XMGMWFEOZNKVO3VBF46F7
nsc generate activation --output-file RESTOCKEVENTS-GRANT-INFO-ACCTB.tok --account ACCTC --subject '$JS.API.CONSUMER.INFO.RESTOCKEVENTS.RESTOCKEVENTS-C1'  --target-account AD7T74QPICDLJYKEJQ37RKP2VXUJYUUIHZ7XMGMWFEOZNKVO3VBF46F7

Note: ACCTC must know ACCTB's NGS public key.

Provide the generated token files to the ACCTB owner.

As the API using account (ACCTB)

Accept access to Restock Events

Import grants using the ACCTC-provided activation token with the nsc add import command:

ImportGrantImport RequiredJS Prefix Required
Request message deliveryserviceYesYes
Acknowledge a delivered messageserviceYesNo
Request JetStream consumer statusserviceOptionalYes
nsc add import --token RESTOCKEVENTS-GRANT-NEXT-ACCTB.tok --account ACCTB --name RESTOCKEVENTS-GRANT-NEXT --local-subject ACCTC.API.CONSUMER.MSG.NEXT.RESTOCKEVENTS.RESTOCKEVENTS-C1
nsc add import --token RESTOCKEVENTS-GRANT-ACK-ACCTB.tok --account ACCTB --name RESTOCKEVENTS-GRANT-ACK --local-subject '$JS.ACK.RESTOCKEVENTS.RESTOCKEVENTS-C1.>'
nsc add import --token RESTOCKEVENTS-GRANT-INFO-ACCTB.tok --account ACCTB --name RESTOCKEVENTS-GRANT-INFO --local-subject ACCTC.API.CONSUMER.INFO.RESTOCKEVENTS.RESTOCKEVENTS-C1
Subscribe to Restock Events

You may use the NATS command-line tool to create a mock service that processes Restock Events.

nats consumer next --context ACCTB --js-api-prefix ACCTC.API --ack --count 1 RESTOCKEVENTS RESTOCKEVENTS-C1
[15:26:43] subj: retail.v1.restock.requested / tries: 1 / cons seq: 9 / str seq: 9 / pending: 0

Restock for item 5678 pronto!

Acknowledged message
Previous
Message Stream