
## Introduction

In modern web development, building complex applications requires efficient and seamless communication between components. One of the challenges developers often face is managing and sharing state across multiple components without introducing unnecessary complexity or tight coupling. This is where **React Context** comes to the rescue. It is one of React's core concepts, which allows data to be passed down the component tree without explicitly passing props through each intermediate component.

While React's built-in context management offers a way to share data globally within the application, combining it with **custom hooks** provides a more elegant and efficient solution for loading and managing context data, enabling developers to build more easily maintainable and scalable applications.

## Understanding React Context

Before delving into custom hooks, let's recap what context is in React. React context is a tool for sharing data, such as theme preferences, user authentication data, or any kind of state, across an entire component tree without having to explicitly pass those values through each component's props.
This is particularly useful for scenarios where multiple components at different levels in the component tree need access to the same data.

### Creating a Context

To start using React context, you need to create a context using the `React.createContext()`. This function returns an object containing two components: `Provider` and `Consumer`.
For example, let's create a context to store the count of fruit available in a smoothie shop:

```jsx
// Creating a context
export const FruitContext = React.createContext();
```

We can use the `Provider` component to distribute the data from the context to the components, responsible for presenting the data (aka view components).

Since we want to be able to work with the data in the context thorugh the app, we can set the data as state inside the `Provider` and define some callback functions, which will be used to update the state.

For example, consider we have two types of fruit - bananas and apples. The quantity of each fruit will be loaded from the backend with an API call - `getBananasCount()`, `getApplesCount()`.

```jsx
// Creating a context provider component
export function FruitContextProvider({ children }) {
  const [bananasCount, setBananasCount] = React.useState(0);
  const [applesCount, setApplesCount] = React.useState(0);

  const [isLoading, setIsLoading] = React.useState(true);

  const getBananasCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/bananas")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setBananasCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching bananas.", e))
      .finally(() => setIsLoading(false));
  }, [setBananasCount, setIsLoading]);

  const getApplesCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/apples")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setApplesCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching apples.", e))
      .finally(() => setIsLoading(false));
  }, [setApplesCount, setIsLoading]);

  // Load the supplies from server
  useEffect(() => {
    console.log("loading supplies from server ...");
    getApplesCount();
    getBananasCount();
  }, [getApplesCount, getBananasCount]);

  // all data and methods you want to use outside of the context
  const exposedData = {
    isLoading,
    bananasCount,
    applesCount,
  };

  return (
    <FruitContext.Provider value={exposedData}>
      {children}
    </FruitContext.Provider>
  );
}
```

To consume the context in a component, ensure it's wrapped with the relevant context provider.

In our example, we would like to access the context inside the `<SupplyDisplay/>` and `<SmoothieMaker/>` components, so all that matters to us is that these are wrapped by the `FruitContextProvider` in `App.js`.

In larger applications, however, you should be mindful where you place the `Provider` in order to avoid wrapping components which do not use the context in question. In such cases, make sure you place the provider **closer to the components, where the context will be consumed**.

```jsx
// App.js

import React from "react";
import { FruitContextProvider } from "./context/FruitContext";
import SupplyDisplay from "./components/SupplyDisplay";
import SmoothieMaker from "./components/SmoothieMaker";

function App() {
  return (
    <div
      className="App"
      style={{
        width: "60%",
        margin: "auto",
        marginTop: "3%",
        padding: "3%",
        boxShadow: "rgba(0, 0, 0, 0.16) 0px 1px 4px",
      }}
    >
      <header className="smoothie-shop">
        <h1 style={{ fontFamily: "Montserat", color: "green" }}>
          Smoothie Shop
        </h1>
        <FruitContextProvider>
          <SupplyDisplay />
          <SmoothieMaker />
        </FruitContextProvider>
      </header>
    </div>
  );
}

export default App;
```

Having setup the context provider, let's introduce some more functionality. We'll check if there are enough bananas and apples for a smoothie using the `canMakeSmoothie` state variable and `checkIfCanMakeSmoothie` method.

Assume that we need 3 bananas and 2 apples for a smoothie. The updated fruit context provider will look like this:

```jsx
// Creating a context provider component
export function FruitContextProvider({ children }) {
  const [bananasCount, setBananasCount] = React.useState(0);
  const [applesCount, setApplesCount] = React.useState(0);
  const [canMakeSmoothie, setCanMakeSmoothie] = React.useState(false);

  const [isLoading, setIsLoading] = React.useState(true);

  const getBananasCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/bananas")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setBananasCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching bananas.", e))
      .finally(() => setIsLoading(false));
  }, [setBananasCount, setIsLoading]);

  const getApplesCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/apples")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setApplesCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching apples.", e))
      .finally(() => setIsLoading(false));
  }, [setApplesCount, setIsLoading]);

  const checkIfCanMakeSmoothie = useCallback(() => {
    // refresh supplies count
    getBananasCount();
    getApplesCount();

    // assume that for a smoothie we need 3 bananas and 2 apples
    if (bananasCount >= 3 && applesCount >= 2) {
      setCanMakeSmoothie(true);
    } else {
      setCanMakeSmoothie(false);
    }
  }, [
    bananasCount,
    applesCount,
    setCanMakeSmoothie,
    getApplesCount,
    getBananasCount,
  ]);

  // Load the supplies from server & check if a smoothie can be made
  useEffect(() => {
    console.log("loading supplies from server ...");
    checkIfCanMakeSmoothie();
  }, [checkIfCanMakeSmoothie]);

  // all data and methods you want to use outside of the context
  const exposedData = {
    isLoading,
    errorMsg,
    bananasCount,
    applesCount,
    canMakeSmoothie,
  };

  return (
    <FruitContext.Provider value={exposedData}>
      {children}
    </FruitContext.Provider>
  );
}
```

Furthermore, we would like to add a button "Make smoothie", which will update the quantity of each fruit accordingly. The button will only be visible if there is enough fruit for a smoothie (i.e. at least 3 bananas and 2 apples).
Alternatively, the user will see a message that there aren't enough supplies.

The function which will be executed `onClick` of the "Make smoothie" button will also be defined in the context provider.
With this, the final version of our `/src/context/FruitContext.js` is:

```jsx
import React, { useCallback, useEffect } from "react";
import axios from "axios";

// Creating a context
export const FruitContext = React.createContext();

// Creating a context provider component
export function FruitContextProvider({ children }) {
  const [bananasCount, setBananasCount] = React.useState(0);
  const [applesCount, setApplesCount] = React.useState(0);
  const [canMakeSmoothie, setCanMakeSmoothie] = React.useState(false);

  const [isLoading, setIsLoading] = React.useState(true);
  const [errorMsg, setErrorMsg] = React.useState("");

  const getBananasCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/bananas")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setBananasCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching bananas.", e))
      .finally(() => setIsLoading(false));
  }, [setBananasCount, setIsLoading]);

  const getApplesCount = useCallback(() => {
    setIsLoading(true);
    axios
      .get("http://localhost:3000/apples")
      .then((res) => {
        const countAsNum = Number(res.data.count);
        setApplesCount(countAsNum);
      })
      .catch((e) => console.log("Error fetching apples.", e))
      .finally(() => setIsLoading(false));
  }, [setApplesCount, setIsLoading]);

  const checkIfCanMakeSmoothie = useCallback(() => {
    // refresh supplies count
    getBananasCount();
    getApplesCount();

    // assume that for a smoothie we need 3 bananas and 2 apples
    if (bananasCount >= 3 && applesCount >= 2) {
      setCanMakeSmoothie(true);
    } else {
      setCanMakeSmoothie(false);
    }
  }, [
    bananasCount,
    applesCount,
    setCanMakeSmoothie,
    getApplesCount,
    getBananasCount,
  ]);

  const makeSmoothie = useCallback(() => {
    if (!canMakeSmoothie) {
      setErrorMsg("Oh oh! Unsufficient supplies!");
      return;
    }

    // Update bananas count
    const updatedBananasCount = bananasCount - 3;
    axios
      .put("http://localhost:3000/bananas", {
        count: updatedBananasCount,
      })
      .then((res) => {
        if (res.ok) {
          setBananasCount(updatedBananasCount);
        }
      })
      .catch((e) => {
        console.log("Error updating bananas count.", e);
        setErrorMsg("Failed to update apples count.");
      });

    // Update apples count
    const updatedApplesCount = applesCount - 2;
    axios
      .put("http://localhost:3000/apples", {
        count: updatedApplesCount,
      })
      .then((res) => {
        if (res.ok) {
          setApplesCount(updatedApplesCount);
        }
      })
      .catch((e) => {
        console.log("Error updating apples count.", e);
        setErrorMsg("Failed to update apples count.");
      });

    // check if we can continue making smoothies
    checkIfCanMakeSmoothie();
  }, [
    canMakeSmoothie,
    setErrorMsg,
    bananasCount,
    setBananasCount,
    applesCount,
    setApplesCount,
    checkIfCanMakeSmoothie,
  ]);

  // Load the supplies from server & check if a smoothie can be made
  useEffect(() => {
    console.log("loading supplies from server ...");
    checkIfCanMakeSmoothie();
  }, [checkIfCanMakeSmoothie]);

  // all data and methods you want to use outside of the context
  const exposedData = {
    isLoading,
    errorMsg,
    bananasCount,
    applesCount,
    canMakeSmoothie,
    makeSmoothie,
  };

  return (
    <FruitContext.Provider value={exposedData}>
      {children}
    </FruitContext.Provider>
  );
}
```

### Accessing the Context with `useContext` hook (default way)

Once a context is created, React provides a concise way to consume it using the `useContext` hook.
This hook allows functional components to access the context directly:

```jsx
import React, { useContext } from "react";
import { FruitContext } from "../context/FruitContext.js";

function SmoothieMaker() {
  const contextData = useContext(FruitContext);

  // Use contextData here
}
```

### Benefits of Using React Context (with default `useContext` hook)

1. **Simplifies Prop Drilling**: React Context eliminates the need to pass props down through multiple levels of components, reducing code complexity and improving code maintainability.

2. **Global State Management**: Context provides a global state accessible to any component within its scope. This is particularly useful for managing application-wide data, such as user authentication status or theme preferences.

3. **Code Organization**: Context allows you to organize your components more logically by reducing the need for intermediary components just for the sake of passing data.

4. **Component Reusability**: Context enables the creation of more reusable components, as they can consume the context without being tightly coupled to their parent components.

## Understanding Custom Hooks

While React's built-in context management offers a default hook to share data globally within an application, combining it with **custom hooks** can provide an even more elegant and efficient solution for loading and managing context data.

Custom hooks are a way to encapsulate reusable logic and state in a composable and organized manner. They allow developers to extract logic from the view components, making them more focused on presentation. By creating custom hooks that handle the context loading and management, we can achieve cleaner and more maintainable code.

## Loading Context Data with Custom Hooks

Here's how you can utilise custom hooks to load and manage context data more efficiently in a React application:

### Step 1: Create the custom hook

Start by creating a new JS file for your custom hook. Let's call it `useFruitContext.js`.

```javascript
import React from "react";
import { FruitContext } from "../context/FruitContext";

// Custom hook to provide the context data
export function useFruitContext() {
  const context = React.useContext(FruitContext);

  if (!context) {
    throw new Error(
      "useFruitContext must be used within the scope of FruitContextProvider"
    );
  }

  return context;
}
```

### Step 2: Implement the custom hook to load the context in a component

Now, let's use the custom hook to load the context data in a component `SupplyDisplay`, which will display the available quantity of each fruit:

```jsx
import React from "react";
import { useFruitContext } from "../hooks/useFruitContext";

function SupplyDisplay() {
  const { isLoading, bananasCount, applesCount } = useFruitContext();

  return (
    <>
      {isLoading ? (
        <p> Loading ... </p>
      ) : (
        <>
          <p> At the moment we have the following supplies: </p>
          <ul>
            <li> bananas: {bananasCount} </li>
            <li> apples: {applesCount} </li>
          </ul>
        </>
      )}
    </>
  );
}

export default SupplyDisplay;
```

