Issue #1012: Add new concept-fetch component.

The `concept-fetch` component contains interfaces for defining an abstract HTTP client for fetching resources.

Author: pocmo

README.md

@@ -83,6 +83,8 @@ _API contracts and abstraction layers for browser components._
 
 * ⚪ [**Engine**](components/concept/engine/README.md) - Abstraction layer that allows hiding the actual browser engine implementation.
 
+* ⚪ [**Fetch**](components/concept/fetch/README.md) - An abstract definition of an HTTP client for fetching resources.
+
 * 🔴 [**Storage**](components/concept/storage/README.md) - Abstract definition of a browser storage component.
 
 * 🔴 [**Tabstray**](components/concept/tabstray/README.md) - Abstract definition of a tabs tray component.

components/concept/fetch/README.md

@@ -0,0 +1,101 @@
+# [Android Components](../../../README.md) > Concept > Fetch
+
+The `concept-fetch` component contains interfaces for defining an abstract HTTP client for fetching resources.
+
+The primary use of this component is to hide the actual implementation of the HTTP client from components required to make HTTP requests. This allows apps to configure a single app-wide used client without the components enforcing a particular dependency.
+
+The API and name of the component is inspired by the [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+
+## Usage
+
+### Setting up the dependency
+
+Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):
+
+```Groovy
+implementation "org.mozilla.components:concept-fetch:{latest-version}"
+```
+
+### Performing requests
+
+#### Get a URL
+
+```Kotlin
+val request = Request(url)
+val response = client.fetch(request)
+val body = response.string()
+```
+
+A `Response` may hold references to other resources (e.g. streams). Therefore it's important to always close the `Response` object or its `Body`. This can be done by either consuming the content of the `Body` with one of the available methods or by using Kotlin's extension methods for using `Closeable` implementations (e.g. `use()`):
+
+```Kotlin
+client.fetch(Request(url)).use { response ->
+    val body = response.body.string()
+}
+```
+
+#### Post to a URL
+
+```Kotlin
+val request = Request(
+   url = "...",
+   method = Request.Method.POST,
+   body = Request.Body.fromStream(stream))
+   
+client.fetch(request).use { response ->
+   if (response.success) {
+       // ...
+   }
+}
+```
+
+#### Github API example
+
+```Kotlin
+val request = Request(
+   url = "https://api.github.com/repos/mozilla-mobile/android-components/issues",
+   headers = MutableHeaders(
+       "User-Agent" to "AwesomeBrowser/1.0",
+       "Accept" to "application/json; q=0.5",
+       "Accept" to "application/vnd.github.v3+json"))
+
+client.fetch(request).use { response ->
+    val server = response.headers.get('Server')
+    val result = response.body.string()
+}
+```
+
+#### Posting a file
+
+```Kotlin
+val file = File("README.md")
+
+val request = Request(
+   url = "https://api.github.com/markdown/raw",
+   headers = MutableHeaders(
+       "Content-Type", "text/x-markdown; charset=utf-8"
+   ),
+   body = Request.Body.fromFile(file))
+   
+client.fetch(request).use { response ->
+   if (request.success) {
+      // Upload was successful!
+   }
+}
+   
+```
+
+#### Asynchronous requests
+
+Client implementations are synchronous. For asynchronous requests it's recommended to wrap a client in a Coroutine with a scope the calling code is in control of:
+
+```Kotlin
+val deferredResponse = async { client.fetch(request) }
+val body = deferredResponse.await().body.string()
+```
+
+## License
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/

components/concept/fetch/build.gradle

