Netra Flutter Plugin #

⚠️ Platform Support: Android only. iOS is not currently supported.

Built on top of a native Kotlin networking engine. A powerful Flutter networking plugin with built-in caching, offline queueing, slow network strategies, circuit breaker support, multipart uploads, and event-driven observability.

📱 Check out the example app for a full working demo.

⚙️ Installation #

flutter pub add netra_flutter

Why Netra? #

Netra focuses on real-world mobile networking problems:

Unreliable connections
Offline-first architecture
Slow networks
Cache consistency
Request recovery
Developer observability

Instead of only being an HTTP client, Netra aims to provide a resilient networking layer for modern Flutter applications.

Netra vs Dio Ecosystem #

Most Netra features can be implemented with Dio and additional packages.

The difference is that Netra provides them as a unified networking layer out of the box.

Capability	Dio Ecosystem	Netra
HTTP Requests	Dio	Built-in
Multipart Upload	Dio	Built-in
Request Cancellation	Dio	Built-in
Caching	Dio + dio_cache_interceptor	Built-in
Offline Cache Fallback	Dio + dio_cache_interceptor configuration	Built-in
Offline Queue	Custom implementation	Built-in
Retry On Reconnect	offline_retry_interceptor + custom persistence	Built-in
Slow Network Policies	Custom implementation	Built-in
Circuit Breaker	Custom implementation	Built-in
Request Lifecycle Events	Custom interceptors	Built-in
Cache Events	Custom implementation	Built-in
Queue Events	Custom implementation	Built-in
Unified API	Multiple packages	Single SDK

Quick Example #

final client = NetraClient(
  baseUrl: "https://api.example.com",
);

client.on(RequestEvent.requestExecuted((request) {
print("executing: ${request.url}");
}));

client.on(RequestEvent.requestSuccess((request, response) {
print("success: ${response.statusCode} data: ${response.data}");
}));

client.on(RequestEvent.requestFailed((request, response, exception) {
print("failed: ${response?.statusCode}");
}));

final response = await client.get(
  requestOptions: RequestOptions(
    url: "/users",
    cacheOptions: CacheOptions(ttl: 60000),
    offlinePolicyAction: OfflinePolicyAction.queue,
    slowNetworkPolicyAction: SlowNetworkPolicyAction.useCache,
  ),
);

Features #

⚡ Simple async/await API
📦 GET, POST, PUT, PATCH, DELETE support
🧠 Smart cache system (memory + disk)
📡 Offline request handling (queue / retry / cache fallback)
🐢 Slow network strategies (wait / timeout / cache fallback)
👀 Event-driven observers (request, cache, queue, network)
🖼 Multipart file/image upload
📥 Streaming support for large responses
🔄 Automatic queued request restoration
🔥 Circuit breaker support
🧩 Converter support (Gson, KotlinX, Moshi)
🛑 Request cancellation on dispose
🧵 Fully async Dart API
🛡️ Guaranteed background execution for long-running requests

Create Client #

final netraClient = NetraClient(
  baseUrl: "https://api.example.com",
  headers: {
    "Authorization": "Bearer token",
  },
  converterType: ConverterType.gson,
);

With circuit breaker:

final netraClient = NetraClient(
  baseUrl: "https://api.example.com",
  converterType: ConverterType.gson,
  circuitBreakerOptions: CircuitBreakerOptions(
    failureThreshold: 5,
    retryDelayMs: 1000,
  ),
);

RequestOptions #

All requests are configured via RequestOptions:

RequestOptions(
  url: "/users",                          // required
  body: null,                             // RequestBody?
  headers: {"X-Custom": "value"},         // per-request headers
  offlinePolicyAction: ...,               // OfflinePolicyAction?
  slowNetworkPolicyAction: ...,           // SlowNetworkPolicyAction?
  cacheOptions: CacheOptions(),           // cache config
  cancelOnDispose: true,                  // auto-cancel on widget dispose
  executionMode: ExecutionMode.direct,    // Execution Mode Direct or Guaranteed
)

GET Request #

final result = await netraClient.get(
  requestOptions: RequestOptions(
    url: "/users",
  ),
);

print(result?.statusCode);
print(result?.data);

POST Request #

final result = await netraClient.post(
  requestOptions: RequestOptions(
    url: "/users",
    body: RequestBody.createJson(
      jsonEncode({"name": "Sinem", "job": "developer"}),
    ),
  ),
);

PUT Request #

final result = await netraClient.put(
  requestOptions: RequestOptions(
    url: "/users/1",
    body: RequestBody.createJson(
      jsonEncode({"name": "Sinem", "job": "mobile developer"}),
    ),
  ),
);

PATCH Request #

final result = await netraClient.patch(
  requestOptions: RequestOptions(
    url: "/users/1",
    body: RequestBody.createJson(
      jsonEncode({"name": "Sinem"}),
    ),
  ),
);

DELETE Request #

final result = await netraClient.delete(
  requestOptions: RequestOptions(
    url: "/users/1",
  ),
);

Example Response #

