<feature>[longjob]: Introduce long job state and progerss notification #3293

coderabbitai · 2026-02-04T14:44:40Z

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# 定位 TaskProgressInventory 类文件 fd 'TaskProgressInventory\.java' -type f

Repository: MatheMatrix/zstack

Length of output: 232

🏁 Script executed:

# 查找 ProgressReportService 相关文件 fd 'ProgressReportService\.java' -type f

Repository: MatheMatrix/zstack

Length of output: 232

🏁 Script executed:

# 同时查找是否存在其他与任务进度库存相关的处理逻辑 rg 'class TaskProgressInventory' -A 30

Repository: MatheMatrix/zstack

Length of output: 6153

🏁 Script executed:

# 查找 ProgressReportService 相关文件 fd 'ProgressReportService' -type f

Repository: MatheMatrix/zstack

Length of output: 232

🏁 Script executed:

# 搜索 ProgressReportService 及其对 TaskProgressInventory 的处理 rg 'ProgressReportService' -A 5 -B 5

Repository: MatheMatrix/zstack

Length of output: 50374

🏁 Script executed:

# 查看完整的 TaskProgressInventory 构造器实现和 content 相关方法 cat header/src/main/java/org/zstack/header/core/progress/TaskProgressInventory.java

Repository: MatheMatrix/zstack

Length of output: 2414

🏁 Script executed:

# 定位 ProgressReportService 的完整实现 find . -name "ProgressReportService.java" -path "*/core/progress/*"

Repository: MatheMatrix/zstack

Length of output: 134

🏁 Script executed:

# 查看 ProgressReportService 中关于 TaskProgressInventory 的处理 rg 'TaskProgressInventory' core/src/main/java/org/zstack/core/progress/ProgressReportService.java -A 5 -B 5

Repository: MatheMatrix/zstack

Length of output: 2551

🏁 Script executed:

# 查看 ProgressReportService 中关于 arguments 或 i18n 的处理 rg 'arguments|i18n' core/src/main/java/org/zstack/core/progress/ProgressReportService.java -A 3 -B 3

Repository: MatheMatrix/zstack

Length of output: 44

🏁 Script executed:

# 查看 toI18nString 方法的实现 rg 'toI18nString' core/src/main/java/org/zstack/core/progress/ProgressReportService.java -B 2 -A 10

Repository: MatheMatrix/zstack

Length of output: 1070

🏁 Script executed:

# 查看 LongJobProgressNotificationMessage 的用途，是否用于 Webhook rg 'LongJobProgressNotificationMessage' header/src/main/java/org/zstack/header/longjob/ -A 5 -B 2

Repository: MatheMatrix/zstack

Length of output: 3339

应用 i18n 转换以保持任务进度内容一致

ProgressReportService.inventory() 方法在设置 content 时应用了 toI18nString() 转换，但此处直接设置 content 未进行相同处理。这会导致 Webhook 通知中的任务进度文案与 API 返回的文案不一致。建议参考 ProgressReportService.inventory() 的实现，对 content 应用 toI18nString() 转换：

inv.setContent(toI18nString(progressVO.getContent()));

同时，arguments 的处理也应与 ProgressReportService 保持一致，仅在非空时设置。

🤖 Prompt for AI Agents

In `@header/src/main/java/org/zstack/header/longjob/LongJobProgressNotificationMessage.java` around lines 79 - 92, In LongJobProgressNotificationMessage.progressUpdated, the TaskProgressInventory content is set directly causing i18n mismatch; change it to mirror ProgressReportService.inventory() by calling toI18nString(progressVO.getContent()) when setting inv.setContent(...) and only set inv.setArguments(...) when progressVO.getArguments() is non-null (and likewise apply toI18nString to those arguments if ProgressReportService does so) to ensure webhook notifications match API i18n formatting.

-Original file line number
+Diff line change
@@ Expand Up / @@ -7,4 +7,18 @@ @@
             <defaultValue>259200</defaultValue>
             <type>java.lang.Long</type>
         </config>
