feat: support scan by time window

[longhoangwkm]

feat: Support scan by time window

Summary

Adds support for scheduled time-based control of blockchain event scanning in development environments. This feature allows configuring specific time windows when scanning should be enabled or disabled, helping reduce resource usage during off-hours in non-production environments.

Cost Benefits: By disabling scanning during off-hours, this feature significantly reduces the number of requests to blockchain nodes, thereby lowering costs for node service providers (e.g., Infura, Alchemy) when running in development environments.

Changes

New Features

• Schedule Pattern Parser (schedule-pattern-parser.ts): Parses schedule pattern strings with timezone and day-specific time ranges
• Schedule Evaluator (schedule-evaluator.ts): Evaluates whether scanning should be enabled at a given UTC time based on the parsed schedule
• Schedule Scan Control Job (schedule_scan_control.job.ts): Command-line job that checks the current time against the schedule and updates network scan states accordingly

Service Enhancements

• NetworkService: Added updateAllNetworksStopScan() method to bulk update is_stop_scan flag for all networks
• ProcessedBlockService: Added deleteAllProcessedBlocks() method to clear processed block records when resuming scans
• NetworkModule: Exported NetworkService to make it available for dependency injection in job modules

Documentation

• Added comprehensive documentation in README.md covering:
  • Schedule pattern format and syntax
  • Timezone handling
  • Multiple usage examples
  • Job execution instructions

Technical Details

Schedule Pattern Format

TZ=<timezone>|<day>[<time-range|all|off>],<day>[<time-range|all|off>],...

• Timezone: +HH:MM or -HH:MM format (e.g., +07:00, -05:00)
• Day names: mon, tue, wed, thu, fri, sat, sun (case-insensitive)
• Time ranges: HH:MM-HH:MM (24-hour format)
• Keywords: all (scan all day), off (disable scanning)
• Default: Days not specified default to scanning all day

Behavior

• Production: Feature is disabled - scanning runs 24/7 regardless of schedule
• Development: Schedule pattern is evaluated, and scanning is enabled/disabled accordingly
• When enabling scan: All ProcessedBlockEntity records are deleted to ensure fresh start from current blockchain state
• When disabling scan: Sets is_stop_scan = true for all networks

Job Execution

The job is designed to run periodically (e.g., via Kubernetes CronJob) and:

1. Checks current UTC time against the schedule pattern
2. Compares desired state with current network state
3. Updates network scan flags only if state change is needed
4. Logs all actions for monitoring

Cost Optimization

Reduced Node Service Costs: This feature helps minimize costs in development environments by:

• Reducing API requests: When scanning is disabled, no requests are made to blockchain nodes (e.g., eth_getBlockByNumber, eth_getLogs)
• Time-based control: Configure scanning only during business hours or when developers are actively working
• Automatic management: No manual intervention needed - the job automatically enables/disables scanning based on the schedule

Example: If scanning is configured for business hours only (8am-6pm, Mon-Fri), this reduces node service requests by approximately 58% compared to 24/7 scanning (10 hours/day × 5 days = 50 hours/week vs 168 hours/week).

Usage Examples

# Vietnam business hours (Mon-Fri 8am-6pm, weekends off)
SCAN_SCHEDULE_PATTERN="TZ=+07:00|mon[08:00-18:00],tue[08:00-18:00],wed[08:00-18:00],thu[08:00-18:00],fri[08:00-18:00],sat[off],sun[off]"

# Different hours per day
SCAN_SCHEDULE_PATTERN="TZ=+07:00|mon[08:00-18:00],tue[09:00-17:00],wed[08:00-18:00],thu[09:00-17:00],fri[08:00-18:00],sat[off],sun[off]"

# 24/7 scanning (default)
SCAN_SCHEDULE_PATTERN="TZ=+00:00|"

Testing

• Test schedule pattern parsing with various valid/invalid formats
• Test timezone conversion and time range evaluation
• Test job execution in development environment
• Verify production environment skips schedule control
• Test state transitions (enable → disable, disable → enable)
• Verify processed blocks are deleted when resuming scans
• Monitor node service request reduction when scanning is disabled

Notes

• This feature is development-only and will not affect production environments
• The job should be scheduled to run periodically (e.g., hourly) via Kubernetes CronJob
• Pattern parsing includes comprehensive error handling with fallback to 24/7 scanning
• Cost savings: Significantly reduces node service API requests and associated costs in development environments