[RFD-0000] - Islandora Events Drupal Module

[joecorall]

Note

This is a tracking issue for the long-term success criteria defined in RFD-0000: Enhanced Event Data for Derivative Microservices. The short-term work (X-Islandora-Event header in Alpaca) is complete. This issue tracks the documentation effort required to ship the Drupal-native Symfony Messenger queue system (islandora_events) to production.

Goal

Replace Islandora's Java-based event infrastructure (Alpaca + ActiveMQ) with a PHP-native queue system using Symfony Messenger. This is a significant architectural change that requires comprehensive documentation before the community can adopt it with confidence.

Long-term Success Criteria (from RFD-0000)

• Event lifecycle management moved from Java (Alpaca/ActiveMQ) to PHP (Symfony Messenger)
• Community members can add event features (retries, scanners, custom logic) without Java knowledge
• Event retries, dead letter queues, and missing derivative scanning are working in production
• Paged content conditional event emission works reliably
• Migration path from Alpaca/ActiveMQ is documented and tested
• The solution is adopted by the broader Islandora community
• Existing microservices continue to function without modification
• Documentation and examples show how to extend the system (plugins, event subscribers)
• Performance is validated for high-volume repositories
• PHP/Drupal developers can debug events using SQL queries and Drupal logs

Documentation Sub-tasks

Sub-task issues will be listed here once created.

Background

The prototype islandora_events module demonstrates the long-term vision using Symfony Messenger to replace Alpaca and ActiveMQ entirely, leveraging drupal/sm. Key components include:

• Entity Hooks — capture entity operations and queue messages
• Message Bus — Symfony Messenger handles routing, retry logic, and delayed execution
• Message Handlers — process queued messages asynchronously and dispatch Drupal events
• Event Subscribers — listen to Drupal events and call microservices via HTTP with full context
• Database-backed Queues — three Doctrine transport queues (islandora_derivatives, islandora_scheduled, failed)
• DerivativeScanner Plugin System — PHP plugins that scan for missing derivatives on cron

Related

• RFD-0000 - Previous discussion on event improvements
• Islandora Documentation Issue #1627
• Alpaca DerivativeConnector
• Scyllaridae Event Handling