Interface ITransportConfiguration
- Namespace
- WebDriverBiDi.Protocol
- Assembly
- WebDriverBiDi.dll
Interface for the settings of a Transport that a consumer may tune. It is implemented by Transport and reached from TransportConfiguration, so that a driver created with the parameterless constructor can be tuned without constructing a transport by hand.
public interface ITransportConfigurationRemarks
This interface is deliberately narrower than Transport itself. The transport's lifecycle and messaging operations — connecting, disconnecting, sending a command, registering an event message — are driven by the BiDiDriver that owns the transport, which enforces the registration-timing rules around them. Handing those out alongside the settings would let a caller step around the driver, so only the settings appear here.
This interface is not intended to be implemented by users of this library. It is exposed publicly to allow for testing and to allow users to implement their own transport classes if they choose.
Properties
ConnectionLockTimeout
Gets or sets the timeout to wait for exclusive access to the transport's connection while another operation holds it. The default is 60 seconds.
TimeSpan ConnectionLockTimeout { get; set; }Property Value
Remarks
Connecting, disconnecting, sending a command and registering a type info resolver each take exclusive access for the duration of their work, so one of them waits while another is in progress. Bounding that wait keeps an operation issued from code the transport itself invoked while holding the access — a synchronous observer of OnLogMessage that sends a command, for example — from waiting on an operation that is itself waiting on the observer to return. Such an operation fails with WebDriverBiDiTimeoutException instead of never completing. An observer that needs to drive the driver should be registered with RunHandlerAsynchronously so that it does not hold up the operation it was dispatched from.
The default is deliberately longer than the longest legitimate hold, so that lowering it is a deliberate choice rather than a trap. A value shorter than the longest hold a session can legitimately take will fail operations that would otherwise have succeeded. Zero never waits, and InfiniteTimeSpan restores an unbounded wait.
Exceptions
- ArgumentOutOfRangeException
Thrown when the value is negative (other than InfiniteTimeSpan) or exceeds the maximum timer duration supported by the runtime.
EventHandlerExceptionBehavior
Gets or sets a value indicating the behavior for handling exceptions thrown by event handlers.
Defaults to Ignore, meaning that such an exception is neither
collected nor thrown from a later call, and does not stop the driver processing messages from the
transport; it is still raised on OnEventHandlerErrorOccurred and as the
EventHandlerError event of WebDriverBiDiEventSource.
TransportErrorBehavior EventHandlerExceptionBehavior { get; set; }Property Value
Remarks
Exceptions from handlers registered with
RunHandlerAsynchronously participate in this behavior
when they are not already owned by task capture. If the caller captures handler tasks using
WaitForCapturedTasksAsync(uint, TimeSpan, CancellationToken),
WaitForCapturedTasksCompleteAsync(uint, TimeSpan, CancellationToken), or
GetCapturedTasks(), those task exceptions remain owned by the caller
rather than being surfaced again through the transport error pipeline. What decides that ownership
is whether a capture session was active when the handler ran, not when its task faulted: a task
that is already faulted by the time the handler returns it — one from
FromException(Exception), say, or from an
async handler that throws before its first await — is captured like any other, and
its failure belongs to the caller in the same way. A handler that throws before returning a
task at all leaves nothing to capture; that exception reaches the code raising the event
directly, and is governed by this property.
LogLevel
Gets or sets the minimum WebDriverBiDiLogLevel at which log messages are raised on OnLogMessage. Defaults to Info.
WebDriverBiDiLogLevel LogLevel { get; set; }Property Value
Remarks
This is one setting for the whole pipeline: the driver, its Transport and the transport's Connection all read and write the same value, so a message from any of the three is subject to it.
The default excludes Debug and Trace. Set it to Debug for a message per command sent and answered, or to Trace to also receive every message exchanged with the remote end, which is how protocol traffic is inspected. Trace is not the default because composing those messages decodes each payload into a string. Off suppresses every message.
This governs only OnLogMessage. The WebDriverBiDiEventSource diagnostic events are independent, and are filtered by whatever enables the event source.
MaxTrackedCanceledCommands
Gets or sets the number of most recent command cancellations within which a canceled command is remembered, so that a response arriving for it later is recognized and discarded. The default is DefaultMaxTrackedCanceledCommands.
uint MaxTrackedCanceledCommands { get; set; }Property Value
Remarks
A command that times out, or is canceled, may still be answered by the remote end. A response for a command still remembered is discarded quietly; a response for one that has been forgotten, because this many further commands were canceled after it, is treated as an unknown message or an unexpected error, as UnknownMessageBehavior and UnexpectedErrorBehavior direct. Raise the value if a session cancels many commands whose responses may arrive long afterwards. A value of zero disables the tracking.
Canceled commands are remembered per session, so the value takes effect for the session started by the next connect, and does not change the session in progress.
ProtocolErrorBehavior
Gets or sets a value indicating the behavior for handling a protocol error: a message recognized as
an error response or as a registered event whose payload cannot be deserialized, or an unexpected
failure while processing an incoming message. An error response whose ID matches a pending command
fails that command instead, and a message that cannot be parsed as JSON is an unknown message.
Defaults to Ignore, meaning that the error is neither collected
nor thrown from a later call, and does not stop the driver processing messages from the transport;
it is still written to OnLogMessage at Error
and, for a payload that cannot be deserialized, raised as the ProtocolError event of
WebDriverBiDiEventSource. No observable event is raised for it.
TransportErrorBehavior ProtocolErrorBehavior { get; set; }Property Value
ShutdownTimeout
Gets or sets the timeout to wait for the incoming message queue to be emptied and its messages processed when disconnecting. The default is 10 seconds.
TimeSpan ShutdownTimeout { get; set; }Property Value
Remarks
This timeout applies to waiting for the incoming message queue to empty, to waiting for the messages in the queue to be processed, and, during disposal, to waiting for an in-flight connect attempt to complete before the transport's resources are released. It is distinct from ShutdownTimeout, which bounds the underlying connection's close handshake.
Abandoning the wait does not stop the reader. Messages already delivered to the queue go on being processed in the background, and their handlers go on running; what this timeout bounds is how long the shutdown waits for them, not whether they run.
Exceptions
- ArgumentOutOfRangeException
Thrown when the value is negative (other than InfiniteTimeSpan) or exceeds the maximum timer duration supported by the runtime.
UnexpectedErrorBehavior
Gets or sets a value indicating the behavior for handling exceptions when an unexpected error is encountered, such as an error response received with no corresponding command. Defaults to Ignore, meaning that the error is neither collected nor thrown from a later call, and does not stop the driver processing messages from the transport; it is still raised on OnUnexpectedErrorReceived. An error response that arrives for a command after that command has timed out or been canceled is not an unexpected error; it is logged and discarded without affecting this behavior.
TransportErrorBehavior UnexpectedErrorBehavior { get; set; }Property Value
UnknownMessageBehavior
Gets or sets a value indicating the behavior for handling an unknown message: a message that cannot be
parsed as JSON, or one that is not a command response, an error response, or a registered event, such
as a response for a command ID that was never issued or an event whose name is not registered.
Defaults to Ignore, meaning that the error is neither collected
nor thrown from a later call, and does not stop the driver processing messages from the transport; it
is still raised on OnUnknownMessageReceived and as the
UnknownMessageReceived event of WebDriverBiDiEventSource, and a message that
cannot be parsed is also written to OnLogMessage at Error.
A response that arrives for a command after that command has timed out or been canceled is not
an unknown message; it is logged and discarded without affecting this behavior.
TransportErrorBehavior UnknownMessageBehavior { get; set; }