Implement poll notifications in core

This commit implements the ability to specify an external command
to run via -pollnotify=<cmd> argument that takes two placeholders,
%s1 and %s2, which are replaced with the poll txid and the
notification status (added, deleted, or expiration_warning).

The notifications are sent on all non-expired polls. Add/delete
notifications are executed by the poll contract handlers. The
expiration warning is handled by a scheduler function which checks
every 5 minutes and does a single shot notification for polls that
are within -pollexpirewarningtime=<hours> of expiration.

This should be sufficient to drive an external script for
notification via email or other desired approach.

Author: jamescowens

src/gridcoin/gridcoin.cpp

@@ -487,6 +487,15 @@ void ScheduleRegistriesPassivation(CScheduler& scheduler)
 
     scheduler.scheduleEvery(RunDBPassivation, std::chrono::minutes{5});
 }
+
+void SchedulePollNotifications(CScheduler& scheduler)
+{
+    // Run poll notifications every 5 minutes. This is a very thin call most of the time.
+    // Please see the NotifyPoll function and notify_poll.
+
+    scheduler.scheduleEvery(NotifyPoll, std::chrono::minutes{5});
+}
+
 } // Anonymous namespace
 
 // -----------------------------------------------------------------------------
@@ -552,6 +561,10 @@ void GRC::ScheduleBackgroundJobs(CScheduler& scheduler)
     ScheduleBackups(scheduler);
     ScheduleUpdateChecks(scheduler);
     ScheduleRegistriesPassivation(scheduler);
+
+#if HAVE_SYSTEM
+    SchedulePollNotifications(scheduler);
+#endif
 }
 
 bool GRC::CleanConfig() {
@@ -615,3 +628,25 @@ void GRC::RunDBPassivation()
         registry.PassivateDB();
     }
 }
+
+void GRC::NotifyPoll()
+{
+    PollRegistry& poll_registry = GetPollRegistry();
+
+    LOCK2(cs_main, poll_registry.cs_poll_registry);
+
+    // Get the expiration warning time from the configuration. Default is 7 days in hours.
+    int64_t expiration_warning_time = gArgs.GetArg("-pollexpirewarningtime", 7 * 24);
+
+    for (const auto& poll : poll_registry.Polls()) {
+        if (!poll->Ref().Expired(GetAdjustedTime())
+            && !poll->Ref().IsExpiringWarningNotified()
+            && poll->Ref().Expiration() - GetAdjustedTime() < expiration_warning_time * 3600) {
+
+            // Note this will set m_is_expiring_warning_notified to true as well as execute the poll notification
+            // free thread to run the provided command. So this is effectively a "single-shot" expiration
+            // warning notification for each expiring poll.
+            poll->Ref().Notify(PollReference::PollNotificationType::POLL_EXPIRE_WARNING);
+        }
+    }
+}

src/gridcoin/gridcoin.h

@@ -46,6 +46,11 @@ bool CleanConfig();
 //! with registry db.
 //!
 void RunDBPassivation();
+
+//!
+//! \brief Function to provide for poll expiration/warning notification.
+//!
+void NotifyPoll();
 } // namespace GRC
 
 #endif // GRIDCOIN_GRIDCOIN_H

src/gridcoin/voting/registry.cpp

@@ -332,6 +332,7 @@ PollReference::PollReference()
     , m_duration_days(0)
     , m_votes({})
     , m_magnitude_weight_factor(Fraction())
+    , m_expiration_warn_notified(false)
 {
 }
 
@@ -764,6 +765,49 @@ std::optional<CAmount> PollReference::GetActiveVoteWeight(const PollResultOption
     }
 }
 
