@jsm-mit/map-routes-package 0.0.0-stage → 0.2.0

package/dist/canister-actor.js

@@ -0,0 +1,150 @@
+// The agent and the error handling of the package: one HttpAgent per host, a stopped canister
+// waited out, `{ Ok } | { Err }` turned into a value or a thrown `CanisterError`, a time
+// limit. (The retry and the error shapes are a copy of @jsm-mit/tigi-sharded-package's.)
+import { Actor, HttpAgent } from "@icp-sdk/core/agent";
+export const MAINNET_HOST = "https://icp0.io";
+/** True for a replica on this machine: localhost, *.localhost, 127.0.0.1 or [::1]. */
+export function isLocalHost(host) {
+    let hostname;
+    try {
+        hostname = new URL(host).hostname;
+    }
+    catch {
+        return false;
+    }
+    return hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/** One anonymous HttpAgent per host: the canister answers anyone. */
+const agents = new Map();
+function agentOf(host) {
+    let entry = agents.get(host);
+    if (!entry) {
+        const agent = HttpAgent.createSync({ host });
+        const ready = isLocalHost(host) ? agent.fetchRootKey().then(() => undefined) : Promise.resolve();
+        entry = { agent, ready };
+        agents.set(host, entry);
+    }
+    return entry;
+}
+export async function rawActorAsync(idlFactory, canisterId, options) {
+    const { agent, ready } = agentOf(options.host ?? MAINNET_HOST);
+    await ready;
+    return Actor.createActor(idlFactory, { agent, canisterId });
+}
+/** One agent per host and identity: a pass names the principal that calls the worker. */
+const signedAgents = new Map();
+export async function signedActorAsync(idlFactory, canisterId, host, identity) {
+    if (!identity) {
+        return rawActorAsync(idlFactory, canisterId, { host });
+    }
+    const key = `${host} ${identity.getPrincipal().toText()}`;
+    let entry = signedAgents.get(key);
+    if (!entry) {
+        const agent = HttpAgent.createSync({ host, identity });
+        const ready = isLocalHost(host) ? agent.fetchRootKey().then(() => undefined) : Promise.resolve();
+        entry = { agent, ready };
+        signedAgents.set(key, entry);
+    }
+    await entry.ready;
+    return Actor.createActor(idlFactory, { agent: entry.agent, canisterId });
+}
+// ----- a stopped canister (an upgrade runs) -----
+/**
+ * A canister that is stopped or stopping — an upgrade of it runs — refuses every call with
+ * IC0508 / IC0509. The call did NOT run, so it is tried again: doubling pauses from
+ * `STOPPED_RETRY_FIRST_DELAY_MS`, at most `STOPPED_RETRY_MAX_FACTOR` times it, each 0.5–1.5
+ * of its length at random, `STOPPED_RETRY_ATTEMPTS` tries in all: about a minute — unless
+ * the time limit of the call ends first.
+ */
+export const STOPPED_RETRY_FIRST_DELAY_MS = 1000;
+export const STOPPED_RETRY_MAX_FACTOR = 8;
+export const STOPPED_RETRY_ATTEMPTS = 10;
+const STOPPED_ERROR_CODES = ["IC0508", "IC0509"];
+const STOPPED_REJECTS = [/ is stopped\b/, / is stopping\b/];
+/** True for the refusal of a stopped or stopping canister. */
+export function isCanisterStoppedError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const raw = error.message === "CriticalCanisterError" ? error.cause?.rawError : error;
+    if (!(raw instanceof Error) && (typeof raw !== "object" || raw === null))
+        return false;
+    const code = raw.cause?.code;
+    if (typeof code?.rejectErrorCode === "string" && STOPPED_ERROR_CODES.includes(code.rejectErrorCode))
+        return true;
+    const text = typeof code?.rejectMessage === "string" ? code.rejectMessage : raw instanceof Error ? raw.message : "";
+    return STOPPED_REJECTS.some((pattern) => pattern.test(text));
+}
+/** The wait before try `attempt + 1`: doubling, capped, 0.5–1.5 of it at random. */
+export function stoppedRetryDelayMs(attempt, firstDelayMs = STOPPED_RETRY_FIRST_DELAY_MS) {
+    const base = firstDelayMs * Math.min(2 ** (attempt - 1), STOPPED_RETRY_MAX_FACTOR);
+    return base * (0.5 + Math.random());
+}
+/** Tests shorten the waits. */
+export const retrySettings = {
+    stoppedFirstDelayMs: STOPPED_RETRY_FIRST_DELAY_MS,
+    stoppedAttempts: STOPPED_RETRY_ATTEMPTS,
+};
+export async function waitOutStoppedAsync(fnAsync) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await fnAsync();
+        }
+        catch (err) {
+            if (!isCanisterStoppedError(err) || attempt >= retrySettings.stoppedAttempts)
+                throw err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, stoppedRetryDelayMs(attempt, retrySettings.stoppedFirstDelayMs)));
+    }
+}
+// ----- the time limit -----
+/** The error of a call that did not answer within its time limit. */
+export function timeoutError(timeoutMs) {
+    return new Error("Timeout", { cause: { timeoutMs } });
+}
+export function isTimeoutError(error) {
+    return error instanceof Error && error.message === "Timeout";
+}
+/**
+ * The call, or `Timeout` after `timeoutMs` (none when undefined). The call itself goes on
+ * (a query cannot be called back); its late answer is dropped.
+ */
+export async function withTimeoutAsync(fnAsync, timeoutMs) {
+    if (timeoutMs === undefined)
+        return fnAsync();
+    let timer;
+    const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(timeoutError(timeoutMs)), timeoutMs);
+    });
+    try {
+        return await Promise.race([fnAsync(), limit]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `{ Ok: T }` resolves with `T`; `{ Err }` is thrown as `Error("CanisterError", { cause:
+ * { errorKey, errorMessage } })` with the variant's name as the errorKey (`OutsideArea`,
+ * `NoRoute`, `NotReady`, `InvalidData`); any transport failure as
+ * `Error("CriticalCanisterError", { cause: { rawError } })`. A stopped canister is waited
+ * out first.
+ */
+export async function executeRustAsyncUnsafe(fnAsync) {
+    let result;
+    try {
+        result = await waitOutStoppedAsync(fnAsync);
+    }
+    catch (err) {
+        throw new Error("CriticalCanisterError", { cause: { rawError: err } });
+    }
+    if ("Ok" in result)
+        return result.Ok;
+    const errorKey = Object.keys(result.Err)[0] ?? "Unknown";
+    throw new Error("CanisterError", { cause: { errorKey, errorMessage: result.Err[errorKey] } });
+}
+/** The errorKey of a `CanisterError`, or undefined for any other error. */
+export function errorKeyOf(error) {
+    if (!(error instanceof Error) || error.message !== "CanisterError")
+        return undefined;
+    return error.cause?.errorKey;
+}

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":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAMpD,OAAO,KAAK,EAAE,WAAW,EAA6B,MAAM,4DAA4D,CAAC;AAEzH,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,IAAI,EAA+D,MAAM,aAAa,CAAC;AAC7H,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5D,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnI;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzE,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACtB,KAAK,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,0EAA0E;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC5G;AAED,MAAM,MAAM,sBAAsB,GAAG;IACjC,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sBAAsB;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,sBAAsB;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnK,MAAM,MAAM,kBAAkB,GAAG;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAgBF,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAkB1G;AAED,oFAAoF;AACpF,eAAO,MAAM,aAAa,SAAU,CAAC;AAErC;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAE,GAAG,YAAY,CA6BvK;AAED,qBAAa,eAAe;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,UAAU,CAAqD;IACvE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6D;IACpF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;gBAErD,OAAO,EAAE,sBAAsB;IAM3C;;;;;;;OAOG;IACU,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAIvG,2DAA2D;IAC9C,UAAU,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YAWhC,YAAY;IA8C1B,kHAAkH;YACpG,YAAY;IAe1B,+EAA+E;IAC/E,OAAO,CAAC,UAAU;CAmBrB"}

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

