feat(offline_first_with_rest): add request/response callbacks to the RestOfflineQueueClient

[jhb-dev]

This PR introduces two optional callbacks to the RestOfflineQueueClient, which closes https://github.com/GetDutchie/brick/issues/393.

1. onReattemptableResponse: This callback is invoked when a request returns a response with a status code listed in the reattemptForStatusCodes. It allows for detecting cases where a request is repeatedly rejected by the remote provider (e.g., when receiving an HTTP 409 (Conflict) response). When serial processing is enabled, this helps detect a blocked queue, allowing the app implementation to handle it appropriately.
2. onRequestError: This callback is triggered when a request throws an exception during execution (e.g., a SocketException). It helps identify the current state of the offline queue synchronization process.

In my application, these two callbacks are used to monitor the status of the offline queue, determining whether the queue is actively processing, blocked by a rejected request, or paused due to the client being offline. This allows me to provide users with real-time feedback on the system's sync status, which is important for my application.

@tshedor, what do you think of this implementation?

[jhb-dev]

Thanks for the feedback @tshedor, I'm currently on vacation and will respond to your feedback and update the PR next week.

[jhb-dev]

Sorry for the late response @tshedor! I had a very busy last week...

I have already addressed some of your feedback and will address the rest this evening.

This feature needs unit testing

Yes! I will add tests once we have agreed on an implementation.

There needs to be documentation

Same as with the tests.

[jhb-dev]

@tshedor, changed the implementation to only include the response status code instead of the http.StreamedResponse. Moreover, I added the callbacks to the GraphqlOfflineQueueLink.

The RestOfflineRequestQueueClient was never really meant to be exposed, and in the repositories where it's implemented, it isn't available on the Repository level. However, RestOfflineRequestQueue is exposed on the repository, so I'd recommend creating an abstract method on OfflineRequestQueue, and implement it in RestOfflineRequestQueue and forward it to RestOfflineRequestQueueClient.

OfflineRequestQueue has a generic type of TRequest that should provides the placeholder for the Request/http.Request. A second generic type of TResponse can be provided for Response/http.StreamedResponse on `OfflineRequestQueue.

I'm in favor of creating the generic methods in the OfflineRequestQueue and implementing them in the RestOfflineRequestQueue and GraphqlOfflineRequestQueue, but how to pass them to the RestOfflineQueueClient and GraphqlOfflineQueueLink?

[tshedor]

@devj3ns I've taken a pass through the code. You're right that adding an abstract to OfflineRequestQueue is not feasible - the flow from queue -> client -> queue doesn't make much sense. RequestManager is the next most likely candidate since it's known to Link and Client, but that's an abuse of its core purpose (convert to and from SQLite). So let's move forward with this design.

After tests and documentation, I think this is good to go.

[jhb-dev]

@tshedor I’ve added a new section to the documentation that covers this feature.

For the unit tests, I included some to cover the RestOfflineQueueClient callbacks. However, I wasn’t able to make a failing request with GraphqlOfflineQueueLink since I don’t have experience with this part of the package. Could you help out here?

[jhb-dev]

Regarding the naming, I would propose the following, more precise names:

• onReattemptableRequestFailure (instead of onReattemptableResponse)
• onRequestException (instead of onRequestError)

[tshedor]

@devj3ns Added some GraphQL tests. It's been a minute since I've been in GraphQL, so I also changed the method signature slightly (GraphQL is sort of REST in a costume, but it doesn't natively support status codes as it turns out).

onRequestException

Sounds great

onReattemptableRequestFailure

What about just onReattempt? The Request part feels redundant since it's already in a RequestQueue constructor, and the Failure part could be confusing given the onRequestException argument. It might just be better to stay simple?

Lastly, do you want to add a quick CHANGELOG note? I added a header and the version numbers in 3330270

[jhb-dev]

@tshedor okay, good to know. I have added the changelog and renamed both functions.

I'm glad that this is now complete! :)