@osqd/bothandlerjs 0.4.0 → 0.5.0

package/dist/config.d.ts

@@ -3,6 +3,7 @@ import type { PresetName } from "./policy/presets.js";
 import type { Clock } from "./internal/clock.js";
 import type { DnsResolver } from "./internal/dns.js";
 import type { Detector } from "./detectors/types.js";
+import type { CrawlerVerificationOptions } from "./detectors/crawler-verification.js";
 import type { BotSignature } from "./detectors/known-bots.js";
 import type { ActionParams, FalsePositivePolicy, Rule } from "./policy/types.js";
 import type { CustomHandler } from "./actions/types.js";
@@ -60,6 +61,15 @@ export interface BotHandlerConfig {
     detectors?: readonly Detector[];
     /** Appended to the built-in set. Ignored when `detectors` is given. */
     extraDetectors?: readonly Detector[];
+    /**
+     * How claimed crawler identities are confirmed or refuted.
+     *
+     * Chiefly `verifiers`: your own answer to "is this really Googlebot", for the many
+     * identities that publish no proof this library can check on its own. Also the two
+     * strictness flags, which were documented on the detector and reachable only by
+     * rebuilding the whole detector list.
+     */
+    crawlerVerification?: CrawlerVerificationOptions;
     /** A named starting policy. Combined with `rules`, which are evaluated first. */
     preset?: PresetName;
     /** Your own rules, evaluated before any preset's. */

package/dist/dashboard/client/feed.d.ts

@@ -1,6 +1,22 @@
 export declare function initFeed(): void;
 /** Applies filter state that arrived in the URL rather than from a click. */
 export declare function reflectFilterButtons(): void;
+/**
+ * Fetches the entries this viewer never received, and merges them.
+ *
+ * They were never lost. The rate cap keeps a burst off the *stream* and the lag guard
+ * drops frames a slow socket cannot take, but both leave the ring alone — and the opening
+ * replay is droppable too, so a first load of a busy dashboard can arrive with most of the
+ * backlog missing. `/api/feed` serves that ring whole, and `ingest` is keyed on the request
+ * id, so merging it is idempotent: what is already held is refreshed, what is missing is
+ * added.
+ *
+ * On demand rather than on a timer. Skips happen exactly when the origin is busiest, and a
+ * dashboard that answered every skip by re-fetching the whole ring would be a load
+ * amplifier pointed at the process it is meant to be watching — which is the thing
+ * `maxEventsPerSecond` exists to prevent.
+ */
+export declare function loadSkipped(): Promise<void>;
 export declare function drawFeed(): void;
 /** Drops every cached node. Used when the feed is cleared under the page's feet. */
 export declare function resetFeedCache(): void;

package/dist/dashboard/client/format.d.ts

@@ -5,7 +5,25 @@ export declare function ms(value: number): string;
 export declare function uptime(milliseconds: number): string;
 export declare function rangeLabel(milliseconds: number): string;
 /** Wall-clock time for a feed row. Local, seconds included, because a feed moves in seconds. */
+/**
+ * A time, always as 24-hour HH:MM:SS.
+ *
+ * Built from the local components rather than handed to `toLocaleTimeString`, which
+ * answers in whatever the viewer's locale prefers — so the same feed read "4:40:46 PM" on
+ * one operator's screen and "16:40:46" on the next, and a dashboard two people look at
+ * together should not disagree with itself about what time it is. Local time, not UTC:
+ * this is the clock on the wall next to the server somebody is watching.
+ */
 export declare function clockTime(at: number): string;
+/** A date, always as DD-MM-YYYY. */
+export declare function clockDate(at: number): string;
+/**
+ * Both, for the places where the time alone is ambiguous.
+ *
+ * An actor's first sighting can be days back, and "first seen 09:14:02" invites the reader
+ * to assume it was this morning.
+ */
+export declare function clockStamp(at: number): string;
 /**
  * What "this window" actually holds, said out loud.
  *

package/dist/dashboard/client/pager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The pager both tables use.
+ *
+ * One renderer rather than two, because the feed pages in the browser and the Actors
+ * table pages on the server and *neither of those facts belongs in the control*. What it
+ * needs to know is where you are and what it should do when you press something.
+ *
+ * Rendered twice per table, above and below. A table of fifty rows is taller than the
+ * window on most screens, and a pager only at the bottom means scrolling to the end to go
+ * back to the top of the next page.
+ */
+export interface PagerModel {
+    /** Zero-based. */
+    page: number;
+    /** What the range reads: `1–50 of 212`. Total omitted where the total is not known. */
+    from: number;
+    to: number;
+    total?: number;
+    atStart: boolean;
+    atEnd: boolean;
+    /** Shown next to the range when the list is being held still. */
+    held?: string;
+    go: (page: number) => void;
+    size?: {
+        current: number;
+        choices: readonly number[];
+        set: (size: number) => void;
+    };
+}
+export declare function renderPager(host: HTMLElement, model: PagerModel, options: {
+    withSize: boolean;
+}): void;

package/dist/dashboard/client/store.d.ts

@@ -29,6 +29,33 @@ export interface State {
     bufferedWhilePaused: number;
     /** Frames the server dropped because *this* connection was too slow to take them. */
     laggedDrops: number;
+    /**
+     * Which page of the feed is showing, newest first, zero-based.
+     *
+     * Zero follows the live feed. Any other page is a position in history, so arriving
+     * requests must not shuffle it under the reader — see `feedFrozen`.
+     */
+    feedPage: number;
+    /**
+     * The matching rows as they stood when the reader left page zero.
+     *
+     * Without this, one request arriving while somebody reads page three moves every row
+     * down by one and they are silently reading different rows than the ones they were
+     * looking at. Frozen on leaving page zero, dropped on returning to it.
+     */
+    feedFrozen: Row[] | undefined;
+    /** Which page of the Actors table is showing. Paged on the server, by offset. */
+    actorsPage: number;
+    /** How many rows a page of each table holds. Chosen in the page, not configured. */
+    feedPageSize: number;
+    actorsPageSize: number;
+    /**
+     * How many skipped entries have already been fetched back and merged.
+     *
+     * The server's `skipped` only ever grows, so the badge subtracts this to say how many
+     * are *still* missing rather than how many ever were.
+     */
+    caughtUp: number;
 }
 export declare const state: State;
 /**
@@ -43,9 +70,42 @@ export declare const state: State;
 export declare function ingest(entry: DashboardEntry): void;
 export declare function clearFeed(): void;
 export declare function setSearch(value: string): void;
+/** Back to the live first page, thawed. Called whenever what matches changes. */
+export declare function resetPaging(): void;
+/**
+ * Puts the ring back in time order after a bulk merge.
+ *
+ * `ingest` appends, because the stream delivers in order and appending is what that
+ * costs. A backlog fetched over HTTP is not in order relative to what is already held —
+ * it is *older* — so merging without this leaves yesterday's requests sitting at the
+ * newest end, which is where the feed reads from.
+ */
+export declare function sortRows(): void;
 export declare function matches(row: Row): boolean;
+/**
+ * Every row matching the filter, newest first.
+ *
+ * The whole set rather than a screenful: the feed pages through it, and the export means
+ * "what I am looking at" rather than "the first page of it".
+ */
+export declare function matchingRows(limit?: number): Row[];
 /** The rows the feed would draw, newest first. Also what "export what I am looking at" means. */
 export declare function visibleRows(limit?: number): Row[];
+/**
+ * One page of the feed, and what the pager needs to describe itself.
+ *
+ * Page zero reads live and is recomputed every draw. Any other page reads the list as it
+ * was when the reader left page zero, because a feed that renumbers itself under somebody
+ * paging through it is a feed they cannot read.
+ */
+export declare function feedPage(size: number): {
+    rows: Row[];
+    page: number;
+    pages: number;
+    total: number;
+};
+/** Moves to a page, freezing the list on the way off page zero and thawing on the way back. */
+export declare function goToFeedPage(page: number): void;
 export declare function matchingCount(): number;
 export declare function oldestAt(): number | undefined;
 export interface Aggregates {