writing documentation.

Author: peterp

README.md

@@ -1 +1,9 @@
-# redux-http-basic-auth-example
+# redux-http-basic-auth-example
+
+When a client, web or app, communicates with an HTTP API which enforces some form of authentication, the client typically follows this pattern:
+
+  1. The app is not authenticated, the user is presented a log in screen.
+  2. The user enters their username and password, and taps submit.
+  3. The credentials are sent to the API and the app inspects the response:
+    3.1. On success (200 - OK): The authentication token or hash is cached, and the app uses this token in every subsequent request. If at any stage, during an API request, the hash or token doesn't work (401 - Unauthorized) the user needs to be prompted to re-enter their credentials.
+    3.2. On failure (401 - Unauthorized): The client displays an error message to the user, prompting them re-enter their credentials.

actions/friends.js

@@ -0,0 +1,62 @@
+import fetch from 'isomorphic-fetch'
+
+import { loginFailure } from './user'
+
+export const FRIENDS_REQUEST = 'friends.request'
+export const FRIENDS_SUCCESS = 'friends.success'
+export const FRIENDS_FAILURE = 'friends.failure'
+
+export function friendsSuccess(friends) {
+  return {
+    type: FRIENDS_SUCCESS,
+    friends
+  }
+}
+function friendsRequest() {
+   return {
+      type: FRIENDS_REQUEST
+   }
+}
+function friendsFailure(error) {
+  return {
+    type: FRIENDS_FAILURE,
+    error
+  }
+}
+
+// Note: This is the same endpoint that we're using for authentication in user.js,
+// but pretend that its returning a list of friends.
+export function fetchFriends(endpoint = 'basic-auth/admin/secret') {
+  return (dispatch, getState) => {
+
+    dispatch(friendsRequest())
+
+    const hash = getState().user.hash
+    return fetch(`https://httpbin.org/${endpoint}`, {
+      headers: {
+        'Authorization': `Basic ${hash}`
+      }
+    })
+    .then(response => response.json().then(json => ({ json, response })))
+    .then(({json, response}) => {
+      if (response.ok === false) {
+        return Promise.reject(response, json)
+      }
+      return json
+    })
+    .then(
+      data => {
+        // data = { friends: [ {}, {}, ... ] }
+        dispatch(friendsSuccess(data.friends))
+      },
+      (response, data) => {
+        dispatch(friendsFailure(data.error))
+
+        // did our request fail because our auth credentials aren't working?
+        if (response.status == 401) {
+          dispatch(loginFailure(data.error))
+        }
+      }
+    )
+  }
+}

actions/user.js

@@ -0,0 +1,55 @@
+import fetch from 'isomorphic-fetch'
+
+export const LOGIN_REQUEST = 'login.request'
+export const LOGIN_SUCCESS = 'login.success'
+export const LOGIN_FAILURE = 'login.failure'
+
+export function loginSuccess(hash, user) {
+  return {
+    type: LOGIN_SUCCESS,
+    hash,
+    user
+  }
+}
+function loginRequest() {
+   return {
+      type: LOGIN_REQUEST
+   }
+}
+export function loginFailure(error) {
+  return {
+    type: LOGIN_FAILURE,
+    error
+  }
+}
+
+export function login(username, password) {
+  return (dispatch) => {
+
+    dispatch(loginRequest())
+
+    // Note: This only works in node.js, use an implementation that works
+    // for the platform you're using, e.g.: base64-js for React Native, or
+    // btoa() for browsers.
+    const hash = new Buffer(`${username}:${password}`).toString('base64')
+    return fetch('https://httpbin.org/basic-auth/admin/secret', {
+      headers: {
+        'Authorization': `Basic ${hash}`
+      }
+    })
+    .then(response => response.json().then(json => ({ json, response })))
+    .then(({json, response}) => {
+      if (response.ok === false) {
+        return Promise.reject(response, json)
+      }
+      return json
+    })
+    .then(
+      data => {
+        // data = { authenticated: true, user: 'admin' }
+        dispatch(loginSuccess(hash, data.user))
+      },
+      (response, data) => dispatch(loginFailure(data.error || 'Log in failed'))
+    )
+  }
+}

index.js

@@ -0,0 +1,30 @@
+import readlineSync from 'readline-sync'
+import { createStore, applyMiddleware, combineReducers } from 'redux'
+import thunk from 'redux-thunk'
+
+import { login } from './actions/user'
+import { fetchFriends } from './actions/friends'
+
+import userReducer from './reducers/user'
+import friendsReducer from './reducers/friends'
+const rootReducer = combineReducers({
+  user: userReducer,
+  friends: friendsReducer
+})
+const store = createStore(rootReducer, {}, applyMiddleware(thunk))
+
+
+
+store.subscribe(() => {
+
+  let state = store.getState()
+
+  console.log('---------- STORE STATE ----------')
+  console.log(JSON.stringify(state, null, 4))
+  console.log('---------------------------------')
+
+  readlineSync.keyInPause()
+})
+
+console.log('~~~ Step 1: The user enters a username and password, and taps login.')
+store.dispatch(login('admin', 'secret'))

package.json

@@ -0,0 +1,29 @@
+{
+  "name": "redux-http-basic-auth-example",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "start:watch": "nodemon index.js --exec babel-node --presets es2015"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/peterp/redux-http-basic-auth-example.git"
+  },
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/peterp/redux-http-basic-auth-example/issues"
+  },
+  "homepage": "https://github.com/peterp/redux-http-basic-auth-example#readme",
+  "dependencies": {
+    "isomorphic-fetch": "^2.2.1",
+    "readline-sync": "^1.4.1",
+    "redux": "^3.3.1",
+    "redux-thunk": "^1.0.3"
+  },
+  "devDependencies": {
+    "babel-cli": "^6.6.5",
+    "babel-preset-es2015": "^6.6.0"
+  }
+}

reducers/friends.js

@@ -0,0 +1,33 @@
+
+import {
+  FRIENDS_REQUEST,
+  FRIENDS_FAILURE,
+  FRIENDS_SUCCESS
+} from '../actions/friends'
+
+function user(state = {
+  isLoading: false,
+  friends: []
+}, action) {
+  switch(action.type) {
+    case FRIENDS_REQUEST:
+      return {
+        isLoading: true,
+        friends: []
+      }
+    case FRIENDS_FAILURE:
+      return {
+        isLoading: false,
+        error: action.error
+      }
+    case FRIENDS_SUCCESS:
+      return {
+        isLoading: false,
+        friends: action.friends
+      }
+    default:
+      return state
+  }
+}
+
+export default user

reducers/user.js

@@ -0,0 +1,40 @@
+
+// The request, failure, success pattern is very typical when performing
+// HTTP requests. The amount of boilerplate can be reduced using Redux
+// middleware, _or so I've read._
+
+import {
+  LOGIN_REQUEST,
+  LOGIN_FAILURE,
+  LOGIN_SUCCESS
+} from '../actions/user'
+
+function user(state = {
+  isLoggingIn: false,
+  isAuthenticated: false
+}, action) {
+  switch(action.type) {
+    case LOGIN_REQUEST:
+      return {
+        isLoggingIn: true,
+        isAuthenticated: false
+      }
+    case LOGIN_FAILURE:
+      return {
+        isLoggingIn: false,
+        isAuthenticated: false,
+        error: action.error
+      }
+    case LOGIN_SUCCESS:
+      return {
+        isLoggingIn: false,
+        isAuthenticated: true,
+        hash: action.hash,
+        user: action.user
+      }
+    default:
+      return state
+  }
+}
+
+export default user