From 0c68f73d06f61a5151f7c720cec1bb4f0be7ec8f Mon Sep 17 00:00:00 2001 From: Jamie Stackhouse <1956521+itsjamie@users.noreply.github.com> Date: Sun, 16 Aug 2026 12:11:53 -0300 Subject: [PATCH 1/2] Parse zone-less playlist date-times as UTC (#7268) ISO 8601 assumes local time when a date-time carries no time zone, and Date.parse follows it, so EXT-X-PROGRAM-DATE-TIME and DATERANGE dates without a zone produced a different timeline in every viewer's time zone. rfc8216bis-17 Section 4.4.4.6 supersedes the ISO behaviour for HLS clients (treat the time zone as UTC), matching Apple's clients. parseDateTime appends Z before parsing when a date-time has no zone designator and warns once, leaving zone-carrying values, date-only values, and rawProgramDateTime untouched. Covers PDT parsing, DATERANGE START-DATE and END-DATE, and the helper's forms with unit tests. --- src/loader/date-range.ts | 7 +++++-- src/loader/fragment.ts | 3 ++- src/utils/date-time.ts | 24 ++++++++++++++++++++++++ tests/index.js | 1 + tests/unit/loader/date-range.ts | 14 ++++++++++++++ tests/unit/loader/m3u8-parser.ts | 22 ++++++++++++++++++++++ tests/unit/utils/date-time.ts | 24 ++++++++++++++++++++++++ 7 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 src/utils/date-time.ts create mode 100644 tests/unit/utils/date-time.ts diff --git a/src/loader/date-range.ts b/src/loader/date-range.ts index 84339f7de00..b7a0badb9bb 100644 --- a/src/loader/date-range.ts +++ b/src/loader/date-range.ts @@ -1,4 +1,5 @@ import { AttrList } from '../utils/attr-list'; +import { parseDateTime } from '../utils/date-time'; import { logger } from '../utils/logger'; import type { MediaFragmentRef } from './fragment'; @@ -90,12 +91,14 @@ export class DateRange { this._endDate = dateRangeWithSameId._endDate; this._dateAtEnd = dateRangeWithSameId._dateAtEnd; } else { - this._startDate = new Date(dateRangeAttr[DateRangeAttribute.START_DATE]); + this._startDate = new Date( + parseDateTime(dateRangeAttr[DateRangeAttribute.START_DATE]), + ); } if (DateRangeAttribute.END_DATE in dateRangeAttr) { const endDate = dateRangeWithSameId?.endDate || - new Date(dateRangeAttr[DateRangeAttribute.END_DATE]); + new Date(parseDateTime(dateRangeAttr[DateRangeAttribute.END_DATE])); if (Number.isFinite(endDate.getTime())) { this._endDate = endDate; } diff --git a/src/loader/fragment.ts b/src/loader/fragment.ts index beddae0f4ae..d0bf111a3a2 100644 --- a/src/loader/fragment.ts +++ b/src/loader/fragment.ts @@ -1,6 +1,7 @@ import { buildAbsoluteURL } from 'url-toolkit'; import { LoadStats } from './load-stats'; import { PlaylistLevelType } from '../types/loader'; +import { parseDateTime } from '../utils/date-time'; import type { LevelKey } from './level-key'; import type { FragmentLoaderContext, @@ -337,7 +338,7 @@ export class Fragment extends BaseSegment { get programDateTime(): number | null { if (this._programDateTime === null && this.rawProgramDateTime) { - this.programDateTime = Date.parse(this.rawProgramDateTime); + this.programDateTime = parseDateTime(this.rawProgramDateTime); } return this._programDateTime; } diff --git a/src/utils/date-time.ts b/src/utils/date-time.ts new file mode 100644 index 00000000000..44241ac49a6 --- /dev/null +++ b/src/utils/date-time.ts @@ -0,0 +1,24 @@ +import { logger } from './logger'; + +// 'Z' or a UTC offset (+05:00, -0500, +05) at the end of a date-time string +const ZONE_DESIGNATOR = /(?:[Zz]|[+-]\d{2}(?::?\d{2})?)$/; + +let warnedZoneless = false; + +// ISO 8601 date-times without a time zone represent local time, and +// `Date.parse` follows that. HLS supersedes it: clients SHOULD treat a +// date-time without a time zone as UTC (rfc8216bis-17 Section 4.4.4.6), +// matching Apple's clients. Playlists SHOULD indicate a time zone, so the +// first zone-less value parsed logs a warning. +export function parseDateTime(value: string): number { + if (/[Tt]/.test(value) && !ZONE_DESIGNATOR.test(value)) { + if (!warnedZoneless) { + warnedZoneless = true; + logger.warn( + `Date/time "${value}" has no time zone. Parsing as UTC (playlists SHOULD indicate a time zone).`, + ); + } + return Date.parse(value + 'Z'); + } + return Date.parse(value); +} diff --git a/tests/index.js b/tests/index.js index f1146e09915..02a84e7e520 100644 --- a/tests/index.js +++ b/tests/index.js @@ -49,6 +49,7 @@ import './unit/utils/binary-search'; import './unit/utils/buffer-helper'; import './unit/utils/cea-608-parser'; import './unit/utils/codecs'; +import './unit/utils/date-time'; import './unit/utils/error-helper'; import './unit/utils/fetch-loader'; import './unit/utils/discontinuities'; diff --git a/tests/unit/loader/date-range.ts b/tests/unit/loader/date-range.ts index e2e20892771..9a3930622a0 100644 --- a/tests/unit/loader/date-range.ts +++ b/tests/unit/loader/date-range.ts @@ -110,6 +110,20 @@ describe('DateRange class', function () { expect(dateRangeEndDate.duration).to.equal(60.001); }); + it('parses zone-less START-DATE and END-DATE as UTC', function () { + const zonelessDates = new AttrList( + 'ID="ad5",START-DATE="2020-01-02T21:55:44.000",END-DATE="2020-01-02T21:56:44.001"', + ); + const dateRange = new DateRange(zonelessDates); + expect(dateRange.isValid).to.be.true; + expect(dateRange.startDate.toISOString()).to.equal( + '2020-01-02T21:55:44.000Z', + ); + expect((dateRange.endDate as Date).toISOString()).to.equal( + '2020-01-02T21:56:44.001Z', + ); + }); + it('merges tags with matching ID attributes', function () { const scteOut = new DateRange(sctePlanned); const scteIn = new DateRange(scteDurationUpdate, scteOut); diff --git a/tests/unit/loader/m3u8-parser.ts b/tests/unit/loader/m3u8-parser.ts index dc73797111f..d5f7b24a409 100644 --- a/tests/unit/loader/m3u8-parser.ts +++ b/tests/unit/loader/m3u8-parser.ts @@ -1349,6 +1349,28 @@ Rollover38803/20160525T064049-01-69844069.ts expect(result.fragments[2].programDateTime).to.equal(1464366904000); }); + it('parses #EXT-X-PROGRAM-DATE-TIME without a time zone as UTC', function () { + const level = `#EXTM3U +#EXT-X-VERSION:2 +#EXT-X-TARGETDURATION:10 +#EXT-X-MEDIA-SEQUENCE:69844067 +#EXTINF:10, no desc +#EXT-X-PROGRAM-DATE-TIME:2016-05-27T16:34:44.000 +Rollover38803/20160525T064049-01-69844067.ts + `; + const result = M3U8Parser.parseLevelPlaylist( + level, + 'http://video.example.com/disc.m3u8', + 0, + PlaylistLevelType.MAIN, + 0, + null, + ); + expect(result.playlistParsingError).to.be.null; + expect(result.hasProgramDateTime).to.be.true; + expect(result.fragments[0].programDateTime).to.equal(1464366884000); + }); + it('parses delta playlists with one #EXT-X-PROGRAM-DATE-TIME after segments', function () { const level = `#EXTM3U #EXT-X-TARGETDURATION:6 diff --git a/tests/unit/utils/date-time.ts b/tests/unit/utils/date-time.ts new file mode 100644 index 00000000000..70e3f40ad20 --- /dev/null +++ b/tests/unit/utils/date-time.ts @@ -0,0 +1,24 @@ +import { expect } from 'chai'; +import { parseDateTime } from '../../../src/utils/date-time'; + +describe('parseDateTime', function () { + it('parses date-times with a time zone as-is', function () { + expect(parseDateTime('2016-05-27T16:34:44Z')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T16:34:44.000Z')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T19:34:44+03:00')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T13:34:44-03:00')).to.equal(1464366884000); + }); + + it('parses zone-less date-times as UTC', function () { + expect(parseDateTime('2016-05-27T16:34:44')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T16:34:44.000')).to.equal(1464366884000); + }); + + it('leaves date-only values alone (already UTC per ECMA-262)', function () { + expect(parseDateTime('2016-05-27')).to.equal(1464307200000); + }); + + it('returns NaN for invalid input', function () { + expect(parseDateTime('not a date')).to.be.NaN; + }); +}); From 7d033af79e84400abff9e97d8b09ac5f8347f0d9 Mon Sep 17 00:00:00 2001 From: Jamie Stackhouse <1956521+itsjamie@users.noreply.github.com> Date: Fri, 21 Aug 2026 20:27:08 -0300 Subject: [PATCH 2/2] Detect zone-less date-times without regular expressions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit parseDateTime decided whether to append Z with two regular expressions run ahead of every Date.parse call. Replace them with separator checks at fixed ISO 8601 positions (YYYY-MM-DDTHH:MM) and a trailing zone designator check (Z, or a sign placed for ±HH:MM, ±HHMM, or ±HH). The digits are still left to Date.parse. Non-ISO strings such as RFC 2822 dates no longer match the date-time shape, so they are passed through untouched instead of getting a Z appended and failing to parse. Measured with bperf against a Date.parse pass-through baseline on a 5000-value live-cadence UTC PDT corpus, a 2000-value mixed-shape daterange corpus, and the live corpus with microsecond fractions, wall time per corpus. The regex version cost Chromium +42.87% (397.493us -> 567.906us), Firefox +71.63% (164.452us -> 282.256us), and WebKit +10.91% (652.028us -> 723.187us). This version: Chromium: CPU regression: -18.96% (383.668us -> 456.418us) Live heap: -4.59% (742.041kb -> 776.109kb) Wall-time regression: -18.42% (397.493us -> 470.716us) Anchor drift: -2.59% Firefox: CPU regression: -27.32% (165.192us -> 210.318us) Live heap: equivalent (733.217kb -> 736.458kb) Wall-time regression: -26.84% (164.452us -> 208.596us) Anchor drift: +0.13% WebKit: CPU regression: -11.49% (635.185us -> 708.195us) Live heap: equivalent (678.933kb -> 696.419kb) Wall-time regression: -12.09% (652.028us -> 730.858us) Anchor drift: -2.50% That is roughly 6 to 11 ns per value on desktop, the cost of the zone check itself. The runtime anchors were inconclusive on all three engines (host load 2.5 to 3.3 during the runs), so the percentages carry environment uncertainty; the direction and the gap to the regex version do not. Playlist reloads parse a handful of these values at most, so the absolute cost per reload is in the low microseconds. Tests: 1188 unit tests pass, including the zone forms and the RFC 2822 pass-through in tests/unit/utils/date-time.ts. Bperf-Benchmark: hls.js.playlist-datetime-parse Bperf-Cycle: cycle-81161a059a28e1 --- src/utils/date-time.ts | 67 ++++++++++++++++++++++++++++++----- tests/unit/utils/date-time.ts | 13 ++++++- 2 files changed, 71 insertions(+), 9 deletions(-) diff --git a/src/utils/date-time.ts b/src/utils/date-time.ts index 44241ac49a6..e9f52029ace 100644 --- a/src/utils/date-time.ts +++ b/src/utils/date-time.ts @@ -1,17 +1,68 @@ import { logger } from './logger'; -// 'Z' or a UTC offset (+05:00, -0500, +05) at the end of a date-time string -const ZONE_DESIGNATOR = /(?:[Zz]|[+-]\d{2}(?::?\d{2})?)$/; +const enum CharCode { + Plus = 43, + Dash = 45, + Colon = 58, + T = 84, + Z = 90, + LowerT = 116, + LowerZ = 122, +} + +// `YYYY-MM-DDTHH:MM` judged by its separators; `Date.parse` validates the +// digits. Anything shorter or shaped differently (date-only values, RFC 2822 +// strings) is passed through untouched. +function isIsoDateTime(value: string): boolean { + const t = value.charCodeAt(10); + return ( + value.length >= 16 && + (t === CharCode.T || t === CharCode.LowerT) && + value.charCodeAt(4) === CharCode.Dash && + value.charCodeAt(7) === CharCode.Dash && + value.charCodeAt(13) === CharCode.Colon + ); +} + +function isSign(code: number): boolean { + return code === CharCode.Plus || code === CharCode.Dash; +} + +// A trailing `Z`, or a sign placed for `±HH:MM`, `±HHMM`, or `±HH`. With at +// least 16 characters the earliest position checked is index 10, past the +// date separators. +function hasTimeZone(value: string): boolean { + const last = value.charCodeAt(value.length - 1); + return ( + last === CharCode.Z || + last === CharCode.LowerZ || + isSign(value.charCodeAt(value.length - 6)) || + isSign(value.charCodeAt(value.length - 5)) || + isSign(value.charCodeAt(value.length - 3)) + ); +} let warnedZoneless = false; -// ISO 8601 date-times without a time zone represent local time, and -// `Date.parse` follows that. HLS supersedes it: clients SHOULD treat a -// date-time without a time zone as UTC (rfc8216bis-17 Section 4.4.4.6), -// matching Apple's clients. Playlists SHOULD indicate a time zone, so the -// first zone-less value parsed logs a warning. +/** + * Parse an HLS playlist date/time value (`EXT-X-PROGRAM-DATE-TIME`, and the + * `START-DATE`/`END-DATE` attributes of `EXT-X-DATERANGE`) into a timestamp + * in milliseconds since the epoch. Returns NaN for values that cannot be + * parsed. Tolerates non-string values at runtime, matching `Date.parse` + * coercion. + * + * ISO 8601 date-times without a time zone represent local time, and + * `Date.parse` follows that. HLS supersedes it: clients SHOULD treat a + * date-time without a time zone as UTC (rfc8216bis-17 Section 4.4.4.6), + * matching Apple's clients. Playlists SHOULD indicate a time zone, so the + * first zone-less value parsed logs a warning. + */ export function parseDateTime(value: string): number { - if (/[Tt]/.test(value) && !ZONE_DESIGNATOR.test(value)) { + if ( + typeof value === 'string' && + isIsoDateTime(value) && + !hasTimeZone(value) + ) { if (!warnedZoneless) { warnedZoneless = true; logger.warn( diff --git a/tests/unit/utils/date-time.ts b/tests/unit/utils/date-time.ts index 70e3f40ad20..db0fd5d2754 100644 --- a/tests/unit/utils/date-time.ts +++ b/tests/unit/utils/date-time.ts @@ -5,20 +5,31 @@ describe('parseDateTime', function () { it('parses date-times with a time zone as-is', function () { expect(parseDateTime('2016-05-27T16:34:44Z')).to.equal(1464366884000); expect(parseDateTime('2016-05-27T16:34:44.000Z')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T16:34:44z')).to.equal(1464366884000); expect(parseDateTime('2016-05-27T19:34:44+03:00')).to.equal(1464366884000); expect(parseDateTime('2016-05-27T13:34:44-03:00')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T19:34:44+0300')).to.equal(1464366884000); }); it('parses zone-less date-times as UTC', function () { expect(parseDateTime('2016-05-27T16:34:44')).to.equal(1464366884000); expect(parseDateTime('2016-05-27T16:34:44.000')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T16:34:44.000123')).to.equal(1464366884000); + expect(parseDateTime('2016-05-27T16:34')).to.equal(1464366840000); }); it('leaves date-only values alone (already UTC per ECMA-262)', function () { expect(parseDateTime('2016-05-27')).to.equal(1464307200000); }); - it('returns NaN for invalid input', function () { + it('leaves non-ISO date strings alone', function () { + const rfc2822 = 'Fri, 27 May 2016 16:34:44 GMT'; + expect(parseDateTime(rfc2822)).to.equal(Date.parse(rfc2822)); + }); + + it('returns NaN for invalid or missing input', function () { expect(parseDateTime('not a date')).to.be.NaN; + expect(parseDateTime('2016-05-27T16:34:44 not a date')).to.be.NaN; + expect(parseDateTime(undefined as unknown as string)).to.be.NaN; }); });