Add Kotlin listings for OkHttp recipes doc

Author: swankjesse

build.gradle

@@ -37,6 +37,7 @@ buildscript {
       'junit': "junit:junit:${versions.junit}",
       'kotlinStdlib': "org.jetbrains.kotlin:kotlin-stdlib:${versions.kotlin}",
       'moshi': "com.squareup.moshi:moshi:${versions.moshi}",
+      'moshiKotlin': "com.squareup.moshi:moshi-kotlin-codegen:${versions.moshi}",
       'okio': "com.squareup.okio:okio:${versions.okio}",
       'openjsse': "org.openjsse:openjsse:${versions.openjsse}"
   ]

docs/connections.md

@@ -3,7 +3,7 @@ Connections
 
 Although you provide only the URL, OkHttp plans its connection to your webserver using three types: URL, Address, and Route.
 
-#### [URLs](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-http-url/)
+### [URLs](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-http-url/)
 
 URLs (like `https://github.com/square/okhttp`) are fundamental to HTTP and the Internet. In addition to being a universal, decentralized naming scheme for everything on the web, they also specify how to access web resources.
 
@@ -14,21 +14,21 @@ URLs are abstract:
 
 They're also concrete: each URL identifies a specific path (like `/square/okhttp`) and query (like `?q=sharks&lang=en`). Each webserver hosts many URLs.
 
