Azure-sdk-for-java: [FSB Track2] [API Shape Discussion] Champion Scenarios

[hemanttanwar]

Service Bus Client: Service Bus Receiver/Sender Client Proposal

The Service Bus client library offers two primary clients for sending and receiving messages, the ServiceBusSenderClient and ServiceBusReceiverClient respectively. Each designed for different operations but unified in their approach to provide a consistent experience for developers. These clients embrace a common design philosophy in providing developers an experience optimized around ease of use, familiar patterns, and a consistent API across them.

Both of the clients are designed to be user-friendly for someone who is new and does not know backend concept of Queue, Topics in details and also to some one who is coming from legacy concept of messaging.

Concepts
Namespace : A namespace is a scoping container for all messaging components. Multiple queues and topics can reside within a single namespace, and namespaces often serve as application containers.
Topics : You can also use topics to send messages. While a queue is often used for point-to-point communication, topics are useful in publish/subscribe scenarios. Enable an application to announce events to multiple interested consumers asynchronously.
https://docs.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber

Subscriptions : A subscriber to a topic can receive a copy of each message sent to that topic. Subscriptions are named entities.

Queue : Messages are sent to and received from queues. Queues store messages until the receiving application is available to receive and process them.

Enable multiple concurrent consumers to process messages received on the same messaging channel. This enables a system to process multiple messages concurrently to optimize throughput, to improve scalability and availability, and to balance the workload
https://docs.microsoft.com/en-us/azure/architecture/patterns/competing-consumers

Things to know before reading
• Some details not related to the high-level concept are not illustrated; the scope of this is limited to the high level shape and paradigms for the feature area.

Target segment: Regular , Middleware , DIY (Do it yourself) Developers

Regular Developers: Most of the developers write to Queue/Topic and read from Queue/Subscriptions. Their use case is simple but used a lot in production. For example Read one message, process it and go to next message.
Middleware Developers : These SDK writers who wrap Queue/ Topic in middle which are agnostic of server side concept or vendor agnostic. Their point of view is "send" or "receive".
DIY Developers: These are advance users who want to do everything on their own. For example message handling, exception handling, managing transactions etc.

Champion Scenarios
Scenarios 1 : Sender can send messages

A Real world existing application:
https://www.cloudamqp.com/blog/2017-09-25-breaking-down-a-monolithic-system-into-microservices.html
https://www.parkster.com/se/parking-with-parkster/

Parkster is company which provide solution for managing parking lots, payments, billing to large number of parking lots all over the world. Parkster started out with a monolithic architecture. They wanted to have their business model proven before they went further, so they started with one application which became monolithic . A monolithic application is where the whole application is built as a single unit. All code for a system is in a single codebase that is compiled together and produces a single system.
The biggest reason we moved from monolith to microservice were decoupling. Parkster’s move from a monolith architecture to a 15-20 microservice architecture. These multiple microservices communicating via message queues.

Once a parking spot is reserved by customer, One ReservationService will send a message to "ParkingLotManagerService" microservice using a queue.

ReservationService ------> ParkingLotManagementService

Message : (Spot 15) is reserved for 4 hours starting at 2 PM PST.

• ReservationService has a guaranteed delivery to the queue.

• Message sequence is not guaranteed unless queue is session enabled and client specify that.

• The ParkingLotManagerService does not have to be online.

Exception case:
What if the receiver hangs/takes JUST long enough to not be able to renew before lock has expired and is claimed by another consumer? : Since the receiver did not renew lock before it expired, this message will be placed in queue and next customer can receive it.

Scenarios 2 : Receiver can receive messages

The ParkingLotManagerService should be able to receive messages asynchronously. The ParkingLotManagerService will receive one message at a time and update its system with start and end time for parking. It will also start a background timer which will inform other services when parking time slot expire.

• There could be one or more competing consumers.
• Receiver could manage message in queue i.e. complete, defer, abandon, and dead-letter
• Receiver could Renew locks on messages and sessions in queues.
• Receiver could peek-lock a message.
• The receiver can indicate message processing is complete.

Message Locking: While this message is being processed , no other thread/process can process this same message.
Receive And Delete: Sometime a receiver do not want to lock the message, It will receive a message and service delete this message from Queue.

Example :If we have "AverageCustomerPerDayService" which count how many customer uses parking lot on average everyday. It will increase count by one for each message and if it fails to do for few messages it wouldn't cause company a fortune.

Exception Cases

• If receiver takes longer time to process, the lock will be released and which makes this message available .

• What if receiver crashes before if complete the message, this message will be made available to other receiver for processing?

Scenarios 3 : Middleware can Send and Receive messages agnostic of Topic/Queue

Some companies build middleware products where user does not care about service concept of Queue and Topics. And user just care about sending to or receiving from "Messaging System" without knowing how it is implemented.

Scenario 1 and 2 list all features needed for this scenario.

Scenarios 4 : Publisher can publish message to a topic

• A publisher can send/publish a message to topic which can be consumed by one or more subscribers.

For Example "Order service" publishes an order.
"Order # 101,Category=Book, Name:Programming Server Side by Jeffery Richter, Number of books = 2, Price = $100.00"

Topic Name = "ORDER_TOPIC"

• When the message is sent to topic it is guaranteed delivery.
• The subscribers does not have to be online.
• The sender does not know how many subscribers are there.

Scenarios 5: Subscriber can subscribe to a topic

Topic Name = "ORDER_TOPIC"
Subscriber 1 Name = "User_Service Subscriber"
Subscriber 2 Name = "Price Service Subscriber"
Subscriber 3 Name = "Delivery Service Subscriber"
Subscriber 4 Name = "HeavyProduct Delivery Service Subscriber"

• There could be more than one subscriber.

• Each subscriber gets their own copy of message.

• A filter could be applied on a message. For example
  Subscriber 4 Name = "HeavyProduct Delivery Service SUBSCRIBER" Filter Rule = "Category == Appliance"

Above order will be received by first three subscriber but not by Subscriber 4 because it does not satisfy filter rule.
Other common uses cases for filter
Security : In some cases, we can restrict a subscriber to see one specific type of message.
Debugging : Some MS groups uses filter 1=1, to receive all the messages and determine why other subscriber are not receiving messages.

Scenarios 6 : Receiver can receive messages in sequence

A Real world existing application:
https://www.cloudamqp.com/blog/2017-09-25-breaking-down-a-monolithic-system-into-microservices.html
https://www.parkster.com/se/parking-with-parkster/

Once a parking spot is reserved by customer, ReservationService will send a message to ParkingLotManagerService using a queue. The customer changes mind with in few minutes and decide to cancel the reservation.

This scenario need FIFO which is only guaranteed when using sessions, since otherwise things would get messed up if we get the cancel message before the reserve message.

Lets say following is message sequence executed by consumer.

Message 1 : Spot 15 is reserved for 4 hours starting at 2 PM , Session ID ="SPOT-15"
Message 2 : Spot 15 reservation for 2 PM is cancelled, Session ID ="SPOT-15"

The ParkingLotManagerService will receive these message in sequence for Session ID ="SPOT-15".

Scenarios 7 : Receiver can receive messages in sequence for next available scenario

A Real world existing application:
https://www.cloudamqp.com/blog/2017-09-25-breaking-down-a-monolithic-system-into-microservices.html
https://www.parkster.com/se/parking-with-parkster/
Once a parking spot is reserved by customer, ReservationService will send a message to ParkingLotManagerService using a queue. There are multiple messages for different parking spots.

Lets say following is message sequence executed by consumer.

Message 1 : Spot 10 is reserved for 4 hours starting at 2 PM , Session ID ="SPOT-10"
Message 3 : Spot 15 reservation for 2 PM is cancelled, Session ID ="SPOT-15"
Message 2 : Spot 10 is extended for 2 more hours , Session ID ="SPOT-10"
Message 4 : Spot 15 reservation is cancelled , Session ID ="SPOT-15"

The ParkingLotManagerService request for "any" available session for processing
Service will pick next available session, for example Session ID ="SPOT-15".

Scenarios 8: Management Scenario
There are more operation which are management in nature.
Create Queue , Topic and Subscription
Add / Remove Rule/Filter
Note : No API are discussed for management scenario here but we noted them here as reference for completeness.

[JoshLove-msft]

Regarding Management Scenario, I thought we aren't planning on covering the management scenarios for this review?

[richardpark-msft]

Topics : You can also use topics to send and receive messages. While a queue is often used for point-to-point communication, topics are useful in publish/subscribe scenarios.

