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

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @jsm-mit/map-routes-package
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The package of map-routes: the fastest route by car through 2–5 points, with the line of each
+leg, from a group of Internet Computer canisters (replicated shards): a coordinator and copies
+of workers, each holding an OpenStreetMap road graph of one area (© OpenStreetMap
+contributors, ODbL). Queries cost the caller nothing. It replaces the deprecated
+`@jsm-mit/tigi-map-package`.
+
+## The group (0.2): `MapRoutesClient`
+
+```ts
+import { coordinatorPassProvider, errorKeyOf, isTimeoutError, MapRoutesClient } from "@jsm-mit/map-routes-package";
+
+const map = new MapRoutesClient({
+    coordinatorId,                                  // the coordinator of the group
+    identity: user,                                 // the caller of the queries (a pass names it)
+    passProvider,                                   // where passes come from (below)
+});
+const route = await map.routeAsyncUnsafe([me, pickup, destination], { line: true, timeoutMs: 5_000 });
+// route.legs[i]: { meters, seconds, line? }       line = encoded polyline, precision 5 (as ORS)
+// route.snapMeters, route.osmDate, route.graphSha256, route.copy (the copy that answered)
+```
+
+- The client reads the areas and their live copies from the coordinator and keeps them
+  `ttlSeconds`; it picks the area that holds every point.
+- A **pass** (`replicated-shards.md`) names the user, the area, a bbox, a time and one copy.
+  The client keeps it per area, asks for the next one in the background in the last quarter
+  of its life, and at once (with one retry of the call) when the worker refuses it
+  (`PassExpired`, `PassInvalid`, `PassMissing`, `OutsideBbox`).
+- **Pass providers:**
+  - a system registered at the coordinator signs `issuePass` itself at the pass core of the
+    user (the coordinator names it, `issuerFor`):
+    `coordinatorPassProvider({ coordinatorId, system: identity, user })` (often the user is
+    the system itself);
+  - a front asks its own backend canister (a registered system), which asks the coordinator
+    for the front's user: `passProvider: (request) => backend.mapPass(request)`.
+- Without a provider the client draws a live copy and sends no pass — only while the copies
+  do not require passes.
+- A copy that does not answer: the list is read again and the call is tried once more.
+
+Errors: `CanisterError` with `errorKeyOf(error)` = `OutsideArea` (no area holds every point,
+or a point farther than 1 km from a road), `NoRoute`, `NotReady` (no live copy, no graph),
+`InvalidData`, the pass refusals above (after the renewal), and the refusals of the provider:
+`Blocked` (the user — a clear reason; show it), `RateLimited`, `Waiting`, `NotAuthorized`.
+`Timeout` (`isTimeoutError`; renewals and retries count) and `CriticalCanisterError`
+(transport; also a system the coordinator does not know).
+
+## One copy: `MapRoutesActor`
+
+`new MapRoutesActor(copyId, { host })` asks one worker copy directly, without a coordinator
+and without a pass (a copy with `passRequired` off; local tests). It is the 0.1 interface.
+
+Local replica: `host: "http://127.0.0.1:4943"`.
+
+## Scripts
+
+- `npm run test-unit` — no canister (the client on a fake transport).
+- `npm run test-smoke` — one copy (`map-routes-worker`) on the LOCAL replica with the newest
+  `data/*.tmc`.
+- `npm run test-group` — the group on the LOCAL replica: the coordinator, two copies of Iraq,
+  passes required (`../scripts/check/local-coordinator-check.sh iraq`, local test identity
+  `mrc-system` as the system).
+- `npm run sync-declarations` — `declarations/` from `../map-routes-worker.did` and
+  `../map-routes-coordinator.did`.
+- `npm run publish-public` — human-run; see the script for its refusals.

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

