node-opcua-address-space 2.51.0

package/source/helpers/dump_tools.ts

@@ -0,0 +1,92 @@
+/**
+ * @module node-opcua-address-space
+ */
+// tslint:disable:no-console
+import * as chalk from "chalk";
+
+import { assert } from "node-opcua-assert";
+import { BrowseDirection } from "node-opcua-data-model";
+import { NodeId, NodeIdLike } from "node-opcua-nodeid";
+import { BrowseDescription, BrowseDescriptionOptions, ReferenceDescription } from "node-opcua-types";
+
+import { IAddressSpace, BaseNode, UAReference, UAReferenceType as UAReferenceTypePublic } from "node-opcua-address-space-base";
+
+import { resolveReferenceType } from "../../src/reference_impl";
+
+export function referenceTypeToString(addressSpace: IAddressSpace, referenceTypeId: NodeIdLike | null): string {
+    // istanbul ignore next
+    if (!referenceTypeId) {
+        return "<null> ";
+    } else {
+        const referenceType = addressSpace.findNode(referenceTypeId)! as UAReferenceTypePublic;
+        return referenceTypeId.toString() + " " + referenceType.browseName.toString() + "/" + referenceType.inverseName!.text;
+    }
+}
+
+function nodeIdInfo(addressSpace: IAddressSpace, nodeId: NodeId): string {
+    const obj = addressSpace.findNode(nodeId);
+    const name = obj ? obj.browseName.toString() : " <????>";
+    return nodeId.toString() + " [ " + name + " ]";
+}
+
+export function dumpReferenceDescription(addressSpace: IAddressSpace, referenceDescription: ReferenceDescription): void {
+    assert(referenceDescription.referenceTypeId); // must be known;
+
+    console.log(chalk.red("referenceDescription"));
+    console.log("    referenceTypeId : ", referenceTypeToString(addressSpace, referenceDescription.referenceTypeId));
+    console.log("    isForward       : ", referenceDescription.isForward ? "true" : "false");
+    console.log("    nodeId          : ", nodeIdInfo(addressSpace, referenceDescription.nodeId));
+    console.log("    browseName      : ", referenceDescription.browseName.toString());
+    console.log("    nodeClass       : ", referenceDescription.nodeClass.toString());
+    console.log("    typeDefinition  : ", nodeIdInfo(addressSpace, referenceDescription.typeDefinition));
+}
+
+export function dumpReferenceDescriptions(addressSpace: IAddressSpace, referenceDescriptions: ReferenceDescription[]): void {
+    referenceDescriptions.forEach((r: ReferenceDescription) => dumpReferenceDescription(addressSpace, r));
+}
+
+export function dumpBrowseDescription(node: BaseNode, _browseDescription: BrowseDescriptionOptions): void {
+    const browseDescription = new BrowseDescription(_browseDescription);
+
+    const addressSpace = node.addressSpace;
+
+    console.log(" Browse Node :");
+
+    if (browseDescription.nodeId) {
+        console.log(" nodeId : ", chalk.cyan(browseDescription.nodeId.toString()));
+    }
+
+    console.log(" nodeId : ", chalk.cyan(node.browseName.toString()), "(", node.nodeId.toString(), ")");
+    console.log("   referenceTypeId :", referenceTypeToString(addressSpace, browseDescription.referenceTypeId));
+
+    console.log("   browseDirection :", chalk.cyan(BrowseDirection[browseDescription.browseDirection]));
+    console.log("   includeSubType  :", browseDescription.includeSubtypes ? "true" : "false");
+    console.log("   nodeClassMask   :", browseDescription.nodeClassMask);
+    console.log("   resultMask      :", browseDescription.resultMask);
+}
+
+/**
+ * @method dumpReferences
+ * @param addressSpace    {IAddressSpace}
+ * @param references  {Array<Reference>|null}
+ * @static
+ */
+export function dumpReferences(addressSpace: IAddressSpace, references: UAReference[]): void {
+    assert(addressSpace);
+    for (const reference of references) {
+        const referenceType = resolveReferenceType(addressSpace, reference);
+        if (!referenceType) {
+            // unknown type ... this may happen when the address space is not fully build
+            return;
+        }
+        const dir = reference.isForward ? "(=>)" : "(<-)";
+        const objectName = nodeIdInfo(addressSpace, reference.nodeId);
+        console.log(
+            " referenceType : ",
+            dir,
+            referenceType ? referenceType.browseName.toString() : reference.referenceType.toString(),
+            " ",
+            objectName
+        );
+    }
+}

