node-opcua-file-transfer 2.51.0

package/readme.md

@@ -0,0 +1,204 @@
+## introduction
+
+this package provides an implementation of the OPCUA File Transfer
+specification as per OPCUA 1.0.4 part 5 Annex C (page 99)
+ 
+
+## installation
+
+```bash
+$ npm install node-opcua
+$ npm install node-opcua-file-transfer
+```
+
+## exposing a File node in the addressSpace
+
+```javascript
+import { OPCUAServer, UAFileType } from "node-opcua";
+import { installFileType } from "node-opcua-file-transfer";
+
+```
+
+```typescript
+
+const server = new OPCUAServer({
+
+});
+
+await server.initialize();
+
+
+// let say we want to create a access to this file:
+const my_data_filename = "/data/someFile.txt";
+await promisify(fs.writeFile)(my_data_filename, "some content", "utf8");
+
+
+// now add a file object in the address Space
+const addressSpace = server.engine.addressSpace;
+
+// retrieve the FileType UAObjectType
+const fileType = addressSpace.findObjectType("FileType")!;
+
+// create a instance of FileType 
+const myFile = fileType.instantiate({
+    nodeId: "s=MyFile",
+    browseName: "MyFile",
+    organizedBy: addressSpace.rootFolder.objects
+}) as UAFileType;
+
+// now bind the opcuaFile object with our file
+installFileType(opcuaFile, { 
+    filename: my_data_filename
+});
+
+```
+
+
+## accessing a File node from a node-opcua client : ClientFile
+
+We assume that we have a valid OPCUA Client Session
+
+```javascript
+import { OPCUAClient } from "node-opcua";
+import { ClientFile } from "node-opcua-file-transfer";
+
+const client = OPCUAClient.create({});
+
+await client.connect();
+const session = await client.createSession();
+```
+
+Let's assume that the nodeId of the file object is "ns=1;s=MyFile"
+
+```javascript
+import {ClientFile,OpenFileMode } from "node-opcua-file-transfer";
+
+// 
+const fileNodeId = "ns=1;s=MyFile";
+
+// let's create a client file object from the session and nodeId
+const clientFile = new ClientFile(session, fileNodeId);
+
+// let's open the file
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+
+// ... do some reading or writing
+
+// don't forget to close the file when done
+await clientFile.close();
+```
+
+### operations
+
+#### ClientFile#size(): Promise<UInt64> :  get file size
+
+You can read the size of the file at any time.
+``` javascript
+const clientFile = new ClientFile(session, fileNodeId);
+
+const size = await clientFile.size();
+console.log("the current file size is : ",size," bytes);
+```
+
+#### ClientFile#open(mode: OpenFileMode) : open a file
+
+```javascript 
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+```
+
+#### OpenFileMode enumeration
+
+| Mode | Description |
+|------|-------------|
+| Read  |The file is opened for reading. the Write method cannot be executed. |
+| Write|The file is opened for writing. the Read cannot be executed. |
+| ReadWrite| The file is opened for reading an writing |
+| WriteEraseExisting | File is opened for writing only. The existing content of the file is erased and an empty file is provided. |
+| ReadWriteEraseExisting | File is opened for reading and writing.  The existing content of the file is erased and an empty file is provided.|
+| WriteAppend | File is opened for writing only and position is set at the end of the file |
+| ReadWriteAppend | File is opened for reading and writing and position is set at the end of the file |
+}
+#### ClientFile#close() : close a file
+
+```javascript 
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+
+// ... do some reading or writing
+
+// don't forget to close the file when done
+await clientFile.close();
+```
+#### ClientFile#setPosition(pos: UInt64) :  Setting read/write position
+
+Once the file is opened, the position for reading or writing can be set
+using setPosition. 
+* setPosition expect a UInt64 parameter (see note below)
+* setPosition will throw an exception if file is not opened
+
+``` javascript
+const clientFile = new ClientFile(session, fileNodeId);
+
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+
+await client.setPosition([0,32]);
+
+```
+
+#### ClientFile#getPosition(): Promise<UInt64> Getting read/write position
+Once the file is opened, the position for reading or writing can be retrieved
+using getPosition. 
+* getPosition returns a UInt64 parameter (see note below)
+* getPosition will throw an exception if file is not opened
+
+``` javascript
+const clientFile = new ClientFile(session, fileNodeId);
+
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+
+await client.setPosition(32);
+
+```
+
+#### ClientFile#write(buf: Buffer) : Writing data to the file
+
+Data can be writing to the file at the current cursor position.
+Data must be passed in a buffer.
+* write will throw an exception if file is not opened
+
+```javascript
+const dataToWrite = Buffer.from("Some data");
+
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+await clientFile.write(dataToWrite);
+```
+
+
+#### ClientFile#read(): Promise<Buffer> :reading data to the file
+
+Data can be writing to the file at the current cursor position.
+Data must be passed in a buffer.
+* read will throw an exception if file is not opened
+
+```javascript
+
+const mode = OpenFileMode.ReadWriteAppend;
+await clientFile.open(mode);
+
+// read 200 bytes from position 32
+await clientFile.setPosition([0,32]);
+const data: Buffer = await clientFile.read(200);
+```
+
+### notes
+
+UInt64
+* At this time BigInt, is not supported by all version of nodeJs that are targeted by node-opcua.
+UInt64 values are currently stored into a array of 2 32bits numbers : [ High,Low]
+
+

