networking_skill

Overview

This skill packages guidance and utilities for implementing networked data layers: clients, parsing, error mapping, and repository/client tests. It focuses on keeping HTTP concerns in the data layer, converting low-level failures into explicit exceptions, offloading heavy parsing, and making auth token refresh robust and testable. The goal is predictable, testable networking code that scales in Flutter/Dart apps.

How this skill works

The pattern places HTTP calls inside datasource/client implementations that the repository calls, keeping domain code agnostic of transport details. Low-level errors (format issues, network failures) are mapped to explicit exception types at the repository boundary. Large JSON parsing runs off the UI thread using compute or Isolate.run. For authenticated APIs, a three-component pattern (TokenStorage, AuthorizationClient, OAuthInterceptor) centralizes token lifecycle and serializes refresh behavior.

When to use it

• Adding a new API endpoint or client integration
• Parsing large JSON payloads that can block the UI
• Introducing retries, timeouts, or improving network reliability
• Implementing authenticated requests with token refresh
• Writing unit tests for repositories and HTTP clients

Best practices

• Keep HTTP logic confined to the data layer (datasource/client) and expose simple repository interfaces
• Convert FormatException/network errors to explicit ParseException/NetworkException at the repository boundary
• Offload heavy JSON parsing to compute or Isolate.run to avoid jank
• Mock the datasource/client in unit tests—do not perform real HTTP calls
• Store sensitive tokens in secure storage and never in SharedPreferences
• Use a sequential lock in the interceptor so only one token refresh runs on concurrent 401s

Example use cases

• Repository fetchOrders calls IOrdersRemoteDataSource.fetchOrders and maps results to DTOs with error translation
• Parsing thousands of items in background via compute(parseOrders, maps) or Isolate.run for heavier workloads
• Unit tests that mock the remote datasource to assert repository parsing and error mapping
• OAuth flow where AuthorizationClient returns valid tokens and OAuthInterceptor serializes refreshes
• Tests asserting single refresh call when multiple requests receive 401 concurrently