Eve library

CDN Integration Guide

Guide

Revision 1

On this page

This document provides comprehensive documentation for the Lilith Media Service CDN integration with AWS CloudFront, including signed URLs, cache invalidation, and content delivery optimization.

Overview#

The CDN Integration provides:

  • CloudFront Distribution: Managed CloudFront client with AWS SDK
  • Signed URLs: Time-limited access to protected content
  • Signed Cookies: Multi-resource access for streaming
  • Cache Invalidation: Path-based and wildcard invalidation
  • Cache Control: Preset cache policies for different content types
  • Geo-Restriction: Whitelist/blacklist based content access
  • Range Requests: Optimal chunking for streaming media

Table of Contents#

  1. Configuration
  2. Signed URL Generation
  3. Signed Cookies
  4. Cache Invalidation
  5. Cache Control
  6. CDN URL Utilities
  7. Geo-Restriction
  8. Range Requests
  9. Error Handling
  10. SDK Integration

Configuration#

Environment Variables#

Variable Required Description
CLOUDFRONT_DISTRIBUTION_ID Yes CloudFront distribution ID
CLOUDFRONT_DOMAIN_NAME Yes CloudFront domain (e.g., d1234abcd.cloudfront.net)
CLOUDFRONT_KEY_PAIR_ID Yes Key pair ID for signed URLs
CLOUDFRONT_PRIVATE_KEY Yes RSA private key (PEM format)
AWS_REGION No AWS region (default: us-east-1)

CloudFront Config Interface#

typescript
interface CloudFrontConfig {
  distributionId: string;
  domainName: string;
  keyPairId: string;
  privateKey: string;
  region?: string;
  defaultTtlSeconds?: number; // Default: 3600 (1 hour)
}

Creating the Client#

typescript
import { CloudFrontCDNClient, createCloudFrontClient } from '@lilith/media/cdn';

// From environment variables
const cdn = createCloudFrontClient();

// With explicit configuration
const cdn = new CloudFrontCDNClient({
  distributionId: 'EDFDVBD6EXAMPLE',
  domainName: 'd1234abcd.cloudfront.net',
  keyPairId: 'K2JCJMDEHXQW5F',
  privateKey:
    '-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----',
  defaultTtlSeconds: 3600,
});

Get Configuration#

typescript
const config = cdn.getConfig();
// Returns: { distributionId, domainName, keyPairId, defaultTtlSeconds }

Signed URL Generation#

Signed URL Options#

typescript
interface SignedUrlOptions {
  expiresIn?: number; // Seconds from now
  expiresAt?: Date; // Absolute expiration
  ipAddress?: string; // IP restriction (CIDR notation)
  dateGreaterThan?: Date; // URL not valid before this date
}

Basic Signed URL#

typescript
const result = cdn.generateSignedUrl('/media/video/123.mp4', {
  expiresIn: 3600, // 1 hour
});

// Returns:
interface SignedUrlResult {
  url: string; // Full signed URL
  expiresAt: Date; // Expiration timestamp
  policy?: string; // Policy JSON (for custom policies)
}

Signed URL with Custom Policy#

For advanced restrictions (IP, time windows):

typescript
const result = cdn.generateSignedUrlWithPolicy('/media/video/123.mp4', {
  expiresIn: 3600,
  ipAddress: '192.168.1.0/24', // Restrict to subnet
  dateGreaterThan: new Date(), // Not valid before now
});

Wildcard Signed URL#

For accessing multiple resources under a path:

typescript
// Sign all files under /media/course_123/
const result = cdn.generateWildcardSignedUrl('/media/course_123/*', {
  expiresIn: 7200, // 2 hours
});

Build Resource URL#

typescript
const url = cdn.buildResourceUrl('/media/video/123.mp4');
// Returns: https://d1234abcd.cloudfront.net/media/video/123.mp4

Signed Cookies#

