@ohos-ports/azle 0.33.0-beta.0

package/src/stable/build/commands/build/javascript.ts

@@ -0,0 +1,259 @@
+import { build, BuildOptions } from 'esbuild';
+import { dirname, join } from 'path';
+
+import { getDfxRoot } from '#utils/dfx_root';
+
+export async function compile(main: string): Promise<string> {
+    const prelude = getPrelude(main);
+    const buildOptions = getBuildOptions(prelude, main);
+    const bundled = await bundle(buildOptions);
+
+    return bundled;
+}
+
+function getPrelude(main: string): string {
+    const absoluteMainPath = join(getDfxRoot(), main);
+    return /*TS*/ `
+            import 'azle/_internal/globals';
+
+            import { getDefaultVisitorData, IDL, idlToString } from 'azle';
+
+            import * as CanisterModule from '${absoluteMainPath}';
+
+            createGetCandidAndMethodMetaFunction(CanisterModule);
+
+            ${handleClassApiCanister(main)}
+
+            ${handleBenchmarking()}
+        `;
+}
+
+export function handleClassApiCanister(main: string): string {
+    return /*TS*/ `
+        /**
+         * @internal
+         *
+         * This function will create the globalThis._azleGetCandidAndMethodMeta variable.
+         * This global variable is used by the Node.js build environment to retrieve
+         * the canister's generated Candid string and the method metadata necessary
+         * for the final manipulated binary to be deployed.
+         */
+        function createGetCandidAndMethodMetaFunction(canisterModule) {
+            const canisterClassMeta = getCanisterClassMeta(canisterModule);
+
+            if (globalThis._azleDispatch === undefined) {
+                throw new Error('globalThis._azleDispatch is undefined');
+            }
+
+            globalThis._azleDispatch({
+                type: 'SET_AZLE_CANISTER_CLASS_META',
+                payload: canisterClassMeta,
+                location: {
+                    filepath: 'azle/src/stable/build/commands/build/javascript.ts',
+                    functionName: 'handleClassApiCanister'
+                }
+            });
+
+            const visibleMethodIdlParamTypes = Object.fromEntries(
+                Object.entries(canisterClassMeta.canisterMethodIdlParamTypes)
+                    .filter(([methodName]) => isMethodVisible(methodName, canisterClassMeta.methodMeta))
+            );
+
+            const canisterIdlType = IDL.Service(visibleMethodIdlParamTypes);
+            const candid = idlToString(canisterIdlType, {
+                ...getDefaultVisitorData(),
+                isFirstService: true,
+                initAndPostUpgradeParamIdlTypes: canisterClassMeta.initAndPostUpgradeIdlTypes
+            });
+
+            globalThis._azleGetCandidAndMethodMeta = () => {
+                return JSON.stringify({
+                    candid,
+                    methodMeta: canisterClassMeta.methodMeta
+                });
+            };
+        }
+
+        /**
+         * @internal
+         *
+         * This function is used to get the CanisterClassMeta object
+         * that contains all of the information required for Candid file generation,
+         * Wasm binary export manipulation, canister method callback invocation, etc.
+         * Unfortunately for now we must execute the canister in a Node Wasm environment
+         * in order to get some of the CanisterClassMeta information needed to manipulate
+         * the Wasm binary and generate the Candid file before final canister deployment.
+         * It would be ideal to avoid this extra Node Wasm environment execution,
+         * but we currently don't know how to do this. Possible ideas:
+         * - ICP protocol improvement to allow for dynamic canister method registration
+         * - ICP replica improvement to automatically run Wasm binaries through a similar process as our Node.js Wasm environment
+         */
+        function getCanisterClassMeta(canisterModule) {
+            const defaultExportNotDefined = canisterModule.default === undefined || canisterModule.default === null;
+            const defaultExportNotAnArrayOrClass = Array.isArray(canisterModule.default) === false && isClass(canisterModule.default) === false;
+            const defaultExportAnArrayWithNonClasses = Array.isArray(canisterModule.default) === true && canisterModule.default.every((canisterClass) => isClass(canisterClass) === true) === false;
+
+            if (
+                defaultExportNotDefined === true ||
+                defaultExportNotAnArrayOrClass === true ||
+                defaultExportAnArrayWithNonClasses === true
+
+            ) {
+                throw new Error('A class or an array of classes must be the default export from ${main}');
+            }
+
+            const canisterClasses = Array.isArray(canisterModule.default) ? canisterModule.default : [canisterModule.default];
+
+            // This object WILL BE MUTATED.
+            // This is the original CanisterClassMeta object that we will
+            // pass as a property of the constructor of each exported canister class just before
+            // instantiating it. Each instantiation of an exported canister class
+            // will mutate this same object, as the same reference will be passed along.
+            // After all instantiations are complete, this will be the final CanisterClassMeta object
+            // that we set on globalThis._azleCanisterClassMeta that contains all of the information
+            // required for Candid file generation, Wasm binary export manipulation, and canister method callback invocation.
+            // We may wish to revisit these mutations later on, but it is working very well for now.
+            // We would have to do a large refactor of the decorators to get rid of these mutations.
+            let canisterClassMeta = {
+                callbacks: {},
+                canisterMethodIdlParamTypes: {},
+                canisterMethodsIndex: 0,
+                initAndPostUpgradeIdlTypes: [],
+                methodMeta: {
+                    queries: [],
+                    updates: []
+                }
+            };
+
+            canisterClasses.forEach((canisterClass) => {
+                canisterClass._azleCanisterClassMeta = canisterClassMeta;
+                // canisterClassMeta WILL BE MUTATED inside of this instantiation
+                new canisterClass();
+            });
+
+            return canisterClassMeta;
+        }
+
+        /**
+         * @internal
+         *
+         * Uses a heuristic to determine if a value is a class or not
+         */
+        function isClass(value) {
+            return value !== undefined && value !== null && typeof value === 'function' && value.toString().startsWith('class');
+        }
+
+        /**
+         * @internal
+         *
+         * Determines if a method should be visible in Candid based on its hidden status
+         */
+        function isMethodVisible(methodName, methodMeta) {
+            const { queries = [], updates = [] } = methodMeta;
+            const allMethods = [...queries, ...updates];
+            const method = allMethods.find(m => m.name === methodName);
+            return method?.hidden === false;
+        }
+    `;
+}
+
+export async function bundle(buildOptions: BuildOptions): Promise<string> {
+    const buildResult = await build(buildOptions);
+
+    if (buildResult.outputFiles === undefined) {
+        throw new Error(
+            `Build process failed to produce JavaScript output files`
+        );
+    }
+
+    const bundleArray = buildResult.outputFiles[0].contents;
+    const bundleString = Buffer.from(bundleArray).toString('utf-8');
+
+    return bundleString;
+}
+
+// TODO tree-shaking does not seem to work with stdin. I have learned this from sad experience
+export function getBuildOptions(ts: string, main: string): BuildOptions {
+    return {
+        stdin: {
+            contents: ts,
+            resolveDir: dirname(join(getDfxRoot(), main))
+        },
+        format: 'esm',
+        bundle: true,
+        treeShaking: true,
+        write: false,
+        logLevel: 'silent',
+        target: 'es2024',
+        preserveSymlinks: true,
+        plugins: [
+            {
+                name: 'Azle experimental check',
+                setup(build): void {
+                    build.onResolve(
+                        {
+                            filter: /^internal$|^util$|^fs$|^fs\/promises$|^fmt$|^assert$|^buffer$|^path$|^stream$|^process$|^url$|^events$|^string_decoder$|^punycode$|^querystring$|^whatwg_url$|^encoding$|^http$|^os$|^crypto$|^zlib$|^internal\/deps\/acorn\/acorn\/dist\/acorn$|^internal\/deps\/acorn\/acorn-walk\/dist\/walk$|^perf_hooks$|^async_hooks$|^https$|^_node:fs$|^_node:os$|^_node:crypto$|^qjs:os$|^_encoding$|^wasi_net$|^wasi_http$/
+                        },
+                        (args) => {
+                            throw experimentalMessage(args.path);
+                        }
+                    );
+                }
+            }
+        ]
+    };
+}
+
+function experimentalMessage(importName: string): string {
+    return `Experimental mode must be enabled to import from ${importName}. You can enable experimental mode in your dfx.json file like this:
+{
+    "canisters": {
+        "canisterName": {
+            "type": "azle",
+            "main": "index.ts",
+            "custom": {
+                "experimental": true
+            }
+        }
+    }
+}
+`;
+}
+
+function handleBenchmarking(): string {
+    return /*TS*/ `
+        if (globalThis.process !== undefined && globalThis.process.env.AZLE_RECORD_BENCHMARKS === 'true') {
+            const methodMeta = canisterClassMeta.methodMeta;
+
+            const canisterMethodNames = Object.entries(methodMeta).reduce((acc, [key, value]) => {
+                if (value === undefined) {
+                    return acc;
+                }
+
+                if (key === 'queries' || key === 'updates') {
+                    const queriesOrUpdates = value.reduce((innerAcc, method) => {
+                        const indexString = method.index.toString();
+                        return { ...innerAcc, [indexString]: method.name };
+                    }, {});
+                    return { ...acc, ...queriesOrUpdates };
+                } else {
+                    const indexString = value.index.toString();
+                    return { ...acc, [indexString]: value.name };
+                }
+            }, {});
+
+            if (globalThis._azleDispatch === undefined) {
+                throw new Error('globalThis._azleDispatch is undefined');
+            }
+
+            globalThis._azleDispatch({
+                type: 'SET_AZLE_CANISTER_METHOD_NAMES',
+                payload: canisterMethodNames,
+                location: {
+                    filepath: 'azle/src/stable/build/commands/build/javascript.ts',
+                    functionName: 'handleBenchmarking'
+                }
+            });
+        }
+    `;
+}

