one/include/BackupJob.h

/* -------------------------------------------------------------------------- */
/* Copyright 2002-2024, OpenNebula Project, OpenNebula Systems                */
/*                                                                            */
/* Licensed under the Apache License, Version 2.0 (the "License"); you may    */
/* not use this file except in compliance with the License. You may obtain    */
/* a copy of the License at                                                   */
/*                                                                            */
/* http://www.apache.org/licenses/LICENSE-2.0                                 */
/*                                                                            */
/* Unless required by applicable law or agreed to in writing, software        */
/* distributed under the License is distributed on an "AS IS" BASIS,          */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   */
/* See the License for the specific language governing permissions and        */
/* limitations under the License.                                             */
/* -------------------------------------------------------------------------- */

#ifndef BACKUP_JOB_H_
#define BACKUP_JOB_H_

#include "PoolObjectSQL.h"
#include "ObjectXML.h"
#include "ObjectCollection.h"

/**
 *  The BackuJob class, it organize backups of multiple VMs
 *
 *  The schema is as follows:
 *  <BACKUPJOB>
 *
 *   <!-- PoolObjectSQL attributes -->
 *
 *   <PRIORITY> Of this backup job. BJ with higher priority are scheduled first
 *   <SCHED_ACTIONS> List of associated scheduled action
 *     <ID>
 *   <UPDATED_VMS> VMs with all backups up to date
 *     <ID>
 *   <OUTDATED_VMS> VMs that need a backup
 *     <ID>
 *   <BACKING_UP_VMS> VMs with an ongoing backup operation
 *     <ID>
 *   <ERROR_VMS>  VMs that fail the last backup operation
 *     <ID>
 *   <LAST_BACKUP_TIME> Last time the backup job was triggered
 *   <LAST_BACKUP_DURATION> Time to backup all VMs int the backup job
 *   <TEMPLATE>
 *     <KEEP_LAST> Just keep the last N backups
 *     <BACKUP_VOLATILE> Backup volatile disks or not
 *     <FS_FREEZE> FS freeze operation to perform on the VM
 *     <MODE> Backup mode
 *     <BACKUP_VMS> comma separated list of VMs to backup, order is implicit
 *     <DATASTORE_ID> The dastore ID used to store the active backups
 *     <EXECUTION>
 */
class BackupJob : public PoolObjectSQL
{
public:
    // *************************************************************************
    // Priority Limits
    // *************************************************************************
    static const int MAX_PRIO;

    static const int MIN_PRIO;

    static const int MAX_USER_PRIO;

    // *************************************************************************
    // Backup modes
    // *************************************************************************
    enum Execution
    {
        SEQUENTIAL = 0, /** < Backup VMs one by one  */
        PARALLEL   = 1, /** < Backup all VMs in parallel */
    };

    static std::string execution_to_str(Execution exec)
    {
        switch (exec)
        {
            case SEQUENTIAL: return "SEQUENTIAL";
            case PARALLEL:   return "PARALLEL";
            default:         return "";
        }
    };

    static Execution str_to_execution(std::string& str_exec)
    {
        Execution exec = SEQUENTIAL;

        one_util::toupper(str_exec);

        if ( str_exec == "SEQUENTIAL" )
        {
            exec = SEQUENTIAL;
        }
        else if ( str_exec == "PARALLEL" )
        {
            exec = PARALLEL;
        }

        return exec;
    };

    /**
     * Function to print the BackuJob object into a string in
     * XML format.
     *  @param xml the resulting XML string
     *  @return a reference to the generated string
     */
    std::string& to_xml(std::string& xml) const override
    {
        return to_xml_extended(xml, false);
    }

    std::string& to_xml_extended(std::string& xml, bool do_sa) const;

    /**
     * Starts execution of the Backup Job
     * Add VMs to WAITING_VMS list, the backup of individual VMs
     * is managed by Scheduled Action Manager
     */
    int execute(std::string& error);

    /**
     * Cancel pending Backup Job action, clear the waiting and pending list
     */
    void cancel();

    /**
     * Retry Backup Job, move VMs from error list to outdated
     */
    void retry();

    /**
     * Returns VMs waiting for a backup, the order define the priority
     */
    std::vector<int> backup_vms() const
    {
        std::string vms_str;
        std::vector<int> vms;
        get_template_attribute("BACKUP_VMS", vms_str);

        one_util::split(vms_str, ',', vms);

        return vms;
    }

    /**
     * Returns VMs waiting for a backup, the order define the priority
     */
    const std::set<int>& outdated() const
    {
        return _outdated.get_collection();
    }

    /**
     * Returns VMs that are currently being backed up
     */
    const std::set<int>& backing_up() const
    {
        return _backing_up.get_collection();
    }

    /**
     * Get priority
     */
    int priority() const
    {
        return _priority;
    }

    /**
     * Set priority
     */
    void priority(int pr)
    {
        if ( pr >= MIN_PRIO && pr <= MAX_PRIO )
        {
            _priority = pr;
        }
    }

    /**
     * Returns execution mode: SEQUENTIAL or PARALLEL
    */
    Execution exec_mode() const;

    /**
     * Returns Datastore ID, where to backup the VMs
    */
    int ds_id() const;

    /**
     * Returns the 'reset' attribute for the Backup Config
    */
    int reset() const;

    /**
     * VM backup started, move the VM from waiting to pending list
    */
    void backup_started(int vm_id);

