#region Copyright notice and license
// Copyright 2019 The 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 Grpc.Core;
using Grpc.Net.Client.Configuration;
using Grpc.Net.Compression;
using Microsoft.Extensions.Logging;
namespace Grpc.Net.Client;
///
/// An options class for configuring a .
///
public sealed class GrpcChannelOptions
{
#if SUPPORT_LOAD_BALANCING
private TimeSpan _initialReconnectBackoff;
private TimeSpan? _maxReconnectBackoff;
#endif
///
/// Gets or sets the credentials for the channel. This setting is used to set for
/// a channel. Connection transport layer security (TLS) is determined by the address used to create the channel.
///
///
///
/// The channel credentials you use must match the address TLS setting. Use
/// for an "http" address and for "https".
///
///
/// The underlying used by the channel automatically loads root certificates
/// from the operating system certificate store.
/// Client certificates should be configured on HttpClient. See for details.
///
///
public ChannelCredentials? Credentials { get; set; }
///
/// Gets or sets the maximum message size in bytes that can be sent from the client. Attempting to send a message
/// that exceeds the configured maximum message size results in an exception.
///
/// A null value removes the maximum message size limit. Defaults to null.
///
///
public int? MaxSendMessageSize { get; set; }
///
/// Gets or sets the maximum message size in bytes that can be received by the client. If the client receives a
/// message that exceeds this limit, it throws an exception.
/// For compressed messages, the limit applies to both the compressed and decompressed message sizes.
///
/// A null value removes the maximum message size limit. Defaults to 4,194,304 (4 MB).
///
///
public int? MaxReceiveMessageSize { get; set; }
///
/// Gets or sets the maximum retry attempts. This value limits any retry and hedging attempt values specified in
/// the service config.
///
/// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done
/// using .
///
///
/// A null value removes the maximum retry attempts limit. Defaults to 5.
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public int? MaxRetryAttempts { get; set; }
///
/// Gets or sets the maximum buffer size in bytes that can be used to store sent messages when retrying
/// or hedging calls. If the buffer limit is exceeded, then no more retry attempts are made and all
/// hedging calls but one will be canceled. This limit is applied across all calls made using the channel.
///
/// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done
/// using .
///
///
/// A null value removes the maximum retry buffer size limit. Defaults to 16,777,216 (16 MB).
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public long? MaxRetryBufferSize { get; set; }
///
/// Gets or sets the maximum buffer size in bytes that can be used to store sent messages when retrying
/// or hedging calls. If the buffer limit is exceeded, then no more retry attempts are made and all
/// hedging calls but one will be canceled. This limit is applied to one call.
///
/// Setting this value alone doesn't enable retries. Retries are enabled in the service config, which can be done
/// using .
///
///
/// A null value removes the maximum retry buffer size limit per call. Defaults to 1,048,576 (1 MB).
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public long? MaxRetryBufferPerCallSize { get; set; }
///
/// Gets or sets a collection of compression providers.
///
public IList? CompressionProviders { get; set; }
///
/// Gets or sets the logger factory used by the channel. If no value is specified then the channel
/// attempts to resolve an from the .
///
public ILoggerFactory? LoggerFactory { get; set; }
///
/// Gets or sets the used by the channel to make HTTP calls.
///
///
///
/// By default a specified here will not be disposed with the channel.
/// To dispose the with the channel you must set
/// to true.
///
///
/// Only one HTTP caller can be specified for a channel. An error will be thrown if this is configured
/// together with .
///
///
public HttpClient? HttpClient { get; set; }
///
/// Gets or sets the used by the channel to make HTTP calls.
///
///
///
/// By default a specified here will not be disposed with the channel.
/// To dispose the with the channel you must set
/// to true.
///
///
/// Only one HTTP caller can be specified for a channel. An error will be thrown if this is configured
/// together with .
///
///
public HttpMessageHandler? HttpHandler { get; set; }
///
/// Gets or sets a value indicating whether the underlying or
/// should be disposed when the instance is disposed.
/// The default value is false.
///
///
/// This setting is used when a or value is specified.
/// If they are not specified then the channel will create an internal HTTP caller that is always disposed
/// when the channel is disposed.
///
public bool DisposeHttpClient { get; set; }
///
/// Gets or sets a value indicating whether clients will throw for a call when its
/// is triggered or its is exceeded.
/// The default value is false.
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public bool ThrowOperationCanceledOnCancellation { get; set; }
///
/// Gets or sets a value indicating whether a gRPC call's are used by an insecure channel.
/// The default value is false.
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
///
///
/// The default value for this property is false, which causes an insecure channel to ignore a gRPC call's .
/// Sending authentication headers over an insecure connection has security implications and shouldn't be done in production environments.
///
///
/// If this property is set to true, call credentials are always used by a channel.
///
///
public bool UnsafeUseInsecureChannelCallCredentials { get; set; }
///
/// Gets or sets the service config for a gRPC channel. A service config allows service owners to publish parameters
/// to be automatically used by all clients of their service. A service config can also be specified by a client
/// using this property.
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public ServiceConfig? ServiceConfig { get; set; }
#if SUPPORT_LOAD_BALANCING
///
/// Gets or sets a value indicating whether resolving a service config from the
/// is disabled.
/// The default value is false.
///
/// A hint is provided to the resolver that it shouldn't fetch a service config.
/// If a service config is returned by then resolver then it is ignored.
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public bool DisableResolverServiceConfig { get; set; }
///
/// Gets or sets the the maximum time between subsequent connection attempts.
///
/// The reconnect backoff starts at an initial backoff and then exponentially increases between attempts, up to the maximum reconnect backoff.
/// Reconnect backoff adds a jitter to randomize the backoff. This is done to avoid spikes of connection attempts.
///
///
/// A null value removes the maximum reconnect backoff limit. The default value is 120 seconds.
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public TimeSpan? MaxReconnectBackoff
{
get => _maxReconnectBackoff;
set
{
if (value <= TimeSpan.Zero)
{
throw new ArgumentException("Maximum reconnect backoff must be greater than zero.");
}
_maxReconnectBackoff = value;
}
}
///
/// Gets or sets the time between the first and second connection attempts.
///
/// The reconnect backoff starts at an initial backoff and then exponentially increases between attempts, up to the maximum reconnect backoff.
/// Reconnect backoff adds a jitter to randomize the backoff. This is done to avoid spikes of connection attempts.
///
///
/// Defaults to 1 second.
///
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public TimeSpan InitialReconnectBackoff
{
get => _initialReconnectBackoff;
set
{
if (value <= TimeSpan.Zero)
{
throw new ArgumentException("Initial reconnect backoff must be greater than zero.");
}
_initialReconnectBackoff = value;
}
}
#endif
///
/// Gets or sets the the channel uses to resolve types.
///
/// Note: Experimental API that can change or be removed without any prior notice.
///
///
public IServiceProvider? ServiceProvider { get; set; }
///
/// Gets or sets the HTTP version to use when making gRPC calls.
///
/// When a is specified the value will be set on
/// as gRPC calls are made. Changing this property allows the HTTP version of gRPC calls to
/// be overridden.
///
///
/// A null value doesn't override the HTTP version of gRPC calls. Defaults to 2.0.
///
///
public Version? HttpVersion { get; set; }
#if NET5_0_OR_GREATER
///
/// Gets or sets the HTTP policy to use when making gRPC calls.
///
/// When a is specified the value will be set on
/// as gRPC calls are made. The policy determines how is interpreted when
/// the final HTTP version is negotiated with the server. Changing this property allows the HTTP
/// version of gRPC calls to be overridden.
///
///
/// A null value doesn't override the HTTP policy of gRPC calls. Defaults to .
///
///
public HttpVersionPolicy? HttpVersionPolicy { get; set; }
#endif
internal T ResolveService(T defaultValue)
{
return (T?)ServiceProvider?.GetService(typeof(T)) ?? defaultValue;
}
///
/// Initializes a new instance of the class.
///
public GrpcChannelOptions()
{
MaxReceiveMessageSize = GrpcChannel.DefaultMaxReceiveMessageSize;
#if SUPPORT_LOAD_BALANCING
_maxReconnectBackoff = TimeSpan.FromTicks(GrpcChannel.DefaultMaxReconnectBackoffTicks);
_initialReconnectBackoff = TimeSpan.FromTicks(GrpcChannel.DefaultInitialReconnectBackoffTicks);
#endif
MaxRetryAttempts = GrpcChannel.DefaultMaxRetryAttempts;
MaxRetryBufferSize = GrpcChannel.DefaultMaxRetryBufferSize;
MaxRetryBufferPerCallSize = GrpcChannel.DefaultMaxRetryBufferPerCallSize;
}
}