@signalk/charts-plugin 3.7.0 → 3.8.0

package/plugin/chartDownloader.d.ts

@@ -1,73 +1,166 @@
-import type { BBox, FeatureCollection } from 'geojson';
-import { ResourcesApi } from '@signalk/server-api';
-import { ChartProvider } from './types';
-export interface Tile {
-    x: number;
-    y: number;
-    z: number;
-}
-export declare enum Status {
+import type { BBox } from 'geojson';
+import { ChartProvider, MBTilesHandle } from './types';
+import { Tile } from './chartDownloaderTileHelpers';
+export type { Tile };
+export declare enum State {
     Stopped = 0,
     Running = 1
 }
+interface CacheStatistic {
+    requests: number;
+    hits: number;
+    misses: number;
+    failures: number;
+}
+export interface JobOptions {
+    refetch: boolean;
+    mbtiles: boolean;
+    vacuum: boolean;
+}
+declare enum JobType {
+    None = 0,
+    Seed = 1,
+    Delete = 2
+}
+export declare enum TileSource {
+    None = 0,
+    FetchedFromCache = 1,
+    FetchedFromRemote = 2
+}
+export declare enum FailureKind {
+    None = "none",
+    Timeout = "timeout",
+    HttpClient = "http_4xx",
+    HttpServer = "http_5xx",
+    Network = "network",
+    NoRemoteUrl = "no_remote_url"
+}
+export interface TileFetchFailure {
+    kind: FailureKind;
+    status?: number;
+}
+export interface TileFetchResult {
+    buffer: Buffer | null;
+    source: TileSource;
+    failure?: TileFetchFailure;
+}
+export type FailureCounts = Partial<Record<FailureKind, number>>;
 export declare class ChartSeedingManager {
     static ActiveJobs: {
         [key: number]: ChartDownloader;
     };
-    static createJob(resourcesApi: ResourcesApi, chartsPath: string, provider: ChartProvider, maxZoom: number, regionGUID?: string | undefined, bbox?: BBox | undefined, tile?: Tile | undefined): Promise<ChartDownloader>;
+    /**
+     * Reset all module-level static state owned by ChartSeedingManager and
+     * ChartDownloader so a test harness can run from a known baseline.
+     *
+     * The plugin's static fields outlive a `stop()` / `start()` cycle in
+     * production (which is intended — process-global gates and ID sequences),
+     * but in a test process running 200+ tests in sequence the residue
+     * shows up as cross-test interference: nextJobId drifts upward, an
+     * earlier low-disk-space probe leaves CachingEnabled=false for 2s,
+     * stale CacheStatistics from one provider get seen by an unrelated
+     * test asserting "stats are an object".
+     *
+     * Production code never calls this. The test app's beforeEach does.
+     */
+    static resetForTests(): void;
+    static createJob(cachePath: string, provider: ChartProvider, options: JobOptions, minZoom: number, maxZoom: number, feature?: GeoJSON.Feature<GeoJSON.Geometry> | undefined, bbox?: BBox | undefined): Promise<ChartDownloader>;
     static cancelAll(): void;
 }
 export declare class ChartDownloader {
-    private resourcesApi;
-    private chartsPath;
+    private cachePath;
     private provider;
+    private options;
     private static MINIMUM_FREE_DISK_SPACE;
     private static nextJobId;
+    private static CachingEnabled;
+    private static CacheStatistics;
+    private static TilesCached;
+    private static lastDiskSpaceCheck;
+    private static lastDiskSpaceResult;
+    static tileRetryBackoffMs: number;
     private id;
+    private type;
+    private state;
     private status;
     private totalTiles;
     private downloadedTiles;
     private failedTiles;
     private cachedTiles;
-    private concurrentDownloadsLimit;
+    private deletedTiles;
+    private failureCounts;
+    private sampleLogged;
     private areaDescription;
     private cancelRequested;
+    private regionName;
     private tiles;
-    private tilesToDownload;
-    constructor(resourcesApi: ResourcesApi, chartsPath: string, provider: ChartProvider);
+    private tilesInDB;
+    constructor(cachePath: string, provider: ChartProvider, options: JobOptions);
     get ID(): number;
-    initializeJobFromRegion(regionGUID: string, maxZoom: number): Promise<void>;
-    initializeJobFromBBox(bbox: BBox, maxZoom: number): Promise<void>;
-    initializeJobFromTile(tile: Tile, maxZoom: number): Promise<void>;
-    private static DISK_CHECK_INTERVAL_MS;
+    initalizeJobFromFeature(feature: GeoJSON.Feature<GeoJSON.Geometry>, minZoom: number, maxZoom: number): Promise<void>;
+    initializeJobFromBBox(bbox: BBox, minZoom: number, maxZoom: number): Promise<void>;
     /**
      * Download map tiles for a specific area.
      */
     seedCache(): Promise<void>;
     deleteCache(): Promise<void>;
     cancelJob(): void;
-    private filterCachedTiles;
     info(): {
         id: number;
+        type: JobType;
         chartName: string;
         regionName: string;
         totalTiles: number;
         downloadedTiles: number;
         cachedTiles: number;
         failedTiles: number;
+        failures: {
+            http_4xx?: number | undefined;
+            http_5xx?: number | undefined;
+            network?: number | undefined;
+            no_remote_url?: number | undefined;
+            none?: number | undefined;
+            timeout?: number | undefined;
+        };
+        deletedTiles: number;
         progress: number;
-        status: Status;
+        status: string;
+        state: State;
     };
-    static getTileFromCacheOrRemote(chartsPath: string, provider: ChartProvider, tile: Tile): Promise<Buffer | null>;
+    static getTileFromCacheOrRemote(chartsPath: string, provider: ChartProvider, tile: Tile, overwrite?: boolean): Promise<TileFetchResult>;
+    static getTileFromMbTiles(mbtilesHandle: MBTilesHandle, tile: Tile): Promise<Buffer | null>;
+    static cacheTileToMbTiles(mbtilesHandle: MBTilesHandle, tile: Tile, buffer: Buffer | null): Promise<void>;
+    /**
+     * Detailed-result variant of fetchTileFromRemote. Returns the buffer on
+     * success and a `failure` discriminator on every other path so the
+     * caller can attribute "failed" tiles to a specific cause (timeout vs
+     * 5xx vs network) for diagnostic logs and per-job counters.
+     *
+     * Retries once on 502/503 with TILE_RETRY_BACKOFF_MS backoff: those are
+     * the response codes that genuinely benefit from one more try (LB hiccup,
+     * backend cold-start). 504 is excluded because it means the upstream
+     * already waited; another wait makes the per-tile latency intolerable.
+     * 4xx are not retried (auth or "tile genuinely doesn't exist" — neither
+     * gets better by trying again).
+     */
+    static fetchTileFromRemoteDetailed(provider: ChartProvider, tile: Tile, timeoutMs?: number): Promise<{
+        buffer: Buffer | null;
+        failure: TileFetchFailure;
+    }>;
+    /**
+     * Backwards-compatible wrapper for callers that only need the buffer.
+     * Internal callers should prefer fetchTileFromRemoteDetailed for the
+     * categorised failure information.
+     */
     static fetchTileFromRemote(provider: ChartProvider, tile: Tile, timeoutMs?: number): Promise<Buffer | null>;
-    getSubTiles(tile: Tile, maxZoom: number): Tile[];
+    static hasDiskSpace(path: string): Promise<boolean>;
+    static getStatistics(): {
+        [k: string]: CacheStatistic;
+    };
     /**
-     * Get all tiles that intersect a bounding box up to a maximum zoom level.
-     * bbox = [minLon, minLat, maxLon, maxLat]
+     * Reset the static fields owned by ChartDownloader. See
+     * ChartSeedingManager.resetForTests for why this exists.
      */
-    getTilesForBBox(bbox: BBox, maxZoom: number): Tile[];
-    getTilesForGeoJSON(geojson: FeatureCollection, zoomMin?: number, zoomMax?: number): Tile[];
-    private convertRegionToGeoJSON;
-    private bboxPolygon;
+    static resetForTests(): void;
 }
 //# sourceMappingURL=chartDownloader.d.ts.map

package/plugin/chartDownloader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chartDownloader.d.ts","sourceRoot":"","sources":["../src/chartDownloader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chartDownloader.d.ts","sourceRoot":"","sources":["../src/chartDownloader.ts"],"names":[],"mappings":"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"}