DurbunClient class

The SDK's connection to the Dürbün desktop for pure Dart programs (no Flutter): logs, events, dart:io HTTP capture, mock rules and commands. Flutter apps use Durbun.run / Durbun.init, which create one of these.

final client = DurbunClient.start(const DurbunOptions(enabled: true));
client.log(DurbunLogLevel.info, 'Job started', tag: 'cron');
await client.flush(const Duration(seconds: 2));
await client.dispose();
Implemented types

Properties

app → DetectedApp
The app as detected at start (id, name, version), options applied.
final
appSessionId → String?
Server-assigned app session id (null until connected once).
no setter
buildHost → String?
The address built into the app (DurbunOptions.host, --dart-define=DURBUN_HOST, environment), if any.
no setter
captureBodies → bool
Whether body contents are captured (sizes always are).
no setteroverride
captureStreams → bool
Send net.ws / net.sse now: the latest desktop config has captureStreams: true.
no setteroverride
config → SdkConfig
Config from the desktop (defaults until the first welcome).
no setter
configKnown → bool
Whether a welcome/config was received at least once.
no setter
connection → DurbunConnection
The current connection to the desktop.
no setter
connectionChanges → Stream<DurbunConnection>
Every change of connection (connected, disconnected).
no setter
connectionReport → ConnectionReport
Why the app is (not) connected, for the in-app panel.
no setter
device → DetectedDevice
The device as detected at start.
final
extraCapabilities → List<String>
Capabilities announced on top of the client's own (e.g. metrics).
final
hashCode → int
The hash code for this object.
no setterinherited
hasNative → bool
Whether a native layer is attached.
no setter
isConnected → bool
Whether the desktop is connected right now.
no setter
isDisposed → bool
Whether dispose ran; a disposed client ignores every call.
no setter
localStreams ↔ LocalStreamSink?
The in-app panel's own record of stream messages (set by the Flutter layer while the panel is on); messages the desktop does not take go there instead of outgoingTap.
getter/setter pair
maxBodyBytes → int
Bodies are cut after this many bytes.
no setteroverride
mocks → List<MockRule>
Mock rules of the connected desktop (empty while disconnected).
no setter
mocksReady → Future<void>?
Requests wait only while a peer has accepted the connection and the welcome (with its mock rules) is on its way. Without a desktop — no listener, hello still held back, nothing accepted yet — they never wait; DurbunOptions.waitForDesktop is the explicit way to wait longer.
no setteroverride
networkEnabled → bool
False → the wrapper is a pure pass-through (SDK disabled or disposed).
no setteroverride
options → DurbunOptions
The options this client was started with.
final
outgoingTap ↔ void Function(Map<String, Object?> message)?
Sees every outgoing message (Dart and native-encoded lines) before the transport: the in-app inspector keeps its own copy. Must not throw or mutate the message.
getter/setter pair
panelHost → String?
The address set at run time with setDesktopHost, if any.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sdkPlatform → String
hello.sdk.platform (flutter unless start was given another).
final
session → String
Random id for this app launch (hello.session).
final
streamMessageCap → int
Payload bytes kept of one stream message (0: sizes only).
no setteroverride
streamsWanted → bool
Stream messages are wanted, or may still be (no desktop config yet). While false, captures skip all decoding work.
no setteroverride
usesBackgroundIsolate → bool
Whether the transport engine runs on a background isolate.
no setter

Methods

