DEV Community: Kelvin Mwinuka

EchoVault: Embeddable Redis Alternative in Go

Kelvin Mwinuka — Tue, 23 Jul 2024 15:31:47 +0000

I started working on an open-source project about a year ago to build an embeddable alternative to Redis in Go. That’s when I started building the EchoVault project. Since then, the project has gained some interest and even a few contributors.

This article introduces EchoVault, its features, use cases, and the motivations behind its development.

What is EchoVault?

EchoVault is an embeddable in-memory datastore tailored for Go applications. It provides a RESP-compatible interface over TCP while offering the flexibility to be embedded directly into applications.

By doing so, EchoVault aims to replace traditional in-memory data stores like Redis in some use cases, offering similar functionalities with enhanced integration for Go.

Why EchoVault was Built

My initial motivations for building EchoVault were:

Embedded Flexibility: Traditional in-memory data stores like Redis are external services that require separate management and deployment. EchoVault eliminates this overhead by allowing developers to embed the data store directly into their applications, streamlining the deployment process.
Go Ecosystem Integration: EchoVault is designed primarily for Go, ensuring seamless integration and optimal performance within Go applications. However, it also maintains RESP compatibility over TCP, making it compatible with existing Redis clients such as redis-cli and Jedis.
Redis License Changes: EchoVault is open-source (licensed under Apache 2.0). We’re committed to staying on this fully open-source model and not open-core.

Features Provided by EchoVault

EchoVault is packed with features that make it a robust choice for in-memory data storage:

TLS and mTLS Support: Secure communication with support for multiple server and client Root Certificate Authorities (RootCAs). Replication Cluster Support: Utilizes the RAFT algorithm for replication and clustering.
Access Control Layer: Provides user authentication and authorization to secure data access.
Distributed Pub/Sub Functionality: Supports publish/subscribe to channels and patterns for real-time data processing.
Data Structures: We support a variety of data structures, including sets, sorted sets, hashes, lists, and more. We are continuing to add more data structures and commands within them.
Persistence Layer: This layer ensures data durability with snapshot and append-only file persistence. The AOF files are RESP compatible but not yet fully Redis compatible.
Key Eviction Policies: Implements various strategies for key eviction to manage memory usage. EchoVault has passive and active key eviction. With passive key eviction, expired keys are not evicted until the next time they are accessed. With active eviction, EchoVault will proactively delete keys that are expired.
Command Extensions: Allows runtime extension of commands via shared object files and an embedded API.

The feature list continues to expand as we’re in the early stages of development. We have some more cool features lined up for the future, including:

Streams.
Extensions with Lua modules.
Sharding.

Architecture of EchoVault

EchoVault supports both standalone and clustered deployments.

Standalone Mode

In standalone mode, EchoVault operates a single (standalone) instance. This is the easiest way to run EchoVault. You can run a standalone instance from the embedded library or start it as its own process that accepts TCP connections.
The embedded instance can also accept TCP connections, allowing you to communicate with your Go process from a TCP client.

RAFT Replication Cluster Mode

For applications requiring strong consistency and fault tolerance, EchoVault supports a RAFT-based replication cluster mode.

RAFT is a consensus algorithm that ensures data consistency across distributed systems. In this mode, multiple EchoVault instances can form a cluster, providing data replication and ensuring that data remains consistent even in the event of node failures.

Key Features of RAFT Cluster Mode:

Fault Tolerance: Ensures data availability even if some nodes in the cluster fail.
Consistency: Guarantees that all nodes in the cluster have the same data.
Scalability: Allows for horizontal scaling by adding more nodes to the cluster.

You can run EchoVault clusters even in embedded modes. This means that your application instances can communicate with each other through the EchoVault layer without having to deploy a third service. This is ideal for use cases such as session management across a cluster of an application’s instances.

Use Cases for EchoVault

EchoVault's versatility makes it suitable for a wide range of applications. Here are some potential use cases:

In-Memory Caching Scenario: An e-commerce website needs to cache product details and user session information to improve performance. Solution: Use EchoVault to cache frequently accessed data to speed up response times. Benefits: Faster page loads, improved user experience, and reduced database strain.
Service Discovery Scenario: A microservices architecture requires dynamic service discovery for inter-service communication. Solution: Store service endpoints in EchoVault, allowing services to discover and communicate with each other efficiently. Benefits: Simplified service discovery and enhanced communication efficiency.
Session Management Scenario: A distributed web application must manage user sessions across multiple instances. Solution: Use EchoVault embedded cluster to store session data, ensuring consistency and accessibility across all application instances. Benefits: Consistent session management across the application’s cluster without deploying a secondary service like Redis.
Real-Time Analytics Scenario: A financial trading platform requires real-time analytics and monitoring of trade data. Solution: Store and process real-time trade data in EchoVault, leveraging its sorted sets and pub/sub capabilities for tracking and analysis. Benefits: Real-time data processing and faster analytics.
Distributed Task Queue Scenario: A backend system needs to manage and distribute tasks to multiple worker nodes. Solution: Implement a task queue using EchoVault's list data structure, where tasks are pushed onto the list and worker nodes pop tasks for processing. Benefits: Efficient task distribution and scalability.
Feature Flags and Configuration Management Scenario: A SaaS application needs to dynamically enable or disable features and manage configuration settings without redeploying the application. Solution: Store feature flags and configuration settings in EchoVault. Benefits: Dynamic configuration management and reduced downtime.
Rate Limiting and Throttling Scenario: An API gateway needs to enforce rate limits and throttle requests to prevent abuse and ensure fair usage. Solution: Implement rate limiting using EchoVault's in-memory capabilities to track request counts and enforce limits in real-time. Benefits: Effective rate limiting and improved API reliability.
Leader Election Scenario: A cluster of distributed services needs to elect a leader to coordinate tasks. Solution: Rely on EchoVault's embedded distributed cluster’s leader election to ensure that only one application instance is designated as the leader. Benefits: Reliable leader election and improved coordination without implementing it yourself at the application level.

Conclusion

EchoVault is an ambitious project. In these early stages, we expect many kinks to have to be ironed out and many features to be added. However, we welcome this challenge and would love to get the Go community involved in the project.

If this article has triggered your curiosity, or you’re interested in contributing to a project like this, check out our GitHub and drop us a star! We’re always open to more feedback and contributions!

Social Login With Cognito and NextAuth

Kelvin Mwinuka — Fri, 24 Feb 2023 20:23:16 +0000

AWS Cognito user pools allow you to manage your app's within the AWS ecosystem. It provides all the basic features you'd expect from an auth system.

When I'm building an application on AWS infrastructure, I prefer using Cognito user pools due to its seamless integration with other AWS services such as API Gateway authorization.

Cognito user pools also allow you to set up social login for your users. This is very convenient in a world where most people have become accustomed to authentication via existing accounts such as Google, Facebook, Apple, etc.

In this article, I will be covering how to integrate social login in your Next.js applications through Cognito. We will essentially allow our users to log in using their social accounts while using Cognito as a proxy auth server.

We will do this while bypassing the Cognito-hosted UI for a seamless auth experience for the user.

There are a few benefits to using this approach instead of manually handling social logins ourselves:

We can leverage Cognito user pools and all its rich features.
In our Next.js application, we only have to deal with 1 auth provider, Cognito.
We have the freedom to design our social sign-in buttons as we please, without being shackled by Cognito's hosted UI.
We do not have to manage a database of users ourselves.

Prerequisites

This article will not go over the process of setting up your Cognito user pool. Before you implement the steps in this article, make sure you have:

A Cognito user pool.
An app client set up for your user pool.
Social login setup for your app client. You don't need to set up all the social providers, just one of them is enough. You can always plug more providers in later.
A domain for your user pool. It does not need to be a custom domain. The default domain provided by aws is sufficient.

Our auth structure should roughly look like this:

Setting up NextAuth

In the Next.js application, first, install the NextAuth library.

npm install next-auth

Next, set up the NextAuth configurations in /api/auth/[...nextauth].ts.

import { TokenSet } from "next-auth";
import NextAuth from "next-auth/next";
import { Provider } from "next-auth/providers";

const { 
  NEXTAUTH_URL,
  COGNITO_REGION,
  COGNITO_DOMAIN,
  COGNITO_CLIENT_ID,
  COGNITO_USER_POOL_ID,
  COGNITO_CLIENT_SECRET,
} = process.env;

type TProvider = "Amazon" | "Apple" | "Facebook" | "Google";

function getProvider(provider: TProvider): Provider {
   /*
      Provider generation function to avoid repeating ourselved when
      declaring providers in the authOptions below.
   */
  return {
    // e.g. cognito_google | cognito_facebook
    id: `cognito_${provider.toLowerCase()}`,  

    // e.g. CognitoGoogle | CognitoFacebook
    name: `Cognito${provider}`,

    type: "oauth",

    // The id of the app client configured in the user pool.
    clientId: COGNITO_CLIENT_ID,

    // The app client secret.
    clientSecret: COGNITO_CLIENT_SECRET,

    wellKnown: `https://cognito-idp.${COGNITO_REGION}.amazonaws.com/${COGNITO_USER_POOL_ID}/.well-known/openid-configuration`,

    // Authorization endpoint configuration
    authorization: {
      url: `${COGNITO_DOMAIN}/oauth2/authorize`,
      params: {
        response_type: "code",
        client_id: COGNITO_CLIENT_ID,
        identity_provider: provider,
        redirect_uri: `${NEXTAUTH_URL}/api/auth/callback/cognito_${provider.toLowerCase()}`
      }
    },

    // Token endpoint configuration
    token: {
      url: `${COGNITO_DOMAIN}/oauth2/token`,
      params: {
        grant_type: "authorization_code",
        client_id: COGNITO_CLIENT_ID,
        client_secret: COGNITO_CLIENT_SECRET,
        redirect_uri: `${NEXTAUTH_URL}/api/auth/callback/cognito_${provider.toLowerCase()}`
      }
    },

    // userInfo endpoint configuration
    userinfo: {
      url: `${COGNITO_DOMAIN}/oauth2/userInfo`,
    },

    // Profile to return after successcul auth.
    // You can do some transformation on your profile object here.
    profile: function(profile) {
      return {
        id: profile.sub,
        ...profile
      }
    }
  }
}

export const authOptions = {

  /*
    Generate the providers for each of our social login.
    Adding a new OIDC provider is a simple as adding the name of the         provider as displayed in the Cognito user pool to the TProvider type
and to this array.
  */
  providers: [
    ...["Amazon", "Apple", "Facebook", "Google"].map((provider: TProvider) => getProvider(provider)),
  ],

  callbacks: {
    async signIn({ user, account, profile }) {
      // Return true to allow sign in and false to block sign in.
      return true;
    },
    async redirect({ url, baseUrl }){
      // Return the url to redirect to after successful sign in.
      return baseUrl;
    },
    async jwt({ token, account, profile, user }){
      // Retrieve jwt tokens
      if (account) {
        // account is provided upon the inital auth
        return {
          ...token,
          accessToken: account.access_token,
          idToken: account.id_token,
        }
      }
    },
    async session({ session, token }) {
      /* 
         Forward tokens to client in case you need to make authorized
         API calls to an AWS service directly from the front end.
      */
      session.accessToken = token.accessToken;
      session.idToken = token.idToken;
      return session;
    }
  }
};

export default NextAuth(authOptions);

As you can see, we're configuring a basic OAuth2.0 flow. You can read more about Cognito's OIDC endpoints here. This flow will work with any OIDC provider that you configure in your user pool.

Callback enhancement

Right now there's a scenario we're not handling. When authenticating in this way, Cognito will return a long-lasting refresh token. A refresh token is used to request new access and id tokens when said tokens have expired.

This allows us to keep the user logged in for a long time without forcing them to sign in every time their tokens expire. We will only prompt the user to sign in again once the refresh token itself has expired or has been invalidated in some other way.

To support this functionality, we need to update the code in the jwt and session callback functions.

First, let's update the jwt callback function:

async jwt({ token, account, profile, user }){
  if (account) {
    // This is an initial login, set JWT tokens.
    return {
      ...token,
      accessToken: account.access_token,
      idToken: account.id_token,
      refreshToken: account.refresh_token,
      expiresAt: account.expires_at,
      tokenType: 'Bearer'
    }
  }
  if (Date.now() < token.expiresAt) {
    // Access/Id token are still valid, return them as is.
    return token;
  }
  // Access/Id tokens have expired, retrieve new tokens using the 
  // refresh token
  try {
    const response = await fetch(`${COGNITO_DOMAIN}/oauth2/token`, {
      headers: { 
        "Content-Type": "application/x-www-form-urlencoded"
      },
      body: new URLSearchParams({
        client_id: COGNITO_CLIENT_ID,
        client_secret: COGNITO_CLIENT_SECRET,
        grant_type: "refresh_token",
        refresh_token: token.refreshToken
      }),
      method: "POST"
    })

    const tokens: TokenSet = await response.json();

    if (!response.ok) throw tokens;

    return {
      ...token,
      accessToken: tokens.access_token,
      idToken: tokens.id_token,
      expiresAt: Date.now() + (Number(tokens.expires_in) * 1000)
    }
  } catch (error) {
    // Could not refresh tokens, return error
    console.error("Error refreshing access and id tokens: ", error);
    return { ...token, error: "RefreshTokensError" as const }
  }
}

Here's what this function is doing before returning the jwt tokens when a token request is made:

If it's the first request (i.e initial sign-in action), add accessToken, idToken, refreshToken, and expiresAt to the token object. The expiresAt attribute lets us know when the access and id token will expire. The object returned here will be represented by the token param in all subsequent token requests.
If this is not the first request, check if the access and id tokens have expired by comparing the current time to the expiresAt time in the token object that was set in point 1.
If the tokens have not expired, return the same token object.
If the tokens have expired, fetch new tokens using the refresh token.
If the fetch fails, throw the error. In the catch block, return the current token object but append an error property so we can check for it and redirect the user to the sign-in page.
If the fetch is successful, replace the accessToken, idToken and expiresAt properties in the token object and return the new token object.

Next, we need to update the session callback. This callback allows us to set session properties that will be accessible in the front end via the useSession hook.

All we need to do here is add the error property of the token to the session object. That way we can detect the error in the front end and redirect the user to the sign-in page.

async session({ session, token }) {
  /* 
    Forward tokens to client in case you need to make authorized API      
    calls to an AWS service directly from the front end.
  */
  session.accessToken = token.accessToken;
  session.idToken = token.idToken;
  /* 
    If there is an error when refreshing tokens, include it so it can 
    be forwarded to the front end.
  */
  session.error = token.error;
  return session;
}

Configuring shared session state

To configure the sessions state, update the _app.tsx or _app.jsx file with the following code:

import '../styles/globals.css';
import { SessionProvider } from "next-auth/react";

function MyApp({ 
  Component,
  pageProps: { session, ...pageProps }
}) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  )
}

export default MyApp

This change allows us to use the session throughout the application.

Frontend login with providers

In order to allow the user to sign in with their preferred provider, we have to configure the sign-in buttons for each provider in our SignIn page component.

import { useEffect, useState } from "react";

/* The getProviders function returns a promise that resolves
   to an object containing all of the configured providers. */
// The signIn functions initiates the signIn process.
import { getProviders, signIn } from "next-auth/react";

export default function SignIn() {
  const [providers, setProviders] = useState(null);

  // Fetch providers on mount.
  useEffect(() => {
    getProviders().then((providers) => setProviders(providers));
  }, []);

  return (
    <div>
      {providers && (
        <>
          <div>
            <button onClick={
              () => signIn(providers["cognito_amazon"].id)
            }>
              Login with Amazon
            </button>
          </div>
          <div>
            <button onClick={
              () => signIn(providers["cognito_apple"].id)
            }>
              Login with Apple
            </button>
          </div>
          <div>
            <button onClick={
              () => signIn(providers["cognito_facebook"].id)
            }>
              Login with Facebook
            </button>
          </div>
          <div>
            <button onClick={
              () => signIn(providers["cognito_google"].id)
            }>
              Login with Google
            </button>
          </div>
        </>
      )}
    </div>
  );
}