package/source/helpers/ensure_secure_access.ts

@@ -0,0 +1,88 @@
+import { allPermissions, BrowseDirection, makeAccessRestrictionsFlag, makePermissionFlag, NodeClass } from "node-opcua-data-model";
+import { MessageSecurityMode } from "node-opcua-types";
+import { BaseNode, UAVariable, UAMethod, UAObject, ISessionContext, IChannelBase } from "node-opcua-address-space-base";
+import { WellKnownRoles } from "../session_context";
+
+function isChannelSecure(channel: IChannelBase): boolean {
+    if (channel.securityMode === MessageSecurityMode.SignAndEncrypt) {
+        return true;
+    }
+    return false;
+}
+
+function newIsUserReadable(this: BaseNode, context: ISessionContext): boolean {
+    if (context) {
+        if (!context.session) {
+            // console.log(" context has no session", context);
+            return false;
+        }
+        if (!context.session.channel) {
+            // console.log(" context has no channel", context);
+            return false;
+        }
+        if (!isChannelSecure(context.session.channel)) {
+            return false;
+        }
+        return true;
+    }
+    return false;
+}
+function replaceMethod(obj: any, method: string, func: any) {
+    const oldMethod = obj[method];
+    if (!oldMethod) {
+        throw new Error("I cannot find method " + method + " on object " + obj.browseName.toString());
+    }
+    obj[method] = function (this: any, ...args: any[]) {
+        const ret = func.apply(this, args);
+        if (!ret) {
+            return false;
+        }
+        return oldMethod.apply(this, args);
+    };
+}
+/**
+ * make sure that the given ia node can only be read
+ * by Administrator user on a encrypted channel
+ * @param node
+
+*/
+const restrictedPermissions = [
+    { roleId: WellKnownRoles.SecurityAdmin, permissions: allPermissions },
+    { roleId: WellKnownRoles.ConfigureAdmin, permissions: allPermissions },
+    { roleId: WellKnownRoles.Supervisor, permissions: allPermissions },
+    { roleId: WellKnownRoles.Operator, permissions: makePermissionFlag("Browse") },
+    { roleId: WellKnownRoles.Engineer, permissions: makePermissionFlag("Browse") },
+    { roleId: WellKnownRoles.Observer, permissions: makePermissionFlag("Browse") }
+    /*
+    { roleId: WellKnownRoles.Anonymous, permissions: makePermissionFlag("Browse") },
+    { roleId: WellKnownRoles.AuthenticatedUser, permissions: makePermissionFlag("Browse") },
+*/
+];
+const restrictedAccessFlag = makeAccessRestrictionsFlag("SigningRequired | EncryptionRequired");
+/**
+ * this method install the access right restriction on the given node and its children
+ * values will only be available to user with role Administrator or supervisor and
+ * with a signed and encrypted channel.
+ *
+ * @param node the node which permissions are to be adjusted
+ */
+export function ensureObjectIsSecure(node: BaseNode): void {
+    node.setAccessRestrictions(restrictedAccessFlag);
+    if (node.nodeClass === NodeClass.Variable) {
+        // replaceMethod(node, "isUserReadable", newIsUserReadable);
+        const variable = node as UAVariable;
+        variable.setRolePermissions(restrictedPermissions);
+    }
+    if (node.nodeClass === NodeClass.Method) {
+        const method = node as UAMethod;
+        method.setRolePermissions(restrictedPermissions);
+    }
+    if (node.nodeClass === NodeClass.Object) {
+        const object = node as UAObject;
+        object.setRolePermissions(restrictedPermissions);
+    }
+    const children = node.findReferencesExAsObject("Aggregates", BrowseDirection.Forward);
+    for (const child of children) {
+        ensureObjectIsSecure(child);
+    }
+}

package/source/helpers/make_optionals_map.ts

