// Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. import 'dart:async'; import 'dart:convert'; import 'dart:typed_data'; import 'package:collection/collection.dart'; import 'base_request.dart'; import 'client.dart'; import 'exception.dart'; import 'request.dart'; import 'response.dart'; import 'streamed_response.dart'; /// The abstract base class for an HTTP client. This is a mixin-style class; /// subclasses only need to implement [send] and maybe [close], and then they /// get various convenience methods for free. abstract class BaseClient implements Client { /// Sends an HTTP HEAD request with the given headers to the given URL, which /// can be a [Uri] or a [String]. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> head(dynamic url, {Map<String, String> headers}) => _sendUnstreamed("HEAD", url, headers); /// Sends an HTTP GET request with the given headers to the given URL, which /// can be a [Uri] or a [String]. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> get(dynamic url, {Map<String, String> headers}) => _sendUnstreamed("GET", url, headers); /// Sends an HTTP POST request with the given headers and body to the given /// URL, which can be a [Uri] or a [String]. /// /// [body] sets the body of the request. It can be a [String], a [List<int>] /// or a [Map<String, String>]. If it's a String, it's encoded using /// [encoding] and used as the body of the request. The content-type of the /// request will default to "text/plain". /// /// If [body] is a List, it's used as a list of bytes for the body of the /// request. /// /// If [body] is a Map, it's encoded as form fields using [encoding]. The /// content-type of the request will be set to /// `"application/x-www-form-urlencoded"`; this cannot be overridden. /// /// [encoding] defaults to UTF-8. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> post(dynamic url, {Map<String, String> headers, dynamic body, Encoding encoding}) => _sendUnstreamed("POST", url, headers, body, encoding); /// Sends an HTTP PUT request with the given headers and body to the given /// URL, which can be a [Uri] or a [String]. /// /// [body] sets the body of the request. It can be a [String], a [List<int>] /// or a [Map<String, String>]. If it's a String, it's encoded using /// [encoding] and used as the body of the request. The content-type of the /// request will default to "text/plain". /// /// If [body] is a List, it's used as a list of bytes for the body of the /// request. /// /// If [body] is a Map, it's encoded as form fields using [encoding]. The /// content-type of the request will be set to /// `"application/x-www-form-urlencoded"`; this cannot be overridden. /// /// [encoding] defaults to UTF-8. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> put(dynamic url, {Map<String, String> headers, dynamic body, Encoding encoding}) => _sendUnstreamed("PUT", url, headers, body, encoding); /// Sends an HTTP PATCH request with the given headers and body to the given /// URL, which can be a [Uri] or a [String]. /// /// [body] sets the body of the request. It can be a [String], a [List<int>] /// or a [Map<String, String>]. If it's a String, it's encoded using /// [encoding] and used as the body of the request. The content-type of the /// request will default to "text/plain". /// /// If [body] is a List, it's used as a list of bytes for the body of the /// request. /// /// If [body] is a Map, it's encoded as form fields using [encoding]. The /// content-type of the request will be set to /// `"application/x-www-form-urlencoded"`; this cannot be overridden. /// /// [encoding] defaults to UTF-8. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> patch(dynamic url, {Map<String, String> headers, dynamic body, Encoding encoding}) => _sendUnstreamed("PATCH", url, headers, body, encoding); /// Sends an HTTP DELETE request with the given headers to the given URL, /// which can be a [Uri] or a [String]. /// /// For more fine-grained control over the request, use [send] instead. @override Future<Response> delete(dynamic url, {Map<String, String> headers}) => _sendUnstreamed("DELETE", url, headers); /// Sends an HTTP GET request with the given headers to the given URL, which /// can be a [Uri] or a [String], and returns a Future that completes to the /// body of the response as a String. /// /// The Future will emit a [ClientException] if the response doesn't have a /// success status code. /// /// For more fine-grained control over the request and response, use [send] or /// [get] instead. @override Future<String> read(dynamic url, {Map<String, String> headers}) { return get(url, headers: headers).then((Response response) { _checkResponseSuccess(url, response); return response.body; }); } /// Sends an HTTP GET request with the given headers to the given URL, which /// can be a [Uri] or a [String], and returns a Future that completes to the /// body of the response as a list of bytes. /// /// The Future will emit an [ClientException] if the response doesn't have a /// success status code. /// /// For more fine-grained control over the request and response, use [send] or /// [get] instead. @override Future<Uint8List> readBytes(dynamic url, {Map<String, String> headers}) { return get(url, headers: headers).then((Response response) { _checkResponseSuccess(url, response); return response.bodyBytes; }); } /// Sends an HTTP request and asynchronously returns the response. /// /// Implementers should call [BaseRequest.finalize] to get the body of the /// request as a [ByteStream]. They shouldn't make any assumptions about the /// state of the stream; it could have data written to it asynchronously at a /// later point, or it could already be closed when it's returned. Any /// internal HTTP errors should be wrapped as [ClientException]s. @override Future<StreamedResponse> send(BaseRequest request); /// Sends a non-streaming [Request] and returns a non-streaming [Response]. Future<Response> _sendUnstreamed(String method, dynamic url, Map<String, String> headers, [dynamic body, Encoding encoding]) async { if (url is String) url = Uri.parse(url); Request request = new Request(method, url); if (headers != null) request.headers.addAll(headers); if (encoding != null) request.encoding = encoding; if (body != null) { if (body is String) { request.body = body; } else if (body is List) { request.bodyBytes = DelegatingList.typed(body); } else if (body is Map) { request.bodyFields = DelegatingMap.typed(body); } else { throw new ArgumentError('Invalid request body "$body".'); } } return Response.fromStream(await send(request)); } /// Throws an error if [response] is not successful. void _checkResponseSuccess(dynamic url, Response response) { if (response.statusCode < 400) return; String message = "Request to $url failed with status ${response.statusCode}"; if (response.reasonPhrase != null) { message = "$message: ${response.reasonPhrase}"; } if (url is String) url = Uri.parse(url); throw new ClientException("$message.", url); } /// Closes the client and cleans up any resources associated with it. It's /// important to close each client when it's done being used; failing to do so /// can cause the Dart process to hang. @override void close() {} }