For more context, the provider object will take the following shape:

{
  <prodiver_id>: {
    "id": <provider_id>
    "name": <provider_name>
    "type": <provider_type>
    "signinUrl": <provider signin url>
    "callbackUrl": <provider callback url>
  }
}

In this configuration, the provider object will look like this:

{
  "cognito_amazon":
  {
    "id":"cognito_amazon",
    "name":"CognitoAmazon",
    "type":"oauth",
    "signinUrl":
      "http://localhost:3000/api/auth/signin/cognito_amazon",
    "callbackUrl":
      "http://localhost:3000/api/auth/callback/cognito_amazon"
  },
  "cognito_apple":{
    "id": "cognito_apple",
    "name":"CognitoApple",
    "type":"oauth",
    "signinUrl":"http://localhost:3000/api/auth/signin/cognito_apple",
    "callbackUrl":
      "http://localhost:3000/api/auth/callback/cognito_apple"
  },
  "cognito_facebook":{
    "id": "cognito_facebook",
    "name":"CognitoFacebook",
    "type":"oauth",
    "signinUrl":
      "http://localhost:3000/api/auth/signin/cognito_facebook",
    "callbackUrl":
      "http://localhost:3000/api/auth/callback/cognito_facebook"
  },
  "cognito_google":{
    "id":"cognito_google",
    "name":"CognitoGoogle",
    "type":"oauth",
    "signinUrl":
      "http://localhost:3000/api/auth/signin/cognito_google",
    "callbackUrl":
      "http://localhost:3000/api/auth/callback/cognito_google"
  }
}

Frontend useSession hook

In order to access the session data in the front end, we can make use of the useSession hook from next-auth/react.

This hook allows us to access the session data and the user's auth status.

First import the hook.

import { useSession } from 'next-auth/react'

Then inside your component, use it as follows:

const { data, status } = useSession();

The data property will contain all the data that we set in the session callback that we configured [...nextauth.ts] . It will also contain an additional user property with information about the current user such as email address.

The status property is a string containing information about the user's auth status. Its possible values are "loading", "authenticated" or "unauthenticated". You can use this to implement protected routes or redirect to the sign-in page when a session is expired.

Web Sockets with API Gateway and AWS Lambda

Kelvin Mwinuka — Sat, 19 Nov 2022 11:25:29 +0000

AWS offers an easy way to work with web sockets through the WebSockets API in API Gateway. This article is going to be a short walkthrough on how to get started with WebSocket APIs.

Setup

This is article is based on a serverless framework project. You can still implement the concepts discussed here without serverless framework.

You can find the code used in this article in this GitHub repository.

Serverless provider config

The serverless provider configuration will look exactly the same as a regular API project with the exception of one additional property: websocketsApiRouteSelectionExpression.

This property tells API gateway which request body property to use in order to determine where to route the request. In this instance, the action property of the payload will determine which handler gets called.

We'll see this in action when we define the handlers.

provider:
  name: aws
  runtime: nodejs14.x
  profile: ${env:PROFILE, "localstack"}
  stage: ${opt:stage, "local"}
  region: ${opt:region, "us-east-1"}
  websocketsApiRouteSelectionExpression: $request.body.action

Connection table

For our use case, we'll need to maintain a record of active connections in order to send targeted messages.

I've chosen DynamoDB for this demonstration but you might get better mileage using a relational database like PostgreSQL. The concept will be the same, but with a slightly different implementation.

A table row will contain Username and ConnectionId fields for each active connection.

We must create a DynamoDB table resource in the serverless.yaml file. The table will use the Username as the primary key so make sure it's unique.

Since we'll need to query the table by ConnectionId at some point, let's create a global secondary index that uses ConnectionId as the primary key.

You can read more about global secondary indexes here.

resources:  
  Resources:
    ConnectionsTable:
      Type: AWS::DynamoDB::Table
      Properties:
        AttributeDefinitions:
          - AttributeName: Username
            AttributeType: S
          - AttributeName: ConnectionId
            AttributeType: S
        KeySchema:
          - AttributeName: Username
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 1
          WriteCapacityUnits: 1
        GlobalSecondaryIndexes:
          - IndexName: ConnectionIdIndex
            KeySchema:
              - AttributeName: ConnectionId
                KeyType: HASH
            Projection:
              ProjectionType: ALL
            ProvisionedThroughput:
                ReadCapacityUnits: 1
                WriteCapacityUnits: 1

Connecting

Now let's create the connection handler. This lambda will be called when a client tries to establish a connection.

The main aim of this handler is to save the connection details in the DynamoDB table so this connection can be targeted when sending a message.

First, let's define the function in serverless.yaml in the function section:

wsConnectHandler:
    handler: ./src/connect.handler
    events:
      - websocket:
          route: $connect
    iamRoleStatements:
      - Effect: "Allow"
        Action: "dynamodb:PutItem"
        Resource: !GetAtt [ConnectionsTable, Arn]

This lambda is triggered by the pre-defined $connect websocket route. We also give this function permission to put an item into the DynamoDB table we defined earlier.

The handler logic looks as follows:

import {
  DynamoDBClient,
  PutItemCommand
} from "@aws-sdk/client-dynamodb";

const {
  STAGE,
  REGION,
  CONNECTION_TABLE,
  LOCALSTACK_ENDPOINT
} = process.env;

const getDynamoDbConfig = (): { region: string, endpoint?: string } => {
  if (STAGE === "local") return { region: REGION, endpoint: LOCALSTACK_ENDPOINT };
  return { region: REGION };
}

module.exports.handler = async (event) => {
  const dynamoDBClient = new DynamoDBClient(getDynamoDbConfig());

  const putItemCommand = new PutItemCommand({
    TableName: CONNECTION_TABLE,
    Item: {
      Username: { S: event.queryStringParameters.username },
      ConnectionId: { S: event.requestContext.connectionId }
    }
  });
  await dynamoDBClient.send(putItemCommand);

  return { statusCode: 200 };
}

When the connection route is triggered, we create a record in the connection table that contains the username and connection id.

We retrieve the username from the queryStringParameters of the request. To establish a connection, the client will have to send a connection request to wss://<api-id>.execute-api.<region>.amazonaws.com/<stage>/?username=<username>.

If the username isn't provided, an error is thrown and a connection isn't established. We must return a 200 status code for a successful connection.

You can implement custom error handling here if you'd like but AWS will usually display the error in the cloudwatch logs when encountered.

Disconnecting

Now let's handle disconnection. The disconnection handler is triggered whenever a connection is ended. We can use this to do some cleanup. In our case, the cleanup involves deleting the connection row in our DynamoDB table.

First, let's define the function in serverless.yaml

wsDisconnectHandler:
    handler: ./src/disconnect.handler
    events:
      - websocket:
          route: $disconnect
    iamRoleStatements:
      - Effect: "Allow"
        Action: 
          - "dynamodb:DeleteItem"
          - "dynamodb:Query"
        Resource: 
          - !GetAtt [ConnectionsTable, Arn]
          - !Join ["/", [!GetAtt [ConnectionsTable, Arn], "index", "ConnectionIdIndex"]]

Once again, this is triggered by the disconnect event through the pre-defined $disconnect route.

We need to give this function permission to delete from the connection table and query the global secondary index we created earlier.

Here's the handler implementation:

import {
  DynamoDBClient,
  DeleteItemCommand,
  QueryCommand,
} from "@aws-sdk/client-dynamodb";

const {
  STAGE,
  REGION,
  CONNECTION_TABLE,
  LOCALSTACK_ENDPOINT
} = process.env;

const getDynamoDbConfig = (): { region: string, endpoint?: string } => {
  if (STAGE === "local") return { region: REGION, endpoint: LOCALSTACK_ENDPOINT };
  return { region: REGION };
}

module.exports.handler = async (event, context, callback) => {
  console.log(event);

  const dynamoDBClient = new DynamoDBClient(getDynamoDbConfig());

  // Retrieve the connection using the connectionId
  const queryCommand = new QueryCommand({
    TableName: CONNECTION_TABLE,
    IndexName: "ConnectionIdIndex",
    KeyConditionExpression: "ConnectionId = :a",
    ExpressionAttributeValues: {
      ":a": { S: event.requestContext.connectionId }
    }
  })

  const queryResult = await dynamoDBClient.send(queryCommand);
  const connectionRecord = queryResult?.Items ? queryResult.Items[0] : undefined;

  const deleteItemCommand = new DeleteItemCommand({
    TableName: CONNECTION_TABLE,
    Key: {
      Username: { S : connectionRecord?.Username?.S ? connectionRecord?.Username?.S : "" }
    }
  });
  await dynamoDBClient.send(deleteItemCommand);

  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Connection ended!" })
  };
}

We retrieve the connection id from the request context in the event object and query the index to find the connection record with this connection id.

Once we've retrieved the record, we delete it from the connection table using the username as the key.

Send a message

Now that we've handled connecting and disconnecting, it's time to handle sending messages directly to another connected user.

This handler will work by receiving a payload that contains the recipient's username, finding the recipient's connection record, extracting the connection id, and sending the payload message to the target connection.

First, let's define the function in serverless.yaml:

wsSendMessage:
    handler: ./src/sendMessage.handler
    events:
      - websocket:
          route: "sendMessage"
    iamRoleStatements:
      - Effect: "Allow"
        Action: "dynamodb:Query"
        Resource:
          - !GetAtt [ConnectionsTable, Arn]
          - !Join ["/", [!GetAtt [ConnectionsTable, Arn], "index", "ConnectionIdIndex"]]
      - Effect: "Allow"
        Action: "execute-api:ManageConnections"
        Resource:
          - Fn::Join:
            - "/"
            -
              - Fn::Join:
                - ":"
                -
                  - "arn:aws:execute-api"
                  - ${opt:region, "us-east-1"}
                  - !Ref AWS::AccountId
                  - !Ref WebsocketsApi
              - ${opt:stage, 'dev'}
              - "POST"
              - "@connections"
              - "{connectionId}"

Notice we have a slightly different event. The route is set as sendMessage. This is a custom route defined by us.

If you recall, the provider section has this property defined: websocketsApiRouteSelectionExpression: $request.body.action. This tells API Gateway to look for the route in the action property of the request body.

So in order to trigger the wsSendMessage lambda, the message we send once connected needs to be an object that contains the action property with the value of "sendMessage" like so:

{
  "action": "sendMessage",
  ...
}

Next, we need to give this lambda permission to query both the connection table and the global secondary index. We also must give it permission to send a message to an existing web socket connection.

This is the handler implementation:

import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";

import {
  ApiGatewayManagementApiClient,
  PostToConnectionCommand
} from "@aws-sdk/client-apigatewaymanagementapi";

const {
  STAGE,
  REGION,
  CONNECTION_TABLE,
  LOCALSTACK_ENDPOINT,
  PORT
} = process.env;

const getDynamoDbConfig = (): { region: string, endpoint?: string } => {
  if (STAGE === "local") return { region: REGION, endpoint: LOCALSTACK_ENDPOINT };
  return { region: REGION };
}

const getConnectionEndpoint = (event) => {
  return STAGE === "local" ? 
  `http://${event.requestContext.domainName}:${PORT}` :
  `https://${event.requestContext.domainName}/${event.requestContext.stage}/`
}

module.exports.handler = async (event, context, callback) => {
  console.log(event);

  const body = JSON.parse(event.body);

  const dynamoDBClient = new DynamoDBClient(getDynamoDbConfig());

  /**
   * Query the connection table for the TARGET connection record.
   * The recepient's username used in the query will be included in the event body.
   */
  let queryResult = await dynamoDBClient.send(new QueryCommand({
    TableName: CONNECTION_TABLE,
    KeyConditionExpression: "Username = :a",
    ExpressionAttributeValues: {
      ":a": { S: body.recepient}
    }
  }));

  // Return early if the recepient is not found in the connections table.
  if (!(queryResult?.Items?.length && queryResult?.Items?.length > 0)) return callback(JSON.stringify({
    message: "Recepient not found",
    body
  }));

  const recepientConnection =  queryResult.Items[0];

  /**
   * Query ConnectionIdIndex using the connection id of the sender.
   * The senders connection id can be found in event.requestContext.connectionId.
   * We retrieve this connection record in order to retrieve the sender's username.
   */
  queryResult = await dynamoDBClient.send(new QueryCommand({
    TableName: CONNECTION_TABLE,
    IndexName: "ConnectionIdIndex",
    KeyConditionExpression: "ConnectionId = :b",
    ExpressionAttributeValues: {
      ":b": { S: event.requestContext.connectionId }
    },
  }));

  // Return early if no actively connected sender is found.
  if (!(queryResult?.Items?.length && queryResult?.Items?.length > 0)) return callback(JSON.stringify({
    message: "Sender not found",
    context: event.requestContext
  }));

  const senderConnection = queryResult?.Items ? queryResult.Items[0]: undefined;

  const apiGatewayManagementApiClient = new ApiGatewayManagementApiClient({ 
    region: REGION,
    endpoint: getConnectionEndpoint(event)
  });

  // Post a message to the recipient's connection.
  const postToConnectionCommand = new PostToConnectionCommand({
    ConnectionId: recepientConnection?.ConnectionId.S,
    Data: Buffer.from(JSON.stringify({
      from: senderConnection?.Username.S,
      message: body.message
    }), "utf-8")
  });

try {
    await apiGatewayManagementApiClient.send(postToConnectionCommand);
  } catch (error) {
    console.log(error);
  }

  return { 
    statusCode: 200,
    body: JSON.stringify({ message: "Message sent." })
  };
}

In order to test this, send a message to the connection with the following signature:

{
  "action": "sendMessage",
  "recepient": <username>,
  "message": <string>
}

Make sure the recipient is connected as well.

For more in-depth reading on WebSocket APIs, visit the official AWS docs here.

Google Login on AWS Cognito Without Hosted UI (Work-around)

Kelvin Mwinuka — Sat, 23 Apr 2022 17:50:54 +0000

I've previously written an article about basic username/password authentication with AWS Cognito. This article will cover registration and authentication using Google.

Cognito offers this functionality built into the hosted-ui. However, if you find the hosted UI to be limited in terms of design or functionality, you might want to implement this authentication method using the AWS SDK in your own custom UI.

Unfortunately, there is no straightforward way of doing this, so this is a possible workaround to that particular limitation.

If you haven't read the other articles in this series, I'm using a react frontend with a nodejs backend for this tutorial. My framework of choice is NextJS. You don't have to use this exact framework. As long as you use a JS frontend and a NodeJS backend, you should be able to adapt this tutorial to your own stack.

Setup

First, we need to install a couple of packages to help us out in our implementation. The 2 packages we need are react-google-login to facilitate Google login in the frontend, and google-auth-library for verifying Google tokens in the backend.

Install the packages with the following command in the terminal: npm install react-google-login google-auth-library.

Registration

On the registration page, import GoogleLogin from react-google-login and add the button to the layout.

You can find more information about this package and how to customise the button here.

<GoogleLogin
    clientId={process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID}
    responseType={'id_token'}
    buttonText="Register with Google"
    onSuccess={googleRegisterSuccess}
    onFailure={googleRegisterFailure}
/>

We pass the googleRegisterSuccess function to the onSuccess prop. We have a useRegister hook that contains the googleRegisterSuccess function.

