Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -621,6 +621,13 @@ jobs:
lib/netstd/Tests/codegen/run-NetStd-Codegen-Tests.ps1 `
-TargetVersions @("net${{ matrix.dotnet-version }}")

- name: Run netstd codegen tests with the isolated option
shell: pwsh
run: |
lib/netstd/Tests/codegen/run-NetStd-Codegen-Tests.ps1 `
-TargetVersions @("net${{ matrix.dotnet-version }}") `
-Isolated

lib-haxe-codegen:
needs: [compiler]
runs-on: ubuntu-24.04
Expand Down
392 changes: 299 additions & 93 deletions compiler/cpp/src/thrift/generate/t_netstd_generator.cc

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions compiler/cpp/src/thrift/generate/t_netstd_generator.h
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ using std::vector;

static const string DEEP_COPY_METHOD_NAME = "DeepCopy";
static const string CANCELLATION_TOKEN_NAME = "cancellationToken";
static const string CALL_CONTEXT_NAME = "callContext";

class t_netstd_generator : public t_oop_generator
{
Expand All @@ -64,6 +65,7 @@ class t_netstd_generator : public t_oop_generator
bool is_wcf_enabled() const;
bool is_hashcode_enabled() const;
bool is_serialize_enabled() const;
bool is_isolated_enabled() const;
bool is_union_enabled() const;

// overrides
Expand Down Expand Up @@ -135,11 +137,18 @@ class t_netstd_generator : public t_oop_generator
static const int MODE_FULL_DECL = 0x00;
static const int MODE_NO_RETURN = 0x01;
static const int MODE_NO_ARGS = 0x02;
static const int MODE_CALL_CONTEXT = 0x04;
static const int MODE_NO_TOKEN = 0x08;

string type_name(t_type* ttype, bool with_namespace = true);
string base_type_name(t_base_type* tbase);
string declare_field(t_field* tfield, bool init = false, bool allow_nullable = true, string prefix = "");
string function_signature_async(t_function* tfunction, string prefix = "", int mode = MODE_FULL_DECL);
string async_method_name(t_function* tfunction, string prefix = "");
bool hides_base_client_member(t_function* tfunction);
string free_parameter_name(t_function* tfunction, string wanted, const string& also_taken);
string context_variable_name(t_function* tfunction);
string timeout_cause_name(t_function* tfunction);
string function_signature(t_function* tfunction, string prefix = "");
string argument_list(t_struct* tstruct, bool with_types = true);
string type_to_enum(t_type* ttype);
Expand Down Expand Up @@ -173,6 +182,7 @@ class t_netstd_generator : public t_oop_generator
bool hashcode_;
bool serialize_;
bool wcf_;
bool isolated_;
bool use_pascal_case_properties;
bool suppress_deepcopy;
int target_net_version; // 0 = any, 6 = net6, 8 = net8, etc.
Expand Down
58 changes: 58 additions & 0 deletions compiler/cpp/tests/netstd/t_netstd_generator_isolated_tests.cc
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
// Licensed to the Apache Software Foundation(ASF) under one
// or more contributor license agreements.See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.

#include "../catch/catch.hpp"
#include <thrift/parse/t_program.h>
#include <thrift/generate/t_netstd_generator.h>

// The isolated client generation is opt-in: without the option the generator must keep producing
// the shared-protocol clients, so the flag has to default to off.
TEST_CASE("t_netstd_generator keeps isolated client generation off by default", "[initialization]")
{
t_program program("IsolatedTest.thrift", "netstd");
map<string, string> parsed_options;
string option_string = "";

t_netstd_generator* gen = nullptr;
REQUIRE_NOTHROW(gen = new t_netstd_generator(&program, parsed_options, option_string));
REQUIRE_FALSE(gen->is_isolated_enabled());
delete gen;
}

TEST_CASE("t_netstd_generator enables isolated client generation with the isolated option", "[initialization]")
{
t_program program("IsolatedTest.thrift", "netstd");
map<string, string> parsed_options = { { "isolated", "" }, { "net10", "" } };
string option_string = "";

t_netstd_generator* gen = nullptr;
REQUIRE_NOTHROW(gen = new t_netstd_generator(&program, parsed_options, option_string));
REQUIRE(gen->is_isolated_enabled());
REQUIRE_FALSE(gen->is_wcf_enabled());
delete gen;
}

TEST_CASE("t_netstd_generator still rejects unknown options next to isolated", "[initialization]")
{
t_program program("IsolatedTest.thrift", "netstd");
map<string, string> parsed_options = { { "isolated", "" }, { "bogus", "" } };
string option_string = "";

t_netstd_generator* gen = nullptr;
REQUIRE_THROWS(gen = new t_netstd_generator(&program, parsed_options, option_string));
delete gen;
}
1 change: 1 addition & 0 deletions lib/netstd/Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ EXTRA_DIST = \
Thrift/GlobalSuppressions.cs \
Thrift/TApplicationException.cs \
Thrift/TBaseClient.cs \
Thrift/TCallContext.cs \
Thrift/TConfiguration.cs \
Thrift/TException.cs \
Thrift/Thrift.csproj \
Expand Down
138 changes: 138 additions & 0 deletions lib/netstd/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ The library ships as two packages so that non-web projects no longer pull in the
or
- Build with scripts

The test projects under `Tests/Thrift.Compile.Tests` generate their code with the compiler they find first, so rebuild
the compiler after changing a generator. An outdated binary produces code that no longer matches the library and
fails with confusing compile errors.

## How to build on Unix/Linux
- Ensure you have a suitable .NET Core SDK installed, or use the [Ubuntu docker image](../../build/docker/README.md)
- Follow common automake build practice: `./ bootstrap && ./ configure && make`
Expand Down Expand Up @@ -73,6 +77,140 @@ Because of the different environment requirements, migration from C# takes sligh
- In case you are using Thrift server event handlers: the `SetEventHandler` method now starts with an uppercase letter
- and you will also have to revise the method names of all `TServerEventHandler` descendants you have in your code

# Isolated clients (overlapping calls)

A generated client normally shares one protocol, and with it one transport, between all of its calls. That is fine for
sequential use, but asynchronous calls that overlap can corrupt each other's request and response data. For transports
that can keep request and response state per call, the generator offers an opt-in `isolated` option:

```bash
thrift -gen netstd:isolated my.thrift
```

The default output is unchanged. With `isolated`, the generated `Client` keeps its constructors that take protocols and
gains a constructor that takes a call-isolated transport and a protocol factory. The constructor you choose decides how
the client behaves:

```csharp
// shared protocols, exactly as without the option (socketTransport: any TTransport, for example a TSocketTransport)
var legacy = new MyService.Client(new TBinaryProtocol(socketTransport));

