Skip to main content
The cdn module provides multi-source Content Delivery Network (CDN) management. It includes automatic fallback, health tracking, circuit breaker patterns, and source selection. Data fetching continues when individual CDN sources fail, experience outages, or degrade in performance.

Overview

The CDN system is a core component of tif1’s data fetching infrastructure. It is designed for availability, reliability, and performance when it retrieves Formula 1 data from remote sources. The system implements circuit breaker logic, automatic failover, health monitoring, and priority-based routing. These patterns keep the application operational under adverse network conditions.

Why CDN Management Matters

Formula 1 data fetching presents unique challenges:
  • Data availability: Historical and live session data must be reliably accessible across multiple seasons (2018-2026+)
  • Geographic distribution: Users worldwide need fast access regardless of location
  • Network resilience: CDN providers can experience outages, rate limiting, or degraded performance
  • Bandwidth optimization: Session data can be large (telemetry, lap times, weather data)
  • Cost efficiency: Proper CDN selection and fallback minimize redundant requests and bandwidth waste
The tif1 CDN system addresses these challenges through multi-source management. This management keeps the application fast and reliable.

Core Capabilities

1. Multi-Source Fallback with Automatic Failover

The CDN manager maintains a prioritized list of CDN sources and automatically tries alternative sources when the primary source fails. This ensures high availability even when individual CDN providers experience issues. How it works:
  • Sources are tried in priority order (lowest priority number first)
  • If a source fails, the next available source is tried immediately
  • Successful requests reset the failure counter for that source
  • Failed sources are temporarily disabled after reaching the failure threshold
  • A 404 or 403 is a per-file refusal, not a failure. The next source is tried (raced, on the async path) and the counter is untouched. jsDelivr returns 403 for uncached files of a repository over its 50 MB package limit. Counting those would disable the fastest mirror for the rest of the process
  • try_sources() reads the status from the response attribute of the exception, as niquests HTTPError carries it. For a NetworkError without a response, such as the one the sync PayloadLoader transport raises, it reads the status_code context key. A 403 is a refusal on both paths
Benefits:
  • Zero-downtime failover: Automatic switching to backup sources without user intervention
  • Counter reset on success: A successful request sets the failure count of that source back to 0
  • Configurable priorities: Define preferred CDN providers based on performance, cost, or geographic location

2. Health Tracking and Circuit Breaker Pattern

Each CDN source is continuously monitored for reliability. The circuit breaker pattern prevents wasting time on consistently failing sources by temporarily disabling them after repeated failures. Circuit breaker states:
  • Closed (healthy): 0-2 failures—source is available and used normally
  • Open (disabled): 3+ failures—source is excluded from get_sources() until reset
  • Recovery: There is no automatic half-open state. try_sources() never tries an open source, so it stays open until a call to reset(), reload(), or mark_success(name)
Failure threshold:
  • Default: 3 consecutive failures before disabling. Transport errors, timeouts, and 5xx responses count. A 404 or a 403 never counts
  • Configurable via _max_failures attribute
  • Failures are tracked per-source in _failure_counts dictionary
Benefits:
  • Reduced latency: Skip known-bad sources instead of waiting for timeouts
  • Prevent cascading failures: Isolate failing sources to protect overall system health
  • Manual recovery: Call reset() after a network outage to re-enable every source

3. Priority-Based Routing

Sources are assigned priority levels (integer values, lower = higher priority) that determine the order in which they are tried. Priority levels support these strategies:
  • Optimize for performance: Set fastest CDN as priority 1
  • Optimize for cost: Set free/unlimited CDN as priority 1, paid CDN as backup
  • Optimize for geography: Set regional CDN as priority 1 for users in that region
  • Implement tiered fallback: Primary (priority 1) → Regional backup (priority 2) → Global backup (priority 3)
Priority behavior:
  • Sources are sorted by priority (ascending order: 1, 2, 3, …)
  • Sources with the same priority maintain their insertion order
  • Priority can be set when creating CDNSource objects
  • Sources are automatically re-sorted when added via add_source()
