Motivation

Ignite 3 needs thin client drivers in different languages.

Description

This proposal lists design consideration and implementation details for Ignite 3 .NET Thin Client.

TargetFramework: .NET Standard 2.1

Ignite 3 is in the alpha stage, we don't know the final release date. Currently (September 2021) the only supported LTS version of .NET SDK is .NET Core 3.1, which implements netstandard2.1.

At the same time, newer SDKs (.NET 5 and upcoming .NET 6) don't introduce anything important for us. Essential performance-oriented APIs (Span<T>, Memory<T>, ref struct) and async network APIs are available in netstandard2.1.

There is also .NET Framework (Windows-only) which is a part of Windows and follows the same support policy (.NET Framework 4.8 is supposed to be supported for many years to come). We are not going to target this in alpha stages to simplify development.

When the release time comes:

• Look at supported versions of .NET and decide which ones to target.
• Add multi-targeting to our packages.
• Use conditional compilation, if necessary, to deal with unsupported APIs on older SDKs.

More info:

• https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-5-and-net-standard
• https://dotnet.microsoft.com/platform/support/policy/dotnet-framework

Namespaces and Assemblies

Use Apache.Ignite as the main assembly name and root namespace. We are not going to have thin/thick client separation or a standalone executable in 3.0.

Libraries

The only dependency is MessagePack-CSharp. The library is performant, lightweight, and has no transitive dependencies. Primitive APIs are based on Span<T> and Memory<T> and don't allocate (except for ReadString).

Async Socket IO

Ignite 2.x uses a custom async engine with a dedicated thread and manual event loop management.

This is no longer required because standard Socket API provides async methods (Socket.ConnectAsync, NetworkStream.ReadAsync and WriteAsync), and the event loop is handled by SocketAsyncEngine, which shares resources across multiple active sockets.

DotNetty was considered (a proven .NET port of Netty, used by Akka.Net), but it does not provide much improvement over the standard API for our use case.

Avoid Sync over Async In Ignite APIs

Do not provide synchronous wrappers for asynchronous API implementations. Example: do not provide ITable.Get method that simply calls ITable.GetAsync().GetAwaiter().GetResult(). Most of the APIs involve network IO and are implemented asynchronously.

Reasoning:

• Sync-over-async APIs can be misleading to the users, as explained here: https://devblogs.microsoft.com/pfxteam/should-i-expose-synchronous-wrappers-for-asynchronous-methods/
• Sync API variant is not needed, since C# and .NET went full async in recent years. async/await were added to C# in 2012, almost 10 years ago.
• Even some system APIs, like HttpClient, don't provide sync variants for most of the methods anymore.

Buffer Pooling

Buffer pooling is essential to reduce allocations and GC pressure when handling network IO. System.Buffers.ArrayPool<byte> should be used instead of allocating new byte arrays.

Note that ArrayPool had 1M elements limit that has been removed in .NET 6: https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-6/#buffering

Retry, Failover, KeepAlive

Adopt connection reliability proposals from 2.x:

• IEP-82 Thin Client Retry Policy
• IEP-83 Thin Client Keepalive

Code Style

Use default Microsoft code style, enforced by StyleCop analyzers (code won't compile if there is a violation).

Discussion Links

• IEP-78 .NET Thin Client for Ignite 3.0

Reference Links

• IEP-76: Thin Client Protocol for Ignite 3.0
• PoC: https://github.com/apache/ignite-3/pull/306

Tickets