WiretapKMP

https://skymansandy.dev/wiretapKMP/
Admin
WiretapKMP is a Kotlin Multiplatform network inspection and mocking SDK. It intercepts HTTP,...
Tokens:32,707
Snippets:487
Trust Score:4.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### DI Setup Example with Wiretap

Source: https://skymansandy.dev/wiretapKMP/okhttp/setup

Configure OkHttpClient with Wiretap interceptor as a singleton in a dependency injection module.

```kotlin
val okHttpModule = module {
    single {
        OkHttpClient.Builder()
            .addInterceptor(WiretapOkHttpInterceptor {
                logRetention = LogRetention.AppSession
                headerAction = { key ->
                    if (key.equals("Authorization", ignoreCase = true))
                        HeaderAction.Mask()
                    else
                        HeaderAction.Keep
                }
            })
            .build()
    }
}
```

--------------------------------

### Complete OkHttp Client Setup with Interceptor

Source: https://skymansandy.dev/wiretapKMP/okhttp/http

Example of building an OkHttpClient with WiretapOkHttpInterceptor, including request filtering and header masking. Demonstrates making GET and POST requests and how headers are logged.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor {
        shouldLog = { url, _ -> url.contains("/api/") }
        headerAction = { key ->
            if (key.equals("Authorization", ignoreCase = true))
                HeaderAction.Mask()
            else
                HeaderAction.Keep
        }
        logRetention = LogRetention.AppSession
    })
    .build()

// GET request
val request = Request.Builder()
    .url("https://api.example.com/users")
    .header("Authorization", "Bearer token123")
    .build()

val response = client.newCall(request).execute()
// Authorization header logged as "***" in the inspector