### Step 2: Use the custom hook to access the context data in another component

Let's introduce one more component - `SmoothieMaker`, which will check if the current fruit supply is sufficient for a glass of smoothie and, if it is, it will ask the user if they would like one.
Alternatively, it will display a message - _"Sorry, we cannot make a smoothie at the moment. Please, check again later!"_

```jsx
import React from "react";
import { useFruitContext } from "../hooks/useFruitContext";

function SmoothieMaker() {
  const { isLoading, canMakeSmoothie, makeSmoothie } = useFruitContext();

  if (isLoading) {
    return <p> Loading ... </p>;
  }

  return (
    <>
      {canMakeSmoothie ? (
        <>
          <p style={{ color: "green" }}>Would you like to have a smoothie ?</p>
          <button type="button" onClick={() => makeSmoothie()}>
            Yes, please!
          </button>
        </>
      ) : (
        <p style={{ color: "darkred" }}>
          Sorry, we cannot make a smoothie at the moment. Please, check again
          later!
        </p>
      )}
    </>
  );
}

export default SmoothieMaker;
```

Voila! Sharing state between components is a breeze with the context and custom hook approach. It keeps your code clean, separates business logic from presentation logic, and facilitates easy refactoring or expansion.

## Benefits of Using Custom Hooks for Context Loading

Using custom hooks for loading context data offers several advantages:

1. **Separation of Concerns**: Custom hooks allow you to separate the logic of loading and managing context data from the presentation components, resulting in cleaner and more organized code.

2. **Reusability**: The custom hook can be easily reused across different parts of your application, reducing duplication of code and ensuring consistent data loading behavior.

3. **Readability**: Custom hooks make the code more readable by abstracting away complex logic and providing a clear and descriptive interface for accessing context data.

4. **Testing**: Custom hooks can be tested independently, ensuring that the data loading logic is functioning as expected.

## Conclusion

React **context** is a powerful tool that **simplifies state management and communication** between components in a React application by providing a centralized way to share data without the need for excessive prop drilling. Understanding how to create and use contexts empowers developers to tackle complex state-sharing scenarios with ease, resulting in more **modular** and **efficient applications** as well as **better development experience**.

Furthermore, by encapsulating the context loading logic into a **reusable hook**, developers can achieve **cleaner**, easily **maintainable**, and highly **readable code**. This approach promotes **separation of concerns** and facilitates **code reuse**, making it easier to **manage complex state and data loading** scenarios in large-scale applications.


React Context is a powerful tool that simplifies state management and communication between components without the need for excessive prop drilling. Utilising the context together with a custom hook to load its data, allows for cleaner, more maintainable, and highly readable code, promoting separation of concerns and facilitating code reuse.

React Context is a powerful tool that simplifies state management and communication between components by providing a centralized way to share state without the need for excessive prop drilling.Even though utilising the React Context along with the useContext hook allows for easy complex data-sharing, developers can achieve even cleaner, more maintainable, and highly readable code by encapsulating the context loading logic into a reusable custom hook, promoting separation of concerns and facilitating code reuse and making it easier to manage complex state and data loading scenarios in large-scale applications.

Leveraging React Context and Custom Hooks for Efficient State Sharing and Data Loading


Welcome to the first article in our series exploring the integration of the Pulumi Automation API, a powerful
Infrastructure as Code (IaC) platform, and Keycloak, a leading open-source Identity and Access Management (IAM)
solution. In the age of rapid cloud migration, managing complex IAM processes across multiple systems and user roles has
become a significant challenge. In this series, we'll show how combining Keycloak and the Pulumi Automation API can make
IAM processes more efficient for businesses while also enhancing security procedures and resource allocation efficiency.

In this first part of our series, we'll concentrate on getting to know Keycloak and Pulumi and setting up the REST API
framework that will support our interactions with the Pulumi Automation API in the following blog posts. Our goal is to
give you a firm understanding of Keycloak and Pulumi's foundational ideas before we continue with an example of the
actual integrate. We want to show how automating realm creation and management in Keycloak reduces manual effort while
also improving consistency across multiple tenants.

## Introduction

Over the past decade, the migration rate of applications and services to the cloud has grown exponentially — and for
good reason. Cloud computing provides organizations with substantial scalability, flexibility, and cost-effectiveness.

However, embracing the cloud also brings new challenges, one of the most notable being secure access to cloud resources.
Organizations today must manage complex identity and access management (IAM) processes across diverse systems and user
roles, a challenging task that brings us to the topic at hand.

This article will explore the benefits of using Keycloak, a widely adopted open-source IAM solution in conjunction with
the Pulumi Automation API. Said setup enables organizations of all sizes to streamline their IAM by leveraging Pulumi
automating capabilities to provision Keycloak instances for multiple tenants, ensuring consistent security practices and
efficient resource allocation.

## What is Keycloak Multi-Tenancy

As we already mentioned, Keycloak is an open-source Identity and Access Management solution. Its main goal is to
centralize user authentication and authorization, making it easier to secure applications and services. One of
Keycloak's strengths is its ability to support multiple tenants. This handy feature enables organizations to effectively
isolate access to resources for different groups and users. To better understand this powerful security feature, we must
briefly explain the concept of realms.

In Keycloak, realms serve as isolated environments for managing users, roles, and permissions. Each realm represents a
tenant or a group of users with a common set of resources and access rules. This multi-tenancy capability enables
organizations to segregate their user bases and maintain separate security policies, ensuring that resources are only
accessible to authorized users.

Simply put, Keycloak's multi-tenancy feature allows creating groups (tenants) according to business units,
responsibilities, or whatever criteria your organization requires. This ensures a consistent security posture across the
entire organization with relatively little effort.

Regarding the latter, managing an IAM system in companies with hundreds of employees can be a daunting task, even using
Keycloak's fantastic UI. This is where the Pulumi Automation API comes into play.

## What is Pulumi and Pulumi Automation API

Pulumi is an open-source Infrastructure as a Code platform that allows developers to define and manage cloud
infrastructure using familiar programming languages like Python, TypeScript, Go, and C#, among others.

On the other hand, the Pulumi Automation API is a powerful library that enables developers to programmatically interact
with Pulumi's infrastructure-as-code (IAC) engine, allowing them to create, update, and delete infrastructure resources
as required.

## Why Use Pulumi Automation API for Keycloak Deployments?

The Pulumi Automation API offers numerous benefits to development teams and organizations as they tackle the challenges
of managing infrastructure in today's cloud-centric world.

In the context of provisioning Keycloak multi-tenancy instances, the Pulumi Automation API allows developers to automate
the creation and management of realms, reducing manual effort and ensuring consistent configurations across multiple
tenants. This streamlined approach saves time and minimizes the risk of misconfigurations that could lead to security
vulnerabilities.

That being said, these are just some of the advantages of using the Pulumi Automation API for handling Keycloak
multi-tenancy solutions.

### Language Flexibility

One of the main benefits of using Pulumi Automation API is the ability to choose from various programming languages to
define your infrastructure resources, including Keycloak deployments. Unlike other IaC tools like Terraform that rely on
domain-specific languages or YAML/JSON configuration files, Pulumi allows developers to use popular languages like
Python, Node.js, TypeScript, JavaScript, Go, Java, and the entire family of .NET languages.

Moreover, regardless of the language used, Pulumi offers support for all the clouds and applications available in the
Pulumi Registry. This includes Pulumi's Keycloak Resource Provider.

### Comprehensive and Customizable Automation

Pulumi Automation API enables developers to create custom workflows and integrations that leverage the power of Pulumi's
Infrastructure as Code capabilities. By embedding Pulumi directly into applications, developers can automate the
creation, modification, and destruction of infrastructure resources with precision and control. Such flexibility is
essential from a security standpoint, as your organization can tune the Pulumi automation API for whatever scenario you
have in mind when deploying Keycloak.

### Enhanced Developer Experience

The Pulumi automation API provides a seamless developer experience by integrating Infrastructure as Code into the same
development environment used for application code. This eliminates the need for context-switching between different
tools, languages, or configuration files, allowing developers to focus on building features and functionality.

### Multi-Cloud Support

Pulumi Automation API supports a wide range of cloud providers, including AWS, Azure, Google Cloud, and Kubernetes. This
flexibility enables developers to manage infrastructure across multiple cloud environments using a single, unified
platform. In other words, with Pulumi and Keycloak, your organization can develop a vendor-agnostic solution that can be
used both on-premise or the cloud, any cloud.

## Setting up the REST API

In this section, we'll guide you through the setup of our REST API that we will later use to interact with the Pulumi
Automation API. To create a new Keycloak realm using a REST API, we'll set up a simple HTTP server in Go and incorporate
the Pulumi Automation API in the next blog article.

In Keycloak multi-tenancy can be modeled in various ways. The two most popular strategies are one realm with one client
per tenant and multi-tenancy with one realm per tenant. Each strategy has its own pros and cons, which we may discuss in
a future blog post. Therefore, the strategy you choose will largely depend on your specific use case. For this
example, we opted for one realm per tenant, as it is the simplest option.

For the REST API we'll define two endpoints `POST /tenants` and `DELETE /tenants/:slug`.

The `POST` endpoint will receive a JSON body with the tenant slug and the tenant name:

```json
{
  "slug": "zone2",
  "name": "Zone 2 technologies Ltd."
}
```

When this endpoint receives a request, it will trigger the Pulumi Automation API which in turn will set up a new realm
named `zone2` in Keycloak.

On the other hand, the `DELETE` endpoint will destroy the newly created realm. For this we'll pass the `slug` as a
path parameter to the `DELETE` endpoint.

### Project setup

Let's get started with the Go project setup.

1. **Create a new directory for your project**: Choose a location outside your `GOPATH`, then create a new directory and
   navigate into it.
   ```shell
   mkdir tenant-service
   cd tenant-service
   ```
2. **Initialize a new module**: Inside your project directory, initialize a new module by running:
   ```shell
   go mod init github.com/your-username/tenant-service
   ```
   Replace "your-username" with your GitHub username. This command will create a `go.mod` file in your directory.
3. **Add dependencies**: To run the project we'll need the following dependencies:
   ```shell
   # HTTP server
   go get github.com/gorilla/mux
   # Pulumi Keycloak SDK
   go get github.com/pulumi/pulumi-keycloak/sdk/v5
   # Pulumi API
   go get github.com/pulumi/pulumi/sdk/v3
   ```
   In this step, we're grabbing the necessary dependencies for our project. Here's a little more information about what
   each of these commands do:
    * `go get github.com/gorilla/mux`: This line is fetching the mux package from the Gorilla web toolkit. It's a
      powerful URL router and dispatcher that we'll use to direct HTTP requests in our server.
    * `go get github.com/pulumi/pulumi-keycloak/sdk/v5`: Here we're downloading the Pulumi Keycloak SDK. This software
      development kit (SDK) will allow us to interact with Keycloak in our Go application.
    * `go get github.com/pulumi/pulumi/sdk/v3`: Lastly, this command retrieves the Pulumi SDK. This will let us use the
      Pulumi API.

### HTTP server setup

After we are done with the basic setup of our application we can continue to integrate the HTTP server.

1. **Application setup**: In this part of the project, we're setting up the main application. We begin by creating a
   `main.go` file in our root directory. This file will be the entry point for our application and will start the HTTP
   server.
   ```go
   func main() {
      router := mux.NewRouter()

      router.HandleFunc("/tenants", createTenantHandler).Methods("POST")
      router.HandleFunc("/tenants/{slug}", deleteTenantHandler).Methods("DELETE")

      s := &http.Server{Addr: ":8000", Handler: router}

      err := s.ListenAndServe()

      if err != nil {
        log.Fatal("Unable to start server", err)
      }
   }
   ```
   This is our basic HTTP server setup in Go that implements the before mentioned endpoints. We have not yet implemented
   the `createTenantHandler` and `deleteTenantHandler` functions - but stay tuned, we'll be tackling those in the next
   steps.
