fix: handle fractional-hour timezone offsets correctly (nesquena#1144)

nesquena · claude · nesquena · commit be8aee652b74 · 2026-04-27T18:16:38.000-07:00
The Etc/GMT-X mapping in _serverTzOptions can only express whole-hour
offsets — IANA Etc/GMT zones don't support fractional hours. Users in
India (+0530), Iran (+0330/+0430), Newfoundland (-0330), Nepal (+0545),
Sri Lanka (+0530), Afghanistan (+0430), and Burma (+0630) — collectively
~1.5 billion people — would see timestamps off by 30 minutes after this
PR's whole-hour-only TZ conversion. That's actively WORSE than the pre-PR
behaviour for them: pre-PR they saw browser-tz times (consistent with
their wall clock), post-PR they'd see times 30 min off from the server.

Fix: introduce _formatInServerTz(date, options) that uses offset
arithmetic — shift the timestamp by the server's offset, then format
with timeZone:'UTC' so no further conversion is applied. The formatted
output reads as the wall-clock time in the server's timezone for ANY
offset, including fractional.

_serverTzOptions is kept for whole-hour fast-path callers that spread
its result; updated to return undefined for fractional offsets so it
can't silently produce off-by-30-min output via the spread path.

ui.js: _formatMessageFooterTimestamp and tsTitle in renderMessages now
go through _formatInServerTz with a fallback to bare toLocaleString
when sessions.js hasn't loaded yet.

Tests:
- test_message_footer_timestamp_uses_server_tz: stubs _formatInServerTz
  with the same offset-arithmetic logic as sessions.js, asserts UTC+8
  conversion produces the right wall-clock hour.
- test_message_footer_timestamp_handles_fractional_offset: NEW. Stubs
  _formatInServerTz with +0530 (IST), asserts 02:00 UTC → 07:30 IST and
  explicitly NOT 07:00 (the broken Etc/GMT-5 result).
- test_ui_js_message_timestamp_uses_server_tz: relaxed to accept either
  _formatInServerTz or _serverTzOptions reference.
- test_sessions_js_has_format_in_server_tz_helper: NEW. Verifies the
  function exists and uses offset arithmetic + UTC formatting.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/static/sessions.js b/static/sessions.js
@@ -778,15 +778,43 @@ function _serverNowMs() {
 
 function _serverTzOptions() {
   // Build a timeZone option from _serverTz (e.g. "+0800" → "Etc/GMT-8").
-  // Falls back to undefined (uses browser timezone) if _serverTz is not set.
+  // Falls back to undefined (uses browser timezone) when:
+  //   - _serverTz is not set or is UTC (no offset to apply)
+  //   - _serverTz is malformed
+  //   - _serverTz has a fractional-hour component (India +0530, Iran +0330,
+  //     Newfoundland -0330, Nepal +0545, etc.) — IANA Etc/GMT zones cannot
+  //     express half/quarter-hour offsets; use _formatInServerTz() instead
+  //     for correct fractional-offset formatting.
   if (!_serverTz || _serverTz === '+0000' || _serverTz === '-0000') return undefined;
   const m = _serverTz.match(/^([+-])(\d{2})(\d{2})$/);
   if (!m) return undefined;
+  if (m[3] !== '00') return undefined;  // fractional offset — caller must use _formatInServerTz
   // IANA Etc/GMT uses inverted sign: UTC+8 → "Etc/GMT-8"
   const sign = m[1] === '+' ? '-' : '+';
   return { timeZone: `Etc/GMT${sign}${parseInt(m[2])}` };
 }
 
+function _formatInServerTz(date, options) {
+  // Format `date` in the server's wall-clock timezone, including correct
+  // handling of fractional-hour offsets that Etc/GMT cannot express.
+  //
+  // Strategy: shift the timestamp by the server's offset, then format with
+  // timeZone:'UTC' so no further conversion is applied — the formatted
+  // output reads as the wall-clock time in the server's timezone.
+  //
+  // Falls back to plain `date.toLocaleString(undefined, options)` (browser
+  // timezone) when _serverTz is absent, UTC, or malformed.
+  if (!_serverTz || _serverTz === '+0000' || _serverTz === '-0000') {
+    return date.toLocaleString(undefined, options);
+  }
+  const m = _serverTz.match(/^([+-])(\d{2})(\d{2})$/);
+  if (!m) return date.toLocaleString(undefined, options);
+  const sign = m[1] === '+' ? 1 : -1;
+  const offsetMin = sign * (parseInt(m[2]) * 60 + parseInt(m[3]));
+  const adjusted = new Date(date.getTime() + offsetMin * 60 * 1000);
+  return adjusted.toLocaleString(undefined, { ...options, timeZone: 'UTC' });
+}
+
 function _localDayOrdinal(timestampMs) {
   const date = new Date(timestampMs);
   return Math.floor(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()) / 86400000);
diff --git a/static/ui.js b/static/ui.js
@@ -2148,17 +2148,16 @@ function _formatMessageFooterTimestamp(tsVal){
   if(!tsVal) return '';
   const date=new Date(tsVal*1000);
   const now=new Date();
-  const tzOpts=(typeof _serverTzOptions==='function')?_serverTzOptions():undefined;
+  // Use _formatInServerTz when available — it correctly handles fractional-hour
+  // offsets like India +0530 that Etc/GMT cannot express. Falls back to plain
+  // toLocaleString when sessions.js hasn't loaded yet.
+  const fmt=(typeof _formatInServerTz==='function')?_formatInServerTz:null;
   if(_isSameLocalDay(date, now)){
-    return date.toLocaleTimeString([], {hour:'2-digit', minute:'2-digit', ...tzOpts});
-  }
-  return date.toLocaleString([], {
-    month:'short',
-    day:'numeric',
-    hour:'numeric',
-    minute:'2-digit',
-    ...tzOpts,
-  });
+    const opts={hour:'2-digit', minute:'2-digit'};
+    return fmt?fmt(date,opts):date.toLocaleTimeString([], opts);
+  }
+  const opts={month:'short', day:'numeric', hour:'numeric', minute:'2-digit'};
+  return fmt?fmt(date,opts):date.toLocaleString([], opts);
 }
 function _compressionStatusCardHtml({
   statusLabel,
@@ -2363,8 +2362,10 @@ function renderMessages(){
     const retryBtn = isLastAssistant ? `<button class="msg-action-btn" title="${t('regenerate')}" onclick="regenerateResponse(this)">${li('rotate-ccw',13)}</button>` : '';
     const copyBtn  = `<button class="msg-copy-btn msg-action-btn" title="${t('copy')}" onclick="copyMsg(this)">${li('copy',13)}</button>`;
     const tsVal=m._ts||m.timestamp;
-    const _tzo=(typeof _serverTzOptions==='function')?_serverTzOptions():undefined;
-    const tsTitle=tsVal?new Date(tsVal*1000).toLocaleString([],_tzo):'';
+    // _formatInServerTz handles fractional-hour offsets (India +0530 etc.)
+    // correctly via offset arithmetic; bare toLocaleString is the browser-tz fallback.
+    const _fmtSv=(typeof _formatInServerTz==='function')?_formatInServerTz:null;
+    const tsTitle=tsVal?(_fmtSv?_fmtSv(new Date(tsVal*1000),{}):new Date(tsVal*1000).toLocaleString()):'';
     const tsTime=_formatMessageFooterTimestamp(tsVal);
     const timeHtml = tsTime ? `<span class="msg-time" title="${esc(tsTitle)}">${tsTime}</span>` : '';
     const footHtml = `<div class="msg-foot">${timeHtml}<span class="msg-actions">${editBtn}${copyBtn}${retryBtn}</span></div>`;
diff --git a/tests/test_issue1144_session_time_sync.py b/tests/test_issue1144_session_time_sync.py
@@ -326,34 +326,89 @@ def _extract_is_same_local_day() -> str:
 
 
 def test_message_footer_timestamp_uses_server_tz():
-    """_formatMessageFooterTimestamp should use _serverTzOptions for display."""
+    """_formatMessageFooterTimestamp should use _formatInServerTz for display."""
     is_same_day_fn = _extract_is_same_local_day()
     fmt_fn = _extract_ui_function("_formatMessageFooterTimestamp")
     script = textwrap.dedent(
         f"""
         process.env.TZ = 'America/New_York';
         let _serverTimeDelta = 0;
         let _serverTz = '+0800';
-        function _serverTzOptions() {{
-          if (!_serverTz || _serverTz === '+0000' || _serverTz === '-0000') return undefined;
+        // Stub _formatInServerTz with the same offset-arithmetic semantics
+        // as the real implementation in sessions.js.
+        function _formatInServerTz(date, options) {{
+          if (!_serverTz || _serverTz === '+0000' || _serverTz === '-0000') {{
+            return date.toLocaleString(undefined, options);
+          }}
           const m = _serverTz.match(/^([+-])(\\d{{2}})(\\d{{2}})$/);
-          if (!m) return undefined;
-          const sign = m[1] === '+' ? '-' : '+';
-          return {{ timeZone: `Etc/GMT${{sign}}${{parseInt(m[2])}}` }};
+          if (!m) return date.toLocaleString(undefined, options);
+          const sign = m[1] === '+' ? 1 : -1;
+          const offsetMin = sign * (parseInt(m[2]) * 60 + parseInt(m[3]));
+          const adjusted = new Date(date.getTime() + offsetMin * 60 * 1000);
+          return adjusted.toLocaleString(undefined, {{ ...options, timeZone: 'UTC' }});
         }}
         {is_same_day_fn}
         {fmt_fn}
-        // Timestamp for 2026-04-28 10:00:00 UTC = 18:00 UTC+8
+        // Timestamp for 2026-03-29 02:00:00 UTC = 10:00 in UTC+8
         const tsVal = 1774749600;
         const result = _formatMessageFooterTimestamp(tsVal);
         process.stdout.write(JSON.stringify({{ formatted: result }}));
         """
     )
     proc = subprocess.run(["node", "-e", script], check=True, capture_output=True, text=True)
     data = json.loads(proc.stdout)
-    # Should display in Etc/GMT-8 timezone (UTC+8), not America/New_York
-    # 2026-03-29 02:00 UTC = 10:00 AM in Etc/GMT-8
-    assert "10:00 AM" in data["formatted"]
+    # Should display in UTC+8, not America/New_York.
+    # 2026-03-29 02:00 UTC = 10:00 in UTC+8
+    assert "10:00 AM" in data["formatted"], (
+        f"Expected '10:00 AM' (UTC+8 wall-clock) in {data['formatted']!r}"
+    )
+
+
+def test_message_footer_timestamp_handles_fractional_offset():
+    """_formatMessageFooterTimestamp must correctly format in IST (+0530) and
+    other half-hour offsets — Etc/GMT can't express these but offset
+    arithmetic in _formatInServerTz handles them correctly. Affects ~1.5B
+    users in India, Iran, Newfoundland, Nepal, Sri Lanka, etc."""
+    is_same_day_fn = _extract_is_same_local_day()
+    fmt_fn = _extract_ui_function("_formatMessageFooterTimestamp")
+    script = textwrap.dedent(
+        f"""
+        process.env.TZ = 'UTC';
+        let _serverTimeDelta = 0;
+        let _serverTz = '+0530';  // India IST
+        function _formatInServerTz(date, options) {{
+          if (!_serverTz || _serverTz === '+0000' || _serverTz === '-0000') {{
+            return date.toLocaleString(undefined, options);
+          }}
+          const m = _serverTz.match(/^([+-])(\\d{{2}})(\\d{{2}})$/);
+          if (!m) return date.toLocaleString(undefined, options);
+          const sign = m[1] === '+' ? 1 : -1;
+          const offsetMin = sign * (parseInt(m[2]) * 60 + parseInt(m[3]));
+          const adjusted = new Date(date.getTime() + offsetMin * 60 * 1000);
+          return adjusted.toLocaleString(undefined, {{ ...options, timeZone: 'UTC' }});
+        }}
+        {is_same_day_fn}
+        {fmt_fn}
+        // 2026-03-29 02:00:00 UTC = 07:30 IST (UTC+5:30)
+        const tsVal = 1774749600;
+        const result = _formatMessageFooterTimestamp(tsVal);
+        process.stdout.write(JSON.stringify({{ formatted: result }}));
+        """
+    )
+    proc = subprocess.run(["node", "-e", script], check=True, capture_output=True, text=True)
+    data = json.loads(proc.stdout)
+    # 2026-03-29 02:00 UTC = 07:30 IST. Old Etc/GMT-5 mapping would have shown 07:00.
+    # Accept either "07:30" or "7:30" (en-US uses hour:'numeric' for non-same-day).
+    formatted = data["formatted"]
+    assert "07:30" in formatted or "7:30" in formatted, (
+        f"Expected '7:30' (IST = UTC+5:30 wall-clock) in {formatted!r}; "
+        "Etc/GMT-5 path would show 7:00 — off by 30 min."
+    )
+    # And explicitly NOT the broken Etc/GMT-5 output (07:00 / 7:00 with 0 minutes).
+    assert ":00" not in formatted.split("M")[0], (
+        f"Output contains ':00' which would be the off-by-30-min Etc/GMT-5 result; "
+        f"got {formatted!r}"
+    )
 
 
 def test_message_footer_timestamp_falls_back_without_server_tz():
@@ -404,7 +459,34 @@ def test_sessions_js_uses_server_now_in_time_functions():
 
 
 def test_ui_js_message_timestamp_uses_server_tz():
-    """ui.js _formatMessageFooterTimestamp should reference _serverTzOptions."""
-    assert "_serverTzOptions" in UI_JS
-    # tsTitle in message rendering should also use it
-    assert "_tzo=" in UI_JS
+    """ui.js timestamp formatters should reference the server-tz helpers
+    so they pick up the server's wall-clock time (with correct fractional
+    offset handling) rather than always rendering in browser TZ."""
+    # _formatInServerTz is the canonical helper that handles both whole-hour
+    # and fractional offsets (e.g. India +0530). _serverTzOptions is the
+    # whole-hour fast path; either reference indicates server-tz awareness.
+    assert "_formatInServerTz" in UI_JS or "_serverTzOptions" in UI_JS, (
+        "ui.js must reference one of the server-tz helpers so message "
+        "timestamps render in the server's wall-clock time"
+    )
+
+
+def test_sessions_js_has_format_in_server_tz_helper():
+    """_formatInServerTz must exist and use offset arithmetic so fractional
+    offsets (India +0530, Iran +0330, etc.) format correctly."""
+    assert "function _formatInServerTz" in SESSIONS_JS, (
+        "_formatInServerTz must be defined to handle fractional-hour "
+        "offsets that Etc/GMT cannot express"
+    )
+    # Find the function body
+    start = SESSIONS_JS.find("function _formatInServerTz")
+    end = SESSIONS_JS.find("\n}", start) + 2
+    body = SESSIONS_JS[start:end]
+    # Offset arithmetic + timeZone:'UTC' is the correct strategy
+    assert "timeZone: 'UTC'" in body or 'timeZone: "UTC"' in body, (
+        "_formatInServerTz must format in UTC after applying the offset "
+        "via arithmetic — that's how fractional offsets work correctly"
+    )
+    assert "60 * 1000" in body or "* 60_000" in body, (
+        "_formatInServerTz must convert the offset minutes to milliseconds"
+    )