-#### [Addresses](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-address/)
+### [Addresses](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-address/)
 
 Addresses specify a webserver (like `github.com`) and all of the **static** configuration necessary to connect to that server: the port number, HTTPS settings, and preferred network protocols (like HTTP/2 or SPDY).
 
 URLs that share the same address may also share the same underlying TCP socket connection. Sharing a connection has substantial performance benefits: lower latency, higher throughput (due to [TCP slow start](http://www.igvita.com/2011/10/20/faster-web-vs-tcp-slow-start/)) and conserved battery. OkHttp uses a [ConnectionPool](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection-pool/) that automatically reuses HTTP/1.x connections and multiplexes HTTP/2 and SPDY connections.
 
 In OkHttp some fields of the address come from the URL (scheme, hostname, port) and the rest come from the [OkHttpClient](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-ok-http-client/).
 
-#### [Routes](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-route/)
+### [Routes](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-route/)
 
 Routes supply the **dynamic** information necessary to actually connect to a webserver. This is the specific IP address to attempt (as discovered by a DNS query), the exact proxy server to use (if a [ProxySelector](http://developer.android.com/reference/java/net/ProxySelector.html) is in use), and which version of TLS to negotiate (for HTTPS connections).
 
 There may be many routes for a single address. For example, a webserver that is hosted in multiple datacenters may yield multiple IP addresses in its DNS response.
 
-#### [Connections](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection/)
+### [Connections](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-connection/)
 
 When you request a URL with OkHttp, here's what it does:
 

docs/https.md

@@ -43,46 +43,123 @@ OkHttpClient client = new OkHttpClient.Builder()
     .build();
 ```
 
-#### [Certificate Pinning](https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/CertificatePinning.java)
+### Certificate Pinning ([.kt][CertificatePinningKotlin], [.java][CertificatePinningJava]) 
 
 By default, OkHttp trusts the certificate authorities of the host platform. This strategy maximizes connectivity, but it is subject to certificate authority attacks such as the [2011 DigiNotar attack](http://www.computerworld.com/article/2510951/cybercrime-hacking/hackers-spied-on-300-000-iranians-using-fake-google-certificate.html). It also assumes your HTTPS servers’ certificates are signed by a certificate authority.
 
 Use [CertificatePinner](http://square.github.io/okhttp/4.x/okhttp/okhttp3/-certificate-pinner/) to restrict which certificates and certificate authorities are trusted. Certificate pinning increases security, but limits your server team’s abilities to update their TLS certificates. **Do not use certificate pinning without the blessing of your server’s TLS administrator!**
 
-```java
-  public CertificatePinning() {
-    client = new OkHttpClient.Builder()
-        .certificatePinner(new CertificatePinner.Builder()
-            .add("publicobject.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")
-            .build())
-        .build();
+```Kotlin tab=
+  private val client = OkHttpClient.Builder()
+      .certificatePinner(
+          CertificatePinner.Builder()
+              .add("publicobject.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")
+              .build())
+      .build()
+
+  fun run() {
+    val request = Request.Builder()
+        .url("https://publicobject.com/robots.txt")
+        .build()
+
+    client.newCall(request).execute().use { response ->
+      if (!response.isSuccessful) throw IOException("Unexpected code $response")
+
+      for (certificate in response.handshake!!.peerCertificates) {
+        println(CertificatePinner.pin(certificate))
+      }
+    }
   }
+```
+
+```Java tab=
+  private final OkHttpClient client = new OkHttpClient.Builder()
+      .certificatePinner(
+          new CertificatePinner.Builder()
+              .add("publicobject.com", "sha256/afwiKY3RxoMmLkuRW1l7QsPZTJPwDS2pdDROQjXw8ig=")
+              .build())
+      .build();
 
   public void run() throws Exception {
     Request request = new Request.Builder()
         .url("https://publicobject.com/robots.txt")
         .build();
 
-    Response response = client.newCall(request).execute();
-    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
+    try (Response response = client.newCall(request).execute()) {
+      if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
 
-    for (Certificate certificate : response.handshake().peerCertificates()) {
-      System.out.println(CertificatePinner.pin(certificate));
+      for (Certificate certificate : response.handshake().peerCertificates()) {
+        System.out.println(CertificatePinner.pin(certificate));
+      }
     }
   }
 ```
 
-#### [Customizing Trusted Certificates](https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/CustomTrust.java)
+### Customizing Trusted Certificates ([.kt][CustomTrustKotlin], [.java][CustomTrustJava])
 
 The full code sample shows how to replace the host platform’s certificate authorities with your own set. As above, **do not use custom certificates without the blessing of your server’s TLS administrator!**
 
-```java
+```Kotlin tab=
+  private val client: OkHttpClient
+
+  init {
+    val trustManager = trustManagerForCertificates(trustedCertificatesInputStream())
+    val sslContext = SSLContext.getInstance("TLS")
+    sslContext.init(null, arrayOf<TrustManager>(trustManager), null)
+    val sslSocketFactory = sslContext.socketFactory
+
+    client = OkHttpClient.Builder()
+        .sslSocketFactory(sslSocketFactory, trustManager)
+        .build()
+  }
+
+  fun run() {
+    val request = Request.Builder()
+        .url("https://publicobject.com/helloworld.txt")
+        .build()
+
+    client.newCall(request).execute().use { response ->
+      if (!response.isSuccessful) throw IOException("Unexpected code $response")
+
+      for ((name, value) in response.headers) {
+        println("$name: $value")
+      }
+
+      println(response.body!!.string())
+    }
+  }
+
+  /**
+   * Returns an input stream containing one or more certificate PEM files. This implementation just
+   * embeds the PEM files in Java strings; most applications will instead read this from a resource
+   * file that gets bundled with the application.
+   */
+  private fun trustedCertificatesInputStream(): InputStream {
+    ... // Full source omitted. See sample.
+  }
+
+  private fun trustManagerForCertificates(inputStream: InputStream): X509TrustManager {
+    ... // Full source omitted. See sample.
+  }
+```
+
+```Java tab=
   private final OkHttpClient client;
 
   public CustomTrust() {
-    SSLContext sslContext = sslContextForTrustedCertificates(trustedCertificatesInputStream());
+    X509TrustManager trustManager;
+    SSLSocketFactory sslSocketFactory;
+    try {
+      trustManager = trustManagerForCertificates(trustedCertificatesInputStream());
+      SSLContext sslContext = SSLContext.getInstance("TLS");
+      sslContext.init(null, new TrustManager[] { trustManager }, null);
+      sslSocketFactory = sslContext.getSocketFactory();
+    } catch (GeneralSecurityException e) {
+      throw new RuntimeException(e);
+    }
+
     client = new OkHttpClient.Builder()
-        .sslSocketFactory(sslContext.getSocketFactory())
+        .sslSocketFactory(sslSocketFactory, trustManager)
         .build();
   }
 
@@ -103,3 +180,8 @@ The full code sample shows how to replace the host platform’s certificate auth
     ... // Full source omitted. See sample.
   }
 ```
+
+ [CustomTrustJava]: https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/CustomTrust.java
+ [CustomTrustKotlin]: https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/kt/CustomTrust.kt
+ [CertificatePinningJava]: https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/CertificatePinning.java
+ [CertificatePinningKotlin]: https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/kt/CertificatePinning.kt

docs/interceptors.md

@@ -29,7 +29,7 @@ Interceptors can be chained. Suppose you have both a compressing interceptor and
 
 ![Interceptors Diagram](images/[email protected])
 
-#### Application Interceptors
+### Application Interceptors
 
 Interceptors are registered as either _application_ or _network_ interceptors. We'll use the `LoggingInterceptor` defined above to show the difference.
 
@@ -64,7 +64,7 @@ Connection: keep-alive
 
 We can see that we were redirected because `response.request().url()` is different from `request.url()`. The two log statements log two different URLs.
 
-#### Network Interceptors
+### Network Interceptors
 
 Registering a network interceptor is quite similar. Call `addNetworkInterceptor()` instead of `addInterceptor()`:
 
@@ -113,7 +113,7 @@ Connection: keep-alive
 
 The network requests also contain more data, such as the `Accept-Encoding: gzip` header added by OkHttp to advertise support for response compression. The network interceptor's `Chain` has a non-null `Connection` that can be used to interrogate the IP address and TLS configuration that were used to connect to the webserver.
 
-#### Choosing between application and network interceptors
+### Choosing between application and network interceptors
 
 Each interceptor chain has relative merits.
 
@@ -132,7 +132,7 @@ Each interceptor chain has relative merits.
  * Observe the data just as it will be transmitted over the network.
  * Access to the `Connection` that carries the request.
 
-#### Rewriting Requests
+### Rewriting Requests
 
 Interceptors can add, remove, or replace request headers. They can also transform the body of those requests that have one. For example, you can use an application interceptor to add request body compression if you're connecting to a webserver known to support it.
 
@@ -172,7 +172,7 @@ final class GzipRequestInterceptor implements Interceptor {
 }
 ```
 
-#### Rewriting Responses
+### Rewriting Responses
 
 Symmetrically, interceptors can rewrite response headers and transform the response body. This is generally more dangerous than rewriting request headers because it may violate the webserver's expectations!