> ## Documentation Index
> Fetch the complete documentation index at: https://docs.imperial.gay/llms.txt
> Use this file to discover all available pages before exploring further.

# Fast Global CDN

> How Imperial delivers your media at lightning speed worldwide

## Powered by Cloudflare

Imperial uses **Cloudflare's global CDN network** to deliver your media with industry-leading performance. With 310+ data centers in 120+ countries, your content is served from the location closest to your users.

### Network Statistics

<CardGroup cols={3}>
  <Card title="310+ Data Centers" icon="server">
    Spanning every continent
  </Card>

  <Card title="120+ Countries" icon="earth-americas">
    Global presence
  </Card>

  <Card title="<50ms Latency" icon="gauge-high">
    95th percentile worldwide
  </Card>
</CardGroup>

## How CDN Caching Works

When someone requests your image or video, here's what happens:

<Steps>
  <Step title="User Makes Request">
    A user in Tokyo requests your image: `https://origin.imperial.gay/uploads/user-id/cat.jpg`
  </Step>

  <Step title="Cloudflare Routing">
    The request is automatically routed to the nearest Cloudflare data center (Tokyo)
  </Step>

  <Step title="Cache Check">Cloudflare checks if the file is already cached at that location</Step>
  <Step title="Cache Hit (Fast Path)">If cached → File is delivered instantly (\~10-30ms)</Step>

  <Step title="Cache Miss (First Time)">
    If not cached → Fetch from R2 storage → Cache at edge → Deliver to user
  </Step>

  <Step title="Subsequent Requests">
    Future requests from that region are served from cache instantly
  </Step>
</Steps>

## Performance Comparison

### Traditional vs CDN Delivery

<Tabs>
  <Tab title="Without CDN">
    **User in Sydney requests file from US server:** `Sydney → USA (Origin Server) ├─ DNS
            Resolution: ~50ms ├─ TCP Handshake: ~200ms ├─ TLS Handshake: ~200ms ├─ HTTP Request: ~200ms └─
            Data Transfer: ~500ms (for 1MB file) Total: ~1,150ms (1.15 seconds) 🐌`
  </Tab>

  <Tab title="With Imperial CDN">
    **User in Sydney requests cached file:** `Sydney → Cloudflare Edge (Sydney) ├─ DNS
            Resolution: ~5ms (cached) ├─ TCP Handshake: ~10ms (local edge) ├─ TLS Handshake: ~10ms (session
            resumption) ├─ HTTP Request: ~5ms └─ Data Transfer: ~20ms (from local cache) Total: ~50ms (0.05
            seconds) ⚡`
  </Tab>
</Tabs>

<Info>**That's 23x faster!** CDN delivery can reduce load times from seconds to milliseconds.</Info>

## Cache Strategy

Imperial's CDN caching is optimized for media delivery:

### Cache Rules

<AccordionGroup>
  <Accordion title="Images (JPEG, PNG, WebP)">
    * **Cache Duration**: 30 days - **Cache Key**: Full URL - **Cache Control**: `public,
          max-age=2592000, immutable` - **Optimization**: Served from edge with Cloudflare Polish
      (auto-optimization)
  </Accordion>

  <Accordion title="Videos (MP4, WebM)">
    * **Cache Duration**: 30 days - **Cache Key**: Full URL - **Streaming**: Range request support
      for smooth playback - **Optimization**: Adaptive bitrate delivery when available
  </Accordion>

  <Accordion title="Video Thumbnails">
    * **Cache Duration**: 90 days (rarely change) - **Format**: Optimized JPEG - **Purpose**: Fast
      gallery loading
  </Accordion>
</AccordionGroup>

## Global Performance

### Average Latency by Region

| Region        | First Load | Cached Load |
| ------------- | ---------- | ----------- |
| North America | 100-150ms  | 20-40ms     |
| Europe        | 80-120ms   | 15-35ms     |
| Asia          | 90-140ms   | 18-38ms     |
| South America | 120-180ms  | 25-45ms     |
| Oceania       | 110-160ms  | 22-42ms     |
| Africa        | 130-200ms  | 28-50ms     |

<Tip>These are 95th percentile numbers. Most requests are even faster!</Tip>

## Advanced Features

### HTTP/3 Support

Imperial supports **HTTP/3** (QUIC protocol) for even faster connections:

```
HTTP/1.1: 6-8 round trips to establish connection
HTTP/2:   3-4 round trips
HTTP/3:   1-2 round trips ⚡
```

Benefits:

