Apply server supplied cache control settings for region url provider (#1669)

Author: lukasIO

.changeset/afraid-yaks-teach.md

@@ -0,0 +1,5 @@
+---
+"livekit-client": patch
+---
+
+Apply server supplied cache control settings for region url provider

src/room/RegionUrlProvider.ts

@@ -1,7 +1,7 @@
 import type { RegionInfo, RegionSettings } from '@livekit/protocol';
 import log from '../logger';
 import { ConnectionError, ConnectionErrorReason } from './errors';
-import { isCloud } from './utils';
+import { extractMaxAgeFromRequestHeaders, isCloud } from './utils';
 
 export class RegionUrlProvider {
   private serverUrl: URL;
@@ -12,7 +12,7 @@ export class RegionUrlProvider {
 
   private lastUpdateAt: number = 0;
 
-  private settingsCacheTime = 3_000;
+  private settingsCacheTimeInMs = 3_000;
 
   private attemptedRegions: RegionInfo[] = [];
 
@@ -37,7 +37,7 @@ export class RegionUrlProvider {
     if (!this.isCloud()) {
       throw Error('region availability is only supported for LiveKit Cloud domains');
     }
-    if (!this.regionSettings || Date.now() - this.lastUpdateAt > this.settingsCacheTime) {
+    if (!this.regionSettings || Date.now() - this.lastUpdateAt > this.settingsCacheTimeInMs) {
       this.regionSettings = await this.fetchRegionSettings(abortSignal);
     }
     const regionsLeft = this.regionSettings.regions.filter(
@@ -64,6 +64,11 @@ export class RegionUrlProvider {
       signal,
     });
     if (regionSettingsResponse.ok) {
+      const maxAge = extractMaxAgeFromRequestHeaders(regionSettingsResponse.headers);
+      if (maxAge) {
+        log.debug(`setting local region settings cache time to ${maxAge} seconds`);
+        this.settingsCacheTimeInMs = maxAge * 1000;
+      }
       const regionSettings = (await regionSettingsResponse.json()) as RegionSettings;
       this.lastUpdateAt = Date.now();
       return regionSettings;

src/room/utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { splitUtf8, toWebsocketUrl } from './utils';
+import { extractMaxAgeFromRequestHeaders, splitUtf8, toWebsocketUrl } from './utils';
 
 describe('toWebsocketUrl', () => {
   it('leaves wss urls alone', () => {
@@ -60,3 +60,118 @@ describe('splitUtf8', () => {
     expect(splitUtf8('', 5)).toEqual([]);
   });
 });
+
+describe('extractMaxAgeFromRequestHeaders', () => {
+  it('extracts max-age from valid Cache-Control header', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=3600');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(3600);
+  });
+
+  it('extracts max-age from Cache-Control header with multiple directives', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'public, max-age=7200, must-revalidate');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(7200);
+  });
+
+  it('extracts max-age when it appears at the beginning', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=1800, public, no-cache');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(1800);
+  });
+
+  it('extracts max-age when it appears in the middle', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'public, max-age=900, no-store');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(900);
+  });
+
+  it('handles max-age with value 0', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=0');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(0);
+  });
+
+  it('handles large max-age values', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=31536000'); // 1 year
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(31536000);
+  });
+
+  it('returns undefined when Cache-Control header is missing', () => {
+    const headers = new Headers();
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('returns undefined when Cache-Control header exists but has no max-age', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'public, no-cache, must-revalidate');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('returns undefined when Cache-Control header is empty', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', '');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('handles Cache-Control header with extra whitespace', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', '  public,  max-age=1200  , no-cache  ');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(1200);
+  });
+
+  it('returns undefined for malformed max-age values', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=abc, public');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('handles max-age with leading zeros', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=0003600');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(3600);
+  });
+
+  it('takes the first max-age value when multiple are present', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=1800, public, max-age=3600');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(1800);
+  });
+
+  it('handles case-insensitive Cache-Control header name', () => {
+    const headers = new Headers();
+    headers.set('cache-control', 'max-age=2400');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(2400);
+  });
+
+  it('handles Cache-Control with s-maxage (should ignore s-maxage)', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 's-maxage=1800, max-age=3600');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(3600);
+  });
+
+  it('returns undefined when only s-maxage is present (no max-age)', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 's-maxage=1800, public');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('returns undefined for negative max-age values (regex only matches positive digits)', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'max-age=-100');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('ignores non standard cache control custom-max-age values', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'custom-max-age=7200');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBeUndefined();
+  });
+
+  it('still works with comma separated non standard cache control custom-max-age values', () => {
+    const headers = new Headers();
+    headers.set('Cache-Control', 'custom-max-age=7200,max-age=3600');
+    expect(extractMaxAgeFromRequestHeaders(headers)).toBe(3600);
+  });
+});

src/room/utils.ts

@@ -750,3 +750,14 @@ export function splitUtf8(s: string, n: number): Uint8Array[] {
   }
   return result;
 }
+
+export function extractMaxAgeFromRequestHeaders(headers: Headers): number | undefined {
+  const cacheControl = headers.get('Cache-Control');
+  if (cacheControl) {
+    const maxAge = cacheControl.match(/(?:^|[,\s])max-age=(\d+)/)?.[1];
+    if (maxAge) {
+      return parseInt(maxAge, 10);
+    }
+  }
+  return undefined;
+}