Document API - add in migration hooks

Signed-off-by: Ikey Doherty <michael.i.doherty@intel.com>

src/datasource/datasource-manager.c

@@ -25,6 +25,16 @@ static const CveDatasource *sources[] = {
         &nvd_data_source,
 };
 
+static void cleanup_sources(void)
+{
+        /* Clean up sources */
+        for (size_t i = 0; i < ARRAY_SIZE(sources); i++) {
+                if (sources[i]->destroy) {
+                        sources[i]->destroy();
+                }
+        }
+}
+
 CveDatasourceManager *cve_datasource_manager_new(const char *dir)
 {
         CveDatasourceManager *manager = NULL;
@@ -36,13 +46,19 @@ CveDatasourceManager *cve_datasource_manager_new(const char *dir)
                         fprintf(stderr,
                                 "%s: Failed to set root directory\n",
                                 source->name);
-                        return NULL;
+                        goto fail;
+                }
+                if (source->migrate && !source->migrate()) {
+                        fprintf(stderr,
+                                "%s: Fatal: Could not perform migration\n",
+                                source->name);
+                        goto fail;
                 }
                 if (source->init && !source->init()) {
                         fprintf(stderr,
                                 "%s: Failed to initialise data source\n",
                                 source->name);
-                        return NULL;
+                        goto fail;
                 }
         }
 
@@ -51,19 +67,17 @@ CveDatasourceManager *cve_datasource_manager_new(const char *dir)
                 return NULL;
         }
         return manager;
+fail:
+        cleanup_sources();
+        return NULL;
 }
 
 void cve_datasource_manager_free(CveDatasourceManager *self)
 {
         if (!self) {
                 return;
         }
-        /* Clean up sources */
-        for (size_t i = 0; i < ARRAY_SIZE(sources); i++) {
-                if (sources[i]->destroy) {
-                        sources[i]->destroy();
-                }
-        }
+        cleanup_sources();
         free(self);
 }
 

src/datasource/datasource.h

@@ -13,18 +13,47 @@
 
 #include <stdbool.h>
 
+/**
+ * Update the data source to the latest version(s)
+ */
 typedef bool (*cve_datasource_update)(bool force);
+
+/**
+ * Initialise this data source after set_basedir and (if implemented)
+ * set_basedir have exited successfully
+ */
 typedef bool (*cve_datasource_init)(void);
+
+/**
+ * Destroy (cleanup) this datasource any any associated resources
+ */
 typedef void (*cve_datasource_destroy)(void);
+
+/**
+ * Set the base directory for all operations. To retain compatibility with
+ * older versions of cve-check-tool, this defaults to the HOME directory.
+ * As such, implementations should take care to correctly namespace themselves.
+ */
 typedef bool (*cve_datasource_set_basedir)(const char *);
 
+/**
+ * Some sources at some point may have used different schemas or paths which
+ * are no longer compatible. In this instance they should perform a schema
+ * bump, and provide a migration function to purge old, potentially broken,
+ * data.
+ *
+ * This will always be called after set_basedir
+ */
+typedef bool (*cve_datasource_migrate)(void);
+
 typedef struct CveDatasource {
         const char *name;
 
         cve_datasource_init init;               /**< Initialise source */
         cve_datasource_update update;           /**< Update this source */
         cve_datasource_destroy destroy;         /**< Uninitialise  source*/
         cve_datasource_set_basedir set_basedir; /**< Set the root dir */
+        cve_datasource_migrate migrate;         /**< Migration handler */
 } CveDatasource;
 
 /*