Improvement to the API for the creation of policies

[sxleixer]

Is your feature request related to a specific problem? Or an existing feature? Please describe.
No.

Describe your proposed or preferred solution:
First of all, I am really pleased by the Polly project and the improvement I suggest would make it a bit more fun to use.

As we can observe, there is an exponential growth in the Policy extension methods. That is, because every argument is paired with virtually every other argument. I found it hard to choose a valid series of arguments, since there are so many of them and I always wanted to max out the information I can take out of the system. However, in most cases they boil down to a single base-case.

So, how to improve. I would suggest to use a more composition-based approach using the Bridge pattern (see Bridge Pattern - Source Making) and separate the configuration of the Policies from the policies itself. Thus the configuration may be re-usable in differenct places. The more, I would pack the callback functions (e.g. OnRetry) into interfaces, such that the implementor has full control over the callbacks and even may exchange them during the program if they want to. To mimic the current semantic I would suggest an implementation of the interface with all the possible delegates to pass to the constructor of this implementation. By this, we achieve more flexibility for the user because the arguments may vary indepently, more clarity on how to use the API as well as more simplicity, since the independent variation of the arguments. Furthermore we introduce new abilities, by being able to decorate the calls with for example a logger or other useful comodities.

It also solves the exponential growth of the fluent-API and reduces boilerplate at the user. It also keeps the user-experience for current users.

One more idea, the current fluent-API gets deprecated and moved to another package, the deprecation message informs the user to use the separate package instead to keep the known API. In some future major release, one may drop the support for the current fluent-API.

Describe any alternative options you've considered:
Keep it as it is.

Any additional info?
I will create a PR with an example.

[sxleixer]

The "breaking change" part is not true this can be introduced without a breaking change.

[martincostello]

Thanks for opening this issue and providing an example PR, which I've left some comments on.

I added the "breaking change" label based on the fact that such a significant change of this type would be part of a future release where we did indeed making breaking changes.

As it stands, I don't think this is something we should consider adding to version 7 as it would increase the complexity of the code base, which is already something we'd like to tackle, as adding new overloads as already become difficult due to the number of different methods/parameters each policy now has to configure them.

This is good food for thought for a future version 8, whenever that might be. The primary maintainer had to take a step back from open source quite some time ago to focus on other things, so Polly's been very much in maintenance mode since the middle of 2020.

If the community at large can come up with some solid proposals for evolution of Polly for a new major release then that's something we could start to shepherd through to move forward if there's a compelling case to do so.

From a personal perspective, while the primary maintainer is away, I'd be reticent to make any big design changes to Polly without being able to consult them.

[joelhulen]

We will make an announcement soon about our plans for v8, which, among other things like massive performance improvements, proposes to simplify how we both author and call policies by moving away from tons of overloaded methods. We will also strive to make the changes compatible with existing policies and provide a way to migrate from the current APIs to the new ones. Community suggestions like yours are crucial to improving the overall design, capabilities, and user experience, which is why we will announce our plans and ask for reactions from the community. Thank you!

[martincostello]

We have recently published the first alpha of the new Polly v8 API. Please take a look and see if it resolves any of the issues you mention in this topic.

We are not planning on changing the existing Polly API surface, with new functionality and patterns instead being actively considered for the new Polly.Core API surface.