Use signed cookies when users need access to multiple private files (e.g., HLS streaming with multiple segments).

typescript
interface SignedCookieOptions extends SignedUrlOptions {
  path?: string; // Cookie path (default: '/')
  domain?: string; // Cookie domain
  secure?: boolean; // HTTPS only (default: true)
  httpOnly?: boolean; // HTTP only (default: true)
  sameSite?: 'Strict' | 'Lax' | 'None'; // SameSite (default: 'Lax')
}

Generate Signed Cookies#

typescript
const result = cdn.generateSignedCookies('/media/course_123/*', {
  expiresIn: 7200,
  path: '/',
  domain: '.example.com',
  secure: true,
  httpOnly: true,
  sameSite: 'Lax',
});

// Returns:
interface SignedCookiesResult {
  cookies: {
    'CloudFront-Policy': string;
    'CloudFront-Signature': string;
    'CloudFront-Key-Pair-Id': string;
  };
  expiresAt: Date;
  cookieOptions: {
    path: string;
    domain?: string;
    secure: boolean;
    httpOnly: boolean;
    sameSite: string;
    expires: Date;
  };
}

Setting Cookies in Response#

typescript
// Express/Fastify example
const { cookies, cookieOptions } = cdn.generateSignedCookies('/media/*', {
  expiresIn: 3600,
});

for (const [name, value] of Object.entries(cookies)) {
  reply.setCookie(name, value, {
    path: cookieOptions.path,
    domain: cookieOptions.domain,
    secure: cookieOptions.secure,
    httpOnly: cookieOptions.httpOnly,
    sameSite: cookieOptions.sameSite,
    expires: cookieOptions.expires,
  });
}

Signed Cookies with Custom Policy#

typescript
const result = cdn.generateSignedCookiesWithPolicy('/media/premium/*', {
  expiresIn: 7200,
  ipAddress: '10.0.0.0/8', // Internal network only
});

Cache Invalidation#

Invalidation Options#

typescript
interface InvalidationOptions {
  paths: string[];
  callerReference?: string; // Auto-generated if not provided
}

Invalidate Specific Paths#

typescript
const result = await cdn.invalidate({
  paths: ['/media/video/123.mp4', '/media/thumbnails/123/*'],
});

// Returns:
interface InvalidationResult {
  id: string;
  status: string; // 'InProgress' | 'Completed'
  createTime?: Date;
  paths: string[];
}

Invalidate Single Path#

typescript
const result = await cdn.invalidatePath('/media/video/123.mp4');

Invalidate Multiple Paths#

Automatically optimizes to use wildcards when beneficial:

typescript
const result = await cdn.invalidatePaths([
  '/media/course_123/segment_001.ts',
  '/media/course_123/segment_002.ts',
  '/media/course_123/segment_003.ts',
  '/media/course_123/segment_004.ts',
  '/media/course_123/segment_005.ts',
  '/media/course_123/segment_006.ts',
]);
// Optimized to: /media/course_123/*

Invalidate All Content#

typescript
// Use sparingly - expensive operation
const result = await cdn.invalidateAll();
// Invalidates: /*

Check Invalidation Status#

typescript
const status = await cdn.getInvalidationStatus('I3GEXAMPLE');
// Returns: InvalidationResult | null

Wait for Invalidation#

typescript
const completed = await cdn.waitForInvalidation('I3GEXAMPLE', 300000);
// Polls every 2 seconds, max wait 5 minutes (default)

List Recent Invalidations#

typescript
const invalidations = await cdn.listInvalidations(10);
// Returns: InvalidationResult[]

Constants#

typescript
const CLOUDFRONT_DEFAULTS = {
  defaultTtlSeconds: 3600, // 1 hour
  maxInvalidationPaths: 3000, // AWS limit
  invalidationStatusPollIntervalMs: 2000,
  invalidationMaxWaitMs: 300000, // 5 minutes
};