Now, define the googleRegisterSuccess function in the useRegister hook as follows:

const googleRegisterSuccess = (googleResponse) => {
        fetch('/api/register/google', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ id_token: googleResponse?.tokenId })
        }).then(res => {
            if (!res.ok) throw res
            router.push({
                pathname: '/login'
            })
        }).catch(err => {
            console.error(err)
        })
    }

const googleRegisterFailure = (googleResponse) => {
    console.error(googleResponse)
}

All we're interested in from the response object is the tokenId, which we send to the backend for verification.

In the handler for the Google register route, we have the following code:

import { CognitoIdentityProviderClient, SignUpCommand } from '@aws-sdk/client-cognito-identity-provider'
import { OAuth2Client } from 'google-auth-library'

const {
  COGNITO_REGION,
  COGNITO_APP_CLIENT_ID,
  GOOGLE_TOKEN_ISSUER,
  NEXT_PUBLIC_GOOGLE_CLIENT_ID,
} = process.env

export default async function handler(req, res) {
  if (req.method !== 'POST') return res.status(405).send()

  let googlePayload

  try {
    // Verify the id token from google
    const oauthClient = new OAuth2Client(NEXT_PUBLIC_GOOGLE_CLIENT_ID)
    const ticket = await oauthClient.verifyIdToken({
      idToken: req.body.id_token,
      audience: NEXT_PUBLIC_GOOGLE_CLIENT_ID
    })
    googlePayload = ticket.getPayload()
    if (
      !googlePayload?.iss === GOOGLE_TOKEN_ISSUER ||
      !googlePayload?.aud === NEXT_PUBLIC_GOOGLE_CLIENT_ID
    ) {
      throw new Error("Token issuer or audience invalid.")
    }
  } catch (err) {
    return res.status(422).json({ message: err.toString() })
  }

  // Register the user
  try {
    const params = {
      ClientId: COGNITO_APP_CLIENT_ID,
      Username: googlePayload.email.split("@")[0], // Username extracted from email address
      Password: googlePayload.sub,
      UserAttributes: [
        {
          Name: 'email',
          Value: googlePayload.email
        },
        {
          Name: 'custom:RegistrationMethod',
          Value: 'google'
        }
      ],
      ClientMetadata: {
        'EmailVerified': googlePayload.email_verified.toString()
      }
    }
    const cognitoClient = new CognitoIdentityProviderClient({
      region: COGNITO_REGION
    })
    const signUpCommand = new SignUpCommand(params)
    const response = await cognitoClient.send(signUpCommand)
    return res.status(response['$metadata'].httpStatusCode).send()
  } catch (err) {
    console.log(err)
    return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
  }
}

Let's go through what's happening here:

We need to verify the idToken by using the google-auth-library package. After verifying the token, we get a "payload" that contains some useful information about the user and about the token.
We need to check that the token issuer is accounts.google.com or https://accounts.google.com and that the audience matches our Google client id.
Next, we register the user with the SignUpCommand. We use a substring of the email as the username and the sub as the password. You'll want to be careful, you may need to find a more creative way to set the password.

Just make sure you can reproduce the string that you pass here otherwise the user will not be able to sign in later. Here, I've used sub because it does not change. You can hash this, add a prefix/suffix, or both if you want to go the extra mile.

In ClientMetadata, we specify the verification status for this email address. We will be using this in the pre-signup trigger later on.

Optionally, you can set a custom attribute custom:RegistrationMethod in case you have several registration methods for your user pool.

PreSignup Trigger

In a previous article on cognito pre-signup triggers, we added some custom logic upon signup that checks if the provided email address is already in use. Feel free to check that article out for more details on that.

We are going to add some logic to that pre-signup trigger to cater to users who register using Google.

module.exports.handler = async (event, context, callback) => {
  // Check if the provided email address is already in use

  // Verify user's email address if it's already verified with Google.
  if (event.request.userAttributes['custom:RegistrationMethod'] === "google") {
    let userEmailVerified = event.request.clientMetadata['EmailVerified'] === 'true'
    event.response.autoVerifyEmail = userEmailVerified
    event.response.autoConfirmUser = userEmailVerified
  }

  callback(null, event);
};

If the user's email address is already verified by Google, we don't need to verify it ourselves. So we set autoVerifyEmail to whatever value we set in the EmailVerified attribute of the ClientMetadata.

When you set autoVerifyEmail to true, you also have to do the same for autoConfirmUser as you cannot verify an email address without confirming the user in cognito.

You can find the code for the cognito triggers I use in this series in this Github repo.

Sign in

Now, that we've handled registration, let's handle signing in. On your login page, add the GoogleLogin button just like we did in the registration page.

<GoogleLogin 
    clientId={process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID}
    buttonText="Login with Google"
    responseType={'id_token'}
    onSuccess={googleSignInSuccess}
    onFailure={googleSignInFailure}
/>

The useAuth hook contains a googleSignInSuccess function that sends the tokenId from Google to the Google login API endpoint on the backend.

const googleSignInSuccess = (googleResponse) => {
    fetch('/api/login/google', {
      method: 'POST',
      headers: { 
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ id_token: googleResponse?.tokenId })
    }).then(res => {
      if (!res.ok) throw res
      return res.json()
    }).then(data => {
      console.log(data)
    }).catch(err => {
      console.error(err)
    })
  }

  const googleSignInFailure = (googleResponse) => {
    console.error(googleResponse)
  }

In the backend, we handle the login as follows:

import { CognitoIdentityProviderClient, AdminInitiateAuthCommand } from "@aws-sdk/client-cognito-identity-provider";
import { OAuth2Client } from "google-auth-library";

const {
  COGNITO_REGION,
  COGNITO_APP_CLIENT_ID,
  COGNITO_USER_POOL_ID,
  GOOGLE_TOKEN_ISSUER,
  NEXT_PUBLIC_GOOGLE_CLIENT_ID
} = process.env

export default async function handler(req, res){
  if (!req.method === 'POST') return res.status(405).send()

  let googlePayload

  try {
    const oauthClient = new OAuth2Client(NEXT_PUBLIC_GOOGLE_CLIENT_ID)
    const ticket = await oauthClient.verifyIdToken({
      idToken: req.body.id_token,
      audience: NEXT_PUBLIC_GOOGLE_CLIENT_ID
    })
    googlePayload = ticket.getPayload()
    if (
      !googlePayload?.iss === GOOGLE_TOKEN_ISSUER ||
      !googlePayload?.aud === NEXT_PUBLIC_GOOGLE_CLIENT_ID
    ) {
      throw new Error("Token issuer or audience invalid.")
    }
  } catch (err) {
    return res.status(422).json({ message: err.toString() })
  }

  // Sign the user in
  try {
    const params = {
      AuthFlow: 'ADMIN_USER_PASSWORD_AUTH',
      ClientId: COGNITO_APP_CLIENT_ID,
      UserPoolId: COGNITO_USER_POOL_ID,
      AuthParameters: {
        USERNAME: googlePayload?.email,
        PASSWORD: googlePayload?.sub
      }
    }
    const cognitoClient = new CognitoIdentityProviderClient({
      region: COGNITO_REGION
    })
    const adminInitiateAuthCommand = new AdminInitiateAuthCommand(params)
    const response = await cognitoClient.send(adminInitiateAuthCommand)
    return res.status(response['$metadata'].httpStatusCode).json({
      ...response.AuthenticationResult
    })
  } catch (err) {
    console.log(err)
    return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
  }
}

The first part of the handler is quite similar to the registration: we verify the token and grab the user's profile details along with more information about the token.

We check the token's issuer and audience to make sure they are correct, and then we proceed to the sign in.

For signing in, we use AdminInitiateAuthCommand along with the ADMIN_USER_PASSWORD_AUTH authentication flow in the params.

AdminInitiateAuthCommand is the recommended way to handle auth in a secure backend environment as it requires developer credentials, adding an extra layer of security.

Pass the username in the params and then generate the password the same way you did in the registration handler. This is why it's important to be able to reproduce the password you created in the registration.

Although we're logging in with Google on the surface, we're still using username/password "under the hood".

Conclusion

That's it on this workaround on Google login with AWS Cognito without going through the hosted UI. This is not an ideal solution, but it serves the purpose if you want to quickly implement simple Google signup/sign-in in your app.

You can check out this repository for the code I reference in this series.

Deploy Cognito Triggers Using Serverless Framework

Kelvin Mwinuka — Mon, 11 Apr 2022 15:36:48 +0000

Recently, I posted an article about pre signup triggers for AWS Cognito user pools. The article went over setting up pre signup validation using a lambda function.

In this article, I'm going to demonstrate how to achieve the same goal, but using the serverless framework instead of the AWS console to develop and deploy the lambdas and policies.

Setup

First install the serverless framework using the following command: npm install -g serverless.

Once serverless is installed, create a project with the following command; serverless create --template aws-nodejs -n cognito-triggers.

With the command above, we're creating a nodejs serverless project intended to be hosted on the AWS cloud platform. We then pass the name of cognito-triggers for the project.

Feel free to use whatever language you want in this project, just be sure to follow your language's package installation and build steps where necessary.

Implementation

First, let's create a .env file at the root of the project with the following content:

COGNITO_USER_POOL_NAME=<user_pool_name>
COGNITO_USER_POOL_ID=<user_pool_id>
COGNITO_USER_POOL_ARN=<user_pool_arn>
REGION=us-west-2

If you're deploying to multiple environments (e.g. testing, staging, production) then you should have multiple env files in your project named in the format .env.{stage}. So the production env file will be .env.production.

For this project, we will stick to one env file for the sake of simplicity.

Let's install a few packages we're going to need for this project with the following command: npm install @aws-sdk/client-cognito-identity-provider dotenv serverless-dotenv-plugin

We will need the dotenv and serverless-dotenv-plugin for loading environment variables. We also need the serverless-offline package if we want to invoke our lambda functions locally. We won't be going into that in this article but you can install it with npm install -D serverless-offline.

You'll notice that there's a serveless.yml file at the root of the project. Open the file and add the following code:

service: cognito-triggers

useDotenv: true

plugins:
  - serverless-dotenv-plugin
  - serverless-offline

frameworkVersion: '3'

In the code above, we're setting the service name, setting useDotenv: true to allow us to load environment variables.

The plugins section has 2 plugins:

serverless-dotenv-plugin for loading environment variables.
serverless-offline for running the project on the local machine (in case you want to invoke the functions locally).

Now let's define the provider:

provider:
  name: aws
  runtime: nodejs14.x
  stage: ${opt:stage, 'dev'}
  region: ${env:REGION}
  profile: default
  iam:
    role:
      statements:
        - Effect: 'Allow'
          Action: 'cognito-idp:ListUsers'
          Resource: '${env:COGNITO_USER_POOL_ARN}'

package:
  patterns:
    - '!.gitignore'

We set the provider name to aws because we're using the AWS platform. Our runtime of choice is nodejs14.x. Be sure to use a runtime that's available for the platform you're deploying to.

When setting the stage, we prefer the provided --stage in the command options. If one is not provided, default to dev. This will dictate which environment file to use when running the service offline or deploying. For example sls offline --stage staging will run the service on your local machine using .env.staging while sls deploy --stage production will deploy the service with the .env.production file.

Now for the interesting part, the actual lambda functions! At the top level of the serverless.yml file right below the provider section, create a function section with the following code:

functions:
  pre_signup:
    handler: ./src/pre_signup.handler
    events:
      - cognitoUserPool:
          pool: ${env:COGNITO_USER_POOL_NAME}
          trigger: PreSignUp
          existing: true

The functions section is where we declare the lambda functions in our service. Here we have a pre_signup function.

The handler property of the function points to the handler function exported by a js file. Make sure the path matches the location of your file. Here we have the file in an src folder that's located at the root of the project.

The events property determines what kind of events can trigger this lambda function. This can be an HTTP request through an API gateway, or in our case, a Cognito signup to a user pool.

If you already have an existing user pool, you have to set the existing property to true for the cognitoUserPool while specifying the user pool's name in the pool property.

Let's create the js function to handle all the pre signup logic.

Create an src folder at the root of the project and then create a file called pre_signup.js within that folder. The file will have the following content:

'use strict';
require("dotenv").config({});

const { COGNITO_USER_POOL_ID } = process.env;

const {
  CognitoIdentityProviderClient,
  ListUsersCommand
} = require("@aws-sdk/client-cognito-identity-provider");

module.exports.handler = async (event, context, callback) => {
  const client = new CognitoIdentityProviderClient();

  const listUsersCommand = new ListUsersCommand({
    UserPoolId: COGNITO_USER_POOL_ID,
    Filter: `email = "${event.request.userAttributes.email}"`
  });

  const result = await client.send(listUsersCommand);

  if (result.Users.length > 0) return callback(new Error("Email is already in use."), event);

  callback(null, event);
};

This code is very familiar if you read my previous article on Pre Signup Validation on AWS Cognito. Basically, we're listing the users in our user pool that have the same email address as the one provided in this signup attempt. If we have more than 0, then throw an error stating that the email address is already in use.

Notice, we're exporting a handler function. This is the function that we reference in the serverless.yml file.

While we're here, let's create another function to edit the messages sent to the user's email address. Cognito user pools have a Custom message trigger that allows us to intercept a message before it's sent and edit its content.

In the functions section of serverless.yml, create a function called custom_message with the following properties:

  custom_message:
    handler: ./src/custom_message.handler
    events:
      - cognitoUserPool:
          pool: ${env:COGNITO_USER_POOL_NAME}
          trigger: CustomMessage
          existing: true

It is identical to the pre_signup functions except it's referencing a different handler and hooking into the CustomMessage trigger.

In the src folder create a custom_message.js file with the following content:

'use strict';
require("dotenv").config({});

module.exports.handler = async (event, context, callback) => {
  switch(event.triggerSource) {
    case "CustomMessage_SignUp":
      event.response.smsMessage = `Hi ${event.userName}, your signup code is ${event.request.codeParameter}`;
      event.response.emailSubject = `Your registration code`;
      event.response.emailMessage = `Hi ${event.userName}, your signup code is ${event.request.codeParameter}`;
      break;
    case "CustomMessage_ForgotPassword":
      event.response.smsMessage = `Hi ${event.userName}, your password reset code is ${event.request.codeParameter}. If you did not request this code, ignore this message. Please DO NOT share this code with anyone.`;
      event.response.emailSubject = `Your password reset code`;
      event.response.emailMessage = `Hi ${event.userName}, your password reset code is ${event.request.codeParameter}. If you did not request this code, ignore this email. Please DO NOT share this code with anyone.`;
      break;
    case "CustomMessage_ResendCode":
      event.response.smsMessage = `Hi ${event.userName}, your requested code is ${event.request.codeParameter}`;
      event.response.emailSubject = `Your requested code`;
      event.response.emailMessage = `Hi ${event.userName}, your requested verification code is ${event.request.codeParameter}`;
      break;
    default:
      event.response.smsMessage = `Hi ${event.userName}, your requested code is ${event.request.codeParameter}`;
      event.response.emailSubject = `Your requested code`;
      event.response.emailMessage = `Hi ${event.userName}, your requested code is ${event.request.codeParameter}`;
  }
  callback(null, event);
}

The handler captures different message events and displays a relevant message depending on the message event. CustomMessage_SignUp is the trigger source when the signup verification email is triggered, CustomMessage_ForgotPassword for the password reset email and CustomMessage_ResendCode when a manual code request is triggered (e.g attempting to log in when unconfirmed).

You can find more information about the different trigger sources here.

The event object for this trigger looks like this:

{
  version: '1',
  region: 'us-west-2',
  userPoolId: '<user_pool_id>',
  userName: '<username>',
  callerContext: {
    awsSdkVersion: 'aws-sdk-js-3.58.0',
    clientId: '<client_id>'
  },
  triggerSource: 'CustomMessage_SignUp',
  request: {
    userAttributes: {
      sub: 'd98dad2a-c2f3-4f97-bc49-a3ed3c81f27a',
      email_verified: 'false',
      'cognito:user_status': 'UNCONFIRMED',
      email: '<user_email_address>'
    },
    codeParameter: '{####}',
    linkParameter: '{##Click Here##}',
    usernameParameter: null
  },
  response: { smsMessage: null, emailMessage: null, emailSubject: null }
}

Make sure you include the codeParameter in your custom message.

Deployment

To deploy the app, run: sls deploy. If you are deploying to a specific environment, specify it with the --stage option (e.g. sls deploy --stage staging or sls deploy --stage production).

If you'd like to remove the deployed service, run sls remove or sls remove --stage <stage> and the service along with any resources you might have created in this service will be destroyed.

Pre Signup Validation on AWS Cognito

Kelvin Mwinuka — Fri, 08 Apr 2022 20:27:19 +0000

In the last article, we leveraged AWS Cognito to handle user authentication in our application. There was a caveat with the setup, email sharing was allowed.

We want to make sure that we only have one user per email. We could build this logic into the sign-up handler in our app's backend but there are a couple of reasons why it's not the best practice.

The validation will only live in this particular backend. If we create another app that interacts with the same user pool, we will have to repeat this logic there too.
We're adding bloat to the request handler, we could keep this handler clean by avoiding unnecessary code if we can.

Enter Cognito user pool triggers. We'll specifically look at the pre-signup trigger. This trigger is executed before Cognito's own signup validation with a couple of notable advantages:

We can add custom validation when registering a new user to the user pool. In our case, it's to check if the submitted email is already in use.
The logic is baked into the user pool. Any signup event for this user pool will be validated regardless of where it's coming from.

Implementation

Lambda

Make sure that the lambda is in the same region as the user pool. The following is the lambda's code:

const { CognitoIdentityProviderClient, ListUsersCommand } = require("@aws-sdk/client-cognito-identity-provider");

exports.handler = async (event, context, callback) => {
    // TODO implement
    const params = {
        UserPoolId: 'us-west-2_rxOJKcUKc',
        Filter: `email = "${event.request.userAttributes.email}"`
    };

    const client = new CognitoIdentityProviderClient();
    const listUsersCommand = new ListUsersCommand(params);

    const data = await client.send(listUsersCommand);

    if (data?.Users?.length > 0) {
        callback(new Error("Email is already taken"), event);
    } else {
        callback(null, event);
    }

};

Before we link this lambda to the user pool, we need to make sure it runs properly. In this example, I'm using the JavaScript v3 SDK. If we try to run this, the @aws-sdk/client-cognito-identity-provider module will not be found.

Layer

This section is only applicable if you're using the v3 SDK at the time of writing this article. If you're not using the v3 SDK, you can skip ahead to the permissions section.

We need to create a lambda layer containing this package so we can use it in the lambda. Create a new project in your development environment. Navigate to the folder and run npm init.

Complete the setup process and then run npm install @aws-sdk/client-cognito-identity-provider to install the package.

Open the package.json file and add the following line to the scripts section:

{
  ...
  "scripts": {
    ...
    "build": "rm -rf nodejs && rm cognito-base-layer.zip && npm install && mkdir nodejs && mv node_modules nodejs && zip -r cognito-base-layer.zip . && cp cognito-base-layer.zip ~/Downloads"
  },
  ...
}

This is the build script for the layer. It does the following:

Delete the previous nodejs directory and cognito-base-layer.zip file from the previous build.
Install the packages.
Create a directory called nodejs.
Move the node_modules folder into nodejs.
Zip the current directory into a zip file called cognito-base-layer.zip.
Copy the zip file to the desired location (Optional).

If you're wondering why we move the node_modules to a subfolder, this is where the lambda will look for the installed packages. If you only have node_modules at the root, your packages will not be found.

When you're ready, run npm run build. A new zip file will be created. Now that we have the zip file, let's create a layer:

Go to the lambda service and click on Layers

Click on "Create layer"

Fill in the layer details:

Name the layer whatever you like. In the upload section, upload the zip file that was generated in the previous build.

In the "compatible architectures" section, make sure to select the same architecture that your lambda is based on. In my case, it's x86_64.

When you're done click "Create".

Let's add this layer to the lambda to allow it to make use of the package(s) in the layer.

Navigate to the lambda function and click on Layers:

Click on Add a layer.

Fill in the layer details:

For the layer source, select Custom layers. In the custom layers dropdown menu, select the layer you just created. Once selected, you'll have the option to select a layer version.

Every time you make another upload on a layer, a new version is created and the old version is kept. This is to prevent breaking lambda functions that depend on the current version as each lambda has to specify which layer version they depend on.

Once you're done, click "Add".

That's it on layers, now our lambda can make use of the AWS JavaScript v3 SDK.

Permissions

We're not done yet. This lambda currently doesn't have the correct permissions to list users from a Cognito user pool. Let's grant the correct permissions to the lambda function. First, take note of the lambda function's role.

You can find this in the Configuration tab of the lambda function:

Navigate to the IAM Management Console and click on the Policies tab:

Click on "Create Policy":

Click on the JSON tab and you should see a template like this:

{
    "Version": "2012-10-17",
    "Statement": []
}

In the statement array add the following code:

{
    "Effect": "Allow",
    "Action": "cognito-idp:ListUsers",
    "Resource": "arn:aws:cognito-idp:<region>:<account_id>:userpool/<userpool_id>"
}

The above policy statement allows us to list users from the specified Cognito user pool. Replace the Resource value with your user pool's ARN.

Now let's attach this policy to the lambda's role in order to allow the lambda to make use of it.

Navigate to "Roles" in the IAM Management Console:

Search for the lambda's role and click on it:

Click on the "Add permissions" dropdown and then click on "Attach policies":

Search for the policy you just created, click on the check box and then click on "Attach policies" at the bottom of the page.

Now we have the right permissions and layers to execute this lambda. All we need to do now is set the lambda as a pre signup trigger for the user pool.

Triggers

Navigate to the user pool's console and click on the "Triggers" tab:

Click on the Pre sign-up dropdown and select the lambda function we created:

Click on "Save changes" at the bottom of the page.

Result

That's all there is to the setup for our use case. Now we can go ahead and try to sign up with an email address that is already used in the user pool. Doing so should return an error that looks like this:

UserLambdaValidationException: PreSignUp failed with error Email is already taken.
...
{
    '$fault': 'client',
    '$metadata': {
        httpStatusCode: 400,
        requestId: '3bc8f968-cbf5-4960-857f-e48daa312870',
        extendedRequestId: undefined,
        cfId: undefined,
        attempts: 1,
        totalRetryDelay: 0
  },
  __type: 'UserLambdaValidationException'
}

Bonus

You can do more with a pre sign-up trigger. The event object passed to the lambda function has a response property with the following structure:

"response": { "autoConfirmUser": "boolean", "autoVerifyPhone": "boolean" "autoVerifyEmail": "boolean" }

These all default to false. They can be set to true if you'd like to skip some parts of the default sign up flow. Before invoking the callback, you can add the following statements:

// Automatically set user's account status to CONFIRMED
event.response.autoConfirmUser = true

// Automatically set phone number as verified
event.response.autoVerifyPhone = true

// Automatically set email as verified
event.response.autoVerifyEmail = true

Basic Authentication with AWS Cognito & NextJS

Kelvin Mwinuka — Thu, 07 Apr 2022 13:50:52 +0000

I’ve written quite a few articles about authentication before. This is yet another user auth article.

However, this time it’s a little different. Previous articles have been about managing user authentication yourself. In this article, we will be leveraging AWS Cognito and its user pools for the same functionality.

You can check out some of my previous articles on handling user auth manually here:

Setup

This article assumes that you have an AWS Cognito user pool set up and that you have some NextJS boilerplate code set up as well. I will write another article explaining how to set up a Cognito user pool using the AWS console.

First, let’s understand the project structure.

.
├── components
│   ├── layouts
│   │   └── InputLayout.js
│   ├── AuthLinkText.js
│   ├── InputField.js
│   ├── InputHelperText.js
│   ├── Label.js
│   └── SubmitButton.js
├── hooks
│   ├── useAuth.js
│   ├── useRegister.js
│   └── useValidationSchema.js
├── pages
│   ├── api
│   │   ├── confirm
│   │   │   ├── index.js
│   │   │   └── send.js
│   │   ├── password
│   │   │   ├── reset.js
│   │   │   └── reset\_code.js
│   │   ├── login.js
│   │   └── register.js
│   ├── password
│   │   ├── reset.js
│   │   └── reset\_code.js
│   ├── \_app.js
│   ├── confirm.js
│   ├── index.js
│   ├── login.js
│   └── register.js
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── styles
│   ├── Home.module.css
│   └── globals.css
├── README.md
├── next.config.js
├── package-lock.json
└── package.json

Most of these are nothing special as they’re created automatically when you set up a NextJS project.

The “components” folder contains all the re-usable custom components like form input fields and layouts.

For this article, I will focus on the “hooks” and “pages” folders. If you’d like to look at the full code, you can find it on Github.

The “hooks” folder has 3 files:

useAuth.js contains a hook that will handle user sign in and password reset.
useRegister.js contains a hook that will handle user registration and verification.
useValidationSchema.js contains the form validation schemas. We won’t be covering this in the article. Feel free to check the repo out for more details on this.

I prefer to use hooks because they allow me to separate the business logic from the UI logic in the component.

The “pages” folder has an “API” sub-directory. This is where all the backend code lives.

NextJS uses file-system based routing so the file structure is what determines the API endpoints.

All the other files and sub-directories outside the API sub-directory will be treated as frontend pages.

Make sure to install the @aws-sdk/client-cognito-identity-provider package.

You can refer to the full CognitoIdentityServiceProvider SDK for more in-depth explanations of what is discussed in this article.

Sign Up

First, let’s handle user registration. Navigate to the “pages/api/register.js” and add the following code:

import { CognitoIdentityProviderClient, SignUpCommand } from '@aws-sdk/client-cognito-identity-provider'

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID } = process.env

export default async function handler(req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        ClientId: COGNITO_APP_CLIENT_ID,
        Password: req.body.password,
        Username: req.body.username,
        UserAttributes: [
            {
                Name: 'email',
                Value: req.body.email
            }
        ]
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO\_REGION
    })
    const signUpCommand = new SignUpCommand(params)

    try {
        const response = await cognitoClient.send(signUpCommand)
        return res.status(response['$metadata'].httpStatusCode).send()
    } catch (err) {
        console.log(err)
        return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
    }
}

This is a handler for the “/api/register” endpoint. Include a guard clause to make sure only POST requests are allowed, return a 405 error for any other type of request.

In the params, we have the following:

ClientId – App client Id that you created for this user pool in the AWS console.
Password – The user’s chosen password.
Username -The user’s chosen username.
UserAttributes – Any additional attributes provided by the user upon signing up. The default list of attributes includes address, nickname, birthdate, phone number, email, family name, preferred username, gender, profile, given name, zoneinfo, locale, updated at, middle name, website and name. You can add custom attributes as well (for example, “Department” if you’re creating an auth system for an organisation).

Keep in mind that if you’re setting a custom user attribute you need to follow the following format:

{
    Name: 'custom:<AttributeName>',             
    Value: '<AttributeValue>'
}

In the case of adding a department attribute, it would look like this:

{
    Name: 'custom:Department',              
    Value: 'Engineering'
}

Then we send the SignUpCommand to trigger a user sign up. Return a status 200 response if all goes well, otherwise, return the error code from Cognito and the stringified version of the error.

Cognito will usually return an error that looks like this:

UsernameExistsException: User already exists
...
{
  '$fault': 'client',
  '$metadata': {
    httpStatusCode: 400,
    requestId: '9442223e-ef29-40c1-880e-6689638d8042',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  __type: 'UsernameExistsException'
}

Grab the status code and message and then forward them to the front end.

When the request is successful, Cognito will return a response that looks like this:

{
  '$metadata': {
    httpStatusCode: 200,
    requestId: '67f6d99c-d13c-4677-ab46-957d88f62bb9',
    extendedRequestId: undefined,
    cfId: undefined,
    attempts: 1,
    totalRetryDelay: 0
  },
  AuthenticationResult: {
    AccessToken: "...",
    ExpiresIn: 3600,
    NewDeviceMetadata: undefined,
    RefreshToken: "...",
    TokenType: "Bearer"
  },
  ChallengeName: undefined,
  ChallengeParameters: {},
  Session: undefined
}

For this application, we’re only interested in the Authentication result as it contains the access and refresh tokens.

Flesh out the useRegister hook in order to make use of the API endpoint we created above.

Create a method called “register” with the following logic:

import { useRouter } from 'next/router'

export default function useRegister() {

    const router = useRouter()

    const register = (values, { setSubmitting }) => {
        fetch('/api/register', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(values)
        }).then(res => {
            if (!res.ok) throw res
            router.push({
                pathname: '/confirm',
                query: { username: values?.username }
            },
                "/confirm")
        }).catch(err => {
            console.error(err)
        }).finally(() => {
            setSubmitting(false)
        })
    }

    const confirm = (values, { setSubmitting }) => {
        // Confirm the user
    }

    return {
        register,
        confirm
    }
}

The register method is the submit method for our registration form. The “values” object contains the form data and “setSubmitting” allows us to update the loading state once we’re done processing the request.

This will be a common theme with most of the hooks in this project.

Set the Content-Type header to “application/json” to help NextJS parse the request body.

In this method, we call the register endpoint and pass all the form values (which include username, email, and password). If the request is successful, we redirect to the confirm page and prompt the user to verify their email address. More on this in the verification section.

You might notice we have an empty confirm method here. This method will handle the request to verify the user. We will cover this in the verification stage as well.

Here is what the registration form will look like, notice we import the useRegister hook and pass the register method as the form submit handler.

import { Formik } from "formik";
import InputLayout from "../components/layouts/InputLayout";
import Label from "../components/Label";
import InputField from "../components/InputField";
import InputHelperText from "../components/InputHelperText";
import AuthLinkText from "../components/AuthLinkText";
import SubmitButton from "../components/SubmitButton";
import useValidationSchema from "../hooks/useValidationSchema";
import useRegister from '../hooks/useRegister'
import Link from "next/link";

export default function Register() {

    const { registerSchema } = useValidationSchema()
    const { register } = useRegister()

    return (
        <div style={{
            padding: "10px"
        }}>
            <Formik
                initialValues={{
                    username: "",
                    email: "",
                    password: "",
                    confirm_password: ""
                }}
                validationSchema={registerSchema}
                onSubmit={register}
                validateOnMount={false}
                validateOnChange={false}
                validateOnBlur={false}>
                {({
                    isSubmitting,
                    errors,
                    values,
                    handleSubmit,
                    handleChange,
                    handleBlur
                }) => (
                    <form onSubmit={handleSubmit}>
                        <InputLayout>
                            <Label>Username</Label>
                            <InputField
                                type="text"
                                name="username"
                                placeholder="Username"
                                onChange={handleChange}
                                onBlur={handleBlur}
                                value={values?.username}
                            />
                            <InputHelperText isError>{errors?.username}</InputHelperText>
                        </InputLayout>
                        <InputLayout>
                            <Label>Email</Label>
                            <InputField
                                type="email"
                                name="email"
                                placeholder="Email"
                                onChange={handleChange}
                                onBlur={handleBlur}
                                value={values?.email}
                            />
                            <InputHelperText isError>{errors?.email}</InputHelperText>
                        </InputLayout>
                        <InputLayout>
                            <Label>Password</Label>
                            <InputField
                                type="password"
                                name="password"
                                placeholder="Password"
                                onChange={handleChange}
                                onBlur={handleBlur}
                                value={values?.password}
                            />
                            <InputHelperText isError>{errors?.password}</InputHelperText>
                        </InputLayout>
                        <InputLayout>
                            <Label>Confirm password</Label>
                            <InputField
                                type="password"
                                name="confirm_password"
                                placeholder="Confirm password"
                                onChange={handleChange}
                                onBlur={handleBlur}
                                value={values?.confirm_password}
                            />
                            <InputHelperText isError>{errors?.confirm_password}</InputHelperText>
                        </InputLayout>
                        <InputLayout>
                            <AuthLinkText href="/login">Already have an account? Log in</AuthLinkText>
                        </InputLayout>
                        <SubmitButton isSubmitting={isSubmitting} />
                    </form>
                )}
            </Formik>
        </div>
    )
}

