Class RpcPeerOptions

Namespace

DotBoxD.Services.Peer

Assembly

DotBoxD.Services.dll

Options for RpcPeer and RpcHost.

public sealed class RpcPeerOptions

Inheritance

object

RpcPeerOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Fields

DefaultInboundQueueCapacity

public const int DefaultInboundQueueCapacity = 1024

Field Value

int

DefaultMaxConcurrentInboundDispatch

public const int DefaultMaxConcurrentInboundDispatch = 1

Field Value

int

DefaultMaxInboundBytes

Default MaxInboundBytes: 64 MiB of in-flight inbound frames per peer.

public const long DefaultMaxInboundBytes = 67108864

Field Value

long

DefaultMaxPendingRequests

public const int DefaultMaxPendingRequests = 4096

Field Value

int

Properties

DisableInboundRequestCancellation

When true, non-streaming inbound calls do not allocate per-request cancellation state. The handler receives None and inbound Cancel frames for those calls are ignored. Streaming calls still allocate cancellation state so stream cleanup and response-stream teardown remain cancellable.

public bool DisableInboundRequestCancellation { get; init; }

Property Value

bool

Remarks

This is a low-allocation option for trusted peers and handlers whose work is short or bounded elsewhere. Peer shutdown waits for those handlers instead of interrupting them. Leave it disabled when callers must be able to stop in-flight handlers with a Cancel frame or when handlers depend on the supplied cancellation token.

EnableLowAllocationValueTaskInvocations

When true, generated generic ValueTask<TResult> unary proxy calls may use a pooled response source instead of the default Task<TResult> path.

public bool EnableLowAllocationValueTaskInvocations { get; init; }

Property Value

bool

Remarks

The optimized path is only used when RequestTimeout is InfiniteTimeSpan and the caller does not pass a cancellable token. It can run continuations inline on the peer read loop and follows the normal ValueTask<TResult> single-consumption rules. Leave this disabled unless the peer is on a measured, trusted hot path and every returned ValueTask<TResult> is awaited exactly once.

ExceptionTransformer

Optional hook, invoked on the side that runs the service, that turns an exception thrown by a handler into the error returned to the caller. Return an RpcErrorInfo to surface that message and type to the caller, or null to keep the default opaque "Internal error." response for that exception.

When this is null (the default) every handler exception is reported opaquely so internal failure detail is never leaked. Framework protocol errors (service, method, and instance not found) keep their own typed mapping and are not routed through this hook.

Exposing exception detail can leak sensitive information, so this is opt-in — only enable it for trusted peers, or map exceptions to safe, caller-facing messages. The shortcut ExceptionTransformer = ex => RpcErrorInfo.FromException(ex) exposes every exception's message and type. The hook may be invoked concurrently when MaxConcurrentInboundDispatch is greater than one, so keep it thread-safe.

public Func<Exception, RpcErrorInfo?>? ExceptionTransformer { get; init; }

Property Value

Func<Exception, RpcErrorInfo?>

InboundQueueCapacity

Maximum queued inbound requests. The default applies bounded read-side backpressure. Null dispatches inbound requests immediately, does not cap concurrent dispatch work, and should only be used with trusted peers or externally bounded transports. In wait mode, request admission waits for bounded dispatch queue space.

public int? InboundQueueCapacity { get; init; }

Property Value

int?

Remarks

A peer demuxes responses, cancels, and inbound requests over a single read loop. In Wait mode that loop parks when the request queue is full, which also pauses reading responses to this peer's own outbound calls. For a bidirectional peer whose inbound handlers call back into the same peer, size this capacity above the maximum number of inbound requests that can arrive ahead of those callbacks' responses, or use null (unbounded) or DropIncoming; otherwise an under-sized Wait queue can stall a reentrant response until RequestTimeout.

MaxConcurrentInboundDispatch

Maximum number of inbound requests dispatched concurrently when InboundQueueCapacity is set. The default of 1 dispatches serially per connection (preserving ordering and bounding work). Raise it for concurrent per-connection dispatch; total in-flight inbound work is then bounded by InboundQueueCapacity + this value. Ignored when InboundQueueCapacity is null (which dispatches immediately and does not cap concurrency).

public int MaxConcurrentInboundDispatch { get; init; }

Property Value

int

MaxInboundBytes

Maximum total bytes of in-flight inbound request frames buffered for dispatch when InboundQueueCapacity is set. InboundQueueCapacity bounds frame count only, so it alone permits up to capacity × max-frame-size bytes (a hostile or overwhelming peer sending large frames can otherwise pin that much memory). This caps the peak independent of frame size; the default is 64 MiB. A frame larger than the budget is still admitted when no other inbound work is in flight, so one oversized request never deadlocks. Set to null to disable the byte bound (count-only). Ignored when InboundQueueCapacity is null (which does not buffer or bound).

public long? MaxInboundBytes { get; init; }

Property Value

long?

MaxPendingRequests

Maximum concurrent outbound calls waiting for responses.

public int MaxPendingRequests { get; init; }

Property Value

int

QueueFullMode

Policy used when InboundQueueCapacity is set and the request queue is full.

public QueueFullMode QueueFullMode { get; init; }

Property Value

QueueFullMode

RejectInboundCalls

When true, inbound request frames are answered with an explicit "this peer does not accept inbound calls" error rather than a "service not found" error. Use it to make a get-only ("client") peer's one-directional intent explicit. This is not an authentication or authorization boundary.

public bool RejectInboundCalls { get; init; }

Property Value

bool

RequestTimeout

Default per-call timeout for proxies created by this peer. Must be a positive TimeSpan (at most MaxValue milliseconds) or InfiniteTimeSpan to disable the timeout.

public TimeSpan RequestTimeout { get; init; }

Property Value

TimeSpan

ServiceProvider

Optional service provider for dispatcher factories that resolve dependencies.

public IServiceProvider? ServiceProvider { get; init; }

Property Value

IServiceProvider