Cache Control#

Cache Control Options#

typescript
interface CacheControlOptions {
  maxAge?: number; // Browser cache (seconds)
  sMaxAge?: number; // CDN cache (s-maxage)
  staleWhileRevalidate?: number; // Serve stale while fetching
  staleIfError?: number; // Serve stale on origin error
  mustRevalidate?: boolean;
  noCache?: boolean;
  noStore?: boolean;
  private?: boolean;
  public?: boolean;
  immutable?: boolean;
  noTransform?: boolean;
}

Build Cache-Control Header#

typescript
import { buildCacheControl } from '@lilith/media/cdn';

const header = buildCacheControl({
  public: true,
  maxAge: 86400,
  sMaxAge: 604800,
  staleWhileRevalidate: 86400,
});
// Returns: "public, max-age=86400, s-maxage=604800, stale-while-revalidate=86400"

Parse Cache-Control Header#

typescript
import { parseCacheControl } from '@lilith/media/cdn';

const options = parseCacheControl('public, max-age=3600, s-maxage=86400');
// Returns: { public: true, maxAge: 3600, sMaxAge: 86400 }

Cache Presets#

typescript
import { CACHE_PRESETS } from '@lilith/media/cdn';

// Available presets:
CACHE_PRESETS.immutable; // Static assets (1 year, immutable)
CACHE_PRESETS.versioned; // Versioned assets (1 year)
CACHE_PRESETS.dynamic; // Frequently updated (1 hour + stale-while-revalidate)
CACHE_PRESETS.private; // User-specific (1 minute, private)
CACHE_PRESETS.noCache; // Real-time (no-store)
CACHE_PRESETS.api; // API responses (1 minute browser, 5 minute CDN)
CACHE_PRESETS.media; // Media files (1 day browser, 1 week CDN)
CACHE_PRESETS.hlsSegment; // HLS .ts segments (immutable)
CACHE_PRESETS.hlsManifest; // HLS .m3u8 manifests (2 seconds)

Preset Details#

Preset max-age s-maxage stale-while-revalidate Notes
immutable 1 year 1 year - immutable flag
versioned 1 year 1 year - revalidation allowed
dynamic 1 hour 1 hour 1 day stale-if-error: 1 week
private 1 min - - must-revalidate
noCache - - - no-store
api 1 min 5 min 1 min -
media 1 day 1 week 1 day -
hlsSegment 1 day 1 week - immutable, no-transform
hlsManifest 2 sec 2 sec - Low TTL for updates

Get Cache Settings by Content Type#

typescript
import { getCacheSettingsForContentType } from '@lilith/media/cdn';

// Returns appropriate preset based on MIME type
const settings = getCacheSettingsForContentType('video/mp4', true);
// Returns: CACHE_PRESETS.media (or immutable if versioned)

// HLS manifest
getCacheSettingsForContentType('application/vnd.apple.mpegurl');
// Returns: CACHE_PRESETS.hlsManifest

// HLS segment
getCacheSettingsForContentType('video/mp2t');
// Returns: CACHE_PRESETS.hlsSegment

// Images
getCacheSettingsForContentType('image/webp', true);
// Returns: CACHE_PRESETS.immutable

CDN URL Utilities#

Build CDN URL#

typescript
import { buildCDNUrl } from '@lilith/media/cdn';

const url = buildCDNUrl('cdn.example.com', '/media/video.mp4', {
  version: 'abc123',
  format: 'webm',
  quality: 80,
  width: 1920,
  height: 1080,
});
// Returns: https://cdn.example.com/media/video.mp4?v=abc123&f=webm&q=80&w=1920&h=1080

Parse CDN URL#

typescript
import { parseCDNUrl } from '@lilith/media/cdn';

const parsed = parseCDNUrl(
  'https://cdn.example.com/media/video.mp4?v=abc123&w=1920'
);
// Returns: { domain: 'cdn.example.com', path: '/media/video.mp4', version: 'abc123', width: 1920 }

