<commit_before>% Bond-over-gRPC

# About #

Bond-over-gRPC provides code generation from Bond IDL service definitions
to send Bond objects via gRPC. The gRPC functionality supercedes the
(now deprecated) Bond Comm framework.

# Features #

## Defining Services ##

The Bond IDL has been extended to support the definition of
[services](compiler.html#service-definition) and
[generic services](compiler.html#generic-service). These definitions are
used by the Bond compiler to generate:

* service stubs that can be used as the base for implementing services'
  methods
* proxy stubs that can be used by clients to invoke those methods

To generate these stubs, pass the `--grpc` flag to `gbc` (the Bond compiler
tool).

Note that gRPC doesn't provide a messaging pattern that matches
the semantics of methods with a return type of `nothing`; to compensate,
`gbc` provides generated wrappers to simulate the appropriate semantics.

# Implementations #

Bond-over-gRPC is available for C# now and will be released for C++ in a
few weeks.

## Bond-over-gRPC for C# ##

Given a service definition like the following:

    service ExampleService
    {
        ExampleResponse Method(ExampleRequest);
    }

`gbc` will produce stubs for gRPC with the `--grpc` flag:

    gbc c# --grpc example.bond

The service stub allows for the definition of the service implementation like this:

    public class ExampleService : ExampleServiceBase
    {
        public override async Task<IMessage<ExampleResponse>> Method(IMessage<ExampleRequest> param, ServerCallContext context)
        {
            ExampleRequest request = param.Payload.Deserialize();

            // Service business logic

            var response = new ExampleResponse();
            return Message.From(response);
        }
    }

The proxy stub allows the client to invoke the remote service method like this:

    var channel = new Channel("localhost", Port, ChannelCredentials.Insecure);
    var client = new ExampleClient(channel);

    var request = new ExampleRequest();
    IMessage<ExampleResponse> responseMessage = await client.Method(request);
    var response = responseMessage.Payload.Deserialize().Payload;

For more information about gRPC in C#, take a look at the
[gRPC C# tutorial](http://www.grpc.io/docs/tutorials/basic/csharp.html).
Note that the singatures generated by `gbc` are slightly different from the
ones in the gRPC tutorial: on the service side, the request is wrapped in
`IMessage<T>` and on the client side, the response is wrapped in
`IMessage<T>`. This allows for better control over the time of
deserialization and also helps prevent slicing when using polymorphic Bond
types.

There is a [Bond-over-gRPC standalone example project](https://github.com/Microsoft/bond-grpc-examples).

See also the following example:

- `examples/cs/grpc/pingpong`
<commit_msg>[C# gRPC] Expand and improve documentation<commit_after>% Bond-over-gRPC

# About #

Bond-over-gRPC provides code generation from Bond IDL service definitions
to send Bond objects via [gRPC](http://www.grpc.io/) The gRPC functionality
supercedes the (now deprecated) Bond Comm framework.

# Features #

## Defining Services ##

The Bond IDL has been extended to support the definition of
[services](compiler.html#service-definition) and
[generic services](compiler.html#generic-service). These definitions are
used by the Bond compiler to generate:

* service stubs that can be used as the base for implementing services'
  methods
* proxy stubs that can be used by clients to invoke those methods

To generate these stubs, pass the `--grpc` flag to `gbc` (the Bond compiler
tool).

Note that gRPC doesn't provide a messaging pattern that matches
the semantics of methods with a return type of `nothing`; to compensate,
`gbc` provides generated wrappers to simulate the appropriate semantics.

Also note that Bond-over-gRPC does not yet provide interfaces for gRPC's
streaming; this functionality will be added in the coming months.

# Implementations #

Bond-over-gRPC is available for C# now and will be released for C++ in a
few weeks.

## Bond-over-gRPC for C# ##

Given a service definition like the following:

    service Example
    {
        ExampleResponse ExampleMethod(ExampleRequest);
    }

`gbc` will produce stub code for gRPC with the `--grpc` flag:

    gbc c# --grpc example.bond

The key parts of the generated C# stub code are:
* A class with the name of the service (e.g.: `Example`), which encloses
  the server-side service stub, the client-side proxy stub, and some static
  methods and data members for initialization
* The service stub, which is named with the name of the service plus the suffix
  `Base` (e.g.: `Example.ExampleBase`). This service stub has
  abstract methods for each of the methods defined in the service IDL.
* The proxy stub, which is named with the name of the service plus the suffix
  `Client' (e.g.: `Example.ExampleClient`).

The service stub allows for the definition of the service implementation, with
the application business logic:

    public class ExampleServiceImpl : Example.ExampleBase
    {
        public override async Task<IMessage<ExampleResponse>> ExampleMethod(IMessage<ExampleRequest> param, ServerCallContext context)
        {
            ExampleRequest request = param.Payload.Deserialize();
            var response = new ExampleResponse();

            // Service business logic goes here

            return Message.From(response);
        }
    }

This service implementation is hooked up to a gRPC server as follows:

    var server = new Grpc.Core.Server
    {
        Services = { Example.BindService(new ExampleServiceImpl()) },
        Ports = { new Grpc.Core.ServerPort(ExampleHost, ExamplePort, Grpc.Core.ServerCredentials.Insecure) }
    };
    server.Start();

On the client side, the proxy stub establishes a connection to the server like this:

    var channel = new Grpc.Core.Channel(ExampleHost, ExamplePort, Grpc.Core.ChannelCredentials.Insecure);
    var client = new Example.ExampleClient(channel);

The proxy stub can then be used to make calls to the server as follows:

    var request = new ExampleRequest();
    IMessage<ExampleResponse> responseMessage = await client.Method(request);
    var response = responseMessage.Payload.Deserialize().Payload;

For more information about gRPC in C#, take a look at the
[gRPC C# tutorial](http://www.grpc.io/docs/tutorials/basic/csharp.html).
Note that the singatures generated by `gbc` are slightly different from the
ones in the gRPC tutorial: on the service side, the request is wrapped in
`IMessage<T>` and on the client side, the response is wrapped in
`IMessage<T>`. This allows for better control over the time of
deserialization and also helps prevent slicing when using polymorphic Bond
types. Note also that Bond-over-gRPC does not provide synchronous APIs in C#
by design.

There is a [Bond-over-gRPC standalone example project](https://github.com/Microsoft/bond-grpc-examples).

See also the following example:

- `examples/cs/grpc/pingpong`

{'fraction_non_alphanumeric': 0.07319148936170213, 'fraction_numerical': 0.0, 'mean_word_length': 3.955024595924104, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 3, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5184383', 'n_tokens_mistral': 1873, 'n_tokens_neox': 1819, 'n_words': 835}