Sign In

Now that we’ve registered our users, it’s time to allow them to log into our application by authenticating them against our Cognito user pool.

Add the following code to the “pages/api/login.js” file.

import { CognitoIdentityProviderClient, AdminInitiateAuthCommand } from "@aws-sdk/client-cognito-identity-provider"

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID, COGNITO_USER_POOL_ID } = process.env

export default async function handler(req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        AuthFlow: 'ADMIN_USER_PASSWORD_AUTH',
        ClientId: COGNITO_APP_CLIENT_ID,
        UserPoolId: COGNITO_USER_POOL_ID,
        AuthParameters: {
            USERNAME: req.body.username,
            PASSWORD: req.body.password
        }
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO_REGION
    })
    const adminInitiateAuthCommand = new AdminInitiateAuthCommand(params)

    try {
        const response = await cognitoClient.send(adminInitiateAuthCommand)
        console.log(response)
        return res.status(response['$metadata'].httpStatusCode).json({
            ...response.AuthenticationResult
        })
    } catch(err) {
        console.log(err)
        return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
    }
}

At the moment, we’re handling only username/password auth. To do this we need to use the ADMIN_USER_PASSWORD_AUTH flow. This authentication flow requires developer credentials. If you're authenticating users in a secure server, this is the recommended method over InitiateAuthCommand with USER_PASSWORD_AUTH.

The final parameter is AuthParameters. This simply contains the username and password passed to the endpoint upon form submission. Be careful here and make sure the auth parameters are in all uppercase as you see here, otherwise, they will not be recognised.

Now let’s divert our attention to the “useAuth” hook. Add this code to the “hooks/useAuth.js” file:

import { useRouter } from "next/router";

export default function useAuth(){

  const router = useRouter()

  const login = (values, { setSubmitting }) => {
    fetch('/api/login', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(values)
    }).then(res => {
      if (!res.ok) throw res
    }).then(data => {
      console.log(data)
    }).catch(async err => {
      const responseData = await err.json()
      if (responseData?.message?.includes("UserNotConfirmedException:")) {
        // Trigger confirmation code email
        await fetch('/api/confirm/send', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ username: values.username })
        })
        await router.push(
      {
            pathname: "/confirm",
            query: {username: values.username},
          },
          "/confirm")
      }
    }).finally(() => {
      setSubmitting(false)
    })
  }

  const resetPasswordRequest = (values, { setSubmitting }) => {
    // Send the password reset code
  }

  const resetPassword = (values, { setSubmitting }) => {
    // Send request to reset password
  }

  return {
    login,
    resetPasswordRequest,
    resetPassword
  }
}

Here we have a login method that is similar to the register method we created above. The “values” object represents our form data (username and password).

It’s important to note that Cognito will not allow a user to be authenticated if they have not yet been verified/confirmed. So attempting this login with an unconfirmed user will return an error.

To handle this, trigger an endpoint to send a confirmation email to the user and then redirect them to the confirm page so they can be verified. More on this endpoint in the verification section.

Our login page has the following code:

import { Formik } from "formik";
import InputLayout from "../components/layouts/InputLayout";
import Label from "../components/Label";
import InputField from "../components/InputField";
import InputHelperText from "../components/InputHelperText";
import AuthLinkText from "../components/AuthLinkText";
import SubmitButton from "../components/SubmitButton";
import useAuth from "../hooks/useAuth";
import useValidationSchema from "../hooks/useValidationSchema";
import { useRouter } from "next/router";

export default function Login() {

  const router = useRouter();
  const { success } = router.query;

  const { loginSchema } = useValidationSchema();
  const { login } = useAuth();

  return (
    <div style={{
      padding: "10px"
    }}>
      {
        success === "true" &&
        <div style={{
          paddingTop: "10px",
          paddingBottom: "10px",
          color: "green"
        }}>
          {'You\\'re signed up!'}
        </div>
      }
      <Formik
        initialValues={{
          username: "",
          password: ""
        }}
        validationSchema={loginSchema}
        onSubmit={login}
        validateOnMount={false}
        validateOnChange={false}
        validateOnBlur={false}>
        {({
          isSubmitting,
          errors,
          values,
          handleChange,
          handleBlur,
          handleSubmit
        }) => (
          <form onSubmit={handleSubmit}>
            <InputLayout>
              <Label>Username</Label>
              <InputField
                type="text"
                name="username"
                placeholder="Username or email"
                onChange={handleChange}
                onBlur={handleBlur}
                value={values?.username}
              />
              <InputHelperText isError>{errors?.username}</InputHelperText>
            </InputLayout>
            <InputLayout>
              <Label>Password</Label>
              <InputField
                type="password"
                name="password"
                placeholder="Password"
                onChange={handleChange}
                onBlur={handleBlur}
                value={values?.password}
              />
              <InputHelperText isError>{errors?.password}</InputHelperText>
            </InputLayout>
            <InputLayout>
              <AuthLinkText href="/password/reset_code">{'Forgot password?'}</AuthLinkText>
            </InputLayout>
            <InputLayout>
              <AuthLinkText href="/register">{'Don\\'t have an account? Register.'}</AuthLinkText>
            </InputLayout>
            <SubmitButton isSubmitting={isSubmitting} />
          </form>
        )}
      </Formik>
    </div>
  );
}

Just like before, we import the useAuth hook and make use of its login method as the form submission handler.

We will discuss the 2 password reset methods in the useAuth hook in the password reset section.

Verification

So we’ve registered our users, but we cannot authenticate them because they are not verified. Let’s fix that.

A few things to note before we continue:

I have set up my user pool to use an email code for verification. This is where AWS will send an email with a code that the user has to enter manually on your app. Other authentication methods include: a clickable verification link and a verification code sent to their phone number. If you are using any of the other verification methods (except verification code to a phone number), then you can go ahead and skip this section.
Cognito will automatically trigger the chosen verification method upon successful registration. Verification can also be triggered via the SDK.

In the “pages/api/confirm/index.js” file, add the following code:

import {
    CognitoIdentityProviderClient,
    ConfirmSignUpCommand
} from "@aws-sdk/client-cognito-identity-provider"

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID } = process.env

export default async function handler (req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        ClientId: COGNITO_APP_CLIENT_ID,
        ConfirmationCode: req.body.code,
        Username: req.body.username
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO_REGION
    })
    const confirmSignUpCommand = new ConfirmSignUpCommand(params)

    try {
        const response = await cognitoClient.send(confirmSignUpCommand)
        console.log(response)
        return res.status(response['$metadata'].httpStatusCode).send()
    } catch (err) {
        console.log(err)
        return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
    }
}

Here create and send confirmSignUpCommand with the following parameters:

ClientId.
ConfirmationCode – The code sent to the user’s email/phone by Cognito.
Username – The username of the user you’d like to verify.

Note that because this is the index file within the confirm directory, we do not need to specify the filename when calling this endpoint. The endpoint would just be “/api/confirm”

In the same confirm directory, we have a file called “send.js”. This file is responsible for manually triggering the confirmation code email.

Add the following code to this file:

import {
    CognitoIdentityProviderClient,
    ResendConfirmationCodeCommand
} from "@aws-sdk/client-cognito-identity-provider"

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID } = process.env

export default async function handler (req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        ClientId: COGNITO_APP_CLIENT_ID,
        Username: req.body.username
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO_REGION
    })
    const resendConfirmationCodeCommand = new ResendConfirmationCodeCommand(params)

    try {
        const response = await cognitoClient.send(resendConfirmationCodeCommand)
        console.log(response)
        return res.status(response['$metadata'].httpStatusCode).send()
    } catch (err) {
        console.log(err)
        return res.stat(err['$metadata'].httpStatusCode).json({ message: err.toString() })
    }
}

Here, simply create and send ResendConfirmationCodeCommand with a params object containing the ClientId and the username of the user you’d like to verify.

Cognito will search for the user with the specified username, then send a verification code to their email/phone number depending on your settings and/or which one is provided.

You might be wondering why this command is called ResendConfirmationCodeCommand.

Cognito will automatically send a verification code to the user upon signing up.

If you are triggering the registration manually, then you are always “re-sending” the code.

Remember that “confirm” method in the useRegister hook? It’s time to flesh it out.

Add the following logic in that method:

const confirm = (values, { setSubmitting }) => {
        fetch('/api/confirm', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(values)
        }).then(res => {
            if (!res.ok) throw res
            router.push({
                pathname: '/login',
                query: { confirmed: true }
            },
                "/login")
        }).catch(err => {
            console.error(err)
        }).finally(() => {
            setSubmitting(false)
        })
    }

From this method, call the “/api/confirm” endpoint with the form values. If the confirmation is successful, redirect the user to the login page so they can sign in.

Here’s a look at the confirm page in the “pages/confirm.js” file:

import { Formik } from "formik";
import InputLayout from "../components/layouts/InputLayout";
import Label from "../components/Label";
import InputField from "../components/InputField";
import InputHelperText from "../components/InputHelperText";
import SubmitButton from "../components/SubmitButton";
import useValidationSchema from "../hooks/useValidationSchema";
import useRegister from "../hooks/useRegister";
import { useRouter } from "next/router";

export default function Confirm(){

    const router = useRouter();
    const { username } = router.query;

    const { confirm } = useRegister();
    const { confirmSchema } = useValidationSchema();

    return (
        <div style={{
            padding: "10px"
        }}>
            <Formik
                initialValues={{
                    username: username,
                    code: ""
                }}
                onSubmit={confirm}
                validationSchema={confirmSchema}
                validateOnMount={false}
                validateOnChange={false}
                validateOnBlur={false}>
                {
                    ({
                        isSubmitting,
                        errors,
                        values,
                        handleSubmit,
                        handleChange,
                        handleBlur
                     }) => (
                        <form onSubmit={handleSubmit}>
                            <InputLayout>
                                <Label>Confirmation Code</Label>
                                <InputField
                                    type={"text"}
                                    name={"code"}
                                    placeholder={"Code"}
                                    onChange={handleChange}
                                    onBlur={handleBlur}
                                    value={values?.code}
                                />
                                <InputHelperText isError>{errors?.code}</InputHelperText>
                            </InputLayout>
                            <SubmitButton isSubmitting={isSubmitting} />
                        </form>
                    )
                }
            </Formik>
        </div>
    )
}

Password reset

One of the most important features in any auth system is the ability to reset passwords.

Fortunately, password reset is made dead simple by Cognito.

The password reset flow is similar to the verification flow but with some extra steps:

The user clicks the “Forgot password” link and is redirected to a page where they are prompted to enter their username.
Send a confirmation code to the user’s email/number.
If the code is sent successfully, redirect the user to a reset page where they enter the code, along with their new password.

First, prepare the endpoint to trigger the verification email containing the code.

Add the following code to “pages/api/password/reset_code.js”:

import { CognitoIdentityProviderClient, ForgotPasswordCommand } from '@aws-sdk/client-cognito-identity-provider'

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID } = process.env

export default async function handler (req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        ClientId: COGNITO_APP_CLIENT_ID,
        Username: req.body.username
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO_REGION
    })
    const forgotPasswordCommand = new ForgotPasswordCommand(params)

    try {
        const response = await cognitoClient.send(forgotPasswordCommand)
        console.log(response)
        return res.status(response['$metadata'].httpStatusCode).send()
    } catch (err) {
        console.log(err)
        return res.status(err['$metadata'].httpStatusCode).json({ message: toString() })
    }
}

Here we accept the ClientId and username params for the “ForgotPasswordCommand” command. Cognito will find a user with the matching username and send them a verification code using the configured method.

In the “pages/api/password/reset.js” file, add the code below:

import {
    CognitoIdentityProviderClient,
    ConfirmForgotPasswordCommand
} from "@aws-sdk/client-cognito-identity-provider"

const { COGNITO_REGION, COGNITO_APP_CLIENT_ID } = process.env

export default async function handler(req, res) {
    if (req.method !== 'POST') return res.status(405).send()

    const params = {
        ClientId: COGNITO_APP_CLIENT_ID,
        ConfirmationCode: req.body.code,
        Password: req.body.password,
        Username: req.body.username
    }

    const cognitoClient = new CognitoIdentityProviderClient({
        region: COGNITO_REGION
    })
    const confirmForgotPasswordCommand = new ConfirmForgotPasswordCommand(params)

    try {
        const response = await cognitoClient.send(confirmForgotPasswordCommand)
        console.log(response)
        return res.status(response['$metadata'].httpStatusCode).send()
    } catch (err) {
        console.log(err)
        return res.status(err['$metadata'].httpStatusCode).json({ message: err.toString() })
    }
}

Here we accept the ConfirmationCode that was sent to the user, their new password and their username.

Cognito will take care of all the logic of making sure that the code provided is valid and is the one that was sent to the user with the specified username.

You’ll remember that in the useAuth hook, we had 2 empty methods “resetPasswordRequest” and “resetPassword”. We are going to flesh those out now.

Add the following logic to those methods:

const resetPasswordRequest = (values, { setSubmitting }) => {
    fetch('/api/password/reset\_code', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(values)
    }).then(res => {
      if (!res.ok) throw res
      router.push({
        pathname: '/password/reset',
        query: { username: values.username }
      },
        "/password/reset")
    }).catch(err => {
      console.error(err)
    }).finally(() => {
      setSubmitting(false)
    })
  }

  const resetPassword = (values, { setSubmitting }) => {
    fetch('/api/password/reset', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(values)
    }).then(res => {
      if (!res.ok) throw res
      router.push({
        pathname: '/login',
        query: { reset: true }
      },
        "/login")
    }).catch(err => {
      console.error(err)
    }).finally(() => {
      setSubmitting(false)
    })
  }

The resetPasswordRequest method triggers the “/api/password/reset_code” endpoint.

From the user’s perspective, they are redirected to a page where they enter their username. Once they submit the form, they receive an email and are redirected to the password reset page (if the email was successfully sent).

The resetPassword method triggers the “/api/password/reset” endpoint to actually reset the password.

Here’s how the forgot password form looks:

import { Formik } from "formik";
import InputLayout from "../../components/layouts/InputLayout";
import Label from "../../components/Label";
import InputField from "../../components/InputField";
import InputHelperText from "../../components/InputHelperText";
import SubmitButton from "../../components/SubmitButton";
import useValidationSchema from "../../hooks/useValidationSchema";
import useAuth from '../../hooks/useAuth';

