Document Dio Interceptors System with Comprehensive Guide and Enhanced Tests

[Copilot]

This PR provides comprehensive documentation for Dio's interceptor system, addressing the lack of detailed documentation for this critical feature. The interceptor system is one of Dio's most powerful capabilities, but it was previously underdocumented, making it difficult for developers to understand and effectively use interceptors.

What's Added

Comprehensive Documentation (/dio/lib/src/interceptors/README.md)

A detailed 16,000+ character guide covering:

Core Architecture:

• Base Interceptor class with lifecycle methods (onRequest, onResponse, onError)
• InterceptorState<T> and InterceptorResultType for state management
• Handler classes and their methods (next, resolve, reject)
• Execution flow and FIFO ordering

Interceptor Types:

• Basic Interceptor for parallel execution
• QueuedInterceptor for serial processing (critical for authentication flows)
• Helper classes: InterceptorsWrapper and QueuedInterceptorsWrapper
• Interceptors list container with built-in interceptor management

Built-in Interceptors:

• ImplyContentTypeInterceptor - automatic content-type detection
• LogInterceptor - configurable request/response logging

Real-world Examples:

// Authentication with token refresh
class AuthInterceptor extends QueuedInterceptor {
  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    if (err.response?.statusCode == 401) {
      refreshToken().then((_) {
        // Retry original request with new token
        final dio = Dio();
        dio.fetch(err.requestOptions).then(handler.resolve);
      });
    }
  }
}

// Request caching
class CacheInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    final cached = cache.get(options.uri.toString());
    if (cached != null) {
      handler.resolve(cached); // Return cached response
      return;
    }
    handler.next(options);
  }
}

Enhanced Test Documentation

Added comprehensive inline documentation to existing tests explaining:

• Handler safety mechanisms (preventing duplicate calls)
• Complex interceptor chain behavior
• Built-in interceptor functionality
• Flow control with callFollowing parameters

New Test Cases

Added 3 critical test cases that demonstrate key concepts:

1. Interceptor Management - Dynamic addition/removal of interceptors
2. Concurrency Behavior - Difference between regular and queued interceptors
3. Flow Control - Handler callFollowing parameter behavior

Why This Matters

Interceptors are essential for:

• Authentication and authorization
• Request/response transformation
• Error handling and retry logic
• Logging and monitoring
• Caching strategies

Without proper documentation, developers often implement these patterns incorrectly or miss powerful features like QueuedInterceptor for serialized operations.

Validation

• ✅ All 24 interceptor tests pass (including 3 new ones)
• ✅ Code formatting meets project standards
• ✅ Documentation examples based on working code patterns
• ✅ Zero breaking changes to existing functionality

The documentation provides both beginner-friendly explanations and advanced patterns, making Dio's interceptor system accessible to developers at all levels.

Fixes #34.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• does.not.exist
  • Triggering command: dart test --preset=default,stable --coverage=coverage/vm --chain-stack-traces (dns block)
• flutter-io.cn
  • Triggering command: dart test --preset=default,stable --coverage=coverage/vm --chain-stack-traces (dns block)
• httpbun.com
  • Triggering command: dart test --preset=default,stable --coverage=coverage/vm --chain-stack-traces (dns block)
• sha256.badssl.com
  • Triggering command: dart test --preset=default,stable --coverage=coverage/vm --chain-stack-traces (dns block)
• wrong.host.badssl.com
  • Triggering command: dart test --preset=default,stable --coverage=coverage/vm --chain-stack-traces (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.