PriceUpdaterAppv2/docs/enhanced-signal-handling.md

Enhanced Signal Handling for Scheduled Operations

Overview

The enhanced signal handling system provides intelligent cancellation support for scheduled price update operations. It distinguishes between different phases of execution and responds appropriately to interrupt signals (SIGINT/SIGTERM).

Features

1. Phase-Aware Cancellation

The system recognizes three distinct phases:

• Scheduling Wait Period: Cancellation is allowed and encouraged
• Price Update Operations: Cancellation is prevented to avoid data corruption
• Normal Operations: Standard graceful shutdown behavior

2. Clear User Feedback

When users press Ctrl+C during different phases, they receive clear, contextual messages:

During Scheduling Wait Period

🛑 Received SIGINT during scheduled wait period.
📋 Cancelling scheduled operation...
✅ Scheduled operation cancelled successfully. No price updates were performed.

During Price Update Operations

⚠️  Received SIGINT during active price update operations.
🔒 Cannot cancel while price updates are in progress to prevent data corruption.
⏳ Please wait for current operations to complete...
💡 Tip: You can cancel during the countdown period before operations begin.

3. State Coordination

The system uses state management to coordinate between the main application and the ScheduleService:

• schedulingActive: Indicates if the system is in the scheduling wait period
• operationInProgress: Indicates if price update operations are running

Implementation Details

Main Application Signal Handlers

Located in src/index.js, the enhanced signal handlers:

1. Check the current phase (scheduling vs. operations)
2. Provide appropriate user feedback
3. Coordinate with the ScheduleService for cleanup
4. Prevent interruption during critical operations

ScheduleService Integration

The ScheduleService (src/services/schedule.js) has been updated to:

1. Remove its own signal handling (delegated to main application)
2. Support external cancellation through the cleanup() method
3. Provide proper resource cleanup and state management

State Management Functions

The main application provides state management functions to the ShopifyPriceUpdater instance:

• setSchedulingActive(boolean): Updates scheduling phase state
• setOperationInProgress(boolean): Updates operation phase state

Usage Examples

Scheduled Operation with Cancellation

# Set scheduled execution time
export SCHEDULED_EXECUTION_TIME="2025-08-07T15:30:00"

# Run the application
npm start

# During countdown, press Ctrl+C to cancel
# Result: Clean cancellation with confirmation message

Scheduled Operation During Updates

# Same setup, but let the countdown complete
# Once price updates begin, press Ctrl+C
# Result: Cancellation is prevented with explanation

Testing

The enhanced signal handling is thoroughly tested in:

• tests/services/schedule-signal-handling.test.js: Unit tests for all requirements
• Tests cover all three requirements:
  • 3.1: Cancellation during wait period
  • 3.2: Clear cancellation confirmation messages
  • 3.3: No interruption once operations begin

Requirements Compliance

Requirement 3.1: Cancellation Support

✅ IMPLEMENTED: System responds to SIGINT and SIGTERM during wait period

Requirement 3.2: Clear Confirmation Messages

✅ IMPLEMENTED: Contextual messages inform users about cancellation status

Requirement 3.3: Operation Protection

✅ IMPLEMENTED: Price updates cannot be interrupted to prevent data corruption

Benefits

1. Data Integrity: Prevents partial updates that could corrupt pricing data
2. User Experience: Clear feedback about what's happening and what's possible
3. Flexibility: Users can cancel during planning phase but not during execution
4. Reliability: Proper resource cleanup and state management