# universal_io 2.0.5 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:2.0.5' ``` Published: 2023-02-16T13:50:41.511328Z Expected archive SHA-256: 2730b3fced23063ef4b4a12d0ff2a697d26dbf7dc83e36790a816abea0680b85 Available in cache; verification: upstream_checksum ## Direct dependencies - collection: ^1.15.0 - crypto: ^3.0.0 - meta: ^1.3.0 - typed_data: ^1.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, mobile, desktop, and server-side). The API is exactly the same API as _dart:io_. You can simply replace _dart:io_ imports with _package:universal_io/io.dart_. Normal _dart:io_ will continue to be used when your application runs in non-Javascript platforms. 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 * [API reference](https://pub.dev/documentation/universal_io/latest/) * [Github project](https://github.com/dint-dev/universal_io) * We appreciate feedback, issue reports, and pull requests. ## Similar packages * [universal_html](https://pub.dev/packages/universal_html) (cross-platform _dart:html_) # Getting started ## 1.Add dependency ```yaml dependencies: universal_io: ^2.0.4 ``` ## 2.Use APIs ```dart import 'package:universal_io/io.dart'; Future main() async { // HttpClient can be used in browser too! final httpClient = HttpClient(); final request = await httpClient.getUrl(Uri.parse("http://example/url")); final response = await request.close(); } ``` # Behavior in browsers ## Platform The following [Platform](https://api.dart.dev/stable/2.12.2/dart-io/Platform-class.html) APIs work in browsers: * Platform.locale * Platform.operatingSystem * Platform.operatingSystemVersion ## HTTP client HTTP client is implemented with [XMLHttpRequest (XHR)](https://developer.mozilla.org/en/docs/Web/API/XMLHttpRequest) (in _dart:html_, the class is [HttpRequest](https://api.dart.dev/stable/2.12.2/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. ### Helpful error messages When requests fail and assertions are enabled, error messages contains descriptions how to fix possible issues such as missing cross-origin headers. The error messages look like the following: ``` XMLHttpRequest error. ------------------------------------------------------------------------------- HTTP method: PUT HTTP URL: http://destination.com/example Origin: http://source.com Cross-origin: true browserCredentialsMode: false browserResponseType: arraybuffer THE REASON FOR THE XHR ERROR IS UNKNOWN. (For security reasons, browsers do not explain XHR errors.) Is the server down? Did the server have an internal error? Enabling credentials mode would enable use of some HTTP headers in both the request and the response. For example, credentials mode is required for sending/receiving cookies. If you think you need to enable 'credentials mode', do the following: final httpClientRequest = ...; if (httpClientRequest is BrowserHttpClientRequest) { httpClientRequest.browserCredentialsMode = true; } Did the server respond to a cross-origin "preflight" (OPTIONS) request? Did the server send the following headers? * Access-Control-Allow-Origin: http://source.com * You can also use wildcard ("*"). * Always required for cross-origin requests! * Access-Control-Allow-Methods: PUT * You can also use wildcard ("*"). ``` Sometimes when you do cross-origin requests in browsers, you want to use [CORS "credentials mode"](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). This can be achieved with the following pattern: ```dart Future main() async { final client = HttpClient(); final request = client.getUrl(Url.parse('http://example/url')); // Enable credentials mode if (request is BrowserHttpClientRequest) { request.browserCredentialsMode = true; } // Close request final response = await request.close(); // ... } ``` See [source code](https://github.com/dint-dev/universal_io/blob/master/lib/src/browser/http_client_request.dart). ### Streaming text responses The underlying XMLHttpRequest (XHR) API supports response streaming only when _responseType_ is "text". This package automatically uses _responseType_ "text" in some cases based on value of the HTTP request header "Accept". If you want to always have arraybuffer / text responses, use: ```dart Future main() async { final client = HttpClient(); final request = client.getUrl(Url.parse('http://example/url')); // The following causes XHR responseType 'text' to be used when request is closed. request.headers.set('Accept', 'text/plain'); // Use XHR responseType 'arraybuffer'. if (request is BrowserHttpClientRequest) { request.browserResponseType = 'arrayBuffer'; } // Close request final response = await request.close(); // ... } ``` See [source code](https://github.com/dint-dev/universal_io/blob/master/lib/src/browser/http_client_request.dart). ## Changelog # 2.0.4 * Fixes Platform.operatingSystemVersion ([issue #9](https://github.com/dint-dev/universal_io/issues/9)). # 2.0.3 * Fixes various issues. # 2.0.2 * Fixes issue [#17](https://github.com/dint-dev/universal_io/issues/17). # 2.0.1 * Fixes issues in Node.JS. # 2.0.0 * Finishes migration to null safety. # 2.0.0-nullsafety.2 * Eliminated unnecessary dependencies. # 2.0.0-nullsafety.1 * Improves documentation. * Improves BrowserHttpClientException messages. * Deprecates libraries _prefer_sdk/io.dart_ and _prefer_universal/io.dart_. Developers should import just _io.dart_. # 2.0.0-nullsafety.0 * The first null-safe version. * Makes changes in BrowserHttpClient / BrowserHttpClientRequest API: * The property for enabling credentials mode is now `browserCredentialsMode`. The default is `false`. * The property for setting response type is now `browserResponseType` ("arraybuffer", "text", etc.). By default, if HTTP request header "Accept" contains only text MIMEs ("text/plain", etc.), this package uses _responseType_ "text". * HTTP client now has `onBrowserHttpClientRequestClose` for using your own logic for setting `browserResponseType`. * Removes IO adapter API. # 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`. 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.