Merge pull request #21 from stanwood/develop

Master merge for final 1.1.0 release

Author: ubuntudroid

README.md

@@ -1,4 +1,5 @@
-[![Release](https://jitpack.io/v/stanwood/Network_android.svg?style=flat-square)](https://jitpack.io/#stanwood/Network_android)
+[![Release](https://jitpack.io/v/stanwood/framework-network-android.svg?style=flat-square)](https://jitpack.io/#stanwood/framework-network-android)
+[![Build Status](https://www.bitrise.io/app/983e6342cc5e0e24/status.svg?token=QtXUf2lbVhJrANROaTkluQ)](https://www.bitrise.io/app/983e6342cc5e0e24)
 
 # stanwood Network Utilities (Android)
 
@@ -23,12 +24,92 @@ Then add this to you app's `build.gradle`:
 
 ```groovy
 dependencies {
-    implementation 'com.github.stanwood:Network_android:<insert latest version here>' // aar version available as well
+    implementation 'com.github.stanwood:framework-network-android:<insert latest version here>' // aar version available as well
 }
 ```
 
 ## Usage
 
 Refer to the extensive javadoc of the provided classes for details on how to use them. Right now there are solutions for the following use cases:
 
-- handle offline situations and caching when using OkHttp (`cache` package)
+- handle offline situations and caching when using OkHttp (`cache` package)
+- generic token based authentication handling with OkHttp (`auth` package)
+
+### cache
+
+TODO
+
+### auth
+
+The `auth` package contains classes for handling token based authentication with OkHttp. Generally this
+is done via Authenticators and Interceptors.
+
+Integration into both existing means of token retrieval as well as from scratch is simple.
+
+First you need to implement both `TokenReaderWriter` and `AuthenticationProvider`.
+The first is used for reading and writing tokens from/to requests.
+The second provides means to get authentication data (such as tokens and sign-in status).
+Refer to the javadoc for more details on how to implement these interfaces.
+In the future optional modules will provide implementations for common use cases.
+
+Then create an instance of `io.stanwood.framework.network.auth.Authenticator`:
+```java
+Authenticator authenticator = new Authenticator(
+    authenticationProvider,
+    tokenReaderWriter,
+    response -> Log.e("Authentication failed permanently!")
+);
+```
+
+And an instance of `AuthInterceptor`:
+```java
+AuthInterceptor authInterceptor = new AuthInterceptor(
+    appContext,
+    authenticationProvider,
+    tokenReaderWriter
+);
+```
+
+Construct an `OkHttpClient` and pass the interceptor and the authenticator:
+```java
+new OkHttpClient.Builder()
+        .authenticator(authenticator)
+        .addInterceptor(authInterceptor)
+        .build();
+```
+
+That's it. When using this `OkHttpClient` instance you'll benefit from fully transparent token handling.
+
+*If your app uses multiple authentication methods make sure to implement an own subclass of `AuthenticationProvider`
+for each method and use an own `OkHttpClient` for each!*
+
+#### A note on authentication exception handling
+
+The library provides an own exception class called `AuthenticationException`. You can listen for this
+class in your Retrofit `Callback.onFailure(Call, Throwable)` to check for authentication related
+errors.
+
+However up until now we are not able to fire this exception everywhere - especially the
+`Authenticator` suffers from a likely [okhttp bug](https://github.com/square/okhttp/issues/3872)
+which prevents us from firing exceptions there. In case of errors you will receive a `NullPointerException`
+instead which probably won't help you much for automated handling as this exception is basically
+caused by every interceptor/authenticator returning `null` for the expected Request/Response.
+
+For the time being we recommend to take a best effort approach here and additionally check for 401 response code
+in Retrofit's `Callback.onSuccess()` for when an issue in the Authenticator occured (if there was no
+issue you won't get a 401 propagated to `Callback.onSuccess()` as in case of successful authentication
+after receiving a 401 for the initial request your callback will get the response code of the following
+originally intended request).
+
+If you're having problems retrieving a token in the `AuthenticationProvider` (e.g. due to an invalid
+refresh token) always try to resolve those issues there as well if possible. Throwing an
+`AuthenticationException` should just be a last resort.
+
+Alternatively you can also subclass the `Authenticator` class and override
+`onAuthenticationFailed()` if you want to trigger special handling for failed authentication from
+which we couldn't recover with our default handling. This usually tends to be a bit harder to get
+right as it expects you to modify the failed request directly without any means of intercepting the
+response. Thus handling token retrieval issues should preferably handled in the `AuthenticationProvider`
+as explained above.
+
+We're looking forward to streamlining this as soon as the okhttp bug has been resolved.

app/build.gradle

@@ -8,7 +8,7 @@ android {
     compileSdkVersion 27
     defaultConfig {
         applicationId "io.stanwood.framework.network.sample"
-        minSdkVersion 21
+        minSdkVersion 16
         targetSdkVersion 27
         versionCode 1
         versionName "1.0"
@@ -24,7 +24,7 @@ android {
 
 dependencies {
     implementation fileTree(include: ['*.jar'], dir: 'libs')
-    implementation "org.jetbrains.kotlin:kotlin-stdlib-jre7:$kotlin_version"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
     implementation 'com.android.support:appcompat-v7:27.0.2'
     implementation 'com.android.support.constraint:constraint-layout:1.0.2'
     testImplementation 'junit:junit:4.12'

build.gradle

@@ -1,13 +1,13 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 
 buildscript {
-    ext.kotlin_version = '1.2.0'
+    ext.kotlin_version = '1.2.21'
     repositories {
         google()
         jcenter()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.0.1'
+        classpath 'com.android.tools.build:gradle:3.1.0-beta2'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
         classpath 'com.github.dcendents:android-maven-gradle-plugin:2.0'
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
-#Wed Dec 13 15:44:17 CET 2017
+#Mon Feb 12 16:58:25 CET 2018
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip

network/build.gradle

@@ -7,7 +7,7 @@ android {
     compileSdkVersion 27
 
     defaultConfig {
-        minSdkVersion 21
+        minSdkVersion 16
         targetSdkVersion 27
         versionCode 1
         versionName "1.0"
@@ -31,7 +31,7 @@ dependencies {
     implementation 'com.android.support:support-annotations:27.0.2'
     testImplementation 'junit:junit:4.12'
     androidTestImplementation 'com.android.support.test:runner:1.0.1'
-    implementation "org.jetbrains.kotlin:kotlin-stdlib-jre7:$kotlin_version"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
     api 'com.squareup.okhttp3:okhttp:3.9.1'
 }
 

network/src/main/AndroidManifest.xml

@@ -1,2 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="io.stanwood.framework.network" />
+    package="io.stanwood.framework.network" >
+
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+</manifest>

network/src/main/java/io/stanwood/framework/network/auth/AuthHeaderKeys.java

@@ -0,0 +1,15 @@
+package io.stanwood.framework.network.auth;
+
+/**
+ * A collection of header keys used by {@link AuthInterceptor} AND {@link Authenticator}
+ * as well as their signed-in variants.
+ */
+@SuppressWarnings("WeakerAccess")
+public abstract class AuthHeaderKeys {
+
+    /**
+     * This header is set by the Authenticators / Auth Interceptors to determine when to retry a
+     * request with a fresh token.
+     */
+    public static final String RETRY_WITH_REFRESH_HEADER_KEY = "RetryWithRefresh";
+}

network/src/main/java/io/stanwood/framework/network/auth/AuthInterceptor.java

@@ -0,0 +1,78 @@
+package io.stanwood.framework.network.auth;
+
+import android.content.Context;
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+import java.io.IOException;
+
+import io.stanwood.framework.network.util.ConnectionState;
+import okhttp3.Interceptor;
+import okhttp3.Request;
+import okhttp3.Response;
+
+/**
+ * This class is used by okhttp to authenticate requests.
+ */
+public class AuthInterceptor implements Interceptor {
+
+    @NonNull
+    private final ConnectionState connectionState;
+    @NonNull
+    private final AuthenticationProvider authenticationProvider;
+    @NonNull
+    private final TokenReaderWriter tokenReaderWriter;
+    @Nullable
+    private final OnAuthenticationFailedListener onAuthenticationFailedListener;
+
+    public AuthInterceptor(
+            @NonNull Context applicationContext,
+            @NonNull AuthenticationProvider authenticationProvider,
+            @NonNull TokenReaderWriter tokenReaderWriter,
+            @Nullable OnAuthenticationFailedListener onAuthenticationFailedListener
+
+    ) {
+        this.connectionState = new ConnectionState(applicationContext);
+        this.authenticationProvider = authenticationProvider;
+        this.tokenReaderWriter = tokenReaderWriter;
+        this.onAuthenticationFailedListener = onAuthenticationFailedListener;
+    }
+
+    @Override
+    public Response intercept(@NonNull Chain chain) throws IOException {
+        Request request = chain.request();
+        request = tokenReaderWriter.removeToken(request);
+        final Request.Builder requestBuilder = request.newBuilder();
+
+        if (connectionState.isConnected()) {
+            String token;
+            synchronized (authenticationProvider.getLock()) {
+                try {
+                    token = authenticationProvider.getToken(false);
+                } catch (AuthenticationException e) {
+                    onAuthenticationFailed();
+                    throw e;
+                }
+            }
+
+            if (token == null) {
+                onAuthenticationFailed();
+                throw new AuthenticationException();
+            }
+
+            requestBuilder.header(AuthHeaderKeys.RETRY_WITH_REFRESH_HEADER_KEY, "true");
+            request = tokenReaderWriter.write(requestBuilder.build(), token);
+        } else {
+            // we're offline, clean up headers for cache handling
+            request = requestBuilder.removeHeader(AuthHeaderKeys.RETRY_WITH_REFRESH_HEADER_KEY).build();
+        }
+
+        return chain.proceed(request);
+    }
+
+    private void onAuthenticationFailed() {
+        if (onAuthenticationFailedListener != null) {
+            onAuthenticationFailedListener.onAuthenticationFailed(null);
+        }
+    }
+}

network/src/main/java/io/stanwood/framework/network/auth/AuthenticationException.java

@@ -0,0 +1,32 @@
+package io.stanwood.framework.network.auth;
+
+import java.io.IOException;
+
+/**
+ * Exception class used by {@link AuthInterceptor} and in the future by {@link Authenticator} to
+ * indicate issues during token retrieval.
+ * <br><br>
+ * Right now we cannot use this for the Authenticator due to a likely
+ * <a href="https://github.com/square/okhttp/issues/3872">bug in okhttp</a> which keeps the
+ * connection open when throwing exceptions in Authenticators.
+ */
+public class AuthenticationException extends IOException {
+
+    public static final String DEFAULT_MESSAGE = "Error while trying to retrieve auth token";
+
+    public AuthenticationException() {
+        super(DEFAULT_MESSAGE);
+    }
+
+    public AuthenticationException(String message) {
+        super(message);
+    }
+
+    public AuthenticationException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public AuthenticationException(Throwable cause) {
+        super(DEFAULT_MESSAGE, cause);
+    }
+}

network/src/main/java/io/stanwood/framework/network/auth/AuthenticationProvider.java

@@ -0,0 +1,33 @@
+package io.stanwood.framework.network.auth;
+
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+/**
+ * Main class to provide authentication information and locks. Used by
+ * Authenticators and Interceptors.
+ * <br><br>
+ * Implement one for each authentication method!
+ */
+public interface AuthenticationProvider {
+
+    /**
+     * Lock used by Authenticator / Auth Interceptor when requesting tokens. Provide a
+     * final static Object here.
+     *
+     * @return lock
+     */
+    @NonNull
+    Object getLock();
+
+    /**
+     * Retrieves a token for authenticated access
+     *
+     * @param forceRefresh whether a new token shall be retrieved from the server and not from cache
+     * @return token
+     *
+     * @throws AuthenticationException if the token cannot be retrieved
+     */
+    @Nullable
+    String getToken(boolean forceRefresh) throws AuthenticationException;
+}