Coordinated Shutdown

GoAkt provides a mechanism to execute user-defined tasks during the shutdown of the actor system. One can use the option WithCoordinatedShutdown when creating the actor system.

Tasks are executed in the order they were registered. If a task fails, the shutdown process will continue uninterrupted. The actor system proceeds with its shutdown sequence, and any errors from the shutdown hooks will be reported at the end. In a future release, we may introduce an option to abort the shutdown entirely—triggering a panic—if any user-defined task fails.

Get Started

Before using the WithCoordinatedShutdown option one must implement the ShutdownHook interface:

type ShutdownHook interface {
    // Execute runs the shutdown logic for this hook.
    //
    // Parameters:
    //   - ctx:         The context for cancellation and deadlines.
    //   - actorSystem: The ActorSystem being shut down.
    //
    // Returns:
    //   - error: An error if the shutdown logic fails, or nil on success.
    Execute(ctx context.Context, actorSystem ActorSystem) error
    
    // Recovery returns the ShutdownHookRecovery configuration for this hook.
    //
    // This determines how failures are handled, including retry and recovery strategies.
    //
    // Returns:
    //   - *ShutdownHookRecovery: The recovery configuration for this hook.
    Recovery() *ShutdownHookRecovery
}

Recovery Strategies

Every ShutdownHook must define a recovery strategy that determines how to handle errors returned by its Execute method. The following strategies are available:

• ShouldFail: indicates that if a ShutdownHook fails, the shutdown process should immediately stop executing any remaining hooks.

• ShouldRetryAndFail: indicates that if a ShutdownHook fails, the system should retry executing the hook. The shutdown process will pause and repeatedly attempt the failed hook until it succeeds or a maximum retry limit is reached. If the hook still fails after all retries, the error is reported and no further hooks are executed.

• ShouldSkip: indicates that if a ShutdownHook fails, the error should be reported, but the shutdown process should skip the failed hook and continue executing the remaining hooks.

• ShouldRetryAndSkip: indicates that if a ShutdownHook fails, the system should retry executing the hook. The shutdown process will pause and repeatedly attempt the failed hook until it succeeds or a maximum retry limit is reached. If the hook still fails after all retries, the error is reported, but the shutdown process continues with the remaining hooks.

To define a recovery strategy for a ShutdownHook, use:

NewShutdownHookRecovery(opts ...RecoveryOption) *ShutdownHookRecovery

Pass the appropriate RecoveryOption to configure the desired behaviour.