package/source/client/client_file.ts

@@ -0,0 +1,322 @@
+/**
+ * @module node-opcua-file-transfer
+ */
+import { Byte, Int32, UInt16, UInt32, UInt64 } from "node-opcua-basic-types";
+import { AttributeIds } from "node-opcua-data-model";
+import { NodeId, resolveNodeId } from "node-opcua-nodeid";
+import { IBasicSession } from "node-opcua-pseudo-session";
+import { ReadValueIdOptions } from "node-opcua-service-read";
+import { BrowsePath, makeBrowsePath } from "node-opcua-service-translate-browse-path";
+import { StatusCodes } from "node-opcua-status-code";
+import { DataType, VariantArrayType } from "node-opcua-variant";
+import { MethodIds } from "node-opcua-constants";
+
+import { checkDebugFlag, make_debugLog, make_errorLog } from "node-opcua-debug";
+
+const debugLog = make_debugLog("FileType");
+const errorLog = make_errorLog("FileType");
+const doDebug = checkDebugFlag("FileType");
+
+import { OpenFileMode } from "../open_mode";
+export { OpenFileMode } from "../open_mode";
+
+/**
+ *
+ *
+ */
+export class ClientFile {
+
+    public static useGlobalMethod = false;
+
+    public    fileHandle = 0;
+    protected session: IBasicSession;
+    protected readonly fileNodeId: NodeId;
+
+    private openMethodNodeId?: NodeId;
+    private closeMethodNodeId?: NodeId;
+    private setPositionNodeId?: NodeId;
+    private getPositionNodeId?: NodeId;
+    private readNodeId?: NodeId;
+    private writeNodeId?: NodeId;
+    private openCountNodeId?: NodeId;
+    private sizeNodeId?: NodeId;
+
+    constructor(session: IBasicSession, nodeId: NodeId) {
+        this.session = session;
+        this.fileNodeId = nodeId;
+    }
+
+    public async open(mode: OpenFileMode): Promise<number> {
+
+        if (mode === null || mode === undefined) {
+            throw new Error("expecting a validMode " + OpenFileMode[mode]);
+        }
+        if (this.fileHandle) {
+            throw new Error("File has already be opened");
+        }
+        await this.ensureInitialized();
+
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.Byte, value: mode as Byte }
+            ],
+            methodId: this.openMethodNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            debugLog("Cannot open file : ");
+            throw new Error("cannot open file statusCode = " + result.statusCode.toString() + " mode = " + OpenFileMode[mode]);
+        }
+
+        this.fileHandle = result.outputArguments![0].value;
+
+        return this.fileHandle;
+    }
+
+    public async close(): Promise<void> {
+        if (!this.fileHandle) {
+            throw new Error("File has not been opened yet");
+        }
+        await this.ensureInitialized();
+
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.UInt32, value: this.fileHandle }
+            ],
+            methodId: this.closeMethodNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            debugLog("Cannot close file : ");
+            throw new Error("cannot close file statusCode = " + result.statusCode.toString());
+        }
+
+        this.fileHandle = 0;
+    }
+
+    public async getPosition(): Promise<UInt64> {
+        await this.ensureInitialized();
+        if (!this.fileHandle) {
+            throw new Error("File has not been opened yet");
+        }
+
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.UInt32, value: this.fileHandle }
+            ],
+            methodId: this.getPositionNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            throw new Error("Error " + result.statusCode.toString());
+        }
+        return result.outputArguments![0].value as UInt64;
+    }
+
+    public async setPosition(position: UInt64 | UInt32): Promise<void> {
+        await this.ensureInitialized();
+        if (!this.fileHandle) {
+            throw new Error("File has not been opened yet");
+        }
+        if (typeof position === "number") {
+            position = [0, position];
+        }
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.UInt32, value: this.fileHandle },
+                {
+                    arrayType: VariantArrayType.Scalar,
+                    dataType: DataType.UInt64,
+                    value: position
+                }
+            ],
+            methodId: this.setPositionNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            throw new Error("Error " + result.statusCode.toString());
+        }
+        return;
+    }
+
+    public async read(bytesToRead: Int32): Promise<Buffer> {
+        await this.ensureInitialized();
+        if (!this.fileHandle) {
+            throw new Error("File has not been opened yet");
+        }
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.UInt32, value: this.fileHandle },
+                {
+                    arrayType: VariantArrayType.Scalar,
+                    dataType: DataType.Int32,
+                    value: bytesToRead
+                }
+            ],
+            methodId: this.readNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            throw new Error("Error " + result.statusCode.toString());
+        }
+        if (!result.outputArguments || result.outputArguments[0].dataType !== DataType.ByteString) {
+            throw new Error("Error invalid output");
+        }
+        return result.outputArguments![0].value as Buffer;
+    }
+
+    public async write(data: Buffer): Promise<void> {
+        await this.ensureInitialized();
+        if (!this.fileHandle) {
+            throw new Error("File has not been opened yet");
+        }
+        const result = await this.session.call({
+            inputArguments: [
+                { dataType: DataType.UInt32, value: this.fileHandle },
+                {
+                    arrayType: VariantArrayType.Scalar,
+                    dataType: DataType.ByteString,
+                    value: data
+                }
+            ],
+            methodId: this.writeNodeId,
+            objectId: this.fileNodeId
+        });
+        if (result.statusCode !== StatusCodes.Good) {
+            throw new Error("Error " + result.statusCode.toString());
+        }
+        return;
+    }
+
+    public async openCount(): Promise<UInt16> {
+        await this.ensureInitialized();
+        const nodeToRead: ReadValueIdOptions = { nodeId: this.openCountNodeId!, attributeId: AttributeIds.Value };
+        const dataValue = await this.session.read(nodeToRead);
+
+        if (doDebug) {
+            debugLog(" OpenCount ", nodeToRead.nodeId!.toString(), dataValue.toString());
+        }
+        return dataValue.value.value;
+    }
+
+    public async size(): Promise<UInt64> {
+        await this.ensureInitialized();
+        const nodeToRead = { nodeId: this.sizeNodeId, attributeId: AttributeIds.Value };
+        const dataValue = await this.session.read(nodeToRead);
+        return dataValue.value.value;
+    }
+
+    // eslint-disable-next-line max-statements
+    protected async extractMethodsIds(): Promise<void> {
+
+        if (ClientFile.useGlobalMethod) {
+            debugLog("Using GlobalMethodId");
+            this.openMethodNodeId = resolveNodeId(MethodIds.FileType_Open);
+            this.closeMethodNodeId = resolveNodeId(MethodIds.FileType_Close);
+            this.setPositionNodeId = resolveNodeId(MethodIds.FileType_SetPosition);
+            this.getPositionNodeId = resolveNodeId(MethodIds.FileType_GetPosition);
+            this.writeNodeId = resolveNodeId(MethodIds.FileType_Write);
+            this.readNodeId = resolveNodeId(MethodIds.FileType_Read);
+            const browsePaths: BrowsePath[] = [
+                makeBrowsePath(this.fileNodeId, "/OpenCount"),
+                makeBrowsePath(this.fileNodeId, "/Size")
+            ];
+            const results = await this.session.translateBrowsePath(browsePaths);
+            if (results[0].statusCode !== StatusCodes.Good) {
+                throw new Error("fileType object does not expose mandatory OpenCount Property");
+            }
+            if (results[1].statusCode !== StatusCodes.Good) {
+                throw new Error("fileType object does not expose mandatory Size Property");
+            }
+            this.openCountNodeId = results[0].targets![0].targetId;
+            this.sizeNodeId = results[1].targets![0].targetId;
+            return;
+        }
+        const browsePaths: BrowsePath[] = [
+            makeBrowsePath(this.fileNodeId, "/Open"),
+            makeBrowsePath(this.fileNodeId, "/Close"),
+            makeBrowsePath(this.fileNodeId, "/SetPosition"),
+            makeBrowsePath(this.fileNodeId, "/GetPosition"),
+            makeBrowsePath(this.fileNodeId, "/Write"),
+            makeBrowsePath(this.fileNodeId, "/Read"),
+            makeBrowsePath(this.fileNodeId, "/OpenCount"),
+            makeBrowsePath(this.fileNodeId, "/Size")
+        ];
+
+        const results = await this.session.translateBrowsePath(browsePaths);
+
+        if (results[0].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory Open Method");
+        }
+        if (results[1].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory Close Method");
+        }
+        if (results[2].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory SetPosition Method");
+        }
+        if (results[3].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory GetPosition Method");
+        }
+        if (results[4].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory Write Method");
+        }
+        if (results[5].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory Read Method");
+        }
+        if (results[6].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory OpenCount Variable");
+        }
+        if (results[7].statusCode !== StatusCodes.Good) {
+            throw new Error("fileType object does not expose mandatory Size Variable");
+        }
+
+        if (false && doDebug) {
+            results.map((x: any) => debugLog(x.toString()));
+        }
+        this.openMethodNodeId = results[0].targets![0].targetId;
+        this.closeMethodNodeId = results[1].targets![0].targetId;
+        this.setPositionNodeId = results[2].targets![0].targetId;
+        this.getPositionNodeId = results[3].targets![0].targetId;
+        this.writeNodeId = results[4].targets![0].targetId;
+        this.readNodeId = results[5].targets![0].targetId;
+        this.openCountNodeId = results[6].targets![0].targetId;
+        this.sizeNodeId = results[7].targets![0].targetId;
+    }
+
+    protected async ensureInitialized(): Promise<void> {
+        if (!this.openMethodNodeId) {
+            await this.extractMethodsIds();
+        }
+    }
+}
+
+/**
+ * 5.2.10 UserRolePermissions
+ *
+ * The optional UserRolePermissions Attribute specifies the Permissions that apply to a Node for
+ * all Roles granted to current Session. The value of the Attribute is an array of
+ * RolePermissionType Structures (see Table 8).
+ * Clients may determine their effective Permissions by logically ORing the Permissions for each
+ * Role in the array.
+ *  The value of this Attribute is derived from the rules used by the Server to map Sessions to
+ * Roles. This mapping may be vendor specific or it may use the standard Role model defined in 4.8.
+ * This Attribute shall not be writeable.
+ * If not specified, the value of DefaultUserRolePermissions Property from the Namespace
+ * Metadata Object associated with the Node is used instead. If the NamespaceMetadata Object
+ * does not define the Property or does not exist, then the Server does not publish any information
+ * about Roles mapped to the current Session.
+ *
+ *
+ * 5.2.11 AccessRestrictions
+ * The optional AccessRestrictions Attribute specifies the AccessRestrictions that apply to a Node.
+ * Its data type is defined in 8.56. If a Server supports AccessRestrictions for a particular
+ * Namespace it adds the DefaultAccessRestrictions Property to the NamespaceMetadata Object
+ * for that Namespace (see Figure 8). If a particular Node in the Namespace needs to override
+ * the default value the Server adds the AccessRestrictions Attribute to the Node.
+ * If a Server implements a vendor specific access restriction model for a Namespace, it does not
+ * add the DefaultAccessRestrictions Property to the NamespaceMetadata Object.
+ *
+ *
+ * DefaultAccessRestrictions
+ *
+ */

