File Transfer (Part 5)

Added in v1.3.0. The suite exposes a folder TestServer/Files containing six FileType nodes plus one FileDirectoryType that exercise the entire OPC UA File Transfer service surface (Open, Close, Read, Write, GetPosition, SetPosition, CreateDirectory, CreateFile, DeleteFileSystemObject, MoveOrCopy) plus the standard properties (Size, Writable, UserWritable, OpenCount, MimeType).

All files are backed by per-process MemoryStreams:

• No disk I/O, no volumes, no mount setup.
• Every docker compose restart (or container kill) resets all six files to their initial seed and clears every runtime-created child of RootDir.
• The OpenCount reflects live handles only.

The six files

Path: TestServer / Files

Plus the directory:

Namespace ns=1 resolves to urn:opcua:testserver:nodes (the standard test namespace). Resolve the index at runtime via NamespaceArray — ns=1 is the typical allocation, not a guarantee.

Open modes (Part 5 §C.2.1)

The Open(Byte mode) method accepts a bit field:

The fixture enforces these invariants:

Round-trip pattern for WritableFile

1.  fileHandle1 = Open(WritableFile, mode = Write | EraseExisting)
2.  Write(fileHandle1, payload)
3.  Close(fileHandle1)
4.  fileHandle2 = Open(WritableFile, mode = Read)
5.  assert Read(fileHandle2, length = payload.Length) == payload
6.  Close(fileHandle2)

Append pattern for AppendableFile

1.  fileHandle = Open(AppendableFile, mode = Write | Append)
2.  assert GetPosition(fileHandle) == 13          # past the seed
3.  Write(fileHandle, additional_bytes)
4.  Close(fileHandle)
5.  fileHandle2 = Open(AppendableFile, mode = Read)
6.  full = Read(fileHandle2, 1024)
7.  assert full[:13] == b"seed-content\n"
8.  assert full[13:]  == additional_bytes
9.  Close(fileHandle2)

Chunked-read pattern for LargeFile

1.  handle = Open(LargeFile, mode = Read)
2.  chunkSize = 8192            # any value smaller than the file
3.  collected = []
4.  loop:
       chunk = Read(handle, chunkSize)
       if chunk is empty: break
       collected.append(chunk)
5.  Close(handle)
6.  assert len(collected) == 32  # 256K / 8K
7.  assert collected.flatten()[i] == i % 256  for every i

Per-session permission pattern for ProtectedWritableFile

# Session A — anonymous on opcua-no-security (4840)
1.  client_a.Open(ProtectedWritableFile, mode = Read)   → Good
2.  client_a.Open(ProtectedWritableFile, mode = Write)  → Bad_UserAccessDenied

# Session B — username=admin password=admin123 on opcua-userpass (4841)
3.  client_b.Open(ProtectedWritableFile, mode = Write)  → Good (handle)
4.  client_b.Write(handle, ...)                          → Good
5.  client_b.Close(handle)                               → Good

# Session C — username=viewer password=viewer123 on opcua-userpass (4841)
6.  client_c.Open(ProtectedWritableFile, mode = Write)  → Bad_UserAccessDenied

The check happens server-side inside the Open callback — the file's Writable property still reads true for everyone (that property advertises the abstract capability, not the per-session authorization).

FileDirectoryType — RootDir

RootDir exposes the four standard methods (Part 5 §C.3):

Behaviour:

• Children are anonymous-writable — CreateFile returns a FileType node with Writable=true. Use RootDir for round-trip scenarios that don't fit WritableFile (multiple files, hierarchies, move/copy).
• CreateFile with requestFileOpen=true returns a fileHandle in Read+Write mode (mode = 3) alongside the new NodeId — spares a separate Open round-trip.
• MoveOrCopy supports both createCopy=true (deep-clones the file content via the backend's snapshot) and createCopy=false (relinks: source NodeId removed, destination NodeId returned). Sub-directories follow the same semantics; their children are a shallow copy when copied.
• DeleteFileSystemObject removes the node from the address space and drops the in-process backend for files. Open handles on the deleted file are not auto-closed; subsequent operations against them return Bad_InvalidArgument.
• Empty name in CreateDirectory / CreateFile → Bad_InvalidArgument. Unknown NodeId in DeleteFileSystemObject / MoveOrCopy → Bad_NodeIdUnknown.

CreateFile + round-trip example

1.  (newNodeId, handle) = RootDir.CreateFile("data.bin", requestFileOpen=true)
2.  Write(handle, payload)
3.  Close(handle)
4.  readHandle = Open(newNodeId, mode = Read)
5.  assert Read(readHandle, len(payload)) == payload
6.  Close(readHandle)
7.  RootDir.DeleteFileSystemObject(newNodeId)

MoveOrCopy with copy

1.  (src, h) = RootDir.CreateFile("src.bin", requestFileOpen=true)
2.  Write(h, b"hello")
3.  Close(h)
4.  dst = RootDir.MoveOrCopy(src, RootDir, createCopy=true, newName="copy.bin")
5.  hr = Open(dst, mode = Read)
6.  assert Read(hr, 5) == b"hello"
7.  Close(hr)
# src still exists at this point — close anyway

Property reads

Standard FileType properties on every file:

Investigated and skipped — FileChange / FileAccess events

UA-.NETStandard 1.5.378.134 does not ship the dedicated FileChangeEventType / FileAccessEventType classes that Part 5 §8.2 defines. The available file-related event types in that release are AuditUpdateEventType / AuditUpdateMethodEventType / AuditUpdateStateEventType — audit semantics, not the data-change notification semantics §8.2 calls for.

The suite intentionally does not emit these events:

• Emitting custom vendor-specific event types would defeat the fixture's role (clients would have to know about the custom type).
• Emitting AuditUpdate* types as a substitute would conflate audit logs with file-change notifications, again forcing client-side workarounds.

The right time to revisit this is when a future UA-.NETStandard release adds the standard FileChangeEventType / FileAccessEventType classes.

Enabling / disabling

On by default on every server instance. Disable with:

environment:
  OPCUA_ENABLE_FILE_TRANSFER: "false"

Disabling skips the entire TestServer/Files folder construction — none of the seven nodes (six files plus the directory) will exist in the address space.

Reset semantics

Each file and the directory tree reset on the events below:

The three read-only files (ReadOnlyFile, EmptyFile, LargeFile) cannot be mutated under any condition — their seeds are reasserted on every container start.

Implementation reference

The fixture is built by src/TestServer/AddressSpace/FileTransferBuilder.cs (~480 lines C#). Uses UA-.NETStandard's FileState and FileDirectoryState as the type wrappers, exposes one in-process InMemoryFileBackend per file plus a per-directory dictionary of dynamically-created child node IDs and backends. The backend is thread-safe via a single lock — UA-.NETStandard dispatches method OnCall from its session worker pool, so concurrent handle access is real but correctly serialised.

TestNodeManager was extended with a DeleteDynamicNode(NodeId) helper that wraps the framework's protected DeleteNode(SystemContext, NodeId) so the DeleteFileSystemObject / MoveOrCopy callbacks can drop nodes from the address space.

The builder is conditionally wired in TestNodeManager.CreateAddressSpace between the Methods and Dynamic builders.