You can send to a topic, but not read from it. Unless you meant something else.

[richardpark-msft]

There is definitely a use case for "get next unlocked session w/o knowing it's name" that we should account for. I think the only session case we have above is via a pre-coordinated name.

@JoshLove-msft's library has the most complete and "in production" version of that.

[richardpark-msft]

Also, this has come up multiple times (and so should probably get mentioned in the champion scenarios) that, in either the subscription or queue case, multiple consumers can run against the same queue or subscription. (could be worth updating the diagram above to show the consumer as multiple overlapping rectangles - ie, multiple instances).

The difference between subscriptions and queues is that in subscriptions multiple consumers can also act on the same message.

I think people get confused that only one _instance_ of a consumer can get messages from a queue/single sub at the same time.

[richardpark-msft]

What if receiver crashes before if complete the message, this message will be made available to other receiver for processing?

This isn't really worth mentioning - it's a property of every network-based system. _Unless_ you're thinking we should provide some form of local durable storage?

[richardpark-msft]

For competing consumers we have a cool page:

https://docs.microsoft.com/en-us/azure/architecture/patterns/competing-consumers

Worth linking, IMO. The diagram in there also shows the multi-instance-consumer thing that I mentioned in another comment.

[richardpark-msft]

Transactions

Hm...perhaps we could do something in the workflow example, but this time receiving payments? So we do the send-via to make sure that we don't move it into the paid queue until the auth (third party system) goes through?

[richardpark-msft]

Looks great to me, btw. Thanks for writing this up, I look forward to demoing this with our libraries! :)

[hemanttanwar]

Transactions

Hm...perhaps we could do something in the workflow example, but this time receiving payments? So we do the send-via to make sure that we don't move it into the paid queue until the auth (third party system) goes through?

@richardpark-msft I removed transactions because, we are not presenting in API. Also I think we need to deep dive. But If team think it is important to add, I can come up with one scenario. Or we can just add one liner about it and say that we will cover in future API reviews.

[hemanttanwar]

What if receiver crashes before if complete the message, this message will be made available to other receiver for processing?

This isn't really worth mentioning - it's a property of every network-based system. Unless you're thinking we should provide some form of local durable storage?

This was raised few times by architect.. what happens to lock when system crashes ? So mentioning it here will answer those questions.

[hemanttanwar]

Regarding Management Scenario, I thought we aren't planning on covering the management scenarios for this review?

I added a line explaining , it is for reference and for completeness only, if they see that it could conflict with API we are suggesting, and not covered in this API review.

[KieranBrantnerMagee]

What if receiver crashes before if complete the message, this message will be made available to other receiver for processing?
This isn't really worth mentioning - it's a property of every network-based system. Unless you're thinking we should provide some form of local durable storage?

This was raised few times by architect.. what happens to lock when system crashes ? So mentioning it here will answer those questions.

It's funny this was already mentioned in part, since I was going to suggest _expanding_ these exception cases. Namely: (and excuse that this is a bit subtle/pedantic, the goal is to emphasize capturing the failure mode at message settlement as opposed to a hard crash or e.g. expecting the user to track this timeout)

• What if the receiver hangs/takes JUST long enough to not be able to renew before lock has expired and is claimed by another consumer?

[KieranBrantnerMagee]

Might this section at the bottom be left over from the issue template? (and can thus be removed)

Information Checklist
Kindly make sure that you have added all the following information above and checkoff the required fields otherwise we will treat the issuer as an incomplete report

Description Added

Expected solution specified

[JoshLove-msft]

Common use cases for filter : Security, Debugging etc

nit - can we say "Other common uses cases for filter". The example we give seems like a great application/business use case not related to security/debugging.

[JoshLove-msft]

Message 1 : Lot 10 is reserved for 4 hours starting at 2 PM , Session ID ="LOT-10"

nit - can we use "SPOT-10"? I think of "lot" as the entire parking lot consisting of multiple spots.

[JoshLove-msft]

Scenarios 5 : Receiver can receive messages in sequence

Could we dive into the "why" for using sessions here? We need FIFO which is only guaranteed when using sessions, since otherwise things would get messed up if we get the cancel message before the reserve message.
Also, this example highlights the typical use case for sessions where each session can be thought of as a sub-queue.

[JoshLove-msft]