// per-call transport view and protocol for every call
var transport = new THttpTransport(new Uri("http://localhost:9090/thrift"), new TConfiguration());
using var client = new MyService.Client(transport, new TBinaryProtocol.Factory());

// these calls may overlap
var a = client.add(1, 2);
var b = client.add(3, 4);
await Task.WhenAll(a, b);
```

When a service extends another service, the base service needs the `isolated` option as well, because the client of
the derived service builds on the client of the base service. Generate the included IDL files together with `-r`, or
regenerate the base service separately with the option. A client generated with `isolated` over a base client that was
generated without it does not compile.

Call-isolated transports implement `ICallIsolatedTransport`: `THttpTransport` and `TMemoryBufferTransport`, plus
`TIsolatedBufferedTransport` and `TIsolatedFramedTransport`, which wrap another call-isolated transport. The isolated
layers only accept an `ICallIsolatedTransport`, so stream-based transports cannot be combined with them. Stream
transports share ordered input and are not suitable for overlapping calls. A transport whose call views need
asynchronous setup implements `IAsyncCallIsolatedTransport`; the client then creates each view asynchronously.

`client.IsCallIsolated` tells which mode a client is in. A client built with a call-isolated transport has no shared
protocols, so its `InputProtocol` and `OutputProtocol` properties throw.

The legacy `TBufferedTransport` and `TFramedTransport` are not call-isolated. Wrapping a `THttpTransport` in one of
them and passing the result to the call-isolated constructor does not compile, and that is intended: it is not
silently ignored. Use `TIsolatedBufferedTransport` or `TIsolatedFramedTransport` instead.

## What is shared and what is per call

Shared by all calls of a client: the transport object and its configuration (for `THttpTransport` that is the
`HttpClient`, its headers, `ContentType`, `ConnectTimeout` and `PerCallTimeout`), the protocol factory and the counter
that hands out sequence IDs.

Created for every call and released with it: the transport view with its request buffer and its response, the
protocol, the sequence ID, and the cancellation token and timeout of the call.

## Multiplexed protocol

The constructor takes a protocol factory, and the factory decides what each call's protocol looks like. To address a
service on a multiplexed server, return a `TMultiplexedProtocol` from the factory:

```csharp
class MultiplexedFactory : TProtocolFactory
{
public override TProtocol GetProtocol(TTransport trans) =>
new TMultiplexedProtocol(new TBinaryProtocol(trans), "MyService");
}

