ghuyfel/universal_io

Cross-platform 'dart:io', including browser-compatible HttpClient.

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. Much of the source code is derived from Dart SDK, which was obtained under the BSD-style license of Dart SDK. See LICENSE file for details.

Links

• API reference
• Github project
  • We appreciate feedback, issue reports, and pull requests.

Similar packages

• universal_html (cross-platform dart:html)

Getting started

1.Add dependency

dependencies:
  universal_io: ^2.0.4

2.Use APIs

import 'package:universal_io/io.dart';

Future<void> 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 APIs work in browsers:

• Platform.locale
• Platform.operatingSystem
• Platform.operatingSystemVersion

HTTP client

HTTP client is implemented with XMLHttpRequest (XHR) (in dart:html, the class is HttpRequest).

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". This can be achieved with the following pattern:

Future<void> 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.

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:

Future<void> 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.