[shepherd] 01/02: service: Add 'default-respawn-limit'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 286259b02549b93b782c358642be4322af7cc84f
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Sat May 27 22:29:55 2023 +0200

    service: Add 'default-respawn-limit'.
    
    * modules/shepherd/service.scm (respawn-limit): Remove.
    (default-respawn-limit): New variable.
    (respawn-service): Honor it.
    * doc/shepherd.texi (Defining Services): Mention it.
    (Service De- and Constructors): Document it.
    * NEWS: Update.
---
 NEWS                         |  5 +++++
 doc/shepherd.texi            | 30 ++++++++++++++++++++++++++++++
 modules/shepherd/service.scm | 19 ++++++++++++-------
 3 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/NEWS b/NEWS
index 54df05c..04bba81 100644
--- a/NEWS
+++ b/NEWS
@@ -18,6 +18,11 @@ Please send Shepherd bug reports to bug-guix@gnu.org.
 The ‘endpoint’ procedure takes a new ‘#:bind-attempts’ parameter.  Its default
 value is (default-bind-attempts), itself a new SRFI-39 parameter.
 
+** New ‘default-respawn-limit’ parameter
+
+This SRFI-39 parameter lets users configure the respawn limit for respawnable
+services.  See “Service De- and Constructors” in the manual.
+
 ** ‘herd restart SERVICE’ starts the replacement, not the original service
    <https://issues.guix.gnu.org/63717>
 
diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 0f46eb3..ec7c18d 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -705,6 +705,11 @@ If this slot has the value @code{#t}, then, assuming the 
service has an
 associated process (its ``running value'' is a PID), restart the service
 if that process terminates.
 
+There is a limit to avoid endless respawning: when the service gets
+respawned ``too fast'', it is @dfn{disabled}.  The limit is defined by
+@code{default-respawn-limit} (@pxref{Service De- and Constructors,
+@code{default-respawn-limit}}).
+
 @item #:one-shot?
 @cindex one-shot services
 Whether the service is a @dfn{one-shot service}.  A one-shot service is
@@ -1098,6 +1103,31 @@ sent @code{SIGKILL} for immediate termination.  It 
defaults to 5
 seconds.
 @end defvar
 
+@cindex respawn limit
+@cindex disabled service
+@defvar default-respawn-limit
+This parameter specifies a limit that prevents @command{shepherd} from
+respawning too quickly a service marked with @code{#:respawn? #t}
+(@pxref{Defining Services}).
+
+The limit is expressed as a pair of integers: the first integer,
+@var{n}, specifies a number of consecutive respawns and the second
+integer, @var{t}, specifies a number of seconds.  If the service gets
+respawned more than @var{n} times over a period of @var{t} seconds, it
+is automatically @dfn{disabled} (@pxref{Interacting with Services,
+@code{service-enabled?}}).  Once it is disabled, the service must be
+explicitly re-enabled using @command{herd enable @var{service}} before
+it can be started again.
+
+As an example, suppose you add this line to your configuration file:
+
+@lisp
+(default-respawn-limit '(3 . 10))
+@end lisp
+
+The effect is that services will be respawned at most 3 times over a
+period of 10 seconds before being disabled.
+@end defvar
 
 @cindex on-demand, starting services
 @cindex inetd-style services
diff --git a/modules/shepherd/service.scm b/modules/shepherd/service.scm
index f9d1ae0..fa2d011 100644
--- a/modules/shepherd/service.scm
+++ b/modules/shepherd/service.scm
@@ -95,6 +95,7 @@
             %precious-signals
             register-services
 
+            default-respawn-limit
             default-service-termination-handler
             default-environment-variables
             make-forkexec-constructor
@@ -207,13 +208,14 @@
 use 'actions' instead.")
     (actions rest ...)))
 
-;; Respawning CAR times in CDR seconds will disable the service.
-;;
-;; XXX: The terrible hack in (shepherd) using SIGALRM to work around
-;; unreliable SIGCHLD delivery means that it might take up to 1 second for
-;; SIGCHLD to be delivered.  Thus, arrange for the car to be lower than the
-;; cdr.
-(define respawn-limit '(5 . 7))
+(define default-respawn-limit
+  ;; Respawning CAR times in CDR seconds will disable the service.
+  ;;
+  ;; XXX: The terrible hack in (shepherd) using SIGALRM to work around
+  ;; unreliable SIGCHLD delivery means that it might take up to 1 second for
+  ;; SIGCHLD to be delivered.  Thus, arrange for the car to be lower than the
+  ;; cdr.
+  (make-parameter '(5 . 7)))
 
 (define (respawn-limit-hit? respawns times seconds)
   "Return true of RESPAWNS, the list of times at which a given service was
@@ -2484,6 +2486,9 @@ terminated."
   "Respawn a service that has stopped running unexpectedly. If we have
 attempted to respawn the service a number of times already and it keeps dying,
 then disable it."
+  (define respawn-limit
+    (default-respawn-limit))
+
   (if (and (respawn-service? serv)
            (not (respawn-limit-hit? (service-respawn-times serv)
                                     (car respawn-limit)