Measured latency adjusts the order. Each source keeps a moving average of its request latency (record_latency(), latency_estimate()). A source can measure more than twice as slow as a lower-priority source, with at least eight samples on each. Then get_sources() moves it behind that source for the rest of the process. Sources without samples keep their configured position. reset() clears the estimates. Stalled requests are hedged. In the async pipeline the first source’s request waits hedge_delay() seconds. That delay is two times the source’s moving average, clamped between 1 second and cdn_hedge_max_delay. A request that has not answered by then is re-issued on the next source, and the first usable answer wins. The abandoned request counts as a latency sample at the hedge delay, so a slow mirror’s estimate stays honest. A healthy source sends one request per file. cdn_hedge=false restores the one-after-the-other loop.

4. JSON Minification Support

The cdn_use_minification option makes tif1 request file.min.json in place of file.json from custom mirrors. It is off by default.
The default CDNs ignore the option. The TracingInsights data repositories have no .min.json files, and jsDelivr minifies only JavaScript and CSS. jsDelivr, Hugging Face and StaticDelivr all return 404 for them (checked 2026-10-14). tif1 never sends a minified request to those three sources.
How it works:
  • When use_minification=True on a CDNSource, URLs are transformed: file.json → file.min.json
  • The source must serve the .min.json file. Otherwise the request returns 404 and tif1 moves to the next source
  • The global cdn_use_minification option applies the flag to custom mirrors only. jsDelivr, Hugging Face and StaticDelivr sources always keep it off
When to enable:
  • Only for a custom mirror that serves a .min.json copy of each payload. Set use_minification=True on that CDNSource only

5. Configurable Custom Sources

Add custom CDN endpoints to support:
  • Private mirrors: Host a private copy of F1 data for guaranteed availability
  • Regional CDNs: Optimize performance for specific geographic regions
  • Corporate proxies: Route requests through internal infrastructure
  • Development/testing: Point to local servers or staging environments
  • Backup sources: Add redundant sources for applications that require high availability
Configuration methods:
  1. Programmatic: Use add_source() method to add sources at runtime
  2. Config file: Define sources in ~/.tif1rc JSON configuration
  3. Environment variable: Set TIF1_CDNS comma-separated list
  4. Runtime config: Call config.set("cdns", [...]), then get_cdn_manager().reload()

6. Singleton Pattern for Global State

The CDN manager uses a singleton pattern to ensure consistent state across the entire application:
  • Single source of truth: All data fetching operations use the same CDN manager instance
  • Shared health tracking: Failure counts and circuit breaker state are global
  • Consistent configuration: Configuration changes affect all subsequent requests
  • Thread-safe reads: Multiple threads can safely read CDN sources
  • Memory efficient: Only one CDN manager instance exists per process

7. Transparent Integration

The CDN system operates in the background. Applications typically do not interact with it directly:
  • Automatic initialization: The CDN manager is created when tif1.cdn is first imported (the first session load imports it)
  • Zero-configuration default: Works out-of-the-box with the jsDelivr → Hugging Face → StaticDelivr chain
  • Session API integration: Session.load() automatically uses CDN system
  • Error handling: Network errors are caught and trigger automatic fallback
  • Logging: Debug-level logs show which CDN source is being used

Architecture

The CDN system consists of three main components working together:

1. CDNSource (Data Class)

Represents a single CDN endpoint with configuration:
Responsibilities:
  • Store CDN configuration (URL, priority, settings)
  • Format complete URLs for specific resources via format_url()
  • Support minification by transforming file paths

2. CDNManager (Orchestrator)

Manages multiple CDN sources and implements fallback logic:
Responsibilities:
  • Initialize sources from configuration (file, env vars, defaults)
  • Validate source URLs (HTTPS only, block raw.githubusercontent.com)
  • Track health via failure counters (circuit breaker pattern)
  • Provide available sources via get_sources() (filters disabled/failed sources)
  • Implement fallback logic via try_sources() (tries sources in priority order). Async fetchers use the async counterpart try_sources_async(year, gp, session, path, fetch_func). It walks the same source chain with awaitable fetch functions
  • Manage source lifecycle (add_source(), reset(), reload())

3. Global Singleton

A single CDNManager instance shared across the application:
Responsibilities:
  • Ensure consistent CDN state across all data fetching operations
  • Provide global access point via get_cdn_manager() function
  • Initialize once on first import, reuse for all subsequent calls

Data Flow

Here’s how a typical data fetch flows through the CDN system:

When to Use This API

