[libvirt] [RFC 0/7] Warn at runtime when deprecated features are used

[Andrea Bolognani]

Background
==========

We have plenty of features in libvirt, some of which were designed at
a time when the virtualization story was much more straightforward
than the multi-architecture, multi-hypervisor, multi-machine world we
currently live in and, while we have found ways to keep the APIs
chugging along, the result is sometimes somewhat confusing for users
and application developers, as well as requiring libvirt developers
themselves to spend quite a bit of collective time working around
decisions that, in hindsight, turn out to have been less than
fortunate.

Two concrete examples are considered here: one is the
virConnectNumOfDomains() API which, while known to be racy and having
non-racy alternatives, can still be used by developers without
getting any kind of warning in the process; the other one is the
ability to define a domain without specifying the machine type, which
is becoming increasingly problematic now with some x86_64 features
being limited to q35 and downstreams looking to push for its
adoption, as well as being a manifestation of the more general
problem of libvirt's default being sometimes too conservative and at
odds with the existence of slimmed-down QEMU binaries being built
with reducing the total attack surface in mind.

Having a proper deprecation story in libvirt would allow us to point
users and developers towards the recommended solution in each case,
be it using a different API or querying libosinfo for information;
after a generous grace period, we could then remove the problematic
functionality altogether. This would be a more conservative version
of the process we already have in place for dropping support for
older QEMU releases, which recently has allowed us to ax massive
chunks of effectively dead code and simplify parts of libvirt quite
significantly.

This series explores one possible approach to the problem and aims
to spark project-wide discussion around the topic.


Further work
============

* Fix the known issues listed below as well as all not-yet-known
  issues that will undoubtably surface through discussion :)

* Introduce a mechanism to catch use of deprecated APIs at build
  time, similar to GLib's G_DISABLE_DEPRECATED, to help application
  developers proactively move off problematic APIs.

* Create a formal deprecation policy with well-defined rules and
  time scales in the spirit of the existing one covering our
  relationship with QEMU.


Know issues
===========

* For the more granular (and more interesting) type of deprecation
  shown in patch 6/7, warnings are not being reported back to the
  client as expected. I believe this is caused by the RPC code
  looking for either a failure, in which case the virError is
  transmitted, or a success, in which case the actual return value
  is: we'll have to figure out a way for the error to travel across
  the wire regardless of whether or not the API call was ultimately
  successful if we want clients to actually receive warnings when
  non-local drivers are involved.


Andrea Bolognani (7):
  util: Add 'level' argument to virReportErrorHelper()
  util: Introduce virReportWarning()
  tools: Print warnings in virsh
  util: Introduce VIR_ERR_DEPRECATED_FEATURE
  Deprecate virConnectNumOfDomains()
  Deprecate missing machine type in virDomainDefineXMLFlags()
  tools: Force virsh to use deprecated features

 include/libvirt/virterror.h        |  1 +
 src/access/viraccessdriverpolkit.c |  2 +-
 src/access/viraccessmanager.c      |  2 +-
 src/conf/domain_conf.c             | 11 ++++++++---
 src/datatypes.h                    | 30 ++++++++++++++++++++++++++----
 src/libvirt-domain.c               |  6 ++++++
 src/libvirt.c                      |  1 +
 src/util/virbuffer.c               |  4 ++--
 src/util/virconf.c                 |  6 ++++--
 src/util/virerror.c                | 10 +++++++++-
 src/util/virerror.h                | 15 ++++++++++-----
 src/util/virkeyfile.c              |  6 ++++--
 src/util/virxml.c                  |  2 +-
 tools/virsh-domain-monitor.c       |  2 ++
 tools/vsh.c                        |  3 +++
 15 files changed, 79 insertions(+), 22 deletions(-)

-- 
2.17.1