+        <config>
+            <category>longJob</category>
+            <name>progress.notification.enabled</name>
+            <description>enable long job progress notification to SNS for UI</description>
+            <defaultValue>true</defaultValue>
+            <type>java.lang.Boolean</type>
+        </config>
+        <config>
+            <category>longJob</category>
+            <name>progress.notification.timeliness</name>
+            <description>batch delay in seconds for long job progress notification (0 = no delay)</description>
+            <defaultValue>1</defaultValue>
+            <type>java.lang.Integer</type>
+        </config>
     </globalConfig>

-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,7 @@ @@
     import org.springframework.transaction.annotation.Transactional;
     import org.zstack.core.Platform;
     import org.zstack.core.cloudbus.CloudBus;
+    import org.zstack.core.componentloader.PluginRegistry;
     import org.zstack.core.cloudbus.MessageSafe;
     import org.zstack.core.config.GlobalConfig;
     import org.zstack.core.config.GlobalConfigUpdateExtensionPoint;
@@ Expand Down Expand Up @@
             vo.setManagementUuid(Platform.getManagementServerId());
             vo.setTaskName(ThreadContext.get(Constants.THREAD_CONTEXT_TASK_NAME));
-            Platform.getComponentLoader().getComponent(DatabaseFacade.class).persist(vo);
+            persistProgress(vo, TaskType.Task);
             // use content as the subtask name
             ThreadContext.put(Constants.THREAD_CONTEXT_TASK_NAME, vo.getContent());
@@ Expand Down Expand Up @@
             }
             Platform.getComponentLoader().getComponent(DatabaseFacade.class).persist(vo);
