Concerns over enforced async APIs

[daniel-smith]

Hi team,

Firstly, thank you for maintaining Stateless - it’s been my go-to library for building reliable state machines in C# for years.

I wanted to share a concern about PR #618. I was surprised to see PermittedTriggers marked as obsolete, as it now seems Stateless enforces async introspection of permitted triggers even when no async triggers are used.

That makes sense when async triggers are present, but it feels unnecessarily restrictive for purely synchronous workflows.

I also see that ToString blocks on a call to GetPermittedTriggersAsync, which, in my view, is a bit of a code smell.

Many of us use Stateless within domain models to enforce workflow rules. In these designs, it’s common to keep domain logic synchronous and leave async operations to higher layers. Having to introduce blocking workarounds (e.g. via GetAwaiter()) feels awkward in that context.

I really appreciate the effort to support async scenarios - that’s a great feature. It would just be great if the async behaviour could remain completely opt-in without leaking into synchronous use cases. I appreciate I haven't been in the weeds on this project and may not see all of the constraints, but I wonder if a cleaner design might have been to introduce a separate type such as AsyncStateMachine, keeping StateMachine fully synchronous while offering an async variant for those workflows. Just a thought.

Thanks again for all your work on this project!

[adanbrownpaca]

100% in agreement.

[mclift]

Thanks for taking the time to raise this issue. I'm sure you've seen the discussion in #618 around removing vs deprecating the synchronous implementations. I agree that it's not optimal to force async calls if you're not using any asynchronous features.

IIRC the contributor's intention was to address duplicated code in the synchronous and asynchronous implementations. Perhaps a way forward would be to:

• restore the synchronous implementation of GetPermittedTriggers
• track when any asynchronous triggers are configured using a boolean or a counter
• if any have been configured, have GetPermittedTriggers invoke GetPermittedTriggersAsync with Task.Run

It's just one idea, but perhaps something like this would avoid making unnecessary async calls while ensuring PermittedTriggers is capable of returning asynchronous triggers and providing a good reason to un-deprecate the sychronous method and property.

Thoughts?

[daniel-smith]

Thanks for the reply @mclift. I agree that avoiding the async path entirely when no async features are configured sounds like a good compromise. Exactly how best to achieve this probably needs a bit of thought. Some initial thoughts:

• Tracking whether any async triggers have been configured (e.g. via a bool flag) seems like a reasonable first step.
• The remaining question is what the behaviour of the synchronous GetPermittedTriggers should be once async triggers are present:
  • Blocking on an async call (e.g. via Task.Run or GetAwaiter().GetResult()) feels undesirable, as it introduces hidden blocking.
  • Throwing an explicit exception may be a better option, making the contract clear that async configuration requires async introspection, even if the failure is only detected at runtime. Given the original direction here was to obsolete (and eventually remove) the synchronous API, keeping it for the sync-only case, but throwing once async triggers are opted into, feels like a reasonable compromise. It preserves compatibility for existing synchronous workflows while making the async boundary explicit.
  • If going with the exception approach, I’d suggest that GetPermittedTriggersAsync should be safe to call regardless of whether any async triggers are configured, providing a consistent API for consumers who prefer that. In cases where no async configuration is present, the method can complete synchronously. Returning a ValueTask could considered, though probably not critical for this library.
• ToString in particular should never block on async work. If async triggers are configured, it could include an additional note indicating presence of async triggers (wording TBD), with the detailed information available via another async method.