soup-server: add new-and-improved APIs

Add new APIs to SoupServer, allowing multiple listening sockets on a
server, and listening on an existing fd or GSocket, and with better
error handling.

https://bugzilla.gnome.org/show_bug.cgi?id=522519
https://bugzilla.gnome.org/show_bug.cgi?id=561547
https://bugzilla.gnome.org/show_bug.cgi?id=621138

3 files changed, 143 insertions, 56 deletions

diff --git a/docs/reference/libsoup-2.4-docs.sgml b/docs/reference/libsoup-2.4-docs.sgml
index c0c8a05c..ba33142a 100644
--- a/docs/reference/libsoup-2.4-docs.sgml
+++ b/docs/reference/libsoup-2.4-docs.sgml
@@ -11,8 +11,8 @@
     <xi:include href="build-howto.xml"/>
     <xi:include href="client-howto.xml"/>
     <xi:include href="request-howto.xml"/>
-    <xi:include href="server-howto.xml"/>
     <xi:include href="session-porting.xml"/>
+    <xi:include href="server-howto.xml"/>
   </chapter>
 
   <chapter>
@@ -35,6 +35,7 @@
     <xi:include href="xml/soup-request-file.xml"/>
     <xi:include href="xml/soup-request-data.xml"/>
     <xi:include href="xml/soup-server.xml"/>
+    <xi:include href="xml/soup-server-deprecated.xml"/>
     <xi:include href="xml/soup-session.xml"/>
     <xi:include href="xml/soup-session-async.xml"/>
     <xi:include href="xml/soup-session-sync.xml"/>
diff --git a/docs/reference/libsoup-2.4-sections.txt b/docs/reference/libsoup-2.4-sections.txt
index 03d35d4b..11f650fb 100644
--- a/docs/reference/libsoup-2.4-sections.txt
+++ b/docs/reference/libsoup-2.4-sections.txt
@@ -216,25 +216,28 @@ SoupKnownStatusCode
 <TITLE>SoupServer</TITLE>
 SoupServer
 soup_server_new
-soup_server_is_https
-soup_server_get_port
-soup_server_get_listener
-soup_server_run
-soup_server_run_async
-soup_server_quit
+soup_server_set_ssl_cert_file
+<SUBSECTION>
+SoupServerListenOptions
+soup_server_listen
+soup_server_listen_all
+soup_server_listen_local
+soup_server_listen_socket
+soup_server_listen_fd
 soup_server_disconnect
-soup_server_get_async_context
+soup_server_is_https
 <SUBSECTION>
 SoupServerCallback
 soup_server_add_handler
 soup_server_remove_handler
 <SUBSECTION>
 SoupClientContext
-soup_client_context_get_socket
-soup_client_context_get_address
+soup_client_context_get_local_address
+soup_client_context_get_remote_address
 soup_client_context_get_host
 soup_client_context_get_auth_domain
 soup_client_context_get_auth_user
+soup_client_context_get_gsocket
 <SUBSECTION>
 soup_server_add_auth_domain
 soup_server_remove_auth_domain
@@ -242,12 +245,7 @@ soup_server_remove_auth_domain
 soup_server_pause_message
 soup_server_unpause_message
 <SUBSECTION>
-SOUP_SERVER_PORT
-SOUP_SERVER_INTERFACE
-SOUP_SERVER_SSL_CERT_FILE
-SOUP_SERVER_SSL_KEY_FILE
 SOUP_SERVER_TLS_CERTIFICATE
-SOUP_SERVER_ASYNC_CONTEXT
 SOUP_SERVER_RAW_PATHS
 SOUP_SERVER_SERVER_HEADER
 SOUP_SERVER_HTTP_ALIASES
@@ -266,6 +264,26 @@ soup_client_context_get_type
 </SECTION>
 
 <SECTION>
+<FILE>soup-server-deprecated</FILE>
+<TITLE>SoupServer deprecated API</TITLE>
+soup_server_get_port
+soup_server_get_listener
+soup_server_run
+soup_server_run_async
+soup_server_quit
+soup_server_get_async_context
+<SUBSECTION>
+soup_client_context_get_socket
+soup_client_context_get_address
+<SUBSECTION>
+SOUP_SERVER_PORT
+SOUP_SERVER_INTERFACE
+SOUP_SERVER_SSL_CERT_FILE
+SOUP_SERVER_SSL_KEY_FILE
+SOUP_SERVER_ASYNC_CONTEXT
+</SECTION>
+
+<SECTION>
 <FILE>soup-auth-domain</FILE>
 <TITLE>SoupAuthDomain</TITLE>
 SoupAuthDomain