@@ -0,0 +1,485 @@
+// One area as a client sees it: where to ask.
+type AreaInfo = record {
+  sha256 : opt text;
+  area : text;
+  bbox : Bbox;
+  // The live copies: a client draws one for every call.
+  copies : vec principal;
+  osmDate : opt text;
+};
+// Stored: the hysteresis of one area (key = its name).
+type AreaLoad = record {
+  // Readings in a row with the average per live copy above H.
+  above : nat32;
+  // The last copy the load made (created or unmarked).
+  lastGrowthNs : opt nat64;
+  // Since when the load would fit into one live copy less (sum / (n − 1) < H/2).
+  belowSinceNs : opt nat64;
+  area : text;
+};
+type Areas = record {
+  // How long a client keeps this list.
+  ttlSeconds : nat32;
+  areas : vec AreaInfo;
+};
+// A rectangle in degrees, edges included.
+type Bbox = record {
+  minLat : float64;
+  minLon : float64;
+  maxLat : float64;
+  maxLon : float64;
+};
+type BeginWasmArgs = record {
+  sha256 : text;
+  // `null` = the worker.
+  kind : opt WasmKind;
+  size : nat64;
+};
+// Stored: a bisection of one area (key = its name). The users stay in the cores.
+type BisectionRun = record {
+  // Set when it ended; a new one starts at least an hour later.
+  endedAtNs : opt nat64;
+  area : text;
+  copyA : principal;
+  copyB : principal;
+  // Suspects left, summed over the cores.
+  suspects : nat64;
+  steps : nat32;
+  // The split of this step began then.
+  stepStartedNs : nat64;
+};
+// Stored: a blocked user (key = system/user). Only a superadmin unblocks.
+type Block = record {
+  who : UserKey;
+  atNs : nat64;
+  // The measured surplus in instructions/s (bisection).
+  load : opt float64;
+  reason : text;
+};
+// Stored: one worker copy (key = its canister). A new field is `Option<…>` + `#[serde(default)]`.
+type Copy = record {
+  area : text;
+  createdAtNs : nat64;
+  state : CopyState;
+  subnet : opt principal;
+  canister : principal;
+  // The last step that failed; `advanceCopy` tries it again.
+  lastError : opt text;
+  // When the copy was marked for removal (off the list since then).
+  markedAtNs : opt nat64;
+};
+type CopyState = variant {
+  // A later copy: it pulls the graph from a live copy of the area.
+  Copying;
+  // Answers queries and is on the list of the area.
+  Live;
+  // Created; its wasm is not installed yet.
+  Installing;
+  // The first copy of an area: an uploader sends the graph (`upload-graph.sh --no-activate`).
+  AwaitingData;
+  // The load fits without it; only a superadmin deletes it.
+  MarkedForRemoval;
+};
+// Stored: a pass core of the group (key = its canister).
+type CoreCanister = record {
+  // The snapshot version the core holds.
+  syncedVersion : opt nat64;
+  createdAtNs : nat64;
+  // Its balance at the last round (the round tops it up like a copy).
+  cycles : opt nat;
+  state : CoreState;
+  subnet : opt principal;
+  canister : principal;
+  lastError : opt text;
+};
+// A core's report (`coreReport`).
+type CoreReport = record {
+  // Blocks made in the core (renewals).
+  blocks : vec Block;
+  // Users with a valid pass, per area.
+  users : vec record { text; nat64 };
+  // Systems refused for passes a minute.
+  rateLimited : vec principal;
+};
+type CoreState = variant {
+  // Issues passes; gets the snapshot.
+  Live;
+  // Created; its wasm is not installed yet (`advanceCore`).
+  Installing;
+};
+type Error = variant {
+  // A call to another canister failed (named); the step can be tried again.
+  CallFailed : text;
+  // The user gets no pass: the reason and whom to contact.
+  Blocked : text;
+  NotFound : text;
+  NotAuthorized : text;
+  // The limit of copies of the area is reached (`maxCopies`).
+  LimitReached : text;
+  InvalidData : text;
+  // The system asks too often (or the demo used its hour): try later.
+  RateLimited : text;
+  // The step waits for something outside (named), e.g. the graph upload.
+  Waiting : text;
+};
+// Test feed (local replica only: it does not count `query_stats`).
+type FeedArgs = record { totals : QueryTotals; canister : principal };
+// A Candid-encodable representation of an HTTP request. This struct is used by
+// the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+// 
+// # Examples
+// 
+// ```
+// use ic_http_certification::{HttpRequest, Method};
+// 
+// let request = HttpRequest::builder()
+// .with_method(Method::GET)
+// .with_url("/")
+// .with_headers(vec![("X-Custom-Foo".into(), "Bar".into())])
+// .with_body(&[1, 2, 3])
+// .with_certificate_version(2)
+// .build();
+// 
+// assert_eq!(request.method(), Method::GET);
+// assert_eq!(request.url(), "/");
+// assert_eq!(request.headers(), &[("X-Custom-Foo".into(), "Bar".into())]);
+// assert_eq!(request.body(), &[1, 2, 3]);
+// assert_eq!(request.certificate_version(), Some(2));
+// ```
+// 
+// # Helpers
+// 
+// There are also a number of convenience methods for quickly creating an [HttpRequest] with
+// commonly used HTTP methods:
+// 
+// - [GET](HttpRequest::get)
+// - [POST](HttpRequest::post)
+// - [PUT](HttpRequest::put)
+// - [PATCH](HttpRequest::patch)
+// - [DELETE](HttpRequest::delete)
+// 
+// ```
+// use ic_http_certification::HttpRequest;
+// 
+// let request = HttpRequest::get("/").build();
+// 
+// assert_eq!(request.method(), "GET");
+// assert_eq!(request.url(), "/");
+// ```
+type HttpRequest = record {
+  // HTTP request URL.
+  url : text;
+  // HTTP request method.
+  method : text;
+  // HTTP request body as an array of bytes.
+  body : blob;
+  // HTTP request headers.
+  headers : vec record { text; text };
+  // The max response verification version to use in the response's
+  // certificate.
+  certificate_version : opt nat16;
+};
+// A Candid-encodable representation of an HTTP response. This struct is used
+// by the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+// 
+// # Examples
+// 
+// ```
+// use ic_http_certification::{HttpResponse, StatusCode};
+// 
+// let response = HttpResponse::builder()
+// .with_status_code(StatusCode::OK)
+// .with_headers(vec![("Content-Type".into(), "text/plain".into())])
+// .with_body(b"Hello, World!")
+// .with_upgrade(false)
+// .build();
+// 
+// assert_eq!(response.status_code(), StatusCode::OK);
+// assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+// assert_eq!(response.body(), b"Hello, World!");
+// assert_eq!(response.upgrade(), Some(false));
+// ```
+// 
+// # Helpers
+// 
+// There are also a number of convenience methods for quickly creating an [HttpResponse] with
+// commonly used HTTP status codes:
+// 
+// - [OK](HttpResponse::ok)
+// - [CREATED](HttpResponse::created)
+// - [NO_CONTENT](HttpResponse::no_content)
+// - [MOVED_PERMANENTLY](HttpResponse::moved_permanently)
+// - [TEMPORARY_REDIRECT](HttpResponse::temporary_redirect)
+// - [BAD_REQUEST](HttpResponse::bad_request)
+// - [UNAUTHORIZED](HttpResponse::unauthorized)
+// - [FORBIDDEN](HttpResponse::forbidden)
+// - [NOT_FOUND](HttpResponse::not_found)
+// - [METHOD_NOT_ALLOWED](HttpResponse::method_not_allowed)
+// - [TOO_MANY_REQUESTS](HttpResponse::too_many_requests)
+// - [INTERNAL_SERVER_ERROR](HttpResponse::internal_server_error)
+// 
+// ```
+// use ic_http_certification::{HttpResponse, StatusCode};
+// 
+// let response = HttpResponse::ok(b"Hello, World!", vec![("Content-Type".into(), "text/plain".into())]).build();
+// 
+// assert_eq!(response.status_code(), StatusCode::OK);
+// assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+// assert_eq!(response.body(), b"Hello, World!");
+// ```
+type HttpResponse = record {
+  // HTTP response body as an array of bytes.
+  body : blob;
+  // HTTP response headers.
+  headers : vec record { text; text };
+  // Whether the corresponding HTTP request should be upgraded to an update
+  // call.
+  upgrade : opt bool;
+  // HTTP response status code.
+  status_code : nat16;
+};
+type InitArgs = record { mode : Mode; superadmins : vec principal };
+type Mode = variant {
+  // The local replica: copies by the management canister (no CMC there), any subnet.
+  Local;
+  Stage;
+  Prod;
+};
+// Stored: one notification for the superadmin (key = its id).
+type Notice = record {
+  id : nat64;
+  area : opt text;
+  atNs : nat64;
+  kind : NoticeKind;
+  "text" : text;
+  canister : opt principal;
+};
+type NoticeKind = variant {
+  // The status of a copy could not be read.
+  StatusFailed;
+  BisectionStarted;
+  CopyCreated;
+  CopyDeleted;
+  // The load needs another copy, but `maxCopies` is reached.
+  MaxCopiesReached;
+  // The pass keys of a copy could not be set.
+  KeysFailed;
+  CopyMarked;
+  CopyUnmarked;
+  CopyFailed;
+  // The bisection found no single user (the load is honest) or lost its copies.
+  BisectionEnded;
+  // A core did not take the snapshot or an order.
+  CoreFailed;
+  // A system asked for too many passes in a minute.
+  SystemRateLimited;
+  // A user is blocked (bisection or too many renewals).
+  UserBlocked;
+  // A copy runs low and the coordinator cannot top it up.
+  CyclesLow;
+};
+type PassState = record {
+  // Copy → the id of its newest key and whether it holds `passRequired`.
+  keys : vec record { principal; nat32; bool };
+  cores : vec CoreCanister;
+  // Users with a valid pass, as the cores reported last.
+  activePasses : nat64;
+  systems : vec System;
+  blocks : vec Block;
+  bisections : vec BisectionRun;
+};
+// The cumulative `query_stats` of one copy (`canister_status`), as numbers.
+type QueryTotals = record {
+  calls : nat;
+  instructions : nat;
+  responseBytes : nat;
+};
+// The load of one copy between two readings, per second.
+type Rates = record {
+  responseBytesPerS : float64;
+  callsPerS : float64;
+  instructionsPerS : float64;
+};
+// Stored: the last reading of one copy (key = its canister).
+type Reading = record {
+  atNs : nat64;
+  // The reading before (the rates cover `sinceNs..atNs`).
+  sinceNs : opt nat64;
+  cycles : nat;
+  totals : QueryTotals;
+  canister : principal;
+  // Since the reading before; none after the first one (or after the totals went down).
+  rates : opt Rates;
+};
+type Result = variant { Ok : Shard; Err : Error };
+type Result_1 = variant { Ok : vec principal; Err : Error };
+type Result_10 = variant { Ok : System; Err : Error };
+type Result_11 = variant { Ok : RoundReport; Err : Error };
+type Result_12 = variant { Ok : Settings; Err : Error };
+type Result_13 = variant { Ok : bool; Err : Error };
+type Result_2 = variant { Ok : Copy; Err : Error };
+type Result_3 = variant { Ok : CoreCanister; Err : Error };
+type Result_4 = variant { Ok : WasmMeta; Err : Error };
+type Result_5 = variant { Ok : nat32; Err : Error };
+type Result_6 = variant { Ok; Err : Error };
+type Result_7 = variant { Ok : PassState; Err : Error };
+type Result_8 = variant { Ok : State; Err : Error };
+type Result_9 = variant { Ok : vec Notice; Err : Error };
+// What one round saw and did.
+type RoundReport = record {
+  atNs : nat64;
+  // What the round did, one line each.
+  actions : vec text;
+  loads : vec AreaLoad;
+  readings : vec Reading;
+};
+// Stored: the settings (key 0).
+type Settings = record {
+  hInstructionsPerS : nat64;
+  subnets : vec Subnet;
+  copyCycles : nat;
+  // `null` = false (stored before phase 4).
+  passRequired : opt bool;
+  mode : Mode;
+  // `null` = `DEFAULT_CORE_CYCLES` (stored before 2026-11-06).
+  coreCycles : opt nat;
+  superadmins : vec principal;
+  maxCopies : nat32;
+};
+type SettingsArgs = record {
+  hInstructionsPerS : nat64;
+  // Where copies may go (stage / prod); ignored on the local replica.
+  subnets : vec Subnet;
+  copyCycles : nat;
+  // Workers refuse a query without a pass (`PassMissing`); `null` keeps the value held.
+  passRequired : opt bool;
+  // Cycles of a new pass core (≥ 0.6 TC); `null` keeps the value held.
+  coreCycles : opt nat;
+  maxCopies : nat32;
+};
+// Stored: one area (key = its name).
+type Shard = record {
+  // The graph every live copy holds; set when the first copy goes live.
+  sha256 : opt text;
+  area : text;
+  bbox : Bbox;
+  osmDate : opt text;
+};
+type State = record {
+  coreWasm : opt WasmMeta;
+  shards : vec Shard;
+  lastRoundNs : opt nat64;
+  cores : vec CoreCanister;
+  wasm : opt WasmMeta;
+  loads : vec AreaLoad;
+  // The coordinator's own balance now.
+  cycles : nat;
+  readings : vec Reading;
+  settings : Settings;
+  copies : vec Copy;
+};
+type Subnet = record {
+  id : principal;
+  // A SEV subnet: the first copy of an area must stand on one.
+  sev : bool;
+};
+// Stored: one system (key = its principal).
+type System = record {
+  id : principal;
+  demo : bool;
+  blocked : bool;
+  name : text;
+  hourlyLimit : opt nat32;
+  // The demo hour: its start and the passes in it.
+  hourStartNs : nat64;
+  passesThisHour : nat32;
+  perMinute : nat32;
+};
+// A trusted system: a canister of another project or an outside system with a principal.
+type SystemArgs = record {
+  // Its principal (`principal` is a Candid keyword).
+  id : principal;
+  // Demo: short passes, a small bbox, `hourlyLimit` passes an hour for the whole system.
+  demo : bool;
+  // A blocked system gets nothing (the superadmin's decision).
+  blocked : bool;
+  name : text;
+  hourlyLimit : opt nat32;
+  // Passes a minute before `RateLimited`.
+  perMinute : nat32;
+};
+type UserKey = record { user : principal; system : principal };
+type WasmChunkArgs = record {
+  // `null` = the worker.
+  kind : opt WasmKind;
+  offset : nat64;
+  bytes : blob;
+};
+// Which wasm: the worker of the copies, or the pass core.
+type WasmKind = variant { Core; Worker };
+// Stored: the worker wasm that is uploaded or held (key 0); its bytes lie in their own memory.
+type WasmMeta = record { sha256 : text; size : nat64; ready : bool };
+service : (InitArgs) -> {
+  // A new area; its first copy comes with `createCopy`.
+  addShard : (text, Bbox) -> (Result);
+  // A superadmin adds another (e.g. the Internet Identity principal of the front: it differs
+  // from a dfx identity). At most 8; never anonymous.
+  addSuperadmin : (principal) -> (Result_1);
+  // The next steps of a copy, from where it stands; a failed step is tried again.
+  advanceCopy : (principal) -> (Result_2);
+  // Installs a core that was created but not installed (a failed `createCore`).
+  advanceCore : (principal) -> (Result_3);
+  // Where to ask: the areas and their live copies. Public; a client keeps it `ttlSeconds`.
+  areas : () -> (Areas) query;
+  beginWasm : (BeginWasmArgs) -> (Result_4);
+  // The superadmin has read the notifications up to `id`.
+  clearNotifications : (nat64) -> (Result_5);
+  // `null` = the worker.
+  commitWasm : (opt WasmKind) -> (Result_4);
+  // A core reports: its users per area (the bisection starts on them), its blocks, the systems
+  // it refused. It arms a round (at most every 10 min).
+  coreReport : (CoreReport) -> (Result_6);
+  // A new copy of `area`: created, installed, then its steps as far as they go (`advanceCopy`
+  // goes on).
+  createCopy : (text) -> (Result_2);
+  // A new pass core: created (on a SEV subnet outside the local replica), installed with the
+  // core wasm, then given the snapshot.
+  createCore : () -> (Result_3);
+  // Only a superadmin deletes, only a marked copy off the list for one list TTL.
+  deleteCopy : (principal) -> (Result_6);
+  // Local replica only: totals of `query_stats` for the next rounds (it counts none itself).
+  feedQueryStats : (vec FeedArgs) -> (Result_6);
+  getPassState : () -> (Result_7) query;
+  getState : () -> (Result_8) query;
+  // Every coordinator (`sharding.md`): the crafting table asks before a reinstall.
+  hasDependents : () -> (bool) query;
+  // The superadmin front, for everybody: the page and its files. It shows nothing by itself;
+  // it asks the methods of the superadmins, as the person who signed in.
+  http_request : (HttpRequest) -> (HttpResponse) query;
+  // Which core issues the passes of `user` (public; a system keeps it with the list TTL).
+  issuerFor : (principal) -> (opt principal) query;
+  listDependents : () -> (vec principal) query;
+  // A superadmin takes a live copy off the list (the coordinator marks after 24 h of low load).
+  markCopy : (principal) -> (Result_2);
+  notifications : () -> (Result_9) query;
+  // A superadmin removes one; the last one stays.
+  removeSuperadmin : (principal) -> (Result_1);
+  // A system is gone: the cores forget it (its users' passes are refused from the next sync;
+  // passes already given stay valid until they end). E.g. a core of a group replaced by the
+  // group's coordinator as the system.
+  removeSystem : (principal) -> (Result_10);
+  // A round now, whatever the time of the last one; refused while one runs.
+  runRound : () -> (Result_11);
+  setSettings : (SettingsArgs) -> (Result_12);
+  // A system added or changed; the cores get it at once.
+  setSystem : (SystemArgs) -> (Result_10);
+  // Only a superadmin unblocks: every core lifts the block (the renewal count starts again).
+  unblockUser : (UserKey) -> (Result_13);
+  // A live (or marked) replicated instance gets the worker wasm held (stop → upgrade → start);
+  // its graphs and pass keys stay (stable memory). A failed step is kept in `lastError`.
+  upgradeCopy : (principal) -> (Result_2);
+  // A live core gets the core wasm held (stop → upgrade → start); its state stays. Then every
+  // core gets the snapshot again. A failed step is kept in `lastError`.
+  upgradeCore : (principal) -> (Result_3);
+  wasmChunk : (WasmChunkArgs) -> (Result_6);
+}