redfolder 1.0.0

Async economic calendar client and automated trading blackout engine for algorithmic traders and prop firms
Documentation

redfolder

Crates.io Docs.rs CI Rust License: MIT Author

A reliable, asynchronous economic calendar client and event-driven trading blackout engine for Rust algorithmic trading systems, quantitative funds, and prop firm challenges.

Table of Contents

Why redfolder?

In quantitative finance and retail foreign exchange trading, high-impact macroeconomic releases (CPI, Non-Farm Payrolls, FOMC rate decisions, central bank press conferences) are universally referred to as "Red Folder" events.

During these releases, liquidity providers widen their spreads by 10x–50x, depth of book vanishes, and execution slippage drastically increases. Furthermore, major prop trading firms (FTMO, FundedNext, The5ers, MFF) enforce strict compliance rules that disqualify accounts holding or executing trades within 2–5 minutes of high-impact releases.

Building economic news protection from scratch usually results in brittle HTTP pollers that fail during rate limits or fail to cluster back-to-back releases. redfolder solves this with a robust, in-memory interval engine:

  1. Direct Calendar Ingestion: Automatically pulls weekly schedules from ForexFactory / FairEconomy feeds.
  2. Dynamic Window Merging: Automatically aggregates tightly spaced releases into unified blackout intervals.
  3. Event-Driven Broadcast Bus: Pushes typed events (BlackoutWarning, BlackoutStarted, BlackoutEnded) directly into your strategy loop via Tokio broadcast channels or worker-specific streams.
  4. Offline Durability: Gracefully falls back to local disk cache during network partitions or HTTP 429 rate limits.

Architecture & Design

System Flow

┌───────────────────────────────────────────────────────────┐
│               ForexFactory / FairEconomy API              │
└─────────────────────────────┬─────────────────────────────┘
                              │ HTTP / JSON (Auto-cached)
┌─────────────────────────────▼─────────────────────────────┐
│                       CalendarClient                      │
│     - Metadata & Event-Count Validation                   │
│     - Bounded Stale Cache Fallback Policy                 │
│     - Source Timezone & DST Support (chrono-tz)           │
└─────────────────────────────┬─────────────────────────────┘
                              │ RawCalendarEvents
┌─────────────────────────────▼─────────────────────────────┐
│                       BlackoutEngine                      │
│        - Explicit EventTiming (Exact / All-Day / Tentative)│
│        - Overlapping Window Merge (Gap Threshold)         │
│        - Half-Open Interval Semantics: [start, end)       │
│        - Weekend Curfew Injection (Short / Weekend)       │
│        - O(log n) Binary Search Window Evaluation         │
└─────────────────────────────┬─────────────────────────────┘
                              │ Compiled BlackoutWindows
┌─────────────────────────────▼─────────────────────────────┐
│                     RedFolderService                      │
│        - Fine-Grained RwLock Concurrency Architecture     │
│        - Concurrent EventListener Dispatch (tokio::spawn) │
│        - Daily Midnight UTC Sync Loop                     │
│        - Transition-Driven Evaluation Loop (Exact Timing) │
│        - CancellationToken & Tracked JoinHandles Lifecycle│
│        - Immediate State Notification on Worker Register  │
└───────┬───────────────────────────────┬───────────────────┘
        │                               │
        │ Broadcast Channel             │ Dedicated Worker Stream
┌───────▼──────────────────────┐ ┌──────▼───────────────────┐
│     tokio::sync::broadcast   │ │  mpsc::UnboundedReceiver  │
│  (Audit, Webhooks, Logging)  │ │   (Execution Strategies)  │
└──────────────────────────────┘ └───────────────────────────┘

Event-Driven Processing Model

Rather than forcing trading strategies to poll state flags in a tight loop, redfolder operates as an asynchronous event producer. When state changes occur, discrete domain events are broadcast across memory:

  • RedFolderEvent::BlackoutWarning: Emitted $N$ minutes prior to the start of a blackout window. Gives execution bots a clean grace period to cancel pending limit orders, tighten stop-loss thresholds, or scale down leverage before volatility explodes.
  • RedFolderEvent::BlackoutStarted: Emitted the exact second a blackout window becomes active. Directs execution modules to reject incoming trade signals and pause active scalpers.
  • RedFolderEvent::BlackoutEnded: Emitted when the window closes (under standard half-open interval [start, end) semantics), signaling strategies that market conditions and spreads have normalized.
  • RedFolderEvent::CalendarUpdated: Emitted when new weekly schedules are synchronized and indexed into memory.
  • RedFolderEvent::CalendarSyncFailed: Emitted when scheduled or background calendar synchronization fails, alerting risk monitors of network partitions or stale data.

Transition-Driven Event Scheduling vs. Polling

Fixed-interval polling (e.g. every 15s) risks delaying risk alerts by up to 14 seconds during market-moving news releases. redfolder employs a transition-driven scheduler:

  1. Evaluates all registered workers and determines the exact timestamp of the earliest upcoming state transition (blackout start, blackout end, or warning threshold).
  2. Sleeps directly until next_transition, guaranteeing alert emission at the exact second.
  3. Automatically awakens via tokio::sync::Notify whenever new workers are registered/unregistered or calendar data is refreshed.
  4. Retains an internal watchdog fallback ensuring configuration changes and periodic checks execute reliably.

Deterministic Lifecycle & Cancellation Primitives