diff --git a/docs/reference/server-howto.xml b/docs/reference/server-howto.xml
index 05fb0c05..336a2af4 100644
--- a/docs/reference/server-howto.xml
+++ b/docs/reference/server-howto.xml
@@ -3,17 +3,17 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 <refentry id="libsoup-server-howto">
 <refmeta>
-<refentrytitle>Soup Server Basics</refentrytitle>
+<refentrytitle>libsoup Server Basics</refentrytitle>
 <manvolnum>3</manvolnum>
 <refmiscinfo>LIBSOUP Library</refmiscinfo>
 </refmeta>
 
 <refnamediv>
-<refname>Soup Server Basics</refname><refpurpose>Server-side tutorial</refpurpose>
+<refname>libsoup Server Basics</refname><refpurpose>Server-side tutorial</refpurpose>
 </refnamediv>
 
 <refsect2>
-<title>Creating a SoupSession</title>
+<title>Creating a SoupServer</title>
 
 <para>
 As with the client API, there is a single object that will encapsulate
@@ -25,61 +25,45 @@ linkend="SoupServer"><type>SoupServer</type></link>.
 You create the server with <link
 linkend="soup-server-new"><function>soup_server_new</function></link>,
 and as with the <type>SoupSession</type> constructor, you can specify
-various additional options:
+a few additional options:
 </para>
 
 <variablelist>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-PORT:CAPS"><literal>SOUP_SERVER_PORT</literal></link></term>
+	<term><link linkend="SOUP-SERVER-TLS-CERTIFICATE:CAPS"><literal>SOUP_SERVER_TLS_CERTIFICATE</literal></link></term>
 	<listitem><para>
