feat(URL): Support seeking logs by timestamp via URL parameter (resolves #117).

src/components/AppController.tsx

@@ -3,32 +3,149 @@ import React, {
     useRef,
 } from "react";
 
+import useLogFileManagerProxyStore from "../stores/logFileManagerProxyStore";
 import useLogFileStore from "../stores/logFileStore";
+import {handleErrorWithNotification} from "../stores/notificationStore";
 import useQueryStore from "../stores/queryStore";
 import useViewStore from "../stores/viewStore";
 import {Nullable} from "../typings/common";
 import {
     CURSOR_CODE,
     CursorType,
 } from "../typings/worker";
+import {
+    findNearestLessThanOrEqualElement,
+    isWithinBounds,
+} from "../utils/data";
+import {clamp} from "../utils/math.ts";
 import {
     getWindowUrlHashParams,
     getWindowUrlSearchParams,
+    updateWindowUrlHashParams,
     URL_HASH_PARAMS_DEFAULT,
     URL_SEARCH_PARAMS_DEFAULT,
 } from "../utils/url";
 
 
+/**
+ * Updates the log event number in the URL to `logEventNum` if it's within the bounds of
+ * `logEventNumsOnPage`.
+ *
+ * @param logEventNum
+ * @param logEventNumsOnPage
+ * @return Whether `logEventNum` is within the bounds of `logEventNumsOnPage`.
+ */
+const updateUrlIfEventOnPage = (
+    logEventNum: number,
+    logEventNumsOnPage: number[]
+): boolean => {
+    if (false === isWithinBounds(logEventNumsOnPage, logEventNum)) {
+        return false;
+    }
+
+    const nearestIdx = findNearestLessThanOrEqualElement(
+        logEventNumsOnPage,
+        logEventNum
+    );
+
+    // Since `isWithinBounds` returned `true`, then:
+    // - `logEventNumsOnPage` must bound `logEventNum`.
+    // - `logEventNumsOnPage` cannot be empty.
+    // - `nearestIdx` cannot be `null`.
+    //
+    // Therefore, we can safely cast:
+    // - `nearestIdx` from `Nullable<number>` to `number`.
+    // - `logEventNumsOnPage[nearestIdx]` from `number | undefined` to `number`.
+    const nearestLogEventNum = logEventNumsOnPage[nearestIdx as number] as number;
+
+    updateWindowUrlHashParams({
+        logEventNum: nearestLogEventNum,
+    });
+
+    return true;
+};
+
+
+/**
+ * Determines the cursor for navigating log events based on URL hash parameters.
+ *
+ * @param params An object containing the following properties:
+ * @param params.isPrettified Whether the log view is in prettified mode.
+ * @param params.logEventNum The log event number from the URL hash.
+ * @param params.timestamp The timestamp from the URL hash.
+ * @return `CursorType` object if a navigation action is needed, or `null` if no action is required.
+ */
+const getCursorFromHashParams = ({isPrettified, logEventNum, timestamp}: {
+    isPrettified: boolean; logEventNum: number; timestamp: number;
+}): Nullable<CursorType> => {
+    const {numEvents} = useLogFileStore.getState();
+    if (0 === numEvents) {
+        updateWindowUrlHashParams({logEventNum: URL_HASH_PARAMS_DEFAULT.logEventNum});
+
+        return null;
+    }
+
+    const {
+        isPrettified: prevIsPrettified, updateIsPrettified, updateLogEventNum,
+    } = useViewStore.getState();
+    const clampedLogEventNum = clamp(logEventNum, 1, numEvents);
+
+    if (isPrettified !== prevIsPrettified) {
+        updateIsPrettified(isPrettified);
+
+        return {
+            code: CURSOR_CODE.EVENT_NUM,
+            args: {eventNum: clampedLogEventNum},
+        };
+    }
+
+    if (timestamp !== URL_HASH_PARAMS_DEFAULT.timestamp) {
+        return {
+            code: CURSOR_CODE.TIMESTAMP,
+            args: {timestamp: timestamp},
+        };
+    } else if (logEventNum !== URL_HASH_PARAMS_DEFAULT.logEventNum) {
+        updateLogEventNum(logEventNum);
+        const {beginLineNumToLogEventNum} = useViewStore.getState();
+        const logEventNumsOnPage: number [] = Array.from(beginLineNumToLogEventNum.values());
+        if (updateUrlIfEventOnPage(clampedLogEventNum, logEventNumsOnPage)) {
+            // No need to request a new page since the log event is on the current page.
+            return null;
+        }
+
+        return {
+            code: CURSOR_CODE.EVENT_NUM,
+            args: {eventNum: clampedLogEventNum},
+        };
+    }
+
+    // If we reach here, we have no valid cursor.
+    return null;
+};
+
 /**
  * Updates view-related states from URL hash parameters.
  * NOTE: this may modify the URL parameters.
  */
 const updateViewHashParams = () => {
-    const {isPrettified, logEventNum} = getWindowUrlHashParams();
-    const {updateIsPrettified, updateLogEventNum} = useViewStore.getState();
+    const {isPrettified, logEventNum, timestamp} = getWindowUrlHashParams();
+    updateWindowUrlHashParams({
+        isPrettified: URL_HASH_PARAMS_DEFAULT.isPrettified,
+        timestamp: URL_HASH_PARAMS_DEFAULT.timestamp,
+    });
 
-    updateIsPrettified(isPrettified);
-    updateLogEventNum(logEventNum);
+    const cursor = getCursorFromHashParams({isPrettified, logEventNum, timestamp});
+    if (null === cursor) {
+        // If no cursor was set, we can return early.
+        return;
+    }
+
+    (async () => {
+        const {logFileManagerProxy} = useLogFileManagerProxyStore.getState();
+        const {updatePageData} = useViewStore.getState();
+        const pageData = await logFileManagerProxy.loadPage(cursor, isPrettified);
+        updatePageData(pageData);
+    })().catch(handleErrorWithNotification);
 };
 
 /**
@@ -39,6 +156,8 @@ const updateViewHashParams = () => {
  */
 const updateQueryHashParams = () => {
     const {queryIsCaseSensitive, queryIsRegex, queryString} = getWindowUrlHashParams();
+    updateWindowUrlHashParams({queryIsCaseSensitive, queryIsRegex, queryString});
+
     const {
         queryIsCaseSensitive: currentQueryIsCaseSensitive,
         queryIsRegex: currentQueryIsRegex,
@@ -110,7 +229,12 @@ const AppController = ({children}: AppControllerProps) => {
         if (URL_SEARCH_PARAMS_DEFAULT.filePath !== searchParams.filePath) {
             let cursor: CursorType = {code: CURSOR_CODE.LAST_EVENT, args: null};
 
-            if (URL_HASH_PARAMS_DEFAULT.logEventNum !== hashParams.logEventNum) {
+            if (URL_HASH_PARAMS_DEFAULT.timestamp !== hashParams.timestamp) {
+                cursor = {
+                    code: CURSOR_CODE.TIMESTAMP,
+                    args: {timestamp: hashParams.timestamp},
+                };
+            } else if (URL_HASH_PARAMS_DEFAULT.logEventNum !== hashParams.logEventNum) {
                 cursor = {
                     code: CURSOR_CODE.EVENT_NUM,
                     args: {eventNum: hashParams.logEventNum},

src/components/CentralContainer/Sidebar/SidebarTabs/SearchTabPanel/index.tsx

@@ -17,7 +17,10 @@ import {
     TAB_DISPLAY_NAMES,
     TAB_NAME,
 } from "../../../../../typings/tab";
-import {copyPermalinkToClipboard} from "../../../../../utils/url";
+import {
+    copyPermalinkToClipboard,
+    URL_HASH_PARAMS_DEFAULT,
+} from "../../../../../utils/url";
 import CustomTabPanel from "../CustomTabPanel";
 import PanelTitleButton from "../PanelTitleButton";
 import QueryInputBox from "./QueryInputBox";
@@ -55,7 +58,7 @@ const SearchTabPanel = () => {
         setQueryString(queryString);
 
         copyPermalinkToClipboard({}, {
-            logEventNum: null,
+            logEventNum: URL_HASH_PARAMS_DEFAULT.logEventNum,
             queryString: queryString,
             queryIsCaseSensitive: queryIsCaseSensitive,
             queryIsRegex: queryIsRegex,

src/services/LogFileManager/index.ts

@@ -438,6 +438,8 @@ class LogFileManager {
      */
     #getCursorData (cursor: CursorType, numActiveEvents: number): CursorData {
         const {code, args} = cursor;
+
+        let eventNum = 0;
         switch (code) {
             case CURSOR_CODE.PAGE_NUM:
                 return getPageNumCursorData(
@@ -449,15 +451,25 @@ class LogFileManager {
             case CURSOR_CODE.LAST_EVENT:
                 return getLastEventCursorData(numActiveEvents, this.#pageSize);
             case CURSOR_CODE.EVENT_NUM:
-                return getEventNumCursorData(
-                    args.eventNum,
-                    numActiveEvents,
-                    this.#pageSize,
-                    this.#decoder.getFilteredLogEventMap(),
-                );
+                ({eventNum} = args);
+                break;
+            case CURSOR_CODE.TIMESTAMP: {
+                const eventIdx = this.#decoder.findNearestLogEventByTimestamp(args.timestamp);
+                if (null !== eventIdx) {
+                    eventNum = eventIdx + 1;
+                }
+                break;
+            }
             default:
-                throw new Error(`Unsupported cursor type: ${code}`);
+                throw new Error(`Unsupported cursor code: ${code as string}`);
         }
+
+        return getEventNumCursorData(
+            eventNum,
+            numActiveEvents,
+            this.#pageSize,
+            this.#decoder.getFilteredLogEventMap(),
+        );
     }
 }
 

src/services/decoders/ClpIrDecoder/index.ts

@@ -95,6 +95,10 @@ class ClpIrDecoder implements Decoder {
         return this.#streamReader.getMetadata();
     }
 
+    findNearestLogEventByTimestamp (timestamp: number): Nullable<number> {
+        return this.#streamReader.findNearestLogEventByTimestamp(BigInt(timestamp));
+    }
+
     setLogLevelFilter (logLevelFilter: LogLevelFilter): boolean {
         this.#streamReader.filterLogEvents(logLevelFilter);
 

src/services/decoders/JsonlDecoder/index.ts

@@ -138,6 +138,34 @@ class JsonlDecoder implements Decoder {
         return results;
     }
 
+    findNearestLogEventByTimestamp (timestamp: number): Nullable<number> {
+        let low = 0;
+        let high = this.#logEvents.length - 1;
+        if (high < low) {
+            return null;
+        }
+
+        while (low <= high) {
+            const mid = Math.floor((low + high) / 2);
+
+            // `mid` is guaranteed to be within bounds since `low <= high`.
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const midTimestamp = this.#logEvents[mid]!.timestamp.valueOf();
+            if (midTimestamp <= timestamp) {
+                low = mid + 1;
+            } else {
+                high = mid - 1;
+            }
+        }
+
+        // corner case: all log events have timestamps >= timestamp
+        if (0 > high) {
+            return 0;
+        }
+
+        return high;
+    }
+
     /**
      * Parses each line from the data array and buffers it internally.
      *

src/stores/viewStore/createViewPageSlice.ts

@@ -101,10 +101,11 @@ const createViewPageSlice: StateCreator<
         });
     },
     updatePageData: (pageData: PageData) => {
-        const {setPageData, updateLogEventNum} = get();
+        const {setPageData} = get();
         setPageData(pageData);
         const newLogEventNum = pageData.logEventNum;
         updateWindowUrlHashParams({logEventNum: newLogEventNum});
+        const {updateLogEventNum} = get();
         updateLogEventNum(newLogEventNum);
         const {setUiState} = useUiStore.getState();
         setUiState(UI_STATE.READY);

src/typings/decoders.ts

@@ -112,6 +112,25 @@ interface Decoder {
         endIdx: number,
         useFilter: boolean
     ): Nullable<DecodeResult[]>;
+
+    /**
+     * Finds the log event, L, where if we assume:
+     *
+     * - the collection of log events is sorted in chronological order;
+     * - and we insert a marker log event, M, with timestamp `timestamp` into the collection (if log
+     *   events with timestamp `timestamp` already exist in the collection, M should be inserted
+     *   after them).
+     *
+     * L is the event just before M, if M is not the first event in the collection; otherwise L is
+     * the event just after M.
+     *
+     * NOTE: If the collection of log events isn't in chronological order, this method has undefined
+     * behaviour.
+     *
+     * @param timestamp
+     * @return The index of the log event L.
+     */
+    findNearestLogEventByTimestamp(timestamp: number): Nullable<number>;
 }
 
 export type {

src/typings/url.ts

@@ -6,11 +6,12 @@ enum SEARCH_PARAM_NAMES {
 }
 
 enum HASH_PARAM_NAMES {
-    LOG_EVENT_NUM = "logEventNum",
     IS_PRETTIFIED = "isPrettified",
+    LOG_EVENT_NUM = "logEventNum",
     QUERY_IS_CASE_SENSITIVE = "queryIsCaseSensitive",
     QUERY_IS_REGEX = "queryIsRegex",
     QUERY_STRING = "queryString",
+    TIMESTAMP = "timestamp",
 }
 
 interface UrlSearchParams {
@@ -23,6 +24,7 @@ interface UrlHashParams {
     [HASH_PARAM_NAMES.QUERY_IS_CASE_SENSITIVE]: boolean;
     [HASH_PARAM_NAMES.QUERY_IS_REGEX]: boolean;
     [HASH_PARAM_NAMES.QUERY_STRING]: string;
+    [HASH_PARAM_NAMES.TIMESTAMP]: number;
 }
 
 type UrlSearchParamUpdatesType = {

src/typings/worker.ts

@@ -27,24 +27,24 @@ enum EVENT_POSITION_ON_PAGE {
  * - PAGE_NUM: the first or last event on the given page
  */
 enum CURSOR_CODE {
-    LAST_EVENT = "lastEvent",
     EVENT_NUM = "eventNum",
-    TIMESTAMP = "timestamp",
+    LAST_EVENT = "lastEvent",
     PAGE_NUM = "pageNum",
+    TIMESTAMP = "timestamp",
 }
 
 type CursorArgMap = {
-    [CURSOR_CODE.LAST_EVENT]: null;
     [CURSOR_CODE.EVENT_NUM]: {
         eventNum: number;
     };
-    [CURSOR_CODE.TIMESTAMP]: {
-        timestamp: number;
-    };
+    [CURSOR_CODE.LAST_EVENT]: null;
     [CURSOR_CODE.PAGE_NUM]: {
         pageNum: number;
         eventPositionOnPage: EVENT_POSITION_ON_PAGE;
     };
+    [CURSOR_CODE.TIMESTAMP]: {
+        timestamp: number;
+    };
 };
 
 type CursorType = {