The service state machine adheres to strict lifecycle transitions: Stopped -> Starting -> Running -> Stopping -> Stopped.

  • Startup Protection: If initial calendar synchronization fails, start() fails cleanly and leaves the service in Stopped state, allowing immediate retry without getting stuck.
  • Clean Task Termination: Background loops are spawned with tokio_util::sync::CancellationToken and tracked JoinHandles. Calling stop() cancels the token, wakes up waiters, and awaits task termination before returning, preventing duplicate concurrent loops across restarts.

Dynamic Window Clustering & Merging

Economic events rarely occur in isolation. A single trading day may schedule:

  • 13:30 UTC: US Consumer Price Index (CPI)
  • 14:00 UTC: FOMC Member Speech
  • 14:15 UTC: Industrial Production

If configured with a 30-minute buffer and a 30-minute merge threshold, redfolder automatically identifies that the tail of the first window intersects or lies within the threshold of the next. It clusters all related events into a single unified BlackoutWindow using half-open intervals ([start, end)), eliminating rapid oscillation between active and inactive states.

Calendar Event Timing & Timezone Normalization

  • Explicit Event Timing: Distinguishes between EventTiming::Exact(DateTime<Utc>), EventTiming::AllDay(NaiveDate), and EventTiming::TentativeDate(NaiveDate). All-day events (e.g. Bank Holidays) and tentative releases do not create spurious midnight spikes by default, but can be configured to cover full 24-hour windows via include_all_day(true).
  • Source Timezone & DST Support: Supports chrono_tz::Tz (e.g. America/New_York) to accurately interpret naive calendar date/time strings with automatic Daylight Saving Time (DST) adjustment (EDT vs EST).

Weekend Market Close Curfew Engine

Forex markets close on Friday evening and reopen on Sunday afternoon, exposing open positions to weekend gap risk. redfolder provides dedicated weekend curfew management:

  • short mode: Initiates a blackout at a configurable Friday UTC time (e.g. 20:30 UTC) and ends at market close (21:00 UTC), preventing late-Friday slippage.
  • weekend mode: Holds trading closed through Friday evening until Monday 00:00 UTC, preventing over-the-weekend exposure.

Weekend curfew windows apply globally to the worker when enabled, intentionally bypassing currency and impact filters since market-close gap risk affects all traded instruments regardless of macroeconomic news releases.

Offline Durability & Rate Limit Resilience

External calendar APIs enforce strict Cloudflare rate limiting (HTTP 429). CalendarClient includes a multi-tier fallback mechanism:

  1. Fresh remote synchronization writes a pretty-printed JSON copy to disk with schema metadata (version, event_count, fetched_at, sha256).
  2. When loading from disk, the client validates that metadata.event_count == events.len() and verifies the SHA-256 cryptographic checksum, rejecting corrupted, truncated, or tampered cache files.
  3. Fallback to stale cache on network failure respects a configurable maximum allowable staleness boundary (max_stale_cache_age, default 36 hours), preventing ancient calendars from silently driving live trading.
  4. An internal lock-split design ensures network downloads execute without holding the service mutex, guaranteeing that worker evaluations are never stalled by remote latency.

Data Sources, Compliance & Multi-Feed Fallback

  • Unofficial Feed Transparency & Risks: By default, redfolder ingests releases from FairEconomy's JSON endpoint (nfs.faireconomy.media/ff_calendar_thisweek.json). Because this is an unofficial endpoint without a formal enterprise SLA, downstream applications must account for potential schema shifts or provider downtime.
  • Anti-Bot Mitigation & User-Agent Disclosure: Upstream Cloudflare mitigations reject default bot User-Agents with HTTP 403 Forbidden. To provide out-of-the-box reliability, CalendarClient provides a standard browser User-Agent by default. For institutional environments or strict corporate compliance policies, custom identification strings can be configured via CalendarClient::with_user_agent.
  • Multi-Endpoint Redundancy: Redundant endpoints, internal cache mirrors, or backup proxies can be chained using with_fallback_url or with_fallback_urls. If the primary endpoint fails or returns a non-retryable error, fetch_remote automatically fails over to the next candidate mirror.

Response Bounding & Memory Hardening

To guard against malicious, misconfigured, or corrupted upstream payloads consuming unbounded heap memory:

  • Pre-Flight Content-Length Enforcement: Validates the HTTP Content-Length header before allocating buffers. If the advertised size exceeds max_response_bytes (default: 10 MiB, configurable via with_max_response_bytes), retrieval is immediately aborted.
  • Streamed Chunk Size Capping: When receiving chunked transfer encoding (where Content-Length is omitted), incoming chunks are streamed incrementally with a strict byte counter. If accumulated bytes exceed the limit, streaming terminates immediately with a typed RedFolderError::Calendar.
  • Event Count Upper Bound: Parsed JSON arrays are bounded by max_event_count (default: 50,000 events, configurable via with_max_event_count), preventing CPU and memory exhaustion from upstream event loops or malformed JSON matrices.

Cryptographic Disk Integrity & File Permissions

Macroeconomic release schedules directly govern live trading execution and risk parameters. redfolder incorporates file-level and disk-level defenses:

  • SHA-256 Cache Checksum: Every atomic write computes a SHA-256 digest of the serialized events array stored in CacheMetadata.sha256. Upon disk load, the digest is re-verified. Any unauthorized out-of-process modification or bit rot triggers immediate cache rejection.
  • Shared Host File Permissions: On Unix platforms, cache directories are created with owner-only access (0700), and temporary/final cache files are locked to read/write owner-only permissions (0600) via std::os::unix::fs.
  • Pluggable Integrity Validation: Institutional teams can attach a custom verification closure via CalendarClient::with_integrity_validator to assert custom HMAC signatures, PGP validation, or domain-specific sanity rules prior to committing releases into memory.

