@ohos-ports/azle 0.33.0-beta.0

package/src/stable/lib/error.ts

@@ -0,0 +1,55 @@
+import { trap } from './ic_apis/trap';
+
+/**
+ * Handles uncaught errors in the canister execution environment by converting them
+ * to a formatted error message and calling IC trap. This function ensures that all
+ * uncaught errors are properly reported with stack traces before halting execution.
+ *
+ * @param rawError - The raw error value to handle. Can be an Error object or any other value
+ * @returns never - This function always traps and never returns
+ *
+ * @remarks
+ *
+ * If an uncaught error happens during execution of the cleanup callback of an inter-canister call,
+ * then its `rejectCode` will be set to `10_001` and its `rejectMessage` will be set to
+ * `executing within cleanup callback`. It is essential that the canister not trap during execution
+ * of the cleanup callback. If the cleanup callback error reaches `handleUncaughtError` it means
+ * that the developer has not caught the error, and thus we return without trapping.
+ *
+ */
+export function handleUncaughtError(rawError: any): never | void {
+    const executingWithinCleanupCallback =
+        rawError.type === 'CleanupCallback' &&
+        rawError.rejectCode === 10_001 &&
+        rawError.rejectMessage === 'executing within cleanup callback';
+
+    if (executingWithinCleanupCallback === true) {
+        return;
+    }
+
+    if (rawError instanceof Error) {
+        const error = rawError;
+        trap(`Uncaught ${error.name}: ${error.message}\n${error.stack}`);
+    } else {
+        const error = new Error(rawError);
+        trap(`Uncaught: ${error.message}\n${error.stack}`);
+    }
+}
+
+export function validateUnsignedInteger(
+    errorPrefix: string,
+    size: number,
+    number: number
+): void {
+    if (number < 0) {
+        throw new Error(`${errorPrefix} cannot be negative`);
+    }
+
+    const maxUnsignedInteger = Math.pow(2, size) - 1;
+
+    if (number > maxUnsignedInteger) {
+        throw new Error(
+            `${errorPrefix} cannot be greater than ${maxUnsignedInteger} (2^${size} - 1)`
+        );
+    }
+}

package/src/stable/lib/execute_and_reply_with_candid_serde.ts

