Allow getting receipt from StompSession.Subscription.unsubscribe()

[Songdoeon]

Motivation

Currently Subscription.unsubscribe() is a void method, so clients have no way to know when an UNSUBSCRIBE frame has actually been processed by the server. This PR brings unsubscribe() in line with send() and acknowledge() by returning a Receiptable that callers can use to register callbacks and track the receipt.

Summary of Changes

• Interface

  • StompSession.Subscription — both unsubscribe() overloads now return Receiptable instead of void.

• Implementation

  • DefaultStompSession.unsubscribe(String, StompHeaders) (private helper) now returns a Receiptable by creating a ReceiptHandler after adding a receipt-id header.
  • DefaultStompSession.DefaultSubscription.unsubscribe(...) now invokes the helper and simply returns its Receiptable.

• Tests (in DefaultStompSessionTests)

  • unsubscribeWithReceipt()
    Verifies that calling unsubscribe() returns a non‑null Receiptable and that the sent frame still only contains the subscription ID when auto‑receipt is off.
  • unsubscribeWithCustomHeaderAndReceipt()
    Verifies that with autoReceipt=true and custom headers, the UNSUBSCRIBE frame contains the subscription ID, the custom header, and the generated receipt header, and that the returned Receiptable holds the same receipt-id.
  • receiptReceivedOnUnsubscribe()
    Verifies that if a RECEIPT frame arrives for the receipt-id, a task registered on the returned Receiptable is executed.

All existing tests pass, and the new tests cover the added behavior.

Closes gh-22729

[rstoyanchev]

It seems reasonable to make this possible, but it could be an overloaded method, e.g. unsubsribeWithReceipt to make it optional to get a receipt.

[xak2000]

Hey, @rstoyanchev

It seems reasonable to make this possible, but it could be an overloaded method, e.g. unsubsribeWithReceipt to make it optional to get a receipt.

What is the motivation for adding a new method instead of using the existing unsubscribe?

I think using the existing method makes more sense because it will align with other methods (subscribe, send, acknowledge). All of them always return Receiptable even when setAutoReceipt is disabled or custom header do not contain the receipt-requesting header. We do not use subscribeWithRecepit or sendWithReceipt here, right?

Also, according to the setAutoReceipt docs subscribe and send automatically adds a receipt header if setAutoReceipt is enabled.

spring-framework/spring-messaging/src/main/java/org/springframework/messaging/simp/stomp/StompSession.java

Lines 42 to 51 in 39760ed

	/**
	* When enabled, a receipt header is automatically added to future
	* {@code send} and {@code subscribe} operations on this session, which
	* causes the server to return a RECEIPT. An application can then use
	* the {@link StompSession.Receiptable Receiptable} returned from the
	* operation to track the receipt.
	* <p>A receipt header can also be added manually through the overloaded
	* methods that accept {@code StompHeaders}.
	*/
	void setAutoReceipt(boolean enabled);

And I see the implementation in this PR uses the same logic: unsubscribe will automatically add a receipt header if setAutoReceipt is enabled.

Considering all of this I think it doesn't make sense to introduce a new overloaded method such as unsubsribeWithReceipt to make it optional to get a receipt. All other methods already return Receiptable and it is already optional for the caller to use the returned value or ignore it. Especially if setAutoReceipt is disabled and no receipt was sent in custom headers: in this case the returned Receiptable will not actually handle any recepits.

But I think the javadoc for setAutoReceipt could be improved. Currently the docs mention only send and subscribe methods, while in reality this flag also affects acknowledge and now will affect Subscription.unsubscribe.

[Songdoeon]

Thanks for the review!

I see two viable options here:

A) keep the current change where both unsubscribe() overloads return Receiptable for consistency with send, subscribe, and acknowledge; callers can still ignore the return value,
B) keep the existing unsubscribe() as-is and add a new unsubscribeWithReceipt() to preserve binary compatibility and avoid public API signature changes.

I initially went with A to keep the API symmetric with the other operations that already return Receiptable. In practice, applications don’t implement StompSession.Subscription and obtain it from the framework, so the impact should be limited. However, given Spring’s emphasis on strong backward compatibility in its public APIs , I’m happy to switch to B if you’d prefer the additive, non-breaking approach.

[rstoyanchev]

Thanks for the feedback. I agree we should change the existing unsubscribe method, which breaks binary compatibility but we can do that for the upcoming 7.0 release. My main thought was to not trigger sending receipts where not needed, but the autoReceipt setting and the receipt id in headers provide full control.