Retry Latency Ceilings & Execution SLAs

Gatekeeping real-time order execution requires strictly bounded network latency. fetch_remote provides deterministic latency boundaries:

  • Bounded Exponential Backoff: Retries are capped at max_retries (default: 2), initial backoff begins at 500ms, and Retry-After header values from upstream 429 responses are hard-capped at 10s.
  • Worst-Case Wall-Clock Bounds: Under total connection timeout conditions, total wall-clock latency per endpoint candidate is bounded to $(1 + 2) \times 30\text{s} + 20\text{s} = 110\text{s}$. Under instant HTTP 429/5xx status responses, maximum total latency is $\le 21\text{s}$.
  • End-to-End Operation Timeout: Callers can configure CalendarClient::with_overall_timeout (e.g. 5s or 10s) to establish a firm cancellation deadline across all candidates and backoffs.

Fail-Safe Risk Policies (Fail-Open vs. Fail-Closed)

When upstream network feeds, fallback mirrors, and local disk caches fail concurrently, risk engines must enforce an unambiguous safety policy:

  • FailSafeMode::FailOpen (Permissive): If calendar data is missing or exceeds max_stale_cache_age, the engine assumes no economic blackout is active, permitting trading (weekend curfews remain enforced if enabled).
  • FailSafeMode::FailClosed (Defensive / Prop Firm Shield): If calendar data is missing, corrupted, or stale, the engine assumes an active blackout condition. A synthetic Fail-Closed Safety Blackout window is dynamically injected, immediately halting trades and protecting prop-firm challenge accounts from catastrophic disqualification during provider outages.
  • Preset Defaults: RedFolderConfig::prop_firm_strict and RedFolderConfig::conservative default to FailSafeMode::FailClosed.

Key Features

  • Zero Unsound Dependencies: Pure Rust implementation with strict compile-time invariants.
  • Fast In-Memory Matching: Compiles events into pre-sorted UTC intervals for $O(\log n)$ binary search lookup and single-digit microsecond query latency (~6–8 µs) during order placement, verified with Criterion benchmarks.
  • High-Concurrency Service Architecture: Granular RwLock synchronization separates engine intervals, registered worker states, and sync metadata, enabling hundreds of trading bots to query blackout statuses concurrently without serialization bottlenecks.
  • Concurrent Event Listeners: Trait-based event listeners are dispatched concurrently across Tokio tasks, preventing slow logging or webhook sinks from delaying order cancellation warnings.
  • Strong Domain Typing: Strongly typed Currency, Impact, and WeekendMode enums with flexible builder ergonomics accepting both typed variants and string literals.
  • Multi-Worker Granularity: Assign separate configurations to different strategies or symbols (e.g. EURUSD bot monitors USD + EUR; GBPJPY bot monitors GBP + JPY).
  • Multiple Integration Channels: Consume events via tokio::sync::broadcast, per-worker tokio::sync::mpsc, or asynchronous EventListener traits.
  • Prop Firm Preset Out of the Box: Configurable presets approximating FTMO, FundedNext, and The5ers rules.
  • Deterministic Historical Queries: Timestamp-aware evaluation enabling accurate backtesting and replay simulations.
  • Terminal CLI Included: Real-time terminal watcher and JSON query interface.

Repository Structure

redfolder/
├── .github/workflows/ci.yml       # Automated GitHub Actions CI (Check, Test, Clippy, Fmt)
├── Cargo.toml                     # Crate definition, metadata, and optional CLI dependencies
├── LICENSE                        # MIT License
├── README.md                      # Architecture documentation and usage guide
├── benches/
│   └── blackout_benchmark.rs      # Criterion benchmarks for engine compile and query matching
├── examples/
│   ├── quickstart.rs              # Basic one-shot calendar inspection
│   ├── event_driven_bot.rs        # Async event loop responding to warnings and halts
│   ├── prop_firm_guard.rs         # FTMO / FundedNext strict news rule validator
│   └── custom_listener.rs         # Trait-based EventListener callback integration
├── src/
│   ├── lib.rs                     # Public API exports and common prelude
│   ├── types.rs                   # Core domain models (Impact, BlackoutWindow, WindowEvent)
│   ├── config.rs                  # RedFolderConfig, builder, and prop-firm presets
│   ├── error.rs                   # Typed RedFolderError via thiserror
│   ├── events.rs                  # RedFolderEvent enum and EventListener trait
│   ├── curfew.rs                  # Weekend market close calculation engine
│   ├── calendar.rs                # HTTP client, JSON parser, and local cache manager
│   ├── engine.rs                  # In-memory interval compiler and window merge engine
│   ├── service.rs                 # Background Tokio task orchestrator
│   └── bin/
│       └── main.rs                # Terminal CLI binary (status, upcoming, watch, sync)
└── tests/
    └── integration_tests.rs       # End-to-end integration test battery

Installation

Add redfolder to your project's Cargo.toml:

[dependencies]
redfolder = "1.0"
tokio = { version = "1", features = ["full"] }

To install the standalone terminal command-line tool:

cargo install redfolder

Usage & Code Examples

1. Quickstart: Checking Active Blackout Status

Fetch the calendar schedule and verify whether a currency is currently within a blackout period:

use redfolder::calendar::CalendarClient;
use redfolder::config::RedFolderConfig;
use redfolder::engine::BlackoutEngine;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Fetch calendar (automatically cached to ~/.cache/redfolder/)
    let client = CalendarClient::new(None);
    let events = client.fetch_or_cached().await?;

    // 2. Configure 30-minute buffers for high-impact USD releases
    let config = RedFolderConfig::builder()
        .currencies(vec!["USD"])
        .impacts(vec!["High"])
        .buffer_minutes(30, 30)
        .build();

    // 3. Compile in-memory interval index
    let engine = BlackoutEngine::compile(&events, &[&config], chrono::Utc::now());

    // 4. Query blackout state atomically (prevents TOCTOU races)
    if let Some(current) = engine.status(&config) {
        println!("Blackout active: {} (ends in {} mins)", 
            current.summary_title(), current.remaining_minutes());
    } else {
        println!("Trading permitted: No active blackout for USD.");
    }

    Ok(())
}

2. Event-Driven Strategy Integration (Tokio Streams)

Integrate redfolder directly into an asynchronous strategy event loop:

use redfolder::prelude::*;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = RedFolderService::new(None);

    let config = RedFolderConfig::builder()
        .currencies(vec!["USD", "EUR"])
        .impacts(vec!["High"])
        .buffer_minutes(15, 15)
        .warning_minutes(5)
        .build();

    // Register worker and receive a dedicated event receiver
    let mut events = service.register_worker_events("eurusd_scalper", config).await?;
    service.start().await?;

    while let Some(event) = events.recv().await {
        match event {
            RedFolderEvent::BlackoutWarning { window, minutes_until_start, .. } => {
                println!("WARNING: '{}' starts in {} mins. Cancelling limit orders...", 
                    window.summary_title(), minutes_until_start);
            }
            RedFolderEvent::BlackoutStarted { window, .. } => {
                println!("BLACKOUT ACTIVE: {}. Halting strategy execution.", window.summary_title());
            }
            RedFolderEvent::BlackoutEnded { .. } => {
                println!("BLACKOUT CLEARED: Resuming normal execution.");
            }
            _ => {}
        }
    }

    Ok(())
}

[!TIP] Always register workers before invoking service.start().await?. If no enabled workers are registered, start() logs an informational warning and safely remains in ServiceState::Stopped without spawning unnecessary background loops.

3. Pre-Blackout Advance Warnings (Order Cancellation Guard)

Spread widening often occurs 1–3 minutes before official release times. By setting warning_minutes(5), your bot receives an advance event before the official blackout starts:

let config = RedFolderConfig::builder()
    .currencies(vec!["USD"])
    .impacts(vec!["High"])
    .buffer_minutes(15, 15)
    .warning_minutes(5) // Emits BlackoutWarning 5 minutes before start
    .build();

4. Prop Firm Challenge Preset (FTMO, FundedNext, The5ers)

Prop firm rules strictly prohibit opening trades or holding execution within 2–5 minutes of high-impact releases. Use the built-in preset:

use redfolder::config::RedFolderConfig;

// Preconfigured with:
// - 8 major currencies (USD, EUR, GBP, JPY, CAD, AUD, NZD, CHF)
// - High-impact (Red Folder) releases only
// - 5-minute pre-event buffer & 5-minute post-event buffer
// - Weekend curfew active from Friday 20:00 UTC until Monday 00:00 UTC
let prop_config = RedFolderConfig::prop_firm_strict();

[!NOTE] Prop Firm Qualification & Compliance: Built-in presets approximate standard industry guidelines (such as FTMO, FundedNext, and The5ers). Specific compliance requirements vary by account type (e.g. Swing vs. Standard), challenge stage, instrument, and effective terms. Traders should verify terms directly with their funding provider and customize buffers accordingly.

5. Custom Trait-Based Event Listener Callback

Implement the EventListener trait to hook into external logging, Telegram bots, or compliance dashboards:

use redfolder::events::{EventListener, RedFolderEvent};
use redfolder::prelude::*;
use std::sync::Arc;

struct SlackAlertNotifier;

#[async_trait::async_trait]
impl EventListener for SlackAlertNotifier {
    async fn on_event(&self, event: &RedFolderEvent) {
        match event {
            RedFolderEvent::BlackoutStarted { window, worker_id } => {
                println!("[Audit] Worker {:?} entered blackout: {}", worker_id, window.summary_title());
            }
            RedFolderEvent::BlackoutEnded { worker_id, .. } => {
                println!("[Audit] Worker {:?} exited blackout.", worker_id);
            }
            _ => {}
        }
    }
}

// Register with service
let service = RedFolderService::new(None);
service.add_listener(Arc::new(SlackAlertNotifier)).await;

6. Multi-Worker Symbol Isolation

Run multiple bots concurrently with strict currency isolation. An event on USD halts the USD worker while leaving the EUR worker uninterrupted:

let usd_config = RedFolderConfig::builder().currencies(vec!["USD"]).build();
let eur_config = RedFolderConfig::builder().currencies(vec!["EUR"]).build();

let mut usd_events = service.register_worker_events("usd_bot", usd_config).await?;
let mut eur_events = service.register_worker_events("eur_bot", eur_config).await?;

7. Terminal Command-Line Interface (CLI)

The redfolder CLI provides terminal tools for live operations:

Status Query

# Check if USD is currently in a blackout window
redfolder status --currency USD

# Output structured JSON for shell scripting or monitoring daemons
redfolder status --currency USD --json

Upcoming Releases

# View all blackout windows scheduled within the next 48 hours
redfolder upcoming --hours 48 --currency USD --impact High

Real-Time Watcher

# Live terminal monitor with real-time countdown
redfolder watch --currency USD --interval 5

Calendar Cache Synchronization

# Manually synchronize calendar releases to disk
redfolder sync

API Reference

RedFolderService