    /**
     * Remove Virtual Machine from outdated and VMS list
    */
    void remove_vm(int vm_id);

    /**
     * VM backup finished, remove it from backing_up list
    */
    void backup_finished(int vm_id, bool success);

    /**
     * Add Virtual Machine to error_vms list
    */
    void add_error(int vm_id);

    /**
     * Return Backup Config in format for Virtual Machine
    */
    void get_backup_config(Template &tmpl);

    /**
     * Get IDs of the associated scheduled actions
     */
    ObjectCollection& sched_actions()
    {
        return _sched_actions;
    }

    const ObjectCollection& sched_actions() const
    {
        return _sched_actions;
    }

    /**
     *  Replace template for this object. Object should be updated
     *  after calling this method
     *    @param tmpl_str new contents
     *    @param keep_restricted If true, the restricted attributes of the
     *    current template will override the new template
     *    @param error string describing the error if any
     *    @return 0 on success
     */
    int replace_template(const std::string& tmpl_str,
                         bool keep_restricted,
                         std::string& error) override;

    /**
     *  Append new attributes to the *user template*.
     *    @param tmpl_str new contents
     *    @param keep_restricted If true, the restricted attributes of the
     *    current template will override the new template
     *    @param error string describing the error if any
     *    @return 0 on success
     */
    int append_template(const std::string& tmpl_str, bool keep_restricted,
                        std::string& error) override;

    friend class BackupJobPool;
    friend class PoolSQL;

protected:
    /**
     * Child classes can process the new template set with replace_template or
     * append_template with this method
     *    @param error string describing the error if any
     *    @return 0 on success
     */
    int post_update_template(std::string& error) override
    {
        remove_template_attribute("NAME");
        remove_template_attribute("PRIORITY");
        remove_template_attribute("SCHED_ACTION");

        return parse(error);
    }

    // *************************************************************************
    // Database implementation
    // *************************************************************************
    /**
     *  Bootstraps the database table(s) associated to the Backup Jobs
     *    @return 0 on success
     */
    static int bootstrap(SqlDB * db);

    /**
     *  Writes the BackupJob to the DB
     *    @param db pointer to the database.
     *    @return 0 on success.
     */
    int insert(SqlDB * db, std::string& error_str) override;

    /**
     *  Updates the BackupJob record
     *    @param db pointer to the database.
     *    @return 0 on success.
     */
    int update(SqlDB * db) override;

    /**
     *  Execute an INSERT or REPLACE Sql query.
     *    @param db The SQL DB
     *    @param replace Execute an INSERT or a REPLACE
     *    @return 0 on success
     */
    int insert_replace(SqlDB *db, bool replace, std::string& error_str);

private:
    /**
     *  Priority for this backup job [0, 99]
     */
    int _priority;

    /**
     * Associated scheduled action for this backup job
     */
    ObjectCollection _sched_actions;

    /**
     *  These collections stores the collection of VMs in the Virtual
     *  Networks and manages the update process
     *    - updated VMs with not pending backups
     *    - outdated VMs that need backup
     *    - backing_up VMs with an ongoing backup operation
     *    - error VMs that fail the last backup operation
     */
    ObjectCollection _updated;

    ObjectCollection _outdated;

    ObjectCollection _backing_up;

    ObjectCollection _error;

    /**
     *  Time stats for the last backup action (start - epoch, duration - sec)
     */
    time_t _last_time;

    time_t _last_duration;

    /**
     *  @param uid
     *  @param id
     *  @param uname
     *  @param gname
     *  @param umask
     *  @param tmpl
     */
    BackupJob(int                 uid,
              int                 gid,
              const std::string&  uname,
              const std::string&  gname,
              int                 umask,
              std::unique_ptr<Template> templ);

    /**
     *  Factory method for Hook templates
     */
    std::unique_ptr<Template> get_new_template() const override
    {
        return std::make_unique<Template>(true);
    }

    /*
     * Parse configuration attributes for the backup operation
     *  - KEEP_LAST
     *  - BACKUP_VOLATILE
     *  - FSFREEZE
     *  - MODE
     *  - BACKUP_VMS
     *
     * This method also updates the VMs collections removing those VMs no longer
     * present in BACKUP_VMS
     */
    int parse(std::string& error);

    /**
     *  Rebuilds the object from an xml formatted string
     *    @param xml_str The xml-formatted string
     *
     *    @return 0 on success, -1 otherwise
     */
    int from_xml(const std::string &xml_str) override;

    /**
     * Check if the VM belongs only to one Backup Job.
     * Assign Backup Job ID to added Virtual Machines, remove ID for removed VMs.
     *   @param vms_new_str New value of BACKUP_VMS attribute
     *   @param vms_old_str Old value of BACKUP_VMS attribute
     *   @param error string describing the error if any
     *   @return 0 on success, -1 otherwise
     */
    int process_backup_vms(const std::string& vms_new_str,
                           const std::string& vms_old_str,
                           std::string& error);

    /**
     * Remove Backup Job ID from Virtual Machines listed in BACKUP_VMS attribute
     */
    void remove_id_from_vms();

    /**
     * Remove Backup Job ID from Virtual Machines
     *   @param vms Virtual Machine IDs to remove the Backup Job ID
     */
    void remove_id_from_vms(const std::set<unsigned int>& vms);
};

#endif /*BACKUP_JOB_H_*/