[tylerje]

ServiceWire 7.0.0 — performance release, negotiated wire protocol v2, and a full user guide

A major performance release plus the documentation to go with it. Steady-state calls are 43–70% faster than 6.0.1 on named pipes and 13–47% faster on TCP; TCP connection setup is roughly 14× faster on .NET 8 and 10.

Every mixed-version pairing keeps working. The new v2 wire activates only when both ends are 7.0, so a fleet can be upgraded in any order with no flag day.

---

📖 Documentation

The wiki is superseded by a versioned user guide that lives in the repo and travels with the code.

docs/user-guide.md is the hub, linked prominently from the README, with 11 topic pages:

Page	Covers
Getting started	Three-project walkthrough, full code, how to run it
Designing contracts	What a method signature may contain, versioning, threading
Transports and endpoints	TCP vs named pipes, pipe ACLs, timeouts, client lifetime
Serialization and compression	ISerializer, ICompressor, when to compress
Security	Zero-knowledge login, credential storage, hardening checklist
Logging and diagnostics	Host.Status supervisor pattern, ILog/IStats, MEL adapter
Interception	Pre/post/exception hooks, host-side vs client-side
Wire protocol	Message types, v1 and v2 frame layouts, negotiation
Performance	Full benchmark tables, tuning guidance, how to re-run
Migrating to 7.0	Compatibility matrix, breaking surface, upgrade checklist
Troubleshooting	Symptom → cause → fix for the common failures

13 hand-authored SVG diagrams in docs/images/ — call path, frame layouts, ZK handshake sequence, host status lifecycle, benchmark chart. All relative links and heading anchors are verified; all SVGs are XML-valid and render in both GitHub themes.

Behaviour verified against the built library while writing these, correcting long-standing assumptions:

• Interface properties and indexers do work — each accessor is a round trip
• Generic methods fail at client construction (T Echo<T>(T) cannot be proxied)
• Events build a proxy but throw on += — there is no callback channel
• out decimal / ref Guid throw NotSupportedException at construction, not at call time

The README is restructured around a quick start and the guide link; the full version history is preserved, and the 2024 benchmark run moved into docs/performance.md rather than being dropped.

---

⚡ Internal optimizations

v1 wire format is unchanged, proven byte-identical by golden tests.

1. Memoized type-to-config-name resolution in both directions, removing three regex passes per complex parameter per call and repeated Type.GetType lookups in DefaultSerializer.
2. Fixed the named-pipe client to actually use its BufferedStream, collapsing dozens of per-field pipe syscalls per call into one (and fixing a pipe stream that was never disposed).
3. Set Socket.NoDelay on client and accepted sockets to eliminate Nagle and delayed-ACK latency; both sides already buffer and flush once per message.
4. Server dispatch through compiled expression delegates instead of MethodInfo.Invoke (byref methods fall back to reflection); async results through compiled Task.Result getters; client Task.FromResult wrapping through compiled converters. Client-visible exception behaviour is unchanged and covered by parity tests.
5. Proxy types are created and their constructors compiled once per pooled builder; creating a proxy is now a delegate call.
6. Larger named-pipe server buffers, connect-path event wait instead of a spin loop, CompressionLevel.Fastest in the default compressor, and reused ZK cipher instances (identical ciphertext).

---

🔌 Wire protocol v2

Default on both transports, negotiated per connection, never sent to a 6.x peer.

1. Servers advertise capabilities through a new additive ServiceSyncInfo.CapabilityFlags member.
2. Framed MethodInvocation2/Response2 messages with length prefixes and correlation ids: a request payload that fails to decode is answered with a correlated error response instead of desynchronizing the stream and killing the connection.
3. DateTime values travel as ToBinary() — Kind-preserving, no string parsing.
4. Concurrent in-flight calls on a shared TCP client proxy. Callers no longer serialize on a whole-round-trip lock; whichever caller holds the read seat pairs responses by correlation id while the server executes each connection's requests strictly in order. An uncontended caller reads inline with no thread handoff.
5. Named-pipe channels speak v2 with the exchange serialized per channel — synchronous pipe handles cannot overlap a read with a write. Pipes still gain decode-error resilience and binary DateTime transfer on top of the Tier 1 buffering wins.
6. Three opt-outs force the classic v1 wire: Host.EnableWireV2 = false (before AddService), and TcpEndPoint.UseWireV2 = false / NpEndPoint.UseWireV2 = false per client.
7. In-place server downgrades with a stale cached capability produce a descriptive error and evict the cache so the next channel renegotiates.

---

🐛 Bug fixes

1. A string[] above the compression threshold was written with a type code no receiver could decode; it now uses CompressedUnknown, which every release since 1.5.0 can read.
2. Scalar Type parameters crashed the default serializer; they now use the wire format's Type code.
3. Thrown exceptions could not be serialized by System.Text.Json (TargetSite), which killed the connection whenever a service method threw with the default serializer. A converter now preserves the exception type, message, HResult, inner chain, and server stack trace.

---

📦 Packaging and opt-ins

The package now multi-targets:

• netstandard2.0 keeps the exact 6.x dependency graph, so existing .NET Framework and .NET Standard consumers see no new binding redirects.
• net8.0 has no package dependencies, plus span-based fast paths that produce identical wire bytes.

Assembly version is pinned at 7.0.0.0 across both TFMs so mixed loads bind cleanly.

Opt-in additions, all defaulting to prior behaviour:

Addition	Where	Default
ReceiveTimeoutMs, SendTimeoutMs	TcpEndPoint, TcpHost	0 — infinite, as before
PersistentFileWriter	LoggerBase	false
EnableWireV2	Host	true
UseWireV2	TcpEndPoint, NpEndPoint	true