Method Signature Description
new fn(Option<PathBuf>) -> Self Initializes service with optional cache directory (defaults to platform cache dir).
with_client fn(CalendarClient) -> Self Initializes service using a preconfigured CalendarClient instance.
state async fn(&self) -> ServiceState Returns the current lifecycle state (Stopped, Starting, Running, Stopping).
is_running async fn(&self) -> bool Checks if background worker tasks are active (state == ServiceState::Running).
subscribe fn(&self) -> broadcast::Receiver<RedFolderEvent> Subscribes to global broadcast bus receiving all system events.
add_listener async fn(&self, Arc<dyn EventListener>) Attaches an asynchronous trait-based callback listener (guarded with execution timeout).
register_worker_events async fn(&self, &str, RedFolderConfig) -> Result<mpsc::UnboundedReceiver<RedFolderEvent>> Validates config, guards against duplicate registrations, and returns a typed stream of scoped events.
register_worker async fn(&self, &str, RedFolderConfig) -> Result<mpsc::UnboundedReceiver<BlackoutNotification>> Legacy registration; validates config and guards against duplicate worker registrations.
reregister_worker_events async fn(&self, &str, RedFolderConfig) -> Result<mpsc::UnboundedReceiver<RedFolderEvent>> Re-registers an existing worker with an updated configuration, replacing its event stream.
reregister_worker async fn(&self, &str, RedFolderConfig) -> Result<mpsc::UnboundedReceiver<BlackoutNotification>> Re-registers an existing worker with an updated configuration, replacing its notification stream.
unregister_worker async fn(&self, &str) Unregisters worker, cleans up state, and recalculates transition schedule.
windows_for_worker async fn(&self, &str) -> Vec<BlackoutWindow> Returns active and upcoming blackout windows derived specifically for the worker's buffers.
start async fn(&self) -> Result<()> Starts background daily refresh and transition-driven evaluation tasks. Reversible on error.
stop async fn(&self) Gracefully terminates all background tasks and awaits their exit.
set_check_interval async fn(&self, Duration) -> Result<()> Configures evaluation frequency; validates interval is at least 100ms to prevent busy loops.
refresh async fn(&self) -> Result<()> Synchronizes calendar and recompiles blackout windows (allowing cached fallback).
force_refresh async fn(&self) -> Result<()> Forces immediate network download from remote API and window recompilation, bypassing cache.
is_blackout async fn(&self, &str) -> bool Checks if a specific registered worker is currently in blackout.
current_window async fn(&self, &str) -> Option<BlackoutWindow> Returns active window details for a specific worker.
get_upcoming_blackouts async fn(&self, &str, u32) -> Vec<BlackoutWindow> Returns upcoming blackout windows within $N$ hours.
last_sync_time async fn(&self) -> Option<DateTime<Utc>> Returns timestamp of the most recent successful calendar synchronization.
last_sync_error async fn(&self) -> Option<String> Returns description of the most recent failed sync attempt, or None if healthy.
is_calendar_stale async fn(&self, Duration) -> bool Checks if the calendar has not successfully synchronized within the specified duration.

BlackoutEngine

Method Signature Description
compile fn(&[RawCalendarEvent], &[&RedFolderConfig], DateTime<Utc>) -> Self Compiles raw releases and curfew rules into merged blackout intervals (defaulting to UTC).
compile_with_tz fn(&[RawCalendarEvent], &[&RedFolderConfig], DateTime<Utc>, Option<chrono_tz::Tz>) -> Self Compiles events using an explicit source timezone for naive timestamps.
windows_for_config fn(&self, &RedFolderConfig, DateTime<Utc>) -> Vec<BlackoutWindow> Derives isolated worker-specific blackout intervals respecting custom buffers and policies.
windows fn(&self) -> &[BlackoutWindow] Accesses pooled precompiled windows across configurations for diagnostic reference.
is_blackout fn(&self, &RedFolderConfig) -> bool Checks if the current UTC time falls within any active window.
is_blackout_at fn(&self, &RedFolderConfig, DateTime<Utc>) -> bool Evaluates blackout status at an arbitrary timestamp using half-open [start, end).
current_window fn(&self, &RedFolderConfig) -> Option<BlackoutWindow> Returns the active BlackoutWindow matching configuration.
current_window_at fn(&self, &RedFolderConfig, DateTime<Utc>) -> Option<BlackoutWindow> Returns the active BlackoutWindow matching configuration at an arbitrary timestamp.
status fn(&self, &RedFolderConfig) -> Option<BlackoutWindow> Atomically queries active blackout status and returns the current window (eliminates TOCTOU races).
status_at fn(&self, &RedFolderConfig, DateTime<Utc>) -> Option<BlackoutWindow> Atomically evaluates status and active window at an arbitrary timestamp.
upcoming_blackouts fn(&self, &RedFolderConfig, u32) -> Vec<BlackoutWindow> Lists matching windows starting within $N$ hours.

CalendarClient

