services: tor: Deprecate 'tor-hidden-service' procedure.

Due to (now renamed) 'hidden-service' record type not being exported, the only
way Onion services (formely hidden services) could have worked is through the
now deprecated 'tor-hidden-service' procedure.

This commit updates the Tor service documentation, corrects some inconsistently
named accessors in <tor-configuration> record-type, renames and refactors
tor-hidden-service-configuration to tor-onion-service-configuration using
define-configuration and also exports it, allowing Onion services to be
configured directly within a <tor-configuration> record.
Lastly, it also deprecates the 'tor-hidden-service' procedure.

* doc/guix.texi (Networking Services): Substitute mentions of “Hidden services”
with “Onion Services”. Add a Tor Onion service configuration example.
Document <tor-onion-service-configuration>. Remove mention of
'tor-hidden-service' procedure.
* gnu/services/networking.scm: Export tor-configuration-tor,
tor-configuration-config-file, tor-configuration-hidden-services,
tor-configuration-socks-socket-type, tor-configuration-control-socket-path,
tor-onion-service-configuration, tor-onion-service-configuration?,
tor-onion-service-configuration-name, tor-onion-service-configuration-mapping.
(<tor-configuration>)[control-socket?]: Rename accessor.
(<hidden-service>): Replace with …
(<tor-onion-service-configuration>): … this.
(tor-configuration->torrc): Update record-type name.
(tor-activation): Ditto.
(tor-hidden-service-type): Remove variable.
(tor-hidden-service): Deprecate procedure.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>

2 files changed, 77 insertions, 47 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index db222dd6df..46e7fd3908 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -20604,11 +20604,22 @@ Spawn a proxy server listening to TLS connections on the specified port.
 
 @cindex Tor
 @defvar tor-service-type