@@ -0,0 +1,49 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { assert } from "node-opcua-assert";
+
+/**
+ * transform  optional into a map
+ *
+ * @example
+ * ```javascript
+ * const optionals = [ "A", "B", "C.D" ];
+ *
+ * const map = makeOptionalsMap(optionals);
+ * const map = {
+ *   A: {}
+ *   B: {}
+ *   C: {  D: {} }
+ * };
+ * ```
+ *
+ * @internal
+ */
+export interface OptionalMap {
+    [key: string]: OptionalMap;
+}
+export function makeOptionalsMap(optionals?: string[] | null): OptionalMap {
+    const resultMap: OptionalMap = {};
+    if (!optionals) {
+        return resultMap;
+    }
+    assert(optionals instanceof Array);
+
+    function insertInMap(map: OptionalMap, s: string[]): void {
+        const key = s[0];
+
+        if (!map[key]) {
+            map[key] = {};
+        }
+        if (s.length > 1) {
+            insertInMap(map[key], s.splice(1));
+        }
+    }
+
+    for (const opt of optionals) {
+        const s: string[] = opt.split(".");
+        insertInMap(resultMap, s);
+    }
+    return resultMap;
+}

package/source/helpers/resolve_opaque_on_address_space.ts

@@ -0,0 +1,23 @@
+import { resolveDynamicExtensionObject } from "node-opcua-client-dynamic-extension-object";
+import { Variant } from "node-opcua-variant";
+import { IAddressSpace } from "node-opcua-address-space-base";
+import { PseudoSession } from "../pseudo_session";
+import { ensureDatatypeExtracted } from "../loader/load_nodeset2";
+
+export async function resolveOpaqueOnAddressSpace(addressSpace: IAddressSpace, variants: (Variant | null) | (Variant | null)[]): Promise<void> {
+    if (!variants) {
+        return;
+    }
+    const session = new PseudoSession(addressSpace);
+    const extraDataTypeManager = await ensureDatatypeExtracted(addressSpace);
+    if (variants instanceof Variant) {
+        await resolveDynamicExtensionObject(session, variants, extraDataTypeManager);
+        return;
+    }
+    // resolve opaque data structure from inputArguments
+    for (const variant of variants) {
+        if (variant) {
+            await resolveDynamicExtensionObject(session, variant, extraDataTypeManager);
+        }
+    }
+}

package/source/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @module node-opcua-address-space
+ */
+export * from "./address_space_ts";
+
+export * from "./interfaces/state_machine/ua_state_machine_type";
+export * from "./interfaces/state_machine/ua_exclusive_limit_state_machine_type_ex";
+export * from "./interfaces/state_machine/ua_finite_state_machine_type";
+export * from "./interfaces/state_machine/ua_program_state_machine_type";
+export * from "./interfaces/state_machine/ua_transition_ex";
+
+export * from "./interfaces/ua_subscription_diagnostics_variable_ex";
+
+export * from "./interfaces/data_access/ua_multistate_discrete_ex";
+export * from "./interfaces/data_access/ua_multistate_value_discrete_ex";
+export * from "./interfaces/data_access/ua_two_state_discrete_ex";
+export * from "./interfaces/data_access/ua_y_array_item_ex";
+
+export { promoteToMultiStateDiscrete } from "../src/data_access/ua_multistate_discrete_impl";
+export { promoteToMultiStateValueDiscrete } from "../src/data_access/ua_multistate_value_discrete";
+export { promoteToTwoStateDiscrete } from "../src/data_access/ua_two_state_discrete";
+
+export * from "../source/ua_root_folder";
+export * from "./session_context";
+export * from "./pseudo_session";
+
+export * from "./helpers/dump_tools";
+export * from "./helpers/make_optionals_map";
+export * from "./helpers/check_event_clause";
+export * from "./helpers/argument_list";
+export * from "./helpers/call_helpers";
+export * from "./helpers/ensure_secure_access";
+export { adjustBrowseDirection } from "./helpers/adjust_browse_direction";
+export { resolveOpaqueOnAddressSpace } from "./helpers/resolve_opaque_on_address_space";
+
+export { ContinuationPointManager } from "./continuation_points/continuation_point_manager";
+export { ensureDatatypeExtracted, ensureDatatypeExtractedWithCallback } from "./loader/load_nodeset2";
+export * from "../source/loader/generateAddressSpaceRaw";
+
+export * from "./namespace";
+export * from "../src/alarms_and_conditions";
+export * from "../src/namespace_private";
+
+export { NodeIdManager, ConstructNodeIdOptions } from "../src/nodeid_manager";
+export * from "../src/event_data";
+export * from "./set_namespace_meta_data";
+
+export * from "node-opcua-address-space-base";
+export * from "node-opcua-nodeset-ua";

package/source/interfaces/alarms_and_conditions/condition_info_i.ts

