io: introduce a DNS resolver API

Currently DNS resolution is done automatically as part
of the creation of a QIOChannelSocket object instance.
This works ok for network clients where you just end
up a single network socket, but for servers, the results
of DNS resolution may require creation of multiple
sockets.

Introducing a DNS resolver API allows DNS resolution
to be separated from the socket object creation. This
will make it practical to create multiple QIOChannelSocket
instances for servers.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>

1 files changed, 228 insertions, 0 deletions

diff --git a/include/io/dns-resolver.h b/include/io/dns-resolver.h
new file mode 100644
index 0000000..2f69c08
--- /dev/null
+++ b/include/io/dns-resolver.h
@@ -0,0 +1,228 @@
+/*
+ * QEMU DNS resolver
+ *
+ * Copyright (c) 2016-2017 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#ifndef QIO_DNS_RESOLVER_H
+#define QIO_DNS_RESOLVER_H
+
+#include "qemu-common.h"
+#include "qom/object.h"
+#include "io/task.h"
+
+#define TYPE_QIO_DNS_RESOLVER "qio-dns-resolver"
+#define QIO_DNS_RESOLVER(obj)                                    \
+    OBJECT_CHECK(QIODNSResolver, (obj), TYPE_QIO_DNS_RESOLVER)
+#define QIO_DNS_RESOLVER_CLASS(klass)                                    \
+    OBJECT_CLASS_CHECK(QIODNSResolverClass, klass, TYPE_QIO_DNS_RESOLVER)
+#define QIO_DNS_RESOLVER_GET_CLASS(obj)                                  \
+    OBJECT_GET_CLASS(QIODNSResolverClass, obj, TYPE_QIO_DNS_RESOLVER)
+
+typedef struct QIODNSResolver QIODNSResolver;
+typedef struct QIODNSResolverClass QIODNSResolverClass;
+
+/**
+ * QIODNSResolver:
+ *
+ * The QIODNSResolver class provides a framework for doing
+ * DNS resolution on SocketAddress objects, independently
+ * of socket creation.
+ *
+ * <example>
+ *   <title>Resolving addresses synchronously</title>
+ *   <programlisting>
+ *    int mylisten(SocketAddress *addr, Error **errp) {
+ *      QIODNSResolver *resolver = qio_dns_resolver_get_instance();
+ *      SocketAddress **rawaddrs = NULL;
+ *      size_t nrawaddrs = 0;
+ *      Error *err = NULL;
+ *      QIOChannel **socks = NULL;
+ *      size_t nsocks = 0;
+ *
+ *      if (qio_dns_resolver_lookup_sync(dns, addr, &nrawaddrs,
+ *                                       &rawaddrs, errp) < 0) {
+ *          return -1;
+ *      }
+ *
+ *      for (i = 0; i < nrawaddrs; i++) {
+ *         QIOChannel *sock = qio_channel_new();
+ *         Error *local_err = NULL;
+ *         qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
+ *         if (local_err) {
+ *            error_propagate(&err, local_err);
+ *         } else {
+ *            socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
+ *            socks[nsocks++] = sock;
+ *         }
+ *         qapi_free_SocketAddress(rawaddrs[i]);
+ *      }
+ *      g_free(rawaddrs);
+ *
+ *      if (nsocks == 0) {
+ *         error_propagate(errp, err);
+ *      } else {
+ *         error_free(err);
+ *      }
+ *   }
+ *   </programlisting>
+ * </example>
+ *
+ * <example>
+ *   <title>Resolving addresses asynchronously</title>
+ *   <programlisting>
+ *    typedef struct MyListenData {
+ *       Error *err;
+ *       QIOChannelSocket **socks;
+ *       size_t nsocks;
+ *    } MyListenData;
+ *
+ *    void mylistenresult(QIOTask *task, void *opaque) {
+ *      MyListenData *data = opaque;
+ *      QIODNSResolver *resolver =
+ *         QIO_DNS_RESOLVER(qio_task_get_source(task);
+ *      SocketAddress **rawaddrs = NULL;
+ *      size_t nrawaddrs = 0;
+ *      Error *err = NULL;
+ *
+ *      if (qio_task_propagate_error(task, &data->err)) {
+ *         return;
+ *      }
+ *
+ *      qio_dns_resolver_lookup_result(resolver, task,
+ *                                     &nrawaddrs, &rawaddrs);
+ *
+ *      for (i = 0; i < nrawaddrs; i++) {
+ *         QIOChannel *sock = qio_channel_new();
+ *         Error *local_err = NULL;
+ *         qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
+ *         if (local_err) {
+ *            error_propagate(&err, local_err);
+ *         } else {
+ *            socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
+ *            socks[nsocks++] = sock;
+ *         }
+ *         qapi_free_SocketAddress(rawaddrs[i]);
+ *      }
+ *      g_free(rawaddrs);
+ *
+ *      if (nsocks == 0) {
+ *         error_propagate(&data->err, err);
+ *      } else {
+ *         error_free(err);
+ *      }
+ *    }
+ *
+ *    void mylisten(SocketAddress *addr, MyListenData *data) {
+ *      QIODNSResolver *resolver = qio_dns_resolver_get_instance();
+ *      qio_dns_resolver_lookup_async(dns, addr,
+ *                                    mylistenresult, data, NULL);
+ *    }
+ *   </programlisting>
+ * </example>
+ */
+struct QIODNSResolver {
+    Object parent;
+};
+
+struct QIODNSResolverClass {
+    ObjectClass parent;
+};
+
+
+/**
+ * qio_dns_resolver_get_instance:
+ *
+ * Get the singleton dns resolver instance. The caller
+ * does not own a reference on the returned object.
+ *
+ * Returns: the single dns resolver instance
+ */
+QIODNSResolver *qio_dns_resolver_get_instance(void);
+
+/**
+ * qio_dns_resolver_lookup_sync:
+ * @resolver: the DNS resolver instance
+ * @addr: the address to resolve
+ * @naddr: pointer to hold number of resolved addresses
+ * @addrs: pointer to hold resolved addresses
+ * @errp: pointer to NULL initialized error object
+ *
+ * This will attempt to resolve the address provided
+ * in @addr. If resolution succeeds, @addrs will be filled
+ * with all the resolved addresses. @naddrs will specify
+ * the number of entries allocated in @addrs. The caller
+ * is responsible for freeing each entry in @addrs, as
+ * well as @addrs itself. @naddrs is guaranteed to be
+ * greater than zero on success.
+ *
+ * DNS resolution will be done synchronously so execution
+ * of the caller may be blocked for an arbitrary length
+ * of time.
+ *
+ * Returns: 0 if resolution was successful, -1 on error
+ */
+int qio_dns_resolver_lookup_sync(QIODNSResolver *resolver,
+                                 SocketAddress *addr,
+                                 size_t *naddrs,
+                                 SocketAddress ***addrs,
+                                 Error **errp);
+
+/**
+ * qio_dns_resolver_lookup_async:
+ * @resolver: the DNS resolver instance
+ * @addr: the address to resolve
+ * @func: the callback to invoke on lookup completion
+ * @opaque: data blob to pass to @func
+ * @notify: the callback to free @opaque, or NULL
+ *
+ * This will attempt to resolve the address provided
+ * in @addr. The callback @func will be invoked when
+ * resolution has either completed or failed. On
+ * success, the @func should call the method
+ * qio_dns_resolver_lookup_result() to obtain the
+ * results.
+ *
+ * DNS resolution will be done asynchronously so execution
+ * of the caller will not be blocked.
+ */
+void qio_dns_resolver_lookup_async(QIODNSResolver *resolver,
+                                   SocketAddress *addr,
+                                   QIOTaskFunc func,
+                                   gpointer opaque,
+                                   GDestroyNotify notify);
+
+/**
+ * qio_dns_resolver_lookup_result:
+ * @resolver: the DNS resolver instance
+ * @task: the task object to get results for
+ * @naddr: pointer to hold number of resolved addresses
+ * @addrs: pointer to hold resolved addresses
+ *
+ * This method should be called from the callback passed
+ * to qio_dns_resolver_lookup_async() in order to obtain
+ * results.  @addrs will be filled with all the resolved
+ * addresses. @naddrs will specify the number of entries
+ * allocated in @addrs. The caller is responsible for
+ * freeing each entry in @addrs, as well as @addrs itself.
+ */
+void qio_dns_resolver_lookup_result(QIODNSResolver *resolver,
+                                    QIOTask *task,
+                                    size_t *naddrs,
+                                    SocketAddress ***addrs);
+
+#endif /* QIO_DNS_RESOLVER_H */