Most users never need to interact with the CDN API directly. It works transparently in the background. Use this API in these situations:

Direct Interaction Scenarios

  1. Adding custom CDN sources: Add a private mirror, regional CDN, or backup source
  2. Monitoring CDN health: Track which sources are failing, or build health dashboards
  3. Debugging network issues: Understand which CDN is used or why requests fail
  4. Checking the minification flag: Keep it off, because the default CDNs return 404 for .min.json files
  5. Testing fallback behavior: Verify that the application handles CDN failures gracefully
  6. Implementing custom retry logic: Build a custom data fetching layer
  7. Recovering from widespread failures: The network was down, and all sources now need a reset

Configuration Scenarios

  1. Setting up regional CDNs: Optimize performance for specific geographic regions
  2. Implementing cost optimization: Use free CDN as primary, paid CDN as backup
  3. Corporate environments: Route through internal proxies or mirrors
  4. Development/testing: Point to local servers or staging environments
  5. High-availability requirements: Add multiple backup sources for production applications
Never use raw.githubusercontent.com as a CDN source. GitHub rate-limits raw file downloads, and one session load can send hundreds of requests. tif1 skips these URLs (with a warning) when it builds the source list. Use the default sources or a custom HTTPS mirror instead. (The live event schedule in tif1.events is the one deliberate exception: a single schedule_{year}.json per season, cached for schedule_ttl_hours, fetched outside the CDN chain.)
The default configuration uses three sources in priority order. The sources are jsDelivr (primary), Hugging Face buckets (https://huggingface.co/buckets/tracinginsights, fallback), and StaticDelivr (last resort).jsDelivr and StaticDelivr serve the TracingInsights GitHub data repositories. The Hugging Face buckets mirror the same repositories, so they stay available when the GitHub-backed CDNs fail.For most users, the default configuration needs no changes.

Quick Start

For most use cases, the CDN API needs no direct interaction. It works transparently in the background. These common operations serve advanced use cases:

Basic Usage (Transparent)

Inspecting CDN Status

Adding Custom CDN Sources

Enabling Minification

Keep the global cdn_use_minification option off: the default CDNs do not serve .min.json files (see JSON Minification Support). Enable minification only on a custom source that serves minified copies:

Monitoring and Recovery

Configuration via File

Instead of programmatic configuration, define CDN sources in ~/.tif1rc:

Configuration via Environment Variables


API Reference

Module-Level Functions

get_cdn_manager()

Returns the global CDN manager singleton instance. This function always returns the same CDNManager object, ensuring consistent CDN state across the entire application. Why Singleton Pattern? The singleton pattern is used because:
  • Shared health tracking: CDN health monitoring must be consistent across all data fetching operations
  • Global configuration: Configuration changes should affect all subsequent requests
  • Consistent failure counts: Circuit breaker state must be global to prevent redundant retries
  • Memory efficiency: Only one CDN manager instance exists per process
  • Thread safety: Single instance simplifies concurrent access patterns
Returns:
  • CDNManager: The global singleton instance
Thread Safety: The CDN manager is thread-safe for read operations (getting sources, checking health). Modify sources or mark failures from a single thread, or use appropriate synchronization:
  • Thread-safe operations: get_sources(), reading sources list, reading _failure_counts
  • Not thread-safe: add_source(), mark_failure(), mark_success(), reset()
For multi-threaded applications, consider:
  • Configure all sources during initialization (single-threaded)
  • Only read sources during concurrent execution
  • Use locks to modify sources from multiple threads
Example: Basic Usage
Example: Health Dashboard
Example: Singleton Verification

CDNManager Class

The CDNManager class is the core orchestrator of the multi-source CDN system. It maintains a list of CDN sources and tracks their health. It implements fallback logic with circuit breaker patterns. It also provides methods for managing sources.

Initialization

The CDN manager initializes once, when tif1.cdn is first imported. The first session load imports it. Configuration changes made after that point do not change the existing manager until reload() runs. During initialization (and in reload()), the following steps occur: Initialization Sequence:
  1. Load configuration: Reads the cdns list from the tif1 config. The config merges ~/.tif1rc and the TIF1_CDNS environment variable
  2. Parse source URLs: The config splits a comma-separated TIF1_CDNS value into individual URLs
  3. Validate sources: Drops URLs that are not HTTPS and URLs on the blocked host raw.githubusercontent.com
  4. Create CDNSource objects: Wraps each URL in a CDNSource. The name is jsDelivr, HuggingFace, StaticDelivr, or CDN {n} for other hosts
  5. Assign priorities: Each source gets its 1-based position in the cdns list as its priority, so the list order is the try order
  6. Initialize health tracking: Sets up _failure_counts dictionary with all sources at 0 failures and sets _max_failures to 3
  7. Fallback to defaults: If no valid sources found, uses jsDelivr, Hugging Face buckets, and StaticDelivr as defaults
Configuration Sources (in order of precedence):
  1. Environment variable: TIF1_CDNS (comma-separated list of HTTPS URLs)
  2. Config file: The file named by TIF1_CONFIG_FILE, ./.tif1rc (if TIF1_TRUST_CWD_CONFIG=true), or ~/.tif1rc; tif1 reads the first one that exists
  3. Default: https://cdn.jsdelivr.net/gh/TracingInsights, https://huggingface.co/buckets/tracinginsights, and https://cdn.staticdelivr.com/gh/TracingInsights (in priority order)
Validation Rules:
  • URLs must start with https:// (HTTP is rejected for security)
  • URLs containing raw.githubusercontent.com are rejected (rate limits)
  • A raw.githubusercontent.com URL is logged as a warning and skipped. Non-HTTPS URLs are dropped without a warning
  • If all URLs are invalid, falls back to the default jsDelivr → Hugging Face → StaticDelivr chain
Example: Initialization via Environment Variable
Example: Initialization via Config File Create ~/.tif1rc:
Then use in Python:
Example: Validation Behavior

Attributes

sources

List of all configured CDN sources, sorted by priority (lowest priority number first). This includes both enabled and disabled sources. Characteristics:
  • Always sorted: Maintained in priority order (1, 2, 3, …)
  • Includes all sources: Both enabled=True and enabled=False sources
  • Includes failed sources: Sources that have exceeded failure threshold
  • Mutable: Can be modified directly, but prefer using add_source() for automatic sorting
Use Cases:
  • Iterate over all sources (including disabled) for health reporting
  • Count total configured sources
  • Inspect source configuration (URLs, priorities, settings)
  • Debug CDN setup
Example: Inspecting All Sources
Example: Filtering Sources

_failure_counts

Internal dictionary tracking consecutive failure counts for each CDN source. When a source’s failure count reaches _max_failures (default: 3), it is automatically excluded from get_sources() until reset. Structure:
Behavior:
  • Initialized to 0: All sources start with 0 failures (healthy state)
  • Incremented on failure: mark_failure() increments the count
  • Reset on success: mark_success() resets to 0
  • Circuit breaker threshold: Sources with count >= _max_failures are excluded
  • Persistent across requests: Counts persist for the lifetime of the CDN manager instance
Note: This is an internal attribute. Use the following methods instead of modifying directly:
  • mark_failure(source_name) to increment
  • mark_success(source_name) to reset
  • reset() to reset all sources
Example: Monitoring Failure Counts
Example: Failure Count Persistence

_max_failures

Maximum number of consecutive failures before a CDN source is automatically disabled (circuit breaker threshold). This implements a circuit breaker pattern to avoid wasting time on consistently failing sources. Default Value: 3 consecutive failures Circuit Breaker States:
  • Closed (healthy): failure_count < _max_failures → Source is available
  • Open (disabled): failure_count >= _max_failures → Source is excluded from get_sources()
  • Recovery: A manual mark_success(), reset(), or reload() sets the count to 0 → Source becomes available again
Why 3 Failures? The default threshold of 3 provides a good balance:
  • Not too sensitive: Tolerates transient network issues (1-2 temporary failures)
  • Not too lenient: Quickly disables consistently failing sources (3 failures = clear pattern)
  • Fast recovery: Single successful request resets the counter
Customization: Modify this value if needed:
Example: Circuit Breaker Behavior
Example: Custom Threshold

Methods

get_sources()

Returns a list of now available CDN sources, sorted by priority (lowest priority number first). This method filters out sources that should not be used for data fetching. Filtering Logic: The method excludes:
  1. Disabled sources: Sources with enabled=False
  2. Failed sources: Sources where _failure_counts[name] >= _max_failures (circuit breaker open)
Returns:
  • list[CDNSource]: Available sources sorted by priority (ascending)
  • Empty list if all sources are disabled or have exceeded failure threshold
Sorting Behavior:
  • Sources are sorted by priority: 1, 2, 3, … (lower number = higher priority)
  • Sources with the same priority maintain their insertion order (stable sort)
  • The first source in the list is tried first by try_sources()
Use Cases:
  • Data fetching: Primary method used by try_sources() to determine which sources to try
  • Health monitoring: Check how many sources are now available
  • Debugging: Understand which sources the next request uses
  • Load balancing: Implement custom logic based on available sources
Example: Basic Usage
Example: Using Primary Source
Example: Health Monitoring
Example: Filtering and Analysis
Example: Handling No Available Sources

add_source()

Adds a new CDN source to the manager. The source is automatically inserted into the sources list in priority order, and its failure count is initialized to 0. This method is useful for:
  • Adding private CDN mirrors
  • Adding regional CDN endpoints for better performance
  • Adding backup sources for increased reliability
  • Testing custom CDN configurations
Parameters:
  • source (CDNSource): The CDN source object to add
Behavior:
  • Sources are automatically sorted by priority after insertion
  • If a source with the same name already exists, both are kept. They share one failure counter, and the call resets it to 0. Use unique names
  • The new source is immediately available for use via get_sources()
  • Failure count is initialized to 0 (healthy state)
Example:
Advanced Example: Dynamic CDN Selection

mark_failure()

Marks a CDN source as having failed a request. This increments the failure counter for the source. When a source reaches the failure threshold (default: 3 consecutive failures), it is automatically excluded from get_sources() until reset. This implements a circuit breaker pattern to prevent wasting time on consistently failing sources. The circuit breaker helps:
  • Reduce latency by skipping known-bad sources
  • Prevent cascading failures
  • Allow sources to recover (via reset() or mark_success())
Parameters:
  • source_name (str): Name of the CDN source that failed
Behavior:
  • Increments failure count by 1
  • If count reaches _max_failures (3), logs a warning
  • Source is automatically excluded from get_sources() after threshold
  • Does not disable the source permanently—can be recovered via reset() or mark_success()
When This Is Called: try_sources() calls this method automatically when a CDN request fails. Call it manually only for custom fetching logic. Example:
Advanced Example: How try_sources() Classifies Errors The fetch function only raises. try_sources() decides from the exception whether to call mark_failure():

mark_success()

Resets the failure count for a CDN source to 0, indicating a successful data fetch. This allows a previously failing source to recover and be used again. When a source with 1 or 2 failures serves a request, try_sources() calls this method. The count then goes back to 0. A source with an open circuit is never tried, so only a manual call or reset() brings it back. Parameters:
  • source_name (str): Name of the CDN source that succeeded
Behavior:
  • Sets failure count to 0 for the specified source
  • Source becomes immediately available via get_sources() if its circuit was open (the enabled flag does not change)
  • Called automatically by try_sources() and try_sources_async() on successful fetch
When This Is Called: try_sources() calls this method automatically when a CDN request succeeds. Applications rarely need to call it manually. Example:
Advanced Example: Monitoring Recovery

reset()

Resets all failure counts for all CDN sources to 0. This re-enables all previously disabled sources. Use this method to recover from widespread network issues or to give all sources a fresh start. Use Cases:
  • After network outage: When the network connection was down and all sources failed
  • After CDN maintenance: When CDN providers have resolved their issues
  • Testing: To test fallback behavior from a clean state
  • Manual recovery: To force retry of all sources
Behavior:
  • Resets failure count to 0 for every source in cdn.sources
  • All sources become immediately available via get_sources() (if enabled=True)
  • Does not modify source configuration (priority, URLs, minification settings)
Example:
Advanced Example: Automatic Recovery Strategy

reload()

Rebuilds the source list from the current cdns and cdn_use_minification config values, then resets all failure counts. Call it after config.set("cdns", ...) to apply the change to the running manager. Behavior:
  • Runs the same steps as Initialization
  • Drops sources that were added with add_source()
  • Sets _max_failures back to 3

try_sources()

Try fetching data from CDN sources with automatic fallback. This is the core method that implements the multi-source fallback logic with circuit breaker patterns. It orchestrates the entire CDN failover process, trying sources in priority order until one succeeds or all fail. How It Works:
  1. Get available sources: Calls get_sources() to get enabled, healthy sources sorted by priority
  2. Check availability: If no sources available, raises NetworkError immediately
  3. Try each source (in priority order):
    • Format URL via source.format_url(year, gp, session, path)
    • Log debug message: "Trying CDN: {source.name} - {url}"
    • Call fetch_func(url) to try the HTTP request
    • On success: Call mark_success(source.name) and return data (done!)
    • On DataNotFoundError (404): Fall through to the next source. The failure count is NOT incremented (a 404 is not a CDN health problem).
    • On an exception whose status is 403 or 404 (response.status_code, or the status_code context key of a NetworkError): Same as a 404
    • On InvalidDataError: Raise it at once
    • On other exceptions: Log warning, call mark_failure(source.name), try next source
  4. All sources failed: Raise DataNotFoundError if every source refused with a 4xx status other than 408 or 429; otherwise NetworkError with details from last exception
Parameters:
  • year (int): Season year (for example, 2021, 2022, 2023)
  • gp (str): Grand Prix name, URL-encoded (for example, “Belgian%20Grand%20Prix”, “Monaco%20Grand%20Prix”)
    • Important: Must be URL-encoded (spaces as %20, not +)
    • Use urllib.parse.quote() if encoding manually
  • session (str): Session name, URL-encoded like gp (for example, “Race”, “Qualifying”, “Practice%201”, “Sprint”)
  • path (str): Resource path relative to session directory (for example, “drivers.json”, “session_laptimes.json”, “VER/laptimes.json”, “VER/1_tel.json”)
  • fetch_func (Callable[[str], Any]): Function that takes a URL string and returns fetched data
    • Should raise DataNotFoundError for 404 responses
    • Should raise other exceptions for network/server errors
    • Pass exception details as context keywords, for example DataNotFoundError(url=url). These classes build their own message, so a message= keyword raises TypeError
    • Return type can be any (dict, list, bytes, etc.)
Returns:
  • Any: Fetched data from the first successful CDN source (return type depends on fetch_func)
Raises:
  • DataNotFoundError: If every CDN source refused the resource with a 4xx status (404 included). A 408 or 429 means “try again later”, so it gives NetworkError instead
    • Raised only after all sources were tried
    • Indicates the requested data does not exist on any mirror
  • NetworkError: If any source failed for another reason, or no source is available
    • Includes URL path and status code from last exception
    • Indicates all sources are unavailable or experiencing issues
  • InvalidDataError: Raised at once when fetch_func raises it. Another CDN cannot fix an invalid payload, so no other source is tried
Error Handling Strategy: The method distinguishes between two types of errors:
  1. Data not found (404 or 403): Possibly a stale or divergent mirror
    • Falls through to the next CDN source (the payload may exist elsewhere)
    • Does NOT increment failure counter (not a CDN health problem)
    • If every source refuses with a 4xx status other than 408 or 429, raises DataNotFoundError
  2. Network/server errors: Temporary error—CDN source is failing
    • Logged as warning
    • Failure counter incremented via mark_failure()
    • Next source is tried
    • If all sources fail, raises NetworkError
Example: Basic Usage
Example: With Proper Error Handling
Example: Custom Fetch Function with Retries
Example: Monitoring Fallback Behavior
Example: Async Fetch Function Async code uses try_sources_async(). Its fetch_func is a coroutine function that receives the CDNSource and the formatted URL:
It follows the rules of try_sources(), with one difference. After a refusal (404 or 403), it fetches all remaining sources at the same time and returns the first payload that arrives.
Example: Fetch with Progress Tracking
Performance Considerations:
  • Latency: Each failed source adds latency (timeout + retry time). Use reasonable timeouts in fetch_func.
  • Circuit breaker: After 3 failures, sources are automatically disabled, reducing latency for subsequent requests.
  • Minification: Leave use_minification off for the default CDNs. They return 404 for .min.json files.
  • Connection pooling: Reuse HTTP sessions in fetch_func for better performance.
  • Parallel fetching: try_sources() is sequential. For parallel fetching of multiple resources, call it multiple times concurrently.
Thread Safety:
  • try_sources() uses no locks. Concurrent calls are safe for reads, but two threads can update the same failure counter at the same time
  • A lost counter update only delays or advances the circuit breaker by one failure
  • In high-concurrency scenarios, consider external synchronization for mark_failure() / mark_success() calls

CDNSource

Dataclass representing a CDN source configuration.

Constructor

Attributes:
  • name: Human-readable source name
  • base_url: Base URL for the CDN (the cdns config accepts only HTTPS URLs)
  • priority: Priority level (lower number = higher priority, default: 0)
  • enabled: Whether source is now enabled (default: True)
  • use_minification: Enable JSON minification (appends .min before .json, default: False)
Example:

Methods

format_url()

Format a complete CDN URL for a specific resource with optional minification support. Parameters:
  • year: Season year (for example, 2021)
  • gp: Grand Prix name, URL-encoded (for example, “Belgian%20Grand%20Prix”)
  • session: Session name, URL-encoded (for example, “Race”, “Practice%201”)
  • path: Resource path (for example, “drivers.json”)
Returns:
  • Complete CDN URL string
URL Format: The format depends on the host in base_url:
If use_minification=True and path ends with .json, the path is transformed from file.json to file.min.json. Example:

Configuration

CDN behavior can be configured via the global config. The CDN manager reads these keys when tif1.cdn is first imported and on each reload() call. Set them before the first session load, or call reload() after the change:

Practical Example: 2021 Belgian Grand Prix

Here’s a complete example showing how the CDN system works when fetching data for the 2021 Belgian Grand Prix Race:

Best Practices

Configuration

  1. Use HTTPS only: HTTP CDN sources are rejected for security
  2. Leave minification off: The default CDNs return 404 for .min.json files
  3. Configure via file: Use ~/.tif1rc for persistent configuration
  4. Set priorities wisely: Lower number = higher priority (1 before 2)

Error Handling

  1. Distinguish error types: Handle DataNotFoundError (404) vs NetworkError (all sources failed)
  2. Let CDN manager handle fallback: Do not implement custom retry logic
  3. Log failures: Enable debug logging to see which CDN is being used

Performance

  1. Leave minification off: A .min.json request costs one 404 per payload on the default CDNs
  2. Use connection pooling: Reuse HTTP sessions in fetch functions
  3. Set reasonable timeouts: Balance between patience and responsiveness
  4. Monitor circuit breaker: Check failure counts to identify problematic sources

Reliability

  1. Add backup sources: At least 2-3 sources for production applications
  2. Use regional CDNs: Optimize for the user’s geographic location
  3. Implement auto-recovery: Periodically reset sources after network issues
  4. Monitor health: Track availability and failure rates

Security

  1. Never use raw.githubusercontent.com: Rate limited and blocked by tif1
  2. Validate custom CDN URLs: Ensure they are trusted sources
  3. Use HTTPS everywhere: HTTP sources are automatically rejected
  4. Audit CDN sources: Regularly review configured sources

Troubleshooting

All CDN Sources Failing

Symptoms: NetworkError: Network request failed: url='2021/Belgian%20Grand%20Prix/Race/drivers.json' Solutions:
  1. Check network connectivity: ping cdn.jsdelivr.net
  2. Verify CDN URLs are accessible in browser
  3. Reset all sources: cdn.reset()
  4. Check firewall/proxy settings
  5. Enable debug logging to see detailed errors

Data Not Found (404)

Symptoms: DataNotFoundError: Data not found Cause: Requested data does not exist (not a CDN failure) Solutions:
  1. Verify session exists: Check year, GP name, session name
  2. Check data availability: Some sessions may not have all data types
  3. Use correct path: Ensure path parameter is correct (for example, “drivers.json”)

Slow Performance

Symptoms: Data fetching is slow Solutions:
  1. Check that cdn_use_minification is off: config.get("cdn_use_minification")
  2. Add regional CDN: Closer to the user’s geographic location
  3. Check network speed: Run speed test
  4. Use connection pooling: Reuse HTTP sessions
  5. Increase timeout: May be timing out prematurely

Circuit Breaker Stuck Open

Symptoms: Sources remain disabled after network recovery Solution: Reset failure counts

Last modified on October 28, 2026