# universal_io 1.0.2

Cross-platform 'dart:io' that works in all platforms (browsers, Flutter, and VM).




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'universal_io:1.0.2'
```
Published: 2021-01-02T22:39:40.952162Z
Expected archive SHA-256: 22c5875f15a25dd8b916566757589dff6c44bd355dcfc0f2e376d9bab7f9e8db

Available in cache; verification: upstream_checksum
## Direct dependencies
- crypto: ^2.1.5
- meta: ^1.1.0
- zone_local: >=0.1.0 <=0.3.0

## Package README (untrusted upstream documentation)
[![Pub Package](https://img.shields.io/pub/v/universal_io.svg)](https://pub.dartlang.org/packages/universal_io)
[![Github Actions CI](https://github.com/dint-dev/universal_io/workflows/Dart%20CI/badge.svg)](https://github.com/dint-dev/universal_io/actions?query=workflow%3A%22Dart+CI%22)

# Overview
A cross-platform _dart:io_ that works in all platforms (browsers, Flutter, and VM).

The API is exactly the same API as _dart:io_. You can simply replace _dart:io_ imports with
_package:universal_io/io.dart_.

Licensed under the [Apache License 2.0](LICENSE).
Much of the source code is derived [from Dart SDK](https://github.com/dart-lang/sdk/tree/master/sdk/lib/io),
which was obtained under the BSD-style license of Dart SDK. See LICENSE file for details.

## Links
  * [Pub package](https://pub.dev/packages/universal_io)
  * [Issue tracker](https://github.com/dint-dev/universal_io/issues)
  * [Create a pull request](https://github.com/dint-dev/universal_io/pull/new/master)

## Similar packages
  * [universal_html](https://pub.dev/packages/universal_html) (cross-platform _dart:html_)


# Getting started
### pubspec.yaml
```yaml
dependencies:
  universal_io: ^1.0.2
```

The may also consider [chrome_os_io](https://pub.dev/packages/chrome_os_io) (if you use Chrome OS)
and [nodejs_io](https://pub.dev/packages/nodejs_io) (if you use Node.JS).

### main.dart

```dart
import 'package:universal_io/io.dart';

Future<void> main() async {
  final httpClient = HttpClient();
  final request = await httpClient.getUrl(Uri.parse("http://google.com"));
  final response = await request.close();
}
```

In some situations, Dart development tools (your IDE) may give warnings, but your application
will compile fine. You can try to eliminate warnings by importing
`"package:universal_io/prefer_universal/io.dart"` or `"package:universal_io/prefer_sdk/io.dart"`


# Browser driver
## HTTP client
HTTP client is implemented using [XMLHttpRequest (XHR)](https://developer.mozilla.org/en/docs/Web/API/XMLHttpRequest)
(in _dart:html_, the class is [HttpRequest](https://api.dart.dev/stable/2.7.1/dart-html/HttpRequest-class.html)).

XHR causes the following differences with _dart:io_:
  * HTTP connection is created only after `request.close()` has been called.
  * Same-origin policy limitations. For making cross-origin requests, see documentation below.

### CORS in browsers
If you do cross-origin requests in browsers, you may want to use
[CORS credentials mode](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).

You can control credentials mode with the following technique:
```dart
final client = HttpClient();
final request = client.openUrl(Url.parse('https://example/path'));
if (request is BrowserHttpClientRequest) {
  request.credentialsMode = BrowserHttpClientCredentialsMode.include;
}
```

If any cross-origin request fails, error message contains a detailed description how to fix
possible issues like missing cross-origin headers. The error messages look like:

```
BrowserHttpClient received an error from XMLHttpRequest (which doesn't tell
reason for the error).

HTTP method:   PUT
URL:           http://destination.com/path/example
Origin:        http://source.com

Cross-origin request!
CORS 'credentials mode' is disabled (the browser will not send cookies).
You can enable 'credentials mode' with:

    if (httpRequest is BrowserHttpClientRequest) {
      httpRequest.credentialsMode = BrowserHttpClientCredentialsMode.include;
    }