addAction(DurbunAction action) → void
Adds (or replaces) an action shown on the desktop.
addActions(Iterable<DurbunAction> actions) → void
Adds several actions with a single hello/actions refresh.
addConfigListener(void listener(SdkConfig config)) → void
Calls listener each time the desktop sends new settings.
addReportListener(void listener()) → void
Called when connectionReport changes.
addStateListener(void listener()) → void
Called whenever connection, config, mocks or hello change.
attachNative(NativePart part) → void
Joins the native layer (Kotlin / Swift core hosted by the Flutter plugin) to this session: its capabilities, actions and app info go into hello, its commands are forwarded to it. Replaces a previous part.
debugHello() → Map<String, Object?>
The hello message as it is sent (for diagnostics and tests).
describeActions() → List<Map<String, Object?>>
The registered actions as the desktop receives them (hello.actions).
describeState() → Map<String, Object?>
Current desktop state as one JSON-like map (for the native layer): {connected, via, appId, config, mocks, hello}.
dispose({Duration flushTimeout = Duration.zero}) → Future<void>
Stops the SDK: closes the connection, removes the HTTP overrides.
event(String name, [Map<String, Object?>? props]) → void
Sends a custom event (SdkEvent). Never throws.
flush([Duration timeout = const Duration(seconds: 5)]) → Future<bool>
Waits until everything logged so far was handed to the desktop's socket (useful before a CLI program exits). False on timeout / no connection.
isRedactedHeader(String lowerCaseName) → bool
Whether the value of lowerCaseName must be redacted.
override
log(DurbunLogLevel level, Object? message, {String? tag, Object? data, Object? error, StackTrace? stackTrace, String? kind, double? ts}) → void
Sends an app log (SdkLog). Never throws.
matchMock(String method, String url) → MockRule?
First matching mock rule for this request, or null.
override
matchMockRequest(String method, String url, {String? contentType, String? body()?}) → MockRule?
First matching rule for this request. body returns the body text when it is held (null otherwise); called at most once, only when needed.
metric(Map<String, Object?> metricMessage) → void
Sends a metric sample. While disconnected only outgoingTap (the in-app inspector) sees it: nothing waits for the desktop.
mockNeedsBody(String method, String url) → bool
Whether the rule for method url may depend on the request body.
nextRequestId() → String
Unique request id within this app session.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
publishActions() → void
Re-sends action descriptors (current values) and refreshes the hello.
registerCommand(String name, DurbunCommandHandler handler) → void
Registers a command that is not shown as an action.
removeAction(String id) → void
Removes the action with id and tells the desktop.
removeConfigListener(void listener(SdkConfig config)) → void
Stops calling a listener added with addConfigListener.
removeReportListener(void listener()) → void
Stops calling a listener added with addReportListener.
removeStateListener(void listener()) → void
Stops calling a listener added with addStateListener.
retryConnectNow() → void
Tries to reach the desktop now instead of after the current wait.
runAction(String id, [Map<String, Object?> params = const <String, Object?>{}]) → Future<Object?>
Runs an action from the in-app panel: the app's own (addAction) or the native layer's. Returns the action's result data (for toggles and selects {value: …}); throws when it fails or a native one does not answer within 9 s. The desktop sees the new values, not the call.
runInternal<R>(R body()) → R
Runs body in the SDK's internal zone (errors are swallowed).
sendEncoded(String jsonLine) → void
Sends a message the native layer already encoded as one JSON object (no trailing newline). It shares this client's buffer and connection.
sendLog({required DurbunLogLevel level, required String message, String? tag, Object? data, Map<String, Object?>? error, String? kind, double? ts}) → void
Lower-level variant of log taking a ready ErrorInfo map.
sendNetMessage(Map<String, Object?> message) → void
Queues a net.* message.
override
setAppInBackground(bool background) → void
The app went to the background (true) or came back (false). In the background no connection attempts are made; back in the foreground the next one starts at once. An open connection is not touched.
setDesktopHost(String? host) → void
Uses host (192.168.1.20 or 192.168.1.20:9751) as the Wi-Fi address instead of the build's, and tries it at once; null goes back to the build's address. A link through the old Wi-Fi address is closed; the USB link (adb reverse, usbmux) stays.
startPeriodicTimer(Duration period, void callback()) → Timer
Periodic timer in the internal zone.
startTimer(Duration duration, void callback()) → Timer
Starts a timer outside the app's zones.
override
toString() → String
A string representation of this object.
inherited
updateNativeActions(List<Map<String, Object?>> actions) → void
The native layer's action list changed (values or entries).
waitForConnection(Duration timeout) → Future<bool>
Waits for a connection (or timeout); true when connected.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

current → DurbunClient?
The running client on this isolate, if any.
no setter

Static Methods

diagnostic(String message) → void
SDK-internal diagnostics (debug level: IDE / DevTools console only).
errorInfo(Object? error, StackTrace? stackTrace) → Map<String, Object?>?
ErrorInfo for an error object / stack trace (null when both absent).
start(DurbunOptions options, {String sdkPlatform = 'flutter', List<String> extraCapabilities = const <String>[], TransportConfig? transportConfig, Future<void>? helloGate}) → DurbunClient
Starts the SDK on this isolate (synchronous; the connection is made in the background). Returns the already running client if there is one.

Constants

kConsoleHintAfter → const Duration
After this long without a first connection, debug builds print once why (see connectionHintForConsole).
kHelloGateTimeout → const Duration
Longest time the first hello waits for start's helloGate: as long as the Flutter glue waits for the plugin's native start, so a slow native layer still makes it into the session (the server keeps the first hello of a connection).