export default function ResetCode(){

    const { resetPasswordRequestSchema } = useValidationSchema();
    const { resetPasswordRequest } = useAuth();

    return (
        <div style={{
            padding: "10px"
        }}>
            <Formik
                initialValues={{
                    username: ""
                }}
                onSubmit={resetPasswordRequest}
                validationSchema={resetPasswordRequestSchema}
                validateOnMount={false}
                validateOnChange={false}
                validateOnBlur={false}
                >
                {
                    ({
                        isSubmitting,
                        errors,
                        values,
                        handleSubmit,
                        handleChange,
                        handleBlur
                    }) => (
                        <form onSubmit={handleSubmit}>
                            <InputLayout>
                                <Label>Username</Label>
                                <InputField
                                    type={"text"}
                                    name={"username"}
                                    placeholder={"Username"}
                                    onChange={handleChange}
                                    onBlur={handleBlur}
                                    value={values?.username}
                                />
                                <InputHelperText isError>{errors?.username}</InputHelperText>
                            </InputLayout>
                            <SubmitButton isSubmitting={isSubmitting} />
                        </form>
                    )
                }
            </Formik>
        </div>
    )
}

Here’s how the password reset form looks:

import { Formik } from "formik";
import InputLayout from "../../components/layouts/InputLayout";
import Label from "../../components/Label";
import InputField from "../../components/InputField";
import InputHelperText from "../../components/InputHelperText";
import SubmitButton from "../../components/SubmitButton";
import useValidationSchema from "../../hooks/useValidationSchema";
import useAuth from '../../hooks/useAuth';
import { useRouter } from "next/router";

export default function Reset(){

    const router = useRouter()
    const { username } = router.query

    const { resetPasswordSchema } = useValidationSchema();
    const { resetPassword } = useAuth()

    return (
        <div style={{
            padding: "10px"
        }}>
            <Formik
                initialValues={{
                    username: username,
                    code: "",
                    password: "",
                    confirm\_password: ""
                }}
                validationSchema={resetPasswordSchema}
                onSubmit={resetPassword}
                validateOnMount={false}
                validateOnChange={false}
                validateOnBlur={false}
            >
                {
                    ({
                        isSubmitting,
                        errors,
                        values,
                        handleSubmit,
                        handleBlur,
                        handleChange
                    }) => (
                        <form onSubmit={handleSubmit}>
                            <InputLayout>
                                <Label>Reset code</Label>
                                <InputField
                                    type={"text"}
                                    name={"code"}
                                    placeholder={"Reset code"}
                                    onChange={handleChange}
                                    onBlur={handleBlur}
                                    value={values?.code}
                                />
                                <InputHelperText isError>{errors?.code}</InputHelperText>
                            </InputLayout>
                            <InputLayout>
                                <Label>New password</Label>
                                <InputField
                                    type={"password"}
                                    name={"password"}
                                    placeholder={"New password"}
                                    onChange={handleChange}
                                    onBlur={handleBlur}
                                    value={values?.password}
                                />
                                <InputHelperText isError>{errors?.password}</InputHelperText>
                            </InputLayout>
                            <InputLayout>
                                <Label>Confirm password</Label>
                                <InputField
                                    type={"password"}
                                    name={"confirm_password"}
                                    placeholder={"Confirm password"}
                                    onChange={handleChange}
                                    onBlur={handleBlur}
                                    value={values?.confirm_password}
                                />
                                <InputHelperText isError>{errors?.confirm_password}</InputHelperText>
                            </InputLayout>
                            <SubmitButton isSubmitting={isSubmitting} />
                        </form>
                    )
                }
            </Formik>
        </div>
    )
}

Caveat

A major caveat with the implementation we’ve just created is that 2 or more users can actually register with the same email.

We don’t want any user to receive a code for another user’s password reset.

For this and many other reasons, you may want to force unique emails for each user.

We can easily achieve this using Cognito triggers which are event triggers that run custom lambda functions. These allow us to customise our workflows.

We can trigger lambdas during any of the following events (and more):

Pre-signup – Right before Cognito signup is triggered.
Pre-authentication – Right before the user is authenticated by Cognito.
Custom message – Right before a verification/confirmation message is sent. We can dynamically edit the message here.
Post-authentication – After the user is successfully authenticated. If the authentication fails, this will not be triggered.
Post-confirmation – After a user is verified/confirmed. You can use this to send a welcome email or enable certain privileges that are only available to confirmed users.

These are only a few of the triggers available to us. You can find more information on these triggers here.

In our case, the trigger we’re most interested in is the Pre-signup trigger. We can check if there are any current users who have the same email address as the one we’ve just received for signup. If so, throw an error and fail early before the Cognito signup.

I will publish an article that demonstrates how to achieve this.

Python Lambda Functions

Kelvin Mwinuka — Sat, 02 Jan 2021 00:13:17 +0000

Python lambda functions are an invaluable feature. One of the benefits of using Python is that it facilitates relatively compact code compared to other programming languages. This means getting so much more done with fewer lines of code.

This isn't always the case, however. If you're not aware of the tools python provided in order to achieve this, it is very easy to write verbose code that defeats the point of picking Python for its "compactness".

One such tool is the lambda function. These allow us to create anonymous functions in python. If you've read good python programmers' code before, you might have come across something that looks like this:

add = lambda a,b : a + b

The code above might look a bit confusing, let me clarify the syntax of a lambda function by breaking it down into its components. Lambda functions have 3 components: the 'lambda' keyword (of course), the set of arguments, and an expression.

lambda [(optional) arguments] : [expression]

The Rules

Before we go into detail about the implementation of lambda functions, let's first discuss their rules:

Lambda functions are nameless (unless assigned to a variable). You cannot assign a function name after the 'lambda' keyword' as you would with the 'def' keyword.
Arguments are optional. Lambda functions can be defined without passing any arguments, just like a regular function.
Lambda functions can only have one expression.
Just like a regular function, you can return anything from a lambda function. It is also possible to return nothing.
Lambda functions can be assigned to variables for repeated use. This is the only way to name a lambda function.
Lambda functions can be returned from regular functions.
Lambda functions can return other lambda functions.

Why Use Lambda Functions?

If you have never used lambda functions before, you probably think that you would do just fine without them, and you'd be right. However, as I've stated before, they play an important role in making sure we maintain clean, compact and pythonic code.

Lambda functions are most useful in situations where an anonymous function is required for single-use or repeated use.

Implementation

As stated before, we can use lambda functions alongside regular functions to generate functions. Let's create an example where we want to create 3 functions. One that doubles a given number, one that triples a given number, and one that quadruples a given number. We could achieve this by creating 3 different functions:

def doubler(n):
    return n * 2

def tripler(n):
    return n * 3

def quadroupler(n):
    return n * 4

Instead of writing the code above, we could create a function that returns a lambda function with the functionality that we want:

def function_generator(n):
    return lambda a : a * n

Now we create our desired functions:

doubler = function_generator(2)
tripler = function_generator(3)
quadroupler = function_generator(4)

The function_generator function returns a function that will multiply its argument to whatever argument was passed to function_generator. We can test this with the following statement:

print(doubler(4), tripler(4), quadroupler(4)) # Output 8 12 16

function_generator = lambda n : lambda a : a * n

The previous test line should produce the same output as before.

Remember that a lambda function assigned to a variable makes the variable callable as a function. When introducing the topic, I gave the following example:

add = lambda a,b : a + b

This makes 'add' callable. So to add 2 numbers, we would use the following statement:

add(4, 6) # Returns 10

This also applies to functions returning lambdas. As long as a lambda function is returned, it is callable, no matter how deep the nesting goes. The function returned also has no name (hence 'anonymous') unless it is assigned to a variable.

We can also call a lambda function immediately after its definition:

(lambda x : x * 2)(4) # Returns 8

Make sure to store/print the value returned as it will not be accessible again later on in your module code. This format is very useful for list comprehensions. Suppose we have a list of numbers (nums) and we want to generate a new list of numbers such that for each number n in nums, n * 2 > 50 should return True. How can we achieve this?

Using a regular function and list comprehension:

def validate(n):
    return n * 2 > 50

nums = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
nums2 = [n for n in nums if validate(n)] # Returns [45, 245, 34]

However, we could eliminate the function definition altogether and include the validation expression within the list comprehension:

nums = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
nums2 = [n for n in nums if (lambda x : x * 2 > 50)(n)] # Returns [45, 245, 34]

Using Python lambda functions makes our code much more compact than in the previous example.

The post Python Lambda Functions appeared first on Kelvin Mwinuka.

If you enjoyed this article, consider following my website for early access to my content before it gets published here (don’t worry, it’s still free with no annoying pop-up ads!). Also, feel free to comment on this post. I’d love to hear your thoughts!

Python Higher-Order Functions

Kelvin Mwinuka — Sat, 02 Jan 2021 00:03:10 +0000

A higher-order function is one that either takes a function as an argument or returns a function (or both!). These functions help us achieve more complex tasks in our business logic that would be much more tedious with first-class functions.

Python allows us to define our own custom higher-order functions. In fact, I demonstrate this feature in my previous article on lambda functions in Python. I won't be covering that particular feature in this article. However, I will be covering 3 of the most useful higher-order functions that are built into Python:

Map
Reduce
Filter

These functions make dealing with iterable objects much simpler than using first-class functions or regular loops. For each function, I will explain what the function does, demonstrate how it works with a code example, and suggest possible applications for the function.

Map

The map function in Python allows us to produce a new iterable object from an original iterable object. It takes 2 arguments: a function and an iterable object. The map function applies the function passed to every member of the iterable and then produces a map object. This object can be cast to an iterable type of our choosing. The function passed to the map object does not have to return a value (I will demonstrate this later).

Implementation

For our example, let's generate a new list (L2) from an initial list (L1) such that each element of L2 is a double of its corresponding element in L1. Here is how we can achieve this with the map function:

def double(x):
    return x * 2

L1 = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]

L2 = list(map(double, L1))

print("Doubled Numbers: {}".format(L2)) 
# [6, 2, 8, 44, 90, 2, 490, 12, 68, 8, 16, 28]

The code above passes the double function(notice we leave out the parenthesis) and the original list (L1). A map object is returned and then cast to a list. Note, we can cast this map object to any type of iterable we want (list, tuple, set, ...).

The map function also works with lambda functions. To make the code above a little more compact, we can rewrite it as follows:

L1 = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
L2 = list(map( (lambda x : x * 2) , L1))
print(L2)

This would be a more desirable solution if your map function is rather simple and will not be needed elsewhere in the program. However, if you're running a complex operation on an iterable and/or plan to reuse the function outside of this context, it's best to stick to regular functions.

Remember I mentioned that the function does not actually have to return anything. If you want to map certain functionality to every member of an iterable but don't care for the resulting map object, the map function will simply return None for every corresponding member of the original iterable.

In fact, we don't even have to store the returned map object at all. If we have a list of people and we simply want to print out a greeting for each person on the list, we can use a map function:

def greet(person):
    print("Hello, {}!".format(person['name']))
people = [
    { 'name' : 'John Doe', 'age' : 20},
    { 'name' : 'Mike Will', 'age' : 10},
    { 'name' : 'Jane Hill', 'age' : 18},
    { 'name' : 'Alan Smith', 'age' : 16},
    { 'name' : 'Chimuka Chinene', 'age' : 18},
]
list(map(greet, people ))
""" Prints :
Hello, John Doe!
...
Hello, Chimuka Chinene!
"""

We have to cast the map object returned in order to actually get the function to execute on all the members. The list produced is just a list of None type objects as the mapper function did not return anything. If you assign that list to a variable and print it, the output would be: [None, None, None, None, None]

Uses

The most obvious use of a map function is in creating a hash table. A hash table is a data structure that associates a key with a hash that's generated using the key. The map function could be used to apply the hash function to a list of keys without the need for iteration.

The map function could also be used to replace loops. Instead of looping through every member of an iterable and executing some logic, we could map a function with that logic to the iterable. Remember, we don't have to return anything from the mapper function nor do we have to care for the resulting map object.

Reduce

A reduce function works similar to a map function in the sense that it accepts an iterable and a function to apply to all the members of an iterable. However, it differs from map as it returns ONE value instead of an iterable mapping to the original. It reduces an iterable down to one value. The reduce function also takes a third argument, the initial value that it starts the iteration with. If this value is not provided, the first element of the iterable will be used as the initial value. With every iteration, the function takes its current value, and the next member in the iterable and returns a value to be used for the next element.

Implementation

Let's calculate the sum of the doubles of all numbers in an array of integers L1. We could use a loop for this. However, a cleaner solution would be to use a reduce function as follows: Note in Python 3, reduce has been moved to functools so you will have to import it.

from functools import reduce
def addDoubles(a, b):
    return a + (b * 2)
L1 = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
doubleSum = reduce(addDoubles, L1, 0)
print(doubleSum) # 774

In the code above, the add function takes 2 parameters: the current sum(a) and the current element in the iterable(b) which is doubled. The total of the double and current sum is returned and carried forward into the next iteration until the end of the iterable. The reduce function also accepts lambda functions. We can simplify the code above as follows:

from functools import reduce
L1 = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
doubleSum = reduce( (lambda a,b : a + b * 2) , L1, 0)
print(doubleSum) # 774

This is a simple example, we can define a much more complex reducer function. We can also pick another initial value. For example, if I wanted my starting point to be 1000, I would write the code differently:

from functools import reduce
L1 = [3, 1, 4, 22, 45, 1, 245, 6, 34, 4, 8, 14]
sum = reduce( (lambda a,b : a + b * 2) , L1, 1000) # 1000 as initial value
print(sum) # 1774

Uses

The reduce function can be used anywhere that an iterable needs to be aggregated to one value. We can define the reducer function anyway we like.

Filter

The filter function is also similar to the map function. It accepts an iterable, and a function to execute on all the members of the iterable. However, it does come with some different rules:

A filter does not have to produce a 1 to 1 mapping between the new iterable and the original one like a map function does.
A filter creates a new list based on the elements that return True when the filter function is executed on them

Implementation

Given a list of 5 people, let's filter out all the people that are younger than 18.

def legal(person):
    return person['age'] >= 18
people = [
    { 'name' : 'John Doe', 'age' : 20},
    { 'name' : 'Mike Will', 'age' : 10},
    { 'name' : 'Jane Hill', 'age' : 18},
    { 'name' : 'Alan Smith', 'age' : 16},
    { 'name' : 'Chimuka Chinene', 'age' : 18},
]
legal_people = list(filter(legal, people))
print(legal_people)
""" Prints [{'name': 'John Doe', 'age': 20}, {'name': 'Jane Hill', 'age': 18}, #{'name': 'Chimuka Chinene', 'age': 18}] """

In the code above, we run the 'legal' function on each person. The function returns either True or False depending on the person's age. Only the people whose age returns True from the legal function make it into the new list. A filter object is returned. We can cast this to any iterable type we desire.

The filter function can also take a lambda function as an argument. We can write the code above as follows:

people = [
    { 'name' : 'John Doe', 'age' : 20},
    { 'name' : 'Mike Will', 'age' : 10},
    { 'name' : 'Jane Hill', 'age' : 18},
    { 'name' : 'Alan Smith', 'age' : 16},
    { 'name' : 'Chimuka Chinene', 'age' : 18},
]
legal_people = list(filter( (lambda person : person['age'] >= 18) , people))
print(legal_people)
""" Prints [{'name': 'John Doe', 'age': 20}, {'name': 'Jane Hill', 'age': 18}, #{'name': 'Chimuka Chinene', 'age': 18}] """

Uses

This one is pretty straight forward. We use the filter function in all instances where we want to filter out undesirable members of the original list. We can run this on very complex elements in an iterable and define complex filter functions to achieve whatever desired outcome we want. Just remember, the filter function has to return True or False.

Conclusion

Higher-order functions are an invaluable tool when writing programs, especially ones working on iterable objects. They are not necessary as their functionality can be achieved by regular for/while loops. However, they help a great deal in keeping our code neat and concise compared to regular loops. I hope I've provided a sufficient explanation on the functions above that will allow you to implement them in your projects. Happy coding!

