@jsm-mit/sultana-sharded-package

The one package of the sharded Sultana group. It takes the coordinator's id and hides the coordinator, the core and the workers: for a consumer the group is one canister (starting-point/rules/icp/canister-wrapper-package.md, sharding.md).

import { SalonsActor, SearchActor } from "@jsm-mit/sultana-sharded-package";

const salons = new SalonsActor(coordinatorId, identity);            // mainnet
const local = new SalonsActor(coordinatorId, identity, { host: "http://127.0.0.1:4943" });
const salonId = await salons.createSalonAsyncUnsafe(address, location, name);

How a call finds its canister

| Call | Goes to | |---|---| | profiles, the service-type dictionary, settings, admins, stats, the seed (BulkActor) | the core (its id comes from the coordinator, kept for good) | | a new salon (createSalon) | the worker of the salon's region — the longest geohash prefix of the coordinator's map | | anything of one salon | the worker that holds the salon (asked from the coordinator, kept until the worker says "not mine") | | search, the promo feed of some cells | the workers of those cells, in slices of at most 800 cells (a worker refuses more), all in parallel; the answers merged | | "my" lists (salons, appointments), the world promo feed | every worker, in parallel | | a person's own day (setDailySchedule, …) | every worker (a person busy in one salon is busy in all) | | linkWorkerByCode | the core says the salon of the code, its worker links | | every salon id, the feed of changed salons (listAllSalonIdsAsyncUnsafe, getSalonChangesAsyncUnsafe(cursor?)) | every worker, in parallel; ONE cursor (a text) holds the place in each |

updateSalonAsyncUnsafe with a pin in another worker's region makes the coordinator move the salon there in the background (coordinator/scripts/local-relocate-check.sh).

A salon on its way to another worker answers writes with SalonIsMoving; the package tries again a few seconds later. A worker that does not hold a salon (any more) answers NotFound; the package asks the coordinator again and follows the salon.

API changes from sultana-core-motoko-package: every actor takes (coordinatorId, identity?, options?); the calls keyed by the id of something INSIDE a salon take the salon too — cancelAppointmentAsyncUnsafe(salonId, appointmentId), getVisitAsyncUnsafe(salonId, visitId), getVisitHistoryAsyncUnsafe, updateVisitAsyncUnsafe(salonId, …), updateSalonServiceAsyncUnsafe(salonId, …), removeSalonServiceAsyncUnsafe(salonId, …) and the four …ToSalonService / …FromSalonService calls. ensureSalonAssistantAsyncUnsafe(salonId, salonName?) lives on the core (it knows every salon's owner) and binds the agent to the group by its coordinator. Gone (for now): the second superadmin and the system-admin seat (the coordinator keeps the core's admins: getAdminsAsyncUnsafe), the export of salon data (MigrationActor exports the profiles only), the automatic report of slow calls (StatsActor reports by hand).

The second entry: /group

@jsm-mit/sultana-sharded-package/group — calls to ONE canister of the group by its id (WorkerSalonsActor: one worker's salons and its own change feed), for the superadmin's scripts and tests. An app uses the main entry only.

Tests

All on the LOCAL replica — no cycles, nothing on mainnet:

npm run test-smoke         # one write and one read per domain
npm run test-local         # every suite, each on a fresh group
npm run test-search-unit && npm run test-asap-unit   # pure unit tests

scripts/run-tests-local.sh builds core and worker, brings up a fresh group (../coordinator/scripts/local-group.sh --live), adds a generated test superadmin to the core's admins through the coordinator and runs the entry with COORDINATOR_CANISTER_ID, HOST and TEST_SUPERADMIN_SEED.

Declarations and publishing

• npm run sync-declarations regenerates declarations/{core,worker,coordinator} from the three parts next to it.
• npm run publish-public (the user runs it): from a clean, pushed master of sultana-sharded; the declarations must match the builds; the smoke test runs on a fresh local group; the package carries the repo's commit (sultanaSharded.commit).