Method Signature Description
new fn(Option<PathBuf>) -> Self Creates client with standard browser User-Agent and default cache.
without_cache fn() -> Self Creates client strictly performing live network requests.
with_user_agent fn(Option<PathBuf>, &str) -> Result<Self> Creates client with custom User-Agent and optional cache directory.
with_fallback_url fn(self, impl Into<String>) -> Self Configures secondary mirror URL for automated failover on network/HTTP errors.
with_fallback_urls fn(self, impl IntoIterator<Item = S>) -> Self Configures multiple fallback mirror URLs in failover priority order.
with_max_response_bytes fn(self, usize) -> Self Enforces upper bound on response payload body (default 10 MiB) to prevent OOM DOS.
with_max_event_count fn(self, usize) -> Self Enforces upper limit on parsed calendar events (default 50,000).
with_max_retries fn(self, usize) -> Self Sets maximum HTTP retry attempts on transient network errors (default 3).
with_backoff fn(self, Duration, Duration) -> Self Configures initial backoff delay and max retry-after cap for exponential backoff.
with_overall_timeout fn(self, Duration) -> Self Enforces hard wall-clock latency ceiling across the entire fetch-and-retry cycle.
with_integrity_validator fn(self, impl Fn(&[RawCalendarEvent]) -> Result<()>) -> Self Injects custom cryptographic verification or semantic sanity checks on fetched events.
with_timezone fn(self, chrono_tz::Tz) -> Self Configures default source timezone for resolving naive calendar timestamps.
with_max_stale_age fn(self, Option<Duration>) -> Self Sets maximum allowable cache age for fallback on network failure.
with_ttl fn(self, Duration) -> Self Configures cache Time-To-Live before remote re-fetch is permitted.
default_cache_dir fn() -> PathBuf Resolves cross-platform cache directory (%LOCALAPPDATA%, XDG, macOS, fallback temp).
fetch_remote async fn(&self) -> Result<Vec<RawCalendarEvent>> Performs HTTP GET against FairEconomy feed with 429/408/5xx retry and Retry-After support.
force_fetch async fn(&self) -> Result<Vec<RawCalendarEvent>> Fetches fresh schedule directly from remote API, bypassing cache while saving to disk.
fetch_or_cached async fn(&self) -> Result<Vec<RawCalendarEvent>> Fetches remote schedule, verifying cache metadata and bounded staleness on failure.
save_cache fn(&self, &[RawCalendarEvent]) -> Result<()> Atomically writes JSON-serialized events using PID + nanoseconds + atomic counter.
load_cache_data fn(&self) -> Option<CachedCalendarData> Loads structured cache validating event_count == events.len().

RedFolderConfig

Method / Associated Fn Signature Description
builder fn() -> RedFolderConfigBuilder Creates a fluent builder with sensible defaults (USD, High impact, 30m buffers).
prop_firm_strict fn() -> Self High-risk prop firm preset: 8 major currencies, High impact, 5m buffers, weekend curfew, and FailSafeMode::FailClosed.
conservative fn() -> Self Wide buffer preset: 8 major currencies, High + Medium impacts, 15m buffers, weekend curfew, and FailSafeMode::FailClosed.
crypto_curfew fn() -> Self Pure weekend curfew preset without macroeconomic currency filters.
validate fn(&self) -> Result<()> Performs semantic validation on buffers, curfews, and intervals (unconditionally checks weekend parameters).
validate_strict fn(&self) -> Result<()> Strict validation ensuring currency and impact lists contain no blank strings and recognized codes.

RedFolderConfigBuilder

Method Signature Description
currencies fn(self, impl IntoIterator<Item = impl IntoCurrency>) -> Self Sets target currencies (accepts Currency variants like Currency::USD or string slices ["USD", "EUR"]).
impacts fn(self, impl IntoIterator<Item = impl IntoImpact>) -> Self Sets impact tiers to filter (accepts Impact variants like Impact::High or string slices ["High", "Red"]).
buffer_minutes fn(self, u32, u32) -> Self Sets pre-event and post-event blackout safety buffers in minutes.
warning_minutes fn(self, u32) -> Self Configures advance warning alert threshold prior to blackout onset.
merge_threshold_minutes fn(self, u32) -> Self Maximum gap between successive events to merge into a single window.
weekend_curfew fn(self, bool, &str, &str, impl IntoWeekendMode) -> Self Enables and configures weekend curfew start, end, and mode (accepts WeekendMode, &str, or String).
include_all_day fn(self, bool) -> Self Controls whether all-day events (e.g. bank holidays) trigger 24h blackouts.
include_tentative fn(self, bool) -> Self Controls whether unscheduled tentative releases trigger blackouts.
fail_safe_mode fn(self, FailSafeMode) -> Self Sets safety policy (FailOpen or FailClosed) for handling stale or failed feeds.
build fn(self) -> RedFolderConfig Validates parameters and constructs config; panics if invalid.
try_build fn(self) -> Result<RedFolderConfig> Validates parameters and returns typed Result<RedFolderConfig, RedFolderError>.
try_build_strict fn(self) -> Result<RedFolderConfig> Strict validation rejecting non-standard currency/impact typos; returns typed Result.
build_strict fn(self) -> RedFolderConfig Validates strictly; panics if non-standard or invalid parameters are provided.

[!NOTE] Permissive Defaults vs. Strict Validation: By default, validate() and try_build() allow custom non-standard currency codes (e.g. "XAU", "BTC", "TRY") via Currency::Custom and Impact::Custom. When loading configuration from external files (YAML, JSON, TOML) or untrusted user input, prefer validate_strict() or try_build_strict() to reject typos like "USDD" at startup instead of silently matching zero events.