Did the server send the following mandatory headers?
  * Access-Control-Allow-Origin: http://source.com
    * OR '*'
  * Access-Control-Allow-Methods: PUT
```

### Streaming responses
The underlying XHR supports streaming only for text responses. You can enable streaming by changing
response type:

```dart
Future<void> main() async {
    // ...

    // Change response type
    if (request is BrowserHttpClientRequest) {
      request.responseType = BrowserHttpClientResponseType.text;
    }

    // Stream chunks
    final response = await request.close();
    response.listen((chunk) {
      // ...
    });
}
```

## Platform
The [implementation](https://github.com/dint-dev/universal_io/blob/master/packages/universal_io/lib/src/driver/default_impl_browser.dart)
supports APIs such as:
  * `Platform.isWindows`
  * `Platform.operatingSystem`
  * `Platform.locale`
## Changelog
# 1.0.2
  * Fixes issue [#11](https://github.com/dint-dev/universal_io/issues/11) (InternetAddress
    parameter).
  * Fixes issue [#12](https://github.com/dint-dev/universal_io/issues/12) (CORS credentials mode).
    Eliminates legacy, complicated behavior. Developers should choose either _omit_ or _include_.
    Improves error messages and documentation related to it.
  * Replaces MD5/SHA1 implementations used by some of the source code copied from _dart:io_. It now
    uses _package:crypto_ instead of implementations copied from _dart:io_.

# 1.0.0
  * Implements recent changes in 'dart:io' (Dart SDK 2.8).
  * HttpDriver is replaced by 'dart:io' HttpOverrides.
  * FileSystemDriver is replaced by 'dart:io' IOOverrides.
  * Various other driver APIs are renamed or removed.
  * BrowserLikeHttpClientRequest is now BrowserHttpClientRequest.
  * BrowserHttpClientRequest implementation is improved.

# 0.8.6
  * Fixed documentation and small fixes related to `nodejs_io`.

# 0.8.5
  * Raised minimum SDK to 2.6 and upgraded dependencies.
  * Changed how CORS credentials mode is enabled. It was previously enabled with a header, but now
    we introduced subclasses for HttpClient and HttpClientRequest. This is a breaking change, but we
    decided not to bump the major version number.
  * Improved analysis and test settings.

# 0.8.4
  * Added 'prefer_sdk/io.dart' and 'prefer_universal/io.dart' libraries for dealing with conditional
    export issues.
  * Library 'package:universal_io/io.dart' now exports SDK version by default.

# 0.8.3
  * Replaced IP address parsing with the new Uri.parseIPv4Address / Uri.parseIPv6Address.
  * Fixed missing HTTP status codes.

# 0.8.2
  * Fixed problems introduced by Dart SDK 2.5.0-dev-2.0.

# 0.8.1
  * Fixed pubspec.yaml and documented Dart SDK 2.5 breaking changes.

# 0.8.0
  * Updated classes to Dart 2.5. See [Dart SDK documentation about the changes](https://github.com/dart-lang/sdk/blob/master/CHANGELOG.md).
    * Various APIs now return `Uint8List` instead of `List<int>`. Examples: `File`, `Socket`, `HttpClientResponse`.
    * Various other breaking changes such as `Cookie` constructor.

# 0.7.3
  * Fixed the following error thrown by the Dart build system in some cases: "Unsupported conditional import of dart:io found in universal_io|lib/io.dart".
  
# 0.7.2
  * Small fixes.
  
# 0.7.1
  * Fixed various bugs.
  * Improved the test suite.
  
# 0.7.0
  * Improved driver base classes and the test suite.
  
# 0.6.0
  * Major refactoring of IODriver API.

# 0.5.1
  * Fixed small bugs.
  
# 0.5.0
  * Fixed various bugs.
  * Re-organized source code.
  * Eliminated dependencies by doing IP parsing in this package.
  * Improved the test suite for drivers.