suture

In Suture v4, services can return specific errors to control how the supervisor tree responds to a service failure:

• ErrDoNotRestart: Indicates the service should not be restarted, but other services in the tree should remain unaffected.
• ErrTerminateTree: Indicates the parent service tree should be terminated. Supervisor trees can be configured to either continue terminating upwards or terminate themselves without propagating the termination upwards.

Suture provides a default logger based on Go's slog package. This is located in a separate module to maintain compatibility with older Go versions in the main repository. To use it, you must explicitly add the dependency to your project:

go get github.com/thejerf/sutureslog

Suture provides Erlang-ish supervisor trees for Go to manage service lifecycles and handle failures gracefully. To use the current major version (v4), import the package using the following path:

import "github.com/thejerf/suture/v4"

The supervisor uses an exponential decay model to track failures.

1. When a failure occurs, the failure count increments by 1.
2. Every FailureDecay seconds, the failure count is reduced (cut in half) using an exponential function.
3. If the failure count exceeds FailureThreshold, the supervisor enters a paused state.
4. In the paused state, the supervisor waits for FailureBackoff (plus optional jitter) before resuming normal operation.
5. Upon resuming, the failure count is reset to zero.

A supervisor must be started before it can manage services. There are three ways to start a supervisor:

1. Serve(ctx context.Context): Runs the supervisor in the current goroutine. It blocks until the provided ctx is cancelled. This is typically called in the main function of a program.
2. ServeBackground(ctx context.Context): Starts the supervisor in a new goroutine and returns a one-buffered channel that receives the error returned by Serve. This is the recommended way to start a supervisor if you want to continue execution in the current goroutine.
3. Adding it to an existing Supervisor: If you add a Supervisor as a service to another supervisor, it will start when the parent starts.

Warning: Avoid manually running go supervisor.Serve() because it creates a race condition if you attempt to .Add() services immediately after.

Suture supervisors are safe to use in synctest bubbles. If you encounter a panic: deadlock: main bubble goroutine has exited but blocked goroutines remain, it typically means a service is not shutting down correctly when the supervisor stops.

To fix this:

1. Identify the blocked goroutine in the stack trace. Look for github.com/thejerf/suture/v4.(*Supervisor).stopSupervisor.
2. Locate the stack trace pointing to your specific service and the line where it is stuck.
3. Ensure your service is correctly monitoring and responding to the passed-in context.Context value to trigger a shutdown.

If you are working with legacy services that implement the DeprecatedService interface, you can wrap them to make them compatible with the modern Service interface using AsService.

AsService handles the lifecycle transition by:

1. Running the legacy Serve() method in a separate goroutine.
2. Monitoring the provided context.Context.
3. Automatically calling Stop() on the legacy service if the context is cancelled.
4. Returning nil if the service stops naturally, or the context error if the service is stopped via context cancellation.

To terminate a specific service managed by a supervisor, use the ServiceToken returned by Add().

• Remove(id ServiceToken): Attempts to stop the service. This method returns immediately without waiting for the service to actually terminate.
• RemoveAndWait(id ServiceToken, timeout time.Duration): Attempts to stop the service and waits up to the specified timeout.
  • Returns nil if the service terminated normally.
  • Returns ErrTimeout if the timeout expires or the supervisor terminates before the service stops.
  • Returns ErrWrongSupervisor if the token does not belong to this supervisor.

Note: A timeout of 0 in RemoveAndWait means it will wait forever.

Use Add(service Service) to register a service with a supervisor.

• If the supervisor is already running, the service starts immediately.
• If the supervisor is not yet running, the service will start when the supervisor's Serve method is called.
• If the service being added is itself a Supervisor (implements HasSupervisor), the child supervisor will automatically inherit the EventHook from the parent supervisor.

Returns a ServiceToken, which is an opaque identifier used to later remove or terminate that specific service.

A Supervisor manages the lifecycle of services (including other supervisors).

• Use New(name string, spec Spec) for full control over configuration, such as failure thresholds, backoff behavior, and event hooks.
• Use NewSimple(name string) for a supervisor with sensible default settings.

Default Configuration:

• FailureDecay: 30 seconds (exponential decay of failure count)
• FailureThreshold: 5 failures
• FailureBackoff: 15 seconds
• Timeout: 10 seconds
• BackoffJitter: DefaultJitter (uniform distribution in [d, 1.5*d))
• EventHook: Uses log.Print to log service starts, stops, failures, and panics.

When a supervisor is stopped, some services might fail to terminate within the configured Timeout.

UnstoppedServiceReport() returns a report of services that failed to stop. This call blocks until the supervisor has finished its shutdown process.

Warning: The returned data is subject to TOCTOU (Time-of-check to time-of-use) violations; a service in the report may have stopped by the time you inspect it. Use this information primarily for logging during program teardown.