Async parallel

[emanuelGitCodes]

✨ Turning the full-course rescan pipeline fully asynchronous ✨

This PR converts our “rescan an entire course” flow from a single, blocking request into a fan-out message/worker architecture that can scale horizontally and respect Canvas API rate limits. It also introduces environment-driven pool sizing so Docker images can spin up the exact number of PHP workers and Node page-scan workers you need at deploy time.

---

Why

• A big course could take several minutes to scan synchronously, tying up PHP-FPM and occasionally blowing past the Canvas rate limit.

• We want parallel workers (both PHP messenger consumers and Node page-scan tabs) to chew through content items independently.

• DevOps needs an easy knob (SCAN_POOL_SIZE) to tune concurrency per environment.

---

What changed

Area	Key additions / refactors
Messages & handlers	New FullRescanMessage (+ API token & LMS meta)  New ScanContentItem  New FullRescanHandler  New ScanContentItemHandler
Controllers	SyncController::fullCourseRescan() now simply dispatch()es a FullRescanMessage instead of doing work synchronously.
LMS layer	CanvasLms::updateCourseContent() now fires off every endpoint with apiGetAsync() and streams responses; rate-limit logic extracted to checkXRateLimit() helper.
Rate-limit back-off	Quick reactive leaky-bucket check: if x-rate-limit-remaining < 2 we sleep() just long enough for the bucket to refill.
Worker pool	Supervisor conf now reads SCAN_POOL_SIZE → numprocs, and Node’s server.ts reads the same env var for its page pool.
ENV / Docker	.env.example, docker-compose.yml, and messenger-concurrent.conf accept SCAN_POOL_SIZE.
Misc	Lots of error_log() / ConsoleOutput breadcrumbs for easier tracing.

---

Flow – end-to-end

┌────────────┐                                             
│  Browser   │  POST /api/sync/rescan/:id                  
└────────────┘                                             
        │                                                  
        ▼                                                  
┌──────────────────┐  ① dispatch FullRescanMessage         
│ SyncController   │ ──────────────────────────────────▶   
└──────────────────┘                                        
        ▲                                                  
        │ ⑥ JSON: {status:"queued"}                        
        │                                                  
        ▼                                                  
┌──────────────────────────────┐                           
│  FullRescanHandler (worker)  │                           
│  ② refreshLmsContent         │                           
│  ③ foreach updated item      │                           
│     dispatch ScanContentItem │                           
└──────────────────────────────┘                           
            │                                              
            ▼  (fan-out)                                   
┌──────────────────────────────┐  ④ scan, create issues    
│ ScanContentItemHandler(*)    │  ────────────────────▶ DB  
└──────────────────────────────┘                           
            │                                              
            ▼                                              
     Doctrine / MySQL      ⑤ report updated                

Workers listening on:

• async_priority_high – for the FullRescanMessage (serial)

• async_concurrent      – for each ScanContentItem (parallel; numprocs == SCAN_POOL_SIZE)

• async_priority_low    – existing low-priority jobs (unchanged)

---

How to test locally

1. cp .env.example .env and set

SCAN_POOL_SIZE=6
COMPOSE_PROJECT_NAME=udoit

1. 
   

2. docker compose up --build – you should see six messenger-concurrent_* workers and Node “page pool size = 6”.

3. Hit Rescan in the UI → request returns instantly (“queued”).

4. docker logs -f udoit3-php | grep ScanContentItem → each content item should be processed by different PIDs.

5. Confirm reports & issues populate as before.

---

Deployment & rollout

• Safe to deploy incrementally: old endpoints still work; new workers sit idle if no FullRescanMessage arrives.

• SCAN_POOL_SIZE defaults to 1 if unset, so small instances won’t spawn extra processes accidentally.

• Remember to reload Supervisor after changing the env var (docker compose up -d --build handles this).

---

Follow-ups (not in scope here)

• Replace the quick sleep()-based back-off with a shared “token bucket” Redis semaphore so all worker pods coordinate.

• Add functional tests for the message fan-out path.

• Surface progress back to the front-end via WebSockets or polling.

Please review & let me know if you’d like any tweaks!