package/src/stable/build/commands/build/wasm_binary/compile.ts

@@ -0,0 +1,27 @@
+import { IOType } from 'child_process';
+
+import { execSyncPretty } from '#utils/exec_sync_pretty';
+import { AZLE_CARGO_TARGET_DIR } from '#utils/global_paths';
+
+export function compile(
+    manifestPath: string,
+    wasmDest: string,
+    ioType: IOType,
+    experimental: boolean = false
+): void {
+    execSyncPretty(
+        `CARGO_TARGET_DIR=${AZLE_CARGO_TARGET_DIR} cargo build --target wasm32-wasip1 --manifest-path ${manifestPath} --release --locked`,
+        {
+            stdio: ioType
+        }
+    );
+
+    execSyncPretty(
+        `wasi2ic ${AZLE_CARGO_TARGET_DIR}/wasm32-wasip1/release/${
+            experimental === true ? 'experimental' : 'stable'
+        }_canister_template.wasm ${wasmDest}`,
+        {
+            stdio: ioType
+        }
+    );
+}

package/src/stable/build/commands/build/wasm_binary/index.ts

@@ -0,0 +1,30 @@
+import { IOType } from 'child_process';
+import { existsSync } from 'fs';
+
+import { runCommand as runDevTemplateCommand } from '#build/commands/dev/template/stable';
+import { STABLE_STATIC_CANISTER_TEMPLATE_PATH } from '#utils/global_paths';
+import { MethodMeta, WasmData } from '#utils/types';
+
+import { manipulateWasmBinary } from './manipulate';
+
+export async function getWasmBinary(
+    ioType: IOType,
+    js: string,
+    wasmData: WasmData,
+    methodMeta?: MethodMeta
+): Promise<Uint8Array> {
+    if (
+        process.env.AZLE_DEV_TEMPLATE === 'true' ||
+        !existsSync(STABLE_STATIC_CANISTER_TEMPLATE_PATH)
+    ) {
+        await runDevTemplateCommand(ioType);
+    }
+
+    return await manipulateWasmBinary<WasmData>(
+        js,
+        STABLE_STATIC_CANISTER_TEMPLATE_PATH,
+        wasmData,
+        false,
+        methodMeta
+    );
+}