result?.statusCode      // int
result?.statusMessage   // String?
result?.headers         // Map<String, String?>?
result?.data            // dynamic
result?.isCache         // bool — true if served from cache

Response Types #

The examples above assume the simple, common case — the request ran and you got real data back. But not every request finishes immediately: an offline-queued or background request hasn't run yet when the call returns. To make that explicit, Netra returns a sealed NetraResponse<T> with two variants:

sealed class NetraResponse<T> {}

class ResponseReceived<T> extends NetraResponse<T> {
  final T? data;
  final int statusCode;
  final String? statusMessage;
  final Map<String, String?>? headers;
  final bool isCache;
}

class ResponseQueued<T> extends NetraResponse<T> {
  final int queueOrder;
}

Variant	When you get it
`ResponseReceived`	The normal case — the request actually ran and you have a real response (online, or served from cache)
`ResponseQueued`	The request was deferred instead of run immediately — either `offlinePolicyAction: OfflinePolicyAction.queue` was set and the device is offline, or `backgroundOptions` was set (see Background Execution)

Handle both explicitly with a switch:

final result = await netraClient.get(
  requestOptions: RequestOptions(
    url: "/users",
    offlinePolicyAction: OfflinePolicyAction.queue,
  ),
);

switch (result) {
  case ResponseReceived(:final data, :final statusCode):
    print("received: $statusCode data: $data");
  case ResponseQueued(:final queuePosition):
    print("queued position $queuePosition");
}

⚠️ When Execution Guaranteed Mode is set, ResponseQueued is always returned — regardless of whether the device is online — because the request is handed off to a guaranteed background executor from the start rather than run inline. Listen to Queue Events to find out when it actually finishes.

Request Body Types #

JSON #

RequestBody.createJson(jsonEncode({"name": "Sinem"}))

Bytes #

RequestBody.createBytes(
  Uint8List.fromList(utf8.encode(jsonEncode({"name": "Sinem"}))),
)

Multipart #

final part = RequestBodyPart.file(
  name: "image",
  fileName: "photo.jpg",
  bytes: bytes,
  contentType: "image/jpeg",
);

RequestBody.multipart([part])

Multipart Upload #

final XFile? file = await picker.pickImage(source: ImageSource.gallery);
if (file != null) {
  final bytes = await file.readAsBytes();

  final result = await netraClient.post(
    requestOptions: RequestOptions(
      url: "/upload",
      body: RequestBody.multipart([
        RequestBodyPart.file(
          name: "image",
          fileName: file.name,
          bytes: bytes,
          contentType: "image/jpeg",
        ),
      ]),
    ),
  );

  print(result?.statusCode);
}

Streaming #

For large responses (images, files, audio), use getStream to consume data chunk by chunk.

final stream = await netraClient.getStream(
  requestOptions: RequestOptions(
    url: "/image",
    cancelOnDispose: true,
  ),
);

final List<int> imageBytes = [];

stream.listen(
  (data) {
    imageBytes.addAll(data);
  },
  onDone: () {
    final bytes = Uint8List.fromList(imageBytes);
    // use bytes
  },
  onError: (e) {
    print("stream error: $e");
  },
);

Cache Support #

final result = await netraClient.get(
  requestOptions: RequestOptions(
    url: "/users",
    cacheOptions: CacheOptions(),
  ),
);

print(result?.isCache);  // true if served from cache

Custom TTL:

cacheOptions: CacheOptions(ttl: 60000)  // 1 minute in ms

Offline Support #

final result = await netraClient.get(
  requestOptions: RequestOptions(
    url: "/users",
    offlinePolicyAction: OfflinePolicyAction.queue,
  ),
);

Available offline actions:

Action	Description
`OfflinePolicyAction.queue`	Stores request, retries automatically when connection is restored
`OfflinePolicyAction.useCache`	Returns cached response if available
`OfflinePolicyAction.retry(retries, retryInterval)`	Retries N times with given interval
`OfflinePolicyAction.throwError`	Immediately throws a network error

RETRY example: #

offlinePolicyAction: OfflinePolicyAction.retry(
  retries: 3,
  retryInterval: Duration(seconds: 2),
),

Guaranteed Execution #

For requests that should survive the app being backgrounded or killed — large uploads, big downloads, anything you don't want lost if the user leaves mid-request — set backgroundOptions. The request is handed off to a guaranteed background executor immediately; get/post/etc. return ResponseQueued right away, and the real result arrives later through Queue Events.

final result = await netraClient.post(
  requestOptions: RequestOptions(
    url: "/uploads/photo",
    body: RequestBody.multipart([...]),
    executionMode: ExecutionMode.guaranteed
  ),
);

// result is always ResponseQueued here

Listen for the eventual result the same way you'd listen for offline queue events:

netraClient.on(QueueEvent.queuedRequestExecuted((url, response) {
  print("background upload finished: ${response.statusCode}");
}));

netraClient.on(QueueEvent.queuedRequestFailed((url) {
  print("background upload failed: $url");
}));

Combining backgroundOptions with offlinePolicyAction is allowed but redundant — backgroundOptions already defers the request unconditionally, so the offline policy is never evaluated in that case.