@@ -0,0 +1,245 @@
+import { IDL, JsonValue } from '@dfinity/candid';
+
+import { CanisterClassMeta } from './canister_methods';
+import { msgArgData } from './ic_apis/msg_arg_data';
+import { msgMethodName } from './ic_apis/msg_method_name';
+import { msgReply } from './ic_apis/msg_reply';
+
+/**
+ * Represents the different types of canister method execution modes.
+ */
+export type CanisterMethodMode =
+    | 'query' // Read-only operations
+    | 'update' // State-modifying operations
+    | 'init' // Canister initialization
+    | 'postUpgrade' // After canister upgrade
+    | 'preUpgrade' // Before canister upgrade
+    | 'inspectMessage' // Message inspection
+    | 'heartbeat' // Periodic heartbeat
+    | 'onLowWasmMemory'; // Low Wasm memory handler
+
+/**
+ * Executes a canister method with Candid serialization/deserialization handling.
+ * This function manages the full lifecycle of a canister method call:
+ * 1. Decodes the input arguments from Candid format
+ * 2. Executes the callback with decoded arguments
+ * 3. Encodes and replies with the result
+ *
+ * @param mode - The execution mode of the canister method
+ * @param args - Raw Candid-encoded input arguments as bytes
+ * @param callback - The actual method implementation to execute
+ * @param paramIdlTypes - Candid type definitions for the input parameters
+ * @param returnIdlType - Candid type definition for the return value
+ * @param manual - If true, skips automatic reply handling
+ */
+export async function executeAndReplyWithCandidSerde(
+    mode: CanisterMethodMode,
+    callback: (...args: any) => any,
+    paramIdlTypes: IDL.Type[],
+    returnIdlType: IDL.Type | undefined,
+    manual: boolean,
+    canisterMethodIdlParamTypes: CanisterClassMeta['canisterMethodIdlParamTypes']
+): Promise<void> {
+    const decodedArgs = decodeArgs(
+        mode,
+        manual,
+        paramIdlTypes,
+        canisterMethodIdlParamTypes
+    );
+
+    // JavaScript code execution: macrotask (if thought of in that way)
+    // This isn't strictly a macrotask because it is executing
+    // within the microtask drain loop, but we are treating it as a macrotask
+    // because from the point of view of the developer it behaves similarly.
+    // This is because we drain the microtasks queued because of this execution
+    // just after this execution, providing priority to its microtasks.
+    // Once its microtasks are drained, Azle's own microtasks will be drained to completion.
+    const unencodedResult = await getUnencodedResult(
+        mode,
+        manual,
+        decodedArgs,
+        callback
+    );
+
+    // We are treating the execution of the final JavaScript callback associated
+    // with the canister method as a macrotask, as described above.
+    // We have decided to drain the microtask queue here to
+    // ensure execution of all microtasks registered because of the macrotask execution above.
+    // This will ensure that all of these microtasks are executed before the final reply is sent.
+    // This call to drain the micotasks is happening within an outer microtask draining loop.
+    // This essentially gives priority to the microtasks that are registered
+    // because of the execution of the final JavaScript callback associated with the canister method.
+    if (globalThis._azleIc !== undefined) {
+        globalThis._azleIc.drainMicrotasks();
+    }
+
+    if (globalThis._azleIcExperimental !== undefined) {
+        globalThis._azleIcExperimental.drainMicrotasks();
+    }
+
+    encodeResultAndReply(mode, manual, unencodedResult, returnIdlType);
+}
+
+/**
+ * Decodes Candid-encoded arguments based on the method mode.
+ * Only decodes arguments for init, postUpgrade, query, and update methods.
+ *
+ * @param mode - The execution mode of the canister method
+ * @param args - Raw Candid-encoded input arguments
+ * @param paramIdlTypes - Candid type definitions for the parameters
+ * @returns Decoded argument values as a JSON-compatible array
+ */
+function decodeArgs(
+    mode: CanisterMethodMode,
+    manual: boolean,
+    paramIdlTypes: IDL.Type[],
+    canisterMethodIdlParamTypes: CanisterClassMeta['canisterMethodIdlParamTypes']
+): JsonValue[] {
+    if (manual === true) {
+        return [];
+    }
+
+    if (
+        mode === 'init' ||
+        mode === 'postUpgrade' ||
+        mode === 'query' ||
+        mode === 'update'
+    ) {
+        return idlDecode(paramIdlTypes, msgArgData());
+    }
+
+    if (mode === 'inspectMessage') {
+        const methodName = msgMethodName();
+
+        if (
+            methodName === '_azle_reject_callbacks_len' ||
+            methodName === '_azle_resolve_callbacks_len' ||
+            methodName === '_azle_timer_callbacks_len' ||
+            methodName === '_azle_actions_len' ||
+            methodName === '_azle_inter_canister_call_futures_len' ||
+            methodName === '_azle_is_job_queue_empty' ||
+            methodName === '_azle_heap_allocation'
+        ) {
+            return [];
+        }
+
+        const paramIdlTypes =
+            canisterMethodIdlParamTypes?.[methodName]?.argTypes;
+
+        if (paramIdlTypes === undefined) {
+            throw new Error(
+                `@inspectMessage could not find the IDL types for method ${methodName}`
+            );
+        }
+
+        return idlDecode(paramIdlTypes, msgArgData());
+    }
+
+    return [];
+}
+
+/**
+ * Executes the callback function with the decoded arguments.
+ *
+ * @param args - Decoded arguments to pass to the callback
+ * @param callback - The method implementation to execute
+ * @returns The result of the callback execution
+ */
+async function getUnencodedResult(
+    mode: CanisterMethodMode,
+    manual: boolean,
+    args: JsonValue[],
+    callback: (...args: any) => any
+): Promise<any> {
+    if (mode === 'inspectMessage') {
+        const result = await callback(
+            ...(manual === true ? [] : [msgMethodName(), ...args])
+        );
+
+        if (result === true) {
+            if (
+                globalThis._azleIc === undefined &&
+                globalThis._azleIcExperimental === undefined
+            ) {
+                throw new Error(
+                    'Neither globalThis._azleIc nor globalThis._azleIcExperimental are defined'
+                );
+            }
+
+            if (globalThis._azleIc !== undefined) {
+                globalThis._azleIc.acceptMessage();
+            }
+
+            if (globalThis._azleIcExperimental !== undefined) {
+                globalThis._azleIcExperimental.acceptMessage();
+            }
+        }
+    } else {
+        return await callback(...args);
+    }
+}
+
+/**
+ * Handles the encoding and reply of the method result.
+ * Only sends replies for query and update methods when manual mode is not enabled.
+ *
+ * @param mode - The execution mode of the canister method
+ * @param manual - If true, skips automatic reply handling
+ * @param unencodedResult - The raw result from the callback
+ * @param returnIdlType - Candid type definition for the return value
+ */
+function encodeResultAndReply(
+    mode: CanisterMethodMode,
+    manual: boolean,
+    unencodedResult: any,
+    returnIdlType: IDL.Type | undefined
+): void {
+    if ((mode !== 'query' && mode !== 'update') || manual === true) {
+        return;
+    }
+
+    const encodedResult = idlEncode(
+        [...(returnIdlType !== undefined ? [returnIdlType] : [])],
+        [...(unencodedResult !== undefined ? [unencodedResult] : [])]
+    );
+
+    msgReply(encodedResult);
+}
+
+/**
+ * Encodes JavaScript values into Candid format.
+ *
+ * @param argTypes - Candid type definitions for the values to encode
+ * @param args - Values to encode into Candid format
+ * @returns Candid-encoded data as bytes
+ * @throws {Error} If encoding fails
+ */
+export function idlEncode(
+    argTypes: Array<IDL.Type<any>>,
+    args: any[]
+): Uint8Array {
+    try {
+        return IDL.encode(argTypes, args);
+    } catch (error) {
+        throw new Error(`Failed to encode Candid arguments: ${error}`);
+    }
+}
+
+/**
+ * Decodes Candid-encoded data into JavaScript values.
+ *
+ * @param retTypes - Candid type definitions for the values to decode
+ * @param bytes - Candid-encoded data to decode
+ * @returns Decoded JavaScript values
+ * @throws {Error} If decoding fails
+ */
+export function idlDecode(
+    retTypes: IDL.Type[],
+    bytes: Uint8Array
+): JsonValue[] {
+    try {
+        return IDL.decode(retTypes, bytes);
+    } catch (error) {
+        throw new Error(`Failed to decode Candid bytes: ${error}`);
+    }
+}

