gRPC transcoding public API

[JamesNK]

Background and Motivation

gRPC transcoding allows apps to expose gRPC services as if they were RESTful APIs.

Proposed API

namespace Microsoft.AspNetCore.Grpc.JsonTranscoding
{
    public sealed class GrpcJsonTranscodingOptions
    {
        public GrpcJsonSettings JsonSettings { get; set; }
        public Google.Protobuf.Reflection.TypeRegistry TypeRegistry { get; set; }
    }

    public sealed class GrpcJsonSettings
    {
        public bool WriteIndented { get; set; } = false;
        public bool WriteEnumsAsIntegers { get; set; } = false;
        public bool WriteInt64AsStrings { get; set; } = false;
        public bool SkipDefaultValues { get; set; } = false;
    }

    public sealed class GrpcJsonTranscodingMetadata
    {
        public GrpcTranscodingMetadata(Google.Protobuf.Reflection.MethodDescriptor methodDescriptor, Google.Api.HttpRule httpRule);

        public Google.Api.HttpRule HttpRule { get; }
        public Google.Protobuf.Reflection.MethodDescriptor MethodDescriptor { get; }
    }
}

namespace Microsoft.Extensions.DependencyInjection
{
    public static class GrpcTranscodingServiceExtensions
    {
        public static IGrpcServerBuilder AddJsonTranscoding(this IGrpcServerBuilder builder);
        public static IGrpcServerBuilder AddJsonTranscoding(this IGrpcServerBuilder builder, Action<GrpcJsonTranscodingOptions> configureOptions);
    }
}

Usage Examples

// Old and busted
services.AddGrpc(options =>
    {
        options.EnableDetailedErrors = true;
    });
services.AddGrpcJsonTranscoding(options =>
    {
        options.JsonSettings.WriteIndented = true;
    });

// New hotness
services
    .AddGrpc(options => options.EnableDetailedErrors = true)
    .AddJsonTranscoding(options => options.JsonSettings.WriteIndented = true);

// Maybe future?
services.AddGrpc()
   .AddJsonTranscoding()
   .AddJsonTranscoding<GreeterService>(options => options.JsonSettings.WriteIndented = true);

Alternative Designs

Risks

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[JamesNK]

Note: Will review in a separate meeting.

[halter73]

Api review:

• Change *Transcoding* -> *JsonTranscoding* in all APIs, namespaces and package names.
• Can TypeRegistry go on the main options type?
• Can we expose JsonSerializerOptions on JsonSettings?
  • Not for now
• JsonSettings -> GrpcJsonSettings
• WriteDefaultValues -> IgnoreDefaultValues (or SkipDefaultValues)
• Make extension method on IGrpcServerBuilder instead of IServiceCollection

+ namespace Microsoft.AspNetCore.Grpc.JsonTranscoding;
+
+ public sealed class GrpcJsonTranscodingOptions
+ {
+     public GrpcJsonSettings JsonSettings { get; set; }
+     public Google.Protobuf.Reflection.TypeRegistry TypeRegistry { get; set; }
+ }
+ 
+ public sealed class GrpcJsonSettings
+ {
+     public bool WriteIndented { get; set; } = false;
+     public bool WriteEnumsAsIntegers { get; set; } = false;
+     public bool WriteInt64AsStrings { get; set; } = false;
+     public bool IgnoreDefaultValues { get; set; } = false;
+ }
+ 
+ public sealed class GrpcJsonTranscodingMetadata
+ {
+     public GrpcTranscodingMetadata(Google.Protobuf.Reflection.MethodDescriptor methodDescriptor, Google.Api.HttpRule httpRule);
+ 
+     public Google.Api.HttpRule HttpRule { get; }
+     public Google.Protobuf.Reflection.MethodDescriptor MethodDescriptor { get; }
+ }
+ 
+ namespace Microsoft.Extensions.DependencyInjection;
+
+ public static class GrpcTranscodingServiceExtensions
+ {
+     public static IGrpcServerBuilder AddJsonTranscoding(this IGrpcServerBuilder builder);
+     public static IGrpcServerBuilder AddJsonTranscoding(this IGrpcServerBuilder builder, Action<GrpcJsonTranscodingOptions> configureOptions);
+ }