Should we cover the "middleware" scenario where app doesn't know if they are dealing with queue or topic?

[JoshLove-msft]

I wonder if we should go into peek lock vs receive and delete for any of the scenarios. Receive and delete is great for when the system is okay with dropping the occasional message. It probably doesn't apply to the Parking Lot scenarios, but it would make sense for notifications based on some event that we don't need to guarantee delivery of.

[hemanttanwar]

I wonder if we should go into peek lock vs receive and delete for any of the scenarios. Receive and delete is great for when the system is okay with dropping the occasional message. It probably doesn't apply to the Parking Lot scenarios, but it would make sense for notifications based on some event that we don't need to guarantee delivery of.

@JoshLove-msft I think this is minor detail of Receive modes. Nothing much changes from client API point except specify Mode when creating Receiver. I worry about we going too deep in trenches in first API review . @jsquire What is your suggestion based on event hub initial API review. We already have seven scenario but I can definately add one for this.

[hemanttanwar]

Should we cover the "middleware" scenario where app doesn't know if they are dealing with queue or topic?

If I copy Scenario 1 and 2. And change picture with Queue -> Queue/Topic , all the text will remain same. So I am thinking to add separate scenario but not repeating same text and add few lines about this usecase.

[jsquire]

I wonder if we should go into peek lock vs receive and delete for any of the scenarios. Receive and delete is great for when the system is okay with dropping the occasional message. It probably doesn't apply to the Parking Lot scenarios, but it would make sense for notifications based on some event that we don't need to guarantee delivery of.

@JoshLove-msft I think this is minor detail of Receive modes. Nothing much changes from client API point except specify Mode when creating Receiver. I worry about we going too deep in trenches in first API review . @jsquire What is your suggestion based on event hub initial API review. We already have seven scenario but I can definately add one for this.

I see value in making mention of it at a high level. There is some focus on error scenarios and I think this helps to build the picture of having low-level mechanisms that enable developers to make choices that work best for their specific application scenarios. To your point, though, I wouldn't delve deeply unless there's an impact to the API. Remember, in general, the architects and other review attendees won't have actually read anything, but having it is a good reminder for those presenting to choose to include or leave out of the discussion depending on how it is flowing.

[jsquire]

Should we cover the "middleware" scenario where app doesn't know if they are dealing with queue or topic?

Personally, I'd reserve that unless it comes up in conversations around "specialized" cases. I don't know that this is a mainline scenario and probably impacts a very small segment of Service Bus customers.

[JoshLove-msft]

Should we cover the "middleware" scenario where app doesn't know if they are dealing with queue or topic?

Personally, I'd reserve that unless it comes up in conversations around "specialized" cases. I don't know that this is a mainline scenario and probably impacts a very small segment of Service Bus customers.

This topic was important in driving our decision to have two generic clients. Based on Service team feedback, this was a common scenario.

[jsquire]

Should we cover the "middleware" scenario where app doesn't know if they are dealing with queue or topic?

Personally, I'd reserve that unless it comes up in conversations around "specialized" cases. I don't know that this is a mainline scenario and probably impacts a very small segment of Service Bus customers.

This topic was important in driving our decision to have two generic clients. Based on Service team feedback, this was a common scenario.

Fair point on the client discussion. That said, I feel like "common" is being conflated with "high profile".

[hemanttanwar]

I wonder if we should go into peek lock vs receive and delete for any of the scenarios. Receive and delete is great for when the system is okay with dropping the occasional message. It probably doesn't apply to the Parking Lot scenarios, but it would make sense for notifications based on some event that we don't need to guarantee delivery of.

@JoshLove-msft I think this is minor detail of Receive modes. Nothing much changes from client API point except specify Mode when creating Receiver. I worry about we going too deep in trenches in first API review . @jsquire What is your suggestion based on event hub initial API review. We already have seven scenario but I can definately add one for this.

I see value in making mention of it at a high level. There is some focus on error scenarios and I think this helps to build the picture of having low-level mechanisms that enable developers to make choices that work best for their specific application scenarios. To your point, though, I wouldn't delve deeply unless there's an impact to the API. Remember, in general, the architects and other review attendees won't have actually read anything, but having it is a good reminder for those presenting to choose to include or leave out of the discussion depending on how it is flowing.

Added as part of scenario 2.