@@ -0,0 +1,13 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { UInt16 } from "node-opcua-basic-types";
+import { LocalizedTextLike } from "node-opcua-data-model";
+import { StatusCode } from "node-opcua-status-code";
+
+export interface ConditionInfoOptions {
+    message?: string | LocalizedTextLike |null ;
+    quality?: StatusCode |null;
+    severity?: UInt16 | null;
+    retain?: boolean | null;
+}

package/source/interfaces/data_access/ua_multistate_discrete_ex.ts

@@ -0,0 +1,26 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { DataType, Variant } from "node-opcua-variant";
+
+/**
+ * @see https://reference.opcfoundation.org/v104/Core/docs/Part8/5.3.3/#5.3.3.3
+ */
+
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+import { StatusCode } from "node-opcua-status-code";
+import { UAMultiStateDiscrete_Base } from "node-opcua-nodeset-ua";
+import { UAVariableT } from "node-opcua-address-space-base";
+
+export { UAMultiStateDiscrete } from "node-opcua-nodeset-ua";
+
+export interface UAMultiStateDiscreteEx<T, DT extends DataType> extends UAVariableT<T, DT>, UAMultiStateDiscrete_Base<T, DT> {
+    //------------ helpers ------------------
+    getValue(): number;
+    getValueAsString(): string;
+    getIndex(value: string): number;
+    setValue(value: string | number): void;
+    checkVariantCompatibility(value: Variant): StatusCode;
+}

package/source/interfaces/data_access/ua_multistate_value_discrete_ex.ts

@@ -0,0 +1,34 @@
+/**
+ * @module node-opcua-address-space.DataAccess
+ */
+import { DataType, Variant } from "node-opcua-variant";
+import { Int64, UInt64 } from "node-opcua-basic-types";
+import { UAMultiStateValueDiscrete_Base } from "node-opcua-nodeset-ua";
+import { UAVariableT } from "node-opcua-address-space-base";
+
+/**
+ * @see https://reference.opcfoundation.org/v104/Core/docs/Part8/5.3.3/#5.3.3.4
+ */
+export interface UAMultiStateValueDiscreteEx<T, DT extends DataType>
+    extends UAVariableT<T, DT>,
+        UAMultiStateValueDiscrete_Base<T, DT> {
+    /**
+     * EnumValues is an array of EnumValueType. Each entry of the array represents one enumeration
+     * value with its integer notation, a human-readable representation, and help information.
+     * This represents enumerations with integers that are not zero-based or have gaps (e.g. 1, 2, 4, 8, 16).
+     *  See OPC 10000-3 for the definition of this type. MultiStateValueDiscrete Variables expose the
+     * current integer notation in their Value Attribute. Clients will often read the EnumValues
+     * Property in advance and cache it to lookup a name or help whenever they receive the numeric representation.
+     */
+    //------------ helpers ------------------
+    //    getValue(): number;
+    //    getIndex(value: string): number;
+
+    getValueAsString(): string;
+    getValueAsNumber(): number;
+
+    setValue(value: string | number | Int64): void;
+
+    findValueAsText(value: number | UInt64): Variant;
+
+}

package/source/interfaces/data_access/ua_two_state_discrete_ex.ts

@@ -0,0 +1,14 @@
+import { LocalizedTextLike } from "node-opcua-data-model";
+import { DataType } from "node-opcua-variant";
+import { UAVariableT } from "node-opcua-address-space-base";
+import { UATwoStateDiscrete_Base } from "node-opcua-nodeset-ua";
+
+/**
+ * @see https://reference.opcfoundation.org/v104/Core/VariableTypes/TwoStateDiscreteType/
+ */
+export interface UATwoStateDiscreteEx extends UAVariableT<boolean, DataType.Boolean>, UATwoStateDiscrete_Base<boolean> {
+    // --- helpers ---
+    getValue(): boolean;
+    getValueAsString(): string;
+    setValue(value: boolean | LocalizedTextLike): void;
+}

package/source/interfaces/data_access/ua_y_array_item_ex.ts

@@ -0,0 +1,10 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { UAVariableT } from "node-opcua-address-space-base";
+import { DataType } from "node-opcua-variant";
+import  { DT3DOrientation, UAYArrayItem_Base } from "node-opcua-nodeset-ua";
+
+export interface UAYArrayItemEx<DT extends DataType.Double|DataType.Float> extends UAVariableT<number[], DT>, UAYArrayItem_Base<number[], DT> {
+    // --- helpers ---
+}

package/source/interfaces/state_machine/ua_exclusive_limit_state_machine_type_ex.ts