Version Management#

typescript
import {
  addVersionToUrl,
  extractVersionFromUrl,
  generateContentHash,
} from '@lilith/media/cdn';

// Add version to URL
const versionedUrl = addVersionToUrl('/media/style.css', 'v2');
// Returns: /media/style.css?v=v2

// Extract version
const version = extractVersionFromUrl('/media/style.css?v=abc123');
// Returns: 'abc123'

// Generate content hash for cache busting
const hash = generateContentHash(fileContent, 'md5');
// Returns: 8-character hex hash (e.g., 'a1b2c3d4')

Geo-Restriction#

Geo Restriction Type#

typescript
interface GeoRestriction {
  type: 'whitelist' | 'blacklist';
  countries: string[]; // ISO 3166-1 alpha-2 codes
}

Check Geo Access#

typescript
import { isGeoAllowed } from '@lilith/media/cdn';

// Whitelist example (only allow US, CA)
const usRestriction: GeoRestriction = {
  type: 'whitelist',
  countries: ['US', 'CA'],
};
isGeoAllowed('US', usRestriction); // true
isGeoAllowed('GB', usRestriction); // false

// Blacklist example (block certain countries)
const blockList: GeoRestriction = {
  type: 'blacklist',
  countries: ['CN', 'RU'],
};
isGeoAllowed('US', blockList); // true
isGeoAllowed('CN', blockList); // false

Origin Shield Region#

Get optimal origin shield location based on user region:

typescript
import { getOriginShieldRegion } from '@lilith/media/cdn';

const shield = getOriginShieldRegion('eu-west-1');
// Returns: 'eu-west-1'

const shield = getOriginShieldRegion('ap-northeast-2');
// Returns: 'ap-northeast-1' (routes to Tokyo)

Supported Origin Shield Regions#

Primary Region Shield Region
us-east-1 us-east-1
us-east-2 us-east-2
us-west-1 us-west-2
us-west-2 us-west-2
eu-west-1 eu-west-1
eu-west-2 eu-west-2
eu-west-3 eu-west-1
eu-central-1 eu-central-1
eu-north-1 eu-west-1
ap-northeast-1 ap-northeast-1
ap-northeast-2 ap-northeast-1
ap-southeast-1 ap-southeast-1
ap-southeast-2 ap-southeast-2
ap-south-1 ap-south-1

Range Requests#

Parse Range Header#

typescript
import { parseRangeHeader } from '@lilith/media/cdn';

const range = parseRangeHeader('bytes=0-999', 10000);
// Returns: { start: 0, end: 999 }

// Suffix range (last 500 bytes)
const suffixRange = parseRangeHeader('bytes=-500', 10000);
// Returns: { start: 9500, end: 9999 }

// Invalid range returns null
const invalid = parseRangeHeader('bytes=5000-4000', 10000);
// Returns: null

Build Content-Range Header#

typescript
import { buildContentRangeHeader } from '@lilith/media/cdn';

const header = buildContentRangeHeader(0, 999, 10000);
// Returns: "bytes 0-999/10000"

Build Accept-Ranges Header#

typescript
import { buildAcceptRangesHeader } from '@lilith/media/cdn';

const header = buildAcceptRangesHeader();
// Returns: "bytes"

Optimal Chunk Size#

Get recommended chunk size based on content:

typescript
import { getOptimalChunkSize } from '@lilith/media/cdn';

// Large video (100MB+)
getOptimalChunkSize(150 * 1024 * 1024, 'video/mp4');
// Returns: 5MB (5242880)

// Medium video (10-100MB)
getOptimalChunkSize(50 * 1024 * 1024, 'video/mp4');
// Returns: 2MB (2097152)

// Small video (<10MB)
getOptimalChunkSize(5 * 1024 * 1024, 'video/mp4');
// Returns: 1MB (1048576)