Types & Domain Models

  • RedFolderEvent: Typed enum (BlackoutWarning, BlackoutStarted, BlackoutEnded, CalendarUpdated, CalendarSyncFailed).
  • FailSafeMode: Policy enum (FailOpen, FailClosed). In FailClosed mode, missing or stale calendar feeds trigger an immediate safety blackout to protect prop firm accounts from unexpected macroeconomic volatility.
  • CustomEventKind: Typed classification enum (WeekendCurfew, FailClosedSafety) identifying synthetic blackout windows. WindowEvent provides helper accessors is_weekend_curfew() and is_fail_closed_safety().
  • EventTiming: Precision timing enum (Exact(DateTime<Utc>), AllDay(NaiveDate), TentativeDate(NaiveDate)).
  • ServiceState: Service lifecycle enum (Stopped, Starting, Running, Stopping).
  • BlackoutWindow: Struct containing start: DateTime<Utc>, end: DateTime<Utc>, and events: Vec<WindowEvent>. Uses standard half-open interval semantics [start, end). Provides helper methods remaining_minutes(), duration_minutes(), is_active(), and summary_title().
  • Currency: Strongly-typed enum with variants USD, EUR, GBP, JPY, CAD, AUD, NZD, CHF, and Custom(String). Supports case-insensitive string parsing, matching, and deserialization.
  • Impact: Enum with variants High, Medium, Low, NonEconomic, Custom(String). Supports case-insensitive string matching ("red", "high").
  • WeekendMode: Enum with variants Short (Friday evening window) and Weekend (Friday evening through Monday 00:00 UTC). Supports case-insensitive deserialization and default derivation.

Testing & Quality Assurance

redfolder includes an automated test battery with 101 unit and integration tests (51 unit + 50 integration) covering interval calculations, state machines, and resilience guarantees.

Run the test suite:

cargo test --all-targets --all-features

Run code formatting and linter checks:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Failure Modes & Edge Case Matrix

Scenario / Injected Condition Expected Invariant / System Behavior Status
HTTP 429 Rate Limit from API Retries transient 429 honoring Retry-After; falls back to local cache if exhausted. Verified
Network Partition / Host Offline Transparently serves existing cached calendar until network recovers. Verified
Startup Failure (Network & Cache Fail) start() errors cleanly and resets state to Stopped; retries succeed without lockout. Verified
Rapid Restart / Task Overlap stop() cleanly joins previous tasks; restarting creates zero duplicate loops. Verified
Transition-Driven Timing Emits alerts at exact scheduled second rather than waiting for 15s polling cycle. Verified
Evaluation Loop Lower Bound set_check_interval rejects zero or sub-100ms durations to prevent busy loops. Verified
CalendarUpdated Event Dispatch Dispatches calendar sync updates to both broadcast bus and EventListener callbacks. Verified
CalendarSyncFailed Event Dispatch Dispatches sync error event on network/parse failure; midnight task retries every 15m. Verified
Duplicate Worker Registration Protection Rejects duplicate worker IDs with typed error; updates require reregister_*. Verified
Atomic Status Accessor engine.status(&config) eliminates TOCTOU races between status check and window retrieval. Verified
Cross-Platform Cache Resolution Resolves cache directory across Linux XDG, Windows %LOCALAPPDATA%/%APPDATA%, macOS, and temp. Verified
Atomic Cache Write Resilience Writes via PID + nanosecond + atomic counter tmp file and atomic rename; prevents write collision. Verified
Concurrent Refresh Serialization Serializes concurrent refresh() / force_refresh() calls; eliminates race conditions. Verified
Cache Event Count Mismatch load_cache_data detects corrupted/truncated cache (event_count != len) and rejects it. Verified
Bounded Stale Cache Fallback Rejects cache older than max_stale_cache_age on network failure; accepts within limit. Verified
Legacy Cache Staleness Protection Rejects unversioned/unknown-age legacy cache files during stale fallback. Verified
Impact & Currency Alias Normalization Matches "Red" vs "High", "med" vs "Medium", and currencies case-insensitively. Verified
Semantic Config & Blank Item Checks Rejects blank or empty strings in currency/impact lists; offers validate_strict(). Verified
All-Day & Tentative Events Default config ignores all-day/tentative events to avoid fake midnight spikes; 24h opt-in. Verified
Missing Release Times Date-only events without time parsed as TentativeDate, preventing fake midnight spikes. Verified
Timezone-Aware All-Day Boundaries Interprets all-day events in configured calendar timezone (e.g. America/New_York). Verified
Naive Timestamps & DST Transition Converts naive times with EDT/EST DST accuracy; gaps advance 1h to valid daylight instant. Verified
Half-Open Interval Semantics Window is active at exact start and inactive at exact end [start, end). Verified
Worker Registered in Active Blackout Newly registered worker immediately receives active blackout notification. Verified
Overlapping Events within Threshold Merges closely spaced releases into single uninterrupted BlackoutWindow. Verified
Zero Pre-Event Buffer (before_min: 0) Window begins precisely at scheduled event time; does not default to 30 min. Verified
Weekend Curfew in weekend Mode Extends blackout window 51.5 hours through to Monday 00:00 UTC. Verified
Cross-Midnight Short Curfew 23:00 -> 01:00 curfew rolls over to Saturday without inverting intervals. Verified
Deterministic Timestamp Replay Historical queries evaluate deterministically without depending on Utc::now(). Verified
Empty Upstream Feed Protection Preserves known-good cache if upstream returns 0 events or invalid array. Verified
Service Concurrency & Restart Multiple start() calls error cleanly; start -> stop -> start restarts properly. Verified
OOM Response / Payload Size Exceeded fetch_remote enforces max_response_bytes via Content-Length pre-check and streaming chunk counter, rejecting oversized payloads. Verified
Cache Tampering / Checksum Mismatch load_cache_data verifies SHA-256 digest against CacheMetadata.sha256; rejects tampered or corrupted files. Verified
Upstream Feed Primary Outage / Failover fetch_remote automatically fails over to configured secondary mirrors in order when primary fails. Verified
Cache File & Directory Permissions Enforces POSIX 0o700 directory and 0o600 file permissions on Unix systems to protect against unauthorized multi-user access. Verified
Sync Failure under Fail-Closed Policy Automatically injects a synthetic Fail-Closed Safety Blackout window for FailClosed workers, halting trading during feed outages. Verified
Retry Latency Ceiling Exceeded Aborts retry loop once cumulative duration exceeds overall_timeout (default 30s), avoiding stalled caller tasks. Verified
Disabled Weekend Config Validation validate() unconditionally checks weekend curfew parameters even when weekend_enabled is false, preventing latent runtime bugs. Verified
Back-to-Back News Interval Merging Merges overlapping releases into unified intervals verified via $O(\log n)$ binary search lookup. Verified
Weekend & Economic Overlap Seamlessly connects late Friday economic releases with weekend market curfews without coverage gap. Verified
Stale Calendar Policy: Fail-Open Maintains normal trading execution when calendar synchronization fails under FailOpen mode. Verified
Stale Calendar Policy: Fail-Closed Defensively triggers continuous safety blackout during feed outages under FailClosed prop firm mode. Verified
Daylight Saving Time (DST) Transitions Resolves spring-forward gaps and fall-back ambiguities in US Eastern / configured timezones deterministically. Verified
CLI Binary Subcommands & JSON Output Verifies status, upcoming, and flag parsing across isolated environments via command execution. Verified

