From cf97aeefa920b849add9ed94845905691c11ff7c Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 10 Feb 2022 19:13:31 -0800
Subject: [PATCH] CRM_Queue_Service - Document/store/load additional queueSpec
 properties

---
 CRM/Queue/Service.php | 42 ++++++++++++++++++++++++++++++++----------
 1 file changed, 32 insertions(+), 10 deletions(-)

diff --git a/CRM/Queue/Service.php b/CRM/Queue/Service.php
index 576f76cdf2..db55233762 100644
--- a/CRM/Queue/Service.php
+++ b/CRM/Queue/Service.php
@@ -37,6 +37,14 @@ class CRM_Queue_Service {
 
   protected static $_singleton;
 
+  /**
+   * List of fields which are shared by `$queueSpec` and `civicrm_queue`.
+   *
+   * @var string[]
+   * @readonly
+   */
+  private static $commonFields = ['name', 'type', 'runner', 'batch_limit', 'lease_time', 'retry_limit', 'retry_interval'];
+
   /**
    * FIXME: Singleton pattern should be removed when dependency-injection
    * becomes available.
@@ -80,9 +88,12 @@ class CRM_Queue_Service {
    *     flushed; default to TRUE
    *   - (additional keys depending on the queue provider).
    *   - is_persistent: bool, optional; if true, then this queue is loaded from `civicrm_queue` list
-   *   - is_autorun: bool, optional; if true, then this queue will be auto-scanned
-   *     by background task-runners
-   *
+   *   - runner: string, optional; if given, then items in this queue can run
+   *     automatically via `hook_civicrm_queueRun_{$runner}`
+   *   - batch_limit: int, Maximum number of items in a batch. Tip: If you expand batch_limit, then also consider expanding lease_time.
+   *   - lease_time: int, When claiming an item (or batch of items) for work, how long should the item(s) be reserved. (Seconds)
+   *   - retry_limit: int, Number of permitted retries. Decreases with each retry. Zero (0) to disable. Null for system default.
+   *   - retry_interval: int, Number of seconds to wait before retrying a failed execution.
    * @return CRM_Queue_Queue
    */
   public function create($queueSpec) {
@@ -121,22 +132,33 @@ class CRM_Queue_Service {
    * @throws \CRM_Core_Exception
    */
   protected function findCreateQueueSpec(array $queueSpec): array {
-    $storageFields = ['type', 'is_autorun'];
-    $dao = new CRM_Queue_DAO_Queue();
-    $dao->name = $queueSpec['name'];
-    if ($dao->find(TRUE)) {
-      return array_merge($queueSpec, CRM_Utils_Array::subset($dao->toArray(), $storageFields));
+    $loaded = $this->findQueueSpec($queueSpec);
+    if ($loaded !== NULL) {
+      return $loaded;
     }
 
     if (empty($queueSpec['type'])) {
       throw new \CRM_Core_Exception(sprintf('Failed to find or create persistent queue "%s". Missing field "%s".',
         $queueSpec['name'], 'type'));
     }
-    $queueSpec = array_merge(['is_autorun' => FALSE], $queueSpec);
+
+    $dao = new CRM_Queue_DAO_Queue();
+    $dao->name = $queueSpec['name'];
     $dao->copyValues($queueSpec);
     $dao->insert();
 
-    return $queueSpec;
+    return $this->findQueueSpec($queueSpec);
+  }
+
+  protected function findQueueSpec(array $queueSpec): ?array {
+    $dao = new CRM_Queue_DAO_Queue();
+    $dao->name = $queueSpec['name'];
+    if ($dao->find(TRUE)) {
+      return array_merge($queueSpec, CRM_Utils_Array::subset($dao->toArray(), static::$commonFields));
+    }
+    else {
+      return NULL;
+    }
   }
 
   /**
-- 
2.25.1