@@ -0,0 +1,39 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    compileSdkVersion Config.compileSdkVersion
+
+    defaultConfig {
+        minSdkVersion Config.minSdkVersion
+        targetSdkVersion Config.targetSdkVersion
+
+        buildConfigField("String", "LIBRARY_VERSION", "\"" + Config.componentsVersion + "\"")
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+
+dependencies {
+    implementation Deps.kotlin_stdlib
+    implementation Deps.kotlin_coroutines
+
+    testImplementation Deps.testing_junit
+    testImplementation Deps.testing_robolectric
+    testImplementation Deps.testing_mockito
+    testImplementation Deps.testing_mockwebserver
+
+    testImplementation project(':support-test')
+}
+
+apply from: '../../../publish.gradle'
+ext.configurePublish(Config.componentsGroupId, archivesBaseName, gradle.componentDescriptions[archivesBaseName])

components/concept/fetch/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

components/concept/fetch/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="mozilla.components.concept.fetch" />

components/concept/fetch/src/main/java/mozilla/components/concept/fetch/Client.kt

@@ -0,0 +1,59 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+package mozilla.components.concept.fetch
+
+import java.io.IOException
+
+/**
+ * A generic [Client] for fetching resources via HTTP/s.
+ *
+ * Abstract base class / interface for clients implementing the `concept-fetch` component.
+ *
+ * The [Request]/[Response] API is inspired by the Web Fetch API:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+ */
+abstract class Client {
+    /**
+     * Starts the process of fetching a resource from the network as described by the [Request] object.
+     *
+     * A [Response] may keep references to open streams. Therefore it's important to always close the [Response] or
+     * its [Response.Body].
+     *
+     * Use the `use()` extension method when performing multiple operations on the [Response] object:
+     *
+     * ```Kotlin
+     * client.fetch(request).use { response ->
+     *     // Use response. Resources will get released automatically at the end of the block.
+     * }
+     * ```
+     *
+     * Alternatively you can use multiple `use*()` methods on the [Response.Body] object.
+     *
+     * @param request The request to be executed by this [Client].
+     * @return The [Response] returned by the server.
+     * @throws IOException if the request could not be executed due to cancellation, a connectivity problem or a
+     * timeout.
+     */
+    @Throws(IOException::class)
+    abstract fun fetch(request: Request): Response
+
+    /**
+     * List of default headers that should be added to every request unless overridden by the headers in the request.
+     */
+    protected val defaultHeaders: Headers = MutableHeaders(
+        // Unfortunately some implementations will always send a not removable Accept header. Let's override it with
+        // a header that accepts everything.
+        "Accept" to "*/*",
+
+        // We expect all clients to implement gzip decoding transparently.
+        "Accept-Encoding" to "gzip",
+
+        // Default User Agent. Clients are expected to append their own tokens if needed.
+        "User-Agent" to "MozacFetch/${BuildConfig.LIBRARY_VERSION}",
+
+        // We expect all clients to support and use keep-alive by default.
+        "Connection" to "keep-alive"
+    )
+}

components/concept/fetch/src/main/java/mozilla/components/concept/fetch/Headers.kt

@@ -0,0 +1,129 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+package mozilla.components.concept.fetch
+
+import java.lang.IllegalArgumentException
+
+/**
+ * A collection of HTTP [Headers] (immutable) of a [Request] or [Response].
+ */
+interface Headers : Iterable<Header> {
+    /**
+     * Returns the number of headers (key / value combinations).
+     */
+    val size: Int
+
+    /**
+     * Gets the [Header] at the specified [index].
+     */
+    operator fun get(index: Int): Header
+
+    /**
+     * Returns the last values corresponding to the specified header field name. Or null if the header does not exist.
+     */
+    operator fun get(name: String): String?
+
+    /**
+     * Returns the list of values corresponding to the specified header field name.
+     */
+    fun getAll(name: String): List<String>
+
+    /**
+     * Sets the [Header] at the specified [index].
+     */
+    operator fun set(index: Int, header: Header)
+
+    /**
+     * Returns true if a [Header] with the given [name] exists.
+     */
+    operator fun contains(name: String): Boolean
+}
+
+/**
+ * Represents a [Header] containing of a [name] and [value].
+ */
+data class Header(
+    val name: String,
+    val value: String
+) {
+    init {
+        if (name.isEmpty()) {
+            throw IllegalArgumentException("Header name cannot be empty")
+        }
+    }
+}
+
+/**
+ * A collection of HTTP [Headers] (mutable) of a [Request] or [Response].
+ */
+class MutableHeaders(
+    vararg pairs: Pair<String, String>
+) : Headers, MutableIterable<Header> {
+    private val headers: MutableList<Header> = pairs.map {
+            (name, value) -> Header(name, value)
+    }.toMutableList()
+
+    /**
+     * Gets the [Header] at the specified [index].
+     */
+    override fun get(index: Int): Header = headers[index]
+
+    /**
+     * Returns the last value corresponding to the specified header field name. Or null if the header does not exist.
+     */
+    override fun get(name: String) = headers.lastOrNull { header -> header.name == name }?.value
+
+    /**
+     * Returns the list of values corresponding to the specified header field name.
+     */
+    override fun getAll(name: String): List<String> = headers
+        .filter { header -> header.name == name }
+        .map { header -> header.value }
+
+    /**
+     * Sets the [Header] at the specified [index].
+     */
+    override fun set(index: Int, header: Header) {
+        headers[index] = header
+    }
+
+    /**
+     * Returns an iterator over the headers that supports removing elements during iteration.
+     */
+    override fun iterator(): MutableIterator<Header> = headers.iterator()
+
+    /**
+     * Returns true if a [Header] with the given [name] exists.
+     */
+    override operator fun contains(name: String): Boolean = headers.firstOrNull { it.name == name } != null
+
+    /**
+     * Returns the number of headers (key / value combinations).
+     */
+    override val size: Int
+        get() = headers.size
+
+    /**
+     * Append a header without removing the headers already present.
+     */
+    fun append(name: String, value: String): MutableHeaders {
+        headers.add(Header(name, value))
+        return this
+    }
+
+    /**
+     * Set the only occurrence of the header; potentially overriding an already existing header.
+     */
+    fun set(name: String, value: String): MutableHeaders {
+        headers.forEachIndexed { index, current ->
+            if (current.name == name) {
+                headers[index] = Header(name, value)
+                return this
+            }
+        }
+
+        return append(name, value)
+    }
+}