using var client = new MyService.Client(transport, new MultiplexedFactory());
```

## Split send and receive

Besides the high-level methods, the client exposes `send_<name>` and `recv_<name>`. Without a context they use the
shared protocols, as before. For an isolated client there is a second overload of each that takes the `TCallContext` of
the call, so replies can be received in any order:

```csharp
using var first = client.CreateCallContext();
using var second = client.CreateCallContext();

await client.send_add(first, 1, 2);
await client.send_add(second, 3, 4);

var r2 = await client.recv_add(second);
var r1 = await client.recv_add(first);
```

The overloads that take a context have no `CancellationToken` parameter: the call's cancellation token and timeout are
those of its context.

## Timeouts and cancellation

Two timeouts can apply to a call. A transport can declare a default for all of its calls, for example
`THttpTransport.PerCallTimeout`, and one call can be given a tighter one of its own. Both are linked with the
cancellation token you pass, and the shortest bound wins. A per-call timeout cannot loosen the transport's.

```csharp
var transport = new THttpTransport(new Uri("http://localhost:9090/thrift"), new TConfiguration())
{
PerCallTimeout = TimeSpan.FromSeconds(60),
ConnectTimeout = 60000, // milliseconds, see below
};
using var client = new MyService.Client(transport, new TBinaryProtocol.Factory());

// this call is bounded by 5 seconds instead of 60
using var context = client.CreateCallContext(TimeSpan.FromSeconds(5));
await client.send_add(context, 1, 2);
var sum = await client.recv_add(context);
```

The clock of a call runs from the creation of its context until the context is disposed, so for split calls it covers
the time between send and receive. A call that exceeds its timeout fails with a `TTransportException` of type
`TimedOut`. A call that the caller cancelled fails as cancelled instead, so the two can be told apart. Neither affects
any other call.

A third limit applies to every request that `THttpTransport` sends: the timeout of its `HttpClient`, which you set
with `ConnectTimeout` (30 seconds by default). It is not the timeout of the call, so a `PerCallTimeout` that is longer
does not extend it. If you need calls to run longer than 30 seconds, raise `ConnectTimeout` as well, as in the example
above. When this limit elapses, the request fails with a `TTransportException` of type `TimedOut`, like the other
timeouts, and not as a cancellation by the caller. The message text of such an exception differs between .NET and
.NET Framework.

## Lifetime and ownership

- The high-level methods create a context, use it for exactly one call and dispose it on success, failure and
cancellation. One-way calls release their context after the request has been sent. A call whose token is already
cancelled creates no transport view at all.
- A context created with `CreateCallContext()` is owned by the caller. Dispose it once its reply has been received, or
when the call is abandoned. Disposing a context releases only that call's transport view.
- Each call gets a sequence ID that is unique within the client. A reply whose ID differs from the ID of its call is
rejected with a `TApplicationException` of type `BadSequenceId`.
- The client owns the shared transport. Disposing the client disposes the transport and rejects new calls, so keep the
client alive until all of its calls have finished.

# Fuzzing

We use [SharpFuzz](https://github.com/Metalnem/sharpfuzz) (and its libfuzzer variant) to fuzz the Thrift protocol parsers. This is **not** integrated with oss-fuzz, so all fuzzing must be run locally. **Supported platform: Linux only.**
Expand Down
39 changes: 39 additions & 0 deletions lib/netstd/Tests/Thrift.Compile.Tests/IsolatedCall.thrift
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

// Fixture for the netstd:isolated generator option (per-call TCallContext clients)

namespace * IsolatedCall

exception Oops {
1: string why
}

service IsolatedBase {
i32 ping(1: i32 value)
}

service IsolatedService extends IsolatedBase {
void nothing()
string echo(1: string text) throws (1: Oops oops)
i32 add(1: i32 a, 2: i32 b)
// argument names that collide with generated parameters
i32 collide(1: i32 callContext, 2: i32 cancellationToken)
oneway void fire(1: string text)
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/

// Fixture for the netstd:isolated option: the namespace of the service also defines a type named Exception.
// Generated code that took Exception to mean System.Exception would compile and then misbehave at run time.

namespace * IsolatedExceptionName

exception Exception {
1: string why
}

service Timeouts {
i32 add(1: i32 a, 2: i32 b) throws (1: Exception e)
}
Loading
Loading