---

⚠️ Breaking surface

This is a major version for exactly one reason: ServiceSyncInfo gained a member.

[DataMember(Order = 5)]
public int CapabilityFlags { get; set; }

Every tolerant serializer handles this — System.Text.Json ignores unknown members, protobuf-net skips unknown field numbers, Newtonsoft ignores extras by default. A strict custom ISerializer on a 6.x client, configured to reject unmapped members or hand-coding the field list, may need updating. It is declared as int rather than an enum so every serializer sees a plain scalar.

Compatibility matrix:

	Host on 6.x	Host on 7.0
Client on 6.x	v1 wire — unchanged	v1 wire — host advertises v2, old client ignores the flag
Client on 7.0	v1 wire — no capability advertised	v2 wire

---

📊 Benchmarks

Identical suite (BenchmarkDotNet 0.15.8), same machine, same day: Windows 11, AMD Ryzen Threadripper PRO 5975WX, .NET SDK 10.0.204. Means are microseconds per call; lower is better.

Steady state — persistent host and client

Benchmark	.NET 10 6.0.1	.NET 10 7.0.0	Faster by	.NET 8 6.0.1	.NET 8 7.0.0	Faster by	.NET 4.8 6.0.1	.NET 4.8 7.0.0	Faster by
NpSim	27.9	14.9	47%	27.9	15.3	45%	32.7	18.0	45%
NpSimJson	27.7	14.4	48%	27.9	15.8	43%	32.7	18.2	44%
NpRg	66.5	19.7	70%	72.7	22.9	68%	129.5	46.9	64%
NpRgJson	68.1	26.9	60%	80.0	30.1	62%	137.8	54.2	61%
NpCxOut	65.1	20.5	69%	71.0	22.2	69%	103.3	36.4	65%
NpCxOutJson	67.0	22.3	67%	74.8	24.7	67%	107.4	43.8	59%
TcpSim	47.9	40.9	14%	48.1	41.7	13%	56.8	48.9	14%
TcpSimJson	47.4	40.8	14%	48.1	41.8	13%	57.5	49.5	14%
TcpRg	91.9	51.7	44%	97.5	54.5	44%	161.0	84.8	47%
TcpRgJson	91.9	51.1	44%	97.6	55.5	43%	160.1	84.5	47%
TcpCxOut	87.7	51.7	41%	94.1	54.3	42%	130.1	76.3	41%
TcpCxOutJson	86.6	51.7	40%	93.3	54.6	42%	130.5	76.0	42%

Connection setup — host and client built and torn down per operation

Benchmark	.NET 10 6.0.1	.NET 10 7.0.0	.NET 8 6.0.1	.NET 8 7.0.0	.NET 4.8 6.0.1	.NET 4.8 7.0.0
TcpConn	15,385	1,114	15,496	1,111	976	1,083
NpConn	331	507	328	451	322	530

The 6.0.1 TcpConn figure is real — the old connect path busy-waited on SpinWait.SpinUntil, which degrades badly on modern runtimes. Named-pipe connection setup is 0.1–0.2 ms slower in 7.0.0 (split read/write buffered streams, larger pipe buffers); the per-call savings repay that within a handful of calls on any connection that is actually used.

Shapes the suite does not cover, measured separately: a client sending an int[1000] over a named pipe is roughly 10× faster (the 6.x pipe client issued one write syscall per array element), concurrent callers sharing one TCP proxy gain up to 2× from v2 pipelining, and DateTime-heavy payloads avoid string formatting and parsing entirely.

---

✅ Testing

• Unit tests: 65 passed, 6 skipped, 0 failed on both net10.0 and net48
• Golden wire-format tests assert the v1 bytes are byte-identical to 6.x
• New interop matrix runs the published ServiceWire 6.0.1 package as a separate process against 7.0 in both directions, across TCP and named pipes, with and without compression — wired into CI
• New pipelining tests cover concurrent callers on a shared proxy, including that the server still executes one connection's requests in order
• New compiled-dispatch tests cover exception parity between the compiled and reflection paths

---

🔍 Review notes and follow-ups

Surfaced while documenting; none are regressions introduced by this branch except the first, and all are judged non-blocking.

1. Unbounded frame length (new in this branch). Host.ProcessInvocation2 and StreamingChannel.ReadOneResponseFrame both call ReadBytes(frameLength - header) with no upper bound, so a corrupt or hostile length allocates up to ~2 GB before anything validates it. Low severity under the trusted-peer model, but a MaxFrameBytes guard is cheap and worth a follow-up.
2. ZkProtocol.CryptRand is not cryptographically random (pre-existing since 2.0.0). It uses new Random(DateTime.Now.Millisecond) — roughly 1000 possible seeds — for salts, ephemerals and session-key material. docs/security.md now states this limitation plainly and recommends tunnelling anything crossing an untrusted network rather than implying audited-SRP strength.
3. IsDebugEnabled() returns true for any custom ILog (pre-existing). Injecting a Serilog or MEL adapter makes ServiceWire build every debug string unconditionally, including base64 payloads on ZK connections — a hot-path cost and a place secrets can reach a log. Documented as a caveat in docs/observability.md.
4. Stats and Logger resolve their default directory differently (pre-existing). Stats uses Assembly.GetEntryAssembly().Location, which can be null and is empty under single-file publish, so new Stats() can throw where new Logger() does not.

One decision worth a look

The README is packed into the NuGet package, so the hero image uses an absolute raw.githubusercontent.com/.../master/... URL. That renders on GitHub today but 404s until this branch merges to master, and nuget.org may not render SVG at all. A PNG would be safer for the NuGet surface if we want it guaranteed.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
1 Accepted issue

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud