Skip to content

Commit 2862f48

Browse files
teolemonteolemon
authored
docs: Create README.md about background tasks debugging and documentation of background tasks (#6745)
* docs: Create README.md about background tasks debugging and documentation of background tasks * Update README.md * Apply suggestions from code review
1 parent 7666c65 commit 2862f48

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎packages/smooth_app/lib/background/README.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
## Debugging Steps for Background Tasks in Smooth App
2+
3+
### 1. **Check Server Responsiveness**
4+
- **Is the Open Food Facts server slow or down?**
5+
- Test server reachability: Try accessing the API or website in a browser.
6+
- Look for server status pages or community reports of outages.
7+
- If the server is slow, background tasks may timeout or fail with “Server timeout” or similar errors (see: `background_task_error_server_time_out`).
8+
9+
### 2. **Product Movement Between Projects**
10+
- **Has the product/barcode moved to a different Open Products Facts instance (e.g., from Open Food Facts to Open Beauty Facts)?**
11+
- Check which project the barcode belongs to on the web.
12+
- If moved, background tasks may fail or be rejected by the server.
13+
14+
### 3. **Network Conditions**
15+
- **WiFi vs Metered Connection (Mobile Data)**
16+
- On metered connections, some operating systems or user settings may restrict background network activity.
17+
- On Android/iOS, check if the app has permission to use data in the background.
18+
- **Data Saver Mode**
19+
- If enabled, this may pause or throttle background tasks.
20+
- Advise users to disable Data Saver for the app if they expect real-time syncing.
21+
22+
### 4. **Connectivity**
23+
- **No Internet or Flaky Connections**
24+
- Tasks will be retried later if the connection is lost (see code: `taskStatusNoInternet`).
25+
- Test with a stable connection.
26+
- Check if other apps can access the internet.
27+
28+
### 5. **App Lifecycle**
29+
- **App Needs to Be Open**
30+
- Background tasks in Smooth App typically require the app to be in the foreground or not aggressively killed by the OS.
31+
- On iOS, background execution is much more restricted than Android.
32+
- Advise users to keep the app open for a while after making changes.
33+
34+
### 6. **Operating System Restrictions**
35+
- **iOS Background Execution**
36+
- iOS limits background execution unless using specific APIs (background fetch, silent push, etc.).
37+
- If the app is closed or in the background for too long, tasks may not run until the user brings the app to the foreground.
38+
- **Android Doze/Battery Optimization**
39+
- Check if the app is exempt from battery optimizations.
40+
41+
### 7. **File Path Issues (iOS Bug)**
42+
- **Current Bug: iOS Filepath**
43+
- There is a known issue affecting file paths on iOS (e.g., uploads may fail if the app cannot access the selected file).
44+
- A fix has been merged for this, and will be in the next release
45+
- Try with a different image or file to see if the problem persists.
46+
47+
### 8. **App Permissions**
48+
- Ensure the app has permissions for:
49+
- Network access
50+
- Background data usage
51+
- Storage (for reading files/images to upload)
52+
53+
### 9. **Check Task Queue**
54+
- **Pending Tasks**
55+
- Check if tasks are stuck, duplicated, or failing repeatedly.
56+
- You can view pending background tasks in the Smooth App (UI may display this info).
57+
- **Task Errors**
58+
- Error logs may indicate why a task failed (e.g., “No internet”, “Server timeout”, etc.).
59+
60+
### 10. **Logs and Debugging**
61+
- **Enable debug logging**
62+
- Look at the debug output for messages from `BackgroundTaskManager`.
63+
- Check for repeated errors or messages about duplicate stamps.
64+
- **Review device logs**
65+
- Use Android Studio/Flutter DevTools to inspect logs.
66+
67+
### 11. **Storage and Local Database**
68+
- **Database Corruption**
69+
- If the local database is corrupted, tasks may not be stored or executed properly.
70+
- Try clearing app data or reinstalling the app.
71+
72+
### 12. **App Version**
73+
- **Update to the Latest Version**
74+
- Ensure you are using the latest release with all known bug fixes, especially regarding the iOS filepath bug.
75+
76+
---
77+
78+
## Summary Table
79+
80+
| Issue/Setting | Debugging Step/Check |
81+
|------------------------------- |------------------------------------------------------ |
82+
| Server slow/unreachable | Test API/website, check status reports |
83+
| Product moved between projects | Check barcode on OFF/OBF/other sites |
84+
| WiFi vs metered/data saver | Try on WiFi, disable data saver, check permissions |
85+
| Connectivity | Verify stable internet, try other apps |
86+
| App must be open | Keep app foregrounded after making changes |
87+
| OS background restrictions | Check iOS/Android background settings |
88+
| iOS filepath bug | Try the internal build once the PR is merged. |
89+
| Permissions | Verify network, storage, background data permissions |
90+
| Task queue/issues | View in-app task queue UI, inspect for stuck tasks |
91+
| Logs and debugging | Enable debug logs, inspect error/status messages |
92+
| Local database/storage | Clear app data, reinstall if corruption suspected |
93+
| App version | Update to latest version |
94+
95+
---
96+
97+
### How the Background Tasks System Works
98+
99+
#### Architecture & Core Concepts
100+
- **BackgroundTaskManager**: Central class managing background tasks. Handles single-threaded execution, blocking, restarting, and displaying tasks.
101+
- **Task Queues**: Tasks are organized into different queues (`fast`, `slow`, `longHaul`), each with its own timing and processing characteristics.
102+
- Each queue has settings for:
103+
- Minimum duration between runs
104+
- Maximum time a task run is allowed before considering it failed
105+
- Database keys for storing start/stop times and the queue itself
106+
- **Task Structure**:
107+
- Each background task is a subclass of `BackgroundTask`.
108+
- Tasks have a `processName`, a unique ID, a "stamp" for deduplication, user/language/country metadata, and are (de)serializable to JSON.
109+
- Tasks implement an `execute(LocalDatabase)` method to perform their work.
110+
- There are specialized types like `BackgroundTaskProgressing` for paged/incremental work, and concrete implementations for product uploads, downloads, "Hunger Games," etc.
111+
112+
#### Task Lifecycle
113+
- **Adding Tasks**: Tasks are added to the appropriate queue and immediately trigger a run if possible.
114+
- **Executing Tasks**: The manager fetches runnable tasks (skipping those scheduled for later, or currently not eligible), deduplicates tasks by "stamp," and runs them in order.
115+
- **Task Execution**:
116+
- Tasks may perform recovery steps before running.
117+
- If a task fails (e.g., due to no internet), it's marked as such and retried later.
118+
- If a newer task with the same "stamp" appears, older duplicates are removed.
119+
- **Finishing Tasks**: After execution, a task's `postExecute` is called, and it's removed from the queue.
120+
- **Error Handling**:
121+
- Errors are recorded (e.g., "No internet, try later!").
122+
- If a task fails but is superseded by a newer one, it's safely discarded.
123+
- **Task Statuses**: Tasks can have statuses like "started," "no internet," or custom error messages.
124+
- **Manual Triggers**: The system can force an immediate run of all task queues.
125+
126+
#### Persistence
127+
- **Local Storage**: Task info and statuses are stored in the local database for reliability and recovery after restarts.
128+
- **Timestamps**: Start/stop times are tracked to ensure tasks don't overlap or get stuck indefinitely.
129+
130+
---
131+
132+
### Current Limitations & Known Issues
133+
134+
- **Single-threaded Execution**: Tasks are run in a single-threaded fashion per queue. If a task takes a long time, subsequent tasks are delayed.
135+
- **Deduplication Logic**: Only the latest task for a given "stamp" (except some uploads) will be executed; earlier ones are discarded. This can sometimes lead to lost intermediate work if many similar tasks are queued quickly.
136+
- **Error Handling**:
137+
- If there's no network, tasks are retried later, but persistent failures might require user intervention.
138+
- Some error messages (like "No internet") are generic.
139+
- **Task Management**:
140+
- If a task fails, it remains until it succeeds or is overwritten.
141+
- There are TODOs in the code about cleaning up or improving task management, especially as the system and use cases evolve.
142+
- **Debugging**: There are debug print statements and TODOs indicating areas for potential improvement or more robust logging.
143+
- **User Feedback**: UI strings note that contributions are saved automatically but not always in real time, reflecting the asynchronous nature and possible delays in background processing.
144+
- **Legacy Code/Upgrades**: Some classes have logic for backward compatibility (e.g., product type defaults for legacy tasks).
145+
- **Security**: There's a TODO about not storing passwords in clear text in the task data.
146+
147+
---
148+
149+
### In Summary
150+
151+
The background tasks system is a robust, queue-based mechanism for processing uploads, downloads, and other operations asynchronously. It uses local persistence, deduplication, and error handling to ensure reliability, but is currently single-threaded, has some rough edges in error recovery and task deduplication, and has ongoing areas for cleanup and improvement.
152+
153+
If you need a more detailed breakdown of a specific part (e.g., how uploads are handled, or how to add new task types), let me know!

0 commit comments

Comments
 (0)