865 lines
28 KiB
Markdown
865 lines
28 KiB
Markdown
# SuiteLink Tag Client Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Build a cross-platform `.NET 10` C# SuiteLink V2 client for tag-only operations: connect, subscribe, receive updates, write values, and unsubscribe for `bool`, `int32`, `float32`, and `string`.
|
|
|
|
**Architecture:** The implementation is split into transport, protocol codec, session state, and public client API layers. The first version targets normal non-encrypted SuiteLink tag traffic only and validates behavior with unit tests, golden packet tests, and optional live integration tests against an AVEVA/OI server in mixed or legacy mode.
|
|
|
|
**Tech Stack:** .NET 10, C#, xUnit, `TcpClient`/`NetworkStream`, `System.Buffers`, `System.Buffers.Binary`
|
|
|
|
---
|
|
|
|
### Task 1: Create Solution Skeleton
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLink.Client.csproj`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Class1.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLink.Client.Tests.csproj`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/UnitTest1.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
|
|
**Step 1: Write the failing structure check**
|
|
|
|
Create a test project with one placeholder test:
|
|
|
|
```csharp
|
|
using Xunit;
|
|
|
|
namespace SuiteLink.Client.Tests;
|
|
|
|
public sealed class UnitTest1
|
|
{
|
|
[Fact]
|
|
public void Placeholder()
|
|
{
|
|
Assert.True(true);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify the solution builds**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
Expected: PASS with one test executed
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Create the library and solution structure only. Leave the default library type empty or minimal.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln /Users/dohertj2/Desktop/suitelinkclient/src /Users/dohertj2/Desktop/suitelinkclient/tests
|
|
git commit -m "chore: scaffold suitelink client solution"
|
|
```
|
|
|
|
### Task 2: Define Public Value And Option Models
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkConnectionOptions.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkValue.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkTagUpdate.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SubscriptionHandle.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkValueTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
using Xunit;
|
|
|
|
namespace SuiteLink.Client.Tests;
|
|
|
|
public sealed class SuiteLinkValueTests
|
|
{
|
|
[Fact]
|
|
public void BoolFactory_CreatesBoolValue()
|
|
{
|
|
var value = SuiteLinkValue.FromBoolean(true);
|
|
|
|
Assert.True(value.TryGetBoolean(out var result));
|
|
Assert.True(result);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter BoolFactory_CreatesBoolValue`
|
|
Expected: FAIL with missing type or method errors
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- immutable `SuiteLinkConnectionOptions`
|
|
- `SuiteLinkValue` discriminated wrapper for `bool`, `int`, `float`, `string`
|
|
- `SuiteLinkTagUpdate`
|
|
- `SubscriptionHandle` placeholder with async disposal hook
|
|
|
|
Minimal `SuiteLinkValue` pattern:
|
|
|
|
```csharp
|
|
public enum SuiteLinkValueKind
|
|
{
|
|
Boolean,
|
|
Int32,
|
|
Float32,
|
|
String
|
|
}
|
|
```
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkValueTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkValueTests.cs
|
|
git commit -m "feat: add public suitelink value models"
|
|
```
|
|
|
|
### Task 3: Add Frame Reader And Writer
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkFrame.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkFrameWriter.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkFrameReader.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkFrameWriterTests.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkFrameReaderTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
using Xunit;
|
|
|
|
namespace SuiteLink.Client.Tests.Protocol;
|
|
|
|
public sealed class SuiteLinkFrameWriterTests
|
|
{
|
|
[Fact]
|
|
public void WriteFrame_AppendsLengthTypeAndMarker()
|
|
{
|
|
var bytes = SuiteLinkFrameWriter.WriteFrame(0x2440, []);
|
|
|
|
Assert.Equal(5, bytes.Length);
|
|
Assert.Equal(0x03, bytes[0]);
|
|
Assert.Equal(0x00, bytes[1]);
|
|
Assert.Equal(0x40, bytes[2]);
|
|
Assert.Equal(0x24, bytes[3]);
|
|
Assert.Equal(0xA5, bytes[4]);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter WriteFrame_AppendsLengthTypeAndMarker`
|
|
Expected: FAIL with missing frame writer
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- `SuiteLinkFrame` record holding message type and payload span or byte array
|
|
- frame writer for normal SuiteLink messages
|
|
- frame reader that:
|
|
- reads two-byte remaining length
|
|
- reads remaining bytes plus trailing marker
|
|
- validates final `0xA5`
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkFrame`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol
|
|
git commit -m "feat: add suitelink frame reader and writer"
|
|
```
|
|
|
|
### Task 4: Add UTF-16LE And Primitive Wire Encoding Helpers
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkEncoding.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkEncodingTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
using Xunit;
|
|
|
|
namespace SuiteLink.Client.Tests.Protocol;
|
|
|
|
public sealed class SuiteLinkEncodingTests
|
|
{
|
|
[Fact]
|
|
public void EncodeLengthPrefixedUtf16_WritesCharacterCountThenUtf16Bytes()
|
|
{
|
|
var bytes = SuiteLinkEncoding.EncodeLengthPrefixedUtf16("AB");
|
|
|
|
Assert.Equal(1 + 4, bytes.Length);
|
|
Assert.Equal(2, bytes[0]);
|
|
Assert.Equal((byte)'A', bytes[1]);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter EncodeLengthPrefixedUtf16_WritesCharacterCountThenUtf16Bytes`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement helper methods for:
|
|
|
|
- one-byte-length-prefixed UTF-16LE strings
|
|
- null-terminated UTF-16LE strings
|
|
- little-endian primitive reads/writes
|
|
- FILETIME conversion helper if needed for future time messages
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkEncodingTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkEncoding.cs /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkEncodingTests.cs
|
|
git commit -m "feat: add suitelink encoding helpers"
|
|
```
|
|
|
|
### Task 5: Encode Handshake And Connect Messages
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkHandshakeCodec.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkConnectCodec.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkHandshakeCodecTests.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkConnectCodecTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Use known bytes captured from the reverse-engineered protocol and assert:
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void EncodeConnect_WritesConnectMessageType()
|
|
{
|
|
var options = new SuiteLinkConnectionOptions(
|
|
host: "127.0.0.1",
|
|
application: "App",
|
|
topic: "Topic",
|
|
clientName: "Client",
|
|
clientNode: "Node",
|
|
userName: "User",
|
|
serverNode: "Server");
|
|
|
|
var bytes = SuiteLinkConnectCodec.Encode(options);
|
|
|
|
Assert.Equal(0x80, bytes[2]);
|
|
Assert.Equal(0x01, bytes[3]);
|
|
Assert.Equal(0xA5, bytes[^1]);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter EncodeConnect_WritesConnectMessageType`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- normal SuiteLink handshake encoder
|
|
- handshake acknowledgement parser
|
|
- connect encoder using the observed field order
|
|
- isolate unknown fixed bytes in constants with comments pointing to capture evidence
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter CodecTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol
|
|
git commit -m "feat: encode suitelink handshake and connect"
|
|
```
|
|
|
|
### Task 6: Encode Advise And Unadvise Messages
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkSubscriptionCodec.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkSubscriptionCodecTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void EncodeAdvise_WritesTagNameInUtf16()
|
|
{
|
|
var bytes = SuiteLinkSubscriptionCodec.EncodeAdvise("Pump001.Run");
|
|
|
|
Assert.Equal(0x80, bytes[2]);
|
|
Assert.Equal(0x10, bytes[3]);
|
|
Assert.Equal(0xA5, bytes[^1]);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter EncodeAdvise_WritesTagNameInUtf16`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- `EncodeAdvise(string itemName)`
|
|
- `EncodeUnadvise(uint tagId)`
|
|
- `DecodeAdviseAck(ReadOnlySpan<byte>)`
|
|
|
|
Add a small result model for advise acknowledgements that captures `tagId`.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkSubscriptionCodecTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkSubscriptionCodecTests.cs
|
|
git commit -m "feat: add advise and unadvise codec support"
|
|
```
|
|
|
|
### Task 7: Decode Update Messages For Primitive Types
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkUpdateCodec.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkWireValueType.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkUpdateCodecTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void DecodeUpdate_DecodesIntegerValue()
|
|
{
|
|
var frame = new byte[]
|
|
{
|
|
0x0D, 0x00, 0x00, 0x09,
|
|
0x34, 0x12, 0x00, 0x00,
|
|
0x01, 0x00,
|
|
0xC0, 0x00,
|
|
0x02,
|
|
0x2A, 0x00, 0x00, 0x00,
|
|
0xA5
|
|
};
|
|
|
|
var update = SuiteLinkUpdateCodec.Decode(frame);
|
|
|
|
Assert.Equal(0x1234u, update.TagId);
|
|
Assert.True(update.Value.TryGetInt32(out var value));
|
|
Assert.Equal(42, value);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter DecodeUpdate_DecodesIntegerValue`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement decoding for:
|
|
|
|
- binary to `bool`
|
|
- integer to `int`
|
|
- real to `float`
|
|
- message to `string`
|
|
|
|
Return a parsed update model containing:
|
|
|
|
- `TagId`
|
|
- `Quality`
|
|
- `ElapsedMilliseconds`
|
|
- `SuiteLinkValue`
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkUpdateCodecTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkUpdateCodecTests.cs
|
|
git commit -m "feat: decode primitive suitelink update values"
|
|
```
|
|
|
|
### Task 8: Encode Poke Messages For Primitive Writes
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol/SuiteLinkWriteCodec.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkWriteCodecTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void EncodeWrite_Int32Value_WritesPokeMessage()
|
|
{
|
|
var bytes = SuiteLinkWriteCodec.Encode(0x1234, SuiteLinkValue.FromInt32(42));
|
|
|
|
Assert.Equal(0x08, bytes[2]);
|
|
Assert.Equal(0x0B, bytes[3]);
|
|
Assert.Equal(0xA5, bytes[^1]);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter EncodeWrite_Int32Value_WritesPokeMessage`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement primitive write encoding for:
|
|
|
|
- `bool`
|
|
- `int32`
|
|
- `float32`
|
|
- `string` if confirmed by packet format used for wire message values
|
|
|
|
Reject unsupported value kinds with a clear exception.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkWriteCodecTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Protocol /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/SuiteLinkWriteCodecTests.cs
|
|
git commit -m "feat: encode primitive suitelink writes"
|
|
```
|
|
|
|
### Task 9: Implement Session State And Tag Mapping
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Internal/SuiteLinkSessionState.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Internal/SuiteLinkSession.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Internal/SuiteLinkSessionTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void RegisterSubscription_MapsItemNameToTagId()
|
|
{
|
|
var session = new SuiteLinkSession();
|
|
|
|
session.RegisterSubscription("Pump001.Run", 0x1234);
|
|
|
|
Assert.Equal(0x1234u, session.GetTagId("Pump001.Run"));
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter RegisterSubscription_MapsItemNameToTagId`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- session state enum
|
|
- tag map for `itemName -> tagId`
|
|
- reverse lookup for `tagId -> itemName`
|
|
- subscription callback registration
|
|
- update dispatch helper
|
|
|
|
Keep transport mocking simple. Do not implement full socket I/O in this task.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkSessionTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Internal /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Internal/SuiteLinkSessionTests.cs
|
|
git commit -m "feat: add session state and tag mapping"
|
|
```
|
|
|
|
### Task 10: Implement Tcp Transport Loop
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Transport/SuiteLinkTcpTransport.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Transport/ISuiteLinkTransport.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Transport/SuiteLinkTcpTransportTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public async Task SendAsync_WritesFrameToUnderlyingStream()
|
|
{
|
|
var stream = new MemoryStream();
|
|
var transport = new SuiteLinkTcpTransport(stream);
|
|
|
|
await transport.SendAsync(new byte[] { 0x01, 0x02 }, CancellationToken.None);
|
|
|
|
Assert.Equal(new byte[] { 0x01, 0x02 }, stream.ToArray());
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SendAsync_WritesFrameToUnderlyingStream`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- transport abstraction
|
|
- stream-backed send and receive methods
|
|
- real `TcpClient` constructor path
|
|
- test-friendly stream injection path
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkTcpTransportTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Transport /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Transport/SuiteLinkTcpTransportTests.cs
|
|
git commit -m "feat: add suitelink transport abstraction"
|
|
```
|
|
|
|
### Task 11: Implement Public Client Connect And Disconnect
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkClient.cs`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SubscriptionHandle.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientConnectionTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public async Task ConnectAsync_TransitionsClientToConnectedState()
|
|
{
|
|
var client = new SuiteLinkClient(new FakeTransport());
|
|
|
|
await client.ConnectAsync(TestOptions.Create());
|
|
|
|
Assert.True(client.IsConnected);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter ConnectAsync_TransitionsClientToConnectedState`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- `SuiteLinkClient`
|
|
- connect flow invoking handshake then connect codec
|
|
- disconnect path
|
|
- basic disposal
|
|
|
|
Expose a minimal `IsConnected` property or equivalent state for tests.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkClientConnectionTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkClient.cs /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SubscriptionHandle.cs /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientConnectionTests.cs
|
|
git commit -m "feat: implement suitelink client connection flow"
|
|
```
|
|
|
|
### Task 12: Implement Subscribe And Read Flow
|
|
|
|
**Files:**
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkClient.cs`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Internal/SuiteLinkSession.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientSubscriptionTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public async Task ReadAsync_ReturnsFirstUpdateForRequestedTag()
|
|
{
|
|
var client = TestClientFactory.CreateConnectedClientWithUpdate("Pump001.Run", SuiteLinkValue.FromBoolean(true));
|
|
|
|
var update = await client.ReadAsync("Pump001.Run", TimeSpan.FromSeconds(1));
|
|
|
|
Assert.True(update.Value.TryGetBoolean(out var value));
|
|
Assert.True(value);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter ReadAsync_ReturnsFirstUpdateForRequestedTag`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- `SubscribeAsync`
|
|
- `ReadAsync` via temporary subscription
|
|
- callback dispatch on incoming updates
|
|
- unadvise when subscription handle is disposed
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkClientSubscriptionTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientSubscriptionTests.cs
|
|
git commit -m "feat: implement suitelink subscribe and read flow"
|
|
```
|
|
|
|
### Task 13: Implement Primitive Write Flow
|
|
|
|
**Files:**
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/SuiteLinkClient.cs`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client/Internal/SuiteLinkSession.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientWriteTests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact]
|
|
public async Task WriteAsync_SendsPokeForSubscribedTag()
|
|
{
|
|
var client = TestClientFactory.CreateConnectedSubscribedClient("Pump001.Speed", 0x1234);
|
|
|
|
await client.WriteAsync("Pump001.Speed", SuiteLinkValue.FromInt32(42));
|
|
|
|
Assert.Contains(client.SentFrames, frame => frame[2] == 0x08 && frame[3] == 0x0B);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter WriteAsync_SendsPokeForSubscribedTag`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Implement:
|
|
|
|
- `WriteAsync`
|
|
- tag lookup by item name
|
|
- fail if item is unknown or not yet subscribed
|
|
- use primitive write codec
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter SuiteLinkClientWriteTests`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/src/SuiteLink.Client /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/SuiteLinkClientWriteTests.cs
|
|
git commit -m "feat: implement primitive suitelink writes"
|
|
```
|
|
|
|
### Task 14: Add Golden Packet Fixtures
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Fixtures/README.md`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Fixtures/*.bin`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol/*Tests.cs`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
Add one fixture-backed assertion that compares encoded output to a stored handshake or connect frame.
|
|
|
|
```csharp
|
|
[Fact]
|
|
public void EncodeConnect_MatchesGoldenFixture()
|
|
{
|
|
var expected = File.ReadAllBytes("Fixtures/connect.bin");
|
|
var actual = SuiteLinkConnectCodec.Encode(TestOptions.Create()).ToArray();
|
|
|
|
Assert.Equal(expected, actual);
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify it fails**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter MatchesGoldenFixture`
|
|
Expected: FAIL until fixture and codec match
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Add fixture files and normalize tests to read them from disk. Document where the fixture bytes came from and which captures or protocol references justify them.
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter Fixture`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Fixtures /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.Tests/Protocol
|
|
git commit -m "test: add golden packet fixtures for suitelink codec"
|
|
```
|
|
|
|
### Task 15: Add Live Integration Test Harness
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.IntegrationTests/SuiteLink.Client.IntegrationTests.csproj`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.IntegrationTests/IntegrationSettings.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.IntegrationTests/TagRoundTripTests.cs`
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.IntegrationTests/README.md`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
|
|
**Step 1: Write the failing test**
|
|
|
|
```csharp
|
|
[Fact(Skip = "Requires live AVEVA SuiteLink endpoint")]
|
|
public async Task CanSubscribeAndWriteBooleanTag()
|
|
{
|
|
var client = new SuiteLinkClient();
|
|
await client.ConnectAsync(IntegrationSettings.Load());
|
|
}
|
|
```
|
|
|
|
**Step 2: Run test to verify the harness builds**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln --filter CanSubscribeAndWriteBooleanTag`
|
|
Expected: PASS or SKIP with the test discovered
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Add:
|
|
|
|
- integration project
|
|
- environment-based settings loader
|
|
- skipped or conditional tests for boolean, integer, float, and string tags
|
|
|
|
**Step 4: Run test to verify it passes**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
Expected: PASS with integration tests skipped by default
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/tests/SuiteLink.Client.IntegrationTests /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln
|
|
git commit -m "test: add suitelink integration test harness"
|
|
```
|
|
|
|
### Task 16: Add Package Documentation
|
|
|
|
**Files:**
|
|
- Create: `/Users/dohertj2/Desktop/suitelinkclient/README.md`
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/docs/plans/2026-03-16-suitelink-client-design.md`
|
|
|
|
**Step 1: Write the failing documentation check**
|
|
|
|
Define the required README sections:
|
|
|
|
- project purpose
|
|
- supported protocol scope
|
|
- supported types
|
|
- unsupported features
|
|
- local build and test commands
|
|
- integration test setup
|
|
|
|
**Step 2: Run documentation review**
|
|
|
|
Run: `rg -n "Supported|Unsupported|Build|Test|Integration" /Users/dohertj2/Desktop/suitelinkclient/README.md`
|
|
Expected: FAIL until README exists
|
|
|
|
**Step 3: Write minimal implementation**
|
|
|
|
Create a README that states:
|
|
|
|
- v1 supports normal SuiteLink V2 tag operations only
|
|
- v1 does not support AlarmMgr or secure V3
|
|
- primitive types only
|
|
- exact `dotnet` commands for build and test
|
|
|
|
**Step 4: Run documentation review**
|
|
|
|
Run: `rg -n "Supported|Unsupported|Build|Test|Integration" /Users/dohertj2/Desktop/suitelinkclient/README.md`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/README.md /Users/dohertj2/Desktop/suitelinkclient/docs/plans/2026-03-16-suitelink-client-design.md
|
|
git commit -m "docs: describe suitelink client scope and usage"
|
|
```
|
|
|
|
### Task 17: Full Verification Pass
|
|
|
|
**Files:**
|
|
- Modify: `/Users/dohertj2/Desktop/suitelinkclient/docs/plans/2026-03-16-suitelink-client-implementation-plan.md`
|
|
|
|
**Step 1: Run unit and integration-default test suite**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln`
|
|
Expected: PASS with integration tests skipped by default
|
|
|
|
**Step 2: Run build verification**
|
|
|
|
Run: `dotnet build /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln -c Release`
|
|
Expected: PASS
|
|
|
|
**Step 3: Run formatting or analyzer checks if added**
|
|
|
|
Run: `dotnet test /Users/dohertj2/Desktop/suitelinkclient/SuiteLink.Client.sln -c Release`
|
|
Expected: PASS
|
|
|
|
**Step 4: Update plan status notes if execution deviated**
|
|
|
|
Add a short note to the plan if any task required deviation due to verified protocol differences.
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add /Users/dohertj2/Desktop/suitelinkclient/docs/plans/2026-03-16-suitelink-client-implementation-plan.md
|
|
git commit -m "docs: finalize suitelink implementation verification"
|
|
```
|