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.ssenow: the latest desktop config hascaptureStreams: 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.waitForDesktopis 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(flutterunless 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
listenereach 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
lowerCaseNamemust 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.
bodyreturns 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
methodurlmay 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
idand 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
bodyin 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
ErrorInfomap. -
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.20or192.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< actions) → voidString, Object?> > - 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?> ? -
ErrorInfofor 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
hellowaits for start'shelloGate: 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).