* Faster connection establishment
* Better performance on mobile networks
* Improved handling of packet loss
* Multiplexed streams

### Brotli Compression

Text-based responses (JSON, HTML) are compressed with Brotli:

* **20-30% smaller** than Gzip
* Faster decompression on modern devices
* Automatically enabled for all API responses

### Early Hints (103 Status Code)

Cloudflare sends early hints to browsers while the origin processes requests, allowing browsers to start loading resources sooner.

## Cache Warming

Popular content automatically stays cached across the global network:

<Steps>
  <Step title="Initial Upload">File is stored in R2 (origin storage)</Step>
  <Step title="First Request">File is cached at the requesting edge location</Step>

  <Step title="Popularity Detection">
    If file receives multiple requests, Cloudflare proactively caches it at more locations
  </Step>

  <Step title="Global Distribution">
    Viral content automatically spreads across all 310+ edge locations
  </Step>
</Steps>

## Smart Routing

Cloudflare's Argo Smart Routing optimizes the path between edge and origin:

```
Traditional Routing:
User → Edge → Public Internet → Origin
        └─ Takes the "default" internet path
        └─ May encounter congestion

Argo Smart Routing:
User → Edge → Cloudflare Private Network → Origin
        └─ Uses faster, less congested Cloudflare backbone
        └─ 30% faster on average
```

## DDoS Protection

Built-in protection against attacks that could slow down your content:

<CardGroup cols={2}>
  <Card title="Layer 3/4 Protection" icon="shield">
    Mitigates network-layer attacks automatically
  </Card>

  <Card title="Layer 7 Protection" icon="shield-check">
    Filters malicious application-layer requests
  </Card>

  <Card title="Always Online" icon="arrows-rotate">
    Serves cached content even if origin is down
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    Prevents abuse and ensures fair usage
  </Card>
</CardGroup>

## Mobile Optimization

Special optimizations for mobile devices:

### Connection Quality Adaptation

Cloudflare detects connection quality and adapts delivery:

* **Fast WiFi/5G**: Full quality, parallel connections
* **4G**: Moderate optimization, pipelined requests
* **3G/Slow**: Aggressive compression, sequential loads

### Image Optimization

For supported devices, images are automatically optimized:

* **Format conversion**: Serve WebP/AVIF to supporting browsers
* **Size optimization**: Reduce file size without quality loss
* **Lazy loading hints**: Suggest browser-level lazy loading

## Monitoring & Analytics

Track your CDN performance in real-time:

```bash theme={null}
# Check cache status via headers
curl -I https://origin.imperial.gay/uploads/user-id/image.jpg

# Response headers:
CF-Cache-Status: HIT
CF-Ray: 8e5a4b3c2d1e0f1a-LAX
Age: 3600
Cache-Control: public, max-age=2592000
```

### Cache Status Values

| Status    | Meaning                                 |
| --------- | --------------------------------------- |
| `HIT`     | Served from cache (fast!)               |
| `MISS`    | First request, fetched from origin      |
| `EXPIRED` | Cache expired, revalidating             |
| `STALE`   | Serving stale while revalidating        |
| `BYPASS`  | Cache bypassed (e.g., query parameters) |

## Best Practices

<Tip>
  **Consistent URLs**: Use the same URL for each file. Changing URLs creates new cache entries and
  wastes cache space.
</Tip>

<Warning>
  **Query Parameters**: Avoid unnecessary query parameters. `image.jpg?v=1` and `image.jpg?v=2` are
  cached separately.
</Warning>

<Info>
  **File Names**: Use meaningful, permanent filenames. Imperial automatically generates stable URLs.
</Info>

## Technical Deep Dive

### Anycast Network

Cloudflare uses **Anycast routing** where all edge locations share the same IP addresses:

```
Traditional (Unicast):
├─ us-east.example.com → 1.2.3.4
├─ eu-west.example.com → 5.6.7.8
└─ asia.example.com → 9.10.11.12

Imperial/Cloudflare (Anycast):
└─ origin.imperial.gay → 104.18.x.x
   ├─ Routes to nearest data center automatically
   └─ No manual geo-routing needed
```

### Cache Hierarchy

```
User Request
    ↓
Edge Cache (Tier 1) - 310+ locations
    ↓ (cache miss)
Regional Cache (Tier 2) - ~50 locations
    ↓ (cache miss)
Origin (R2 Storage)
```

This multi-tier approach means even cache misses are fast!

## Get Started

Experience the speed difference:

<Card title="Upload Your First File" icon="rocket" href="/quickstart">
  See how fast global delivery can be
</Card>