@@ -0,0 +1,14 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { InstantiateObjectOptions, UAObject } from "node-opcua-address-space-base";
+import { UAExclusiveLimitStateMachine, UAExclusiveLimitStateMachine_Base } from "node-opcua-nodeset-ua";
+
+import { UAStateMachineEx, UAStateMachineHelper, UAStateMachineType } from "./ua_state_machine_type";
+
+export interface UAExclusiveLimitStateMachineEx extends  UAObject, UAExclusiveLimitStateMachine_Base , UAStateMachineHelper, UAStateMachineEx {}
+
+export interface UAExclusiveLimitStateMachineType extends UAStateMachineType {
+    isAbstract: false;
+    instantiate(options: InstantiateObjectOptions): UAExclusiveLimitStateMachineEx;
+}

package/source/interfaces/state_machine/ua_finite_state_machine_type.ts

@@ -0,0 +1,50 @@
+/**
+ * @module node-opcua-address-space
+ */
+import { InstantiateObjectOptions } from "node-opcua-address-space-base";
+
+import { UAStateMachineEx, UAStateMachineType } from "./ua_state_machine_type";
+/**
+ * Finite State Machine
+ *
+ * The FiniteStateMachineType is the base ObjectType for StateMachines that explicitly define
+ * the possible States and Transitions. Once the States are defined subtypes shall not add new
+ * States (see B.4.18).
+ * The States of the machine are represented with instances of the StateType ObjectType.
+ *
+ * EachState shall have a BrowseName which is unique within the StateMachine and shall have a
+ * StateNumber which shall also be unique across all States defined in the StateMachine.
+ *
+ * Be aware that States in a SubStateMachine may have the same StateNumber or BrowseName as
+ * States in the parent machine. A concrete subtype of FiniteStateMachineType shall define at
+ * least one State.
+ *
+ * A StateMachine may define one State which is an instance of the InitialStateType. This State
+ * is the State that the machine goes into when it is activated.
+ *
+ * The Transitions that may occur are represented with instances of the TransitionType.
+ *
+ * Each Transition shall have a BrowseName which is unique within the StateMachine and may have a
+ * TransitionNumber which shall also be unique across all Transitions defined in the StateMachine.
+ *
+ * The initial State for a Transition is a StateType Object which is the target of a FromState
+ * Reference. The final State for a Transition is a StateType Object which is the target of a ToState
+ * Reference. The FromState and ToState References shall always be specified.
+ * A Transition may produce an Event. The Event is indicated by a HasEffect Reference to a
+ * subtype of BaseEventType. The StateMachineType shall have GeneratesEvent References to
+ * the targets of a HasEffect Reference for each of its Transitions.
+ * A FiniteStateMachineType may define Methods that cause a transition to occur. These Methods
+ * are targets of HasCause References for each of the Transitions that may be triggered by the
+ * Method. The Executable Attribute for a Method is used to indicate whether the current State of
+ * the machine allows the Method to be called.
+ *
+ * A FiniteStateMachineType may have sub-state-machines which are represented as instances
+ * of StateMachineType ObjectTypes. Each State shall have a HasSubStateMachine Reference
+ * to the StateMachineType Object which represents the child States. The SubStateMachine is
+ * not active if the parent State is not active. In this case the CurrentState and LastTransition
+ * Variables of the SubStateMachine shall have a status equal to BadStateNotActive (see Table
+ * B.17).
+ */
+export interface UAFiniteStateMachineType extends UAStateMachineType {
+    instantiate(options: InstantiateObjectOptions): UAStateMachineEx;
+}

package/source/interfaces/state_machine/ua_program_state_machine_type.ts

@@ -0,0 +1,13 @@
+/**
+ * @module node-opcua-address-space
+ */
+// tslint:disable:no-empty-interface
+import { InstantiateObjectOptions, UAMethod, UAObject, UAObjectType } from "node-opcua-address-space-base";
+import { UAFiniteStateMachine, UAProgramStateMachine, UAProgramStateMachine_Base } from "node-opcua-nodeset-ua";
+import { UAStateMachineEx, UAStateMachineType } from "./ua_state_machine_type";
+
+export interface UAProgramStateMachineEx extends UAStateMachineEx {}
+
+export interface UAProgramStateMachineType extends UAProgramStateMachine_Base, UAObjectType {
+    instantiate(options: InstantiateObjectOptions): UAProgramStateMachineEx;
+}