// Audio
getOptimalChunkSize(10 * 1024 * 1024, 'audio/mpeg');
// Returns: 256KB (262144)

Error Handling#

Common Errors#

Error Description
At least one path is required Invalidation called with empty paths
Maximum 3000 paths per invalidation AWS limit exceeded
NoSuchInvalidation Invalidation ID not found
NoSuchDistribution Distribution ID not found
Invalidation timed out Wait timeout exceeded

Error Handling Example#

typescript
try {
  const result = await cdn.invalidatePaths(paths);
  console.log(`Invalidation ${result.id} started`);

  // Wait for completion
  const completed = await cdn.waitForInvalidation(result.id);
  console.log('Invalidation completed');
} catch (error) {
  if (error.message.includes('Maximum 3000 paths')) {
    // Split into multiple requests
  } else if (error.message.includes('timed out')) {
    // Check status later
  } else {
    throw error;
  }
}

SDK Integration#

TypeScript/JavaScript#

typescript
import { LilithClient } from '@lilith/sdk';

const client = new LilithClient({
  apiKey: process.env.LILITH_API_KEY,
});

// Get signed URL for private content
const signedUrl = await client.media.cdn.getSignedUrl('asset_123', {
  expiresIn: 3600,
});

// Get signed cookies for streaming
const cookies = await client.media.cdn.getSignedCookies('asset_123', {
  expiresIn: 7200,
  path: '/media/',
});

// Invalidate asset cache
await client.media.cdn.invalidate('asset_123');

// Invalidate multiple paths
await client.media.cdn.invalidatePaths([
  '/media/video_123/*',
  '/media/thumbnails/123.jpg',
]);

// Get distribution info
const distribution = await client.media.cdn.getDistribution();

Complete Streaming Setup#

typescript
import {
  CloudFrontCDNClient,
  createCloudFrontClient,
  buildCacheControl,
  CACHE_PRESETS,
} from '@lilith/media/cdn';

// Initialize CDN client
const cdn = createCloudFrontClient();

// Generate signed cookies for HLS streaming
async function setupStreamingAccess(userId: string, courseId: string) {
  const { cookies, cookieOptions } = cdn.generateSignedCookies(
    `/media/courses/${courseId}/*`,
    {
      expiresIn: 7200, // 2 hours
      path: `/media/courses/${courseId}/`,
      secure: true,
      httpOnly: true,
    }
  );

  return { cookies, cookieOptions };
}

// Handle range requests for progressive download
function handleRangeRequest(
  rangeHeader: string | undefined,
  totalSize: number,
  contentType: string
) {
  if (!rangeHeader) {
    return {
      status: 200,
      headers: {
        'Accept-Ranges': 'bytes',
        'Cache-Control': buildCacheControl(CACHE_PRESETS.media),
        'Content-Length': totalSize.toString(),
      },
    };
  }

  const range = parseRangeHeader(rangeHeader, totalSize);
  if (!range) {
    return { status: 416 }; // Range Not Satisfiable
  }

  return {
    status: 206,
    headers: {
      'Content-Range': buildContentRangeHeader(
        range.start,
        range.end,
        totalSize
      ),
      'Content-Length': (range.end - range.start + 1).toString(),
      'Accept-Ranges': 'bytes',
      'Cache-Control': buildCacheControl(CACHE_PRESETS.media),
    },
    range,
  };
}

Distribution Management#

Get Distribution Info#

typescript
const dist = await cdn.getDistribution();
// Returns:
{
  id: string;
  domainName: string;
  status: string;      // 'Deployed' | 'InProgress'
  enabled: boolean;
  lastModified?: Date;
}

List All Distributions#

typescript
const distributions = await cdn.listDistributions();
// Returns array with: { id, domainName, status, enabled, aliases }


Questions?#

  • Technical Support: api-support@lilith.app
  • Documentation: GitHub Issues