-This is the type for a service that runs the @uref{https://torproject.org,
-Tor} anonymous networking daemon.  The service is configured using a
+Type for a service that runs the @uref{https://torproject.org, Tor}
+anonymous networking daemon.  The service is configured using a
 @code{<tor-configuration>} record.  By default, the Tor daemon runs as the
 @code{tor} unprivileged user, which is a member of the @code{tor} group.
 
+@cindex onion services, for Tor
+Services of this type can be extended by other services to specify
+@dfn{onion services} (in addition to those already specified in
+@code{tor-configuration}) as in this example:
+
+@lisp
+(simple-service 'my-extra-onion-service tor-service-type
+                (list (tor-onion-service-configuration
+                        (name "extra-onion-service")
+                        (mapping '((80 . "127.0.0.1:8080"))))))
+@end lisp
 @end defvar
 
 @deftp {Data Type} tor-configuration
@@ -20627,11 +20638,10 @@ file-like objects}).  See @code{man tor} for details on the configuration file
 syntax.
 
 @item @code{hidden-services} (default: @code{'()})
-The list of @code{<hidden-service>} records to use.  For any hidden service
-you include in this list, appropriate configuration to enable the hidden
-service will be automatically added to the default configuration file.  You
-may conveniently create @code{<hidden-service>} records using the
-@code{tor-hidden-service} procedure described below.
+The list of @code{<tor-onion-service-configuration>} records to use.
+For any onion service you include in this list, appropriate
+configuration to enable the onion service will be automatically added to
+the default configuration file.
 
 @item @code{socks-socket-type} (default: @code{'tcp})
 The default socket type that Tor should use for its SOCKS socket.  This must
@@ -20656,26 +20666,30 @@ If @code{#t}, Tor will listen for control commands on the UNIX domain socket
 @end table
 @end deftp
 
-@cindex hidden service
-@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
-Define a new Tor @dfn{hidden service} called @var{name} and implementing
-@var{mapping}.  @var{mapping} is a list of port/host tuples, such as:
-
-@example
- '((22 "127.0.0.1:22")
-   (80 "127.0.0.1:8080"))
-@end example
+@cindex onion service, tor
+@deftp {Data Type} tor-onion-service-configuration
+Data Type representing a Tor @dfn{Onion Service} configuration.
+See @url{https://community.torproject.org/onion-services/, the Tor
+project's documentation} for more information.
+Available @code{tor-onion-service-configuration} fields are:
 
-In this example, port 22 of the hidden service is mapped to local port 22, and
-port 80 is mapped to local port 8080.
+@table @asis
+@item @code{name} (type: string)
+Name for this Onion Service.  This creates a
+@file{/var/lib/tor/hidden-services/@var{name}} directory, where the
+@file{hostname} file contains the @indicateurl{.onion} host name for this Onion
+Service.
 
-This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
-the @file{hostname} file contains the @code{.onion} host name for the hidden
-service.
+@item @code{mapping} (type: alist)
+Association list of port to address mappings.  The following example:
+@lisp
+'((22 . "127.0.0.1:22")
+  (80 . "127.0.0.1:8080"))
+@end lisp
+maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080.
 
-See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
-project's documentation} for more information.
-@end deffn
+@end table
+@end deftp
 
 The @code{(gnu services rsync)} module provides the following services:
 
diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm
index 19c109d238..866368aa90 100644
--- a/gnu/services/networking.scm
+++ b/gnu/services/networking.scm
@@ -138,7 +138,16 @@
 
             tor-configuration
             tor-configuration?
-            tor-hidden-service
+            tor-configuration-tor
+            tor-configuration-config-file
+            tor-configuration-hidden-services
+            tor-configuration-socks-socket-type
+            tor-configuration-control-socket-path
+            tor-onion-service-configuration
+            tor-onion-service-configuration?
+            tor-onion-service-configuration-name
+            tor-onion-service-configuration-mapping
+            tor-hidden-service  ; deprecated
             tor-service-type
 
             network-manager-configuration
@@ -908,7 +917,7 @@ applications in communication.  It is used by Jami, for example.")))
                     (default '()))
   (socks-socket-type tor-configuration-socks-socket-type ; 'tcp or 'unix
                      (default 'tcp))
-  (control-socket?  tor-control-socket-path
+  (control-socket?  tor-configuration-control-socket-path
                     (default #f)))
 
 (define %tor-accounts
@@ -922,11 +931,22 @@ applications in communication.  It is used by Jami, for example.")))
          (home-directory "/var/empty")
          (shell (file-append shadow "/sbin/nologin")))))
 
-(define-record-type <hidden-service>
-  (hidden-service name mapping)
-  hidden-service?
-  (name    hidden-service-name)                   ;string
-  (mapping hidden-service-mapping))               ;list of port/address tuples
+(define-configuration/no-serialization tor-onion-service-configuration
+  (name
+   string
+   "Name for this Onion Service.  This creates a
+@file{/var/lib/tor/hidden-services/@var{name}} directory, where the
+@file{hostname} file contains the @indicateurl{.onion} host name for this
+Onion Service.")
+
+  (mapping
+   alist
+   "Association list of port to address mappings.  The following example:
+@lisp
+'((22 . \"127.0.0.1:22\")
+  (80 . \"127.0.0.1:8080\"))
+@end lisp
+maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080."))
 
 (define (tor-configuration->torrc config)
   "Return a 'torrc' file for CONFIG."
@@ -966,7 +986,7 @@ HiddenServicePort ~a ~a~%"
                                                 tcp-port host))
                                       ports hosts)))
                          '#$(map (match-lambda
-                                   (($ <hidden-service> name mapping)
+                                   (($ <tor-onion-service-configuration> name mapping)
                                     (cons name mapping)))
                                  hidden-services))
 
@@ -1053,7 +1073,7 @@ HiddenServicePort ~a ~a~%"
       (chmod "/var/lib" #o755)
 
       (for-each initialize
-                '#$(map hidden-service-name
+                '#$(map tor-onion-service-configuration-name
                         (tor-configuration-hidden-services config)))))
 
 (define tor-service-type
@@ -1066,7 +1086,7 @@ HiddenServicePort ~a ~a~%"
                        (service-extension activation-service-type
                                           tor-activation)))
 
-                ;; This can be extended with hidden services.
+                ;; This can be extended with Tor Onion Services.
                 (compose concatenate)
                 (extend (lambda (config services)
                           (tor-configuration
@@ -1079,21 +1099,14 @@ HiddenServicePort ~a ~a~%"
                  "Run the @uref{https://torproject.org, Tor} anonymous
 networking daemon.")))
 
-(define tor-hidden-service-type
-  ;; A type that extends Tor with hidden services.
-  (service-type (name 'tor-hidden-service)
-                (extensions
-                 (list (service-extension tor-service-type list)))
-                (description
-                 "Define a new Tor @dfn{hidden service}.")))
-
-(define (tor-hidden-service name mapping)
+(define-deprecated (tor-hidden-service name mapping)
+  #f
   "Define a new Tor @dfn{hidden service} called @var{name} and implementing
 @var{mapping}.  @var{mapping} is a list of port/host tuples, such as:
 
 @example
- '((22 \"127.0.0.1:22\")
-   (80 \"127.0.0.1:8080\"))
+ '((22 . \"127.0.0.1:22\")
+   (80 . \"127.0.0.1:8080\"))
 @end example
 
 In this example, port 22 of the hidden service is mapped to local port 22, and
@@ -1105,8 +1118,11 @@ service.
 
 See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
 project's documentation} for more information."
-  (service tor-hidden-service-type
-           (hidden-service name mapping)))
+  (simple-service 'tor-hidden-service
+                  tor-service-type
+                  (list (tor-onion-service-configuration
+                         (name name)
+                         (mapping mapping)))))
 
 
 ;;;