package/source/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @module node-opcua-file-transfer
+ */
+export * from "./client/client_file";
+export * from "./server/file_type_helpers";

package/source/open_mode.ts

@@ -0,0 +1,41 @@
+/**
+ * @module node-opcua-file-transfer-server
+ */
+export enum OpenFileModeMask {
+    ReadBit = 0x01,
+    WriteBit = 0x02,
+    EraseExistingBit = 0x04,
+    AppendBit = 0x08,
+}
+
+export enum OpenFileMode {
+    /**
+     *       Read         bit 0   The file is opened for reading. If this bit is not
+     *                            set the Read Method cannot be executed.
+     */
+    Read = OpenFileModeMask.ReadBit,
+    /**
+     *      Write         bit 1   The file is opened for writing. If this bit is not
+     *                            set the Write Method cannot be executed.
+     *
+     */
+    Write = OpenFileModeMask.WriteBit,
+    ReadWrite = OpenFileModeMask.ReadBit + OpenFileModeMask.WriteBit,
+
+    /**
+     *
+     *  WriteEraseExisting
+     *      EraseExisting 2   This bit can only be set if the file is opened for writing
+     *                        (Write bit is set). The existing content of the file is
+     *                        erased and an empty file is provided.
+     */
+    WriteEraseExisting = OpenFileModeMask.EraseExistingBit + OpenFileModeMask.WriteBit,
+    ReadWriteEraseExisting = OpenFileModeMask.EraseExistingBit + OpenFileModeMask.WriteBit + OpenFileModeMask.ReadBit,
+    /**
+     *      Append        3   When the Append bit is set the file is opened at end
+     *                        of the file, otherwise at begin of the file.
+     *                        The SetPosition Method can be used to change the position.
+     */
+    WriteAppend = OpenFileModeMask.AppendBit + OpenFileModeMask.WriteBit,
+    ReadWriteAppend = OpenFileModeMask.AppendBit + OpenFileModeMask.WriteBit + OpenFileModeMask.ReadBit,
+}