node-opcua-address-space 2.180.0 → 2.181.0

package/impl/ua_method_impl.ts

@@ -0,0 +1,364 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import { callbackify } from "node:util";
+import chalk from "chalk";
+import {
+    type CloneExtraInfo,
+    type CloneFilter,
+    type CloneOptions,
+    defaultCloneFilter,
+    type ISessionContext,
+    type MethodFunctor,
+    type MethodFunctorA,
+    type MethodFunctorC,
+    makeDefaultCloneExtraInfo,
+    type UAMethod,
+    type UAMethodEvents,
+    type UAObject,
+    type UAObjectType,
+    type UAVariable
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { AttributeIds, type DiagnosticInfo, NodeClass, type QualifiedNameLike } from "node-opcua-data-model";
+import { DataValue, type DataValueLike } from "node-opcua-data-value";
+import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
+import type { NodeId } from "node-opcua-nodeid";
+import type { NumericRange } from "node-opcua-numeric-range";
+import { Argument } from "node-opcua-service-call";
+import { type CallbackT, type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { type CallMethodResultOptions, PermissionType } from "node-opcua-types";
+import { DataType, Variant, type VariantLike } from "node-opcua-variant";
+import type { SessionContext } from "../api/session_context.js";
+import type { AddressSpacePrivate } from "./address_space_private.js";
+import { BaseNodeImpl, type InternalBaseNodeOptions } from "./base_node_impl.js";
+import { _clone } from "./base_node_private.js";
+import { _handle_hierarchy_parent } from "./handle_hierarchy_parent.js";
+
+const warningLog = make_warningLog("ua_method_impl");
+const debugLog = make_debugLog("ua_method_impl");
+const doDebug = checkDebugFlag("ua_method_impl");
+const errorLog = make_errorLog("ua_method_impl");
+
+function default_check_valid_argument(arg: unknown): boolean {
+    return (arg as object) instanceof Argument;
+}
+
+export interface IMethodOptons extends InternalBaseNodeOptions {
+    value: unknown;
+    methodDeclarationId: NodeId;
+}
+export class UAMethodImpl extends BaseNodeImpl<UAMethodEvents> implements UAMethod {
+    public static checkValidArgument(args: unknown): boolean {
+        return default_check_valid_argument(args);
+    }
+
+    public readonly nodeClass = NodeClass.Method;
+
+    public get typeDefinitionObj(): UAObjectType {
+        return super.typeDefinitionObj as UAObjectType;
+    }
+
+    public get parent(): UAObject | null {
+        return super.parent as UAObject;
+    }
+
+    public declare value?: unknown;
+    public methodDeclarationId: NodeId;
+    public _getExecutableFlag?: (this: UAMethod, context: ISessionContext | null) => boolean;
+
+    public _asyncExecutionFunction?: MethodFunctor;
+
+    constructor(options: IMethodOptons) {
+        super(options);
+        if (options.value !== undefined) {
+            this.value = options.value;
+        }
+        this.methodDeclarationId = options.methodDeclarationId;
+    }
+
+    /**
+     *
+     *
+     */
+    public getExecutableFlag(context: ISessionContext | null): boolean {
+        if (!this.isBound()) {
+            return false;
+        }
+        if (this._getExecutableFlag) {
+            return this._getExecutableFlag(context);
+        }
+        return true;
+    }
+    public getUserExecutableFlag(context: ISessionContext | null): boolean {
+        if (context && !context.checkPermission(this, PermissionType.Call)) {
+            return false;
+        }
+        if (!this.getExecutableFlag(context)) return false;
+        return true;
+    }
+    /**
+     *
+     * @returns  true if the method is bound
+     */
+    public isBound(): boolean {
+        return typeof this._asyncExecutionFunction === "function";
+    }
+
+    public readAttribute(
+        context: ISessionContext | null,
+        attributeId: AttributeIds,
+        indexRange?: NumericRange,
+        dataEncoding?: QualifiedNameLike | null
+    ): DataValue {
+        const options: DataValueLike = {};
+        switch (attributeId) {
+            case AttributeIds.Executable:
+                options.value = { dataType: DataType.Boolean, value: this.getExecutableFlag(context) };
+                options.statusCode = StatusCodes.Good;
+                break;
+            case AttributeIds.UserExecutable:
+                options.value = { dataType: DataType.Boolean, value: this.getUserExecutableFlag(context) };
+                options.statusCode = StatusCodes.Good;
+                break;
+            default:
+                return BaseNodeImpl.prototype.readAttribute.call(this, context, attributeId, indexRange, dataEncoding);
+        }
+        return new DataValue(options);
+    }
+
+    public getInputArguments(): Argument[] {
+        return this._getArguments("InputArguments");
+    }
+
+    public getOutputArguments(): Argument[] {
+        return this._getArguments("OutputArguments");
+    }
+
+    public bindMethod(async_func: MethodFunctor): void {
+        assert(typeof async_func === "function");
+        if (async_func.length === 2) {
+            async_func = callbackify(async_func as MethodFunctorA) as MethodFunctorC;
+        }
+        assert(async_func.length === 3, ` a method with callback should have 3 arguments : got ${async_func.length}`);
+        this._asyncExecutionFunction = async_func;
+    }
+    public execute(
+        object: UAObject | UAObjectType | null,
+        inputArguments: null | VariantLike[],
+        context: SessionContext
+    ): Promise<CallMethodResultOptions>;
+    public execute(
+        object: UAObject | UAObjectType | null,
+        inputArguments: null | VariantLike[],
+        context: ISessionContext,
+        callback: CallbackT<CallMethodResultOptions>
+    ): void;
+    public execute(
+        object: UAObject | UAObjectType | null,
+        inputArguments: VariantLike[] | null,
+        context: ISessionContext,
+        callback?: CallbackT<CallMethodResultOptions>
+    ): Promise<CallMethodResultOptions> | undefined {
+        // c8 ignore next
+        if (!callback) {
+            throw new Error("execute need to be promisified");
+        }
+        assert(inputArguments === null || Array.isArray(inputArguments));
+        inputArguments = inputArguments || [];
+        inputArguments = inputArguments.map(Variant.coerce);
+        assert(inputArguments.length === 0 || inputArguments[0] instanceof Variant);
+        assert(context !== null && typeof context === "object");
+        assert(typeof callback === "function");
+
+        object = object || (this.parent as UAObject);
+
+        // c8 ignore next
+        if (!object) {
+            errorLog("UAMethod#execute expects a valid object");
+            callback(null, { statusCode: StatusCodes.BadInternalError });
+            return;
+        }
+
+        if (object.nodeClass !== NodeClass.Object && object.nodeClass !== NodeClass.ObjectType) {
+            warningLog(
+                "Method " +
+                    this.nodeId.toString() +
+                    " " +
+                    this.browseName.toString() +
+                    " called for a node that is not a Object/ObjectType but " +
+                    NodeClass[context.object?.nodeClass as number]
+            );
+            callback(null, { statusCode: StatusCodes.BadNodeIdInvalid });
+            return;
+        }
+        if (!this._asyncExecutionFunction) {
+            warningLog(`Method ${this.nodeId.toString()} ${this.browseName.toString()} has not been bound`);
+            callback(null, { statusCode: StatusCodes.BadInternalError });
+            return;
+        }
+
+        if (!this.getExecutableFlag(context)) {
+            warningLog(`Method ${this.nodeId.toString()} ${this.browseName.toString()} is not executable`);
+            callback(null, { statusCode: StatusCodes.BadNotExecutable });
+            return;
+        }
+
+        if (context.isAccessRestricted(this)) {
+            callback(null, { statusCode: StatusCodes.BadSecurityModeInsufficient });
+            return;
+        }
+
+        if (!context.checkPermission(this, PermissionType.Call)) {
+            callback(null, { statusCode: StatusCodes.BadUserAccessDenied });
+            return;
+        }
+
+        // verify that input arguments are correct
+        // todo :
+        const inputArgumentDiagnosticInfos: DiagnosticInfo[] = [];
+
+        context.object = object;
+
+        // ── method call interceptors ──
+        const addressSpace = this.addressSpace as AddressSpacePrivate;
+        const interceptors = addressSpace._methodCallInterceptors;
+
+        const coercedInputArguments = inputArguments as Variant[];
+        const callObject = object;
+
+        const runInterceptorsAndExecute = async () => {
+            // Run interceptors sequentially
+            for (const interceptor of interceptors) {
+                let status: StatusCode;
+                try {
+                    status = await interceptor(context, callObject, this, coercedInputArguments);
+                } catch (err) {
+                    if (err instanceof Error) {
+                        warningLog(chalk.red("ERR in method interceptor"), err.message);
+                    }
+                    const callMethodResponse = { statusCode: StatusCodes.BadInternalError };
+                    callback?.(err as Error, callMethodResponse);
+                    return;
+                }
+                if (status !== StatusCodes.Good) {
+                    const callMethodResult: CallMethodResultOptions = {
+                        statusCode: status,
+                        outputArguments: [],
+                        inputArgumentResults: coercedInputArguments?.map(() => status) || [],
+                        inputArgumentDiagnosticInfos
+                    };
+                    callback?.(null, callMethodResult);
+                    return;
+                }
+            }
+
+            // All interceptors passed — execute the method body
+            try {
+                this._asyncExecutionFunction?.call(
+                    this as UAMethodImpl,
+                    coercedInputArguments,
+                    context,
+                    (err: Error | null, callMethodResult?: CallMethodResultOptions) => {
+                        if (err) {
+                            // c8 ignore next
+                            if (doDebug) {
+                                debugLog(err.message);
+                                debugLog(err);
+                            }
+                        }
+                        callMethodResult = callMethodResult || {};
+
+                        callMethodResult.statusCode = callMethodResult.statusCode || StatusCodes.Good;
+                        callMethodResult.outputArguments = callMethodResult.outputArguments || [];
+
+                        callMethodResult.inputArgumentResults =
+                            callMethodResult.inputArgumentResults?.length === coercedInputArguments?.length
+                                ? callMethodResult.inputArgumentResults
+                                : coercedInputArguments?.map(() => StatusCodes.Good);
+                        callMethodResult.inputArgumentDiagnosticInfos =
+                            callMethodResult.inputArgumentDiagnosticInfos || inputArgumentDiagnosticInfos;
+
+                        // ── afterCall event ──
+                        try {
+                            (this as UAMethod).emit("afterCall", context, coercedInputArguments, callMethodResult);
+                        } catch (afterCallErr) {
+                            if (afterCallErr instanceof Error) {
+                                warningLog(chalk.red("ERR in afterCall listener"), afterCallErr.message);
+                            }
+                        }
+
+                        callback?.(err, callMethodResult);
+                    }
+                );
+            } catch (err) {
+                if (err instanceof Error) {
+                    warningLog(chalk.red("ERR in method  handler"), err.message);
+                    warningLog(err.stack);
+                }
+                const callMethodResponse = { statusCode: StatusCodes.BadInternalError };
+                callback?.(err as Error, callMethodResponse);
+            }
+        };
+
+        runInterceptorsAndExecute().catch((err) => {
+            if (err instanceof Error) {
+                warningLog(chalk.red("ERR in method interceptor"), err.message);
+            }
+            const callMethodResponse = { statusCode: StatusCodes.BadInternalError };
+            callback?.(err as Error, callMethodResponse);
+        });
+        return undefined;
+    }
+
+    public clone(options: CloneOptions, optionalFilter?: CloneFilter, extraInfo?: CloneExtraInfo): UAMethod {
+        assert(!options.componentOf || options.componentOf, "trying to create an orphan method ?");
+
+        const addressSpace = this.addressSpace as AddressSpacePrivate;
+        options = {
+            ...options,
+            methodDeclarationId: this.nodeId
+        };
+        options.references = options.references || [];
+
+        _handle_hierarchy_parent(addressSpace, options.references, options);
+
+        if (!extraInfo) {
+            extraInfo = makeDefaultCloneExtraInfo(this);
+        }
+        const clonedMethod = _clone(this, UAMethodImpl, options, optionalFilter || defaultCloneFilter, extraInfo) as UAMethodImpl;
+
+        clonedMethod._asyncExecutionFunction = this._asyncExecutionFunction;
+        clonedMethod._getExecutableFlag = this._getExecutableFlag;
+
+        if (options.componentOf) {
+            const m = options.componentOf.getMethodByName(clonedMethod.browseName.name || "");
+            assert(m);
+        }
+        return clonedMethod as UAMethod;
+    }
+
+    private _getArguments(name: string): Argument[] {
+        assert(name === "InputArguments" || name === "OutputArguments");
+        const argsVariable = this.getPropertyByName(name);
+        if (!argsVariable) {
+            return [];
+        }
+
+        assert(argsVariable.nodeClass === NodeClass.Variable);
+
+        const args = (argsVariable as UAVariable).readValue().value.value;
+        if (!args) {
+            return [];
+        }
+        // a list of extension object
+        assert(Array.isArray(args));
+        assert(args.length === 0 || UAMethodImpl.checkValidArgument(args[0]));
+        return args;
+    }
+}
+
+import { withCallback } from "thenify-ex";
+
+UAMethodImpl.prototype.execute = withCallback(UAMethodImpl.prototype.execute);

package/impl/ua_object_impl.ts

@@ -0,0 +1,278 @@
+/**
+ * @module node-opcua-address-space
+ */
+
+import chalk from "chalk";
+import {
+    type BaseNode,
+    type CloneExtraInfo,
+    type CloneFilter,
+    type CloneOptions,
+    defaultCloneFilter,
+    EventNotifierFlags,
+    type EventTypeLike,
+    type IEventData,
+    type ISessionContext,
+    type ListenerSignature,
+    makeDefaultCloneExtraInfo,
+    type RaiseEventData,
+    type UAEventType,
+    type UAMethod,
+    type UAObject,
+    type UAObjectEvents,
+    type UAObjectType
+} from "node-opcua-address-space-base";
+import { assert } from "node-opcua-assert";
+import { isValidByte } from "node-opcua-basic-types";
+import { AttributeIds, NodeClass, type QualifiedNameLike, type QualifiedNameOptions } from "node-opcua-data-model";
+import { DataValue, type DataValueLike } from "node-opcua-data-value";
+import { getCurrentClock } from "node-opcua-date-time";
+import { make_errorLog } from "node-opcua-debug";
+import { NodeId } from "node-opcua-nodeid";
+import type { NumericRange } from "node-opcua-numeric-range";
+import { StatusCodes } from "node-opcua-status-code";
+import { DataType } from "node-opcua-variant";
+import { apply_condition_refresh, type ConditionRefreshCache } from "./apply_condition_refresh.js";
+import { BaseNodeImpl, type InternalBaseNodeOptions } from "./base_node_impl.js";
+import { _clone, ToStringBuilder, UAObject_toString } from "./base_node_private.js";
+
+const errorLog = make_errorLog("ua_object_impl");
+
+export class UAObjectImpl<T extends UAObjectEvents & ListenerSignature<T> = UAObjectEvents>
+    extends BaseNodeImpl<T>
+    implements UAObject<T>
+{
+    private _eventNotifier: EventNotifierFlags;
+    public readonly nodeClass = NodeClass.Object;
+    public get eventNotifier(): EventNotifierFlags {
+        // ensure eventNotifier is set if the node has some event
+
+        if (!this._eventNotifier) {
+            // const s = this.getEventSources();
+            const s = this.getEventSources();
+            const n = this.getNotifiers();
+            if (s.length > 0 || n.length > 0) {
+                this._eventNotifier = this._eventNotifier | EventNotifierFlags.SubscribeToEvents;
+            }
+        }
+
+        return this._eventNotifier;
+    }
+    public readonly symbolicName: string | null;
+
+    get typeDefinitionObj(): UAObjectType {
+        // c8 ignore next
+        if (super.typeDefinitionObj.nodeClass !== NodeClass.ObjectType) {
+            const msg = `Invalid type definition node class , expecting a ObjectType got ${
+                NodeClass[super.typeDefinitionObj.nodeClass]
+            }\n${this.browseName.toString()} ${this.nodeId.toString()}`;
+            errorLog(msg);
+            throw new Error(msg);
+        }
+        return super.typeDefinitionObj as UAObjectType;
+    }
+
+    constructor(options: InternalBaseNodeOptions & { eventNotifier?: number; symbolicName?: string | null }) {
+        super(options);
+        this._eventNotifier = options.eventNotifier || EventNotifierFlags.None;
+        assert(typeof this.eventNotifier === "number" && isValidByte(this.eventNotifier));
+        this.symbolicName = options.symbolicName || null;
+    }
+
+    public readAttribute(
+        context: ISessionContext | null,
+        attributeId: AttributeIds,
+        indexRange?: NumericRange,
+        dataEncoding?: QualifiedNameLike | null
+    ): DataValue {
+        indexRange;
+        dataEncoding;
+        const now = getCurrentClock();
+        const options: DataValueLike = {};
+        switch (attributeId) {
+            case AttributeIds.EventNotifier:
+                assert(isValidByte(this.eventNotifier));
+                options.value = { dataType: DataType.Byte, value: this.eventNotifier };
+                options.serverTimestamp = now.timestamp;
+                options.serverPicoseconds = now.picoseconds;
+                options.statusCode = StatusCodes.Good;
+                break;
+            default:
+                return BaseNodeImpl.prototype.readAttribute.call(this, context, attributeId, indexRange, dataEncoding);
+        }
+        return new DataValue(options);
+    }
+
+    public clone(options: CloneOptions, optionalFilter?: CloneFilter, extraInfo?: CloneExtraInfo): UAObject {
+        options = {
+            eventNotifier: this.eventNotifier,
+            symbolicName: this.symbolicName || undefined,
+            ...options
+        };
+
+        const cloneObject = _clone(
+            this,
+            UAObjectImpl<T>,
+            options,
+            optionalFilter || defaultCloneFilter,
+            extraInfo || makeDefaultCloneExtraInfo(this)
+        ) as UAObject;
+        // xx  newObject.propagate_back_references();
+        // xx newObject.install_extra_properties();
+        return cloneObject;
+    }
+
+    /**
+     * returns true if the object has some opcua methods
+     */
+    public get hasMethods(): boolean {
+        return this.getMethods().length > 0;
+    }
+
+    public getMethodByName(methodName: QualifiedNameOptions): UAMethod | null;
+    public getMethodByName(methodName: string, namespaceIndex?: number): UAMethod | null;
+    public getMethodByName(methodName: QualifiedNameLike, namespaceIndex?: number): UAMethod | null {
+        return super.getMethodByName(methodName as string, namespaceIndex);
+    }
+
+    public getMethods(): UAMethod[] {
+        return super.getMethods();
+    }
+
+    public setEventNotifier(eventNotifierFlags: EventNotifierFlags): void {
+        this._eventNotifier = eventNotifierFlags;
+    }
+
+    /**
+     * Raise a transient Event
+     */
+    public raiseEvent(eventType: EventTypeLike | BaseNode, data: RaiseEventData): void {
+        const addressSpace = this.addressSpace;
+
+        if (typeof eventType === "string") {
+            const eventTypeFound = addressSpace.findEventType(eventType);
+            if (!eventTypeFound) {
+                throw new Error(`raiseEvent: eventType cannot find event Type ${eventType.toString()}`);
+            }
+            eventType = eventTypeFound;
+            if (!eventType || eventType.nodeClass !== NodeClass.ObjectType) {
+                throw new Error("eventType must exist and be an UAObjectType");
+            }
+        } else if (eventType instanceof NodeId) {
+            const eventTypeFound = addressSpace.findNode(eventType) as BaseNode;
+            if (!eventTypeFound) {
+                throw new Error(`raiseEvent: eventType cannot find event Type ${eventType.toString()}`);
+            }
+            eventType = eventTypeFound;
+            if (!eventType || eventType.nodeClass !== NodeClass.ObjectType) {
+                throw new Error(`eventType must exist and be an UAObjectType: ${eventType.toString()}`);
+            }
+        }
+
+        eventType = eventType as UAEventType;
+
+        let eventTypeNode: UAEventType = eventType as UAEventType;
+        // c8 ignore next
+        if (!eventTypeNode) {
+            throw new Error(`UAObject#raiseEventType : Cannot find event type : ${eventType.toString()}`);
+        }
+
+        // coerce EventType
+        eventTypeNode = addressSpace.findEventType(eventType as UAEventType) as UAEventType;
+        const _baseEventType = addressSpace.findEventType("BaseEventType");
+
+        data.$eventDataSource = eventTypeNode;
+        data.sourceNode = data.sourceNode || { dataType: DataType.NodeId, value: this.nodeId };
+
+        const eventData1 = addressSpace.constructEventData(eventTypeNode, data);
+
+        this._bubble_up_event(eventData1);
+    }
+
+    public _bubble_up_event(eventData: IEventData): void {
+        const addressSpace = this.addressSpace;
+
+        const queue: BaseNode[] = [];
+        // walk up the hasNotify / hasEventSource chain
+        const m: Record<string, BaseNode> = {};
+
+        // all events are notified to the server object
+        // emit on server object
+        const server = addressSpace.findNode("Server") as UAObject;
+
+        if (server) {
+            assert(server.eventNotifier > 0x00, "Server must be an event notifier");
+            server.emit("event", eventData);
+            m[server.nodeId.toString()] = server;
+        } else {
+            errorLog(
+                chalk.yellow("Warning. ") +
+                    chalk.cyan("UAObject#raiseEvent") +
+                    chalk.red(" cannot find Server object on addressSpace")
+            );
+        }
+
+        addInQueue(this);
+
+        function addInQueue(obj: BaseNode) {
+            const key: string = obj.nodeId.toString();
+            if (!m[key]) {
+                m[key] = obj;
+                queue.push(obj);
+            }
+        }
+
+        while (queue.length) {
+            const obj = queue.pop();
+            if (!obj) {
+                continue;
+            }
+            // emit on object
+            obj.emit("event", eventData);
+
+            const elements1 = obj.findReferencesAsObject("HasNotifier", false);
+            elements1.forEach(addInQueue);
+
+            const elements2 = obj.findReferencesAsObject("HasEventSource", false);
+            elements2.forEach(addInQueue);
+        }
+    }
+    public _conditionRefresh(_cache?: ConditionRefreshCache): void {
+        apply_condition_refresh.call(this, _cache);
+    }
+
+    public toString(): string {
+        const options = new ToStringBuilder();
+        UAObject_toString.call(this, options);
+        return options.toString();
+    }
+
+    public toJSON(): Record<string, unknown> {
+        return {
+            ...super.toJSON(),
+            typeDefinition: this.typeDefinitionObj ? this.typeDefinitionObj.browseName.toString() : undefined,
+            eventNotifier: this._eventNotifier
+        };
+    }
+
+    public [Symbol.for("nodejs.util.inspect.custom")](depth: number | null, inspectOptions: { colors?: boolean }): string {
+        const c = inspectOptions?.colors === false ? plainChalk : chalk;
+        const typeName = this.typeDefinitionObj?.browseName.toString() ?? "?";
+        const displayName = this.displayName.length ? this.displayName.map((d) => d.text).join(" | ") : "";
+        if (depth !== null && depth <= 0) {
+            return `${c.cyan("UAObject<")}${c.green(this.browseName.toString())}${c.grey(` ${this.nodeId.toString()}`)}${c.cyan(">")}`;
+        }
+        const lines = [
+            `${c.cyan("UAObject ")}${c.green(this.browseName.toString())}${c.grey(` ${this.nodeId.toString()}`)}`,
+            c.yellow("  typeDefinition : ") + typeName,
+            c.yellow("  displayName    : ") + displayName,
+            c.yellow("  eventNotifier  : ") + this._eventNotifier
+        ];
+        if (this.description?.text) {
+            lines.push(c.yellow("  description    : ") + this.description.text);
+        }
+        return lines.join("\n");
+    }
+}
+
+const plainChalk = new Proxy(chalk, { get: () => (s: string) => s }) as typeof chalk;