kea/doc/design/datasrc/data-source-classes.txt

Data Source Library Classes
===========================

About this document
-------------------

This memo describes major classes used in the data source library,
mainly focusing on handling in-memory cache with consideration of the
shared memory support.  It will give an overview of the entire design
architecture and some specific details of how these classes are expected
to be used.

Before reading, the higher level inter-module protocol should be understood:
http://bind10.isc.org/wiki/SharedMemoryIPC

Overall relationships between classes
-------------------------------------

The following diagram shows major classes in the data source library
related to in-memory caches and their relationship.

image::overview.png[Class diagram showing overview of relationships]

Major design decisions of this architecture are:

* Keep each class as concise as possible, each focusing on one or
  small set of responsibilities.  Smaller classes are generally easier
  to understand (at the cost of understanding how they work in the
  "big picture" of course) and easier to test.

* On a related point, minimize dependency to any single class.  A
  monolithic class on which many others are dependent is generally
  difficult to maintain because you'll need to ensure a change to the
  monolithic class doesn't break anything on any other classes.

* Use polymorphism for any "fluid" behavior, and hide specific details
  under abstract interfaces so implementation details won't be
  directly referenced from any other part of the library.
  Specifically, the underlying memory segment type (local, mapped, and
  possibly others) and the source of in-memory data (master file or
  other data source) are hidden via a kind of polymorphism.

* Separate classes directly used by applications from classes that
  implement details.  Make the former classes as generic as possible,
  agnostic about implementation specific details such as the memory
  segment type (or, ideally and where possible, whether it's for
  in-memory cache or the underlying data source).

The following give a summarized description of these classes.

* `ConfigurableClientList`: The front end to application classes.  An
  application that uses the data source library generally maintains
  one or more `ConfigurableClientList` object (usually one per RR
  class, or when we support views, probably one per view).  This class
  is a container of sets of data source related classes, providing
  accessor to these classes and also acting as a factory of other
  related class objects.  Note: Due to internal implementation
  reasons, there is a base class for `ConfigurableClientList` named
  `ClientList` in the C++ version, and applications are expected to
  use the latter.  But conceptually `ConfigurableClientList` is an
  independent value class; the inheritance is not for polymorphism.
  Note also that the Python version doesn't have the base class.

* `DataSourceInfo`: this is a straightforward tuple of set of class
  objects corresponding to a single data source, including
  `DataSourceClient`, `CacheConfig`, and `ZoneTableSegment`.
  `ConfigurableClientList` maintains a list of `DataSourceInfo`, one
  for each data source specified in its configuration.

* `DataSourceClient`: The front end class to applications for a single
  data source.  Applications will get a specific `DataSourceClient`
  object by `ConfigurableClientList::find()`.
  `DataSourceClient` itself is a set of factories for various
  operations on the data source such as lookup or update.

* `CacheConfig`: library internal representation of in-memory cache
  configuration for a data source.  It knows which zones are to be
  cached and where the zone data (RRs) should come from, either from a
  master file or other data source.  With this knowledge it will
  create an appropriate `LoadAction` object.  Note that `CacheConfig`
  isn't aware of the underlying memory segment type for the in-memory
  data.  It's intentionally separated from this class (see the
  conciseness and minimal-dependency design decisions above).

* `ZoneTableSegment`: when in-memory cache is enabled, it provides
  memory-segment-type independent interface to the in-memory data.
  This is an abstract base class (see polymorphism in the design
  decisions) and inherited by segment-type specific subclasses:
  `ZoneTableSegmentLocal` and `ZoneTableSegmentMapped` (and possibly
  others).  Any subclass of `ZoneTableSegment` is expected to maintain
  the specific type of `MemorySegment` object.

* `ZoneWriter`: a frontend utility class for applications to update
  in-memory zone data (currently it can only load a whole zone and
  replace any existing zone content with a new one, but this should be
  extended so it can handle partial updates).
  Applications will get a specific `ZoneWriter`
  object by `ConfigurableClientList::getCachedZoneWriter()`.
  `ZoneWriter` is constructed with `ZoneableSegment` and `LoadAction`.
  Since these are abstract classes, `ZoneWriter` doesn't have to be
  aware of "fluid" details.  It's only responsible for "somehow" preparing
  `ZoneData` for a new version of a specified zone using `LoadAction`,
  and installing it in the `ZoneTable` (which can be accessed via
  `ZoneTableSegment`).

* `DataSourceStatus`: created by `ConfigurableClientList::getStatus()`,
  a straightforward tuple that represents some status information of a
  specific data source managed in the `ConfigurableClientList`.
  `getStatus()` generates `DataSourceStatus` for all data sources
  managed in it, and returns them as a vector.

* `ZoneTableAccessor`, `ZoneTableIterator`: frontend classes to get
  access to the conceptual "zone table" (a set of zones) stored in a
  specific data source.  In particular, `ZoneTableIterator` allows
  applications to iterate over all zones (by name) stored in the
  specific data source.
  Applications will get a specific `ZoneTableAccessor`
  object by `ConfigurableClientList::getZoneTableAccessor()`,
  and get an iterator object by calling `getIterator` on the accessor.
  These are abstract classes and provide unified interfaces
  independent from whether it's for in-memory cached zones or "real"
  underlying data source.  But the initial implementation only
  provides the in-memory cache version of subclass (see the next
  item).

