@jsm-mit/map-routes-package 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,109 @@
+import type { Identity } from "@icp-sdk/core/agent";
+import { Principal } from "@icp-sdk/core/principal";
+import type { RouteAnswer } from "../declarations/map-routes-worker/map-routes-worker.did.js";
+import { type AreaView, type Bbox } from "./passes.js";
+import type { LatLng } from "./types.js";
+export type { AreaView, Bbox, HeldPass } from "./passes.js";
+/** What a pass provider is asked: a pass for this area (the provider may narrow the bbox). */
+export type PassRequest = {
+    area: string;
+    bbox: Bbox;
+};
+/** A pass as the pass core issues it (`issuePass`), whoever relays it. */
+export type IssuedPass = {
+    pass: Uint8Array | number[];
+    copy: string | Principal;
+    validUntilNs: bigint;
+    area: string;
+    bbox: Bbox;
+};
+/**
+ * Where passes come from. A system that is registered at the coordinator asks the pass core
+ * of its user itself (`coordinatorPassProvider`); a front asks its own backend canister, which
+ * asks the core for its user. Throws like the package (`CanisterError` with `Blocked`,
+ * `RateLimited`, `Waiting`, `NotAuthorized`).
+ */
+export type PassProvider = (request: PassRequest) => Promise<IssuedPass>;
+/** How the client reaches the group; the tests give their own. */
+export interface Transport {
+    areas(): Promise<{
+        areas: AreaView[];
+        ttlSeconds: number;
+    }>;
+    /** `RouteAnswer`, or throws `CanisterError` / `CriticalCanisterError`. */
+    route(copy: string, points: LatLng[], line: boolean, pass: Uint8Array | undefined): Promise<RouteAnswer>;
+}
+export type MapRoutesClientOptions = {
+    /** The coordinator of the group. */
+    coordinatorId: string;
+    /** Default: mainnet. A local replica: `http://127.0.0.1:4943`. */
+    host?: string;
+    /** The user: the caller of every query (a pass names it). Default: anonymous. */
+    identity?: Identity;
+    /** Without it: no pass, a random live copy (only while the copies do not require passes). */
+    passProvider?: PassProvider;
+    /** @internal tests */
+    transport?: Transport;
+    /** @internal tests */
+    now?: () => number;
+};
+/** A route, and the copy that computed it. */
+export type ClientRoute = {
+    legs: {
+        meters: number;
+        seconds: number;
+        line?: string;
+    }[];
+    snapMeters: number[];
+    osmDate: string;
+    graphSha256: string;
+    copy: string;
+};
+export type ClientRouteOptions = {
+    line?: boolean;
+    /** `Timeout` after this many milliseconds, renewals and retries included. */
+    timeoutMs?: number;
+};
+/** The group over the IC: anonymous to the coordinator (a public query), as the user to the copies. */
+export declare function icTransport(coordinatorId: string, host: string, identity: Identity | undefined): Transport;
+/** How long a system keeps the core of a user (the list TTL of the coordinator). */
+export declare const ISSUER_TTL_MS = 300000;
+/**
+ * A pass provider for a system registered at the coordinator: `system` asks the coordinator
+ * which core issues the passes of `user` (kept `ISSUER_TTL_MS`, asked again after a failure)
+ * and signs `issuePass` at that core for `user` (the principal that will call the copies —
+ * often the system itself).
+ */
+export declare function coordinatorPassProvider(options: {
+    coordinatorId: string;
+    host?: string;
+    system: Identity;
+    user: Principal | string;
+    now?: () => number;
+}): PassProvider;
+export declare class MapRoutesClient {
+    private readonly transport;
+    private readonly provider;
+    private readonly now;
+    private areasCache;
+    private readonly passes;
+    private readonly renewals;
+    constructor(options: MapRoutesClientOptions);
+    /**
+     * The fastest route through `points` (2..=5) in the area that holds them all. Throws
+     * `CanisterError` — `OutsideArea` (no area of the group holds every point, or a point far
+     * from a road), `NoRoute`, `NotReady` (no live copy), `InvalidData`, the pass refusals of
+     * the worker after one renewal (`PassExpired`, `PassInvalid`, `PassMissing`,
+     * `OutsideBbox`) and of the provider (`Blocked`, `RateLimited`, `Waiting`, `NotAuthorized`)
+     * — `Timeout`, or `CriticalCanisterError`.
+     */
+    routeAsyncUnsafe(points: LatLng[], options?: ClientRouteOptions): Promise<ClientRoute>;
+    /** The areas and their live copies (kept `ttlSeconds`). */
+    areasAsync(): Promise<AreaView[]>;
+    private attemptAsync;
+    /** The held pass of the area when it serves (a renewal starts in the background near its end), else a new one. */
+    private passForAsync;
+    /** One renewal per area at a time; the pass is kept from when it was asked. */
+    private renewAsync;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -0,0 +1,174 @@
+// MapRoutesClient: the group (`replicated-shards.md`). It asks the coordinator WHERE (the areas
+// and their live copies, kept `ttlSeconds`), takes a pass for the area of the points from a
+// pass provider (kept, renewed in the background before its end, at once on `PassExpired`),
+// and asks the copy the pass names. Without a provider it draws a live copy (a group whose
+// copies do not require passes yet).
+import { Principal } from "@icp-sdk/core/principal";
+import { idlFactory as coordinatorIdl } from "../declarations/map-routes-coordinator/map-routes-coordinator.did.js";
+import { idlFactory as coreIdl } from "../declarations/map-routes-core/map-routes-core.did.js";
+import { idlFactory as workerIdl } from "../declarations/map-routes-worker/map-routes-worker.did.js";
+import { errorKeyOf, executeRustAsyncUnsafe, MAINNET_HOST, signedActorAsync, withTimeoutAsync } from "./canister-actor.js";
+import { areaFor, PASS_ERROR_KEYS, passServes, pick, renewSoon } from "./passes.js";
+function canisterError(errorKey, errorMessage) {
+    return new Error("CanisterError", { cause: { errorKey, errorMessage } });
+}
+function toHeld(issued) {
+    return {
+        pass: issued.pass instanceof Uint8Array ? issued.pass : Uint8Array.from(issued.pass),
+        copy: typeof issued.copy === "string" ? issued.copy : issued.copy.toText(),
+        validUntilMs: Number(issued.validUntilNs / 1000000n),
+        area: issued.area,
+        bbox: issued.bbox,
+    };
+}
+/** The group over the IC: anonymous to the coordinator (a public query), as the user to the copies. */
+export function icTransport(coordinatorId, host, identity) {
+    return {
+        async areas() {
+            const coordinator = await signedActorAsync(coordinatorIdl, coordinatorId, host, undefined);
+            const answer = await executeRustAsyncUnsafe(async () => ({ Ok: await coordinator.areas() }));
+            return {
+                ttlSeconds: answer.ttlSeconds,
+                areas: answer.areas.map((a) => ({ area: a.area, bbox: a.bbox, copies: a.copies.map((c) => c.toText()) })),
+            };
+        },
+        async route(copy, points, line, pass) {
+            const worker = await signedActorAsync(workerIdl, copy, host, identity);
+            return executeRustAsyncUnsafe(() => worker.route({ points: points.map((p) => ({ lat: p.lat, lon: p.lng })), line, pass: pass ? [pass] : [] }));
+        },
+    };
+}
+/** How long a system keeps the core of a user (the list TTL of the coordinator). */
+export const ISSUER_TTL_MS = 300_000;
+/**
+ * A pass provider for a system registered at the coordinator: `system` asks the coordinator
+ * which core issues the passes of `user` (kept `ISSUER_TTL_MS`, asked again after a failure)
+ * and signs `issuePass` at that core for `user` (the principal that will call the copies —
+ * often the system itself).
+ */
+export function coordinatorPassProvider(options) {
+    const host = options.host ?? MAINNET_HOST;
+    const user = typeof options.user === "string" ? Principal.fromText(options.user) : options.user;
+    const now = options.now ?? Date.now;
+    let issuer;
+    return async ({ area, bbox }) => {
+        if (!issuer || issuer.untilMs <= now()) {
+            const coordinator = await signedActorAsync(coordinatorIdl, options.coordinatorId, host, undefined);
+            const found = await executeRustAsyncUnsafe(async () => ({ Ok: await coordinator.issuerFor(user) }));
+            if (found.length === 0) {
+                throw canisterError("Waiting", "the group has no pass core yet");
+            }
+            issuer = { id: found[0].toText(), untilMs: now() + ISSUER_TTL_MS };
+        }
+        const core = await signedActorAsync(coreIdl, issuer.id, host, options.system);
+        try {
+            return await executeRustAsyncUnsafe(() => core.issuePass({ user, area, bbox, system: [] }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === "CriticalCanisterError") {
+                issuer = undefined;
+            }
+            throw error;
+        }
+    };
+}
+export class MapRoutesClient {
+    transport;
+    provider;
+    now;
+    areasCache;
+    passes = new Map();
+    renewals = new Map();
+    constructor(options) {
+        this.transport = options.transport ?? icTransport(options.coordinatorId, options.host ?? MAINNET_HOST, options.identity);
+        this.provider = options.passProvider;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * The fastest route through `points` (2..=5) in the area that holds them all. Throws
+     * `CanisterError` — `OutsideArea` (no area of the group holds every point, or a point far
+     * from a road), `NoRoute`, `NotReady` (no live copy), `InvalidData`, the pass refusals of
+     * the worker after one renewal (`PassExpired`, `PassInvalid`, `PassMissing`,
+     * `OutsideBbox`) and of the provider (`Blocked`, `RateLimited`, `Waiting`, `NotAuthorized`)
+     * — `Timeout`, or `CriticalCanisterError`.
+     */
+    async routeAsyncUnsafe(points, options = {}) {
+        return withTimeoutAsync(() => this.attemptAsync(points, options.line ?? false, false), options.timeoutMs);
+    }
+    /** The areas and their live copies (kept `ttlSeconds`). */
+    async areasAsync() {
+        if (this.areasCache && this.areasCache.untilMs > this.now()) {
+            return this.areasCache.areas;
+        }
+        const { areas, ttlSeconds } = await this.transport.areas();
+        this.areasCache = { areas, untilMs: this.now() + ttlSeconds * 1000 };
+        return areas;
+    }
+    async attemptAsync(points, line, retried) {
+        const area = areaFor(await this.areasAsync(), points);
+        if (!area) {
+            throw canisterError("OutsideArea", "no area of the group holds every point");
+        }
+        const held = this.provider ? await this.passForAsync(area, points) : undefined;
+        const copy = held?.copy ?? pick(area.copies);
+        if (!copy) {
+            throw canisterError("NotReady", `${area.area}: no live copy`);
+        }
+        try {
+            const answer = await this.transport.route(copy, points, line, held?.pass);
+            return {
+                legs: answer.legs.map((leg) => ({ meters: Number(leg.meters), seconds: Number(leg.seconds), ...(leg.line ? { line: leg.line } : {}) })),
+                snapMeters: Array.from(answer.snapMeters),
+                osmDate: answer.osmDate,
+                graphSha256: answer.graphSha256,
+                copy,
+            };
+        }
+        catch (error) {
+            if (retried) {
+                throw error;
+            }
+            // The pass itself: a new one (the key rotated, the copy changed, its time ended).
+            if (this.provider && PASS_ERROR_KEYS.includes(errorKeyOf(error) ?? "")) {
+                this.passes.delete(area.area);
+                return this.attemptAsync(points, line, true);
+            }
+            // The copy did not answer (deleted, moved): the list again, and a pass for another.
+            if (error instanceof Error && error.message === "CriticalCanisterError") {
+                this.areasCache = undefined;
+                this.passes.delete(area.area);
+                return this.attemptAsync(points, line, true);
+            }
+            throw error;
+        }
+    }
+    /** The held pass of the area when it serves (a renewal starts in the background near its end), else a new one. */
+    async passForAsync(area, points) {
+        const entry = this.passes.get(area.area);
+        const now = this.now();
+        if (entry && passServes(entry.held, area.area, points, now)) {
+            if (renewSoon(entry.held, entry.issuedAtMs, now)) {
+                void this.renewAsync(area).catch(() => undefined);
+            }
+            return entry.held;
+        }
+        return this.renewAsync(area);
+    }
+    /** One renewal per area at a time; the pass is kept from when it was asked. */
+    renewAsync(area) {
+        const running = this.renewals.get(area.area);
+        if (running) {
+            return running;
+        }
+        const askedAt = this.now();
+        const renewal = this.provider({ area: area.area, bbox: area.bbox })
+            .then((issued) => {
+            const held = toHeld(issued);
+            this.passes.set(area.area, { held, issuedAtMs: askedAt });
+            return held;
+        })
+            .finally(() => this.renewals.delete(area.area));
+        this.renewals.set(area.area, renewal);
+        return renewal;
+    }
+}

package/dist/index.d.ts

@@ -1,14 +1,12 @@
-import type { Point, RouteAnswer } from "../declarations/map-routes/map-routes.did.js";
+import type { Point, RouteAnswer } from "../declarations/map-routes-worker/map-routes-worker.did.js";
 import { type MapRoutesOptions } from "./canister-actor.js";
 export { errorKeyOf, isCanisterStoppedError, isLocalHost, isTimeoutError, MAINNET_HOST, retrySettings, type MapRoutesOptions } from "./canister-actor.js";
 /** The canister on mainnet (crafting-table slot backend7). */
 export declare const MAP_ROUTES_CANISTER_ID = "6aigz-vyaaa-aaaag-ayjqa-cai";
 /** Points of one route: a start, up to three stops, an end. */
 export declare const MAX_ROUTE_POINTS = 5;
-export type LatLng = {
-    lat: number;
-    lng: number;
-};
+export type { LatLng } from "./types.js";
+import type { LatLng } from "./types.js";
 export type RouteLeg = {
     meters: number;
     seconds: number;
@@ -32,6 +30,11 @@ export type RouteOptions = {
 };
 export declare function toPoint(point: LatLng): Point;
 export declare function fromAnswer(answer: RouteAnswer): Route;
+export * from "./client.js";
+/**
+ * ONE worker copy, asked directly, without the coordinator and without a pass: a copy that
+ * does not require passes (`passRequired` off), a local test. Groups use `MapRoutesClient`.
+ */
 export declare class MapRoutesActor {
     private readonly canisterId;
     private readonly options;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,KAAK,EAAE,WAAW,EAAE,MAAM,8CAA8C,CAAC;AAEjG,OAAO,EAAyC,KAAK,gBAAgB,EAAoB,MAAM,qBAAqB,CAAC;AAErH,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE1J,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,MAAM,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,QAAQ,GAAG;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAChB,mDAAmD;IACnD,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAWrD;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAE/B,UAAU,GAAE,MAA+B,EAAE,OAAO,GAAE,gBAAqB;IAKvF;;;;;OAKG;IACU,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;CAS9F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,KAAK,EAAE,WAAW,EAAE,MAAM,4DAA4D,CAAC;AAE/G,OAAO,EAAyC,KAAK,gBAAgB,EAAoB,MAAM,qBAAqB,CAAC;AAErH,OAAO,EAAE,UAAU,EAAE,sBAAsB,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE1J,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,YAAY,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAAG;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAChB,mDAAmD;IACnD,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAE5C;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAWrD;AAED,cAAc,aAAa,CAAC;AAE5B;;;GAGG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;gBAE/B,UAAU,GAAE,MAA+B,EAAE,OAAO,GAAE,gBAAqB;IAKvF;;;;;OAKG;IACU,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;CAS9F"}

package/dist/index.js

@@ -1,7 +1,7 @@
 // @jsm-mit/map-routes-package: the fastest route by car through 2–5 points from the map-routes
 // canister (an OpenStreetMap road graph of Nordrhein-Westfalen), with the line of each leg
 // as an encoded polyline of precision 5 — the format ORS sends.
-import { idlFactory } from "../declarations/map-routes/map-routes.did.js";
+import { idlFactory } from "../declarations/map-routes-worker/map-routes-worker.did.js";
 import { executeRustAsyncUnsafe, rawActorAsync, withTimeoutAsync } from "./canister-actor.js";
 export { errorKeyOf, isCanisterStoppedError, isLocalHost, isTimeoutError, MAINNET_HOST, retrySettings } from "./canister-actor.js";
 /** The canister on mainnet (crafting-table slot backend7). */
@@ -23,6 +23,11 @@ export function fromAnswer(answer) {
         graphSha256: answer.graphSha256,
     };
 }
+export * from "./client.js";
+/**
+ * ONE worker copy, asked directly, without the coordinator and without a pass: a copy that
+ * does not require passes (`passRequired` off), a local test. Groups use `MapRoutesClient`.
+ */
 export class MapRoutesActor {
     canisterId;
     options;
@@ -38,7 +43,7 @@ export class MapRoutesActor {
      */
     async routeAsyncUnsafe(points, options = {}) {
         const actor = await rawActorAsync(idlFactory, this.canisterId, this.options);
-        const answer = await withTimeoutAsync(() => executeRustAsyncUnsafe(() => actor.route({ points: points.map(toPoint), line: options.line ?? false })), options.timeoutMs);
+        const answer = await withTimeoutAsync(() => executeRustAsyncUnsafe(() => actor.route({ points: points.map(toPoint), line: options.line ?? false, pass: [] })), options.timeoutMs);
         return fromAnswer(answer);
     }
 }

package/dist/passes.d.ts

@@ -0,0 +1,37 @@
+import type { LatLng } from "./types.js";
+/** A rectangle in degrees, edges included. */
+export type Bbox = {
+    minLat: number;
+    minLon: number;
+    maxLat: number;
+    maxLon: number;
+};
+export type AreaView = {
+    area: string;
+    bbox: Bbox;
+    copies: string[];
+};
+/** A pass from the coordinator: valid on `copy`, for `bbox`, until `validUntilMs`. */
+export type HeldPass = {
+    pass: Uint8Array;
+    copy: string;
+    validUntilMs: number;
+    area: string;
+    bbox: Bbox;
+};
+/** A held pass is renewed in the background when less than this part of its life is left. */
+export declare const RENEW_PART = 0.25;
+/** A pass this close to its end is not used any more (the call itself takes time). */
+export declare const PASS_MARGIN_MS = 10000;
+export declare function contains(b: Bbox, p: LatLng): boolean;
+/** The first area whose bbox holds every point; undefined when none does. */
+export declare function areaFor(areas: AreaView[], points: LatLng[]): AreaView | undefined;
+/** A held pass serves this call: the same area, every point inside, not too close to its end. */
+export declare function passServes(held: HeldPass | undefined, area: string, points: LatLng[], nowMs: number): held is HeldPass;
+/** Time to get the next pass in the background (the held one still serves). */
+export declare function renewSoon(held: HeldPass, issuedAtMs: number, nowMs: number): boolean;
+/** The worker refused the pass itself: a new pass may help, a retry of the same one not. */
+export declare const PASS_ERROR_KEYS: string[];
+/** A random element (the copies of an area without a pass). */
+export declare function pick<T>(items: T[], random?: () => number): T | undefined;
+//# sourceMappingURL=passes.d.ts.map

package/dist/passes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passes.d.ts","sourceRoot":"","sources":["../src/passes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,8CAA8C;AAC9C,MAAM,MAAM,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEtE,sFAAsF;AACtF,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1G,6FAA6F;AAC7F,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,sFAAsF;AACtF,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,GAAG,SAAS,CAEjF;AAED,iGAAiG;AACjG,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,IAAI,QAAQ,CAEtH;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAIpF;AAED,4FAA4F;AAC5F,eAAO,MAAM,eAAe,UAA+D,CAAC;AAE5F,+DAA+D;AAC/D,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,GAAE,MAAM,MAAoB,GAAG,CAAC,GAAG,SAAS,CAErF"}

package/dist/passes.js

@@ -0,0 +1,28 @@
+// The decisions of the client: which area holds the points, whether a held pass serves,
+// when to renew it. Plain functions (tests/test-unit.ts).
+/** A held pass is renewed in the background when less than this part of its life is left. */
+export const RENEW_PART = 0.25;
+/** A pass this close to its end is not used any more (the call itself takes time). */
+export const PASS_MARGIN_MS = 10_000;
+export function contains(b, p) {
+    return p.lat >= b.minLat && p.lat <= b.maxLat && p.lng >= b.minLon && p.lng <= b.maxLon;
+}
+/** The first area whose bbox holds every point; undefined when none does. */
+export function areaFor(areas, points) {
+    return areas.find((a) => points.every((p) => contains(a.bbox, p)));
+}
+/** A held pass serves this call: the same area, every point inside, not too close to its end. */
+export function passServes(held, area, points, nowMs) {
+    return held !== undefined && held.area === area && held.validUntilMs - PASS_MARGIN_MS > nowMs && points.every((p) => contains(held.bbox, p));
+}
+/** Time to get the next pass in the background (the held one still serves). */
+export function renewSoon(held, issuedAtMs, nowMs) {
+    const life = held.validUntilMs - issuedAtMs;
+    return life > 0 && held.validUntilMs - nowMs < life * RENEW_PART;
+}
+/** The worker refused the pass itself: a new pass may help, a retry of the same one not. */
+export const PASS_ERROR_KEYS = ["PassExpired", "PassInvalid", "PassMissing", "OutsideBbox"];
+/** A random element (the copies of an area without a pass). */
+export function pick(items, random = Math.random) {
+    return items.length === 0 ? undefined : items[Math.floor(random() * items.length) % items.length];
+}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@jsm-mit/map-routes-package",
-    "version": "0.1.0",
-    "description": "The package of map-routes: the fastest route by car through 2–5 points, with the line of each leg, from an IC canister that holds an OpenStreetMap road graph.",
-    "homepage": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes/tree/master/package#readme",
+    "version": "0.2.0",
+    "description": "The package of map-routes: the fastest route by car through 2–5 points, with the line of each leg, from a replicated-shards group of IC canisters (a coordinator and worker copies) that hold OpenStreetMap road graphs.",
+    "homepage": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes-replicated-shards/tree/master/package#readme",
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/JSM-Internet-Computer-Map-Service/map-routes.git",
+        "url": "git+https://github.com/JSM-Internet-Computer-Map-Service/map-routes-replicated-shards.git",
         "directory": "package"
     },
     "license": "ISC",
@@ -30,7 +30,8 @@
         "prepare": "npm run build",
         "publish-public": "bash scripts/publish-public.sh",
         "test-unit": "npx tsx tests/test-unit.ts",
-        "test-smoke": "bash scripts/run-tests-local.sh tests/test-smoke.ts"
+        "test-smoke": "bash scripts/run-tests-local.sh tests/test-smoke.ts",
+        "test-group": "bash scripts/run-group-tests-local.sh tests/test-group.ts"
     },
     "dependencies": {
         "@icp-sdk/core": "^6.1.0"
@@ -41,11 +42,11 @@
         "typescript": "^5.9.3"
     },
     "bugs": {
-        "url": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes/issues"
+        "url": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes-replicated-shards/issues"
     },
     "mapRoutes": {
-        "repo": "map-routes",
-        "repoUrl": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes",
-        "commit": "21a20fa3d79c1703edf29352d616e81d84428610"
+        "repo": "map-routes-replicated-shards",
+        "repoUrl": "https://github.com/JSM-Internet-Computer-Map-Service/map-routes-replicated-shards",
+        "commit": "63152a303365beb6134d98c633a66f6b159eea92"
     }
 }

package/declarations/map-routes/map-routes.did

@@ -1,93 +0,0 @@
-type BeginUploadArgs = record {
-  // sha256 (hex) of the graph file.
-  sha256 : text;
-  // Bytes of the graph file (`map-routes-build build` output, format TMC3).
-  size : nat64;
-  osmDate : text;
-};
-type BufferInfo = record {
-  sha256 : text;
-  size : nat64;
-  startedAtNs : nat64;
-  state : BufferState;
-  buffer : nat8;
-  osmDate : text;
-};
-type BufferState = variant { Uploading; Active; Ready };
-// The fastest route by car between two points.
-type Distance = record {
-  meters : nat64;
-  snapToMeters : nat32;
-  seconds : nat64;
-  // Instructions this query took (measurement of the PoC).
-  instructions : nat64;
-  // sha256 (hex) of the graph, as printed by `map-routes-build build`.
-  graphSha256 : text;
-  // Date of the OpenStreetMap extract the graph was built from.
-  osmDate : text;
-  // How far each point lies from the junction the route starts or ends at.
-  snapFromMeters : nat32;
-};
-type DistanceArgs = record { to : Point; from : Point };
-type Error = variant {
-  // No road within `MAX_SNAP_M` of the point named ("from" / "to" / "points[i]").
-  OutsideArea : text;
-  // No graph is active yet, or the active one is of an older format.
-  NotReady;
-  NotFound;
-  NotAuthorized : text;
-  NoRoute;
-  InvalidData : text;
-};
-// The fastest route from one point of a `route` query to the next.
-type Leg = record {
-  meters : nat64;
-  // Encoded polyline of precision 5 (as ORS sends it), from the junction the leg starts
-  // at to the one it ends at; "" when the line was not asked for.
-  line : text;
-  seconds : nat64;
-};
-type Point = record { lat : float64; lon : float64 };
-type Result = variant { Ok : BufferInfo; Err : Error };
-type Result_1 = variant { Ok : Distance; Err : Error };
-type Result_2 = variant { Ok : Status; Err : Error };
-type Result_3 = variant { Ok : RouteAnswer; Err : Error };
-type Result_4 = variant { Ok; Err : Error };
-type RouteAnswer = record {
-  // How far each point lies from the junction its legs start or end at.
-  snapMeters : vec nat32;
-  // One leg for each pair of consecutive points.
-  legs : vec Leg;
-  instructions : nat64;
-  graphSha256 : text;
-  osmDate : text;
-};
-type RouteArgs = record {
-  // Whether each leg carries its line.
-  line : bool;
-  // 2..=`MAX_ROUTE_POINTS` points, driven in this order.
-  points : vec Point;
-};
-type Status = record {
-  stableBytes : nat64;
-  heapBytes : nat64;
-  // Nodes of the graph that answers `distance`; 0 when none is active.
-  nodes : nat64;
-  buffers : vec BufferInfo;
-};
-type UploadChunkArgs = record { offset : nat64; bytes : blob };
-service : () -> {
-  // Switches `distance` to the inactive buffer — a new graph, or back to the previous one.
-  activate : () -> (Result);
-  // Starts an upload into the inactive buffer; whatever was there is dropped.
-  beginUpload : (BeginUploadArgs) -> (Result);
-  // Checks the hash and the header of the uploaded graph; the buffer becomes Ready.
-  commitUpload : () -> (Result);
-  // The fastest route by car from one point to another. Public.
-  distance : (DistanceArgs) -> (Result_1) query;
-  getStatus : () -> (Result_2) query;
-  // The fastest route by car through 2..=5 points, leg by leg, with each leg's line when
-  // asked. Public.
-  route : (RouteArgs) -> (Result_3) query;
-  uploadChunk : (UploadChunkArgs) -> (Result_4);
-}