package/src/stable/build/commands/build/wasm_binary/manipulate.ts

@@ -0,0 +1,268 @@
+import binaryen from 'binaryen';
+import { readFile } from 'fs/promises';
+
+import { MethodMeta } from '#utils/types';
+
+// TODO can we make the start function just load the passive segment into memory?
+export async function manipulateWasmBinary<T extends Record<string, unknown>>(
+    js: string,
+    canisterTemplatePath: string,
+    wasmData: T,
+    validate: boolean,
+    methodMeta?: MethodMeta
+): Promise<Uint8Array> {
+    const module = await getModule(canisterTemplatePath);
+
+    addCanisterMethodProxies(module, methodMeta);
+
+    const { memoryInfo, memorySegmentInfos } = getMemoryInformation(module);
+
+    const encodedJs = encode(js);
+    const encodedWasmData = encode(JSON.stringify(wasmData));
+
+    addPassiveDataSegmentsToMemory(
+        module,
+        memoryInfo,
+        memorySegmentInfos,
+        encodedJs,
+        encodedWasmData
+    );
+
+    addPassiveSizeFunction(module, 'js_passive_data_size', encodedJs);
+    addPassiveSizeFunction(
+        module,
+        'wasm_data_passive_data_size',
+        encodedWasmData
+    );
+
+    addInitPassiveDataFunction(
+        module,
+        'init_js_passive_data',
+        memorySegmentInfos.length,
+        encodedJs
+    );
+    addInitPassiveDataFunction(
+        module,
+        'init_wasm_data_passive_data',
+        memorySegmentInfos.length + 1,
+        encodedWasmData
+    );
+
+    if (validate === true) {
+        module.validate();
+    }
+
+    return module.emitBinary();
+}
+
+export async function getModule(
+    wasmBinaryPath: string
+): Promise<binaryen.Module> {
+    const originalWasm = await readFile(wasmBinaryPath);
+    // Toggle debug info based on AZLE_CANISTER_BACKTRACES environment variable
+    // Backtraces are off by default to avoid exposing end developers to confusing Rust messages.
+    // Azle's error messages are designed to provide relevant details to end developers.
+    // Canister backtraces are usually for Azle core developers debugging internal issues.
+    // When set to 'true', backtraces are enabled by keeping the name section
+    // When not set or set to any other value, backtraces are disabled by removing the name section
+    const enableBacktraces = process.env.AZLE_CANISTER_BACKTRACES === 'true';
+    binaryen.setDebugInfo(enableBacktraces);
+    const module = binaryen.readBinary(originalWasm);
+
+    return module;
+}
+
+export function addCanisterMethodProxies(
+    module: binaryen.Module,
+    methodMeta: MethodMeta | undefined
+): void {
+    methodMeta?.queries?.forEach(({ name: functionName, index, composite }) => {
+        addCanisterMethod(
+            module,
+            `${
+                composite === true
+                    ? 'canister_composite_query'
+                    : 'canister_query'
+            } ${functionName}`,
+            'execute_method_js',
+            index
+        );
+    });
+
+    methodMeta?.updates?.forEach(({ name: functionName, index }) => {
+        addCanisterMethod(
+            module,
+            `canister_update ${functionName}`,
+            'execute_method_js',
+            index
+        );
+    });
+
+    addCanisterMethod(
+        module,
+        'canister_init',
+        'init',
+        methodMeta?.init?.index ?? -1
+    );
+
+    addCanisterMethod(
+        module,
+        'canister_post_upgrade',
+        'post_upgrade',
+        methodMeta?.post_upgrade?.index ?? -1
+    );
+
+    if (methodMeta?.pre_upgrade !== undefined) {
+        addCanisterMethod(
+            module,
+            'canister_pre_upgrade',
+            'execute_method_js',
+            methodMeta.pre_upgrade.index
+        );
+    }
+
+    if (methodMeta?.inspect_message !== undefined) {
+        addCanisterMethod(
+            module,
+            'canister_inspect_message',
+            'execute_method_js',
+            methodMeta.inspect_message.index
+        );
+    }
+
+    if (methodMeta?.heartbeat !== undefined) {
+        addCanisterMethod(
+            module,
+            'canister_heartbeat',
+            'execute_method_js',
+            methodMeta.heartbeat.index
+        );
+    }
+
+    if (methodMeta?.on_low_wasm_memory !== undefined) {
+        addCanisterMethod(
+            module,
+            'canister_on_low_wasm_memory',
+            'execute_method_js',
+            methodMeta.on_low_wasm_memory.index
+        );
+    }
+}
+
+export function addCanisterMethod(
+    module: binaryen.Module,
+    exportName: string,
+    functionToCall: string,
+    index: number
+): void {
+    const funcBody = module.block(null, [
+        module.call(functionToCall, [module.i32.const(index)], binaryen.none)
+    ]);
+
+    module.addFunction(exportName, binaryen.none, binaryen.none, [], funcBody);
+
+    module.addFunctionExport(exportName, exportName);
+}
+
+export function getMemoryInformation(module: binaryen.Module): {
+    memoryInfo: binaryen.MemoryInfo;
+    memorySegmentInfos: binaryen.MemorySegmentInfo[];
+} {
+    const memoryInfo = module.getMemoryInfo();
+
+    const numMemorySegments = module.getNumMemorySegments();
+
+    let memorySegmentInfos: binaryen.MemorySegmentInfo[] = [];
+
+    for (let i = 0; i < numMemorySegments; i++) {
+        const segment = module.getMemorySegmentInfoByIndex(i);
+
+        memorySegmentInfos.push(segment);
+    }
+
+    // Normalization is necessary for some reason
+    // the TypeScript types work out fine without normalization
+    // but not the actual values during manipulation
+    const normalizedMemorySegmentInfos = memorySegmentInfos.map(
+        (memorySegmentInfo) => {
+            return {
+                offset: module.i32.const(memorySegmentInfo.offset),
+                // This must be wrapped in a Uint8Array or this error will be thrown during the build: Azle BuildError: RuntimeError: null function or function signature mismatch
+                data: new Uint8Array(memorySegmentInfo.data),
+                passive: memorySegmentInfo.passive
+            };
+        }
+    );
+
+    return {
+        memoryInfo,
+        memorySegmentInfos: normalizedMemorySegmentInfos
+    };
+}
+
+export function encode(text: string): Uint8Array {
+    return new TextEncoder().encode(text);
+}
+
+export function addPassiveDataSegmentsToMemory(
+    module: binaryen.Module,
+    memoryInfo: binaryen.MemoryInfo,
+    memorySegmentInfos: binaryen.MemorySegmentInfo[],
+    encodedJs: Uint8Array,
+    encodedWasmData: Uint8Array
+): void {
+    module.setMemory(memoryInfo.initial, memoryInfo.max ?? -1, null, [
+        ...memorySegmentInfos,
+        {
+            offset: 0,
+            data: encodedJs,
+            passive: true
+        },
+        {
+            offset: 0,
+            data: encodedWasmData,
+            passive: true
+        }
+    ]);
+}
+
+export function addPassiveSizeFunction(
+    module: binaryen.Module,
+    name: string,
+    encoded: Uint8Array
+): void {
+    module.removeFunction(name);
+
+    module.addFunction(
+        name,
+        binaryen.none,
+        binaryen.i32,
+        [],
+        module.i32.const(encoded.byteLength)
+    );
+}
+
+export function addInitPassiveDataFunction(
+    module: binaryen.Module,
+    name: string,
+    segmentNumber: number,
+    encoded: Uint8Array
+): void {
+    module.removeFunction(name);
+
+    module.addFunction(
+        name,
+        binaryen.createType([binaryen.i32]),
+        binaryen.none,
+        [],
+        module.block(null, [
+            module.memory.init(
+                segmentNumber.toString() as unknown as number,
+                module.local.get(0, binaryen.i32),
+                module.i32.const(0),
+                module.i32.const(encoded.byteLength)
+            ),
+            module.data.drop(segmentNumber.toString() as unknown as number)
+        ])
+    );
+}