The post Python Higher-Order Functions appeared first on Kelvin Mwinuka.

Testing React App With Jest & Puppeteer

Kelvin Mwinuka — Fri, 01 Jan 2021 23:51:26 +0000

So you've created your react application and now you have to write end-to-end tests in order to make sure your application works as expected from the end user's perspective. In this article, I will provide a simple step-by-step guide on how to achieve this using the Jest testing framework and the Puppeteer library.

This article will have the following structure:

Creating the app - The creation of a simple app that will be used in our testing demonstration.
Installing the packages - The installation of the packages we will need in order to achieve our goal.
Creating the custom environment - Class that encompasses the setup and teardown of tests.
Configuring Jest
Writing the tests
Considerations - Bonus tips that will help enhance test performance and developer experience

Before we continue, it's important to note that a react application created using create-react-app will come pre-packaged with Testing Library, which more or less allows us to achieve the same thing this article addresses. Here is a brilliant article that explains how to run tests using Jest and Testing Library.

So why puppeteer? Well, there are many reasons you might choose to go with puppeteer instead. Maybe there is some functionality that is unique to puppeteer that satisfies a very specific use case. For me, it's a matter of personal preference, I prefer the way Puppeteer handles interaction with the DOM.

1. Creating the app

First, let's create an application that will be our test subject. I've created a simple single-page application that contains a form and a table. The form will allow us to input some data that immediately gets displayed in the table upon submission. Here's how it looks:

This application is created using create-react-app. The application folder will be structured as shown below.



├── e2e
│   ├── custom-environment.js
│   ├── jest.config.js
│   └── tests
│       └── App.test.js
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── DevsTable.js
    ├── Form.js
    ├── index.js
    ├── serviceWorker.js
    └── setupTests.js

I've placed the e2e folder in the project root. This is where our puppeteer tests and Jest configurations will live. Other additional files are the DevsTable, and Form components.

In the form component, we accept the user input and pass it to the App component to update its state.



import React from 'react'

const Form = ({ add }) => {

    const handleSubmit = (event) => {
        event.preventDefault();
        let dev = new FormData(event.target)
        add({name: dev.get('name'), role: dev.get('role')})
        event.target.reset()
    }

    return (
        <form onSubmit={handleSubmit} id="devForm">
            <span>Name: </span>
            <input type="text" name="name" required/>
            <span>Role: </span>
            <input type="text" name="role"/><br/>
            <input class="submit" type="submit" value="Add Developer" required/>
        </form>
    )
}

export default Form

The DevsTable component displays a table and maps each object in the devs prop to a row in the table.



import React from 'react';

const DevsTable = (props) => {
    return (
        <table>
            <thead>
                <tr>
                    <th>Name</th>
                    <th>Role</th>
                </tr>
            </thead>
            <tbody>
                {
                    props.devs.map((dev, index) => {
                        return (
                            <tr key={index}>
                                <td id={`name${index}`}>{dev.name}</td>
                                <td id={`role${index}`}>{dev.role}</td>
                            </tr>
                        )
                    })
                }
            </tbody>
        </table>
    )
}

export default DevsTable

Here's the App component's code:



import React, { useState, useCallback } from 'react';
import './App.css';
import Form from './Form';
import DevsTable from './DevsTable'

const App = () => {

  const [devs, setDevs] = useState([]); 

  const addDeveloper = useCallback((dev) => {
    setDevs(devs => [...devs, dev])
  }, [setDevs])

  return (
    <div className="App">
      <DevsTable devs={devs} />
      <Form add={addDeveloper} />
    </div>
  );
}

export default App;

Finally, the styling in App.css:



.App {
  text-align: left;
  font-family: Arial, Helvetica, sans-serif;
}

table {
  width: 50%;
  margin: 50px;
  border: 1px solid black;
  border-collapse: collapse;
}

th, td {
  padding: 10px;
  border: 1px solid black;
}

th {
  color: white;
  background-color: teal;
}

form {
  margin: 50px;
}

input {
  margin-left: 5px;
  margin-right: 50px;
  margin-bottom: 20px;
}

.submit {
  padding: 10px;
  color: white;
  background-color: teal;
  border-width: 0px;
  border-radius: 5px;
  margin-left: 0px;
}

I usually delete the index.css file and its import statement in index.js. I prefer to have the top-level CSS in App.css.

2. Installing the packages

Before we can start writing the tests, we need to make sure we have the right packages. The first will be the Jest testing framework. When using create-react-app, Jest comes pre-packaged in order to run the default test script. However, we will not be able to use this in the terminal when running our own custom test scripts.

To solve this, we need to add Jest to our devDependencies. If you don't already have devDependencies in your package.json, add it at the top level. Next, navigate to your node_modules folder and look for the Jest module. Open that module's package.json and check the version of Jest that's been pre-packaged by create-react-app.

We want to use the same version of jest in our devDependencies to avoid clashes. Inside devDependencies, add Jest and set the version to the same version installed with create-react-app.

Your devDependencies section should look something like this:



"devDependencies": {
    "jest": "24.9.0"
}

Now run npm install.

We are going to need 2 more packages for our testing: jest-environment-node and Puppeteer.

jest-environment-node allows us to create a custom environment in which to run our tests(I will explain this in more detail later in the article). Puppeteer is the testing library that provides a high-level API for controlling chromium. At the time of writing, puppeteer only offers chromium support.

We only need these in our dev environment so we will install them with the following command:



npm install jest-environment-node puppeteer --save-dev

Once the installation is done, our devDependencies section should look like this:



"devDependencies": {
    "jest": "24.9.0",
    "jest-environment-node": "^26.0.1",
    "puppeteer": "^4.0.0"
}

3. Creating the custom test environment

Jest runs tests in environments. The default environment used by Jest is a browser-like environment through jsdom. The environment is created for each test suite. We want to create a custom environment so we can control the test suites' setup and teardown.

Why is this important? We could just create the browser and page objects in beforeAll and then close them in afterAll, right?

While this would work, it's not the most efficient solution if we have multiple test suites that use puppeteer. This would lead to typing the same setup and teardown logic multiple times.

Instead, we will create one custom environment, set up and tear down the tests here and then use that custom environment for all our tests.

Here's how we set up the custom environment:



var NodeEnvironemnt = require('jest-environment-node')
var puppeteer = require('puppeteer')

class CustomEnvironment extends NodeEnvironemnt {
    constructor(config, context){
        super(config, context)
    }

    async setup(){
        await super.setup()
        this.global.browser = await puppeteer.launch({
            headless: false,
            slowMo: 100
        })
        this.global.page = await this.global.browser.newPage()
        await this.global.page.goto('http://localhost:3000/', {waitUntil: 'load'})
    }

    async teardown(){
        await this.global.browser.close()
        await super.teardown()
    }
}

module.exports = CustomEnvironment

In the custom environment, we have access to this.global. This is where you put data that needs to be accessible in the tests.

We set up our browser and page objects in the setup method. This method runs before the test suite is executed. The teardown method runs after all the tests in a suite are complete so its where we close the browser.

Configuring Jest Next, we have to configure Jest. We can do this directly in the project's package.json with a "jest" object, but I prefer using a config file. Let's navigate to the jest.config.js inside the e2e folder and add the following code:



module.exports = {
    testEnvironment: './custom-environment.js',
    testTimeout: 60000
}

The testEnvironment option allows us to set a custom environment to be used instead of the default environment. Let's point it to the custom environment we defined earlier.

The testTimeout option allows us to set the amount of time a test has to run before Jest times out and aborts it. The default is 5 seconds. This is quite short for end-to-end tests as launching the browser and loading pages alone can take a few seconds. I've set it to 1 minute here but feel free to adjust this according to your needs.

However, it's important to set a timeout that's not too long either. One of the criteria to test for is performance. It's not beneficial to simply adjust your tests to tolerate extremely slow loading times as that's a sign that your application can be optimised.

Next, we have to create a command to run our tests. In the scripts section inside the package.json, let's add the following line:



"test:e2e": "jest -c e2e/jest.config.js"

This sets the Jest terminal command that will be run. We also set the configuration file here. Now, all we have to do to run the tests is use the "npm run test:e2e" command in the terminal.

5. Writing the tests

Finally, we can write the tests! Let's navigate to e2e/tests/App.test.js and define the test suite. Inside the test suite, we're exposed to the global object which contains the browser and page objects we created in the custom environment.

Here, I've written a simple test that fills the form 3 times with 3 sets of data, and then iterates through the table rows to check if the data is being displayed as expected.



describe('App tests',() => {

  let page = global.page

  test('Loads all elements', async () => {

    const testData = [
      { name: 'Kelvin Mwinuka', role: 'Front-end developer' },
      { name: 'James Mitchel', role: 'Back-end developer' },
      { name: 'Michael Scott', role: 'DevOps' }
    ]

    await page.waitForFunction('document.getElementById("devForm")')

    // Input all the data
    for(let i = 0; i < testData.length; i++){
      await page.type("input[name='name']", testData[i].name)
      await page.type("input[name='role']", testData[i].role)
      await page.click("input[type='submit']")
    }

    // Check if all the data is represented in the table
    for(let i = 0; i < testData.length; i++){
      expect(await page.$eval(`#name${i}`, element => element.innerText))
      .toEqual(testData[i].name)
      expect(await page.$eval(`#role${i}`, element => element.innerText))
      .toEqual(testData[i].role)
    }
  });
})

6. Considerations

There are several improvements we can make for a better testing experience.

1. Dev server

At the moment, we need the application to already be running before we can run our tests. We can improve this by employing the help of jest-dev-server. First let's install it in our devDependencies:



npm install jest-dev-server --save-dev

Now let's create a global-setup.js file in our e2e folder with the following contents:



const { setup: setupDevServer } = require("jest-dev-server")

module.exports = async () => {
    await setupDevServer({
        command: 'npm run start --port 3000',
        launchTimeout: 30000,
        debug: true,
        port: 3000
    })
}

This file starts the server upon setting up our test. Next, let's create a global-teardown.js file in the same directory with the following content:



const { teardown: teardownDevServer } = require("jest-dev-server")

module.exports = async () => {
    await teardownDevServer()
}

This will shutdown the dev server once the tests have finished executing. In order for jest to run these setup and teardown functions, we must update the jest.config.js file to this:



module.exports = {
    testEnvironment: './custom-environment.js',
    testTimeout: 60000,
    globalSetup: './global-setup.js',
    globalTeardown: './global-teardown.js'
}

It's important to note that the setup and teardown methods in custom environment run once before and after EACH test suite respectively. The globalSetup and globalTeardown function run before and after ALL tests suites respectively.

Also note that the global variables set in globalSetup can only be accessed in globalTeardown and cannot be accessed inside the test suites unlike the global variables set in the custom environment.

2. Tests with login

If you have multiple test suites which create user sessions, you'll want to make sure they are queued to run consecutively. By default, Jest will run test suites concurrently.

The issue arises when one suite logs in and essentially kicks another suite out of its session. To prevent this, limit the max workers to 1 in the jest command by updating the script in package.json to the following:



"test:e2e": "jest -c e2e/jest.config.js --maxWorkers=1"

This will make sure only one test suite is run at a time. Do note that this will increase the total execution time.

3. Mocking requests

If you want to avoid the above problem entirely, it's advisable to mock requests in your tests. This has multiple advantages including but not limited to:

Reducing test execution time as no real network calls are made
Having full control over responses when testing for various response scenarios
Not being at the mercy of the back-end server when running tests

Here's a library that provides puppeteer request mocking functionality along with concise documentation.

The post Testing React App With Jest & Puppeteer appeared first on Kelvin Mwinuka.

Setting Up Redux in React

Kelvin Mwinuka — Fri, 01 Jan 2021 23:31:26 +0000

Setting up redux in your react application can be confusing, but it doesn't have to be. In this article, I walk you through the entire process of setting up and connecting redux to your react application along with a practical application example.

This article is divided into the following sections:

Creating the application - building our example application.

Installing the packages

Action creators - A brief explanation and example of action creators.

Reducer - A brief explanation and example of a reducer.

Connecting the app - Connecting the application to the redux store.

Dispatching actions

Enhancement with redux-thunk - Enhancing the development experience by applying redux-thunk middleware

I'd recommend that you follow along from the beginning as we use an app example, but feel free to skip ahead to a particular section if you feel comfortable with certain concepts discussed here.

1. Creating the application

In this example, we will create a simple application that displays a user's profile containing a name, bio and 2 lists: one for programming languages and one for frameworks.

Let's create the app using create-react-app:

npx create-react-app <app_name>

Let's add an image in the public folder to be used as the profile picture(optional) and create a component file in /src named TechList.js.

Our folder structure should look like this:

.
├── README.md
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   ├── pro.jpg
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── App.test.js
    ├── TechList.js
    ├── index.js
    ├── logo.svg
    ├── serviceWorker.js
    └── setupTests.js

Let's define the App component:

import React from 'react';
import TechList from './TechList'
import './App.css';

const App = () => {
  return (
    <div className="App">
      <div className="media">
        <img className="align-self-start mr-3 profile-pic" src="pro.jpg" alt="Profile" />
        <div className="media-body">
          <h5 className="mt-0">{/** Bio will go here */}</h5>
          <p>{/** Bio will go here */}</p>
          <div className="container tech-container">
            <div className="row">
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                  items={[]}
                />
              </div>
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                  items={[]}
                />
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  );
}
export default App;

Now let's define the TechList component, a reusable component that will display both the languages and frameworks lists:

import React from 'react'

const TechList = ({
    items,
}) => {

    const handleFormubmit = (event) => {
        event.preventDefault()
        event.target.reset()
    }
    return (
        <ul className="list-group">
            {
                items.map( (item, index) => {
                    return <li key={index} className="list-group-item">{item}</li>
                })
            }
            <li className="list-group-item">
                <form onSubmit={handleFormubmit}>
                    <div className="form-row">
                        <div className="col">
                            <input type="text" className="form-control add-tech-text" placeholder="Type new" name="entry" required/>
                        </div>
                        <div className="col">
                            <button type="submit" className="btn btn-primary">Add to list</button>
                        </div>
                    </div>
                </form>
            </li>
        </ul>
    )
}

export default TechList

This component receives an items prop which is an array containing the languages/frameworks that will be displayed in the list. At the moment, we're passing an empty array from the App component so this will not display anything.

It also contains a form appended at the end of the list that allows us to enter some text to be appended to the list dynamically. We will add functionality to this later.

Next, let's set up a redux folder inside /src that will contain our action creators and reducer. Inside the folder, we'll have actions.js and reducer.js. The folder structure should now look like this:

.
├── README.md
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   ├── pro.jpg
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── App.test.js
    ├── TechList.js
    ├── index.js
    ├── logo.svg
    ├── redux
    │   ├── actions.js
    │   └── reducer.js
    ├── serviceWorker.js
    └── setupTests.js

2. Installing the packages

We will need to install the necessary packages with the following command:

npm install redux react-redux redux-thunk axios

3. Action creators

Our action creators will be located inside the actions.js file. We will have 2 action creators for now: one that creates an action that sends data to add a programming language to the store, and one that sends data to add a framework.

Our code in actions.js will look like this:

export const addLanguange = (language) => {
    return {
        type: 'ADD_LANGUAGE',
        payload: language
    }
}

export const addFramework = (framework) => {
    return {
        type: 'ADD_FRAMEWORK',
        payload: framework
    }
}

<!-- wp:heading {"level":3} -->
<h3 id="reducer">4. Reducer</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Our reducer.js file will contain our reducer:</p>
<!-- /wp:paragraph -->

