From 05ef4382ccaeadf6ad057159633b71515e103af1 Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Thu, 21 Nov 2024 07:27:12 +0100 Subject: [PATCH 1/5] feat: load canister snapshots Signed-off-by: David Dal Busco --- .../src/ic-management.canister.spec.ts | 79 +++++++++++++++++++ .../src/ic-management.canister.ts | 35 ++++++++ 2 files changed, 114 insertions(+) diff --git a/packages/ic-management/src/ic-management.canister.spec.ts b/packages/ic-management/src/ic-management.canister.spec.ts index e8409dbd9..45c125791 100644 --- a/packages/ic-management/src/ic-management.canister.spec.ts +++ b/packages/ic-management/src/ic-management.canister.spec.ts @@ -805,4 +805,83 @@ describe("ICManagementCanister", () => { await expect(call).rejects.toThrow(error); }); }); + + describe("loadCanisterSnapshot", () => { + it("should call load_canister_snapshot with Uint8Array snapshotId", async () => { + const service = mock(); + service.load_canister_snapshot.mockResolvedValue(undefined); + + const icManagement = await createICManagement(service); + + const params = { + canisterId: mockCanisterId, + snapshotId: Uint8Array.from([1, 2, 3, 4]), + }; + + await icManagement.loadCanisterSnapshot(params); + + expect(service.load_canister_snapshot).toHaveBeenCalledWith({ + canister_id: params.canisterId, + snapshot_id: params.snapshotId, + sender_canister_version: [], + }); + }); + + it("should call load_canister_snapshot with string snapshotId", async () => { + const service = mock(); + service.load_canister_snapshot.mockResolvedValue(undefined); + + const icManagement = await createICManagement(service); + + const params = { + canisterId: mockCanisterId, + snapshotId: "000000000000000201010000000000000001", + }; + + await icManagement.loadCanisterSnapshot(params); + + expect(service.load_canister_snapshot).toHaveBeenCalledWith({ + canister_id: params.canisterId, + snapshot_id: decodeSnapshotId(params.snapshotId), + sender_canister_version: [], + }); + }); + + it("should call load_canister_snapshot with senderCanisterVersion", async () => { + const service = mock(); + service.load_canister_snapshot.mockResolvedValue(undefined); + + const icManagement = await createICManagement(service); + + const params = { + canisterId: mockCanisterId, + snapshotId: Uint8Array.from([1, 2, 3, 4]), + senderCanisterVersion: 5n, + }; + + await icManagement.loadCanisterSnapshot(params); + + expect(service.load_canister_snapshot).toHaveBeenCalledWith({ + canister_id: params.canisterId, + snapshot_id: params.snapshotId, + sender_canister_version: [params.senderCanisterVersion], + }); + }); + + it("should throw an Error if load_canister_snapshot fails", async () => { + const error = new Error("Test"); + const service = mock(); + service.load_canister_snapshot.mockRejectedValue(error); + + const icManagement = await createICManagement(service); + + const call = () => + icManagement.loadCanisterSnapshot({ + canisterId: mockCanisterId, + snapshotId: Uint8Array.from([1, 2, 3, 4]), + }); + + await expect(call).rejects.toThrow(error); + }); + }); }); diff --git a/packages/ic-management/src/ic-management.canister.ts b/packages/ic-management/src/ic-management.canister.ts index 3b17493a1..53aafe563 100644 --- a/packages/ic-management/src/ic-management.canister.ts +++ b/packages/ic-management/src/ic-management.canister.ts @@ -392,4 +392,39 @@ export class ICManagementCanister { ), }); }; + + /** + * Loads a snapshot of a canister's state. + * + * @link https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-load_canister_snapshot + * + * @param {Object} params - Parameters for the snapshot loading operation. + * @param {Principal} params.canisterId - The ID of the canister for which the snapshot will be loaded. + * @param {snapshot_id} params.snapshotId - The ID of the snapshot to load. + * @param {BigInt} [params.senderCanisterVersion] - The optional sender canister version. If provided, its value must be equal to ic0.canister_version. + * + * @returns {Promise} A promise that resolves when the snapshot is successfully loaded. + * + * @throws {Error} If the snapshot loading operation fails. + */ + loadCanisterSnapshot = async ({ + canisterId, + snapshotId, + senderCanisterVersion, + }: { + canisterId: Principal; + snapshotId: SnapshotIdText | snapshot_id; + senderCanisterVersion?: bigint; + }): Promise => { + const { load_canister_snapshot } = this.service; + + await load_canister_snapshot({ + canister_id: canisterId, + snapshot_id: + typeof snapshotId === "string" + ? decodeSnapshotId(snapshotId) + : snapshotId, + sender_canister_version: toNullable(senderCanisterVersion), + }); + }; } From ab98850e1a23c8acca3499180937709c728c8477 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 21 Nov 2024 06:28:38 +0000 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=A4=96=20Documentation=20auto-update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/ic-management/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/ic-management/README.md b/packages/ic-management/README.md index 97f1b3a05..032477d2e 100644 --- a/packages/ic-management/README.md +++ b/packages/ic-management/README.md @@ -74,6 +74,7 @@ const { status, memory_size, ...rest } = await canisterStatus(YOUR_CANISTER_ID); - [provisionalCreateCanisterWithCycles](#gear-provisionalcreatecanisterwithcycles) - [fetchCanisterLogs](#gear-fetchcanisterlogs) - [takeCanisterSnapshot](#gear-takecanistersnapshot) +- [loadCanisterSnapshot](#gear-loadcanistersnapshot) ##### :gear: create @@ -264,6 +265,23 @@ Parameters: [:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L375) +##### :gear: loadCanisterSnapshot + +Loads a snapshot of a canister's state. + +| Method | Type | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `loadCanisterSnapshot` | `({ canisterId, snapshotId, senderCanisterVersion, }: { canisterId: Principal; snapshotId: string or snapshot_id; senderCanisterVersion?: bigint or undefined; }) => Promise` | + +Parameters: + +- `params`: - Parameters for the snapshot loading operation. +- `params.canisterId`: - The ID of the canister for which the snapshot will be loaded. +- `params.snapshotId`: - The ID of the snapshot to load. +- `params.senderCanisterVersion`: - The optional sender canister version. If provided, its value must be equal to ic0.canister_version. + +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L410) + ## Resources From a638bbb38128870f3c01c47bee632b5c1ecf192b Mon Sep 17 00:00:00 2001 From: David Dal Busco Date: Thu, 21 Nov 2024 12:51:46 +0100 Subject: [PATCH 3/5] feat: use mapSnapshotId Signed-off-by: David Dal Busco --- packages/ic-management/src/ic-management.canister.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/ic-management/src/ic-management.canister.ts b/packages/ic-management/src/ic-management.canister.ts index 9d3465cb8..dc3ef9cad 100644 --- a/packages/ic-management/src/ic-management.canister.ts +++ b/packages/ic-management/src/ic-management.canister.ts @@ -416,10 +416,7 @@ export class ICManagementCanister { await load_canister_snapshot({ canister_id: canisterId, - snapshot_id: - typeof snapshotId === "string" - ? decodeSnapshotId(snapshotId) - : snapshotId, + snapshot_id: mapSnapshotId(snapshotId), sender_canister_version: toNullable(senderCanisterVersion), }); }; From fee670a64ce604aec3b15c9f2f0ce0c34bc5e9f7 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 21 Nov 2024 11:53:20 +0000 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=A4=96=20Documentation=20auto-update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/ic-management/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ic-management/README.md b/packages/ic-management/README.md index 032477d2e..b3a1cebb8 100644 --- a/packages/ic-management/README.md +++ b/packages/ic-management/README.md @@ -280,7 +280,7 @@ Parameters: - `params.snapshotId`: - The ID of the snapshot to load. - `params.senderCanisterVersion`: - The optional sender canister version. If provided, its value must be equal to ic0.canister_version. -[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L410) +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L406) From 15b5fe18f3910d65094647b13601a8a7717f32a6 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 21 Nov 2024 12:40:51 +0000 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=A4=96=20Documentation=20auto-update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/ic-management/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/ic-management/README.md b/packages/ic-management/README.md index e933eb0ac..3184e1e13 100644 --- a/packages/ic-management/README.md +++ b/packages/ic-management/README.md @@ -75,6 +75,7 @@ const { status, memory_size, ...rest } = await canisterStatus(YOUR_CANISTER_ID); - [fetchCanisterLogs](#gear-fetchcanisterlogs) - [takeCanisterSnapshot](#gear-takecanistersnapshot) - [listCanisterSnapshots](#gear-listcanistersnapshots) +- [loadCanisterSnapshot](#gear-loadcanistersnapshot) ##### :gear: create @@ -280,6 +281,23 @@ Parameters: [:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L405) +##### :gear: loadCanisterSnapshot + +Loads a snapshot of a canister's state. + +| Method | Type | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `loadCanisterSnapshot` | `({ canisterId, snapshotId, senderCanisterVersion, }: { canisterId: Principal; snapshotId: string or snapshot_id; senderCanisterVersion?: bigint or undefined; }) => Promise` | + +Parameters: + +- `params`: - Parameters for the snapshot loading operation. +- `params.canisterId`: - The ID of the canister for which the snapshot will be loaded. +- `params.snapshotId`: - The ID of the snapshot to load. +- `params.senderCanisterVersion`: - The optional sender canister version. If provided, its value must be equal to ic0.canister_version. + +[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/ic-management/src/ic-management.canister.ts#L431) + ## Resources