package/src/stable/lib/func.ts

@@ -0,0 +1,7 @@
+import { GenericIdlFuncArgs, IDL } from '@dfinity/candid';
+
+export function toFuncArgs(types?: IDL.Type[]): GenericIdlFuncArgs {
+    if (types === undefined) return [];
+    if (Array.isArray(types)) return types as GenericIdlFuncArgs;
+    throw new Error('toFuncArgs expected IDL.Type[] or undefined');
+}

package/src/stable/lib/globals.ts

@@ -0,0 +1,250 @@
+import './state';
+
+// @ts-ignore
+import { TextDecoder, TextEncoder } from '@sinonjs/text-encoding';
+
+import { AzleIcExperimental } from '#experimental/lib/ic/azle_ic_experimental';
+
+import { CanisterClassMeta } from './canister_methods';
+import { AzleIc } from './ic_apis/azle_ic_stable';
+import { jsonReplacer } from './stable_structures/stable_json';
+import { Action } from './state';
+
+declare global {
+    var _azleActions: Action[] | undefined;
+    var _azleCanisterClassMeta: CanisterClassMeta | undefined;
+    var _azleCanisterMethodNames: { [key: string]: string } | undefined;
+    var _azleDispatch: ((action: Action) => void) | undefined;
+    var _azleExperimental: boolean | undefined;
+    var _azleIcExperimental: AzleIcExperimental | undefined;
+    var _azleIcpReplicaWasmEnvironment: boolean | undefined;
+    var _azleIc: AzleIc | undefined;
+    var _azleInitCalled: boolean | undefined;
+    var _azleNodejsWasmEnvironment: boolean | undefined;
+    var _azlePostUpgradeCalled: boolean | undefined;
+    var _azleRejectCallbacks:
+        | { [globalRejectId: string]: (err: any) => void }
+        | undefined;
+    var _azleResolveCallbacks:
+        | {
+              [globalResolveId: string]: (
+                  buf: Uint8Array | ArrayBuffer
+              ) => void;
+          }
+        | undefined;
+    var _azleTimerCallbacks:
+        | { [timerId: string]: () => Promise<void> }
+        | undefined;
+}
+
+// TODO do we need to disable any other wasmedge-quickjs globals
+// TODO that we don't think are stable yet?
+if (
+    globalThis._azleIcpReplicaWasmEnvironment === true ||
+    globalThis._azleNodejsWasmEnvironment === true
+) {
+    if (globalThis._azleDispatch === undefined) {
+        throw new Error('globalThis._azleDispatch is undefined');
+    }
+
+    globalThis._azleDispatch({
+        type: 'SET_TEXT_DECODER',
+        payload: TextDecoder,
+        location: {
+            filepath: 'azle/src/stable/lib/global.ts',
+            functionName: ''
+        }
+    });
+
+    globalThis._azleDispatch({
+        type: 'SET_TEXT_ENCODER',
+        payload: TextEncoder,
+        location: {
+            filepath: 'azle/src/stable/lib/global.ts',
+            functionName: ''
+        }
+    });
+
+    globalThis._azleDispatch({
+        type: 'SET_CRYPTO',
+        payload: {
+            ...globalThis.crypto,
+            getRandomValues: (array) => {
+                if (
+                    array instanceof Int8Array === false &&
+                    array instanceof Uint8Array === false &&
+                    array instanceof Uint8ClampedArray === false &&
+                    array instanceof Int16Array === false &&
+                    array instanceof Uint16Array === false &&
+                    array instanceof Int32Array === false &&
+                    array instanceof Uint32Array === false &&
+                    array instanceof BigInt64Array === false &&
+                    array instanceof BigUint64Array === false
+                ) {
+                    throw new TypeError(
+                        'Expected an Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, or BigUint64Array'
+                    );
+                }
+
+                const byteLength = array.byteLength;
+
+                if (byteLength === 0) {
+                    return array;
+                }
+
+                if (byteLength > 65_536) {
+                    throw new Error(
+                        `QuotaExceeded: array cannot be larger than 65_536 bytes`
+                    );
+                }
+
+                const bytes =
+                    globalThis._azleIc !== undefined
+                        ? globalThis._azleIc.randBytes(byteLength)
+                        : globalThis._azleIcExperimental !== undefined
+                          ? new Uint8Array(
+                                globalThis._azleIcExperimental.randBytes(
+                                    byteLength
+                                )
+                            )
+                          : ((): never => {
+                                throw new Error(
+                                    `Neither globalThis._azleIc nor globalThis._azleIcExperimental are defined`
+                                );
+                            })();
+
+                let targetView = new Uint8Array(
+                    array.buffer,
+                    array.byteOffset,
+                    byteLength
+                );
+
+                targetView.set(bytes);
+
+                return array;
+            }
+        },
+        location: {
+            filepath: 'azle/src/stable/lib/global.ts',
+            functionName: ''
+        }
+    });
+
+    globalThis._azleDispatch({
+        type: 'SET_CONSOLE',
+        payload: {
+            ...globalThis.console,
+            log,
+            error: log,
+            warn: log,
+            info: log
+        },
+        location: {
+            filepath: 'azle/src/stable/lib/global.ts',
+            functionName: ''
+        }
+    });
+
+    if (globalThis._azleExperimental === false) {
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'fetch',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'Buffer',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'window',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'global',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'self',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'URL',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'WebAssembly',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'setTimeout',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+
+        globalThis._azleDispatch({
+            type: 'SET_GLOBAL_EXPERIMENTAL_ERROR_PROPERTY',
+            payload: 'clearTimeout',
+            location: {
+                filepath: 'azle/src/stable/lib/global.ts',
+                functionName: ''
+            }
+        });
+    }
+}
+
+export function log(...args: any[]): void {
+    const jsonStringifiedArgs = args
+        .map((arg) => {
+            if (arg instanceof Error) {
+                return `${arg.name}: ${arg.message} at ${arg.stack}`;
+            } else {
+                return JSON.stringify(arg, jsonReplacer, 4);
+            }
+        })
+        .join(' ');
+
+    if (globalThis._azleIc !== undefined) {
+        return globalThis._azleIc.debugPrint(jsonStringifiedArgs);
+    } else if (globalThis._azleIcExperimental !== undefined) {
+        return globalThis._azleIcExperimental.debugPrint(jsonStringifiedArgs);
+    }
+
+    throw new Error(`No global debugPrint implementation found`);
+}