Performance & Empirical Benchmarks

redfolder includes a Criterion benchmark battery measuring engine compilation, dynamic worker window derivation, and blackout query latency.

Benchmark Environment & Methodology

  • Hardware / Architecture: Representative measurements on modern x86_64 hardware (AMD Ryzen / Intel Core class, Linux x86_64, release mode with link-time optimization). Actual latencies vary based on CPU clock, cache hierarchy, and system load.
  • Dataset: 50 raw macroeconomic calendar events across 4 currencies (USD, EUR, GBP, JPY).
  • Configuration: Strict prop firm challenge rules (prop_firm_strict: 8 currencies, 5-minute pre/post buffers, weekend curfew enabled).

Empirical Criterion Measurements

The following representative measurements illustrate sub-microsecond to low-microsecond throughput under typical server workloads:

Operation Benchmark Name Latency (Mean) 95% Confidence Interval Description
Engine Compilation engine_compile_50_events 24.02 µs [23.57 µs – 24.52 µs] Parses, sorts, filters, and merges 50 raw events into UTC intervals
Runtime Blackout Check is_blackout_query 12.26 µs [12.17 µs – 12.37 µs] Evaluates active blackout state across currencies, impacts, and weekend curfew
Deterministic Timestamp Query is_blackout_at_query 10.76 µs [10.60 µs – 10.96 µs] Historical or future evaluation point query for tick-level backtesting
Worker Window Derivation windows_for_config 13.10 µs [12.92 µs – 13.36 µs] Derives isolated worker-specific blackout intervals from parsed events
Atomic Status Accessor status_query 13.09 µs [13.01 µs – 13.17 µs] Atomically evaluates status and extracts active window in a single pass

To reproduce these benchmarks:

cargo bench --bench blackout_benchmark

Troubleshooting & FAQ

1. "HTTP 429 Too Many Requests from nfs.faireconomy.media"

  • Cause: FairEconomy / Cloudflare enforces strict rate limits against automated clients.
  • Fix: redfolder automatically caches events locally to avoid frequent requests. Avoid calling fetch_remote() in tight loops; use fetch_or_cached() or run RedFolderService which syncs once daily at midnight UTC.

2. "Why is a blackout active even though the event time passed?"

  • Cause: The configuration specifies an after_min post-event buffer (e.g. 15 or 30 minutes). Volatility and spread expansion persist after high-impact announcements.
  • Fix: Adjust buffer_minutes(before, after) or inspect window.end to view when spreads are projected to normalize.

3. "How do I filter for multiple currencies simultaneously?"

  • Cause: Using single-currency configs on cross-pairs (e.g. trading EUR/USD requires monitoring both EUR and USD events).
  • Fix: Pass all relevant currency codes to the builder: 
    let config = RedFolderConfig::builder()
    .currencies(vec!["EUR", "USD"])
    .build();

4. "Can I run redfolder without local file caching?"

  • Cause: Embedded systems or restricted environments where filesystem access is read-only.
  • Fix: Instantiate the client with CalendarClient::without_cache().

5. "How do I configure backup mirrors or custom endpoints?"

  • Cause: Institutional setups requiring internal proxies or redundant mirrors if the primary feed is unreachable.
  • Fix: Chain .with_fallback_url() or .with_fallback_urls() on the client: 
    let client = CalendarClient::new(None)
    .with_fallback_url("https://internal-mirror.corp/calendar.json");
let service = RedFolderService::with_client(client);

6. "How does redfolder protect prop firm accounts during feed outages?"

  • Cause: If external feeds are blocked and the local cache expires, trading during an unannounced CPI release would breach prop firm rules.
  • Fix: Use RedFolderConfig::prop_firm_strict() or explicitly configure .fail_safe_mode(FailSafeMode::FailClosed). If synchronization fails or the cache exceeds staleness limits, a synthetic safety blackout window is immediately enforced, pausing trades until verified calendar data is restored.

Author & Contributions

Created and maintained by 0xbarss.

Contributions, bug reports, and suggestions are welcome! Please check out CONTRIBUTING.md for architecture guidelines, code standards, and local testing instructions before opening a pull request at github.com/0xbarss/redfolder.

License & Disclaimer

This project is licensed under the MIT License.

Disclaimer: This is an open-source tool designed for risk management and educational purposes. Trading foreign exchange, CFDs, and cryptocurrencies carries high risk. Past calendar accuracy does not guarantee future event timing. Always verify news rules with your broker or prop firm before deploying automated algorithms.