Slow Network Strategies #

final result = await netraClient.get(
  requestOptions: RequestOptions(
    url: "/users",
    slowNetworkPolicyAction: SlowNetworkPolicyAction.useCache,
  ),
);

Available actions:

Action	Description
`SlowNetworkPolicyAction.useCache`	Returns cached response immediately
`SlowNetworkPolicyAction.wait(delay)`	Waits given duration before sending request
`SlowNetworkPolicyAction.timeout(timeout)`	Throws error if request exceeds duration

WAIT example: #

slowNetworkPolicyAction: SlowNetworkPolicyAction.wait(
  delay: Duration(seconds: 2),
),

TIMEOUT example: #

slowNetworkPolicyAction: SlowNetworkPolicyAction.timeout(
  timeout: Duration(milliseconds: 2000),
),

Per-Request Headers #

requestOptions: RequestOptions(
  url: "/users",
  headers: {
    "X-Custom-Header": "value",
  },
),

Cancel on Dispose #

Requests marked with cancelOnDispose: true are automatically cancelled when the widget is disposed.

requestOptions: RequestOptions(
  url: "/users",
  cancelOnDispose: true,
),

Converter Support #

Converter	Enum
Gson	`ConverterType.gson`
Kotlinx Serialization	`ConverterType.kotlinX`
Moshi	`ConverterType.moshi`

final netraClient = NetraClient(
  baseUrl: "https://api.example.com",
  converterType: ConverterType.kotlinX,
);

Observers #

Netra uses an event-driven system. Attach listeners with on() and detach with off().

// attach — returns an eventId
final eventId = netraClient.on(
  CacheEvent.cacheStaleUsed((request, ageMs, ttlMs, expiredByMs) {
    print("stale cache used: ${request.url}");
  }),
);

// detach
netraClient.off(eventId);

Request Events #

netraClient.on(RequestEvent.requestExecuted((request) {
  print("executing: ${request.url}");
}));

netraClient.on(RequestEvent.requestSuccess((request, response) {
  print("success: ${response.statusCode} data: ${response.data}");
}));

netraClient.on(RequestEvent.requestFailed((request, response, exception) {
  print("failed: ${response?.statusCode}");
}));

Cache Events #

netraClient.on(CacheEvent.cacheHit((request, ageMs, ttlMs) {
  print("cache hit: ${request.url}");
}));

netraClient.on(CacheEvent.cacheMiss((request) {
  print("cache miss: ${request.url}");
}));

netraClient.on(CacheEvent.cacheStored((request, ageMs, ttlMs) {
  print("cache stored: ${request.url}");
}));

netraClient.on(CacheEvent.cacheExpired((request, ageMs, ttlMs, expiredByMs) {
  print("cache expired: ${request.url}");
}));

netraClient.on(CacheEvent.cacheStaleUsed((request, ageMs, ttlMs, expiredByMs) {
  print("stale cache used: ${request.url}");
}));

Event	Description
`cacheHit`	Valid cached data found and returned
`cacheMiss`	No cache entry exists
`cacheStored`	Response saved to cache
`cacheExpired`	Cache exists but TTL has passed
`cacheStaleUsed`	Expired cache returned as fallback

Queue Events #

netraClient.on(QueueEvent.requestQueued((url, queueOrder, createdAt) {
  print("queued: $url order: $queueOrder");
}));

netraClient.on(QueueEvent.queuedRequestRestored((url) {
  print("restored: $url");
}));

netraClient.on(QueueEvent.queuedRequestExecuted((url, response) {
  print("executed: $url status: ${response.statusCode}");
}));

netraClient.on(QueueEvent.queuedRequestFailed((url) {
  print("queue failed: $url");
}));

Event	Description
`requestQueued`	Request stored in offline queue
`queuedRequestRestored`	Connection restored, queue processing started
`queuedRequestExecuted`	Queued request succeeded
`queuedRequestFailed`	Queued request failed on retry

These same events also fire for backgroundOptions requests — a background request is a queued request under the hood, just deferred unconditionally instead of only when offline.

Network Events #

netraClient.on(NetworkEvent.offline(() {
  print("offline");
}));

netraClient.on(NetworkEvent.slowNetwork(() {
  print("slow network");
}));

netraClient.on(NetworkEvent.connectionRestored(() {
  print("connection restored");
}));

Event	Description
`offline`	Device lost internet connection
`slowNetwork`	Network is congested or degraded
`connectionRestored`	Internet connection is back

Circuit Breaker #

Automatically stops sending requests after a threshold of consecutive failures.

final netraClient = NetraClient(
  baseUrl: "https://api.example.com",
  circuitBreakerOptions: CircuitBreakerOptions(
    failureThreshold: 5,
    retryDelayMs: 1000,
  ),
);

Roadmap #

❌ iOS support
❌ WebSocket support
❌ Request deduplication
❌ Logging interceptor

License #

MIT License

netra_flutter 1.0.4 netra_flutter: ^1.0.4 copied to clipboard

Metadata