// POST request
val postBody = """{"name": "Alice"}""
    .toRequestBody("application/json".toMediaType())

val postRequest = Request.Builder()
    .url("https://api.example.com/users")
    .post(postBody)
    .build()

client.newCall(postRequest).execute()


```

--------------------------------

### Complete Ktor SSE Logging Example

Source: https://skymansandy.dev/wiretapKMP/ktor/sse

A full example demonstrating the setup and usage of Ktor SSE logging with event handling.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
val client = HttpClient {
    install(SSE)
    install(WiretapKtorSsePlugin)
    install(WiretapKtorHttpPlugin)
}

@OptIn(ExperimentalWiretapSseApi::class)
client.sse("https://api.example.com/stream") {
    incoming.collect {
        when (event.event) {
            "message" -> handleMessage(event.data)
            "heartbeat" -> { /* ignore */ }
            else -> println("Unknown event: ${event.event}")
        }
    }
}

```

--------------------------------

### DI Setup Example with Wiretap

Source: https://skymansandy.dev/wiretapKMP/ktor/setup

Configure HttpClient with Wiretap plugins for HTTP, WebSocket, and SSE within a Koin module. Demonstrates header masking.

```kotlin
val networkModule = module {
    single {
        HttpClient {
            install(WebSockets)
            install(SSE)
            install(WiretapKtorWebSocketPlugin)
            install(WiretapKtorSsePlugin)
            install(WiretapKtorHttpPlugin) {
                logRetention = LogRetention.AppSession
                headerAction = { key ->
                    if (key.equals("Authorization", ignoreCase = true))
                        HeaderAction.Mask()
                    else
                        HeaderAction.Keep
                }
            }
        }
    }
}
```

--------------------------------

### Install WiretapOkHttpEventSourceListener

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Shows two ways to install the WiretapOkHttpEventSourceListener: using the recommended extension function `wiretapped()` or directly through the constructor.

```kotlin
// Extension function (recommended)
factory.newEventSource(request, myListener.wiretapped())
```

```kotlin
// Constructor
factory.newEventSource(request, WiretapOkHttpEventSourceListener(myListener))
```

--------------------------------

### Ktor SSE Plugin Setup

Source: https://skymansandy.dev/wiretapKMP/ktor/sse

Install the Ktor SSE plugin and the Wiretap SSE plugin. SSE APIs require opt-in.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
val client = HttpClient {
    install(SSE)
    install(WiretapKtorSsePlugin)    // SSE logging (experimental)
    install(WiretapKtorHttpPlugin)   // HTTP logging
}

```

--------------------------------

### Install WiretapOkHttpWebSocketListener

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Shows two ways to install the WiretapOkHttpWebSocketListener: using the recommended extension function `wiretapped()` or directly through the constructor.

```kotlin
// Extension function (recommended)
client.newWebSocket(request, myListener.wiretapped())
```

```kotlin
// Constructor
client.newWebSocket(request, WiretapOkHttpWebSocketListener(myListener))
```

--------------------------------

### Ktor HttpClient Setup with Wiretap Plugins

Source: https://skymansandy.dev/wiretapKMP/ktor/websockets

Installs the standard WebSockets plugin along with Wiretap plugins for logging HTTP and WebSocket traffic.

```kotlin
val client = HttpClient {
    install(WebSockets)
    install(WiretapKtorWebSocketPlugin)  // Logs connections
    install(WiretapKtorHttpPlugin)           // Logs HTTP (deletes 101плення entries)
}
```

--------------------------------

### Install WebSocket and Wiretap Plugins

Source: https://skymansandy.dev/wiretapKMP/ktor/websockets?q=

Install the standard WebSocket plugin and the Wiretap WebSocket plugin for logging connections and HTTP traffic.

```kotlin
val client = HttpClient {
    install(WebSockets)
    install(WiretapKtorWebSocketPlugin)  // Logs connections
    install(WiretapKtorHttpPlugin)           // Logs HTTP (deletes 101 upgrade entries)
}
```

--------------------------------

### Install Wiretap with SSE Support

Source: https://skymansandy.dev/wiretapKMP/ktor/setup?q=

Configure HttpClient to use SSE and Wiretap for logging HTTP and SSE traffic. The example demonstrates basic SSE client usage.

```kotlin
val client = HttpClient {
    install(SSE)
    install(WiretapKtorSsePlugin)        // SSE logging
    install(WiretapKtorHttpPlugin)       // HTTP logging
}

client.sse("https://example.com/events") {
    incoming.collect { event ->
        println("Event: ${event.event} — ${event.data}")
    }
}
```

--------------------------------

### Full OkHttp SSE Logging Example

Source: https://skymansandy.dev/wiretapKMP/okhttp/sse

A complete example demonstrating how to configure OkHttp with Wiretap's interceptor and set up an EventSourceListener to log SSE events. Ensure to opt into experimental APIs.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor())
    .build()

val listener = object : EventSourceListener() {
    override fun onOpen(eventSource: EventSource, response: Response) {
        println("Connected")
    }

    override fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) {
        println("Event: $type — $data")
    }

    override fun onClosed(eventSource: EventSource) {
        println("Closed")
    }

    override fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) {
        println("Failed: ${t?.message}")
    }
}

val request = Request.Builder().url("https://api.example.com/stream").build()
val factory = EventSources.createFactory(client)
@OptIn(ExperimentalWiretapSseApi::class)
factory.newEventSource(request, listener.wiretapped())
```

--------------------------------

### Complete Ktor HTTP Client Example

Source: https://skymansandy.dev/wiretapKMP/ktor/http

An example of an `ApiClient` using `HttpClient` with the Wiretap plugin implicitly handling all request and response logging.

```kotlin
class ApiClient(private val client: HttpClient) {

    suspend fun getUsers(): List<User> {
        return client.get("https://api.example.com/users").body()
    }

    suspend fun createUser(name: String): User {
        return client.post("https://api.example.com/users") {
            contentType(ContentType.Application.Json)
            setBody(mapOf("name" to name))
        }.body()
    }

}
```

--------------------------------

### Install WiretapOkHttpInterceptor

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Demonstrates how to add the WiretapOkHttpInterceptor to an OkHttpClient builder. The interceptor can be configured using a lambda expression.

```kotlin
OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor {
        // WiretapHttpConfig properties — all optional
    })
    .build()
```

--------------------------------

### Install Wiretap with WebSocket Support

Source: https://skymansandy.dev/wiretapKMP/ktor/setup

Integrate Wiretap for both HTTP and WebSocket logging. Ensure the WebSocket plugin is installed before the HTTP plugin.

```kotlin
val client = HttpClient {
    install(WebSockets)
    install(WiretapKtorWebSocketPlugin)  // WebSocket logging
    install(WiretapKtorHttpPlugin) {         // HTTP logging
        logRetention = LogRetention.AppSession
    }
}
```

--------------------------------

### Consume SSE Events with Wiretap

Source: https://skymansandy.dev/wiretapKMP/ktor/setup

Example of directly using the SSE session after installing the WiretapKtorSsePlugin. Incoming events are collected and printed.

```kotlin
client.sse("https://example.com/events") {
    incoming.collect { event ->
        println("Event: ${event.event} — ${event.data}")
    }
}
```

--------------------------------

### Basic WebSocket Logging Setup

Source: https://skymansandy.dev/wiretapKMP/okhttp/websockets

Use the `wiretapped()` extension on any `WebSocketListener` to enable logging for WebSocket connections.

```kotlin
val request = Request.Builder().url("wss://echo.websocket.org").build()
client.newWebSocket(request, myListener.wiretapped())
```

--------------------------------

### Full WebSocket Listener Example with Logging

Source: https://skymansandy.dev/wiretapKMP/okhttp/websockets

A complete `WebSocketListener` implementation demonstrating how messages are sent and received, with automatic logging enabled by `wiretapped()`.

```kotlin
val myListener = object : WebSocketListener() {
    override fun onOpen(webSocket: WebSocket, response: Response) {
        webSocket.send("Hello!")  // Automatically logged (outgoing)
    }

    override fun onMessage(webSocket: WebSocket, text: String) {
        println("Received: $text")  // Automatically logged (incoming)
    }

    override fun onClosing(webSocket: WebSocket, code: Int, reason: String) {
        webSocket.close(1000, null)
    }

    override fun onClosed(webSocket: WebSocket, code: Int, reason: String) {
        println("Closed: $code $reason")
    }

    override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
        println("Failed: ${t.message}")
    }
}

val request = Request.Builder().url("wss://echo.websocket.org").build()
client.newWebSocket(request, myListener.wiretapped())
```

--------------------------------

### Update WiretapKtorHttpPlugin install block

Source: https://skymansandy.dev/wiretapKMP/ktor/migration?q=

The `install` DSL remains unchanged, only the config type name has changed from `WiretapConfig` to `WiretapHttpConfig`.

```kotlin
- install(WiretapKtorHttpPlugin) { // this: WiretapConfig
+ install(WiretapKtorHttpPlugin) { // this: WiretapHttpConfig
      enabled = true
  }
```

--------------------------------

### WiretapKtorHttpPlugin Installation

Source: https://skymansandy.dev/wiretapKMP/ktor/api?q=

Installs the WiretapKtorHttpPlugin into your Ktor HttpClient. This plugin provides HTTP request/response logging with mock/throttle rule support. Configuration options are available within the WiretapHttpConfig DSL.

```APIDOC
## WiretapKtorHttpPlugin

### Description
Top-level Ktor client plugin for HTTP request/response logging with mock/throttle rule support.

### Installation
```kotlin
HttpClient {
    install(WiretapKtorHttpPlugin) {
        // WiretapHttpConfig DSL — all properties optional
        enabled = true
        shouldLog = { url, method -> true }
        headerAction = { key -> HeaderAction.Keep }
        logRetention = LogRetention.Forever
        maxContentLength = 100 * 1024
    }
}
```

### Lifecycle Hooks
Hook | Purpose  
---|---
`onRequest` | Captures request timestamps (ms + ns)  
`on(Send)` | Intercepts request: evaluates rules, logs request, applies mock/throttle  
`onResponse` | Updates log entry with response data
```

--------------------------------

### Install Ktor Wiretap Plugin

Source: https://skymansandy.dev/wiretapKMP/getting-started

Integrate the WiretapKtorHttpPlugin into your Ktor HttpClient to enable network traffic capture.

```kotlin
val client = HttpClient {
    install(WiretapKtorHttpPlugin)
}
```

--------------------------------

### Install Wiretap Interceptor with Custom Configuration

Source: https://skymansandy.dev/wiretapKMP/okhttp/setup

Configure the Wiretap interceptor with custom settings for logging, retention, and header handling when building an OkHttpClient.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor {
        enabled = true                                    // default
        shouldLog = { url, method -> true }               // default: log everything
        logRetention = LogRetention.Days(7)
        maxContentLength = 100 * 1024                     // truncate bodies > 100 KB
        headerAction = { key ->
            when {
                key.equals("Authorization", ignoreCase = true) -> HeaderAction.Mask()
                key.equals("Cookie", ignoreCase = true) -> HeaderAction.Skip
                else -> HeaderAction.Keep
            }
        }
    })
    .build()
```

--------------------------------

### Setup SSE Listener with Wiretap

Source: https://skymansandy.dev/wiretapKMP/okhttp/sse

Use the wiretapped() extension on an EventSourceListener to enable SSE inspection. This requires opting into experimental APIs.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
val factory = EventSources.createFactory(client)
val source = factory.newEventSource(request, myListener.wiretapped())
```

--------------------------------

### Body Matching Examples

Source: https://skymansandy.dev/wiretapKMP/configuration/rules

Shows how to match request bodies using WiretapKMP's BodyMatcher. Supports exact string, substring, and regex matching.

```kotlin
BodyMatcher.Exact("{\"action\": \"delete\"}")
BodyMatcher.Contains("delete")
BodyMatcher.Regex("\"action\":\\s*\"delete\"")
```

--------------------------------

### Swift Construction of WiretapURLSession

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Example of configuring WiretapURLSession in Swift, enabling logging and setting retention policies based on build configuration.

```swift
let session = WiretapURLSession { config in
    #if DEBUG
    config.enabled = true
    #else
    config.enabled = false
    #endif
    config.logRetention = LogRetentionDays(days: 7)
    config.maxContentLength = 100 * 1024
    config.shouldLog = { url, method in KotlinBoolean(value: true) }
    config.headerAction = { key in HeaderActionKeep.shared }
}
```

--------------------------------

### Configure WiretapOkHttpInterceptor

Source: https://skymansandy.dev/wiretapKMP/configuration/config

Example configuration for the WiretapOkHttpInterceptor, mirroring Ktor plugin settings for enabled status, logging filters, header actions, log retention, and max content length.

```kotlin
WiretapOkHttpInterceptor {
    enabled = true
    shouldLog = { url, _ -> url.contains("/api/") }
    headerAction = { key -> HeaderAction.Keep }
    logRetention = LogRetention.AppSession
    maxContentLength = 100 * 1024
}
```

--------------------------------

### Configure WiretapKtorHttpPlugin

Source: https://skymansandy.dev/wiretapKMP/configuration/config

Example configuration for the WiretapKtorHttpPlugin, including enabled status, logging filters, header actions, log retention, and max content length.

```kotlin
install(WiretapKtorHttpPlugin) {
    enabled = true
    shouldLog = { url, _ -> url.contains("/api/") }
    headerAction = { key -> HeaderAction.Keep }
    logRetention = LogRetention.AppSession
    maxContentLength = 100 * 1024
}
```

--------------------------------

### Install WiretapKtorSsePlugin for SSE logging

Source: https://skymansandy.dev/wiretapKMP/ktor/migration?q=

SSE logging is a new experimental API in RC10. Install the `WiretapKtorSsePlugin` to automatically wrap sessions for SSE logging.

```kotlin
val client = HttpClient {
    install(WiretapKtorSsePlugin) {
        enabled = true
    }
}

@OptIn(ExperimentalWiretapSseApi::class)
client.sse("https://example.com/events") {
    incoming.collect { event ->
        println("Event: ${event.data}")
    }
}
```

--------------------------------

### Create Debug and Release URLSession

Source: https://skymansandy.dev/wiretapKMP/urlsession/setup

Use WiretapURLSession in debug builds and standard URLSession in release builds to avoid production overhead. This example demonstrates conditional initialization and configuration.

```swift
#if DEBUG
import WiretapURLSession
#endif

class NetworkClient {

    #if DEBUG
    private let session: WiretapURLSession

    init() {
        session = WiretapURLSession(configuration: .default) { config in
            config.enabled = true
            config.shouldLog = { url, method in
                KotlinBoolean(value: url.contains("/api/"))
            }
            config.headerAction = { key in
                if key.caseInsensitiveCompare("Authorization") == .orderedSame {
                    return HeaderActionMask(mask: "***")
                }
                if key.caseInsensitiveCompare("Cookie") == .orderedSame {
                    return HeaderActionSkip.shared
                }
                return HeaderActionKeep.shared
            }
            config.logRetention = LogRetentionDays(days: 7)
            config.maxContentLength = 100 * 1024
        }
    }
    #else
    private let session = URLSession.shared

    init() {}
    #endif
}
```

--------------------------------

### Install Wiretap with SSE Support

Source: https://skymansandy.dev/wiretapKMP/ktor/setup

Enable Wiretap logging for Server-Sent Events (SSE) alongside HTTP logging. The SSE plugin handles session data automatically.

```kotlin
val client = HttpClient {
    install(SSE)
    install(WiretapKtorSsePlugin)        // SSE logging
    install(WiretapKtorHttpPlugin)       // HTTP logging
}
```

--------------------------------

### Manually Start Wiretap Inspector

Source: https://skymansandy.dev/wiretapKMP/configuration/shake

Call startWiretap() programmatically to launch the inspector at any time. This is useful for triggering the inspector from a debug menu or button.

```kotlin
startWiretap()

```

--------------------------------

### POST Request with intercept()

Source: https://skymansandy.dev/wiretapKMP/urlsession/http

Example of making a POST request using the intercept() method. The request body is captured and logged automatically.

```swift
var request = URLRequest(url: URL(string: "https://api.example.com/users")!)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try? JSONSerialization.data(withJSONObject: [
    "name": "John Doe",
    "email": "john@example.com",
])

session.intercept(request: request) { data, response, error in
    // Request body is captured in the log
}

```

--------------------------------

### WiretapOkHttpInterceptor

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

OkHttp Interceptor for HTTP request/response logging with mock/throttle rule support. It can be installed by adding it to the OkHttpClient.Builder.

```APIDOC
## WiretapOkHttpInterceptor

### Description
OkHttp `Interceptor` for HTTP request/response logging with mock/throttle rule support.

### Constructor
- **configure** (`WiretapHttpConfig.() -> Unit`) - Required - Configuration builder lambda.

### Installation
```kotlin
OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor {
        // WiretapHttpConfig properties — all optional
    })
    .build()
```

### TLS Details Captured
- **protocol** (`response.protocol`)
- **remoteAddress** (`chain.connection()?.route()?.socketAddress`)
- **tlsProtocol** (`handshake.tlsVersion.javaName`)
- **cipherSuite** (`handshake.cipherSuite.javaName`)
- **certificateCn** (Peer certificate subject CN)
- **issuerCn** (Peer certificate issuer CN)
- **certificateExpiry** (`peerCert.notAfter`)
```

--------------------------------

### Configure SSE Logging with DSL

Source: https://skymansandy.dev/wiretapKMP/okhttp/sse

Configure SSE logging using the config DSL overload, for example, to enable logging only in debug builds. Requires opting into experimental APIs.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
factory.newEventSource(request, myListener.wiretapped {
    enabled = BuildConfig.DEBUG
})
```

--------------------------------

### WiretapOkHttpWebSocketListener

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Wraps a consumer's `WebSocketListener` to log all WebSocket events. It can be installed using an extension function or directly via the constructor.

```APIDOC
## WiretapOkHttpWebSocketListener

### Description
Wraps a consumer's `WebSocketListener` to log all WebSocket events.

### Installation
```kotlin
// Extension function (recommended)
client.newWebSocket(request, myListener.wiretapped())

// Constructor
client.newWebSocket(request, WiretapOkHttpWebSocketListener(myListener))
```

### Intercepted Callbacks
- **onOpen(webSocket, response)** - Logged As: Connection opened. WebSocket wrapped for outgoing logging
- **onMessage(webSocket, text)** - Logged As: Text message received
- **onMessage(webSocket, bytes)** - Logged As: Binary message received
- **onClosing(webSocket, code, reason)** - Logged As: Status → Closing
- **onClosed(webSocket, code, reason)** - Logged As: Status → Closed
- **onFailure(webSocket, t, response)** - Logged As: Status → Failed
```

--------------------------------

### WiretapOkHttpEventSourceListener

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Wraps a consumer's `EventSourceListener` to log all SSE events. It can be installed using an extension function or directly via the constructor.

```APIDOC
## WiretapOkHttpEventSourceListener

### Description
Wraps a consumer's `EventSourceListener` to log all SSE events.

### Installation
```kotlin
// Extension function (recommended)
factory.newEventSource(request, myListener.wiretapped())

// Constructor
factory.newEventSource(request, WiretapOkHttpEventSourceListener(myListener))
```

### Intercepted Callbacks
- **onOpen(eventSource, response)** - Logged As: Connection opened with URL and request headers
- **onEvent(eventSource, id, type, data)** - Logged As: Event logged with type, data, ID, and byte count
- **onClosed(eventSource)** - Logged As: Status → Closed
- **onFailure(eventSource, t, response)** - Logged As: Status → Failed
```

--------------------------------

### Custom URLSession Configuration

Source: https://skymansandy.dev/wiretapKMP/urlsession/http

Example of creating a custom URLSessionConfiguration to set properties like request timeout. This configuration is then passed to WiretapURLSession.

```swift
let config = URLSessionConfiguration.default
config.timeoutIntervalForRequest = 5

let session = WiretapURLSession(configuration: config) { config in
    config.enabled = true
}

```

--------------------------------

### Automatic WebSocket Session Wrapping and Logging

Source: https://skymansandy.dev/wiretapKMP/ktor/websockets

Demonstrates how WiretapKtorWebSocketPlugin automatically logs sent and received WebSocket frames without extra calls. The example shows sending a text message and receiving frames.

```kotlin
client.webSocket("wss://echo.websocket.org") {
    // Send — automatically logged
    send(Frame.Text("Hello, server!"))

    // Receive — automatically logged as frames are consumed
    for (frame in incoming) {
        when (frame) {
            is Frame.Text -> println("Received: ${frame.readText()}")
            is Frame.Binary -> println("Received ${frame.readBytes().size} bytes")
            else -> {}
        }
    }
}
```

--------------------------------

### Enable SSE Logging with @OptIn

Source: https://skymansandy.dev/wiretapKMP/okhttp/migration

Enable the new experimental SSE logging feature by applying the @OptIn annotation with ExperimentalWiretapSseApi at the call site.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
factory.newEventSource(request, myListener.wiretapped())
```

--------------------------------

### WiretapURLSession with Custom Configuration

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Demonstrates creating a WiretapURLSession instance with a custom URLSessionConfiguration and enabling its features.

```swift
let config = URLSessionConfiguration.default
config.timeoutIntervalForRequest = 10

let session = WiretapURLSession(configuration: config) { config in
    config.enabled = true
}
```

--------------------------------

### Enable Wiretap Launcher in JVM Desktop Application

Source: https://skymansandy.dev/wiretapKMP/configuration/shake

Call enableWiretapLauncher() once during your JVM Desktop application startup.

```kotlin
fun main() = application {
    enableWiretapLauncher()
    // ...
}

```

--------------------------------

### Enable Inspector UI

Source: https://skymansandy.dev/wiretapKMP/urlsession/setup

Enable the Wiretap inspector UI by calling `enableLaunchTool()` during application initialization.

```swift
@main
struct MyApp: App {
    init() {
        WiretapLauncher_iosKt.enableLaunchTool()
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
```

--------------------------------

### Enable Wiretap Inspector (Kotlin)

Source: https://skymansandy.dev/wiretapKMP/getting-started

Call this function once at application startup to enable the shake-to-open inspector for Android and JVM Desktop.

```kotlin
enableWiretapLauncher()
```

--------------------------------

### dataTask(request:completionHandler:)

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Creates a data task with logging. The caller must call `resume()` on the returned task.

```APIDOC
## dataTask(request:completionHandler:)

### Description
Creates a data task with logging. Captures full request/response body, headers, timing, and detects cancellation automatically. Mock/throttle rules are NOT applied.

### Method
POST (Implied by data task creation)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **request** (`NSURLRequest`) - Required - The URL request to execute.
- **completionHandler** (`(NSData?, NSURLResponse?, NSError?) -> Unit`) - Required - Called with response data.
```

--------------------------------

### Update WebSocket config import

Source: https://skymansandy.dev/wiretapKMP/ktor/migration?q=

The `WiretapWsConfig` has moved from the Ktor plugin package to the core module. Update the import path.

```kotlin
- import dev.skymansandy.wiretap.plugin.ws.WiretapWsConfig
+ import dev.skymansandy.wiretap.domain.model.config.ws.WiretapWsConfig
```

--------------------------------

### WiretapURLSession Constructor

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Initializes WiretapURLSession with optional configuration for network inspection.

```swift
class WiretapURLSession(
    configuration: NSURLSessionConfiguration = NSURLSessionConfiguration.defaultSessionConfiguration,
    configure: WiretapHttpConfig.() -> Unit = {},
)
```

--------------------------------

### Configure SSE Logging with Enabled Parameter

Source: https://skymansandy.dev/wiretapKMP/okhttp/sse

Enable or disable SSE logging using the simple 'enabled' parameter. Requires opting into experimental APIs.

```kotlin
@OptIn(ExperimentalWiretapSseApi::class)
factory.newEventSource(request, myListener.wiretapped(enabled = false))
```

--------------------------------

### Enable Wiretap Inspector (Swift)

Source: https://skymansandy.dev/wiretapKMP/getting-started

Call this function once at application startup to enable the shake-to-open inspector for iOS.

```swift
WiretapLauncher_iosKt.enableLaunchTool()
```

--------------------------------

### Keep Header Action

Source: https://skymansandy.dev/wiretapKMP/configuration/headers

Logs the header as-is. This is the default behavior.

```kotlin
headerAction = { HeaderAction.Keep }
```

--------------------------------

### dataTask(request:completionHandler:)

Source: https://skymansandy.dev/wiretapKMP/urlsession/api?q=

Creates a data task with logging enabled. The caller is responsible for calling `resume()` on the returned task. This method captures full request/response bodies, headers, and timing, and automatically detects and logs cancellations.

```APIDOC
## dataTask(request:completionHandler:)

Creates a data task with logging. Caller must call `resume()`.

```swift
fun dataTask(
    request: NSURLRequest,
    completionHandler: (NSData?, NSURLResponse?, NSError?) -> Unit,
): NSURLSessionDataTask
```

### Parameters

- **request** (`NSURLRequest`): The URL request to execute.
- **completionHandler** (`(NSData?, NSURLResponse?, NSError?) -> Unit`): Called with response data. Captures full request/response body, headers, timing, and detects/logs cancellation automatically. Mock/throttle rules are NOT applied; use `intercept()` for rule support.
```

--------------------------------

### Integrate Wiretap with SSE

Source: https://skymansandy.dev/wiretapKMP/okhttp/setup

Use the `wiretapped()` extension on your `EventSourceListener` to log Server-Sent Events.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor())
    .build()

val factory = EventSources.createFactory(client)
val request = Request.Builder().url("https://example.com/events").build()
factory.newEventSource(request, myEventSourceListener.wiretapped())
```

--------------------------------

### Add OkHttp Dependency

Source: https://skymansandy.dev/wiretapKMP/getting-started

Add the WiretapKMP OkHttp integration for debug builds. Use the noop variant for release builds.

```kotlin
debugImplementation("dev.skymansandy:wiretap-okhttp:1.0.0-RC14")
releaseImplementation("dev.skymansandy:wiretap-okhttp-noop:1.0.0-RC14")
```

--------------------------------

### Enable Wiretap Launcher in iOS (Swift) App

Source: https://skymansandy.dev/wiretapKMP/configuration/shake

Call WiretapLauncherKt.enableWiretapLauncher() in the initializer of your Swift App struct.

```swift
import WiretapKit

@main
struct MyApp: App {
    init() {
        WiretapLauncherKt.enableWiretapLauncher()
    }
}

```

--------------------------------

### Configure Header Actions

Source: https://skymansandy.dev/wiretapKMP/urlsession/setup

Defines actions for specific headers like Authorization and Cookie. Use `.shared` for Kotlin objects like HeaderActionSkip and HeaderActionKeep.

```swift
config.headerAction = { key in
    if key.caseInsensitiveCompare("Authorization") == .orderedSame {
        return HeaderActionMask(mask: "***")
    }
    if key.caseInsensitiveCompare("Cookie") == .orderedSame {
        return HeaderActionSkip.shared
    }
    return HeaderActionKeep.shared
}
```

--------------------------------

### Enable WiretapKtorHttpPlugin

Source: https://skymansandy.dev/wiretapKMP/configuration/config

Master switch for the WiretapKtorHttpPlugin. When false, requests bypass logging and rule evaluation.

```kotlin
install(WiretapKtorHttpPlugin) {
    enabled = BuildConfig.DEBUG
}
```

--------------------------------

### Enable Wiretap Launcher in Android Application

Source: https://skymansandy.dev/wiretapKMP/configuration/shake

Call enableWiretapLauncher() once during app startup in your Android Application class.

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()        enableWiretapLauncher()
    }
}

```

--------------------------------

### intercept(request:completionHandler:)

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Fire-and-forget execution with full mock/throttle rule support. Executes immediately if no rule matches.

```APIDOC
## intercept(request:completionHandler:)

### Description
Executes a request with full mock/throttle rule support. Mock rules return mock data immediately. Throttle rules delay execution. If no rule applies, the request is executed immediately.

### Method
POST (Implied by request execution)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **request** (`NSURLRequest`) - Required - The URL request to execute.
- **completionHandler** (`(NSData?, NSHTTPURLResponse?, NSError?) -> Unit`) - Required - Called with response data.
```

--------------------------------

### Enable Wiretap Launcher in iOS (KMP) View Controller

Source: https://skymansandy.dev/wiretapKMP/configuration/shake

Call enableWiretapLauncher() in your iOS KMP UIViewController initializer.

```kotlin
fun MainViewController(): UIViewController {
    enableWiretapLauncher()
    // ...
}

```

--------------------------------

### Configuring WebSocket Logging with DSL

Source: https://skymansandy.dev/wiretapKMP/okhttp/websockets

Configure WebSocket logging behavior, such as binary frame decoding, using the `wiretapped` DSL overload. The `enabled` property controls whether logging is active.

```kotlin
client.newWebSocket(request, myListener.wiretapped {
    enabled = BuildConfig.DEBUG

    // How to render Binary frames. Defaults to Auto.
    binaryDecoding = BinaryFrameDecoding.Auto
    // = BinaryFrameDecoding.Utf8         // always decode as UTF-8 (replacement chars on invalid bytes)
    // = BinaryFrameDecoding.Placeholder  // never decode, always show "[Binary: N bytes]"
    // = BinaryFrameDecoding.Custom { bytes -> bytes.toHexPreview() }
})
```

--------------------------------

### Add OkHttp Interceptor

Source: https://skymansandy.dev/wiretapKMP/getting-started

Incorporate the WiretapOkHttpInterceptor into your OkHttpClient builder to capture network requests.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor())
    .build()
```

--------------------------------

### Allowlist Pattern for Headers

Source: https://skymansandy.dev/wiretapKMP/configuration/headers

Logs only specified headers by skipping all others. This pattern is useful for controlling the amount of data logged.

```kotlin
val allowedHeaders = setOf("content-type", "accept", "cache-control")

headerAction = { key ->
    if (key.lowercase() in allowedHeaders) HeaderAction.Keep
    else HeaderAction.Skip
}
```

--------------------------------

### Update WiretapOkHttpInterceptor Package Import

Source: https://skymansandy.dev/wiretapKMP/okhttp/migration

Update the import statement for WiretapOkHttpInterceptor to reflect its new location in the http subpackage.

```kotlin
- import dev.skymansandy.wiretap.okhttp.WiretapOkHttpInterceptor
+ import dev.skymansandy.wiretap.okhttp.http.WiretapOkHttpInterceptor
```

--------------------------------

### dataTask(url:completionHandler:)

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Convenience overload for creating a data task from an NSURL.

```APIDOC
## dataTask(url:completionHandler:)

### Description
Convenience overload for creating a data task from an `NSURL`. The caller must call `resume()` on the returned task.

### Method
POST (Implied by data task creation)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **url** (`NSURL`) - Required - The `NSURL` to request.
- **completionHandler** (`(NSData?, NSURLResponse?, NSError?) -> Unit`) - Required - Called with response data.
```

--------------------------------

### dataTask(url:completionHandler:)

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Convenience overload for creating a data task from a URL string.

```APIDOC
## dataTask(url:completionHandler:)

### Description
Convenience overload for creating a data task from a URL string. The caller must call `resume()` on the returned task.

### Method
POST (Implied by data task creation)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **url** (`String`) - Required - The URL string to request.
- **completionHandler** (`(NSData?, NSURLResponse?, NSError?) -> Unit`) - Required - Called with response data.
```

--------------------------------

### Update WiretapConfig imports for Ktor

Source: https://skymansandy.dev/wiretapKMP/ktor/migration?q=

Renamed WiretapConfig to WiretapHttpConfig and moved config classes to protocol-specific subpackages. Update your import statements accordingly.

```kotlin
- import dev.skymansandy.wiretap.domain.model.config.WiretapConfig
- import dev.skymansandy.wiretap.domain.model.config.HeaderAction
- import dev.skymansandy.wiretap.domain.model.config.LogRetention
+ import dev.skymansandy.wiretap.domain.model.config.http.WiretapHttpConfig
+ import dev.skymansandy.wiretap.domain.model.config.http.HeaderAction
+ import dev.skymansandy.wiretap.domain.model.config.http.LogRetention
```

--------------------------------

### WiretapURLSession Constructor DSL Update

Source: https://skymansandy.dev/wiretapKMP/urlsession/migration?q=

Shows the change in the `WiretapURLSession` constructor's type from `WiretapConfig` to `WiretapHttpConfig`. The constructor DSL itself remains unchanged.

```kotlin
- WiretapURLSession { // this: WiretapConfig
+ WiretapURLSession { // this: WiretapHttpConfig
      enabled = true
  }
```

--------------------------------

### Declare WiretapKtorHttpPlugin

Source: https://skymansandy.dev/wiretapKMP/ktor/api

Declares the top-level Ktor client plugin for HTTP logging with mock/throttle support.

```kotlin
val WiretapKtorHttpPlugin: ClientPlugin<WiretapHttpConfig>
```

--------------------------------

### Use wiretapped() Extension for WebSocket Listener

Source: https://skymansandy.dev/wiretapKMP/okhttp/migration

Replace the direct instantiation of WiretapOkHttpWebSocketListener with the new wiretapped() extension function for creating WebSocket listeners.

```kotlin
- import dev.skymansandy.wiretap.okhttp.WiretapOkHttpWebSocketListener
- val listener = WiretapOkHttpWebSocketListener(myListener)
- client.newWebSocket(request, listener)
+ import dev.skymansandy.wiretap.okhttp.ws.wiretapped
+ client.newWebSocket(request, myListener.wiretapped { enabled = true })
```

--------------------------------

### Integrate Wiretap with WebSocket

Source: https://skymansandy.dev/wiretapKMP/okhttp/setup

Wrap your WebSocket listener with the `wiretapped()` extension to enable logging for WebSocket communication.

```kotlin
val client = OkHttpClient.Builder()
    .addInterceptor(WiretapOkHttpInterceptor())
    .build()

client.newWebSocket(request, myWebSocketListener.wiretapped())
```

--------------------------------

### Add Ktor Dependency

Source: https://skymansandy.dev/wiretapKMP/getting-started?q=

Include the WiretapKtor plugin for debug builds and a no-op version for release builds.

```gradle
// Debug only — use wiretap-ktor-noop for release builds
debugImplementation("dev.skymansandy:wiretap-ktor:1.0.0-RC14")
releaseImplementation("dev.skymansandy:wiretap-ktor-noop:1.0.0-RC14")
```

--------------------------------

### WiretapKtorWebSocketPlugin Configuration

Source: https://skymansandy.dev/wiretapKMP/ktor/websockets

Configures the WiretapKtorWebSocketPlugin, including enabling it based on build configuration and setting the binary frame decoding strategy.

```kotlin
install(WiretapKtorWebSocketPlugin) {
    enabled = BuildConfig.DEBUG

    // How to render Binary frames. Defaults to Auto.
    binaryDecoding = BinaryFrameDecoding.Auto
    // = BinaryFrameDecoding.Utf8         // always decode as UTF-8 (replacement chars on invalid bytes)
    // = BinaryFrameDecoding.Placeholder  // never decode, always show "[Binary: N bytes]"
    // = BinaryFrameDecoding.Custom { bytes -> bytes.toHexPreview() }
}
```

--------------------------------

### No-op (wiretap-okhttp-noop)

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Provides a no-operation (no-op) replacement for OkHttp components, offering zero overhead.

```APIDOC
## No-op (wiretap-okhttp-noop)

### Component Behavior
- **WiretapOkHttpInterceptor**: `chain.proceed(chain.request())`
- **WiretapOkHttpWebSocketListener**: Pure delegation to original listener
- **WiretapOkHttpEventSourceListener**: Pure delegation to original listener
- **wiretapModule**: Empty Koin module

Same constructor signatures — zero overhead, drop-in replacement.
```

--------------------------------

### dataTask with Request

Source: https://skymansandy.dev/wiretapKMP/urlsession/api

Creates a data task for a given URLRequest, enabling logging and automatic cancellation detection. Caller must call resume().

```kotlin
fun dataTask(
    request: NSURLRequest,
    completionHandler: (NSData?, NSURLResponse?, NSError?) -> Unit,
): NSURLSessionDataTask
```

--------------------------------

### Programmatic Rule Management

Source: https://skymansandy.dev/wiretapKMP/configuration/rules?q=

Provides functions for interacting with the rule repository, including adding, retrieving, enabling/disabling, deleting, and clearing all rules.

```kotlin
val ruleRepository = WiretapDi.ruleRepository

ruleRepository.addRule(rule)                        // Add
ruleRepository.getAll()                             // Flow<List<WiretapRule>>
ruleRepository.setEnabled(ruleId, enabled = false)  // Toggle
ruleRepository.deleteById(ruleId)                   // Delete
ruleRepository.deleteAll()                          // Clear all
```

--------------------------------

### Configure Log Retention Policy

Source: https://skymansandy.dev/wiretapKMP/okhttp/setup

Set the `logRetention` policy to manage how long log entries are stored in the SQLite database, with options for indefinite storage, session-based, or time-based pruning.

```kotlin
WiretapOkHttpInterceptor {
    // Keep all logs indefinitely (default)
    logRetention = LogRetention.Forever

    // Clear all logs on app restart — only current session visible
    logRetention = LogRetention.AppSession

    // Auto-prune entries older than N days
    logRetention = LogRetention.Days(7)
}
```

--------------------------------

### No-op Component Behaviors

Source: https://skymansandy.dev/wiretapKMP/okhttp/api

Details the behavior of no-op components in the wiretap-okhttp-noop module, including WiretapOkHttpInterceptor, WiretapOkHttpWebSocketListener, WiretapOkHttpEventSourceListener, and wiretapModule. These provide zero overhead, drop-in replacements.

```kotlin
`WiretapOkHttpInterceptor` | `chain.proceed(chain.request())`
```

```kotlin
`WiretapOkHttpWebSocketListener` | Pure delegation to original listener
```

```kotlin
`WiretapOkHttpEventSourceListener` | Pure delegation to original listener
```

```kotlin
`wiretapModule` | Empty Koin module
```
Tokens:
Raw