+std::string PollReference::NotifyTypeToString(const PollNotificationType& notify_type) const
+{
+    switch (notify_type) {
+    case PollNotificationType::POLL_ADD:
+        return "added";
+    case PollNotificationType::POLL_DELETE:
+        return "deleted";
+    case PollNotificationType::POLL_EXPIRE_WARNING:
+        return "expiration_warning";
+    default:
+        return "unknown";
+    }
+}
+
+void PollReference::Notify(const PollNotificationType& notify_type) const
+{
+#if HAVE_SYSTEM
+  // Support running an external command on poll creation. Do not notify for already expired polls. This is especially
+    // important during a sync to avoid spamming poll notifications.
+    if (!Expired(GetAdjustedTime())) {
+        std::string strCmd = gArgs.GetArg("-pollnotify", std::string {});
+
+        if (strCmd.empty()) {
+            return;
+        }
+
+        // The placeholders %s1 and %s2 are replaced with the txid and the notification type.
+        boost::replace_all(strCmd, "%s1", m_txid.ToString());
+        boost::replace_all(strCmd, "%s2", NotifyTypeToString(notify_type));
+        boost::thread t(runCommand, strCmd); // thread runs free
+
+        if (notify_type == POLL_EXPIRE_WARNING) {
+            m_expiration_warn_notified = true;
+        }
+    }
+#endif
+}
+
+bool PollReference::IsExpiringWarningNotified() const
+{
+    return m_expiration_warn_notified;
+}
+
 void PollReference::LinkVote(const uint256 txid)
 {
     m_votes.emplace_back(txid);
@@ -1064,6 +1108,8 @@ void PollRegistry::AddPoll(const ContractContext& ctx) EXCLUSIVE_LOCKS_REQUIRED(
 
         poll_ref.m_magnitude_weight_factor = payload->m_poll.ResolveMagnitudeWeightFactor(poll_ref.GetStartingBlockIndexPtr());
 
+        poll_ref.Notify(PollReference::PollNotificationType::POLL_ADD);
+
         if (fQtActive && !poll_ref.Expired(GetAdjustedTime())) {
             uiInterface.NewPollReceived(poll_ref.Time());
         }
@@ -1142,6 +1188,12 @@ void PollRegistry::DeletePoll(const ContractContext& ctx) EXCLUSIVE_LOCKS_REQUIR
 
     int64_t poll_time = payload->m_poll.m_timestamp;
 
+    PollReference* poll_ref = TryBy(payload->m_poll.m_title);
+
+    // Note this reference will effectively disappear once this function exits, but this is ok, because there will
+    // be no need to further reference it after this point for purposes of notification.
+    poll_ref->Notify(PollReference::PollNotificationType::POLL_DELETE);
+
     m_polls.erase(ToLower(payload->m_poll.m_title));
 
     m_polls_by_txid.erase(ctx.m_tx.GetHash());
@@ -1155,7 +1207,6 @@ void PollRegistry::DeletePoll(const ContractContext& ctx) EXCLUSIVE_LOCKS_REQUIR
     if (fQtActive) {
         uiInterface.NewPollReceived(poll_time);;
     }
-
 }
 
 void PollRegistry::DeleteVote(const ContractContext& ctx) EXCLUSIVE_LOCKS_REQUIRED(cs_main, PollRegistry::cs_poll_registry)

src/gridcoin/voting/registry.h

@@ -47,6 +47,14 @@ class PollReference
     friend class PollRegistry;
 
 public:
+    enum PollNotificationType
+    {
+        UNKNOWN,
+        POLL_ADD,
+        POLL_DELETE,
+        POLL_EXPIRE_WARNING
+    };
+
     //!
     //! \brief Initialize an empty, invalid poll reference object.
     //!
@@ -167,6 +175,26 @@ class PollReference
     //!
     std::optional<CAmount> GetActiveVoteWeight(const PollResultOption &result) const;
 
+    //!
+    //! \brief Provides string equivalent of PollNotificationType
+    //! \param notify_type
+    //! \return string equivalent of PollNotificationType
+    //!
+    std::string NotifyTypeToString(const PollNotificationType& notify_type) const;
+
+    //!
+    //! \brief Runs a free thread executing provided poll notification command. Also sets m_expiration_warn_notified
+    //! to true if the notification type is EXPIRE_WARNING.
+    //! \param notify_type
+    //!
+    void Notify(const PollNotificationType& notify_type) const;
+
+    //!
+    //! \brief Returns whether the expiration warning was sent.
+    //! \return boolean indicating whether the expiration warning was sent.
+    //!
+    bool IsExpiringWarningNotified() const;
+
     //!
     //! \brief Record a transaction that contains a response to the poll.
     //!
@@ -193,6 +221,7 @@ class PollReference
     uint32_t m_duration_days;                   //!< Number of days the poll remains active.
     std::vector<uint256> m_votes;               //!< Hashes of the linked vote transactions.
     mutable Fraction m_magnitude_weight_factor; //!< Magnitude weight factor for the poll (defined at poll start).
+    mutable bool m_expiration_warn_notified;    //!< Flag to indicate whether the expiration warning was sent.
 }; // PollReference
 
 //!

src/init.cpp

@@ -360,6 +360,12 @@ void SetupServerArgs()
                    ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
     argsman.AddArg("-walletnotify=<cmd>", "Execute command when a wallet transaction changes (%s in cmd is replaced by TxID)",
                    ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
+    argsman.AddArg("-pollnotify=<cmd>", "Execute command when a poll is added/deleted/expiring (%s1 in cmd is replaced by poll id,"
+                                        "%s2 is replaced by status: added, deleted, expiration warning)",
+                   ArgsManager::ALLOW_ANY | ArgsManager::IMMEDIATE_EFFECT, OptionsCategory::OPTIONS);
+    argsman.AddArg("-pollexpirewarningtime=<hours>", "Hours before poll expiration to execute notification command. Default is "
+                                                     "7 days (168 hours)",
+                   ArgsManager::ALLOW_ANY | ArgsManager::IMMEDIATE_EFFECT, OptionsCategory::OPTIONS);
 #endif
     argsman.AddArg("-confchange", "Require confirmations for change (default: 0)",
                    ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);