-	    The TCP port to listen on. If <literal>0</literal> (or
-	    left unspecified), some unused port will be selected for
-	    you. (You can find out what port by calling <link
-	    linkend="soup-server-get-port"><function>soup_server_get_port</function></link>.
+	    A <link
+	    linkend="GTlsCertificate"><type>GTlsCertificate</type></link>
+	    (containing a private key) that will be used when handling
+	    HTTPS requests on the server.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-INTERFACE:CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link></term>
-	<listitem><para>
-	    A <link linkend="SoupAddress"><type>SoupAddress</type></link>,
-	    specifying the IP address of the network interface to run
-	    the server on. If <literal>NULL</literal> (or left
-	    unspecified), the server will listen on all interfaces.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SOUP-SERVER-SSL-CERT-FILE:CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link></term>
-	<listitem><para>
-	    Points to a file containing an SSL certificate to use. If
-	    this is set, then the server will speak HTTPS; otherwise
-	    it will speak HTTP.
-	</para></listitem>
-    </varlistentry>
-    <varlistentry>
-	<term><link linkend="SOUP-SERVER-SSL-KEY-FILE:CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link></term>
+	<term><link linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
 	<listitem><para>
-	    Points to a file containing the private key for the
-	    <literal>SOUP_SERVER_SSL_CERT_FILE</literal>. (It may
-	    point to the same file.)
+	    Set this to <literal>TRUE</literal> if you don't want
+	    <application>libsoup</application> to decode %-encoding
+	    in the Request-URI. (Eg, because you need to treat
+	    <literal>"/foo/bar"</literal> and
+	    <literal>"/foo%2Fbar"</literal> as different paths.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-ASYNC-CONTEXT:CAPS"><literal>SOUP_SERVER_ASYNC_CONTEXT</literal></link></term>
+	<term><link linkend="SOUP-SERVER-SERVER-HEADER:CAPS"><literal>SOUP_SERVER_SERVER_HEADER</literal></link></term>
 	<listitem><para>
-	    A <link linkend="GMainContext"><type>GMainContext</type></link> which
-	    the server will use for asynchronous operations. This can
-	    be set if you want to use a SoupServer in a thread
-	    other than the main thread.
+	    Allows you to set a Server header string that will be sent
+	    on all responses.
 	</para></listitem>
     </varlistentry>
     <varlistentry>
-	<term><link linkend="SOUP-SERVER-RAW-PATHS:CAPS"><literal>SOUP_SERVER_RAW_PATHS</literal></link></term>
+	<term><link linkend="SOUP-SERVER-HTTP-ALIASES:CAPS"><literal>SOUP_SERVER_HTTP_ALIASES</literal></link>
+	and <link linkend="SOUP-SERVER-HTTPS-ALIASES:CAPS"><literal>SOUP_SERVER_HTTPS_ALIASES</literal></link></term>
 	<listitem><para>
-	    Set this to <literal>TRUE</literal> if you don't want
-	    <application>libsoup</application> to decode %-encoding
-	    in the Request-URI. (Eg, because you need to treat
-	    <literal>"/foo/bar"</literal> and
-	    <literal>"/foo%2Fbar"</literal> as different paths.
+	    Allow you to tell the server to recognize additional URI
+	    schemes as aliases for "<literal>http</literal>" or
+	    <literal>https</literal>. You can set this if you are
+	    serving URIs with schemes like "<literal>dav</literal>" or
+	    "<literal>webcal</literal>".
 	</para></listitem>
     </varlistentry>
 </variablelist>
@@ -87,6 +71,90 @@ various additional options:
 </refsect2>
 
 <refsect2>
+<title>Adding Listening Sockets</title>
+
+<para>
+  To tell the server where to listen, call <link
+  linkend="soup-server-listen"><function>soup_server_listen</function></link>
+  (to listen on a specific <link
+  linkend="GSocketAddress"><type>GSocketAddress</type></link>), <link
+  linkend="soup-server-listen-all"><function>soup_server_listen_all</function></link>
+  (to listen on a given port on all network interfaces), or <link
+  linkend="soup-server-listen-local"><function>soup_server_listen_local</function></link>
+  (to listen to a given port on the loopback interface only). You can
+  call any of these functions multiple times, to set up multiple
+  listening sockets.
+</para>
+
+<para>
+  To set up an HTTPS server, you must first either set the <link
+  linkend="SOUP-SERVER-TLS-CERTIFICATE:CAPS"><literal>SOUP_SERVER_TLS_CERTIFICATE</literal></link>
+  property, or else call <link
+  linkend="soup-server-set-ssl-cert-file"><function>soup_server_set_ssl_cert_file</function></link>.
+  After that you can pass the <link
+  linkend="SOUP-SERVER-LISTEN-HTTPS:CAPS"><literal>SOUP_SERVER_LISTEN_HTTPS</literal></link>
+  option to <link
+  linkend="soup-server-listen"><function>soup_server_listen</function></link>,
+  etc.
+</para>
+
+<para>
+  By default, servers listen for both IPv4 and IPv6 connections; if
+  you don't want this, use the <link
+  linkend="SOUP-SERVER-LISTEN-IPV4-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV4_ONLY</literal></link>
+  or <link
+  linkend="SOUP-SERVER-LISTEN-IPV6-ONLY:CAPS"><literal>SOUP_SERVER_LISTEN_IPV6_ONLY</literal></link>
+  options.
+</para>
+
+<para>
+  The server runs asynchronously, in the thread-default
+  <link linkend="GMainContext"><type>GMainContext</type></link> of the
+  thread in which the "listen" calls were made.
+</para>
+</refsect2>
+
+<refsect2 id="soup-server-old-api">
+<title>The Old SoupServer Listening API</title>
+
+<para>
+<link
+linkend="soup-server-listen"><function>soup_server_listen</function></link>,
+etc, are available only in <application>libsoup</application> 2.46 and
+later. In earlier versions, there was a simpler API, in which a server
+could only listen on a single port, determined at construct time
+either by passing the <link
+linkend="SOUP-SERVER-INTERFACE:CAPS"><literal>SOUP_SERVER_INTERFACE</literal></link>
+property (to specify a <link
+linkend="SoupAddress"><type>SoupAddress</type></link> to listen on),
+or the <link
+linkend="SOUP-SERVER-PORT:CAPS"><literal>SOUP_SERVER_PORT</literal></link>
+property (to specify a port to listen on, on all interfaces). The <link
+linkend="SOUP-SERVER-SSL-CERT-FILE:CAPS"><literal>SOUP_SERVER_SSL_CERT_FILE</literal></link>
+and <link
+linkend="SOUP-SERVER-SSL-KEY-FILE:CAPS"><literal>SOUP_SERVER_SSL_KEY_FILE</literal></link>
+properties could be used to create an HTTP server.
+</para>
+
+<para>
+When using this API, if <link
+linkend="SoupServer"><type>SoupServer</type></link> is unable to bind
+the listening socket, or unable to read the provided certificate or
+key files, then it will return <literal>NULL</literal> from its
+constructor (with no further indication of what exactly went wrong).
+</para>
+
+<para>
+Additionally, when using this API, it is necessary to call <link
+linkend="soup-server-run"><function>soup_server_run</function></link>
+or <link
+linkend="soup-server-run-async"><function>soup_server_run_async</function></link>
+to start the server after creating it.
+</para>
+
+</refsect2>
+
+<refsect2>
 <title>Adding Handlers</title>
 
 <para>