* `ZoneTableAccessorCache`, `ZoneTableIteratorCache`: implementation
  classes of `ZoneTableAccessor` and `ZoneTableIterator` for in-memory
  cache.  They refer to `CacheConfig` to get a list of zones to be
  cached.

* `ZoneTableHeader`, `ZoneTable`: top-level interface to actual
  in-memory data.  These were separated based on a prior version of
  the design (http://bind10.isc.org/wiki/ScalableZoneLoadDesign) where
  `ZoneTableHeader` may contain multiple `ZoneTable`s.  It's
  one-to-one relationship in the latest version (of implementation),
  so we could probably unify them as a cleanup.

* `ZoneData`: representing the in-memory content of a single zone.
  `ZoneTable` contains (zero, one or) multiple `ZoneData` objects.

* `RdataSet`: representing the in-memory content of (data of) a single
  RRset.
  `ZoneData` contains `RdataSet`s corresponding to the RRsets stored
  in the zone.

* `LoadAction`: a "polymorphic" functor that implements loading zone
  data into memory.  It hides from its user (i.e., `ZoneWriter`)
  details about the source of the data: master file or other data
  source (and perhaps some others).  The "polymorphism" is actually
  realized as different implementations of the functor interface, not
  class inheritance (but conceptually the effect and goal is the
  same).  Note: there's a proposal to replace `LoadAction` with
  a revised `ZoneDataLoader`, although the overall concept doesn't
  change.  See Trac ticket #2912.

* `ZoneDataLoader` and `ZoneDataUpdater`: helper classes for the
  `LoadAction` functor(s).  These work independently from the source
  of data, taking a sequence of RRsets objects, converting them
  into the in-memory data structures (`RdataSet`), and installing them
  into a newly created `ZoneData` object.

Sequence for auth module using local memory segment
---------------------------------------------------

In the remaining sections, we explain how the classes shown in the
previous section work together through their methods for commonly
intended operations.

The following sequence diagram shows the case for the authoritative
DNS server module to maintain "local" in-memory data.  Note that
"auth" is a conceptual "class" (not actually implemented as a C++
class) to represent the server application behavior.  For the purpose
of this document that should be sufficient.  The same note applies to
all examples below.

image::auth-local.png[Sequence diagram for auth server using local memory segment]

1. On startup, the auth module creates a `ConfigurableClientList`
   for each RR class specified in the configuration for "data_sources"
   module.  It then calls `ConfigurableClientList::configure()`
   for the given configuration of that RR class.

2. For each data source, `ConfigurableClientList` creates a
   `CacheConfig` object with the corresponding cache related
   configuration.

3. If in-memory cache is enabled for the data source,
   `ZoneTableSegment` is also created.  In this scenario the cache
   type is specified as "local" in the configuration, so a functor
   creates `ZoneTableSegmentLocal` as the actual instance.
   In this case its `ZoneTable` is immediately created, too.

4. `ConfigurableClientList` checks if the created `ZoneTableSegment` is
   writable.  It is always so for "local" type of segments.  So
   `ConfigurableClientList` immediately loads zones to be cached into
   memory.  For each such zone, it first gets the appropriate
   `LoadAction` through `CacheConfig`, then creates `ZoneWriter` with
   the `LoadAction`, and loads the data using the writer.

5. If the auth module receives a "reload" command for a cached zone
   from other module (xfrin, an end user, etc), it calls
   `ConfigurableClientList::getCachedZoneWriter` to load and install
   the new version of the zone.  The same loading sequence takes place
   except that the user of the writer is the auth module.
   Also, the old version of the zone data is destroyed at the end of
   the process.

Sequence for auth module using mapped memory segment
----------------------------------------------------

This is an example for the authoritative server module that uses
mapped type memory segment for in-memory data.

image::auth-mapped.png[Sequence diagram for auth server using mapped memory segment]

1. The sequence is the same to the point of creating `CacheConfig`.

2. But in this case a `ZoneTableSegmentMapped` object is created based
   on the configuration of the cache type.  This type of
   `ZoneTableSegment` is initially empty and isn't even associated
   with a `MemorySegment` (and therefore considered non-writable).

3. `ConfigurableClientList` checks if the zone table segment is
   writable to know whether to load zones into memory by itself,
   but as `ZoneTableSegment::isWritable()` returns false, it skips
   the loading.

4. The auth module gets the status of each data source, and notices
   there's a `WAITING` state of segment. So it subscribes to the
   "Memmgr" group on a command session and waits for an update
   from the memory manager (memmgr) module. (See also the note at the
   end of the section)

5. When the auth module receives an update command from memmgr, it
   calls `ConfigurableClientList::resetMemorySegment()` with the command
   argument and the segment mode of `READ_ONLY`.
   Note that the auth module handles the command argument as mostly
   opaque data; it's not expected to deal with details of segment
   type-specific behavior. If the reset fails, auth aborts (as there's
   no clear way to handle the failure).

6. `ConfigurableClientList::resetMemorySegment()` subsequently calls
   `reset()` method on the corresponding `ZoneTableSegment` with the
   given parameters.
   In the case of `ZoneTableSegmentMapped`, it creates a new
   `MemorySegment` object for the mapped type, which internally maps
   the specific file into memory.
   memmgr is expected to have prepared all necessary data in the file,
   so all the data are immediately ready for use (i.e., there
   shouldn't be any explicit load operation).

7. When a change is made in the mapped data, memmgr will send another
   update command with parameters for new mapping.  The auth module
   calls `ConfigurableClientList::resetMemorySegment()`, and the
   underlying memory segment is swapped with a new one.  The old
   memory segment object is destroyed.  Note that
   this "destroy" just means unmapping the memory region; the data
   stored in the file are intact. Again, if mapping fails, auth
   aborts.

8. If the auth module happens to receive a reload command from other
   module, it could call
   `ConfigurableClientList::getCachedZoneWriter()`
   to reload the data by itself, just like in the previous section.
   In this case, however, the writability check of
   `getCachedZoneWriter()` fails (the segment was created as
   `READ_ONLY` and is non-writable), so loading won't happen.

NOTE: While less likely in practice, it's possible that the same auth
module uses both "local" and "mapped" (and even others) type of
segments for different data sources.  In such cases the sequence is
either the one in this or previous section depending on the specified
segment type in the configuration.  The auth module itself isn't aware
of per segment-type details, but changes the behavior depending on the
segment state of each data source at step 4 above: if it's `WAITING`,
it means the auth module needs help from memmgr (that's all the auth
module should know; it shouldn't be bothered with further details such
as mapped file names); if it's something else, the auth module doesn't
have to do anything further.

Sequence for memmgr module initialization using mapped memory segment
---------------------------------------------------------------------

This sequence shows the common initialization sequence for the
memory manager (memmgr) module using a mapped type memory segment.
This is a mixture of the sequences shown in Sections 2 and 3.

image::memmgr-mapped-init.png[]

1. Initial sequence is the same until the application module (memmgr)
   calls `ConfigurableClientList::getStatus()` as that for the
   previous section.

2. The memmgr module identifies the data sources whose in-memory cache
   type is "mapped".  (Unlike other application modules, the memmgr
   should know what such types means due to its exact responsibility).
   For each such data source, it calls
   `ConfigurableClientList::resetMemorySegment` with the READ_WRITE
   mode and other mapped-type specific parameters.  memmgr should be
   able to generate the parameters from its own configuration and
   other data source specific information (such as the RR class and
   data source name).

3. The `ConfigurableClientList` class calls
   `ZoneTableSegment::reset()` on the corresponding zone table
   segment with the given parameters.  In this case, since the mode is
   READ_WRITE, a new `ZoneTable` will be created (assuming this is a
   very first time initialization; if there's already a zone table
   in the segment, it will be used).

4. The memmgr module then calls
   `ConfigurableClientList::getZoneTableAccessor()`, and calls the
   `getIterator()` method on it to get a list of zones for which
   zone data are to be loaded into the memory segment.

5. The memmgr module loads the zone data for each such zone.  This
   sequence is the same as shown in Section 2.

6. On loading all zone data, the memmgr module sends an update command
   to all interested modules (such as auth) in the segment, and waits
   for acknowledgment from all of them.

7. Then it calls `ConfigurableClientList::resetMemorySegment()` for
   this data source with almost the same parameter as step 2 above,
   but with a different mapped file name.  This will make a swap of
   the underlying memory segment with a new mapping.  The old
   `MemorySegment` object will be destroyed, but as explained in the
   previous section, it simply means unmapping the file.

8. The memmgr loads the zone data into the newly mapped memory region
   by repeating the sequence shown in step 5.

9. The memmgr repeats all this sequence for data sources that use
   "mapped" segment for in-memory cache.  Note: it could handle
   multiple data sources in parallel, e.g., while waiting for
   acknowledgment from other modules.

Sequence for memmgr module to reload a zone using mapped memory segment
-----------------------------------------------------------------------

This example is a continuation of the previous section, describing how
the memory manager reloads a zone in mapped memory segment.

image::memmgr-mapped-reload.png[]

1. When the memmgr module receives a reload command from other module,
   it calls `ConfigurableClientList::getCachedZoneWriter()` for the
   specified zone name.  This method checks the writability of
   the segment, and since it's writable (as memmgr created it in the
   READ_WRITE mode), `getCachedZoneWriter()` succeeds and returns
   a `ZoneWriter`.

2. The memmgr module uses the writer to load the new version of zone
   data.  There is nothing specific to mapped-type segment here.

3. The memmgr module then sends an update command to other modules
   that would share this version, and waits for acknowledgment from
   all of them.

4. On getting acknowledgments, the memmgr module calls
  `ConfigurableClientList::resetMemorySegment()` with the parameter
   specifying the other mapped file.  This will swap the underlying
   `MemorySegment` with a newly created one, mapping the other file.

5. The memmgr updates this segment, too, so the two files will contain
   the same version of data.