+            for (ProgressUpdateExtensionPoint ext : Platform.getComponentLoader().getComponent(PluginRegistry.class).getExtensionList(ProgressUpdateExtensionPoint.class)) {
+                try {
+                    ext.afterProgressPersisted(vo);
+                } catch (Throwable t) {
+                    logger.warn("ProgressUpdateExtensionPoint.afterProgressPersisted failed", t);
+                }
+            }
         }
         private static void taskProgress(TaskType type, String fmt, Object... args) {
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -0,0 +1,9 @@
+    package org.zstack.header.core.progress;
+    /**
+     * Extension point invoked after a task progress record is persisted.
+     * Used to trigger downstream notifications (e.g. Long Job progress to SNS) without coupling to progress storage.
+     */
+    public interface ProgressUpdateExtensionPoint {
+        void afterProgressPersisted(TaskProgressVO vo);
+    }

-Original file line number
+Diff line change
@@ -0,0 +1,105 @@
+    package org.zstack.header.longjob;
+    import org.zstack.header.core.progress.TaskProgressInventory;
+    import org.zstack.header.core.progress.TaskProgressVO;
+    import java.io.Serializable;
+    /**
+     * Notification message for Long Job state change and progress update.
+     * Reuses LongJobInventory and TaskProgressInventory for UI consistency.
+     *
+     * <p>Webhook/BFF contract: the payload should include a 0-100 progress number.
+     * BFF uses {@link #getProgress()} (Integer) directly; full taskProgress is optional for future use.
+     */
+    public class LongJobProgressNotificationMessage implements Serializable {
+        public enum EventType {
+            STATE_CHANGED,
+            PROGRESS_UPDATED
+        }
+        private LongJobInventory longJob;
+        /** Latest progress 0-100, derived from type=Progress latest record content. For BFF webhook. */
+        private Integer progress;
+        /** Full progress detail; optional, BFF current version only needs {@link #getProgress()}. */
+        private TaskProgressInventory taskProgress;
+        private EventType eventType;
+        private Long timestamp;
+        public LongJobInventory getLongJob() {
+            return longJob;
+        }
+        public void setLongJob(LongJobInventory longJob) {
+            this.longJob = longJob;
+        }
+        /** Progress 0-100 for BFF webhook; from latest type=Progress content. */
+        public Integer getProgress() {
+            return progress;
+        }
+        public void setProgress(Integer progress) {
+            this.progress = progress;
+        }
+        /** Full task progress inventory; optional for BFF. */
+        public TaskProgressInventory getTaskProgress() {
+            return taskProgress;
+        }
+        public void setTaskProgress(TaskProgressInventory taskProgress) {
+            this.taskProgress = taskProgress;
+        }
+        public EventType getEventType() {
+            return eventType;
+        }
+        public void setEventType(EventType eventType) {
+            this.eventType = eventType;
+        }
+        public Long getTimestamp() {
+            return timestamp;
+        }
+        public void setTimestamp(Long timestamp) {
+            this.timestamp = timestamp;
+        }
+        public static LongJobProgressNotificationMessage stateChanged(LongJobVO vo) {
+            LongJobProgressNotificationMessage msg = new LongJobProgressNotificationMessage();
+            msg.longJob = LongJobInventory.valueOf(vo);
+            msg.eventType = EventType.STATE_CHANGED;
+            msg.timestamp = System.currentTimeMillis();
+            return msg;
+        }
+        public static LongJobProgressNotificationMessage progressUpdated(LongJobVO vo, TaskProgressVO progressVO) {
+            LongJobProgressNotificationMessage msg = new LongJobProgressNotificationMessage();
+            msg.longJob = LongJobInventory.valueOf(vo);
+            int percent = parseProgressContent(progressVO.getContent());
+            msg.progress = percent;
+            TaskProgressInventory inv = new TaskProgressInventory(progressVO);
+            if (progressVO.getContent() != null) {
+                inv.setContent(progressVO.getContent());
+            }
+            msg.taskProgress = inv;
+            msg.eventType = EventType.PROGRESS_UPDATED;
+            msg.timestamp = System.currentTimeMillis();
+            return msg;
+        }
+        private static int parseProgressContent(String content) {
+            if (content == null || content.isEmpty()) {
+                return 0;
+            }
+            try {
+                int v = Integer.parseInt(content.trim());
+                return Math.min(100, Math.max(0, v));
+            } catch (NumberFormatException e) {
+                return 0;
+            }
+        }
+    }

-Original file line number
+Diff line change
@@ Expand Up / @@ -13,4 +13,7 @@ public class LongJobGlobalConfig { @@
         @GlobalConfigValidation
         public static GlobalConfig LONG_JOB_DEFAULT_TIMEOUT = new GlobalConfig(CATEGORY, "longJob.api.timeout");
+        public static GlobalConfig LONG_JOB_PROGRESS_NOTIFICATION_ENABLED = new GlobalConfig(CATEGORY, "progress.notification.enabled");
+        public static GlobalConfig LONG_JOB_NOTIFICATION_TIMELINESS = new GlobalConfig(CATEGORY, "progress.notification.timeliness");
     }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

<feature>[longjob]: Introduce long job state and progerss notification #3293

Uh oh!

Diff view

Diff view

There are no files selected for viewing

coderabbitai bot Feb 4, 2026

Uh oh!

-Original file line number
+Diff line change
@@ -0,0 +1,36 @@
+    package org.zstack.longjob.sns;
+    import org.zstack.core.progress.TaskTracker;
+    import org.zstack.header.longjob.LongJobVO;
+    /**
+     * Task tracker for Long Job state change and progress update notifications.
+     * Used by LongJobProgressNotification to receive tasks and publish to SNS.
+     */
+    public class LongJobTaskTracker extends TaskTracker {
+        public static final String TASK_NAME = "longjob-progress";
+        public static final String PARAM_STATE = "state";
+        public static final String PARAM_PROGRESS = "progress";
+        public static final String PARAM_LONG_JOB_UUID = "longJobUuid";
+        public static final String PARAM_JOB_NAME = "jobName";
+        public enum EventType {
+            STATE_CHANGED,
+            PROGRESS_UPDATED
+        }
+        public LongJobTaskTracker(String resourceUuid) {
+            super(resourceUuid);
+        }
+        @Override
+        protected String getResourceType() {
+            return LongJobVO.class.getSimpleName();
+        }
+        @Override
+        protected String getTaskName() {
+            return TASK_NAME;
+        }
+    }

<feature>[longjob]: Introduce long job state and progerss notification #3293

Uh oh!

<feature>[longjob]: Introduce long job state and progerss notification #3293

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

coderabbitai bot Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!