package suture // FIXMES in progress: // 1. Ensure the supervisor actually gets to the terminated state for the // unstopped service report. // 2. Save the unstopped service report in the supervisor. import ( "context" "errors" "fmt" "log" "math" "math/rand" "runtime" "sync" "sync/atomic" "time" ) const ( notRunning = iota normal paused terminated ) type supervisorID uint32 type serviceID uint32 // ErrSupervisorNotRunning is returned by some methods if the supervisor is // not running, either because it has not been started or because it has // been terminated. var ErrSupervisorNotRunning = errors.New("supervisor not running") /* Supervisor is the core type of the module that represents a Supervisor. Supervisors should be constructed either by New or NewSimple. Once constructed, a Supervisor should be started in one of three ways: 1. Calling .Serve(ctx). 2. Calling .ServeBackground(ctx). 3. Adding it to an existing Supervisor. Calling Serve will cause the supervisor to run until the passed-in context is cancelled. Often one of the last lines of the "main" func for a program will be to call one of the Serve methods. Calling ServeBackground will CORRECTLY start the supervisor running in a new goroutine. It is risky to directly run go supervisor.Serve() because that will briefly create a race condition as it starts up, if you try to .Add() services immediately afterward. */ type Supervisor struct { Name string spec Spec services map[serviceID]serviceWithName cancellations map[serviceID]context.CancelFunc servicesShuttingDown map[serviceID]serviceWithName lastFail time.Time failures float64 restartQueue []serviceID serviceCounter serviceID control chan supervisorMessage notifyServiceDone chan serviceID resumeTimer <-chan time.Time liveness chan struct{} // despite the recommendation in the context package to avoid // holding this in a struct, I think due to the function of suture // and the way it works, I think it's OK in this case. This is the // exceptional case, basically. ctxMutex sync.Mutex ctx context.Context // This function cancels this supervisor specifically. ctxCancel func() getNow func() time.Time getAfterChan func(time.Duration) <-chan time.Time m sync.Mutex // The unstopped service report is generated when we finish // stopping. unstoppedServiceReport UnstoppedServiceReport // malign leftovers id supervisorID state uint8 } /* New is the full constructor function for a supervisor. The name is a friendly human name for the supervisor, used in logging. Suture does not care if this is unique, but it is good for your sanity if it is. If not set, the following values are used: - EventHook: A function is created that uses log.Print. - FailureDecay: 30 seconds - FailureThreshold: 5 failures - FailureBackoff: 15 seconds - Timeout: 10 seconds - BackoffJitter: DefaultJitter The EventHook function will be called when errors occur. Suture will log the following: - When a service has failed, with a descriptive message about the current backoff status, and whether it was immediately restarted - When the supervisor has gone into its backoff mode, and when it exits it - When a service fails to stop A default hook for slog is provided with the [sutureslog module](https://github.com/thejerf/sutureslog). The failureRate, failureThreshold, and failureBackoff controls how failures are handled, in order to avoid the supervisor failure case where the program does nothing but restarting failed services. If you do not care how failures behave, the default values should be fine for the vast majority of services, but if you want the details: The supervisor tracks the number of failures that have occurred, with an exponential decay on the count. Every FailureDecay seconds, the number of failures that have occurred is cut in half. (This is done smoothly with an exponential function.) When a failure occurs, the number of failures is incremented by one. When the number of failures passes the FailureThreshold, the entire service waits for FailureBackoff seconds before attempting any further restarts, at which point it resets its failure count to zero. Timeout is how long Suture will wait for a service to properly terminate. The PassThroughPanics options can be set to let panics in services propagate and crash the program, should this be desirable. DontPropagateTermination indicates whether this supervisor tree will propagate a ErrTerminateTree if a child process returns it. If false, this supervisor will itself return an error that will terminate its parent. If true, it will merely return ErrDoNotRestart. false by default. */ func New(name string, spec Spec) *Supervisor { spec.configureDefaults(name) return &Supervisor{ name, spec, // services make(map[serviceID]serviceWithName), // cancellations make(map[serviceID]context.CancelFunc), // servicesShuttingDown make(map[serviceID]serviceWithName), // lastFail, deliberately the zero time time.Time{}, // failures 0, // restartQueue make([]serviceID, 0, 1), // serviceCounter 0, // control make(chan supervisorMessage), // notifyServiceDone make(chan serviceID), // resumeTimer make(chan time.Time), // liveness make(chan struct{}), sync.Mutex{}, // ctx nil, // myCancel nil, // the tests can override these for testing threshold // behavior // getNow time.Now, // getAfterChan time.After, // m sync.Mutex{}, // unstoppedServiceReport nil, // id nextSupervisorID(), // state notRunning, } } func serviceName(service Service) (serviceName string) { stringer, canStringer := service.(fmt.Stringer) if canStringer { serviceName = stringer.String() } else { serviceName = fmt.Sprintf("%#v", service) } return } // NewSimple is a convenience function to create a service with just a name // and the sensible defaults. func NewSimple(name string) *Supervisor { return New(name, Spec{}) } // HasSupervisor is an interface that indicates the given struct contains a // supervisor. If the struct is either already a *Supervisor, or it embeds // a *Supervisor, this will already be implemented for you. Otherwise, a // struct containing a supervisor will need to implement this in order to // participate in the log function propagation and recursive // UnstoppedService report. // // It is legal for GetSupervisor to return nil, in which case // the supervisor-specific behaviors will simply be ignored. type HasSupervisor interface { GetSupervisor() *Supervisor } func (s *Supervisor) GetSupervisor() *Supervisor { return s } /* Add adds a service to this supervisor. If the supervisor is currently running, the service will be started immediately. If the supervisor has not been started yet, the service will be started when the supervisor is. If the supervisor was already stopped, this is a no-op returning an empty service-token. The returned ServiceID may be passed to the Remove method of the Supervisor to terminate the service. As a special behavior, if the service added is itself a supervisor, the supervisor being added will copy the EventHook function from the Supervisor it is being added to. This allows factoring out providing a Supervisor from its logging. This unconditionally overwrites the child Supervisor's logging functions. */ func (s *Supervisor) Add(service Service) ServiceToken { if s == nil { panic("can't add service to nil *suture.Supervisor") } if hasSupervisor, isHaveSupervisor := service.(HasSupervisor); isHaveSupervisor { supervisor := hasSupervisor.GetSupervisor() if supervisor != nil { supervisor.spec.EventHook = s.spec.EventHook } } s.m.Lock() if s.state == notRunning { id := s.serviceCounter s.serviceCounter++ s.services[id] = serviceWithName{service, serviceName(service)} s.restartQueue = append(s.restartQueue, id) s.m.Unlock() return ServiceToken{supervisor: s.id, service: id} } s.m.Unlock() response := make(chan serviceID) if s.sendControl(addService{service, serviceName(service), response}) != nil { return ServiceToken{} } return ServiceToken{supervisor: s.id, service: <-response} } // ServeBackground starts running a supervisor in its own goroutine. When // this method returns, the supervisor is guaranteed to be in a running state. // The returned one-buffered channel receives the error returned by .Serve. func (s *Supervisor) ServeBackground(ctx context.Context) <-chan error { errChan := make(chan error, 1) go func() { errChan <- s.Serve(ctx) }() s.sync() return errChan } /* Serve starts the supervisor. You should call this on the top-level supervisor, but nothing else. */ func (s *Supervisor) Serve(ctx context.Context) error { // context documentation suggests that it is legal for functions to // take nil contexts, it's user's responsibility to never pass them in. if ctx == nil { ctx = context.Background() } if s == nil { panic("Can't serve with a nil *suture.Supervisor") } // Take a separate cancellation function so this tree can be // indepedently cancelled. ctx, myCancel := context.WithCancel(ctx) s.ctxMutex.Lock() s.ctx = ctx s.ctxMutex.Unlock() s.ctxCancel = myCancel if s.id == 0 { panic("Can't call Serve on an incorrectly-constructed *suture.Supervisor") } s.m.Lock() if s.state == normal || s.state == paused { s.m.Unlock() panic("Called .Serve() on a supervisor that is already Serve()ing") } s.state = normal s.m.Unlock() defer func() { s.m.Lock() s.state = terminated s.m.Unlock() }() // for all the services I currently know about, start them for _, id := range s.restartQueue { namedService, present := s.services[id] if present { s.runService(ctx, namedService.Service, id) } } s.restartQueue = make([]serviceID, 0, 1) for { select { case <-ctx.Done(): s.stopSupervisor() return ctx.Err() case m := <-s.control: switch msg := m.(type) { case serviceFailed: s.handleFailedService(ctx, msg.id, msg.panicVal, msg.stacktrace, true) case serviceEnded: _, monitored := s.services[msg.id] if monitored { cancel := s.cancellations[msg.id] if isErr(msg.err, ErrDoNotRestart) || ctx.Err() != nil { delete(s.services, msg.id) delete(s.cancellations, msg.id) go cancel() } else if isErr(msg.err, ErrTerminateSupervisorTree) { s.stopSupervisor() if s.spec.DontPropagateTermination { return ErrDoNotRestart } else { return msg.err } } else { err := msg.err if isErr(msg.err, context.DeadlineExceeded) || isErr(msg.err, context.Canceled) { err = fmt.Errorf("from some other context, not the service's context, so service is being restarted: %w", msg.err) } s.handleFailedService(ctx, msg.id, err, nil, false) } } case addService: id := s.serviceCounter s.serviceCounter++ s.services[id] = serviceWithName{msg.service, msg.name} s.runService(ctx, msg.service, id) msg.response <- id case removeService: s.removeService(msg.id, msg.notification) case stopSupervisor: msg.done <- s.stopSupervisor() return nil case listServices: services := []Service{} for _, service := range s.services { services = append(services, service.Service) } msg.c <- services case syncSupervisor: // this does nothing on purpose; its sole purpose is to // introduce a sync point via the channel receive case panicSupervisor: // used only by tests panic("Panicking as requested!") } case serviceEnded := <-s.notifyServiceDone: delete(s.servicesShuttingDown, serviceEnded) case <-s.resumeTimer: // We're resuming normal operation after a pause due to // excessive thrashing // FIXME: Ought to permit some spacing of these functions, rather // than simply hammering through them s.m.Lock() s.state = normal s.m.Unlock() s.failures = 0 s.spec.EventHook(EventResume{s, s.Name}) for _, id := range s.restartQueue { namedService, present := s.services[id] if present { s.runService(ctx, namedService.Service, id) } } s.restartQueue = make([]serviceID, 0, 1) } } } // UnstoppedServiceReport will return a report of what services failed to // stop when the supervisor was stopped. This call will return when the // supervisor is done shutting down. It will hang on a supervisor that has // not been stopped, because it will not be "done shutting down". // // Calling this on a supervisor will return a report for the whole // supervisor tree under it. // // WARNING: Technically, any use of the returned data structure is a // TOCTOU violation: // https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use // Since the data structure was generated and returned to you, any of these // services may have stopped since then. // // However, this can still be useful information at program teardown // time. For instance, logging that a service failed to stop as expected is // still useful, as even if it shuts down later, it was still later than // you expected. // // But if you cast the Service objects back to their underlying objects and // start trying to manipulate them ("shut down harder!"), be sure to // account for the possibility they are in fact shut down before you get // them. // // If there are no services to report, the UnstoppedServiceReport will be // nil. A zero-length constructed slice is never returned. func (s *Supervisor) UnstoppedServiceReport() (UnstoppedServiceReport, error) { // the only thing that ever happens to this channel is getting // closed when the supervisor terminates. _, _ = <-s.liveness // FIXME: Recurse on the supervisors return s.unstoppedServiceReport, nil } func (s *Supervisor) handleFailedService(ctx context.Context, id serviceID, err interface{}, stacktrace []byte, panic bool) { now := s.getNow() if s.lastFail.IsZero() { s.lastFail = now s.failures = 1.0 } else { sinceLastFail := now.Sub(s.lastFail).Seconds() intervals := sinceLastFail / s.spec.FailureDecay s.failures = s.failures*math.Pow(.5, intervals) + 1 } if s.failures > s.spec.FailureThreshold { s.m.Lock() s.state = paused s.m.Unlock() s.spec.EventHook(EventBackoff{s, s.Name}) s.resumeTimer = s.getAfterChan( s.spec.BackoffJitter.Jitter(s.spec.FailureBackoff)) } s.lastFail = now failedService, monitored := s.services[id] // It is possible for a service to be no longer monitored // by the time we get here. In that case, just ignore it. if monitored { s.m.Lock() curState := s.state s.m.Unlock() if curState == normal { s.runService(ctx, failedService.Service, id) } else { s.restartQueue = append(s.restartQueue, id) } if panic { s.spec.EventHook(EventServicePanic{ Supervisor: s, SupervisorName: s.Name, Service: failedService.Service, ServiceName: failedService.name, CurrentFailures: s.failures, FailureThreshold: s.spec.FailureThreshold, Restarting: curState == normal, PanicMsg: s.spec.Sprint(err), Stacktrace: string(stacktrace), }) } else { e := EventServiceTerminate{ Supervisor: s, SupervisorName: s.Name, Service: failedService.Service, ServiceName: failedService.name, CurrentFailures: s.failures, FailureThreshold: s.spec.FailureThreshold, Restarting: curState == normal, } if err != nil { e.Err = err } s.spec.EventHook(e) } } } func (s *Supervisor) runService(ctx context.Context, service Service, id serviceID) { childCtx, cancel := context.WithCancel(ctx) done := make(chan struct{}) blockingCancellation := func() { cancel() <-done } s.cancellations[id] = blockingCancellation go func() { if !s.spec.PassThroughPanics { defer func() { if r := recover(); r != nil { buf := make([]byte, 65535) written := runtime.Stack(buf, false) buf = buf[:written] s.fail(id, r, buf) } }() } var err error defer func() { cancel() close(done) r := recover() if r == nil { s.serviceEnded(id, err) } else { panic(r) } }() err = service.Serve(childCtx) }() } func (s *Supervisor) removeService(id serviceID, notificationChan chan struct{}) { namedService, present := s.services[id] if present { cancel := s.cancellations[id] delete(s.services, id) delete(s.cancellations, id) s.servicesShuttingDown[id] = namedService go func() { successChan := make(chan struct{}) go func() { cancel() close(successChan) if notificationChan != nil { notificationChan <- struct{}{} } }() select { case <-successChan: // Life is good! case <-s.getAfterChan(s.spec.Timeout): s.spec.EventHook(EventStopTimeout{ s, s.Name, namedService.Service, namedService.name}) } s.notifyServiceDone <- id }() } else { if notificationChan != nil { notificationChan <- struct{}{} } } } func (s *Supervisor) stopSupervisor() UnstoppedServiceReport { notifyDone := make(chan serviceID, len(s.services)) for id, namedService := range s.services { cancel := s.cancellations[id] delete(s.services, id) delete(s.cancellations, id) s.servicesShuttingDown[id] = namedService go func(sID serviceID) { cancel() notifyDone <- sID }(id) } timeout := s.getAfterChan(s.spec.Timeout) SHUTTING_DOWN_SERVICES: for len(s.servicesShuttingDown) > 0 { select { case id := <-notifyDone: delete(s.servicesShuttingDown, id) case serviceID := <-s.notifyServiceDone: delete(s.servicesShuttingDown, serviceID) case <-timeout: for _, namedService := range s.servicesShuttingDown { s.spec.EventHook(EventStopTimeout{ s, s.Name, namedService.Service, namedService.name, }) } // failed remove statements will log the errors. break SHUTTING_DOWN_SERVICES } } // If nothing else has cancelled our context, we should now. s.ctxCancel() // Indicate that we're done shutting down defer close(s.liveness) if len(s.servicesShuttingDown) == 0 { return nil } else { report := UnstoppedServiceReport{} for serviceID, serviceWithName := range s.servicesShuttingDown { report = append(report, UnstoppedService{ SupervisorPath: []*Supervisor{s}, Service: serviceWithName.Service, Name: serviceWithName.name, ServiceToken: ServiceToken{supervisor: s.id, service: serviceID}, }) } s.m.Lock() s.unstoppedServiceReport = report s.m.Unlock() return report } } // String implements the fmt.Stringer interface. func (s *Supervisor) String() string { return s.Name } // sendControl abstracts checking for the supervisor to still be running // when we send a message. This prevents blocking when sending to a // cancelled supervisor. func (s *Supervisor) sendControl(sm supervisorMessage) error { var doneChan <-chan struct{} s.ctxMutex.Lock() if s.ctx == nil { s.ctxMutex.Unlock() return ErrSupervisorNotStarted } doneChan = s.ctx.Done() s.ctxMutex.Unlock() select { case s.control <- sm: return nil case <-doneChan: return ErrSupervisorNotRunning } } /* Remove will remove the given service from the Supervisor, and attempt to Stop() it. The ServiceID token comes from the Add() call. This returns without waiting for the service to stop. */ func (s *Supervisor) Remove(id ServiceToken) error { if id.supervisor != s.id { return ErrWrongSupervisor } err := s.sendControl(removeService{id.service, nil}) if err == ErrSupervisorNotRunning { // No meaningful error handling if the supervisor is stopped. return nil } return err } /* RemoveAndWait will remove the given service from the Supervisor and attempt to Stop() it. It will wait up to the given timeout value for the service to terminate. A timeout value of 0 means to wait forever. If a nil error is returned from this function, then the service was terminated normally. If either the supervisor terminates or the timeout passes, ErrTimeout is returned. (If this isn't even the right supervisor ErrWrongSupervisor is returned.) */ func (s *Supervisor) RemoveAndWait(id ServiceToken, timeout time.Duration) error { if id.supervisor != s.id { return ErrWrongSupervisor } var timeoutC <-chan time.Time if timeout > 0 { timer := time.NewTimer(timeout) defer timer.Stop() timeoutC = timer.C } notificationC := make(chan struct{}) sentControlErr := s.sendControl(removeService{id.service, notificationC}) if sentControlErr != nil { return sentControlErr } select { case <-notificationC: // normal case; the service is terminated. return nil // This occurs if the entire supervisor ends without the service // having terminated, and includes the timeout the supervisor // itself waited before closing the liveness channel. case <-s.ctx.Done(): return ErrTimeout // The local timeout. case <-timeoutC: return ErrTimeout } } /* Services returns a []Service containing a snapshot of the services this Supervisor is managing. */ func (s *Supervisor) Services() []Service { ls := listServices{make(chan []Service)} if s.sendControl(ls) == nil { return <-ls.c } return nil } var currentSupervisorID uint32 func nextSupervisorID() supervisorID { return supervisorID(atomic.AddUint32(¤tSupervisorID, 1)) } // ServiceToken is an opaque identifier that can be used to terminate a service that // has been Add()ed to a Supervisor. type ServiceToken struct { supervisor supervisorID service serviceID } // An UnstoppedService is the component member of an // UnstoppedServiceReport. // // The SupervisorPath is the path down the supervisor tree to the given // service. type UnstoppedService struct { SupervisorPath []*Supervisor Service Service Name string ServiceToken ServiceToken } // An UnstoppedServiceReport will be returned by StopWithReport, reporting // which services failed to stop. type UnstoppedServiceReport []UnstoppedService type serviceWithName struct { Service Service name string } // Jitter returns the sum of the input duration and a random jitter. It is // compatible with the jitter functions in github.com/lthibault/jitterbug. type Jitter interface { Jitter(time.Duration) time.Duration } // NoJitter does not apply any jitter to the input duration type NoJitter struct{} // Jitter leaves the input duration d unchanged. func (NoJitter) Jitter(d time.Duration) time.Duration { return d } // DefaultJitter is the jitter function that is applied when spec.BackoffJitter // is set to nil. type DefaultJitter struct { rand *rand.Rand } // Jitter will jitter the backoff time by uniformly distributing it into // the range [FailureBackoff, 1.5 * FailureBackoff). func (dj *DefaultJitter) Jitter(d time.Duration) time.Duration { // this is only called by the core supervisor loop, so it is // single-thread safe. if dj.rand == nil { dj.rand = rand.New(rand.NewSource(time.Now().UnixNano())) } jitter := dj.rand.Float64() / 2 return d + time.Duration(float64(d)*jitter) } // ErrWrongSupervisor is returned by the (*Supervisor).Remove method // if you pass a ServiceToken from the wrong Supervisor. var ErrWrongSupervisor = errors.New("wrong supervisor for this service token, no service removed") // ErrTimeout is returned when an attempt to RemoveAndWait for a service to // stop has timed out. var ErrTimeout = errors.New("waiting for service to stop has timed out") // ErrSupervisorNotTerminated is returned when asking for a stopped service // report before the supervisor has been terminated. var ErrSupervisorNotTerminated = errors.New("supervisor not terminated") // ErrSupervisorNotStarted is returned if you try to send control messages // to a supervisor that has not started yet. See note on Supervisor struct // about the legal ways to start a supervisor. var ErrSupervisorNotStarted = errors.New("supervisor not started yet") // Spec is used to pass arguments to the New function to create a // supervisor. See the New function for full documentation. type Spec struct { EventHook EventHook Sprint SprintFunc FailureDecay float64 FailureThreshold float64 FailureBackoff time.Duration BackoffJitter Jitter Timeout time.Duration PassThroughPanics bool DontPropagateTermination bool } func (s *Spec) configureDefaults(supervisorName string) { if s.FailureDecay == 0 { s.FailureDecay = 30 } if s.FailureThreshold == 0 { s.FailureThreshold = 5 } if s.FailureBackoff == 0 { s.FailureBackoff = time.Second * 15 } if s.BackoffJitter == nil { s.BackoffJitter = &DefaultJitter{} } if s.Timeout == 0 { s.Timeout = time.Second * 10 } // set up the default logging handlers if s.EventHook == nil { s.EventHook = func(e Event) { log.Print(e) } } if s.Sprint == nil { s.Sprint = func(v interface{}) string { return fmt.Sprintf("%v", v) } } }