2. **Implement `createTenantHandler`**: In this step, we're implementing the `createTenantHandler` function in a new
   file named `handlers.go`. This function will be responsible for handling incoming HTTP POST requests to create a new
   tenant.
   ```go
   // POST request payload
   type CreateTenantRequest struct {
      Slug string `json:"slug"`
      Name string `json:"name"`
   }

   // POST request response
   type CreateTenantResponse struct {
      RealmId string `json:"realmId"`
   }


   func createTenantHandler(w http.ResponseWriter, req *http.Request) {
      var payload CreateTenantRequest
      err := json.NewDecoder(req.Body).Decode(&payload)

       if err != nil {
           http.Error(w, "Invalid request body", http.StatusBadRequest)

           return
       }

       // TODO: implement creation of the Keycloak realm

       response := &CreateTenantResponse{
           RealmId: "TODO",
       }

       err = json.NewEncoder(w).Encode(&response)

       if err != nil {
           http.Error(w, "Could not write response json", http.StatusInternalServerError)
       }
   }
   ```
   In this function, we're processing a POST request to create a new tenant (or "realm" in Keycloak terms). After
   successfully decoding the incoming request, we reach a placeholder section:
   ```go
   // TODO: implement creation of the Keycloak realm
   ```
   Here is where we'll add our code to interact with Keycloak, using the information provided in the
   `CreateTenantRequest` to create a new realm.

   After the realm is created in Keycloak, we'll need to replace the `"TODO"` placeholder in
   the `CreateTenantResponse` with information relevant to the newly created realm:

   ```go
   response := &CreateTenantResponse{
       RealmId: "TODO",
   }
   ```
   Lastly, we encode and send our response. If there's an issue during encoding, we handle it accordingly and respond
   with an appropriate error status.

   So, this function is all about making Keycloak create a new realm based on our request, then sending back some
   meaningful information about the created realm in the response. It's a key part of our multi-tenancy setup with
   Keycloak, allowing us to programmatically expand our application with new tenants as required. We'll explore how to
   actually communicate with Keycloak and create realms in the following parts of the blog.
3. **Implement `deleteTenantHandler`**: We're now moving on to implementing the `deleteTenantHandler`, which is
   responsible for deleting a tenant. You can add the following code to the `handlers.go` file:
   ```go
   func deleteTenantHandler(w http.ResponseWriter, req *http.Request) {
       params := mux.Vars(req)
   
       if len(params["slug"]) == 0 {
           http.Error(w, "slug is required", http.StatusBadRequest)
   
           return
       }
	   
       // TODO: implement deletion of the Keycloak realm
   }
   ```
   This function will handle incoming HTTP DELETE requests, allowing us to delete an existing tenant. The slug of the
   tenant we want to delete is expected to be included in the request URL. Like in the `createTenantHandler` we have
   a `TODO` placeholder where we'll add our code to communicate with Keycloak and delete the realm corresponding to
   the given `slug`.
4. **Start the application**: At this stage, we've set up our HTTP server and implemented the handler functions for
   creating and deleting tenants. Our next step is to actually start the application and see it in action. Here's how we
   can do that:
   ```shell
   # build
   go build -o tenant-service
   
   # run
   ./tenant-service
   ```
   Once the server is up and running, we'll be able to send HTTP requests to theoretically create and delete tenants. In
   the next steps, we'll be adding more functionality and starting to interact with Pulumi to manage our tenants.

## Conclusion

We've started our journey exploring the integration of Keycloak and the Pulumi Automation API for more efficient
Identity and Access Management. Additionally, we've laid out the basics of Keycloak and Pulumi, with a focus on the potential of
Pulumi's Automation API for improving a multi-tenancy setup in organizations. Moreover, we walked through setting up a
simple REST API framework in Go, demonstrating how it will support our interactions moving forward. 

In the following articles, we will build on this foundation, focusing on implementing the API, automating realm creation, and managing
Keycloak using Pulumi's Infrastructure as Code capabilities.

I hope that you enjoyed the blog post and will join me for next one, too. I look forward to hearing your thoughts and
feedback!

