diff options
Diffstat (limited to 'src/csharp/Grpc.Core/Interceptors')
6 files changed, 881 insertions, 0 deletions
diff --git a/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs b/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs new file mode 100644 index 0000000000..421b5d379e --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/CallInvokerExtensions.cs @@ -0,0 +1,144 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; +using System.Linq; +using Grpc.Core.Utils; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Extends the CallInvoker class to provide the interceptor facility on the client side. + /// This is an EXPERIMENTAL API. + /// </summary> + public static class CallInvokerExtensions + { + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the invoker with the given interceptor. + /// </summary> + /// <param name="invoker">The underlying invoker to intercept.</param> + /// <param name="interceptor">The interceptor to intercept calls to the invoker with.</param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "invoker.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted CallInvoker, effectively + /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this CallInvoker invoker, Interceptor interceptor) + { + return new InterceptingCallInvoker(invoker, interceptor); + } + + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the invoker with the given interceptors. + /// </summary> + /// <param name="invoker">The channel to intercept.</param> + /// <param name="interceptors"> + /// An array of interceptors to intercept the calls to the invoker with. + /// Control is passed to the interceptors in the order specified. + /// </param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "invoker.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted CallInvoker, effectively + /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this CallInvoker invoker, params Interceptor[] interceptors) + { + GrpcPreconditions.CheckNotNull(invoker, nameof(invoker)); + GrpcPreconditions.CheckNotNull(interceptors, nameof(interceptors)); + + foreach (var interceptor in interceptors.Reverse()) + { + invoker = Intercept(invoker, interceptor); + } + + return invoker; + } + + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the invoker with the given interceptor. + /// </summary> + /// <param name="invoker">The underlying invoker to intercept.</param> + /// <param name="interceptor"> + /// An interceptor delegate that takes the request metadata to be sent with an outgoing call + /// and returns a <see cref="Grpc.Core.Metadata" /> instance that will replace the existing + /// invocation metadata. + /// </param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by + /// building a chain like "invoker.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this CallInvoker invoker, Func<Metadata, Metadata> interceptor) + { + return new InterceptingCallInvoker(invoker, new MetadataInterceptor(interceptor)); + } + + private class MetadataInterceptor : Interceptor + { + readonly Func<Metadata, Metadata> interceptor; + + /// <summary> + /// Creates a new instance of MetadataInterceptor given the specified interceptor function. + /// </summary> + public MetadataInterceptor(Func<Metadata, Metadata> interceptor) + { + this.interceptor = GrpcPreconditions.CheckNotNull(interceptor, nameof(interceptor)); + } + + private ClientInterceptorContext<TRequest, TResponse> GetNewContext<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class + { + var metadata = context.Options.Headers ?? new Metadata(); + return new ClientInterceptorContext<TRequest, TResponse>(context.Method, context.Host, context.Options.WithHeaders(interceptor(metadata))); + } + + public override TResponse BlockingUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, BlockingUnaryCallContinuation<TRequest, TResponse> continuation) + { + return continuation(request, GetNewContext(context)); + } + + public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncUnaryCallContinuation<TRequest, TResponse> continuation) + { + return continuation(request, GetNewContext(context)); + } + + public override AsyncServerStreamingCall<TResponse> AsyncServerStreamingCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncServerStreamingCallContinuation<TRequest, TResponse> continuation) + { + return continuation(request, GetNewContext(context)); + } + + public override AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncClientStreamingCallContinuation<TRequest, TResponse> continuation) + { + return continuation(GetNewContext(context)); + } + + public override AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncDuplexStreamingCallContinuation<TRequest, TResponse> continuation) + { + return continuation(GetNewContext(context)); + } + } + } +} diff --git a/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs b/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs new file mode 100644 index 0000000000..00b2fa8bec --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/ChannelExtensions.cs @@ -0,0 +1,88 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Provides extension methods to make it easy to register interceptors on Channel objects. + /// This is an EXPERIMENTAL API. + /// </summary> + public static class ChannelExtensions + { + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the channel with the given interceptor. + /// </summary> + /// <param name="channel">The channel to intercept.</param> + /// <param name="interceptor">The interceptor to intercept the channel with.</param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "channel.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted channel, effectively + /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this Channel channel, Interceptor interceptor) + { + return new DefaultCallInvoker(channel).Intercept(interceptor); + } + + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the channel with the given interceptors. + /// </summary> + /// <param name="channel">The channel to intercept.</param> + /// <param name="interceptors"> + /// An array of interceptors to intercept the channel with. + /// Control is passed to the interceptors in the order specified. + /// </param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "channel.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted channel, effectively + /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this Channel channel, params Interceptor[] interceptors) + { + return new DefaultCallInvoker(channel).Intercept(interceptors); + } + + /// <summary> + /// Returns a <see cref="Grpc.Core.CallInvoker" /> instance that intercepts + /// the invoker with the given interceptor. + /// </summary> + /// <param name="channel">The channel to intercept.</param> + /// <param name="interceptor"> + /// An interceptor delegate that takes the request metadata to be sent with an outgoing call + /// and returns a <see cref="Grpc.Core.Metadata" /> instance that will replace the existing + /// invocation metadata. + /// </param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by + /// building a chain like "channel.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static CallInvoker Intercept(this Channel channel, Func<Metadata, Metadata> interceptor) + { + return new DefaultCallInvoker(channel).Intercept(interceptor); + } + } +} diff --git a/src/csharp/Grpc.Core/Interceptors/ClientInterceptorContext.cs b/src/csharp/Grpc.Core/Interceptors/ClientInterceptorContext.cs new file mode 100644 index 0000000000..de06a77077 --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/ClientInterceptorContext.cs @@ -0,0 +1,65 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; +using System.Reflection; +using System.Threading.Tasks; +using Grpc.Core.Internal; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Carries along the context associated with intercepted invocations on the client side. + /// This is an EXPERIMENTAL API. + /// </summary> + public struct ClientInterceptorContext<TRequest, TResponse> + where TRequest : class + where TResponse : class + { + /// <summary> + /// Creates a new instance of <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}" /> + /// with the specified method, host, and call options. + /// </summary> + /// <param name="method">A <see cref="Grpc.Core.Method{TRequest, TResponse}"/> object representing the method to be invoked.</param> + /// <param name="host">The host to dispatch the current call to.</param> + /// <param name="options">A <see cref="Grpc.Core.CallOptions"/> instance containing the call options of the current call.</param> + public ClientInterceptorContext(Method<TRequest, TResponse> method, string host, CallOptions options) + { + Method = method; + Host = host; + Options = options; + } + + /// <summary> + /// Gets the <see cref="Grpc.Core.Method{TRequest, TResponse}"/> instance + /// representing the method to be invoked. + /// </summary> + public Method<TRequest, TResponse> Method { get; } + + /// <summary> + /// Gets the host that the currect invocation will be dispatched to. + /// </summary> + public string Host { get; } + + /// <summary> + /// Gets the <see cref="Grpc.Core.CallOptions"/> structure representing the + /// call options associated with the current invocation. + /// </summary> + public CallOptions Options { get; } + } +} diff --git a/src/csharp/Grpc.Core/Interceptors/InterceptingCallInvoker.cs b/src/csharp/Grpc.Core/Interceptors/InterceptingCallInvoker.cs new file mode 100644 index 0000000000..84d2a0b958 --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/InterceptingCallInvoker.cs @@ -0,0 +1,96 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; +using Grpc.Core.Utils; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Decorates an underlying <see cref="Grpc.Core.CallInvoker" /> to + /// intercept calls through a given interceptor. + /// </summary> + internal class InterceptingCallInvoker : CallInvoker + { + readonly CallInvoker invoker; + readonly Interceptor interceptor; + + /// <summary> + /// Creates a new instance of <see cref="Grpc.Core.Interceptors.InterceptingCallInvoker" /> + /// with the given underlying invoker and interceptor instances. + /// </summary> + public InterceptingCallInvoker(CallInvoker invoker, Interceptor interceptor) + { + this.invoker = GrpcPreconditions.CheckNotNull(invoker, nameof(invoker)); + this.interceptor = GrpcPreconditions.CheckNotNull(interceptor, nameof(interceptor)); + } + + /// <summary> + /// Intercepts a simple blocking call with the registered interceptor. + /// </summary> + public override TResponse BlockingUnaryCall<TRequest, TResponse>(Method<TRequest, TResponse> method, string host, CallOptions options, TRequest request) + { + return interceptor.BlockingUnaryCall( + request, + new ClientInterceptorContext<TRequest, TResponse>(method, host, options), + (req, ctx) => invoker.BlockingUnaryCall(ctx.Method, ctx.Host, ctx.Options, req)); + } + + /// <summary> + /// Intercepts a simple asynchronous call with the registered interceptor. + /// </summary> + public override AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(Method<TRequest, TResponse> method, string host, CallOptions options, TRequest request) + { + return interceptor.AsyncUnaryCall( + request, + new ClientInterceptorContext<TRequest, TResponse>(method, host, options), + (req, ctx) => invoker.AsyncUnaryCall(ctx.Method, ctx.Host, ctx.Options, req)); + } + + /// <summary> + /// Intercepts an asynchronous server streaming call with the registered interceptor. + /// </summary> + public override AsyncServerStreamingCall<TResponse> AsyncServerStreamingCall<TRequest, TResponse>(Method<TRequest, TResponse> method, string host, CallOptions options, TRequest request) + { + return interceptor.AsyncServerStreamingCall( + request, + new ClientInterceptorContext<TRequest, TResponse>(method, host, options), + (req, ctx) => invoker.AsyncServerStreamingCall(ctx.Method, ctx.Host, ctx.Options, req)); + } + + /// <summary> + /// Intercepts an asynchronous client streaming call with the registered interceptor. + /// </summary> + public override AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCall<TRequest, TResponse>(Method<TRequest, TResponse> method, string host, CallOptions options) + { + return interceptor.AsyncClientStreamingCall( + new ClientInterceptorContext<TRequest, TResponse>(method, host, options), + ctx => invoker.AsyncClientStreamingCall(ctx.Method, ctx.Host, ctx.Options)); + } + + /// <summary> + /// Intercepts an asynchronous duplex streaming call with the registered interceptor. + /// </summary> + public override AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCall<TRequest, TResponse>(Method<TRequest, TResponse> method, string host, CallOptions options) + { + return interceptor.AsyncDuplexStreamingCall( + new ClientInterceptorContext<TRequest, TResponse>(method, host, options), + ctx => invoker.AsyncDuplexStreamingCall(ctx.Method, ctx.Host, ctx.Options)); + } + } +} diff --git a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs new file mode 100644 index 0000000000..56a30c34af --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs @@ -0,0 +1,406 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; +using System.Reflection; +using System.Threading.Tasks; +using Grpc.Core.Internal; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Serves as the base class for gRPC interceptors. + /// This is an EXPERIMENTAL API. + /// </summary> + public abstract class Interceptor + { + /// <summary> + /// Represents a continuation for intercepting simple blocking invocations. + /// A delegate of this type is passed to the BlockingUnaryCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// context and request values as it sees fit. + /// </summary> + /// <typeparam name="TRequest">Request message type for this invocation.</typeparam> + /// <typeparam name="TResponse">Response message type for this invocation.</typeparam> + /// <param name="request">The request value to continue the invocation with.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// instance to pass to the next step in the invocation process. + /// </param> + /// <returns> + /// The response value of the invocation to return to the caller. + /// The interceptor can choose to return the return value of the + /// continuation delegate or an arbitrary value as it sees fit. + /// </returns> + public delegate TResponse BlockingUnaryCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class; + + /// <summary> + /// Represents a continuation for intercepting simple asynchronous invocations. + /// A delegate of this type is passed to the AsyncUnaryCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. + /// </summary> + /// <typeparam name="TRequest">Request message type for this invocation.</typeparam> + /// <typeparam name="TResponse">Response message type for this invocation.</typeparam> + /// <param name="request">The request value to continue the invocation with.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// instance to pass to the next step in the invocation process. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncUnaryCall{TResponse}" /> + /// representing an asynchronous invocation of a unary RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// </returns> + public delegate AsyncUnaryCall<TResponse> AsyncUnaryCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class; + + /// <summary> + /// Represents a continuation for intercepting asynchronous server-streaming invocations. + /// A delegate of this type is passed to the AsyncServerStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. + /// </summary> + /// <typeparam name="TRequest">Request message type for this invocation.</typeparam> + /// <typeparam name="TResponse">Response message type for this invocation.</typeparam> + /// <param name="request">The request value to continue the invocation with.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// instance to pass to the next step in the invocation process. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncServerStreamingCall{TResponse}" /> + /// representing an asynchronous invocation of a server-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// </returns> + public delegate AsyncServerStreamingCall<TResponse> AsyncServerStreamingCallContinuation<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class; + + /// <summary> + /// Represents a continuation for intercepting asynchronous client-streaming invocations. + /// A delegate of this type is passed to the AsyncClientStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. + /// </summary> + /// <typeparam name="TRequest">Request message type for this invocation.</typeparam> + /// <typeparam name="TResponse">Response message type for this invocation.</typeparam> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// instance to pass to the next step in the invocation process. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncClientStreamingCall{TRequest, TResponse}" /> + /// representing an asynchronous invocation of a client-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// </returns> + public delegate AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCallContinuation<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class; + + /// <summary> + /// Represents a continuation for intercepting asynchronous duplex invocations. + /// A delegate of this type is passed to the AsyncDuplexStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. + /// </summary> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// instance to pass to the next step in the invocation process. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncDuplexStreamingCall{TRequest, TResponse}" /> + /// representing an asynchronous invocation of a duplex-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// </returns> + public delegate AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCallContinuation<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context) + where TRequest : class + where TResponse : class; + + /// <summary> + /// Intercepts a blocking invocation of a simple remote call. + /// </summary> + /// <param name="request">The request message of the invocation.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// associated with the current invocation. + /// </param> + /// <param name="continuation"> + /// The callback that continues the invocation process. + /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. + /// </param> + /// <returns> + /// The response message of the current invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or an arbitrary + /// value as it sees fit. + /// </returns> + public virtual TResponse BlockingUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, BlockingUnaryCallContinuation<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(request, context); + } + + /// <summary> + /// Intercepts an asynchronous invocation of a simple remote call. + /// </summary> + /// <param name="request">The request message of the invocation.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// associated with the current invocation. + /// </param> + /// <param name="continuation"> + /// The callback that continues the invocation process. + /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncUnaryCall{TResponse}" /> + /// representing an asynchronous unary invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// </returns> + public virtual AsyncUnaryCall<TResponse> AsyncUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncUnaryCallContinuation<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(request, context); + } + + /// <summary> + /// Intercepts an asynchronous invocation of a streaming remote call. + /// </summary> + /// <param name="request">The request message of the invocation.</param> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// associated with the current invocation. + /// </param> + /// <param name="continuation"> + /// The callback that continues the invocation process. + /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncServerStreamingCall{TResponse}" /> + /// representing an asynchronous server-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// </returns> + public virtual AsyncServerStreamingCall<TResponse> AsyncServerStreamingCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, AsyncServerStreamingCallContinuation<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(request, context); + } + + /// <summary> + /// Intercepts an asynchronous invocation of a client streaming call. + /// </summary> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// associated with the current invocation. + /// </param> + /// <param name="continuation"> + /// The callback that continues the invocation process. + /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// context argument, or substitute as it sees fit. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncClientStreamingCall{TRequest, TResponse}" /> + /// representing an asynchronous client-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// </returns> + public virtual AsyncClientStreamingCall<TRequest, TResponse> AsyncClientStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncClientStreamingCallContinuation<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(context); + } + + /// <summary> + /// Intercepts an asynchronous invocation of a duplex streaming call. + /// </summary> + /// <param name="context"> + /// The <see cref="Grpc.Core.Interceptors.ClientInterceptorContext{TRequest, TResponse}"/> + /// associated with the current invocation. + /// </param> + /// <param name="continuation"> + /// The callback that continues the invocation process. + /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// context argument, or substitute as it sees fit. + /// </param> + /// <returns> + /// An instance of <see cref="Grpc.Core.AsyncDuplexStreamingCall{TRequest, TResponse}" /> + /// representing an asynchronous duplex-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// </returns> + public virtual AsyncDuplexStreamingCall<TRequest, TResponse> AsyncDuplexStreamingCall<TRequest, TResponse>(ClientInterceptorContext<TRequest, TResponse> context, AsyncDuplexStreamingCallContinuation<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(context); + } + + /// <summary> + /// Server-side handler for intercepting and incoming unary call. + /// </summary> + /// <typeparam name="TRequest">Request message type for this method.</typeparam> + /// <typeparam name="TResponse">Response message type for this method.</typeparam> + /// <param name="request">The request value of the incoming invocation.</param> + /// <param name="context"> + /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing + /// the context of the invocation. + /// </param> + /// <param name="continuation"> + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and return the response value of + /// the RPC. The interceptor can choose to call it zero or more times + /// at its discretion. + /// </param> + /// <returns> + /// A future representing the response value of the RPC. The interceptor + /// can simply return the return value from the continuation intact, + /// or an arbitrary response value as it sees fit. + /// </returns> + public virtual Task<TResponse> UnaryServerHandler<TRequest, TResponse>(TRequest request, ServerCallContext context, UnaryServerMethod<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(request, context); + } + + /// <summary> + /// Server-side handler for intercepting client streaming call. + /// </summary> + /// <typeparam name="TRequest">Request message type for this method.</typeparam> + /// <typeparam name="TResponse">Response message type for this method.</typeparam> + /// <param name="requestStream">The request stream of the incoming invocation.</param> + /// <param name="context"> + /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing + /// the context of the invocation. + /// </param> + /// <param name="continuation"> + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and return the response value of + /// the RPC. The interceptor can choose to call it zero or more times + /// at its discretion. + /// </param> + /// <returns> + /// A future representing the response value of the RPC. The interceptor + /// can simply return the return value from the continuation intact, + /// or an arbitrary response value as it sees fit. The interceptor has + /// the ability to wrap or substitute the request stream when calling + /// the continuation. + /// </returns> + public virtual Task<TResponse> ClientStreamingServerHandler<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, ServerCallContext context, ClientStreamingServerMethod<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(requestStream, context); + } + + /// <summary> + /// Server-side handler for intercepting server streaming call. + /// </summary> + /// <typeparam name="TRequest">Request message type for this method.</typeparam> + /// <typeparam name="TResponse">Response message type for this method.</typeparam> + /// <param name="request">The request value of the incoming invocation.</param> + /// <param name="responseStream">The response stream of the incoming invocation.</param> + /// <param name="context"> + /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing + /// the context of the invocation. + /// </param> + /// <param name="continuation"> + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and the interceptor can choose to + /// call it zero or more times at its discretion. The interceptor has + /// the ability to wrap or substitute the request value and the response stream + /// when calling the continuation. + /// </param> + public virtual Task ServerStreamingServerHandler<TRequest, TResponse>(TRequest request, IServerStreamWriter<TResponse> responseStream, ServerCallContext context, ServerStreamingServerMethod<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(request, responseStream, context); + } + + /// <summary> + /// Server-side handler for intercepting bidirectional streaming calls. + /// </summary> + /// <typeparam name="TRequest">Request message type for this method.</typeparam> + /// <typeparam name="TResponse">Response message type for this method.</typeparam> + /// <param name="requestStream">The request stream of the incoming invocation.</param> + /// <param name="responseStream">The response stream of the incoming invocation.</param> + /// <param name="context"> + /// An instance of <see cref="Grpc.Core.ServerCallContext" /> representing + /// the context of the invocation. + /// </param> + /// <param name="continuation"> + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and the interceptor can choose to + /// call it zero or more times at its discretion. The interceptor has + /// the ability to wrap or substitute the request and response streams + /// when calling the continuation. + /// </param> + public virtual Task DuplexStreamingServerHandler<TRequest, TResponse>(IAsyncStreamReader<TRequest> requestStream, IServerStreamWriter<TResponse> responseStream, ServerCallContext context, DuplexStreamingServerMethod<TRequest, TResponse> continuation) + where TRequest : class + where TResponse : class + { + return continuation(requestStream, responseStream, context); + } + } +} diff --git a/src/csharp/Grpc.Core/Interceptors/ServerServiceDefinitionExtensions.cs b/src/csharp/Grpc.Core/Interceptors/ServerServiceDefinitionExtensions.cs new file mode 100644 index 0000000000..b9b53247ce --- /dev/null +++ b/src/csharp/Grpc.Core/Interceptors/ServerServiceDefinitionExtensions.cs @@ -0,0 +1,82 @@ +#region Copyright notice and license + +// Copyright 2018 gRPC authors. +// +// Licensed 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. + +#endregion + +using System; +using System.Linq; +using Grpc.Core.Utils; + +namespace Grpc.Core.Interceptors +{ + /// <summary> + /// Extends the ServerServiceDefinition class to add methods used to register interceptors on the server side. + /// This is an EXPERIMENTAL API. + /// </summary> + public static class ServerServiceDefinitionExtensions + { + /// <summary> + /// Returns a <see cref="Grpc.Core.ServerServiceDefinition" /> instance that + /// intercepts incoming calls to the underlying service handler through the given interceptor. + /// This is an EXPERIMENTAL API. + /// </summary> + /// <param name="serverServiceDefinition">The <see cref="Grpc.Core.ServerServiceDefinition" /> instance to register interceptors on.</param> + /// <param name="interceptor">The interceptor to intercept the incoming invocations with.</param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "serverServiceDefinition.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted service definition, effectively + /// building a chain like "serverServiceDefinition.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static ServerServiceDefinition Intercept(this ServerServiceDefinition serverServiceDefinition, Interceptor interceptor) + { + GrpcPreconditions.CheckNotNull(serverServiceDefinition, nameof(serverServiceDefinition)); + GrpcPreconditions.CheckNotNull(interceptor, nameof(interceptor)); + return new ServerServiceDefinition(serverServiceDefinition.CallHandlers.ToDictionary(x => x.Key, x => x.Value.Intercept(interceptor))); + } + + /// <summary> + /// Returns a <see cref="Grpc.Core.ServerServiceDefinition" /> instance that + /// intercepts incoming calls to the underlying service handler through the given interceptors. + /// This is an EXPERIMENTAL API. + /// </summary> + /// <param name="serverServiceDefinition">The <see cref="Grpc.Core.ServerServiceDefinition" /> instance to register interceptors on.</param> + /// <param name="interceptors"> + /// An array of interceptors to intercept the incoming invocations with. + /// Control is passed to the interceptors in the order specified. + /// </param> + /// <remarks> + /// Multiple interceptors can be added on top of each other by calling + /// "serverServiceDefinition.Intercept(a, b, c)". The order of invocation will be "a", "b", and then "c". + /// Interceptors can be later added to an existing intercepted service definition, effectively + /// building a chain like "serverServiceDefinition.Intercept(c).Intercept(b).Intercept(a)". Note that + /// in this case, the last interceptor added will be the first to take control. + /// </remarks> + public static ServerServiceDefinition Intercept(this ServerServiceDefinition serverServiceDefinition, params Interceptor[] interceptors) + { + GrpcPreconditions.CheckNotNull(serverServiceDefinition, nameof(serverServiceDefinition)); + GrpcPreconditions.CheckNotNull(interceptors, nameof(interceptors)); + + foreach (var interceptor in interceptors.Reverse()) + { + serverServiceDefinition = Intercept(serverServiceDefinition, interceptor); + } + + return serverServiceDefinition; + } + } +}
\ No newline at end of file |