native_workmanager 1.2.5

Background task scheduling for Flutter — 25+ native workers (HTTP, image, crypto, file), task chains, zero Flutter Engine overhead.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

1.2.5 - 2026-05-06

Fixed

• Core: Removed over-restrictive assertion in TaskTrigger.periodic that prevented using initialDelay and runImmediately: false together (#26).
• iOS: Fixed bug where runImmediately flag was incorrectly recomputed from initialDelay instead of using the user-provided value.

1.2.4 - 2026-04-29

Fixed

• Android: Added automatic ProGuard rules to prevent task classes from being stripped in Release builds (#24).
• Android: Clarified that Application class setup is required for all tasks to survive app kill.
• iOS: Synchronized background task identifiers between setup_ios.dart and Swift code.
• iOS: getTaskStatus() now correctly returns TaskStatus.completed for finished tasks. Previously, the iOS plugin wrote "success" to SQLite but Dart's TaskStatus enum has no success case, so every call returned null.
• Android: Removed duplicate taskStore.updateStatus() call on task completion. The redundant second write used JSONObject(map).toString() which could corrupt nested result maps, overwriting the correctly-encoded first write.
• iOS: FlutterEngineManager now disposes the engine after a Dart callback timeout. Previously the engine remained isInitialized = true with a hung MethodChannel, causing all subsequent DartCallbackWorker tasks to silently fail (timeout again).

Changed

• Engine: Upgraded core kmpworkmanager to v2.4.3 (re-publish of v2.4.2 to fix Maven Central artifact issue; no code changes).

1.2.3 - 2026-04-24

Added

• Feature: Support initialDelay and runImmediately for periodic tasks (#21)
  • Allows delaying the first execution of a periodic task.
  • Added runImmediately flag to skip the first execution.
  • On Android, uses native PeriodicWorkRequest.setInitialDelay().
  • On iOS, maps initialDelay to earliestBeginDate for optimized scheduling.
  • Added parameters to TaskTrigger.periodic().
• Security: Advanced Input Validation
  • All native workers now perform strict validation to block Null Byte Injection, Path Traversal (.., %2e%2e), and Shell Injection characters in URLs and file paths.
• Enterprise-Grade Testing:
  • Implemented comprehensive scripts/run_all_tests.sh covering Unit, Integration, Security, Performance, and Stress tests.
  • Added specific performance benchmarks for task scheduling overhead.
  • Added malicious payload protection tests.
• Improved CI/CD: Integrated automated Security, Performance, and Stress testing into the GitHub Actions pipeline.

Fixed

• Android: Upgraded to kmpworkmanager 2.4.1
  • Switched to native setInitialDelay instead of manual bypass logic.
  • Fixed edge-case crashes on Android 15.
• iOS: Improved Periodic Task Lifecycle
  • Fixed regression where periodic tasks were not tracked in activeTasks, preventing cancellation.
• Android: Fixed broken expedited flag logic in direct enqueue path.

---

1.2.2 - 2026-04-22

Added

• registerPlugins parameter in NativeWorkManager.initialize(): opt-in flag to register all Flutter plugins in the background engine, required when using plugins like flutter_local_notifications inside DartWorker callbacks. Defaults to false to preserve the Zero-Engine I/O principle and avoid side-effects (e.g. Bluetooth disconnects). Also added NativeWorkmanagerPlugin.setPluginRegistrantCallback on Android and iOS to allow selective plugin registration when registerPlugins is false. (#18)

Fixed

• iOS: openFile always fails on Flutter 3.38+ / scene-based apps — UIApplication.shared.keyWindow returns nil in UIWindowScene lifecycle. Replaced with a new activeRootViewController extension that traverses connectedScenes to find the active key window. (#16)
• Android: StackOverflowError when middleware is registered — Kotlin companion extension applyMiddleware was shadowing the internal package-level function of the same name, causing infinite recursion. Renamed the internal function to applyMiddlewareInternal to eliminate the ambiguity. (#17)
• native_workmanager_gen incompatible with Flutter 3.41.x — analyzer >=11.0.0 requires meta ^1.18.0 which conflicts with the Flutter SDK's meta 1.17.0 pin. Widened constraint to >=10.0.0 <13.0.0; analyzer 10.x supports all APIs used by the generator and requires only meta ^1.15.0. (#15)

---

1.2.1 - 2026-04-19

Added

• Security Hardening: All HTTP workers now support HTTPS Enforcement and Private IP Blocking (SSRF Protection) via NativeWorkManager.initialize(enforceHttps: true, blockPrivateIPs: true).
• Path Traversal Protection: Enhanced file path validation to block null-byte injection and encoded dot-segments (%2e%2e) across all native workers.
• WorkManagerLogger interface: A type-safe delegate for forwarding background task events to third-party SDKs like Firebase or Sentry without dynamic reflection.
• New Test Suite: Added 100+ new test cases covering input sanitization, security policy enforcement, performance benchmarks for large directory operations, and multi-stage task chains.

Fixed

• Android: Dart Isolate Timeouts: Implemented hard timeout handling for background Dart execution. If an isolate hangs, the engine is now force-disposed to prevent 50MB+ RAM leaks.
• Android: Task Store Performance: Added batch deletion for task history cleanup to prevent long SQLite write-locks on high-traffic apps.
• Migration Tool: Moved the migrate.dart script to the bin/ directory and added it to the executables section in pubspec.yaml to resolve the Could not find bin/migrate.dart error when running dart run native_workmanager:migrate (#14). Also changed developer.log to print so the CLI output displays correctly.
• Test Infrastructure: Fixed a bug in TaskEventTracker where it incorrectly resolved on "task started" events instead of terminal completion events, leading to flakey stress tests.

---

1.2.0 - 2026-04-17

Added

• Android cold-start DartWorker persistence: DartWorker tasks now execute reliably after app kill. The callbackHandle is persisted to SharedPreferences (Android) and UserDefaults (iOS) during initialize() and automatically restored when WorkManager restarts the process. Requires host app to implement Configuration.Provider — see doc/ANDROID_SETUP.md.
• Advanced Remote Trigger: Support for direct commands in push payloads (native_wm key). Execute tasks, chains (enqueue_chain), graphs, and offline queues without waking Flutter. Both Android and iOS support executing task chains completely in the background.
• HMAC Security: Robust HMAC SHA-256 signature verification for remote triggers (supporting nested objects) to prevent unauthorized task execution.
• Real-time Observability: DevTools extension now supports real-time event streaming via developer.postEvent.
• Global Middleware API: Global interceptors for task configuration (Headers, RemoteConfig, Logging).
• Code Generation Enhancements: native_workmanager_gen now generates type-safe enqueue wrappers and automatic worker registries from @WorkerCallback annotations.
• Task Graphs (DAG): Support for complex non-linear task dependencies on Android.