package/src/stable/build/commands/build/wasm_binary/rust/stable_canister_template/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "stable_canister_template"
+version = "0.0.0"
+edition = "2024"
+license-file = "../../../../../../../../LICENSE"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+candid = { workspace = true }
+candid_parser = { workspace = true }
+ic-cdk = { workspace = true }
+ic-cdk-timers = { workspace = true }
+ic-stable-structures = { workspace = true }
+ic-wasi-polyfill = { workspace = true }
+peak_alloc = { workspace = true }
+rand = { workspace = true }
+rquickjs = { version = "0.9.0", features = ["array-buffer"] }
+scopeguard = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+slotmap = { workspace = true }

package/src/stable/build/commands/build/wasm_binary/rust/stable_canister_template/src/benchmarking.rs

@@ -0,0 +1,45 @@
+use std::{cell::RefCell, error::Error};
+
+use candid::CandidType;
+use ic_cdk::api::time;
+use rquickjs::Object;
+
+use crate::rquickjs_utils::with_ctx;
+
+#[derive(CandidType, Debug, Clone)]
+pub struct BenchmarkEntry {
+    pub method_name: String,
+    pub instructions: u64,
+    pub timestamp: u64,
+}
+
+thread_local! {
+    pub static BENCHMARKS_REF_CELL: RefCell<Vec<BenchmarkEntry>> = RefCell::new(Vec::new());
+}
+
+pub fn record_benchmark(function_name: &str, instructions: u64) -> Result<(), Box<dyn Error>> {
+    with_ctx(|ctx| {
+        let timestamp = time();
+
+        let method_names: Object = ctx
+            .clone()
+            .globals()
+            .get("_azleCanisterMethodNames")
+            .map_err(|e| format!("Failed to get globalThis._azleCanisterMethodNames: {e}"))?;
+
+        let method_name: String = method_names.get(function_name).map_err(|e| {
+            format!("Failed to get globalThis._azleCanisterMethodNames[{function_name}]: {e}")
+        })?;
+
+        BENCHMARKS_REF_CELL.with(|benchmarks_ref_cell| {
+            let mut benchmarks = benchmarks_ref_cell.borrow_mut();
+            benchmarks.push(BenchmarkEntry {
+                method_name,
+                instructions,
+                timestamp,
+            });
+        });
+
+        Ok(())
+    })
+}