The code for each part of the project will be available in this [Git repository](https://github.com/zone-2-technologies/keycloak-multi-tenancy-pulumi-automation-api).


Explore the synergy between Keycloak and Pulumi's Automation API. This detailed guide emphasizes efficient Identity and Access Management (IAM) with a focus on multi-tenancy capabilities. Gain in-depth insights and understanding of these robust tools to improve your organization's security infrastructure.

Explore the integration of Keycloak and Pulumi's Automation API for efficient IAM, focusing on enhancing multi-tenancy capabilities.

Keycloak Multi-Tenancy and the Pulumi Automation API - Part 1


Developers need fast and efficient way to deliver apps to the users, ensuring continuous integration and clear versioning of their apps.
Manual publishing of an app can be time-consuming and involves a lot of repetitive steps that could easily be automated, such as building and signing a new apk/aab file, logging in to the Google Play Console and uploading the file.
Therefore, the most efficient way to achieve this is automating the process of publishing the app to Google Play Store or AppStore.

In this tutorial, I will show you how you can use [Fastlane](https://docs.fastlane.tools/) and [Gihtub Actions](https://docs.github.com/en/actions) to automatically upload an android app bundle (.aab) to Google Play Store.

## Prerequisites

Before we proceed with the tutorial, you will need to have done the following:

    1. [Create a Google Play Developer Account](https://support.google.com/googleplay/android-developer/answer/6112435?hl=en)
    2. [Setup an app in your account](https://support.google.com/googleplay/android-developer/answer/9859152?hl=en)
    3. [Enable Google Play Android Developer API](https://support.google.com/googleapi/answer/6158841?hl=en)
    4. [Enroll on Play App Signing](https://support.google.com/googleplay/android-developer/answer/9842756?hl=en): if you are not sure how to enroll, check out this super concise tutorial on [jmango360](https://support.jmango360.com/portal/en/kb/articles/enroll-in-app-signing-by-google-play)
    5. [Configure your app to use the correct upload key for signing the app](https://reactnative.dev/docs/signed-apk-android#setting-up-gradle-variables): it must be the one used to enroll for Play App Signing and for the purposes of this tutorial it will be called `myKeystore.keystore`

## 1. Create a service account and JSON key

To automate the process of publishing your app to Google Play Store you will have to provide a JSON key, which will be used for authentication against Google Play Developer API.
In order to obtain this key, you have to setup a service account first.

### Create a new service account

Step 1: Login to **Google Cloud Console**

Step 2: Navigate to **IAM & Admin** and select **Service Accounts**

Step 3: Create a new service account and assign the role of **Basic Editor** to it.

### Generate a new json key

Step 4: Navigate to the service account you have just created, click on **create new key** and select type **JSON**.

Download the key and store it securely. For the purposes of this tutorial rename the file to `service-account.json`.

### Invite the service account user to the app project

Step 5: Login to **Google Play Console** and navigate to **Setup** -> **API access**

Step 6: Find the service account name (email) and grant **admin** access to it. If you want to keep the permissions to the minimum required, make sure that you have selected everything under the release section.

Note: Be aware that granting access to the service account can only be performed by the **owner of the google developer account**.

## 2. Setting up Fastlane

Step 1: Make sure that you have installed Ruby on your machine:

```shell
    ruby -v
```

Step 2: Install fastlane:

```shell
    gem install fastlane -NV
```

Step 3: At the root of the project (i.e. `android/`) run the following command to initialise fastlane:

```shell
    fastlane init
```

This will prompt you to enter the name of the package, e.g. "io.appname.app".
You can press enter to skip the rest of the questions, as they can be configured later.
When asked "Download existing metadata and setup metadata management?" respond with no (i.e. `n`).

After the command has been executed you will notice that a new folder `fastlane` has been created.
Inside this folder there will be two files - `Appfile` and `Fastfile`.
Place the `service-account.json` in the `fastlane/` folder, but **do NOT commit it to github**.

Step 4: In the `fastlane/Appfile` define the path to the service account json key (relative to where the fastlane actions will be called) and the package name.

Assuming that the fastlane actions will be called at the root of the project, the `Appfile` content looks like this:

```shell
    json_key_file("fastlane/service-account.json")
    package_name("io.appname.app")
```

Important: When you use github actions make sure to restore the json key in the correct directory (i.e. `fastlane/`).

Step 5: The `fastlane/Fastfile` is where all methods (a.k.a lanes) must be defined.

Let's take a look at the following `Fastfile`.

There are two lanes (methods), the first of which is `:internal`. It uses the `gradle` action to build an app bundle (.aab) and the `upload_to_play_store` action to upload the bundle to the internal track on the play store (the other track options are 'alpha', 'beta' and 'production').
To find out more about the google play tracks click [here](https://developers.google.com/android-publisher/tracks).

The second lane is `:production` and uses the same actions to build and publish the bundle to the production track on Google Play.

```rb
    default_platform(:android)

        platform :android do

            # LANE 1
            desc "Publish a new version to the Google Play (INTERNAL)"
            lane :internal do

                # Generate AAB file
                gradle(
                task: "bundle",
                build_type: "Release"
                )

                # Upload the AAB to play store (internal track)
                upload_to_play_store(track: 'internal')
            end

            # LANE 2
            desc "Publish a new version to the Google Play (PROD)"
            lane :production do

                # Generate AAB file
                gradle(
                task: "bundle",
                build_type: "Release"
                )

                # Upload the AAB to play store (production track)
                upload_to_play_store(track: 'production')
            end
        end

```

If you want to make sure everything works as expected before you publish your app, you could pass the `validate_only: true` argument to the `upload_to_play_store` action.
It will only verify that everything is correct without actually publishing the app on the selected track.

```rb
    # Validate upload the AAB to play store (production track)
    upload_to_play_store(track: 'production', validate_only: true)
```

Note: You can find all available arguments for `upload_to_play_store` [here](https://docs.fastlane.tools/actions/upload_to_play_store/)

If you want to run the `:production` lane locally, execute the following command in your terminal (note: make sure you are working in the root dir):

```shell
    bundle exec fastlane production
```

## 3. Create a workflow with Github Actions

### Create new repository secrets for the JSON key and upload key (`myKeystore.keystore`)

Both the upload key and the service account json key contain sensitive information which should be stored securely and hence, should not be pushed to the github repository.
In order to be able to access them from within the workflow, you have to obtain them from the repository secrets. To achieve this, let's first ecrypt/encode them:

Step 1: Encrypt the .keystore file, in the terminal run the following command:

```shell
    gpg -c -armor myKeystore.keystore
```

This command will prompt you to enter a passphrase. Important: Make note of the passphrase.

After successful exection you will be able to see a `myKeystore.keystore.asc` file in the current directory.

Step 2: Create a new repository secret (ENCRYPTED_KEYSTORE), containing the content of `myKeystore.keystore.asc`

Step 3: Create a new repository secret (ENCRYPTED_KEYSTORE_PASSPHRASE), containing the passphrase, used to encrypt the keystore (ref. Step 1)

Step 4: Encode the JSON key

```shell
    base64 -it service-account.json -o encoded.base64.txt
```

Step 5: Create new repository secret (SERVICE_ACCOUNT_JSON) and place the content of the `encoded.base64.txt`

### Create a new github workflow

Now, that Fastlane and the secrets have been setup, let's create the workflow `.github/workflows/publish_play_store.yml`, containing the following:

```yml
name: Publish to Play Store ( Internal track )

on:
  workflow_disptach:

jobs:
  upload-play-store-internal:
    name: Upload app to Play Store (Internal track)
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v3

      - name: Setup ruby
        uses: actions/setup-ruby@v1
        with:
          ruby-version: "3.x"

      - name: Setup fastlane
        run: |
          cd android
          bundle install
          cd ..

      - name: Restore json key # make sure that you restore the key in the correct directory (ref. fastlane/Appfile)
        run: |
          cd android/fastlane
          echo "${{ secrets.SERVICE_ACCOUNT_JSON }}" | base64 --decode > service-account.json
          cd ../..

      - name: Restore keystore # make sure that you restore the key in the correct directory (same as app/gradle.properties)
        run: |
          cd android/app
          echo "${{ secrets.ENCRYPTED_KEYSTORE }}" > myKeystore.keystore.asc
          gpg -d --passphrase ${{ secrets.ENCRYPTED_KEYSTORE_PASSPHRASE }} --batch myKeystore.keystore.asc > myKeystore.keystore
          cd ../..

      - name: Set up JDK environment
        uses: actions/setup-java@v3
        with:
          distribution: "zulu"
          java-version: 11

      - name: Install dependencies
        run: yarn install --frozen-lockfile

      - name: Make Gradlew Executable
        run: cd android && chmod +x ./gradlew

      - name: Upload app to Play Store (Internal track)
        run: |
          cd android
          bundle exec fastlane internal
```

Congratulations, you have automated your app publishing process.
All you have to do is run the workflow and your app will be available to testers on the internal track. To publish the app on the production track instead, simply switch the lane in the final step to poduction and you are good to go.

## Conclusion

Automating your app deployment can save you hours of building, testing, and releasing
your app on a regular basis. In this tutorial I have walked you through the steps
of automating the process of building and publishing an android app to Google Play
Store. If you are interested in reading other tutorials related to play store automation
with Gihtub Actions, I recommend these amazing articles by Tomer Ben Rachel on [freecodecamp.org](https://www.freecodecamp.org/news/use-github-actions-to-automate-android-development/)
and by Shreyas Patil on [medium.com](https://medium.com/scalereal/automate-publishing-app-to-the-google-play-store-with-github-actions-fastlane-ac9104712486).


Discover how to automate Android app deployment to the Google Play Store using Fastlane and GitHub Actions, simplifying the process and enhancing efficiency.

Automate publishing your android app to Google Play Store with Fastlane and Github Actions


A React component undergoes three distinct phases in its lifecycle (i.e. mounting, updating, and unmounting). Each phase has specific methods responsible for a particular stage in the component's lifecycle.

Be aware that these lifecycle methods are specific to **class-based components** and are, therefore,
**not applicable to functional components**. When working with **functional components**, however, the **state** is used in a similar manner, where the data is stored and manipulated with abstracted versions of the lifecycle methods called "**hooks**".

Here you'll learn more about the React component lifecycle and the different methods within each phase, as well as, how to use the most common hooks `useState` and `useEffect`.

## The Lifecycle of a React Component

### Phase 1: Mounting

The first phase in a component's lifecycle is called "Mounting".
The mounting phase begins with the creation of a new component and its insertion into the DOM.

It can only happen once and React has four built-in methods that get called in this exact order:

- `constructor(props)` :

  - called before anything else;
  - called with props as an argument;
  - sets the initial state;
  - must always start with the `super(props)` in order to inherit methods from its parent (i.e. `React.Component`);

- `getDerivedStateFromProps(props, state)` :

  - called right before rendering the elements in the DOM;
  - sets the state object based on the props;
  - accepts two arguments: `props` and `state`;
  - returns an object with the changes to the state, or null if there is no change.

- `render()` :

  - called after the props and state have been set;
  - inserts the HTML into the DOM;
  - returns the JSX which will be rendered;
  - supposed to be **pure** (i.e. **must NOT** modify the state, have any direct interaction with the browser, or any other kind of side effect)

- `componentDidMount()` :
  - called after the component is rendered;
  - runs statements that require that the component be in the DOM;
  - can include side effects like sending network requests and updating the component's state;
  - **caution**: it may accidentally cause unnecessary re-renders.

Note: The `render()` method is **required** and **will always be called**, the rest are optional and will only be called if defined.

Here is an example of the construtor and render methods:

First, the `super(props)` is called, in order to initialise the `React.Component`'s constructor and inherit its methods.

Then, inside the `constructor` method the variable `colour` is set to "purple".

And finally, the `render` method is used to display an `<h1>` element, containing the text "My favourite colour is purple"

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }
  render() {
    return <h1>My favorite colour is {this.state.colour}</h1>;
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour />);
```

Now, let's implement the `getDerivedStateFromProps(props, state)` method.

Initially the `colour` is set to "purple", but then the `getDerivedStateFromProps` method
updates the `colour`, depending on the `favouriteColour` attribute, which, in this case, is "yellow".

The resulting text, rendered on the page, is "My favourite colour is yellow".

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }
  static getDerivedStateFromProps(props, state) {
    return { colour: props.favouriteColour };
  }
  render() {
    return <h1>My favorite colour is {this.state.colour}</h1>;
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

Suppose that the colour should not be changed right away. Instead, the initial value has to be displayed first and then, after some time has passed, it should be updated to "yellow".

Well, in that case, the `componentDidMount` method could be used to change the colour to yellow 10 seconds after the component has been rendered.

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }
  componentDidMount() {
    setTimeout(() => {
      this.setState({ colour: "yellow" });
    }, 10000);
  }
  render() {
    return <h1>My favorite colour is {this.state.colour}</h1>;
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

### Phase 2: Updating

The second phase is the updating phase and it **can occur multiple times**.

It is triggered when there is a **change in the component's state or props** and causes the component to re-render with the updated values of the state/props.

The updating phase includes the following methods, in this exact order:

- `getDerivedStateFromProps()` : like in the mounting phase, it sets the state based on the initial props

- `shouldComponentUpdate()` :

  - can accept `nextProps` and `nextState` as arguments, however, they are **optional**;
  - returns a Boolean value that specifies whether React should continue with the re-rendering or not;
  - the default value is true;
  - ignored when `forceUpdate()` is invoked;
  - specifically intended for performance optimisation

- `render()` : re-renders the HTML in the DOM, with the updated values;

- `getSnapshotBeforeUpdate()` :

  - provides access to the **props and state before the update**, so that even after the update, you can still check what the values had been before it;
  - should also include the `componentDidUpdate` method, otherwise you will get an error;
  - **use case**: handling scroll positions in a chat app. Upon receiveing new messages, the app shouldn’t push the currently visible ones out of view.

- `componentDidUpdate()` :

  - called after the component is updated in the DOM;
  - **required if `getSnapshotBeforeUpdate` is called**;
  - accepts up to three parameters: **prevProps**, **prevState**, and **snapshot**;
  - allows you to create side effects such as sending network requests or calling `this.setState`;
  - **caution**: **avoid** the use of `setState` in this method, or it will result in an **infinite loop of re-rendering**.

Let's add a button that changes the `colour` to "green".

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }
  static getDerivedStateFromProps(props, state) {
    return { colour: props.favouriteColour };
  }
  changeColour = () => {
    this.setState({ colour: "green" });
  };
  render() {
    return (
      <div>
        <h1>My favorite colour is {this.state.colour}</h1>
        <button type="button" onClick={this.changeColour}>
          GREEN
        </button>
      </div>
    );
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

Once the button is clicked the `state.colour` is set to "green". However, the change in state triggers the components's updating phase, which in turn triggers the `getDerivedStateFromProps`. Once it has been called, it updates the state colour to "yellow" (the value of the favouriteColour attribute). As a result, the colour displayed on the page is not "green", but "yellow".

To disable this behaviour the `getDerivedStateFromProps` method must be removed.

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }

  changeColour = () => {
    this.setState({ colour: "green" });
  };
  render() {
    return (
      <div>
        <h1>My favorite colour is {this.state.colour}</h1>
        <button type="button" onClick={this.changeColour}>
          GREEN
        </button>
      </div>
    );
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour />);
```

Now, let's add the `getSnapshotBeforeUpdate` method and display what the colour had been set to before the update.

To do so, two `<div>` elements are added. One `<div>` will contain the value of the colour before and the other - after the re-rendering.

In the `getSnapshotBeforeUpdate` method, the previous state is accepted as argument, then the `<div>` with id `before-update` is selected and its text content set the colour to be displayed.

Whenever the `getSnapshotBeforeUpdate` is used, the `componentDidUpdate` method must be included as well. In the example, it is used to set the text content of the second `<div>` to the value of `colour` after the update.

```js
class FavouriteColour extends React.Component {
  constructor(props) {
    super(props);
    this.state = { colour: "purple" };
  }
  componentDidMount() {
    setTimeout(() => {
      this.setState({ colour: "yellow" });
    }, 10000);
  }
  getSnapshotBeforeUpdate(prevProps, prevState) {
    document.getElementById("before-update").textContent =
      "Before: " + prevState.colour;
  }
  componentDidUpdate() {
    document.getElementById("after-update").textContent =
      "After: " + this.state.colour;
  }
  render() {
    return (
      <div>
        <h1>My favorite colour is {this.state.colour}</h1>
        <div id="before-update"></div>
        <div id="after-update"></div>
      </div>
    );
  }
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

### Phase 3: Unmounting

The final phase in the lifecycle of a React component is unmounting. It occurs right before the component is removed from the DOM.

React has only one built-in method that is called when a component is unmounted:

- `componentWillUnmount()` :
  - called when the component is about to be removed from the DOM;
  - meant for any necessary **clean up** of the component( i.e. canceling any network requests);
  - once this method has been executed, the component is **destroyed**.

## useState and useEffect React Hooks

Before the release of React 16.8 there were two kinds of components in terms of state:
the class-based stateful component, and the stateless functional components.

In version 16.8, however, the so-called **hooks** were introduced. They are functions that allow you to "hook into" the React state and the lifecycle of the components.

As a result, developers can now **access and modify the state from functional components**, which would have, otherwise, required a class. With this change, building components has become easier and less verbose.

React has released several default hooks which are ready to use, however, you can also create your own custom hooks.

Bear in mind that there is a **naming convention** for **custom hooks**. The name of the hook must **begin with `use`** (i.e. `useCustomHook`, `useColour`, `useTheme` etc.)

Among the default hooks, the most commonly used ones are `useState` and `useEffect`:

- `useState(initialState)`:

  - used to store variables in the state;
  - accepts one argument: `initialState`, which will be set as the initial value of the state;
  - returns two values: the state value, and a function to be used to update the state;
  - the update function's name usualy begins with `set` and it accepts one argument, `newState`, which replaces the existing state.

Generic example of `useState`:

```js
const [value, setValue] = useState(initialState);
```

Let's rewrite one of the examples above as a functional component and use `useState` to update the colour:

```js
function FavouriteColour(props) {
  const [colour, setColour] = React.useState(props.favouriteColour);

  const changeColour = () => {
    setColour("green");
  };

  return (
    <div>
      <h1>My favorite colour is {colour}</h1>
      <button type="button" onClick={changeColour}>
        GREEN
      </button>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

In this example the text displayed initially on the page is "My favourite colour is yellow" because the initial value of `useState` is set to "yellow".

Similarly to the previous examples, "yellow" comes from the `favouriteColour` attribute, which is received by the component as a prop. Then, upon clicking the GREEN button, the page is re-rendered and the updated text reads "My favourite colour is green".

- `useEffect(function, dependencyArray)`:

  - allows you to add **side effects** (such as send network requests), which aren’t allowed within the function's main body;
  - allows you to **call functions upon updates** on the state;
  - accepts **a function** as an argument, inside which you write all the side effects;
  - accepts **an array** as second argument called the dependency array (optional);
  - invoked after every browser paint and **before any renders** (depends on the **dependency array**);
  - can return another function called the **clean-up function**, which is used to clean up the side effects when the component is destroyed.

The dependency array is an array of variables, which will **trigger the `useEffect` function** when their value changes.

If the dependency array is **empty**, then the `useEffect` runs only once, before render.

Alternatively, if it is **not defined**, `useEffect` will run once during mounting and then again on every re-render.

```js
function FavouriteColour(props) {
  const [colour, setColour] = React.useState(props.favouriteColour);
  const [count, setCount] = React.useState(0);

  React.useEffect(() => {
    setCount((previousCount) => (previousCount += 1));
  }, [colour]);

  const changeColour = (newColour) => {
    setColour(newColour);
  };

  return (
    <div>
      <h1> My favourite colour has been updated {count} times.</h1>
      <h1>My favorite colour is {colour}</h1>

      <button type="button" onClick={() => changeColour("green")}>
        GREEN
      </button>
      <button type="button" onClick={() => changeColour("yellow")}>
        YELLOW
      </button>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

In the example above `useEffect` is used to increment the state of `count` each time the state of `colour` is updated.

Note that when the page is rendered for the first time the `count` has already been incremented once. This happens because the function in `useEffect` is executed every time the value of `colour` is modified, inclding the inital one.

If this is not the desired outcome, instead of using `useEffect`, the `setCount` could be called inside the `changeHandler` to update the `count`.
Now, the initial render does not affect the initial value of `count`.

```js
function FavouriteColour(props) {
  const [colour, setColour] = React.useState(props.favouriteColour);
  const [count, setCount] = React.useState(0);

  const changeColour = (newColour) => {
    setColour(newColour);
    setCount((previousCount) => (previousCount += 1));
  };

  return (
    <div>
      <h1> My favourite colour has been updated {count} times.</h1>
      <h1>My favorite colour is {colour}</h1>

      <button type="button" onClick={() => changeColour("green")}>
        GREEN
      </button>
      <button type="button" onClick={() => changeColour("yellow")}>
        YELLOW
      </button>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<FavouriteColour favouriteColour={"yellow"} />);
```

This is, in fact, the better way of achieving the desired behaviour in this case. The previous example only aimed to show how the `useEffect` works.

## Conclusion

React components go through three phases in their lifecycle. These are mounting, updating and unmounting. Each of the phases is associated with certain methods which are executed in specific order and can be used to modify the state
and behaviour of the components.

These methods, however, are only for class-based components. For functional components the lifecycle methods are replaced by hooks.

Hooks have gaining popularity because they are cleaner and less verbose. Even though there are several default hooks provided by React, the most commonly used ones are `useState` and `useEffect`.


React components go through three phases in their lifecycle. Each phase is associated with certain methods which are executed in specific order and can be used to modify the state and behaviour of the class-based components. For functional components the lifecycle methods are replaced by hooks. 

Learn about the lifecycle of React components and how they mount, update, and unmount, using methods or hooks to manage state and behavior.

The Lifecycle of React Components


A Shell script is a program designed to be run on the comand-line-interpreter (CLI). With shell scripting, you can write a series of commands in a file and then once you run the file, each command will be executed by the shell automatically. This allows you to perform repetitive tasks more efficiently. Additionally, there is a wide range of use cases of shell scripting, such as installing and running programs, creating a program environment, scheduling data backups, and many more.

### WHAT IS THE SHELL

A shell is a program that acts as an interface between the user and the kernel or, more simply put, it translates the commands from the terminal to the operating system. The original unix shell (`sh`) was written by Steve Bourne. At present, the most popular shell is `bash`, which stands for Bourne Again Shell and is an enhanced version of the original shell. Other shell programs include but are not limited to: `zsh` (Z Shell), `csh` (C Shell) and `ksch` (KornShell).

### BASH SHELL FILE IDENTIFICATION

Shell scripts use the `.sh` extension and begin with a shebang ( e.g. `#! /bin/bash`, `#! usr/bin/bash`), which indicates to the shell how to locate the interpreter required to execute the script. In its essence, the shebang is a special kind of comment which contains the absolute path to the interpreter and it varies for different computer systems. You can check which is the correct shebang on your machine by running the command `which bash` in your terminal.

### SCRIPT EXECUTION RIGHTS

Let's create an example file:

```bash
touch example.sh
```

By default, after creation, the file has only read and write permissions, represented by "r" and "w". The execution right is marked with an "x". You can learn more about file permissions in this article on [guru99](https://www.guru99.com/file-permissions.html).

In brief, you can check the permissions of a file by runinng `ls -a <filename>`

````sh
ls -l example.sh
-rw-r--r--@ 1 user  0 20 Jan 15:37 example.sh```
````

"-rw-r--r--": The first three letters represent the rights of the owner of the file. Rights which are not granted are marked with a dash instead of their respecive letters. In this case the owner has read and write rights (`rw-`), while the user and group rights are read-only (`r--`).
In order to allow the execution of the `example.sh` file for all:

```sh
chmod +x example.sh
-rwxr-xr-x@ 1 user  0 20 Jan 15:37 example.sh
```

"-rwxr-xr-x": You can see that now the owner has all three rights (`rwx`), while the user and group have read and execute rights (`r-x`).

### WRITING SHELL SCRIPTS

Shell scripts use the same syntax you would use on the shell command line.
Here is a list of some of the essential Linux commands posted on [Digital Ocean](https://www.digitalocean.com/community/tutorials/linux-commands).

Let's keep our example simple and print the message "Hello World" to the console:

```sh
#! /bin/bash
echo "Hello World"
```

### Executing the shell script

To execute the script, use the command `bash <filepath>`. In my case, the file is located in the current folder so:

```sh
bash example.sh
```

### Defining variables

Defining variables in a shell script is as easy as `variable_name=variable_value`.

```sh
#! /bin/bash

name="John"
surname="Doe"

echo "Hello, my name is $name $surname"
```

### Using arguments

Arguments are passed after the filename in the form of a sequence of strings (or numbers) separated by space. In our example, we pass two arguments to the `example.sh` - John and Doe:

```sh
bash example.sh John Doe
```

In the script, the arguments are identified by the order in which they are received, starting with 1.
Hence, `name=$1` will equal `name="John"` while `surname=$2` will equal `surname="Doe"`

```sh
#! /bin/bash

name=$1
surname=$2

echo "Hello, my name is $name $surname"
```

### Setting default values for the variables

Default values could be set for the variables in the script in case that no argument is received.
The syntax is `variable_name=${arg_position:-"Default Value"}`. For example,

```sh
#! /bin/bash

name=${1:-"John"}
surname=${2:-"Doe"}

echo "Hello, my name is $name $surname"
```

### Reading user input

User input can be saved inside a variable with `read variable_name` or, if you would like to prompt the user with a specific message, you can add the -p flag and the message - `read -p "Propmt Message: " variable_name`. You can see both options in the following example:

```sh
#! /bin/bash

echo "What is your name?"
read name

read -p "What is your surname?" surname

echo "Nice to meet you, $name $surname."
```

### Setting dynamic variables

In case you want to calculate the value of a variable during runtime, you could use the `$(( expression ))` syntax. For example, the user provides two numbers and you want to evaluate their sum:

```sh
#! /bin/bash

echo "Enter a number"
read x

echo "Enter another number"
read y

sum=$((x+y))

echo "The sum of $x and $y is $sum"
```

### Conditional statements

The keywords used to write conditional statements in bash are:

- **if [ logical operation ]**: represents the condition that must be evaluated before proceeding
- **then**: indicates that the following commands must be executed when the if-condition (or elif-condition) is satisfied
- **elif [ logical operation ]**: in case that the if-condition was not satisfied, evaluate the logical operation in the brackets before proceeding
- **else**: if neither of the if- or elif-conditions were satisfied, evaluate the following commands
- **fi**: end of the conditional statement

The general syntax looks like this:

```sh
if [ condition ]
    then
         ...commands
elif [ condition ]
    then
        ...commands
else
    ...commands
fi
```

**Note the space surrounding each bracket**

Let's look at the following example. The user is prompted to enter two numbers and the script must find out which of the numbers is bigger. If the difference between the first and second number is negative, then the second number must be bigger, else the first one must be the bigger one. If it is 0, then the numbers are equal.

```sh
#! /bin/bash

echo "Enter a number"
read x

echo "Enter another number"
read y

dif=$((x-y))

if [ $dif -gt 0 ]
    then
        echo "$x is bigger than $y"
elif [ $dif -lt 0 ]
    then
        echo "$x is smaller than $y"
else
    echo "$x is equal to $y"
fi
```

It is important to note that evaluating multiple logical operations in a single condition requires the use of double brackets `[[ logical_op1 && logical_op2 ]]`. Upgrading the previous example to check if the first number is positive and determine if it is bigger than the other:

```sh
#! /bin/bash

echo "Enter a number"
read x

echo "Enter another number"
read y

if [[ $x -gt 0  &&  $x -gt $y ]]
    then
        echo "$x is positive and bigger than $y"
elif [[ $x -gt 0  && $x -lt $y ]]
    then
        echo "$x is positive, but smaller than $y"
else
        echo "$x is negative"
fi
```

**Note the spacing around the brackets**

You can find a cheat sheet with the logical operators in bash provided by [kapeli.com](https://kapeli.com/cheat_sheets/Bash_Test_Operators.docset/Contents/Resources/Documents/index)

### For-Loops

For-loops are used to repeat a block of code several times. It is important that the number of repetitions must be known; it might be known only by the computer, not by you, but it is still known.
The general syntax of a for-loop is:

```sh

for variable_name in list_of_values
do
    commands
done

```

```sh
#!/bin/bash

for city in London Paris Berlin
do
	echo "$city"
done
```

When looping through numerical values, you can set the loop's boundary conditions as an interval defined with curly brackets and separated by two dots , i.e. `{start_value..end_value}`. For example,

```sh
#!/bin/bash

for i in {1..5}
do
    echo $i
done
```

A cool use-case for the for-loop is looping through all the arguments when you don't know how many they are.
I hope you remember that an argument is read by the script with `$` appended with the order in which it is received (i.e `$1`, `$2`). You can substitute the order number of the argument with an `@` to capture all available arguments ( i.e. $@ = `arg1 arg2 arg3`). Then if we run the script below with arguments - London, Paris and Berlin, the output will match the output of the cities example above.

```sh
#!/bin/bash

for x in $@
do
    echo "$x"
done
```

### While-Loops

For-loops are great but they are only useful when the number of repetitions (loops) that must be performed is known. When that number is unknown, you have to use a while-loop. It repeats a block of code as long as some condition is satisfied. The general syntax of a while-loop is:

```sh
while [ condition ] ; do
    commands
done
```

For example, say we want to count from 1 to a given number, which is entered by the user:

```sh
#!/bin/bash

read -p "Count to: " count_to

i=1
while [ $i -le $count_to ] ; do
   echo "$i"
  (( i += 1 ))
done

```

The script prompts the user to enter a number and starts counting from 1. While the current count number (`i`) is less than the user input (`count_to`), the loop will print the current count, add 1 to it and start over. When the current count (`i`) becomes bigger than the user input, the condition will no longer be satisfied and the code won't run the while-loop.

### CONCLUSION

In this article we used examples to show some of the main tools used in shell scripting. Starting with the execution of the shell script file, going through using variables and arguments, up to writing conditional statements and loops. However, there is a lot more to shell scripting and if you are interested in learning more about it, here is an in-depth guide by [Mendel Cooper](https://tldp.org/LDP/abs/html/) and a comprehensive cheat sheet on [devhints](https://devhints.io/bash).


A Shell script allows you to write a series of commands in a file and then once you run the file, each command will be executed by the shell automatically. This saves you time when performing repetitive tasks. Furthermore, there are numerous other use cases for shell scripting, such as installing and running programs, creating a program environment, scheduling data backups.

With shell scripting, you can write a series of commands in a file and then once you run the file, each command will be executed by the shell automatically. This allows you to perform repetitive tasks more efficiently.There is a wide range of other use cases of shell scripting, such as installing and running programs, creating a program environment, scheduling data backups, and many more. If you are interested in learning shell scripting, as you should, you have come to the right place. With no further delay, let's dive in!

Shell Scripting For Beginners


<Typography variant={"h5"}> What is SQL?</Typography>

Structured Query Language, or SQL, is a standard ANSI/ISO language for accessing and manipulating data stored in relational databases.

A relational database is a type of database which stores data in structured manner, in a table with columns. Each column can store a specific data type such as a string, an integer, a boolean, etc., or it can be linked (i.e. "related") to other tables within the same database through a key (usually an id) that is present in both tables. The key is called the **primary key** in the connected table and the **foreign key** in the connecting table.

For example, we have a table `school_class_8b` that contains the students in class 8b and their average grade (in percentage) in each subject that they study.

```
| student_id | mathematics | english | science | physical_education |
| ---------- | ----------- | ------- | ------  | ------------------ |
| 123        | 70          | 83      | 54      | 67                 |
| 234        | 63          | 67      | 75      | 98                 |
| 345        | 34          | 78      | 87      | 92                 |
```

Additionally, we have another table `students` which holds information about every student in the school.

```
| student_id | f_name | l_name   | year_of_birth | address           |
|------------|--------|----------|---------------|-------------------|
| 123        | John   | Doe      | 2001          | 67 Baker Str.     |
| 234        | Maria  | Santiago | 2001          | 98 Roberttown Ln. |
| 789        | Jane   | Doe      | 2000          | 8 Sunnybank Rd.   |
```

The tables are connected through the `student_id` key, which appears in both tables, and it serves as primary key in the `students` table and as foreign key in the `school_class_8b` table.

Some of the most popular database management systems that use SQL are Oracle, MySQL, Microsoft SQL Server and PostgreSQL.

<Typography variant={"h5"}> Why should you learn SQL?</Typography>
SQL was introduced in 1974 and has come a long way since. Currently, it is the most
widely used languge for quering data, and there is a high chance that you stumble
upon it in your workplace, even if your job does not directly involve working with
data.

Due to its popularity, SQL has been adopted in many database management systems and tools for analysis on large datasets. Although SQL knowledge is an essential tool frequently implemented by data analysts and data scientists, you will still benefit from knowing at least basic SQL, even if you are not a data analyst, as it will help you understand how a database is structured and how you can acquire certain pieces of information inside it. Additionally, you will be able to communicate more effectively with your colleagues who work directly with data.

In practice you might use an ORM framework (a.k.a. Object Relational Mapper) which will provide easier syntax; however, under the hood, it still builds an SQL statement based on your input. Therefore, having proper understanding of how SQL works can help you use the framework features more efficiently and select the quickest way to access the data you need.

<Typography variant={"h5"}> Top 5 Websites to learn SQL </Typography>
Recently I have started learning SQL and I want to share with you the resources that
I have found most useful to me.{" "}

1. [Mode](https://mode.com/sql-tutorial/)
2. [SQLBolt](https://sqlbolt.com/)

In my opinion, Mode and SQLBolt are the best resources because they both offer great explanations with clear examples and some practice questions after each article to help you use active recall for better memory retention.

3. [W3Schools](https://www.w3schools.com/sql/)

W3Schools is another great choice for obtaining information regarding the use of SQL, as the articles there are written concisely and provide good summaries of the information, which I find super useful for revision and for later reference. However, from my perspective, the practice questions were too simple and therefore less useful than the ones in other websites.

4. [DataLemur](https://datalemur.com/)

DataLemur is a website that provides interview questions for data scientists and naturally, it includes more complex problems, some of which require additional knowledge in statistics as well. Fortunately, each question is marked as easy, medium or hard, so that you can select the problems that suit your level of knowledge.
I do recommend this website for people with intermediate knowledge, though, since even the easy practice problems might be a little too challenging for complete beginners.

5. [Javatpoint](https://www.javatpoint.com/sql-vs-nosql)

Lastly, Javatpoint provides very detailed articles and clear examples; however, it offers no practice questions. If your learning style is not dependent on solving problems after each new topic, Javatpoint is still a great resource for learning SQL.

<Typography variant={"h5"}> Conclusion </Typography>
SQL has been here for more than three decades, and it is still in demand in many
data-related areas of industry. Due to its applicability, versatility, and user-friendliness,
SQL is the most popular language for data querying and manipulation. Learning it
can have numerous benefits, including having a clear idea of how data is structured,
accessed, and modified, being able to quickly learn frameworks that are based on
SQL; and improving performance by constructing fast and efficient query statements.


SQL has been here for more than three decades and it is still in demand in many data-related areas of industry. Due to its applicability, versatility and user-friendliness, SQL is the most popular language for data querying and manipulation.

SQL has been here for more than three decades and it is still in demand in many data-related areas of industry. Due to its applicability, versatility and user-friendliness, SQL is the most popular language for data querying and manipulation. In this article I share with you the top 5 best websites to learn sql.

Top 5 Websites to learn SQL


Do you ever find yourself using a library that lacks the API you require? I've lost track of how many utility functions
and adapters I've had to write that, in retrospect, should have been part of the third-party library in the first place.

This guide will not save you from having to write a utility function, but it will show you how to easily add functionality
to virtually any interface offered by a third-party library. The best approach to accomplish this in Kotlin is to use the
language's extension features. Extensions, as opposed to other prevalent design patterns such as decorators and adapters,
allow you to add new functionality to a class or interface in a simplified manner. You don't have to use inheritance or
delegation to add new functions and properties to classes. Instead, you can add them directly to the classes themselves.

Extensions can either be declared as functions or properties.

```kotlin
class Host(val name: String)

// extension function
fun Host.resolveIP() = "Resolving IP for $name"

// extension property
val Host.port
    get() = "3030 is the port for $name"
```

Once defined, the extensions can be used just like any other function or property of the class or interface to which
they belong. Public member functions and properties (e.g. `name`) can be used as part of the extension.

```kotlin
fun main() {
    val host = Host("example.com")

    println(host.name) // -> example.com

    println(host.resolveIP()) // -> Resolving IP for example.com

    println(host.port) // -> 3030 is the port for example.com
}
```

The extensions are not particularly useful in this scenario because the described functionality can be
incorporated into the `Host` class. On the other hand, they flourish in test frameworks
like [Kotest](https://github.com/kotest/kotest) and enable the rapid development of useful add-ons
like [custom matchers](https://kotest.io/docs/assertions/custom-matchers.html). Extending third-party libraries with
utility functions is another prevalent use case. In the next sections, we'll zero in on this specific aspect.

## Improving Mime4J

To give you a practical example, we will improve the [Mime4J](https://james.apache.org/mime4j) library.
Mime4J can read plain [RFC822](https://datatracker.ietf.org/doc/html/rfc822)
and [MIME](https://www.rfc-editor.org/rfc/rfc2045) email messages. One of its major drawbacks is that it lacks
predefined methods that return the HTML and plain text parts of a message. The intrinsic complexity of knowing MIME and
all of its non-standard implementations exacerbates this disadvantage.

While looking for a good solution to extract the HTML and text parts, I came across the
following [code](https://github.com/apache/james-project/blob/f0da59b65a846d9c2aae8b6a5f65c92150ad93a8/server/container/util/src/main/java/org/apache/james/util/mime/MessageContentExtractor.java)
hidden in the [Apache James](https://james.apache.org/) mail server: It has a 160-line class
called `MessageContentExtractor` to extract the content as well as a 50-line inner static class called `MessageContent`,
which is used to hold the data.

When you break down the `MessageContentExtractor`, you will see the following main conditions that identify the HTML and
plain text parts:

1. The body part has to be of type `TextBody`.
2. The `mime-type` has to be `text/plain` or `null` for the text part and `text/html` for the HTML part.
3. Furthermore, the processed part cannot be an attachment. This is determined by evaluating whether
   the `Content-Disposition` is `null`. Accepting a part with an inline Content-Disposition when it lacks a CID is an
   exception to this rule.

Now that we know what to look for, we can evaluate how we want to extend the Mime4J `Message` interface. From the
consumer's point of view, adding two new properties, `html` and `text` looks like the best solution. Both properties
return the content of their respective parts as a `String`.

```kotlin
val Message.text: String?
    get() = TODO()

val Message.html: String?
    get() = TODO()
```

### Implementing the search conditions

In the beginning, we will concentrate on point number one: find all body parts with the `TextBody` type. To actually do
this, we need some background information on how the `Message` interface is structured.

```
┌───────────────────┐     ┌───────────────────┐
│      Entity       │     │        Body       │
└───────┬───────────┘     └──────────┬────────┘
        │                            │
        │   ┌───────────────────┐    │
        └───►      Message      ◄────┘
            └───────────────────┘
```

`Message` inherits from both the `Entity` and `Body` interfaces. The `Entity` interface offers the methods required to
access the body (content) of a message, or the body parts in case of a multipart message. Additionally, the `Body`
interface indicates that the message itself can be part of a message body. Based on the previous points, we can conclude
that the `Message` interface represents a recursive data type. A message can be part of a message, which can likewise be
part of another message, and so on.

As a consequence, we must attach a function to the `Entity` interface in order to find the body part we are looking for. We'll call it `findTextBody`. This function will return any message body that is a text, even if it is in a text format (for example, CSS) that we are not interested in.

```kotlin
fun Entity.findTextBody(): TextBody? {
    // Check if Entity contains a TextBody. Return it if it does
    if (body is TextBody) {
        return body as TextBody
    }

    // Check if the message has multiple parts
    if (!isMultipart) {
        return null
    }

    // Call the findTextBody function recursively on all
    // body parts and return the first one that is not null,
    // or return null when no part is found
    return (body as Multipart).bodyParts
        .firstNotNullOfOrNull { it.findTextBody() }
}
```

After we've gone through the most significant section of our conditions, we can look for parts in plain text or HTML
format (our second condition). Our second condition said that the message body's MIME type must be `text/plain`
or `null` for the plain text part and `text/html` for the HTML part. To do this, all we have to do is add an extra
condition when our function finds a `TextBody`.

```kotlin
fun Entity.findTextBody(validMimeTypes: Set<String?>): TextBody? {
    // Added mimeType condition
    if (body is TextBody && mimeType in validMimeTypes) {
        return body as TextBody
    }

    if (!isMultipart) {
        return null
    }

    return (body as Multipart).bodyParts
        .firstNotNullOfOrNull { it.findTextBody(validMimeTypes) }
}
```

Now we can add our final condition:

> Furthermore, the processed part cannot be an attachment. This is determined by evaluating whether
> the `Content-Disposition` is `null`. An exception to this rule is accepting a part with an
> inline `Content-Disposition`
> when it lacks a CID.

As you can see, the condition contains two parts, which we can implement by adding two extension properties so that our
code stays clean and readable.

```kotlin
private val Entity.isNotAttachment
    get() = dispositionType == null

private val Entity.isInlinedWithoutCid
    get() = dispositionType == "inline" && header.getField(FieldName.CONTENT_ID) == null

fun Entity.findTextBody(validMimeTypes: Set<String?>): TextBody? {
    // Added extension properties to the condition
    if (body is TextBody && mimeType in validMimeTypes && (isNotAttachment || isInlinedWithoutCid)) {
        return body as TextBody
    }

    if (!isMultipart) {
        return null
    }

    return (body as Multipart).bodyParts
        .firstNotNullOfOrNull { it.findTextBody(validMimeTypes) }
}
```

The `private` modifier is added to both functions because they should only be accessible from the Kotlin file where the `findTextBody` function is declared.

### Extracting the content

Let's add our new function to the extension properties we set up at the start.

```kotlin
val Message.text: String?
    get() {
        val textBody = findTextBody(setOf("text/plain", null)) ?: return null

        return TODO()
    }

val Message.html: String?
    get() {
        val textBody = findTextBody(setOf("text/html")) ?: return null

        return TODO()
    }
```

All that we have left now is to convert the `TextBody` into a `String`. We achieve this by writing the `TextBody` into
a `ByteArrayOutputStream` and converting it to a `String` based on the `TextBody` charset. If the charset name is
invalid, we will use the default charset (ASCII).

```kotlin
private val TextBody.content: String
    get() {
        val byteArrayOutputStream = ByteArrayOutputStream()

        writeTo(byteArrayOutputStream)

        return String(byteArrayOutputStream.toByteArray(), contentCharset)
    }

private val TextBody.contentCharset
    get() = try {
        Charset.forName(mimeCharset)
    } catch (e: IllegalCharsetNameException) {
        Charsets.DEFAULT_CHARSET
    } catch (e: IllegalArgumentException) {
        Charsets.DEFAULT_CHARSET
    } catch (e: UnsupportedCharsetException) {
        Charsets.DEFAULT_CHARSET
    }
```

### The final result

To finish our extension properties, we can access the `content` extension property of the `TextBody`.

```kotlin
val Message.text: String?
    get() {
        val textBody = findTextBody(setOf("text/plain", null)) ?: return null

        return textBody.content
    }

val Message.html: String?
    get() {
        val textBody = findTextBody(setOf("text/html")) ?: return null

        return textBody.content
    }
```

The implementation of our two new extension properties is now complete. We can use them as part of the `Message` interface.

```kotlin
fun main() {
    val textPart = BodyPartBuilder.create()
        .setBody("plain text content", "plain", Charsets.UTF_8)
    val htmlPart = BodyPartBuilder.create()
        .setBody("<html><body>content</body></html>", "html", Charsets.UTF_8)

    val multipart: Multipart = MultipartBuilder.create("alternative")
        .addBodyPart(textPart)
        .addBodyPart(htmlPart)
        .build()

    val message = Message.Builder.of()
        .setBody(multipart)
        .build()

    println(message.text) // -> plain text content
    println(message.html) // -> <html><body>content</body></html>
}
```

## Conclusion

Extensions in Kotlin are a powerful technique for implementing utility functions for third-party libraries. In this
particular situation, they assisted us in reducing a 210-line Java class to approximately 50 lines of readable and
maintainable Kotlin code\*. If you want to see the entire code, check out
this [Github gist](https://gist.github.com/spoptchev/e0821c4bf39032eb1f5f208f2f8fd8d8).

Here are a few general recommendations when you are getting started with Kotlin extensions:

- When you can put the properties or functions directly into the class or interface, don't use extensions.
- Expose the bare minimum set of functions or properties as extensions. Everything else should be kept private.
- Don't forget that extension functions are resolved statically. So, mocking them in a test is only possible when you
  use libraries like `PowerMock` or `MockK`.
- Another common pitfall is that extension functions are invoked based on expressions and not types. A good example can
  be found [here](https://kotlinlang.org/docs/extensions.html#extensions-are-resolved-statically).

Thank you for following me on this journey.

\*) The Java code also includes logic for loading plain text and HTML depending on the multipart type (`alternative`
, `related`, etc.). As a result, the comparison on the number of lines may not be fair in this case, but is
still a pretty good indicator how Kotlin improves our development experience.


In this article we discuss the use of Kotlin extensions to add functionality to third-party library interfaces. Extensions allow developers to add new functions and properties to classes without the need for inheritance or delegation.

How to improve third-party libraries with Kotlin extensions


Keycloak comes preconfigured with a number of industry-standard providers, themes, and connectors. These built-in features are fairly robust, but they may not always be sufficient. To implement custom features, Keycloak allows you to use a number of service provider interfaces ([SPI](https://en.wikipedia.org/wiki/Service_provider_interface)). By extending them, you can add a new social identity provider or make a unique form action to tell the difference between human and automated access.

## Key concepts

There are two fundamental components that make up a custom Keycloak service provider: a `ProviderFactory` and the actual `Provider` itself.

### ProviderFactory

As implied by its name, the `ProviderFactory` is the component that is in charge of actually creating the `Provider`. The factory will be discovered once the Keycloak server is launched, and only **one** instance of it will exist for the duration of the server's operation. Its interface, limited to the essential bits, is as follows:

```java
public interface ProviderFactory<T extends Provider> {

    void init(Config.Scope config);

    void postInit(KeycloakSessionFactory factory);

    void close();

    T create(KeycloakSession session);

    // not mentioned: getId, order, getConfigMetadata

}
```

Now, let's examine each method in greater depth.

#### void init(Config.Scope config)

During the initialization of the factory, `init` will be called once and only once. The configuration will be obtained from the `keycloak_server.json` file. You can use this method to initialize and create objects that will be utilized in your implementation of the provider. To illustrate, HTTP clients and database clients are two examples of objects that should almost never be created more than once.

#### void postInit(KeycloakSessionFactory factory)

After all provider factories have been initialized, the function `postInit` will be invoked. You can now access any additional `ProviderFactories` and SPIs that you require. Further more, if your business logic calls for it, you might also initialize recurring tasks.

#### void close()

The `close` method is called when the server shuts down. Resources, such as HTTP clients, created in the `init` or `postInit` methods should be released here.

#### T create(KeycloakSession session)

This is the method that creates the actual provider instance. Keycloak is calling this method on each **request** so the provider object itself should be light-weight.

### Provider

Each time a request is made, Keycloak invokes the `create` function on the `ProviderFactory` to generate a new provider object. In the provider, you'll implement the business logic of the functionality you want to add to your system. The only truly essential part of the interface is the `close` method, which frees up any resources that were allocated for the request but are no longer in use. Other methods will depend on the actual provider interface you want to implement.

### Provider discorvery

To tell Keycloak where to find the `ProviderFactory`, you have to set up a file in `META-INF/services` named after the specific service provider implementation and the fully qualified name of your service `ProviderFactory` as the file content.

## Anti-Patterns

Having covered the fundamentals of what a custom provider should look like, we can now examine bad practices that may arise while developing a Keycloak extension.

<Typography variant={"h6"} id={"ap-1"} sx={{ fontWeight: "700" }}>
  AP#1 - Implementing ProviderFactory and Provider in the same class{" "}
</Typography>

Take a look at the following example, in which a `ProviderFactory` and a `Provider` are implemented in the same class.

```java
class AntiPatternProvider implements ProviderFactory<AntiPatternProvider>, Provider {

    private HTTPClient httpClient;

    @Override
    public AntiPatternProvider create(KeycloakSession session) {
        httpClient.post("https://example.com");

        return this;
    }

    @Override
    public void init() {
        httpClient = new HTTPClient();
    }

    @Override
    public void close() {
        httpClient.close();
    }

    // other implementation specific functions...
}
```

Yes, it would appear odd, but in theory, this is a legitimate provider. Can you identify any potential issues?

The server will start up without any problems, but as soon as the provider receives a second request, an error message stating that the HTTP client has already been closed will appear. Keycloak has no means of knowing that we only want to close the HTTP client when the server is shutting down. Instead, each request will result in the client closing. This is because we are implementing the `close` method of both the `ProviderFactory` and the `Provider`, which, as we have seen, have different responsibilities.

We can avoid the issue by implementing the `Provider` and the `ProviderFactory` in separate classes.

```java
class BestPracticeProvider implements Provider {

    private final HTTPClient httpClient;

    public BestPracticeProvider(HTTPClient httpClient) {
        this.httpClient = httpClient;
    }

    @Override
    public void close() {
        // This method will be called on each request.
        // Do not close the HTTP client here!
    }
}

class BestPracticeProviderFactory implements ProviderFactory<BestPracticeProvider> {

    private HTTPClient httpClient;

    @Override
    public BestPracticeProvider create(KeycloakSession session) {
        return new BestPracticeProvider(httpClient);
    }

    @Override
    public void init() {
        httpClient = new HTTPClient();
    }

    @Override
    public void close() {
        // The server is shutting down.
        // We can safely close the HTTP client.
        httpClient.close();
    }

    // other implementation specific functions...
}
```

<Typography variant={"h6"} id={"ap-2"} sx={{ fontWeight: "700" }}>
  AP#2 - Creating heavy-weight objects during requests
</Typography>
In the example below, we will look at another anti-pattern that may arise while creating
a provider.

```java
class AntiPatternProvider implements Provider {

    private final HTTPClient httpClient;

    public AntiPatternProvider() {
        httpClient = new HTTPClient();
    }

    @Override
    public void close() {
        httpClient.close();
    }
}

class AntiPatternProviderFactory implements ProviderFactory<AntiPatternProvider> {

    @Override
    public AntiPatternProvider create(KeycloakSession session) {
        return new AntiPatternProvider();
    }

    // other implementation specific functions...
}
```

In this provider implementation, the HTTP client is created and closed during each request. The issue is that the client is a heavy object. Creating it for every request is expensive. Similarly to how we fixed [AP#1](#ap-1), we need to have the `ProviderFactory` handle both the creation and closing of the HTTP client.

## Conclusion

Keycloak offers a lot of possibilities to extend its built-in functionality. Anyone working on an extension should familiarize themselves with the [Keycloak SPI](https://www.keycloak.org/docs/latest/server_development/#_providers) first. In my opinion, Keycloak's documentation and examples aren't great, especially for developers who are just getting started.

So, here are a few general recommendations when you are starting out:

- Treat each provider as a self-contained application.
- Keep an eye out for resources that have to be released once the server is shut down or the request is finished. Otherwise, you may unintentionally create memory leaks.
- Avoid having multiple providers in the same library whenever possible. Instead, try to split them up per domain. This will make it easier to test, maintain, and deploy them.
- Keep your providers up to date with the latest Keycloak version.
- Do not package external libraries with [shadowJar](https://github.com/johnrengelman/shadow) (only applies to the Quarkus distribution). Instead, add the libraries to the `providers` directory.


Learn the essential concepts and avoid common mistakes when writing Keycloak extensions. This comprehensive guide covers the key principles of Keycloak extension development and provides examples of antipatterns to steer clear of. Get expert tips on creating effective, efficient and secure Keycloak extensions.

Learn the essential concepts and avoid common mistakes when writing Keycloak extensions. This guide covers the key principles of Keycloak extension development.

Writing Keycloak extensions: Key concepts and anti-patterns


When we decided to implement a blog feature to the Zone 2 Technologies webpage, our team conculded it would be best to use MDX for writing the content of articles as it brings together the ease of use of regular Markdown language and allows the use of custom components.

In this article we walk you through the process of creating a simple blog app using the popular React framework [NextJS](https://nextjs.org), [`gray-matter`](https://www.npmjs.com/package/gray-matter) and [`next-mdx-remote`](https://www.npmjs.com/package/next-mdx-remote).

<Box
  sx={{ fontFamily: "Roboto", a: { textDecoration: "none", color: "#248783" } }}
>
  ### Table of Contents

- [What is MDX?](#mdx)
- [Setup a simple NextJS app](#create-nextjs-app)
- [Use gray-matter to extract metadata from mdx file](#use-graymatter)
- [Use next-mdx-remote to compile html](#next-mdx-remote)
- [Add code highlighting with rehype-highlight](#code-highlight)
- [Improve the SEO of your app](#improve-seo)

</Box>

<Typography variant={"h5"} id={"mdx"}>
  What is MDX?
</Typography>

MDX is a format which combines JSX and Markdown. Markdown is easier to write than HTML and is therefore the preferred option for writing content such as blog posts.
JSX, on the other hand, is an extension of JS which looks like html and allows the reuse of components.

<Typography variant={"h5"} id={"create-nextjs-app"}>
  Setup NextJS app
</Typography>

1.0. To create a NextJS app run the following command in your terminal:

```shell
npx create-next-app@latest
```

2.0. Create a `/src` folder at the root of the project and move the folder `/pages` inside it, so the project structure is as follows:

```
 ┣ node_modules
 ┣ public
 ┣ src
 ┃  ┣ pages
 ┃  ┃ ┣ _app.js
 ┃  ┃ ┗ index.js
 ┣ .gitignore
 ┣ next.config.js
 ┣ package-lock.json
 ┣ package.json
 ┣ README.md
```

3.1. Create a `/posts` folder and add a few articles inside it:

```
  ┣ node_modules
  ┣ public
  ┣ src
  ┃  ┣ pages
  ┃  ┃ ┣ [id].jsx
  ┃  ┃ ┣ _app.js
  ┃  ┃ ┗ index.js
  ┃  ┣ posts
  ┃  ┃ ┣ article-1.mdx
  ┃  ┃ ┗ article-2.mdx
  ┣ .gitignore
  ┣ next.config.js
  ┣ package-lock.json
  ┣ package.json
  ┣ README.md
```

3.2. Example content for the `article-1.mdx` and `article-2.mdx` :

```md
---
title: "Article 1"
id: "article-1"
---

## This is article 1
```

**Note:** Make sure that the `id` meta tag matches the name of the mdx file as it will be used in dynamic routing later on.

4.0. Create a `/services` folder in `/src` and add a JavaScript file `blog-services.js`:

                ```
                ┣ node_modules
                ┣ public
                ┣ src
                ┃  ┣ pages
                ┃  ┃ ┣ [id].jsx
                ┃  ┃ ┣ _app.js
                ┃  ┃ ┗ index.js
                ┃  ┣ posts
                ┃  ┃ ┣ article-1.mdx
                ┃  ┃ ┗ article-2.mdx
                ┃  ┗ services
                ┃    ┗ blog-services.js
                ┣ .gitignore
                ┣ next.config.js
                ┣ package-lock.json
                ┣ package.json
                ┣ README.md

                ```

<Typography variant={"h5"} id={"use-graymatter"}>
  Use gray-matter to extract metadata from mdx file
</Typography>

5.0. Now that we have the project structure let's install the packages we need to compile html from the mdx:

    - [`gray-matter`](https://www.npmjs.com/package/gray-matter) : Used to separate the metadata and content of markdown
    - [`next-mdx-remote`](https://www.npmjs.com/package/next-mdx-remote) : Used to compile html and display it on the page
    - [`rehype-highlight`](https://www.npmjs.com/package/rehype-highlight) : Used to add highlight to code blocks

```shell
npm i gray-matter next-mdx-remote rehype-highlight
```

6.0. In `/src/services/blog-services.js` write a function which will receive the filename (id) of an article, read it and return its metadata and content.
To achieve this use the `matter()` function from the `gray-matter` package

```js
import matter from "gray-matter";
import { join } from "path";
import * as fs from "fs";

export async function getArticleById(fileId) {
  const postsDirectory = join(process.cwd(), "./src/posts");
  const fullPath = join(postsDirectory, `${fileId}.mdx`);

  const fileContents = fs.readFileSync(fullPath, "utf8");

  const { data, content } = matter(fileContents);
  return { ...data, content };
}
```

7.0. Now that we have extracted the content of the article, we need another function to list all of the articles stored in the `/posts` directory. In the same file add the following:

```js
export async function getAllArticles() {
  const articlesList = [];
  const postsDirectory = join(process.cwd(), "./src/posts");
  const filesList = fs.readdirSync(postsDirectory);

  for (let fname of filesList) {
    const id = fname.replace(/\.mdx$/, "");

    const articleInfo = await getArticleById(id);
    articlesList.push({ ...articleInfo });
  }
  return articlesList;
}
```

8.0. We can now access the metadata and read the content of each article. Awesome!
Let's display the articles on our homepage. What we have to do is use the `getStaticProps()` function to load all available articles and pass them down to the component as props.
In the `/src/pages/index.js` write the following:

```js
import { getAllArticles } from "../services/blog-services";

export async function getStaticProps() {
  const articles = await getAllArticles();
  return { props: { articles } };
}

export default function Home({ articles }) {
  return (
    <>
      <h1>Blog Articles:</h1>

      {articles.map((article, key) => (
        <div key={key}>
          <p>{article.title}</p>
          <a href={`/${article.id}`}> Read More</a>
        </div>
      ))}
    </>
  );
}
```

**Note:** Don't forget to add the `key` attribute when looping through elements!

<Typography variant={"h5"} id={"next-mdx-remote"}>
  Use next-mdx-remote to compile html
</Typography>

9.0. In order to access each article inividually, we will use dynamic routing. If you are not familiar with dynamic routing I advise you to look it up in the [NextJS Documentation](https://nextjs.org/docs/routing/dynamic-routes).

9.1. Create a `/src/pages/[id].jsx` file and export a component which will be used as a template for each article. The component must receive the article as props, so that let's begin with
the `getStaticProps()` function. The id of the article is accessible through the `context`. In order to display the content from mdx we need to compile it to html first. To do so, use the `serialize()` function from the `next-mdx-remote` package.

```js
import { getArticleById } from "../services/blog-services";
import { getAllArticles } from "../services/blog-services";

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";

export async function getStaticProps(context) {
  const { id } = context.params;
  const articleInfo = await getArticleById(id);

  const serializedPost = await serialize(articleInfo.content);
  return {
    props: {
      ...articleInfo,
      source: serializedPost,
    },
  };
}
```

9.2. When using dynamic routing we need to use the `getStaticPaths()` function to generate a route for each article. So, let's add one:

```js
export async function getStaticPaths() {
  const allPosts = await getAllArticles();
  let allPostIds = allPosts.map((post) => `/${post.id}`);

  return {
    paths: allPostIds,
    fallback: false,
  };
}
```

9.3. And finally, the `Article` component itself. Since we are using the `next-mdx-remote` package, we have to import the `MDXRemote` component and pass down the serialized content to it like shown:

```js
const Article = (article) => {
  return (
    <>
      <h1>{article.title}</h1>
      <MDXRemote {...article.source} components={{}}></MDXRemote>
    </>
  );
};

export default Article;
```

9.4 It is **important to note** that if there are any **imported components inside the mdx file** you have to pass them down the `MDXRemote` through the **`components` attribute**. To make it clear let's add a custom image component.

10. Add a `/src/components/ImageCard.jsx` with the following code:

```js
export default function ImageCard({
  imageSrc,
  altText,
  width = "200px",
  height,
}) {
  console.log(imageSrc);
  return height ? (
    <img src={imageSrc} alt={altText} width={width} height={height} />
  ) : (
    <img src={imageSrc} alt={altText} width={width} />
  );
}
```

11. To use the component inside the mdx file, simply add it as a JSX tag, e.g.:

```md
---
title: "Article 1"
id: "article-1"
---

## This is article 1

<ImageCard imageSrc="https://images.pexels.com/photos/1001682/pexels-photo-1001682.jpeg" altText="sea">
```

**Note:** Notice that you don't have to explicitly import the component in the mdx file.

12. In order to use the `<ImageCard>` you have to import it in the `[id].jsx` file and pass it down the `MDXRemote` component through the `components` attribute (i.e. `components={{ ImageCard }}`):

```js
import { getArticleById } from "../services/blog-services";
import { getAllArticles } from "../services/blog-services";

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";
import { ImageCard } from "../components/ImageCard";

export async function getStaticProps(context) {
  const { id } = context.params;
  const articleInfo = await getArticleById(id);

  const serializedPost = await serialize(articleInfo.content);
  return {
    props: {
      ...articleInfo,
      source: serializedPost,
    },
  };
}

export async function getStaticPaths() {
  const allPosts = await getAllArticles();
  let allPostIds = allPosts.map((post) => `/${post.id}`);

  return {
    paths: allPostIds,
    fallback: false,
  };
}

const Article = (article) => {
  return (
    <>
      <h1>{article.title}</h1>
      <MDXRemote {...article.source} components={{ ImageCard }}></MDXRemote>
    </>
  );
};

export default Article;
```

<Typography variant={"h5"} id={"code-highlight"}>
  Add code highlighting with rehype-highlight
</Typography>

13.1. Congratulations! Now our blog is fully functional. However, if we want it to
look better, we can add code highlighting theme with the `rehype-highlight` package.

We already inastalled the package in step 5.0., so what remains to be done is select
a theme and import it in `/src/pages/[id].jsx`. You can check out the available themes on
[https://highlightjs.org/static/demo](https://highlightjs.org/static/demo/). Our theme of choice is Agate:

```js
import rehypeHighlight from "rehype-highlight";
import "highlight.js/styles/agate.css";
```

13.2. Lastly, add the `rehypeHighlight` as plugin to the serialize function.

```js
const serializedPost = await serialize(articleInfo.content, {
  mdxOptions: {
    rehypePlugins: [rehypeHighlight],
  },
});
```

With this final step, the complete `[id].jsx` file looks like this:

```js
import { getArticleById } from "../services/blog-services";
import { getAllArticles } from "../services/blog-services";

import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote } from "next-mdx-remote";
import ImageCard from "../components/ImageCard";

import rehypeHighlight from "rehype-highlight";
import "highlight.js/styles/agate.css";

export async function getStaticProps(context) {
  const { id } = context.params;
  const articleInfo = await getArticleById(id);

  const serializedPost = await serialize(articleInfo.content, {
    mdxOptions: {
      rehypePlugins: [rehypeHighlight],
    },
  });
  return {
    props: {
      ...articleInfo,
      source: serializedPost,
    },
  };
}

export async function getStaticPaths() {
  const allPosts = await getAllArticles();
  let allPostIds = allPosts.map((post) => `/${post.id}`);

  return {
    paths: allPostIds,
    fallback: false,
  };
}

const Article = (article) => {
  return (
    <>
      <h1>{article.title}</h1>
      <MDXRemote {...article.source} components={{ ImageCard }}></MDXRemote>
    </>
  );
};

export default Article;
```

<Typography variant={"h5"} id={"improve-seo"}>
  Improve the SEO of your blog
</Typography>

SEO (Search Engine Optimisation) is the process of improving the visibility of a page on search engines.
Search Engines use bots to crawl the web and collect information about each page and store it for further reference,
so that it can be used to retrieve the respctive webpage when it is being searched.

SEO is critical part of digital marketing as people often conduct search with commercial intent - to obtain information about a product/service.
Ranking higher in search results can have an imense impact on the success of a business.

Fortunately, NextJS supports a component `<Head>`, which allows you to pass `<meta>` tags to your pages.
In our blog app we can improve the SEO by adding some meta tags describing the article.

First, let's add more information to the metadata of the article, which we will use in the meta tags:

```md
---
title: "Article 1"
description: "This is a very interesting and informative article"
author: "John Doe"
img: "https://images.pexels.com/photos/1001682/pexels-photo-1001682.jpeg"
id: "article-1"
---

## This is article 1

<ImageCard imageSrc="https://images.pexels.com/photos/1001682/pexels-photo-1001682.jpeg" altText="sea"/>
```

Finally, in the `/src/pages/[id].jsx` import the `<Head>` tag and populate it with the metadata from props:

```js
import Head from "next/head";

const Article = (article) => {
  return (
    <>
      <Head>
        <meta property="og:title" content={article.title} key="ogtitle" />
        <meta
          property="og:description"
          content={article.description}
          key="ogdesc"
        />
        <meta property="og:image" content={article.img} key="ogimage" />
        <meta
          property="og:url"
          content={`https://www.my-blog.com/${article.id}`}
          key="ogurl"
        />
        <meta property="og:type" content="article" key="ogtype" />
        <title>{`Blog | ${article.title}`}</title>
      </Head>
      <h1>{article.title}</h1>
      <MDXRemote {...article.source} components={{ ImageCard }}></MDXRemote>
    </>
  );
};

export default Article;
```

With this our blog app is complete.

#### Thank you for reading this article. I hope it has been helpful to you.


In this article you will learn how to create a simple blog app using the popular React framework NextJS, gray-matter and next-mdx-remote.

In this article you will learn how to create a simple blog app using the popular React framework NextJS and parse the content of MDX files with gray-matter and next-mdx-remote.

Blog