feat: enhance retention management and testing for mini programs

Author: dos1in

.github/workflows/fe-tests.yml

@@ -5,10 +5,16 @@ on:
     paths:
       - 'fe/**'
       - 'examples/miniprogram/**'
+      - 'harmony/dimina/src/main/ets/**'
+      - 'harmony/scripts/**'
+      - '.github/workflows/fe-tests.yml'
   push:
     paths:
       - 'fe/**'
       - 'examples/miniprogram/**'
+      - 'harmony/dimina/src/main/ets/**'
+      - 'harmony/scripts/**'
+      - '.github/workflows/fe-tests.yml'
   workflow_dispatch:
 
 jobs:
@@ -60,3 +66,6 @@ jobs:
       - name: Run tests
         working-directory: ./fe
         run: pnpm test
+
+      - name: Run Harmony portable runtime regressions
+        run: node --test harmony/scripts/*.test.mjs

android/dimina/src/test/java/com/didi/dimina/core/BackgroundRetentionTest.kt

@@ -34,4 +34,26 @@ class BackgroundRetentionTest {
 
     @Test(expected = IllegalArgumentException::class)
     fun rejectsNegativeCapacity() { RetentionPolicy(-1) }
+    @Test fun reentryStartsANewLeaseAndAnOldDeadlineCannotEvictIt() {
+        val state = BackgroundRetention()
+        state.policy = RetentionPolicy(3, 100)
+        state.hide("a", 0)
+        state.forget("a") // show before expiry
+        assertNull(state.nextDelay(90) { true })
+        state.hide("a", 200)
+        assertEquals(emptyList<String>(), state.collect(299, false) { true })
+        assertEquals(listOf("a"), state.collect(300, false) { true })
+    }
+
+    @Test fun repeatedPressureAndCapacityChangesDoNotRetainDestroyedGenerations() {
+        val state = BackgroundRetention()
+        state.hide("a", 0); state.hide("b", 1)
+        assertEquals(listOf("a", "b"), state.collect(2, true) { true })
+        assertEquals(emptyList<String>(), state.collect(3, true) { true })
+        state.hide("a", 200) // a new runtime with the same appId
+        state.policy = RetentionPolicy(0, 0)
+        assertEquals(listOf("a"), state.collect(200, false) { true })
+        assertNull(state.nextDelay(200) { true })
+    }
+
 }

docs/MiniProgram-Retention.md

@@ -40,7 +40,7 @@ Android、iOS 和 Harmony 的后台实例不能操作前台导航栈。销毁后
 
 每个保留实例仍占用 JS 和 WebView 内存，宿主可通过主动销毁入口释放不再需要的实例。Harmony 隐藏期间的 TabBar 更新在恢复时应用；待处理更新最多 128 条，超过上限会失败，避免无限积压。
 
-四端共用逻辑层的协作式挂起：`App.onHide` 执行后暂停 `setTimeout`、`setInterval` 和普通业务消息回调，包括网络、扩展事件与 Canvas 动画回调。`App.onShow` 时恢复，定时器继续剩余等待时间，周期定时器不补跑隐藏期间错过的次数。业务消息按接收顺序分批处理，每批最多 64 条，避免为每条积压消息创建原生定时器。
+四端共用逻辑层的协作式挂起：`App.onHide` 执行后暂停 `setTimeout`、`setInterval` 和普通业务消息回调，包括网络、扩展事件与 Canvas 动画回调。`App.onShow` 时恢复，定时器继续剩余等待时间，周期定时器不补跑隐藏期间错过的次数。业务消息按接收顺序恢复，每条消息保留独立任务边界，让它产生的 Promise 微任务在下一条消息前完成。浏览器使用一个 `MessageChannel`，原生运行时使用计时器调度，始终只保留一个待执行的恢复任务。已经失效的定时器回调不会在快速隐藏、恢复后重复执行。
 
 资源初始化、页面生命周期、销毁屏障和跨小程序导航的成功/失败/完成回调继续分发，避免隐藏后的退出或重启操作互相等待。挂起不抢占正在执行的 JS 或微任务，不冻结整个 Worker、WebView、原生网络或媒体任务；已到达但尚未分发的业务消息仍占用内存。原生能力继续遵循各自的隐藏与销毁规则。
 
@@ -59,6 +59,8 @@ Android、iOS 和 Harmony 的后台实例不能操作前台导航栈。销毁后
 
 当前展示的实例，以及跨小程序导航中尚未解除的来源链，属于受保护的展示关系，不计入可回收缓存上限。宿主整体进入系统后台也不会立即解除该关系。因此总运行实例数可以大于 `maxBackgroundApps`，该配置不是进程总实例数的硬上限。实例脱离展示关系后才允许自动销毁，避免破坏返回页面与来源关系。
 
+Harmony 某个实例关闭失败时保留其留存记录，并继续处理其他实例；下次配置、真实显示变化或内存压力事件可以重试，不针对失败实例反复启动立即到期的计时器。
+
 内存压力会释放所有可回收后台实例，保留受保护的展示关系；之后再次打开被回收实例走冷启动。回收释放运行时、页面和实例资源，不清除 Storage 或用户文件，也不自动打开其他小程序。
 
 ### Android
@@ -132,3 +134,15 @@ Harmony 的 `customLaunchPageCallBack` 自定义挂载页面没有框架路由
 - Web：`retention-policy.spec.ts`、`retained-mini-program.spec.ts` 与容器 SDK 现有生命周期、并发打开测试。
 - 共享逻辑层：`background-scheduler.spec.js`、`background-lifecycle.spec.js`，验证挂起、恢复、定时器剩余时间和终止性回调的顺序。
 - Harmony：安装前端依赖后执行 `node --test harmony/scripts/retained-pages.test.mjs`；ArkUI 编译通过 `dimina:assembleHar` 验证，实际界面复用仍需设备验证。
+
+### 业务执行回归
+
+自动回归同时验证公开 API 的业务状态和管理器的资源状态：
+
+- `App.globalData` 经 API 成功回调及 Promise 链修改后，完成回调能读取到最终状态。
+- 恢复过程中同步回调重入、Promise 再次隐藏、消息积压和旧定时器迟到，保持顺序与恰好一次执行。
+- Web 过期重开会冷启动，内存压力不影响其他容器或跨小程序返回链。
+- Android/iOS 再次显示取消旧期限，再次隐藏创建新期限；iOS 导航事务期间暂缓回收。
+- Harmony 关闭失败不会丢失留存记录、阻断其他实例回收或立即循环重试。
+
+前端工作流会自动运行共享逻辑层、Web 容器及 Harmony 便携回归；Harmony 源码及脚本变更也会触发该工作流。Android 和 iOS 用例沿用各自的测试工作流。便携测试与模拟器测试不能替代真机压力和长时间运行验证。

fe/packages/container-sdk/__tests__/retained-mini-program.spec.ts

@@ -85,3 +85,60 @@ it('reclaims a hidden runtime after capacity reduction and rebuilds it on next e
 	await container.application.destroyRootView(second)
 	mount.remove()
 })
+
+
+it('checks expiry before reopening even when the host expiry timer has not run', async () => {
+	const clock = vi.spyOn(performance, 'now').mockReturnValue(0)
+	const mount = document.createElement('div')
+	const container = createContainer({ mount, retention: { backgroundTimeoutMs: 100000 } })
+	try {
+		const first = await container.openApp({ appId: 'expired-entry' })
+		await container.application.dismissView(first, { destroy: false })
+		clock.mockReturnValue(100001)
+		const reopened = await container.openApp({ appId: first.appId })
+		expect(reopened).not.toBe(first)
+		expect(FakeWorker.instances[0].terminate).toHaveBeenCalledTimes(1)
+		expect(container.application.views.at(-1)).toBe(reopened)
+	} finally {
+		for (const app of [...container.application.appManager.apps.values()]) await container.application.destroyRootView(app)
+		clock.mockRestore()
+	}
+})
+
+it('keeps a cross-app return chain usable under memory pressure and a zero cache limit', async () => {
+	const container = createContainer({ mount: document.createElement('div'), retention: { maxBackgroundApps: 0 } })
+	const manager = container.application.appManager
+	try {
+		const source = await container.openApp({ appId: 'pinned-source' })
+		const target = await manager.navigateToMiniProgram({ appId: 'pinned-target' }, source)
+		container.notifyMemoryPressure()
+		await manager._enqueue(async () => {})
+		expect(manager.getAppById(source.appId)).toBe(source)
+		expect(manager.getAppById(target.appId)).toBe(target)
+		await manager.navigateBackMiniProgram(target, {}, async () => {})
+		expect(container.application.views.at(-1)).toBe(source)
+		expect(FakeWorker.instances[0].terminate).not.toHaveBeenCalled()
+	} finally {
+		for (const app of [...manager.apps.values()]) await container.application.destroyRootView(app)
+	}
+})
+
+it('isolates memory pressure across containers even when appIds match', async () => {
+	const one = createContainer({ mount: document.createElement('div') })
+	const two = createContainer({ mount: document.createElement('div') })
+	try {
+		const a = await one.openApp({ appId: 'same-id' })
+		const b = await two.openApp({ appId: 'same-id' })
+		await one.application.dismissView(a, { destroy: false })
+		await two.application.dismissView(b, { destroy: false })
+		one.notifyMemoryPressure()
+		await one.application.appManager._enqueue(async () => {})
+		expect(one.application.appManager.getAppById('same-id')).toBeNull()
+		expect(two.application.appManager.getAppById('same-id')).toBe(b)
+		expect(await two.openApp({ appId: 'same-id' })).toBe(b)
+	} finally {
+		for (const container of [one, two]) {
+			for (const app of [...container.application.appManager.apps.values()]) await container.application.destroyRootView(app)
+		}
+	}
+})

fe/packages/service/__tests__/background-lifecycle.spec.js

@@ -30,3 +30,35 @@ it('hides before suspension, defers API callbacks, and keeps exit callbacks and
 	vi.advanceTimersByTime(10)
 	expect(events).toEqual(['hide', 'exit', 'complete', 'show', 'network', 'timer'])
 })
+
+
+it('preserves business state derived by Promise callbacks before the API complete callback', async () => {
+	vi.resetModules()
+	vi.useFakeTimers()
+	globalThis.DiminaServiceBridge.invoke = vi.fn()
+	const service = (await import('../src/index')).default
+	globalThis.App({
+		globalData: { phase: 'initial', completedPhase: undefined },
+		onHide() { this.globalData.hidden = true },
+		onShow() { this.globalData.hidden = false },
+	})
+	const app = globalThis.getApp()
+	globalThis.wx.getStorageInfo({
+		success() {
+			Promise.resolve().then(() => { app.globalData.phase = 'decoded' })
+				.then(() => { app.globalData.phase = 'ready' })
+		},
+		complete() { app.globalData.completedPhase = app.globalData.phase },
+	})
+	const params = globalThis.DiminaServiceBridge.invoke.mock.calls.at(-1)[0].body.params
+	service.message.handleMsg({ type: 'appHide' })
+	service.message.handleMsg({ type: 'triggerCallback', body: { id: params.success, args: { keys: [] } } })
+	service.message.handleMsg({ type: 'triggerCallback', body: { id: params.complete } })
+	await vi.runAllTimersAsync()
+	expect(app.globalData.phase).toBe('initial')
+	expect(app.globalData.hidden).toBe(true)
+	service.message.handleMsg({ type: 'appShow', body: {} })
+	await vi.runAllTimersAsync()
+	expect(app.globalData.hidden).toBe(false)
+	expect(app.globalData.completedPhase).toBe('ready')
+})

fe/packages/service/__tests__/background-scheduler.spec.js

@@ -42,15 +42,15 @@ it('supports cancelling and creating timers while suspended and repeated visibil
 	expect(callback).toHaveBeenCalledTimes(1)
 })
 
-it('defers business callbacks in FIFO order until resume without replaying cancelled timers', () => {
+it('defers business callbacks in FIFO order until resume without replaying cancelled timers', async () => {
 	const events = []
 	scheduler.pause()
 	scheduler.dispatch(() => events.push('network'))
 	scheduler.dispatch(() => events.push('animation'))
 	vi.runOnlyPendingTimers()
 	expect(events).toEqual([])
 	scheduler.resume()
-	vi.runOnlyPendingTimers()
+	await vi.runAllTimersAsync()
 	expect(events).toEqual(['network', 'animation'])
 })
 
@@ -61,3 +61,84 @@ it('an interval cancelled from its callback is not rearmed', () => {
 	expect(callback).toHaveBeenCalledTimes(1)
 	expect(vi.getTimerCount()).toBe(0)
 })
+
+
+it('retains FIFO order when a resumed callback dispatches another callback synchronously', async () => {
+	const events = []
+	scheduler.pause()
+	scheduler.dispatch(() => {
+		events.push('first')
+		scheduler.dispatch(() => events.push('nested'))
+	})
+	scheduler.dispatch(() => events.push('second'))
+	scheduler.resume()
+	await vi.runAllTimersAsync()
+	expect(events).toEqual(['first', 'second', 'nested'])
+})
+
+it('finishes the full Promise chain of one message before delivering the next message', async () => {
+	const events = []
+	scheduler.pause()
+	scheduler.dispatch(() => {
+		events.push('success')
+		Promise.resolve().then(() => events.push('then')).then(() => events.push('chained'))
+	})
+	scheduler.dispatch(() => events.push('complete'))
+	scheduler.resume()
+	await vi.runAllTimersAsync()
+	expect(events).toEqual(['success', 'then', 'chained', 'complete'])
+})
+
+it('does not run the rest of the backlog when a Promise callback hides the app again', async () => {
+	const events = []
+	scheduler.pause()
+	scheduler.dispatch(() => Promise.resolve().then(() => scheduler.pause()))
+	scheduler.dispatch(() => events.push('later'))
+	scheduler.resume()
+	await vi.runAllTimersAsync()
+	expect(events).toEqual([])
+	scheduler.resume()
+	await vi.runAllTimersAsync()
+	expect(events).toEqual(['later'])
+})
+
+it('ignores an already queued native timer callback from before suspension', () => {
+	const queued = []
+	const clock = { now: () => 0, setTimeout: fn => { queued.push(fn); return queued.length }, clearTimeout() {} }
+	const runtime = new BackgroundScheduler(clock)
+	const callback = vi.fn()
+	runtime.set(callback, 10, true)
+	runtime.pause()
+	runtime.resume()
+	queued[0]() // Already submitted by native before clearTimeout; it cannot be withdrawn.
+	expect(callback).not.toHaveBeenCalled()
+	queued[1]()
+	expect(callback).toHaveBeenCalledTimes(1)
+	expect(queued).toHaveLength(3)
+})
+
+
+it('restores a large backlog in order with at most one pending host task', async () => {
+	const events = []
+	scheduler.pause()
+	for (let index = 0; index < 257; index++) scheduler.dispatch(() => events.push(index))
+	expect(vi.getTimerCount()).toBe(0)
+	scheduler.resume()
+	for (let index = 0; index < 257; index++) {
+		expect(vi.getTimerCount()).toBe(1)
+		await vi.advanceTimersToNextTimerAsync()
+	}
+	expect(events).toEqual(Array.from({ length: 257 }, (_, index) => index))
+	expect(vi.getTimerCount()).toBe(0)
+})
+
+it('an exception in one pending callback does not discard following messages', () => {
+	const events = []
+	scheduler.pause()
+	scheduler.dispatch(() => { throw new Error('business callback') })
+	scheduler.dispatch(() => events.push('next'))
+	scheduler.resume()
+	expect(() => vi.advanceTimersToNextTimer()).toThrow('business callback')
+	vi.runAllTimers()
+	expect(events).toEqual(['next'])
+})

fe/packages/service/__tests__/background-worker-tasks.spec.js

@@ -0,0 +1,38 @@
+import { afterEach, expect, it, vi } from 'vitest'
+
+afterEach(() => {
+	vi.useRealTimers()
+	vi.doUnmock('@dimina/common')
+	vi.resetModules()
+})
+
+it('uses one Worker MessageChannel and ignores cancelled task packets across quick hide/show', async () => {
+	vi.resetModules()
+	vi.useFakeTimers()
+	vi.doMock('@dimina/common', () => ({ isWebWorker: true }))
+	const { installBackgroundScheduler } = await import('../src/core/background-scheduler')
+	const nativeTimeout = setTimeout
+	const userTimer = vi.fn(nativeTimeout)
+	let channels = 0
+	class TestMessageChannel {
+		port1 = { onmessage: undefined }
+		port2 = { postMessage: data => nativeTimeout(() => this.port1.onmessage?.({ data }), 0) }
+		constructor() { channels++ }
+	}
+	const target = { setTimeout: userTimer, clearTimeout, MessageChannel: TestMessageChannel }
+	const runtime = installBackgroundScheduler(target)
+	const events = []
+	runtime.pause()
+	runtime.dispatch(() => {
+		events.push('callback')
+		Promise.resolve().then(() => events.push('promise'))
+	})
+	runtime.dispatch(() => events.push('complete'))
+	runtime.resume()
+	runtime.pause()
+	runtime.resume()
+	await vi.runAllTimersAsync()
+	expect(events).toEqual(['callback', 'promise', 'complete'])
+	expect(channels).toBe(1)
+	expect(userTimer).not.toHaveBeenCalled()
+})

fe/packages/service/__tests__/env.spec.js

@@ -8,6 +8,7 @@ const mockGlobalApi = { __mock: true }
 const mockRegisterEnumerableApiNames = vi.fn()
 
 vi.mock('@dimina/common', () => ({
+	isWebWorker: false,
 	modDefine: vi.fn(),
 	modRequire: vi.fn(),
 }))