const initial_state = {
    profile: {
        name: 'Kelvin Clement Mwinuka',
        bio: 'I am a software developer with a BS in Computer Science from The University of Nottingham. I’m passionate about web technologies. On my free time, I like blogging and challenging myself physically.',
        languages: [
            'JavaScript', 'Python', 'HTML', 'CSS'
        ],
        frameworks: [
            'React', 'Express', 'Flask', 'Django'
        ]
    },
}

const rootReducer = (state = initial_state, action) => {
    switch (action.type) {
        case 'ADD_LANGUAGE':
            return {
                ...state, 
                profile: {
                    ...state.profile,
                    languages: [...state.profile.languages, action.payload]
                }
            }
        case 'ADD_FRAMEWORK':
            return {
                ...state, 
                profile: {
                    ...state.profile,
                    frameworks: [...state.profile.frameworks, action.payload]
                }
            }
        default:
            return state
    }
}

export default rootReducer

In this example, I've set up an initial state with some pre-loaded values. When an action is dispatched, the reducer will figure out which part of the state to append data.

Keep the reducer pure by not having any other logic besides returning the new state. We also should not directly mutate the state.

5. Connecting the app

Now that we have our action creators and reducer, it's time to connect our application to redux so we can actually use them.

Let's open the index.js file and make the following changes:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import * as serviceWorker from './serviceWorker';
import { createStore, applyMiddleware } from 'redux'
import { Provider } from 'react-redux'
import thunk from 'redux-thunk'
import rootReducer from './redux/reducer'

const store = createStore(
  rootReducer,
  applyMiddleware(thunk)
)

ReactDOM.render(
  <React.StrictMode>
    <Provider store={store}>
      <App />
    </Provider>
  </React.StrictMode>,
  document.getElementById('root')
);

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

First, we import createStore and applyMiddleware. createStore is exactly what it sounds like: it allows us to create the store that will hold our data. applyMiddleware allows us to extend the functionality of redux by adding packages called middleware.

Next, we import the Provider component from react-redux that will wrap our App component.

Our third import is a middleware package called redux-thunk, I will get into more detail about this in section 7 (Enhancement with redux-thunk).

The final import is our reducer. We only have one to import here. However, if you have multiple reducers, you could merge them into one giant reducer using combineReducer from the redux package.

Now we can create our store using createStore and pass in our reducer, and then applying the middleware.

If you wish to stop here or if this simple setup is sufficient, you do not have to use applyMiddleware at all. You could just pass the reducer and call it a day. I've added the middleware here in order to set up for the redux-thunk section.

Now lets go into our App component in App.js and make the following changes:

import React from 'react';
import TechList from './TechList'
import { bindActionCreators } from 'redux'
import { addLanguange, addFramework } from './redux/actions'
import { connect } from 'react-redux'
import './App.css';

const App = ({
  profile,
  action
}) => {
  return (
    <div className="App">
      <div className="media">
        <img className="align-self-start mr-3 profile-pic" src="pro.jpg" alt="Profile" />
        <div className="media-body">
          <h5 className="mt-0">{profile.name}</h5>
          <p>{profile.bio}</p>
          <div className="container tech-container">
            <div className="row">
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                  items={profile.languages}
                  action={actions.addLanguange}
                />
              </div>
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                 items={profile.languages}
                  action={actions.addFrameworks}
                />
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  );
}

function mapStateToProps (state) {
  return {
    profile: state.profile
  }
}

function mapDispatchToProps (dispatch) {
  return {
    actions: bindActionCreators({ 
      addLanguange,
      addFramework 
    }, dispatch)
  }
}

export default connect(mapStateToProps, mapDispatchToProps)(App);

First, we import bindActionCreators from redux which allows us to combine all our action creators into one object with corresponding keys.

This is not necessary but I find this to be a clean way of dealing with action creators especially as the project grows and necessitates the usage of more of action creators.

Next we import our action creators themselves from actions.js.

Finally, we import connect from 'react-redux'. This allows us to connect a particular component to our store. We will have this only on the App component and pass down any action creators or data as props.

If you have a large project, you could use this method on multiple components especially if you want to make sure you're only subscribing to certain parts of the state rather than the entire store.

We've added a mapStateToProps function:

function mapStateToProps (state) {
  return {
    profile: state.profile
  }
}

This takes the state contained in our redux store as a parameter and returns an object that can be considered a subset of the state. The object in question will be passed to the current component via its props.

Right now, we are subscribing to the 'profile' object in the state. Meaning the component will only re-render if this section of the state changes.

This is one of the strengths of redux. The component does not have to re-render if the portion of the state it subscribes to has not changed. Even if the state has changed elsewhere.

If we end up expanding our state in reducer.js and add another section other than 'profile', the App component and subsequently, its children, will not re-render if the new portion of the state changes.

We've also added another function:

function mapDispatchToProps (dispatch) {
  return {
    actions: bindActionCreators({ 
      addLanguange,
      addFramework 
    }, dispatch)
  }
}

This function enables us to fire our action creators within the app component and its children provided they are passed down.

We make the following update on both instances of the TechList component:

              ...
               {/** Programming lanugages list */}
               <TechList 
                  items={profile.languages}
                  action={actions.addLanguange}
                />
              ...
                {/** Programming lanugages list */}
                <TechList 
                 items={profile.languages}
                  action={actions.addFrameworks}
                />

We pass the relevant items list and action creator to each of the instances.

6. Dispatching actions

Now that we've connected the application to the redux store, let's dispatch the actions.

The actions in question add a programming language and a framework to the state's languages and framework lists respectively. In order to make this possible, we'll update the TechList component to the following:

import React from 'react'

const TechList = ({
    items,
    action
}) => {

    const handleFormubmit = (event) => {
        event.preventDefault()
        action(event.target.entry.value)
        event.target.reset()
    }
    return (
        <ul className="list-group">
            {
                items.map( (item, index) => {
                    return <li key={index} className="list-group-item">{item}</li>
                })
            }
            <li className="list-group-item">
                <form onSubmit={handleFormubmit}>
                    <div className="form-row">
                        <div className="col">
                            <input type="text" className="form-control add-tech-text" placeholder="Type new" name="entry" required/>
                        </div>
                        <div className="col">
                            <button type="submit" className="btn btn-primary">Add to list</button>
                        </div>
                    </div>
                </form>
            </li>
        </ul>
    )
}

export default TechList

This component takes an items props which it loops through and displays in a list as described before. The second prop is an actions prop. This will contain an action creator that will be invoked and passed the data grabbed from the form submission.

This component is action creator agnostic, even though it is the one invoking the action creator. So it's important to pass the correct action creator down from the parent component.

Congratulations! you've connected your app to redux. Now you can add new items to each of the lists.

Next, we'll take a look at how to enhance this app. At the moment, action creators can only return an action object. This is great if we already have the data we want to return.

What about a situation where we need to retrieve data from a server through an API call? We can't do this in the reducer as it needs to be pure. The action creator is the place to do this. We need a way to add this logic here. This is where redux-thunk comes in.

7. Enhancement with redux-thunk

To understand redux-thunk, we first need to understand what a thunk is. A thunk is a function that delays the execution of some code until the exact moment the result of that execution is needed. In our case, that code is dispatching an action.

Why is this important? At the moment, we have to dispatch an action that consists of the type and the payload. This requires that we already have the payload data beforehand.

What if we don't have that data? What if we need to retrieve that data from a server before we display it? This is what a thunk is useful for. In this case, instead of dispatching an action directly, we want to make a request to the server and then dispatch an action with the data from the response.

Our action creators need to return a function that has this logic and then returns an action at the end of its execution. This is the thunk.

In order to enable thunks in redux, we need to apply the redux-thunk middleware, which we have already done.

First, let's write. a simple Node server that listens on port 8000 for requests. This server has a '/profile' GET endpoint which returns the user's profile details, a '/languages' POST endpoint that adds to the user's list of languages, and a '/frameworks' POST endpoint that adds to the user's list of frameworks.

Each endpoint returns the latest user object as a JSON response.

var bodyParser = require('body-parser')
var cors = require('cors')
var app = require('express')()

const port = 8000

var profile = {
    name: 'Kelvin Mwinuka',
    bio: 'I am a software developer with a BS in Computer Science from The University of Nottingham. I’m passionate about web technologies. On my free time, I like blogging and challenging myself physically.',
    languages: [],
    frameworks: []
}

app.use(cors())
app.use(bodyParser.json())

app.post('/languages', (req, res) => {
    let language = req.body.language
    if (!profile.languages.map( l => l.toLowerCase()).includes(language.toLowerCase())) {
        profile.languages.push(language)
    }
    res.json(profile)
});

app.post('/frameworks', (req, res) => {
    let framework = req.body.framework
    if (!profile.frameworks.map( f => f.toLowerCase()).includes(framework.toLowerCase())) {
        profile.frameworks.push(framework)
    }
    res.json(profile)
});

app.get('/profile', (req, res) => {
    res.json(profile)
});

http.listen(port, () => {
    console.log(`Server started at port ${port}`)
});

Let's make the necessary changes in actions.js to enable the desired behaviour:

import axios from 'axios'

export const setProfileData = (profile) => {
    return {
        type: 'SET_PROFILE_DATA',
        payload: profile
    }
}

export const loadProfile = () => {
    return async (dispatch) => {
        let res = await axios.get('http://localhost:8000/profile')
        let profile = res.data
        dispatch(setProfileData(profile))
    }
}

export const addLanguange = (language) => {
    return async (dispatch) => {
        let res = await axios.post('http://localhost:8000/languages', { 
            language: language 
        })
        let profile = res.data
        dispatch(setProfileData(profile))
    }
}

export const addFramework = (framework) => {
    return async (dispatch) => {
        let res = await axios.post('http://localhost:8000/frameworks', { 
            framework: framework 
        })
        let profile = res.data
        dispatch(setProfileData(profile))
    }
}

The first change we've made is the addition of a 'setProfileData' action creator that behaves like a regular action creator (no thunk) to set the profile data if we already have it.

Notice what we've done with the 'addLanguage' and 'addFramework' action creators? Instead of returning a raw action object, we instead return an async function that takes dispatch as a parameter.

This function executes whatever logic is needed first, and only then will it dispatch an action. This is what a thunk is. A thunk can also be used for conditional dispatches but that is outside the scope of this article.

We've also added another action creator called 'loadProfile' that is explicitly responsible for retrieving the user profile from the server. It behaves similar to the 'addLanguage' and 'addFramework' action creators.

Another important thing to note is that these 3 action creators now pass the 'setProfileData' action creator to the dispatch function. We can do this because that action creator returns a raw action. Therefore, it's equivalent to passing the action object directly to dispatch. I take this approach in order to avoid typing the same action object multiple times.

In the reducer, let's add one more case for setting the user profile. The data is no longer hardcoded in the initial state and will instead be set by dispatching an action after retrieving it from the server.

const initial_state = {
    profile: {
        name: '',
        bio: '',
        languages: [],
        frameworks: []
    },
}

const rootReducer = (state = initial_state, action) => {
    switch (action.type) {

        case 'SET_PROFILE_DATA':
            return {...state, profile: action.payload}

        case 'ADD_LANGUAGE':
            return {
                ...state, 
                profile: {
                    ...state.profile,
                    languages: [...state.profile.languages, action.payload]
                }
            }
        case 'ADD_FRAMEWORK':
            return {
                ...state, 
                profile: {
                    ...state.profile,
                    frameworks: [...state.profile.frameworks, action.payload]
                }
            }
        default:
            return state
    }
}

export default rootReducer

In the app section, let's import our new 'loadProfile' action creator and then invoke it right at the top of our app component in order to trigger the user profile retrieval from the server.

import React from 'react';
import TechList from './TechList'
import { bindActionCreators } from 'redux'
import { addLanguange, addFramework, loadProfile } from './redux/actions'
import { connect } from 'react-redux'
import './App.css';

const App = ({
  profile,
  actions
}) => {

  actions.loadProfile()

  return (
    <div className="App">
      <div className="media">
        <img className="align-self-start mr-3 profile-pic" src="pro.jpg" alt="Profile" />
        <div className="media-body">
          <h5 className="mt-0">{profile.name}</h5>
          <p>{profile.bio}</p>
          <div className="container tech-container">
            <div className="row">
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                  items={profile.languages}
                  action={actions.addLanguange}
                />
              </div>
              <div className="col-sm">
                {/** Programming lanugages list */}
                <TechList 
                  items={profile.frameworks}
                  action={actions.addFramework}
                />
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  );
}

function mapStateToProps (state) {
  return {
    profile: state.profile
  }
}

function mapDispatchToProps (dispatch) {
  return {
    actions: bindActionCreators({ 
      loadProfile,
      addLanguange,
      addFramework
    }, dispatch)
  }
}

export default connect(mapStateToProps, mapDispatchToProps)(App);

That's it! run the app and you'll notice that we've retained all the functionality we had before from the user's perspective, but we can now create smarter action creators that allow us to accomplish more with redux.

The post Setting Up Redux in React appeared first on Kelvin Mwinuka.

How To Set Up Cronjobs on MacOS

Kelvin Mwinuka — Fri, 01 Jan 2021 23:12:09 +0000

Cron is a software utility that allows us to schedule tasks (cronjobs) to run periodically, at fixed times or at pre-determined intervals.

These tasks can serve any desired function. Some common applications include periodically backing up user data or calling an API endpoint.

In this article, I'm going to cover the basics of setting up and running cronjobs. Although I use a macOS (Mojave) system, the examples should work on Linux systems, provided all the necessary dependencies are installed.

If you are on a linux system, this article will assume you already have all the dependencies installed.

Displaying cronjobs

In order to display current crobjobs, open the terminal and enter the following command:

crontab -l

If you've never done this before, the output should be empty. Let's change this by actually creating a shell script that will contain the job to be executed periodically.

Creating cronjobs

Now let's create a cronjob. To keep this simple, we will create a simple bash script that prints "Hello, world!" to a file. Create a bash script in the directory of your choice with the following code:

#!/bin/bash

echo "Hello, world" >> ~/Desktop/job.txt

Save this script as 'job.sh' and open a terminal window in the script's directory. Run the script by with the following command:

bash job.sh

A new file named 'job.txt' should have appeared in the directory with the expected output. Run the file several times and you should notice the script append to the file.

Running this manually every single time doesn't seem practical. So let's use cron to make this process run automatically at a certain intervals.

Executing cronjob

Before we can get cron to execute this bash script in the background, we first have to make sure the script is executable. We can achieve this with the following command:

chmod +x job.sh

Make sure you run this command in the same directory as the script. If not, make sure you specify the path of the script.

Now, we can add the job to the crontab. Using the following command:

crontab -e

This gets us into crontab's edit mode. If your default editor is Vi, press 'i' in order to enter insert mode. Now type the following line:

* * * * * ~/Desktop/job.sh

The second part of this command "~/Desktop/job.sh" is the path to the shell script we'd like to execute. In my case, this resides in the desktop folder. Be sure to specify the exact path your script is in.

Notice the "* * * * *" at the beginning of the statement. This is the actual schedule condition for the job's execution.

Each position, from left to right, represents minutes, hours, day of the month, month and day of the week respectively. An asterisk(*) simply means "every". So, in this case, we are executing this job every minute of every hour of every day of the month, every month and every day of the week.

Here's an excellent article with and in-depth explanation on formatting crontab commands.

For now, let's save this by pressing the escape key and then typing ":wq" in order to save and quit.

You should notice the file getting appended to every minute now. Great the cronjob works!

Conclusion

This was by no means an in-depth look at cronjobs and their power. However, I do think it serves as a sufficient starting guide on setting them up. In a future article, I will demonstrate how to execute python scripts while keeping track of terminal output.

The post How To Set Up Cronjobs on MacOS appeared first on Kelvin Mwinuka.