@@ -0,0 +1,50 @@
+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 } from "./types.js";
+import type { LatLng } from "./types.js";
+export type RouteLeg = {
+    meters: number;
+    seconds: number;
+    /** Encoded polyline of precision 5, junction to junction; absent when not asked for. */
+    line?: string;
+};
+export type Route = {
+    /** One leg for each pair of consecutive points. */
+    legs: RouteLeg[];
+    /** How far each point lies from the junction its legs start or end at. */
+    snapMeters: number[];
+    /** Date of the OpenStreetMap extract of the graph. */
+    osmDate: string;
+    graphSha256: string;
+};
+export type RouteOptions = {
+    /** Each leg carries its line. Default: false. */
+    line?: boolean;
+    /** `Timeout` after this many milliseconds. Default: none. */
+    timeoutMs?: number;
+};
+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;
+    constructor(canisterId?: string, options?: MapRoutesOptions);
+    /**
+     * The fastest route through `points` (2..=MAX_ROUTE_POINTS), leg by leg. Throws
+     * `CanisterError` (errorKey `OutsideArea` — a point farther than 1 km from a road of
+     * the map, `NoRoute`, `NotReady` — no graph yet, `InvalidData`), `Timeout`, or
+     * `CriticalCanisterError`.
+     */
+    routeAsyncUnsafe(points: LatLng[], options?: RouteOptions): Promise<Route>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,49 @@
+// @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-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). */
+export const MAP_ROUTES_CANISTER_ID = "6aigz-vyaaa-aaaag-ayjqa-cai";
+/** Points of one route: a start, up to three stops, an end. */
+export const MAX_ROUTE_POINTS = 5;
+export function toPoint(point) {
+    return { lat: point.lat, lon: point.lng };
+}
+export function fromAnswer(answer) {
+    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,
+    };
+}
+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;
+    constructor(canisterId = MAP_ROUTES_CANISTER_ID, options = {}) {
+        this.canisterId = canisterId;
+        this.options = options;
+    }
+    /**
+     * The fastest route through `points` (2..=MAX_ROUTE_POINTS), leg by leg. Throws
+     * `CanisterError` (errorKey `OutsideArea` — a point farther than 1 km from a road of
+     * the map, `NoRoute`, `NotReady` — no graph yet, `InvalidData`), `Timeout`, or
+     * `CriticalCanisterError`.
+     */
+    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, 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 {};