Network Execution Layer

Relevant source files

The following files were used as context for generating this wiki page:

• app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt
• app/src/main/kotlin/com/fathiraz/flowbell/domain/entities/HttpRequestResponseDetails.kt
• app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/screens/webhook/WebhookViewModel.kt
• app/src/main/kotlin/com/fathiraz/flowbell/core/di/DataModule.kt
• app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt

The Network Execution Layer in FlowBell is responsible for the reliable delivery of notification payloads to user-configured webhooks. It serves as the bridge between the device's local notification capture system and external HTTP endpoints. This layer encapsulates request construction, DNS resolution validation, batch processing, and comprehensive diagnostic logging to ensure that high-priority notification data is transmitted securely and efficiently.

This layer is primarily centered around the HttpRequestUtils utility and is utilized by both the NotificationListenerService for real-time/batch forwarding and the Webhook configuration UI for endpoint validation.

Sources: README.md, app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:1-25

Core Components and Architecture

The network architecture follows a service-oriented approach, utilizing OkHttp as the primary engine for HTTP transport.

HttpRequestUtils

This is the central engine of the network layer. It provides high-level methods for testing webhooks and sending payloads. It integrates with Chucker and Beagle for real-time traffic inspection during development.
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:20-50, app/src/main/kotlin/com/fathiraz/flowbell/core/di/DataModule.kt:56

Data Flow for Webhook Dispatch

The following diagram illustrates the flow from a captured notification to the network execution:

DNS Resolution and Validation

A critical feature of the execution layer is the pre-request DNS validation. Before attempting a network connection, the system performs an explicit check to resolve the hostname to prevent silent failures or long timeouts caused by environment-specific network issues (e.g., firewalls or captive portals).

Component	Logic
Connectivity Check	Uses ConnectivityManager to verify NET_CAPABILITY_INTERNET.
Resolution Methods	Attempts InetAddress.getByName() followed by InetAddress.getAllByName().
Diagnostics	Logs DNS server IPs and link properties on failure.

The resolution logic provides specific error messages for scenarios such as "No address associated with hostname" or "Unable to resolve host."
Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:52-115

Webhook Testing and Execution

The execution layer provides specialized methods for testing and production delivery.

Webhook Testing Logic

The testWebhook method generates a mock payload that mirrors the production structure, including device metadata and security nonces, to ensure the destination endpoint is compatible with FlowBell's actual data format.

Production Dispatch

The sendWebhook function handles the final execution of the POST/PUT requests.

// Simplified execution snippet from HttpRequestUtils.kt
val requestBuilder = Request.Builder()
    .url(url)
    .method(method, if (method == "POST" || method == "PUT") requestBody else null)
    .header("Content-Type", "application/json")
    .header("User-Agent", "FlowBell/1.0")

Sources: app/src/main/kotlin/com/fathiraz/flowbell/core/utils/HttpRequestUtils.kt:252-270

Network Models and Logging

Every network operation is encapsulated in a data entity that tracks the full lifecycle of the request.

HttpRequestResponseDetails

This domain entity stores the exhaustive state of a network transaction, allowing the UI to display detailed history and debugging information.

Field	Type	Description
requestMethod	String	GET, POST, etc.
requestUrl	String	The target endpoint.
responseCode	Int	HTTP status code (or -1 on internal error).
duration	Long	Execution time in milliseconds.
timestamp	Long	Epoch time when the request started.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/domain/entities/HttpRequestResponseDetails.kt:3-15, app/src/main/kotlin/com/fathiraz/flowbell/presentation/components/NotificationDetailBottomSheet.kt:210-240

Batch Processing Strategy

To optimize battery life and reduce network overhead, the execution layer supports batch processing. The NotificationListenerService aggregates notifications in a ConcurrentLinkedQueue and drains them every 5 seconds.

• Deduplication: A local cache (processedNotifications) prevents duplicate transmissions for the same notification ID.
• Sequential Delivery: Within a batch, each notification is processed through the standard sendWebhook pipeline.
• Result Persistence: Results for every item in a batch are individually logged to the NotificationQueueRepository with their respective HttpRequestResponseDetails.

Sources: app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:83-118, app/src/main/kotlin/com/fathiraz/flowbell/data/services/NotificationListenerService.kt:300-330

Conclusion

The Network Execution Layer is a robust subsystem designed for the high-reliability requirements of notification bridging. By combining proactive DNS validation, structured diagnostic models, and batched delivery, it ensures that notification data reaches its destination while providing developers with the tools necessary to troubleshoot connectivity issues in diverse network environments.