feat: bootstrap suitelink tag client codecs
This commit is contained in:
Joseph Doherty
864
docs/plans/2026-03-16-suitelink-client-implementation-plan.md
Normal file
864
docs/plans/2026-03-16-suitelink-client-implementation-plan.md
Normal file
@@ -0,0 +1,864 @@
|
||||
# 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"
|
||||
```
|
||||
Reference in New Issue
Block a user