Topics​

• Problem Description
• Dockerfile and SQL script
• Build and Run
• Validate the table is there exec
• Conclusion

This blog post won't go through what Docker or containerization is, and all images are pulled from DockerHub.

Problem Description​

Some Context​

I was recently working on a side project in an attempt to learn a new language and I wanted to build a simple REST API with the language.
I wanted to use PostgresSQL as my SQL database. I was to using the Postgres Docker image to achieve this.

The Problem​

Then I had a problem: How can I create tables on container creation so I don't need to manually create tables in the running container because that would want me to use: docker exec -it <Postgres-Container-ID> sh so I can open the container's shell to do this:

# In postgres docker conatiner:
psql -U postgres # connect to postgres cli as default user postgres.

#  result of psql -U postgres:
postgres=# 

# manually write postgres queries here...

This would've meant everytime I remove the postgres container with a command like docker rm <postgres-container-id> then I will always need to do the creation of my tables AGAIN!! That isn't ideal.

Lucky for me, the Docker postgres image has a way to run a script on initial creation of the container. Let's see how we can use that to at least always create a container with the desired database tables.

Dockerfile and SQL script.​

The Dockerfile​

The Dockerfile we are going to use will be using the Postgres image from DockerHub as the base image and will look like this:

FROM postgres:latest

# populate database and password arguments so we don't use the default values.
ENV POSTGRES_DB=initdb
ENV POSTGRES_PASSWORD=initpassword

# copying the sql script into docker-entrypoint-initdb.d to be run when the container is created. 
COPY ./scripts/create-initial-tables-if-not-exists.sql /docker-entrypoint-initdb.d/

The COPY instruction is where we copy our script into the image we are building. This will take our sql into the docker-entrypoint-initdb.d directory.
That is the directory which will be inspected on container initial creation.

The environment variables POSTGRES_DB and POSTGRES_PASSWORD will be used by postgres to:

• Create a database called initdb (default database is postgres)
• Create a password for the default user in postgres called postgres.

So we are essentially just overriding default values here. You can read up about the default environment variables and what they imply here

The SQL script​

You can store this SQL script anywhere, as long as your Dockerfile will be able to access it. I store mine in the root where I have my Dockerfile.
It's in a directory that I chose to call scripts, this can be any name you like.

The script looks like this:

-- connect to initdb that will be created by our Dockerfile
\c initdb;

-- Create init_user table in the initdb database
CREATE TABLE IF NOT EXISTS init_user (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    firstname VARCHAR(255) NOT NULL,
    surname TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

The script connects to the initdb database using \c initdb the command \c is a Postgres command to connect to a database. We then create a simple init_user table in the database named initdb that we specified as the POSTGRES_DB environment variable.

Build and Run​

Building the image​

To build our Dockerfile we simply go:

# build dockerfile (assuming the shell is open in the same directory as the Dockerfile):
docker build .

# tag image for ease of reading 
docker tag <built-image-id> localhost/init_postgres

You can find the built-image-id by running docker images and then copying the latest built image.
Now that the image is built, we can then use it to create a container i.e. an instance of the image.

Running the Image (Creating the container):​

To run the container it's as simple as doing a docker run, here's how:

# docker run will create a new container from this built image
docker run localhost/init_postgres

This will create your container and you will see postgres logs. Then look for log lines like these:

server started
CREATE DATABASE


/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/create-initial-tables-if-not-exists.sql
You are now connected to database "initdb" as user "postgres".
CREATE TABLE

From these lines we can see that we connected to the initdb database as the default user (postgres).
Another cool thing is we can see the line:
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/create-initial-tables-if-not-exists.sql
which validates that our script is ran.

Validate the table exits (exec).​

At this point we can rest assured that our database is created but how do we validate? We can exec into the running container.
To exec into the container allows us to go into the running container and do some tasks like checking logs, filesystem and even run some Postgres CLI commands.

First we need to get the created container's id by running: docker ps then we can see something like this:

CONTAINER ID   IMAGE                     COMMAND                  CREATED         STATUS         PORTS      NAMES
496a74be5e61   localhost/init_postgres   "docker-entrypoint.s…"   7 minutes ago   Up 7 minutes   5432/tcp   loving_leavitt

Then copy the the CONTAINER ID then run the exec command: docker exec -it 496a74be5e61 sh. This opens a shell/terminal in the container we then need.
After this we will be in the container, then we need to login as the default user (postres) to the Postgres CLI in the container using the command: psql -U postgres

This will open a CLI with a prefix: postgres=# then we can run the following commands to connect and view the table

# connect to the initdb database
postgres=# \c initdb

# list all tables:
postgres=# \dt

# result of the table list operation:
           List of relations
 Schema |   Name    | Type  |  Owner   
--------+-----------+-------+----------
 public | init_user | table | postgres
(1 row)

From here we can see that the table was created and we can work with it however we want. You can type exit into your terminal until you exit both postgres CLI and the container's shell.

Conclusion.​

On this blog post we pretended to understand how we can use the Postgres docker image to create tables on initial creation of a container.
This is helpful for situation where we want to create a table every time we want create a container and we don't want to do it manually.
REMINDER: THIS IS USEFUL FOR PLAYING AROUND PROJECTS OR LOCAL INSTANCES FOR LOCAL DEVELOPMENT as it doesn't scale.
If we add more tables or columns we will need to rebuild and re-run the image thus lossing data that we already have in the database container.

With that being said, keep pretending until you are not, until the next time!

Topics​

• Brief explanation of the useEffect Hook
• A word on dependencies array
• My Silly Error

Before we dive into the details I would like to say React has a good documentation on the UseEffect hook, I'd recommend that as a source of learning about the hook, here I will be just focusing on the error I made so then enjoy, you beautiful reader!

Brief explanation of the useEffect Hook​

The useEffect(setup, dependencies) function is a React hook, a hook is a React function that allows you to use React features like state where you want to store the state of a certain variable on every re-render of a component. The useEffect is used to reach out to external services from our React component.

A good example would be to get data from a REST API so we can display in our component, other tasks would be to do some operations on a file system which is external to our React app, something like reading a file.

The React useEffect hook is called within the body of a React component or custom hook we defined, it has two arguments setup and dependencies. The setup is a function we pass that will be called when our useEffect is triggered. The dependencies is an array of dependencies, can be ignore, empty or have a known list of dependencies.

A simple example of the react useEffect in action would look like this:

const myReactComponent = (props) => {
    useEffect(() => {
        //set up method
        //call api, go to file system, reach out to the DOM
    }, []);

    return (<div>Some Content here</div>);
}

We can also optionally return a clean up function in our useEffect hook, a clean up method is a method that is called after the set up is done doing it's task. A clean up function can be used like so:

const myReactComponent = (props) => {
    useEffect(() => {
        //set up method
        //call api, go to file system, reach out to the DOM

        return () => {
            //body of clean-up
            //do some clean up like closing connections etc.
        }
    }, []);

    return (<div>Some Content here</div>);
}

For more info about the clean up method please refer to the React docs, I don't want to dwell on it here, so sorry. Something I want us to dwell in is the dependencies array argument that I have purposefully left of the convo.

A word on dependencies array​

The dependencies array is an optional parameter we pass along with the setup function in the useEffect function. The array lists the dependencies that will cause the useEffect to be called when they change, there are some cases that cause the useEffect to behave a certain way, the cases are as follows:

No dependencies specified:​

const myReactComponent = (props) => {
    useEffect(() => {
        //set up method
        //call api, go to file system, reach out to the DOM

        return () => {
            //body of clean-up
        }
    }); // no dependencies array

    return (<div>Some Content here</div>);
}

When no dependencies are specified this tells React to call the useEffect on every re-render that happens in the component, re-renders are consequence of state changes or page reloads, state variables are specified with useState() which I won't dwell on here. This is desirable if you want useEffect to be called when any of state varibales changes for whatever reason.

Empty dependencies array​

const myReactComponent = (props) => {
    useEffect(() => {
        //set up method
        //call api, go to file system, reach out to the DOM

        return () => {
            //body of clean-up
        }
    }, []); //empty array

    return (<div>Some Content here</div>);
}

When an empty array is passed this tells React to run the useEffect after initial render of the component and never again, this is ideal for situations where we want to do some external task on initial load of the component then never again, like fetching a file once when the component comes up on the screen and never wanting to fetch the file ever again until we remove the component from the view.

Specifying dependencies​

const myReactComponent = (props) => {
    const [message, setMessage] = useState('');
    const otherMessage = '';

    useEffect(() => {
        //set up method
        //call api to save message to db

        return () => {
            //body of clean-up
        }
    }, [message, otherMessage]); //dependency


    //some code that potentially changes the message or otherMessage variables

    return (<div>Some Content here</div>);
}

When a dependency is specified this tells React that when this value changes run the code in the useEffect, the useEffect will run once after initial render and again unless the message state or otherMessage variable changes.

If you look carefully I have two dependencies, message and otherMessage, this is to drive an important point, variables that are defined within the component body including props are called reactive variables and are the only objects/variables that can be dependencies to a useEffect, please see this for more info.

This final case is the reason I did my silly mistake. Let's see how.

My Silly Error​

If we refer to the previous case above we can see that: When a dependency is specified this tells React that when this value changes run the code in the useEffect.

My mistake was I had a state variable which I set as a dependency that got set by the setup code in the useEffact on initial render of the app, after the setup changed my state variable then the useEffect detacted a change on the dependency then called the setup, which caused a change on the dependency again, and the useEffect detected another change and so on and so on.

A little Diagram To Help​

The below diagram shows the high level of how the error works:

To explain what is happening here:

• First I created a state variable and initialized it as an empty array.
• Then I set it as a dependency is my useEffect(), so if this state variable changed, the useEffect will be called.
• The useEffect has a setup method that changes the state variable's value (this is the bug btw. I indicated the change here by showing an array with values 1,2, and 3).
• After the initial change, my useEffect realized; "hey the dependency has changed, let me call the setup again!". The setup changed the var again and useEffect was like: "okay I need to call the setup again!". This continued nonstop and thus the infinite loop 😂

Conclusion​

React offers some useful functions called hooks that allow us to use some React's useful features like state. The useEffect hook is one of those hooks which allows us to do some external tasks that we can't normally do from our React component's code, this includes and not limited to: calling a remote service, reaching out to the DOM, reading a file system. The useEffect uses normal JavaScript/TypeScript code inside it's setup to do tasks.

Topics​

• Reading the Configuration (Bind, Configure and Configuration[string-value])
• The WebAPI For Testing
• How Each Method Handle Changes.
• What to use?
• Conclusion

All code referenced in this blog post can be found here. Microsoft has good documentation on this which can be found here

Reading the Configuration (Bind, Configure and Configuration[string-value])​

In this section we will look at different ways we can read in the configuration into a .NET Application. The following code snippets assumes we have an appsetting.json file with this Secrets:SecretA structure, as seen below:

{
    "Secrets": {
        "SecretA":"someValue"
    },
    "Key":"Value" 
}

We also assume we have a C# class with that structure for binding purposes, as seen below:

namespace ConfigTesting.Models 
{
    #pragma warning disable CS8618
    public class SecretsOptions
    {
        public const string Secrets = "Secrets";
        public string SecretA { get; set; }
    }
}

Bind Method​

With the bind method, we get the section we want from the loaded configuration (in our case the appsettings.json) then we bind that section to an instance of a class that we have created ourselves. For the binding to work the corresponding properties in the class need to have public getter and setter as seen above for SecretsOptions class.

This is how we can bind:

//assuming configuration is IConfiguration which we can access via DI or builder.Configuration
//.NET must have loaded the appsettings.json file by default for us.

//we create an instance then bind it to values in the configuration
var secretsOptions = new SecretsOptions();
configuration.GetSection(SecretsOptions.Secrets).Bind(secretsOptions)

//this will give out the current SecretA value, the one we had at the time of binding
secretsOptions.SecretA;

Things to note here are:

• This gets the current loaded configuration and binds values to the class
• If the IConfiguration updates values the secretOptions WILL NOT update.
• This method can be used anywhere in the application where we can have access to IConfiguration.

Configure<TOption> Method​

The TOption generic class in this instance is our class that represents the settings i.e. SecretsOptions class.
With this method we still need to get the section from the configuration but we don't need to bind to any instance as we will be accessing our settings via Dependency Injection.

This is how we read in the config:

// This allow us to get the configuration via the IOptions<TOption>, IOptionsMonitor<TOption>, or IOptionsSnapshot<TOption> interfaces
// This adds our options to the DI container
configuration.GetSection(SecretsOptions.Secrets).Configure<SecretsOptions>();

//Example of usage in other class
public class SomeClass 
{
    private readonly _secretsOptions;
    public SomeClass(IOptions<SecretsOptions> options)
    {
        _secretsOptions = options.Value ?? throw new ArgumentNullException(nameof(options));
    }

    //usage later in the code
    //This will give us the value of SecretA that was loaded from the configuration when IOptions was constructed.
    //The IOption is constructed into the DI container as a singleton, more on this later.
    _secretsOptions.SecretA;
}

Things to note here are:

• This method adds our configuration section to the DI container.
• It allows us to get our section with the class IOptions, IOptionsMonitor, or IOptionsSnapshot

Configuration[string-value]​

Another note worthy method of reading the configuration is using the configuration itself. This works for the IConfiguration which can be accessed via DI. .NET Automatically adds the loaded Configuration into the DI container.

This method always get the most recent values from our configuration. When using this method you will get back a string. Using our example json below:

{
    "Secrets": {
        "SecretA":"someValue"
    },
    "Key":"Value" 
}

Assuming I have IConfiguration as a variable then if I go: config["Secrets"] this will return null since Secrets section is not parsable to a string, but config["Key"] we will get value Value since it is parsable to a string.

IConfigurationSection secretsSection = config.GetSection("Secrets");

//To access values in the section:
//secretA will have a value if SecretA is parsable as a string.
var secretA = secretsSection["SecretA"]; //will have someValue string

So as we can see .NET offers a bunch of options for getting your configuration values from the IConfiguration. Now let's look at how each method handles the changes in the configuration.

The WebAPI For Testing​

In this section we are going to see how a simple miminal API can help look at how each of the methods handle changes that might happen to the IConfiguration. Knowing when your configuration changes is important to applications that might have a configuration provider that changes value, like auto rotated secrets in a key vault.

Configuration Providers​

One cool thing about .NET's IConfiguration is that it can have multiple providers at the same time. To understand what I mean about providers let's look at this diagram:

The diagram shows that a .NET Application can construct a configuration from multiple sources, like appsettings.json, customsettings.json, and some external service like a keyvault. We can have as many providers as we want.

These different sources are what we call configuration providers, because they provide values to our configuration. Multiple configurations can be added to our IConfiguration in different ways. The appsettings.json will be added automitically by .NET unless told otherwise.

The reason we spoke about configuration providers it's because I wanted to chip in something like keyvault into the conversation, but why? Well because providers like keyvault tend to have values that can change and our application might need to use the latest value and hence we need to have means to be alerted of our the changes so that our application uses the lastest and freshest settings.

Now let's look at our application that will help us test out which method is best for listening to changes in our configuration.

The Configuration API.​

The code to this api can be found here. Please note the only provider used in this application is the appsetting.json for the sake of simplicity.

What the WebAPI Does​

The WebAPI provides an endpoint to change a value of a section in the appsettings.json, the value is Secrets:SecretA as seen in the JSON file below:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "SettingA": "initValue",
  "Secrets": {
    "SecretA": "a-very-secret-value"
  },
  "Key": 1,
  "AllowedHosts": "*"
}

The API will be able to update the SecretA value to any value provided.
The Web API also has another endpoint to get the current value of SecretA

The endpoint to update the config value returns a result like this:

public record ConfigChangeResponse
    {
        /// <summary>
        /// The value before the IConfiguration changed
        /// </summary>
        public string OldValue { get; init; } = string.Empty;

        /// <summary>
        /// The value after the IConfiguration changed
        /// </summary>
        public string NewValue { get; init; } = string.Empty;

        /// <summary>
        /// The value of the binded property before the IConfiguration changed
        /// </summary>
        public string BindBeforeChange { get; init; } = string.Empty;

        /// <summary>
        /// The value of the binded property after the IConfiguration changed
        /// </summary>
        public string BindAfterChange { get; init; } = string.Empty;
    }

Each property value is explained in the summary comments of the class as seen above. The BindBeforeChange and BindAfterChange will be the properties that will have values before and after the change of the configuration respectively, this will help us see how each binding method mentioned above handles changes.

How the WebAPI updates the IConfiguration​

I have a class I wrote called ConfigurationUpdater. Which looks like this:

public void UpdateAppSettings(string section, string key, string newValue)
{
    var json = File.ReadAllText(_filePath);
    var jsonObj = JObject.Parse(json);

    if (jsonObj.SelectToken(section) is JObject sectionToken)
    {
        sectionToken[key] = newValue;
        File.WriteAllText(_filePath, jsonObj.ToString());

        //Reloads the IConfiguration in the application's DI container
        //Every class using the IConfiguration will reload the configuration
        _configRoot.Reload();
    }
    else
    {
        throw new ArgumentException($"Section '{section}' not found in configuration.");
    }
}

The above code just updates a said value on a section. Then reloads the configuration so that any class using the passed IConfigurationRoot can have the reloaded configuration. This is how the class can be used:

updater.UpdateAppSettings("Secrets", "SecretA", "someValue");

In all, the ConfigurationUpdater class is for updating the IConfiguration. I just wanted to discuss how it does that, nothing fancy. Please see this for usage, and this on how the service is registered into the application's DI container.

The Update Endpoint​

The Update method does a few steps to help us test how each method behaves for, here is the code and sequence:

app.MapPut("/updateconfig/{newValue}", (
    string newValue,
     IOptionsMonitor<SecretsOptions> secretsOptionsMonitor,
     IConfiguration config, 
     IConfigurationUpdater updater) =>
{
    //Bind section to the SecretsOptions class
    IConfigurationSection section = config.GetSection(SecretsOptions.Secrets);
    var secretsOptions = new SecretsOptions();
    section.Bind(secretsOptions);

    // Get the current value from the binded property
    var bindBeforeChange = secretsOptions.SecretA;

    // Get the current value from the configuration
    var oldConfigValue = config["Secrets:SecretA"];

    // Update the configuration
    updater.UpdateAppSettings("Secrets", "SecretA", newValue);

    // Get the new value from the configuration
    var newConfigValue = config["Secrets:SecretA"];

    // Get the new value from the binded property
    var bindAfterChange = secretsOptions.SecretA;

    if (oldConfigValue == newConfigValue)
    {
        return Results.BadRequest("Failed to update configuration");
    }

    return Results.Ok(new ConfigChangeResponse
    {
        OldValue = oldConfigValue ?? string.Empty,
        NewValue = newConfigValue ?? string.Empty,
        BindBeforeChange = bindBeforeChange ?? string.Empty,
        BindAfterChange = bindAfterChange ?? string.Empty,
    });
})
.WithName("ConfigUpdater")
.WithOpenApi();

Sequence:

• Binds the SecretsOptions class using a specific method, in the above example we used the Bind().
• We read what is binded into the SecretsOptions class' SecretA value.
• We then follow by reading the SecretA value straight from IConfiguration, this will be the same as the step above's value.
• After this we update the IConfiguration with the new value.
• We then get the new value from the IConfiguration, this should be the updated value.
• After we read the binded SecretsOptions class' SecretA value.
• Finally, we return the appropriate class with 4 values as explain in this section

How Each Method Handle Changes.​

Okay, that was looooong. Now let's test out doing changes, I will be looking at Bind(), IOptions<TOption> and IOptionsMonitor<T> methods. The IConfiguration[string-value] will always find the latest loaded values on the configuration so I won't look at it.

How the appsettings.json looks:​

This is how the appsettings.json looks like, it will be our initial state of the JSON configuration:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "SettingA": "initValue",
  "Secrets": {
    "SecretA": "a-very-secret-value"
  },
  "Key": 1,
  "AllowedHosts": "*"
}

Bind​

To use the bind method we just need to create an instance of the SecretsOptions class then call the bind method of the IConfiguration so the configuration can bind the class. Like this:

//SecretsOptions.Secrets has the value: "Secrets"
IConfigurationSection section = config.GetSection(SecretsOptions.Secrets);
var secretsOptions = new SecretsOptions();
section.Bind(secretsOptions);

Testing Bind Method​

• Calling the Update endpoint:
• Calling the Get SecretA endpoint:

As seen above the update endpoint's BindAfterChange still has the value a-very-secret-value even though we have changed the configuration, this is expected because the Bind() will add values of the Configuration at a certain time and if the configuration changes, there is no way to update the already bounded instance.

IOptions<TOption>​

The IOptions is one of the ways to get the configuration that is injected in DI via the Configure<TOption> method. To use this method the following has to be done:

//In your StartUp.cs ConfigureServices() or Program.cs
//Add the Configure of the SecretsOptions like so:
builder.Services.Configure<SecretsOptions>(builder.Configuration.GetSection(SecretsOptions.Secrets));

//In the constructor of my class I'd have something like this:
private readonly IOptions<SecretsOptions> iSecretsOptions;
public class MyClass(IOptions<SecretsOptions> iSecretsOptions) 
{
    this.iSecretsOptions = iSecretsOptions;
} 

// Because I am using minimal APIs I don't need to have constructors
// As seen in the source code of the app.MapPut() method in the Program.cs.

//In the Update endpoint this is how get SecretsOptions:
var secretsOptions = iSecretsOptions.Value;

When using the IOptions<TOption> to get the configured section we the Value property as seen above, this will give us the registered Option values that were registered at app start up. A key takeaway here is that IOptions<TOption> offers means to get your configured options via DI without needing to create an instance of the options class and binding it ourselves everytime. This works well for settings that are used in different parts of the application, we can just rely on the DI container to give us the created instance. It's even more useful for settings that don't change but are needed in different parts of the application.

• Calling the Update endpoint:
• Calling the Get SecretA endpoint:

But as seen in the above calls, the IOptions<TOption> doesn't automitically load new change to your configuration. Then comes in the IOptionsMonitor<TOptions> in the following section.

IOptionsMonitor<TOption>​

As far as I can tell with my very little knowledge of the world and the universe of .NET, the IOptionsMonitor<TOption> is the ideal solution to the problem of changing configuration. It offers two ways to access the new changes, with one for just reading, the other for doing way more than reading/writing. The two options are:

• IOptionsMonitor<TOption>.CurrentValue - gets current values in IConfiguration, the latest values.
• IOptionsMonitor<TOption>.OnChange(Action<out TOption, string?> listner) - adds a listener that can be invoked whenever the configured section changes.

In this blog plost I won't be looking at the OnChange option, though it is useful for cases where you'd need to perform some tasks when the configuration changes like. Things like calling an external service that depends on the changed configuration value, etc.

So then to use the IOptionsMonitor in our code, we will do similar steps as IOptions like so:

//In your StartUp.cs ConfigureServices() or Program.cs
//Add the Configure of the SecretsOptions like so:
builder.Services.Configure<SecretsOptions>(builder.Configuration.GetSection(SecretsOptions.Secrets));

//In the constructor of my class I'd have something like this:
private readonly IOptionsMonitor<SecretsOptions> iSecretsOptions;
public class MyClass(IOptionsMonitor<SecretsOptions> iSecretsOptions) 
{
    this.iSecretsOptions = iSecretsOptions;
} 

// Because I am using minimal APIs I don't need to have constructors
// As seen in the source code of the app.MapPut() method in the Program.cs.

//In the Update endpoint this is how get SecretsOptions:
var secretsOptions = iSecretsOptions.CurrentValue;

The only difference between IOptions and IOptionsMonitor is how inject them and that the IOptionsMonitor has a property CurrentValue for reading the configured options while IOptions uses Value. This is how the API calls look for this approach:

• Calling the Update endpoint:
• Calling the Get SecretA endpoint:

As we can see above the IOptionsMonitor is able to get the latest configuration as soon as it changes and reloads, and just like the Value property of IOptions, the CurrentValue property of IOptionsMonitor is of type TOptions which will be the configured section.

var x = ioptionsMonitor.CurrentValue;
//some code here...
//using x, thinking it will change:
var y = SomeFunction(x);

var x = ioptionsMonitor.CurrentValue;
//some code here...
//using x, thinking it will change:
var y = SomeFunction(ioptionsMonitor.CurrentValue);

Then this leads us to ask:

What to use?​

Like all software decisions, it depends. Each method has it's own ideal cases but this is how I see it:

Bind() Use Case​

Use it when you are concerned with getting the configuration once for some set up, like during StartUp. It is also ideal for settings that don't change and are used in one place, so we wouldn't mind creating the instance ourselves.

IOptions<TOption> Use Case​

I'd use this for cases where I want to use my settings in different places, this is good because it allows me to get my options from the DI container and I can reuse it all over my application. I'd use this for settings that hardly change, like service URLs, App Name, logging settings, etc.

IOptionsMonitor<TOption> Use Case​

This has benefits of IOptions plus the ability to monitor changes to the IConfiguration. So if I need to apply configuration changes as soon as they happen I can go with this method.

Conclusion​

Well this was a looong one but it was fun. So here are some highlights of the blog post:

• .NET has IConfiguration that reads the configuration from different providers
• .NET has means to read the configuration into the application.
• To read simple types from the configuration we can use IConfiguration["key"]
• To read complex types from the configuration we can use IConfiguration.GetSection("Key")
• Different methods have different benefits when reading the configuration.

Topics​

• What are Mocks?
• Setting up a mock in your unit test using Moq.
• The Good and the Bad of Moq It.IsAny<T>
• Conclusion

What are Mocks.​

A Mock in the context of unit testing is a module that mimics the behavior of another class/component. These mocks are usually used in Unit tests to replace dependencies that a System Under Test (SUT) needs to perform a task. Mocks are useful for giving the tests the same behaviour as the actual dependency would've given us but they are light-weight and depend on some kind of inputs and set up to give us the behaviour we need, good news, we set up those inputs.

To get a good grasp of what mocks are we going to draw a little diagram and later some code to see how Mocks work using Moq in a C# XUnit Test Project.

A little scenario​

Let's say we have a piece of software that adds recipes to a database using a class called RecipesManager. For the RecipesManager to add recipes it needs to use RecipeStoreService class that is responsible for saving recipes to some database.

In this scenario we can say RecipesManager has a dependency on RecipeStoreService that is, the manager needs the store service for it to fullfil it's functional purpose, i.e. to store recipes to some database.

This diagram shows the dependency:

The above diagram shows the dependency if the software was normally running but in a unit test we might want to replace RecipeStoreService with a mock for a number of reasons listed but not limited to them:

• Starting up the original RecipeStoreService can be expensive for unit tests (time/resources).
• Mocking dependencies means we have control of the input thus the behaviours we want from the SUT.
• The dependency graph of the RecipeStoreService can be big (the service has dependencies that have dependencies etc.)

After replacing the RecipeStoreService with a mock we might have something like this:

The above replacement results in something like this for a given test case:

• Mock Wrapper when your IRecipeStoreService is called with input A output B.
• We will passed the IRecipeStoreService implementation created by our Mock framework to the SUT.
• When the SUT excutes code that calls our IRecipeStoreService with A then B will be the output.

Setting up a mock in your unit test using Moq.​

So now that we have an idea of what a mock is, let's have the above scenario in code and then delve into the reason we have this blog post. Please note I am doing all of this in a simple console application.

Our Recipe Store will look like this:

//interface for the Recipe Store
public interface IRecipeStoreService 
{
  bool AddRecipe(string recipe);
}

//Implementation
public class RecipeStoreService : IRecipeStoreService
{
    public bool AddRecipe(string recipe)
    {
        //stores the recipe and returns true if successful
        return true;
    }
}

Our Manager like this:

public class RecipesManager 
    {
        private readonly IRecipeStoreService _recipeStoreService;
        public RecipesManager(IRecipeStoreService recipeStoreService)
        {
            _recipeStoreService = recipeStoreService;
        }

        public bool AddRecipe(string recipe)
        {
            //does manager responisbilties like validation
            if(_recipeStoreService.AddRecipe(recipe))
            {
                Console.WriteLine("Stored Recipe with name: {0}", recipe);
                return true;
            }
            else
            {
                Console.WriteLine("Failed to store Recipe with name: {0}", recipe);
                return false;
            }
        }  
    }

Then we will proceed to have a simple Main method like this:

class Program
    {
        static void Main(string[] args)
        {
            var recipe = "Pizza Recipe";
            var manager = new RecipesManager(new RecipeStoreService());
            manager.AddRecipe(recipe);                
        }
    }

This will simply print out this to the console:

This is sweet now, let's test this using Mocks. Just a reminder, we are testing RecipesManager not Program.cs' Main so we won't be looking at that logic. To Start we will need to create an xunit test project like this. I have alreay set up my tests and have a test project called MockSetUpTests.

In There I will have a simple test cases:

public class RecipeManagerTests
{
    [Fact]
    public void AddRecipe_WhenCalled_ReturnsTrue()
    {
        // Arrange
        var recipe = "Pizza Recipe";
        var mockRecipeStoreService = new Mock<IRecipeStoreService>();
        mockRecipeStoreService.Setup(x => x.AddRecipe(recipe)).Returns(true);
        var manager = new RecipesManager(mockRecipeStoreService.Object);

        // Act
        var result = manager.AddRecipe(recipe);

        // Assert
        Assert.True(result);
    }
}

This will result in a passing test:

How we used Moq to Mock​

This is how we mocked the RecipeStoreService:

• Created a mock that wraps our service like this: var mockRecipeStoreService = new Mock<IRecipeStoreService>();
• Then we proceeded to SetUp our mock for a certain call with this line: mockRecipeStoreService.Setup(x => x.AddRecipe(recipe)).Returns(true);
• By setting up we are telling mock if the IRecipeStoreService you created is given input "Pizza recipe" return true, otherwise it would return false and the test fails.
• Then our manager can do whatever with response, in this case it just propagates the value to the caller.

It.IsAny​

Now let's talk a little about some magic wand, In the case above we see that recipe we pass to the manager will further be used in the store service. This might lead those who use Moq a lot to use this magic wand: It.IsAny<string>() which would lead our set up line to look like this:

mockRecipeStoreService.Setup(x => x.AddRecipe(It.IsAny<string>())).Returns(true);

This tells our test It doesn't matter what string value I give you just return TRUE. Let's use talk about the danger of this.

The Good and the Bad of Moq It.IsAny<T>​

The Good of It.IsAny is that when we really don't care what value is passed to our dependency we don't need to have a test value for it, the bad? If we care and still use It.IsAny.

The danger​

We are going to change our code to show the danger of this, consider our manager changes and we want use a request Object like this:

public class RecipesManager 
{
    private readonly IRecipeStoreService _recipeStoreService;
    public RecipesManager(IRecipeStoreService recipeStoreService)
    {
        _recipeStoreService = recipeStoreService;
    }

    public bool AddRecipe(RecipeRequest request)
    {
        //does manager responisbilties like validation
        if(_recipeStoreService.AddRecipe(request.Founder))
        {
            Console.WriteLine("Stored Recipe with name: {0}", request.Recipe);
            return true;
        }
        else
        {
            Console.WriteLine("Failed to store Recipe with name: {0}", request.Recipe);
            return false;
        }
    }  
}

    //Request object
public class RecipeRequest(string recipe, string founder)
{
    public string Recipe { get; set; } = recipe;
    public string Founder { get; set; } = founder;
}

We now introduced a new Request object but we accidentally stored the Founder name instead of the recipe but because we used the It.IsAny<string>() in our code base the test will pass. In our test we just need to add the Request model and pass it in our act statement, the rest should work fine:

 // Arrange
var recipe = "Pizza Recipe";
var request = new RecipeRequest(recipe, "John Doe");
var mockRecipeStoreService = new Mock<IRecipeStoreService>();
mockRecipeStoreService.Setup(x => x.AddRecipe(It.IsAny<string>())).Returns(true);
var manager = new RecipesManager(mockRecipeStoreService.Object);

// Act
var result = manager.AddRecipe(request);

// Assert
Assert.True(result);

This would be misleading because now we will think our code works as expected until we run and see otherwise and sometimes such bugs are easy to not see then we have this kind of code in production, so what is the solution? Here's How:

How To Correctly verify inputs on set.​

Moq and most mocking frameworks provide a means to make your test inputs more explict to what they need to perform a task. Moq has It.Is<T>() which is helpful to make sure the paramter passed is the value we want, In test we would swap It.IsAny for It.Is like this:

mockRecipeStoreService.Setup(x => x.AddRecipe(It.Is<string>(c => c == request.Recipe))).Returns(true);

Now this tells mock make sure the string passed to AddRecipe is the same as the Request's Recipe parameter if I run my test with this change, I get:

Conclusion​

That will be it for the blog, pretty lengthy! Here's somethings to remember:

• Mocks are meant to replace dependency for the SUT.
• Always make your set up input data reflect the actual data
• Be explict with your inputs, especially if they are used in important places.

Topics​

• What is a Nullable boolean
• Casting Warning.
• How To Get Around the Cast Possible error.
• Conclusion.

What is a Nullable boolean​

In the world of coding we say a data type or structure is nullable if it can contain a null value (to an extent). This means that I can use null in place of this datatype and my program won't complain, in C# you would see something like the below:

public class MyClass
{
    //Can be written as public Nullable<int> NullableInteger { get; set; }
    public int? NullableInteger { get; set; }   //can assign null here
    public int NotNullableInteger { get; set; } //can't be assign null to this.
}

In C# we usually use the question mark symbol ? to make a property nullable. This is useful for some reasons:

• Your code is explict with letting you know this value can possibly be null
• Every nullable property/type in C# is wrapped inside the Nullable<T> class
• Nullable types have properties like HasValue and Value thanks to the Nullable wrapper.

Casting Warning.​

In our codebase we had a nullable property that we used to check a condition and C# gave us a warning against this.
To illustrate what we had, lets look at the below:

namespace nullable;

class Program
{
    static void Main(string[] args)
    {
        var starWarsMovie = new Movie("Star Wars The Clone Wars");
        if (starWarsMovie.IsGoodMovie)
        {
            Console.WriteLine("A Good Movie Indeed");
        }
    }
}

public class Movie
{
    public Movie(string movieName)
    {
        MovieName = movieName;
    }

    public string MovieName { get; set; } = string.Empty;
    public bool? IsGoodMovie { get; set; }  = null;
}

You can notice I set my IsGoodMovie property to have a default value of null, just for the sake of this blog post. If you have ever used C# before you might know that the above if statement in the Main method will cause the compiler to freak out and your IDE/Editor will scream at you with this error code: CS0266

This will tell you something like Cannot implicitly convert type 'bool?' to 'bool'. An explicit conversion exists (are you missing a cast?). Tempting suggestion, and spoiler alert, we fell for it!
So essentially the error says, the if-statement expects something like if(bool) but you are trying to do if(bool?), because remember our IsGoodMovie is nullable it is not a bool type but a bool? type or you can say Nullable<bool>.

So what do you do then? well we went the casting route and had something like this:

//cast by adding (bool).
if ((bool)starWarsMovie.IsGoodMovie)
{
    Console.WriteLine("A Good Movie Indeed");
}

Casting just means forcing an object which type A to be type B. The Language takes care of value conversion, some types are easy to cast some are hard and can cause unexpected results, so not recommended if we don't know what we are getting ourselves into!

This didn't totally solve our problems we now have a warning with code: CS8629 but we were not phased and didn't pay attention to the implication of this warning.

The warning was telling us: "Hey, nullables can possibly have null values and you are assuming it is not null here". C# even gives you this beautiful message:

If I run this piece of code, knowing that my IsGoodMovie is null I will get this runtime exception:

And Oops! Just like that we broke production, yup, BIG NO NO! So this is the danger: Don't rely on nullables always having a value. So we assumed (bool)null => false but we got humbled! because this is not the case, the C# Runtime can't change nothing (null) into a valid true/false.

How To Get Around the Cast Possible error.​

Our fix around this was simple; use the capabilities Nullable provided for us so we change our code to:

static void Main(string[] args)
    {
        var starWarsMovie = new Movie("Star Wars The Clone Wars");
        if (starWarsMovie.IsGoodMovie.HasValue && starWarsMovie.IsGoodMovie.Value)
        {
            Console.WriteLine("A Good Movie Indeed");
        }
    }

Now we use HasValue to check if the value in IsGoodMovie is a valid boolean if true, we then proceed to check if value is true, only then do we go into our if.
Simple fix but it has made us aware of something important DON'T JUST CAST TO GET RID OF ERRORS.

Conclusion.​

Okay, I enjoyed this blog, was nice. Here are the main points:

• Don't assume Nullables have values
• Always use the machinism provided to help with checking nulls.
• Don't just cast because it removes errors.
• Always test your assumptions - tests are good negative indicators.

Until next, keep pretending until you are not.

Topics​

• What is JQuery and AJAX.
• Doing an AJAX call with JQuery.
• JQuery "mistaking" your success as error
• The "fix"
• Conclusion

What is JQuery and AJAX.​

What is JQuery?​

Well in the world of web development JQuery is pretty famous it is a library that allowed web developers to make their websites more dynamic and do edgy stuff without doing a lot of vanilla javascript, yes, there is still a lot of heavy lifting were you need to do a lot of work for yourself when manipulating the DOM as oppossed to using a library like React or a Framework like Angular.

JQuery was (and still is) amazing because it allows you to use selectors to manipulate DOM elements like divs, p1, h1, etc. It also has capabilities to insert html into the DOM with the .html(data) function where data is any html you want to insert.

Apart from that JQuery allowed developers to change styling on the fly as they need to with the help of the .css() function. Below is an example of how we can use JQuery to simply just change the text of a div and insert some h1 tag:

<!DOCTYPE html>
<html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script>
    $(document).ready(function(){
        $("#myDiv p").text("This is the new text for the paragraph.");
        $("#myDiv").append("<h1>This is a new H1 heading</h1>");
    });
    </script>
</head>
<body>

<div id="myDiv">
    <p>This is a paragraph.</p>
</div>

</body>
</html>

JQuery uses selectors to find elements in the DOM. To find any element with an id we use the hash symbol (#). In my example because my div has an id attribute set to myDiv thus to select that element using JQuery I just go $("#myDiv") you can even store this in a variable and console.log() it to see how a DOM element looks as javascript object.

In the above example the first line in my script finds my div by id then looks for any p child inside the div then changes the text using the .text() method.

A line later I use the append() method to append a child to my div this will add a new h1 tag to my div. This is just a simple example to try and show you how JQuery works, you can copy the HTML then serve in any web server you like locally and you will see the result 🙃

What is AJAX?​

AJAX stands Asynchronous Javascript And XML. It is used for sending HTTP request to the server from your web app in manner that doesn't load up the whole page, it is useful for sending requests then dynamically changing your page.

With plain javascript a AJAX object can be initialised using the new keyword as follows: var xhttp = new XMLHttpRequest();.

JQuery's AJAX​

JQuery has a way to use AJAX functionality without needing to initiliaze the XLMHttpRequest which may become tedious real fast. To do that we have a $.ajax({...}) where we give our ajax method some values as follows:

<!DOCTYPE html>
<html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script>
    $(document).ready(function(){
        $.ajax({
            url: "https://jsonplaceholder.typicode.com/posts",
            method: "GET",
            dataType: json
            beforeSend: function(){
                console.log("loading")
            },
            success: function(result){
                console.log(result);
                $("body").append("<p>Data received!</p>");
            },
            error: function(error){
                console.log(error);
                $("body").append("<p>An error occurred.</p>");
            }
        });
    });
    </script>
</head>
<body>
</body>
</html>

I served the above HTML with npx server and got the follwing result:

The json we passed in the $.ajax({...}) method had the following properties and here's what they mean:

• url: this is url where we want to send our call.
• method: HTTP method like GET, POST, PUT and DELETE
• dataType: the expected data type from the response.
• beforeSend: function that will be executed right before sending the call.
• success: function to execute on success. This includes responses with with 2xx, 3xx.
• error: function to execute for non-success calls or failures to read/process responses. Example: 4xx, 5xx.

JQuery "mistaking" your success as error​

If you can notice I put mistaking in qoutes because it's not really mistaking, but rather something we can easily miss.

Cause of "mistaking" success with error​

There is a case that is easy to miss that may cause JQuery AJAX call to think a success call has failed. This happens when we specify the wrong dataType.

So if I am expecting a json response and my server sends me a 200 HTTP Status Code with html content this will classified as an error but there won't be any log to let me know. The reason this becomes an error is because by telling JQuery you expect json it will try to parse the response for you and if it fails even though the response 200 OK, it will just go to the error function.

To illustrate this, I have create an html page that just has an h1 tag as follow:

<!DOCTYPE html>
<html>
<body>
<h1>About Page For Blog</h1>
</body>
</html>

Which simply shows this:

This will be hosted on localhost:3000 same as my html with JQuery. Then I will do a call where I specify dataType: json, then do a call to get this new page. It's as follows:

<!DOCTYPE html>
<html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
    <script>
    $(document).ready(function(){
        $.ajax({
            url: "/about",
            method: "GET",
            dataType: "json",
            beforeSend: function(){
                console.log("loading")
            },
            success: function(result){
                console.log(result);
                $("body").append("<p>Data received!</p>");
            },
            error: function(error){
                console.log(error);
                $("body").append("<p>An error occurred.</p>");
            }
        });
    });
    </script>
</head>
<body>
</body>
</html>

The result:

As you can see the responseText which serves as the content of the response is an html about page and status is OK from the part we logged in the console, yet JQuery goes to error hence we see our body appended with An error occurred message.

Again this because we told JQuery: "hey, I am sending an HTTP request and the server must give me back data with dataType json as a response". Then JQuery tries to be nice and parse your responseText for you then it fails, hence calling the error function. So how do we fix this?

The "fix"​

To fix this we would need to change the dataType from json to html. That would stop JQuery from trying to parse your html response into json and calling the error method on failure, it is that simple.

But what if for some reason you are calling an endpoint that can potentially give you both html and json? What do you do then? simple, if we don't specify the dataType value JQuery's Ajax won't even bother to try and parse our response in any way.

Conclusion.​

This is it for the blog post. Here are some important points we went through:

• JQuery is library that allows us to do DOM manipulation using the function $(<html-selector>) to make our web application dynamic
• AJAX is a means of sending HTTP server requests without loading the whole page.
• JQuery has an AJAX method built into it accessed by $.ajax({...})
• dataType is useful for specifying what kind of data we expect back, if not specified JQuery accepts any kind of response.
• error function is not called when we have HTTP status failures only but rather when JQuery fails to process our server response in anyway.

Keep pretending, until next time!

Topics​

• Introduction
• What is React, from a library viewpoint?
• If Not A Framework then WHAT IS REACT?
• Making my React App
• Conclusion

Introduction​

React is a popular JavaScript library for building user interfaces. It allows developers to create reusable UI components and efficiently update the UI when the underlying data changes.

Let's get started!

What is React, from a library viewpoint?​

I have had problems with understanding why people would refer to React as a library and not a framework and knowing my little lack of knowledge of front-end technologies, I'd just not stress myself being such conversations. You'd hear people say "React is not a full framework, I don't like working with it" or "Angular is better it's feature-rich, it has routing built into, a clear design in mind (MVC)"

And I'd be confused until I met this beaut here React Quickly. Then I got a clear understanding of what React is.

What Problem Is React Solving?​

As mentioned in the introduction React focuses on building reusable UI components that change as the state of the data changes, what does this mean? It just means React isn't a framework that is there to help with state management, routing, etc. It is just a means to have reusable and dynamic UI, that's about it.

Yes react can be extendible with other libraries like React Router, and Redux to name a few. These libraries along with React can form an ecosystem that can mimic and compete with fully fleshed UI frameworks like Angular and Vue.Js.

This is one of the reasons the model of React is state-centric, by this I mean the interactivity of UI components built in React is tightly coupled with the state changing, hence hooks like useEffect have things like dependencies to fire the hook whenever data changes.

If Not A Framework then WHAT IS REACT?​

To demonstrate fully what is react, we are going to build a mini project that will just show us how we can run react without the famous and useful create-react-app package which templates our application and helps create a web server for us and also creates a beautiful folder structure for us.

To start please create an empty HTML file in a directory, I named my directory react-bare-bones and have an index.html file such that I have the directory path react-bare-bones/index.html.

preferably have Node.Js installed (we will need it for our web server but any server can be used). This is how my HTML file will look like:

<!DOCTYPE html>
<html>
<head>
    <title>React Bare Bones</title>
</head>
<body>
    <div id="root"></div>
</body>
<script>
    //where my React code will be
</script>
</html>

ReactDom and React libraries.​

For us to have React capabilities on our website we would need to import the following libraries: ReactDOM and React. These two classes/libs are important for the following reasons:

• The React class helps us with the capability to create React elements these elements may be well-known HTML elements like h1, p, div, or our custom components.
• The ReactDOM class creates an abstraction of the DOM object and helps create the root container of our React application, that is, a container where all our React-rendered elements/components will reside. It also has the render method that will render our app in the DOM.

To add these two classes in our HTML file, which we use adding React to our website would require us to add this in our header tag:

<head>
    <title>React Bare Bones</title>
    <script crossorigin src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
</head>

Making my React App​

In this section, we will add some React into our app and can't create a simple Hello, World Website. Assuming you have added the cdn references to the index.html file we can proceed to add our React code in the script.

React Element​

To create the React element we will add the following line in our script:

var reacth1Element = React.createElement('h1', null, 'Hello World');

The createElement takes in three arguments:

• type is a string that represents a component that we want to render like h1, div, p, or our custom component.
• data would represent the data we want to pass to the component/element. This is also referred to as props, short for properties. In this mini example, we don't need props hence the null.
• ...children is the list of children of the component in this case the h1 tage would have the text as the only child.

This would allow us to create a React element but we need a place to render this element.

Rendering the React Element.​

To render the element we will need a container to place our React application, we will use our div with id="root" like this:

var divNode = document.getElementById('root');

This is a just vanilla javascript line to get the div's object instance in the DOM.

Will then need to set this as the root element in our React virtual DOM using this line:

var reactAppRoot = ReactDOM.createRoot(divNode);

This will create our React App Node but if we were to run our web server now, nothing would be rendered because we just created the root but didn't render it on the DOM, to do so we will do the following:

reactAppRoot.render(reacth1Element);

The render method takes in a react element to be displayed.

The complete file would look like this:

<!DOCTYPE html>
<html>
<head>
    <title>React Bare Bones</title>
    <script crossorigin src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
</head>
<body>
    <div id="root"></div>
</body>
<script>
    var reacth1Element = React.createElement('h1', null, 'Hello World');
    var divNode = document.getElementById('root');
    var reactAppRoot = ReactDOM.createRoot(divNode);
    reactAppRoot.render(reacth1Element);
</script>
</html>

The above would be enough to get your React app running, but first, we need to create a web server to host our beautiful website.

Web Server with Node.Js​

I have Node installed in my machine so I will just use that to host my site. Here's how I will do it:

• open the terminal in my working directory, i.e. directory with index.html
• run npx serve this will serve up the HTML in the working directory.
• A URL with a port number will be shown in the terminal that you can follow and see your website.

The Result should be something like this:

As you can see the div now has the h1 tag and we didn't template this or write it in a markdown format just pure Javascripting!! and no react-create-app.

Conclusion.​

Just to close this, here's a quick recap of what we covered:

• React is a library and not a framework.
• React focuses on building dynamic UI components.
• You just need JavaScript and the relevant libraries that have ReactDom and React to build your web app.
• react-create-app is a template library and not part of React.

Until next time! keep pretending until you are not 😁. Bye!!

Topics​

• What is OAuth?
• Actors In OAuth
• Problem OAuth Is Solving
• OAuth Flow: Authorization Code Flow
• How Authorization Code Flow Works
• Getting Authorization Code
• Getting The Access Token
• Calling the Protected Resource

What is OAuth?​

Open Authentication commonly referred to as OAuth is a means of authenticating an application to access a resource owner's data from a different application. It provides a standardized framework that allows this data sharing to be secure, easily adoptable and easily extensible, while providing flows that make sense for different use cases like mobile, native or web applications to name a few.

To understand what is OAuth we will need to travel a while back in time and see what kind of problem OAuth was trying to solve in the first place.

Actors In OAuth​

In this small section I will just add terms to some actors that are involved in OAuth:

• Resource Owner - This is the person/entity that owns the data we are interested in.
• Client - This is the application that wants to access the resource owner's data. An example would be an application that wants to view your Spotify data to maybe show most played songs in the last week.
• Authorization Server - Is an important piece in OAuth, this is the component that is responsible for authenticating the resource owner and issuing out tokens to client applications.
• Protected Resource - This is where the requested data resides, this will be thought to be an REST API in this blog post.

We will come back to these later and explain their role in OAuth for now let's keep the terms in mind. Now let's look at how exposing a resource owner's data in another application looked like before OAuth.

Problem OAuth is Solving: Replaying Password​

In the olden days if a client wanted to access data on behalf of the user, the user would need to give their password and username to the client so that the client can replay signing in as the user as shown below:

This has a lot of security implications what if the client loses your credentials and they end up in the wrong hands?

Another security implication would be the resource application has no way of distinguishing between the resource owner and the client. Another one is, since the client signs in as the resource owner, they also have access to resources that they shouldn't and can perform more actions like deleting, modifying and sharing resources when they shouldn't.

The above problem is one the big reasons OAuth was implemented: for scoping application's permissions on the resource owner's content and making sure there is no credentials sharing that can expose the resource owner to potential malicious acts.

OAuth: Authorization Code Flow​

In OAuth we have different ways to implement delegation of the resource owner's data, this is usually refered to as an OAuth Flow. Different flows are useful for differnt user cases, we will be looking at the authorization code flow. This flow is useful for Web Application that want access to the resource owner's content, it's ideal if the Web Application doesn't run on the browser like a SPA application or isn't a native application, this is more suitable for REST APIs or server rendered web apps.

How Authorization Code Flow Works​

In the simplest terms for this flow to work, the resource owner has to authorize the client's request to access their data. The client should know what kind of rights (scopes) they need. When they have been authorized a code will be given to the client known as the authorization code.
The client will then need to ask the authorization server to exchange the authorization code with an access token. An access token will then allow the client to send a request to the Protected Resources endpoint.

This is just a simple overview let's see how that can be achieved. With the below diagrams. We will talk through each important processes piece by piece to form the whole picture.

For the below example we will assume the client is using the browser to communicate with the other actors and the client is registered to use the OAuth capabilities offered by the authorization server and protected resources endpoints. This means the client has some identity and configurations against it in the authorization server.

1. Getting Authorization Code:​

• Firstly the resource owner will be asked by the application if they want the client to get resources on their behalf.
• If they agree then step 1 is done.
• The client will then redirect the resource owner to the Authorization Server with the following query parameters: client_id, scopes, redirect_uri and response_typeappended on the redirect url.
• the response_type=code indicates to the authorization server that the clients wants a authorization code thus using the authorization code flow.
• The client will have had the client_id issued to them by the authorization server when the client registered to use the protected resources OpenAPI.
• When the resource owner is redirected to the Authorization Server they will be asked to authenticate themselves with the authorization server, this all happens without the client application seeing anything thus no way to see the resource owner's credentials.
• Once authenticated the resource owner will be presented with a page that shows the scopes that the client application needs to in order to perform whatever tasks it wants, at this point the resource owner can approve or reject this request.
• If approved the authorization server will redirect the resource owner to the client's redirect_uri and append the authorization code on the url with the parameter code that will have some opeque code like code=sgysbcAhbdfj... which is authorization code.
• The redirect_uri will have been the same redirect_uri sent on step 2 and the same as the one the client configured when it registered to use the OpenAPI. This adds a level of security because the authorization server will always redirect to the url the client knows and can read from, not that just anyone can inject their own redirect_uri.
• The client doesn't need to understand the authorization code it just needs to know how to use it, that is exchange it for an access token.

As seen above the client application and the authorization server communicate indirectly through redirects with the browser being the middle man. This separation is essential to OAuth because it makes the client a simple component in the framework and gives all the authentication and authorization related functionality to the Authorization Server.

2. Getting The Access Token​

Once a client has the authorization code, the client will need to trade this for an access token. The client will typically have some kind of identity i.e. client_id and some client_secret that will be sent along with the authorization code. This will help the Authorization Server identify the client if it is to be trusted to be given the access token. Here is the flow:

• The client would have extracted the authorization code from the redirect respond in getting-authorization-code
• Then send an HTTP request to the Authorization Server with it's client_id and client_secret as form of identitification. How this identification is done i.e. HTTP Basic Auth or some flow like client credentials, doesn't really matter as long as there is this identification.
• The Authorization Server will process the request and do some checks to verify the code is still valid and check if the client is who they claim to be.
• If all is well an access token we will be sent back to the client with some extra data like expiration time, refresh token. What kind of extra data the Authorization Server returns is totally up to the Authorization Server.
• Once the client receives the access token which like the authorization code is opeque to the client, the client will be ready to make calls to Protected Resource.

A nice thing about this flow is since the access token and authorization code is opeque, the client doesn't even know which user it is delegating for because it doesn't need to. It knows that it needs an access token that the Protected Resource can understand. This again just shows how OAuth has made the client as dump as possible to the point it can't easily leak or see the resource owner's sensitive information.

Another thing is since the Authorization Server oversees the access/auth responsibility the resource owner only needs to go to one place to revoke the access if needed. Now that is good security right there.

note::: The client would have registered with the Authorization Server so that it can be able to delegate calls for the resource owners. Apon registration a client_id, client_secret and redirect_uri are configured for the client in the Authorization Server in some sense like manually, developer portal, etc. :::

3. Calling the Protected Resource​

Now that the client has the access token it can then use it to get the protected resources scoped to what scope was requested in the intial call to create the authorization code. The Protected Resource endpoints will have enough context to know which user the access token is for and what kind of data can the client ask for. The Protected Resource can even do extra validation to make sure the access token hasn't expired or been tempared with.

Here is the diagram:

• The client will send a request to perform an action (read, edit, write, delete) with an access token attached to the request.
• If the action is within the scopes of the access token and the access token is still valid, the Protected Resource will respond gracefully and fufil the request.
• If the action is not within the scopes of the access token or the access token is not valid the Protected Resource will have to kick back.

This will be all to get resources on behalf of a resource owner with OAuth's Authorization Code Flow.

Conclusion​

This is it for now, I think this gives us a better view of how OAuth works and yes, we didn't touch on other OAuth flows like Implict Grant Type, Client Credentials, PKCE flow. But hopefully this gave us a view on what OAuth is, what problem is it solving.

Just a recap, here are the points we touched on:

• OAuth is a framework designed to allow resource owners to give access to client applications to access their data in a controlled manner.
• OAuth is built on HTTP and relys on technologies like redirects to create separation of what one actor can see, namely the resource owner and client application.
• OAuth has flows or different implementation and Authorization Code Flow is one of them, this flow relys on a client creating an authorization code that describes the scope on which an access token will be scoped to, thus what actions can be performed with it.
• OAuth introduces an Authorization Server which is responsible giving access token as of the user's consent.

This is not the most detailed walk through of OAuth, if you are really interested in the indepths of the framework I'd suggest the following references:

• OAuth 2.0 in Action book
• OAuth RFC Specification
• Okta blog has a overview of this
• OAuth has a good compiled sources

I am hoping in the next blog post I will build a mini OAuth ecosystem just to see how this can be translated in code but until then keep pretending until you are not and happy coding.🚀

Topics​

• What is SignalR ?
• Why Should I use it ?
• A mini project with concepts: What are Hubs, Events and Methods in SignalR
• Controller Configuration
• Configuring A Client App
• Causing An Event To Fire
• Conclusion

What is SignalR ?​

Before we even start looking at SignalR I think it would be cool to understand what it is and what does it do.

SignalR is .NET's solution to allow servers to send information to clients as soon the change happens in the server. Both the client and the server can invoke methods on each other. This allows the server to call the client thus tell the client about the changes it is interested in. A client can subscribe to changes, called events.

The image below shows the typical architecture of SignalR:

The image above shows some of the fundamental parts of SignalR. We have a server that has SiganlR. Which in turns has a Hub which has Events and Methods. The connection is bi-directional meaning the server can call the client and vice-versa.

A Hub exposes our signalR endpoints. It enables clients to communicate with the server and vice-versa.

Events are the type of actions that clients can subscribe to. So whenever an event happens in the server a client that is subscribed to it will get notified on change. Note that a client can subscribe to multiple events as we can see client 3 from the image.

Methods these are functions on the server/Hub that can be called from the client side code. The client should provide the appropriate parameters and method name to invoke the correct method.

Why Should I use it ?​

There are number of reasons to use SignalR but my number one take is live updates. If you have an app that needs to know of changes as soon as they happen (chat notification or live updates like order tracking) then you might need to consider SignalR.

Why? Well imagine you have an app that needs live data from your database as soon as the state of the database changes. One way to do this is polling, where your app will call the server every, say 60 seconds. This will definitely work until we have a lot requests to the server and potentially causing many request errors and slowing down our server.

Another big win is that clients can choose what is important to them and listen to those events and then inform other clients of their changes.

A mini project with concepts: What are Hubs, Events and Methods in SignalR​

Now, the action! In this section we are going to explore some key conecpts with code snippets! 🐱‍🏍

Problem Statement:​

We want to have some frontent clients notified whenever a change happens on a certain table that we have in our database. So differnt client apps can subscribe to a signalR change event of any table they are interested in and we will notify them when there is a change.

Set Up:​

The .NET Solution will have an ASP.NET Web API with .NET 7. The frontend will be a simple React App that just listens to events. The database will be sqlite database, to query the database we are going to use Entity Framework Core. Simple stuff 😉.

Our server will be our ASP.NET Web API and our client a React App. It is worth a mention that a client app can also be another ASP.NET Web API.

Here is a mini diagram of flow:

We are simply going to have a controller that does a database table change then uses the Hub to fire an event that a table has changed.

Set Up SignalR in ASP.NET:​

• In our Program.cs file we need to add our hub dependencies to the service collections with this line: builder.Services.AddSignalR()
• Create Hub folder in the root of our project called Hubs as I did in my repo
• Inside the folder create a file called DatabaseHub.cs. This folder will have our Hub class and interface that describes our events.
• Then in our Program.cs we map a url to our Hub with this line: app.MapHub<DatabaseHub>("/database-hub") this means our hub url will be like this https://localhost:<port>/database-hub

This should be enough for a set-up no eventing yet but first steps.

Hub Class​

A Hub is a server concept in SignalR terms. It simply just represents a signalr server. This will be a normal c# class that extends from Microsoft.AspNetCore.SignalR.Hub<T>

The Type T is an interface that has all the events the Hub can expose.

Hub Example:

using Microsoft.AspNetCore.SignalR;

namespace SignalRExample.Hubs;

//Hub
public class DatabaseHub : Hub<IDatabaseHubEvents>
{
    //This is a method, it can be called from the client's code.
    public async Task NotifyAll(string clientName)
    {
       //I can cause an event in here by calling Clients property.
       //or something unrelated to SignalR.
    }
}

public interface IDatabaseHubEvents
{
    //Event we are going to fire when Product table changes.
    Task ProductTableChanged(TableChangeModel changeModel);

    //Event we are going to fire when Person table changes.
    Task PersonTableChanged(PersonChangeModel changeModel);
}

//Just a model
public class TableChangeModel
{
    public string TableName { get; set; } = string.Empty;
    public int ItemId { get; set; }
}

public class PersonChangeModel 
{
    public int PersonId { get; set; }
    public string Name { get; set; } = string.Empty;
    public string Surname { get; set; } = string.Empty;
    public string ChangeReason { get; set; } = string.Empty;
}

When an event ProductTableChanged is fired, clients that are subscribed to the event will receive a TableChangeModel object which has the data TableName and ItemId.

We will see how that is done on the client side later but for now. This will be enough. I want us to talk about the Clients property in Hubs namespace

SignalR Hub Clients​

IHubCallerClients<T> Clients This property has the ability to call all clients that are subscribed to an event. It also has the capability to group client calls:

• Clients.All - calls all clients that are listening to an event.
• Clients.Groups - calls a certain group of clients

This is what we will use to cause events. We can edit the above code to be like this:

public class DatabaseHub : Hub<DatabaseHubMethods>
{
    //Notify every client that subscribed to this event.
    public async Task NotifyAll(TableChangeModel changeModel)
    {
        //Send changeModel to All subscribed clients
        //Note we are causing an Event inside a Method, we don't need to do this all the time
       await Clients.All.ProductTableChanged(changeModel);
    }
}

Entity Framework Models​

We will have simple EFCore models that represent tables in our database.

• ProductModel:

public class Product : Entity
{
    public string ProductName { get; set; } = string.Empty;
    public string ProductDescription { get; set; } = string.Empty;
}

• PersonModel:

public class Person : Entity
{
    public string Name { get; set; } = string.Empty;
    public string Surname { get; set; } = string.Empty;
    public string UserName { get; set; } = string.Empty;
}

• Entity

public class Entity 
{
    public int Id {get; set;}
}

For Data Models and set up, please see Repo

Controller Configuration 🔥​

For us to cause an event to fire we just need to call the Clients.All.<my-event-function> So we are going to create a Controller that can be POSTED to and then it will fire an event after a successful insert.

Here is the Controller:

[ApiController]
    [Route("[controller]")]
    public class SignalRController : ControllerBase
    {
        private readonly IHubContext<DatabaseHub, IDatabaseHubEvents> _dbHubContext;
        private readonly ISignalRDbContext _signalRDbContext;

        public SignalRController(
            IHubContext<DatabaseHub, IDatabaseHubEvents> dbHubContext,
            ISignalRDbContext signalRDbContext)
        {
            //make sure you have registerd IDatabaseHubEvents in the DI container
            //i.e services.AddSingleton<IDatabaseHubEvents, DatabaseHub>()
            _dbHubContext = dbHubContext;
            _signalRDbContext = signalRDbContext;
        }

        [Route("add-person")]
        [HttpPost]
        public async Task<IActionResult> AddPerson(string name, string surname)
        {
            var person = new Person
            {
                Name = name,
                Surname = surname,
                UserName = $"{Guid.NewGuid()}"
            };

            DatabaseResult<Person> result = _signalRDbContext.AddPerson(person);
            if (result.Status == Status.Success)
            {
                var changeModel = new PersonChangeModel
                {
                    PersonId = person.Id,
                    Name = person.Name,
                    Surname = person.Surname,
                    ChangeReason = "New Add"
                };

                //Calling all clients and giving them the change model.
                await _dbHubContext.Clients.All.PersonTableChanged(changeModel);
                return Ok("User Added and alerted subscribers!");
            }

            //generates appropriate response based on database result
            return Conflict();
        }
    }

In the above we register our Hub via IHubContext interface and our DbContext that is behind an interface. The important line here is:
await _dbHubContext.Clients.All.PersonTableChanged(changeModel); this lines calls subscribed clients by firing an event ProductTableChanged thus passing down the PersonChangeModel data to be used by all the subscribed clients.

And that's it, that's how you fire an event. For all the controller source code check out: SignalR Example Repo.

Configurig A Client App​

I will be using a React JS client but the concept should be the same for any other client app. This means we will need to install the package: npm install microsoft/signalr.

Subscribing To An Event.​

Clients subscribe to a hub event by specifing the hub url and the event they are interested in. This would be any event specified in your client's event interface, in my case any method specified in they IDatabaseHubEvents interface of my database Hub would be an event.

Let's see how the client app does it:

I created a service class to take care of my SignalR connectivity SignalRHubService. The class looks like this:

import * as SignalR from "@microsoft/signalr";

class SignalRHubService {
  connection = null;
  tableEvents = ["PersonTableChanged", "ProductTableChanged"];

  startConnection = (serverHubUrl) => {
    this.connection = new SignalR.HubConnectionBuilder()
      .withUrl(serverHubUrl)
      .configureLogging(SignalR.LogLevel.Information)
      .build();

    this.connection.start().catch((error) => {
      console.error(error);
    });
  };

  addTableChangeListner = (tableEvent, callback) => {
    if (this.isEventAndConnectionValid(tableEvent, this.connection)) {
      this.connection.on(tableEvent, (tableChangeModel) => {
        callback(tableChangeModel);
      });
    } else {
      console.error("Can't Add Listner with Invalid Connection or Event");
    }
  };

  isEventAndConnectionValid = (tableEvent, connection) => {
    if (!connection) {
      console.error("Can't Add Listner with Invalid Connection");
      return false;
    }

    if (!tableEvent.includes(tableEvent)) {
      console.error("Can't Add Listner For unknow event");
      return false;
    }

    return true;
  };
}

export default SignalRHubService;

Start Connection​

The function that is responsible for starting a SignalR connection thus creating a subscribtion to my signalR Hub is startConnection:

//serverHubUrl is the URL of SignalR server.
//In this example it will be the server that Host my ASP.NET Web API that has SignalR configured.
startConnection = (serverHubUrl) => {
    
    this.connection = new SignalR.HubConnectionBuilder()
      .withUrl(serverHubUrl)
      .configureLogging(SignalR.LogLevel.Information)
      .build();

    this.connection.start().catch((error) => {
      console.error(error);
    });
  };

In the above example we are just building our SignalR connection. The SignalR class comes from the microsoft/signalr package. I pass the serverHubUrl this will the url where my SignalR Hub Server is hosted, the url must have the path to the Hub. As we will see in my App.js I used the url http:localhost:5078/database-hub as I have configured my .NET Web API to use path database-hub for signalR.

In my App.js I will just start a connection like this: signalRHubService.startConnection("http://localhost:5078/database-hub");

If you check your Networks in dev tools, you will see something similar:

This indicates that the connection to the hub has been established. Now subscribing to an event.

Subscribing To An Event​

The function that is responsible for subscribing to an event is addTableChangeListner:

addTableChangeListner = (tableEvent, callback) => {
    if (this.isEventAndConnectionValid(tableEvent, this.connection)) {
      this.connection.on(tableEvent, (tableChangeModel) => {
        callback(tableChangeModel);
      });
    } else {
      console.error("Can't Add Listner with Invalid Connection or Event");
    }
  };

This function takes in the event name which in my case can either be PersonTableChanged or PersonTableChanged then a callback method to handle the event. So when event PersonTableChanged happens the server will send a PersonChangeModel as described in the IDatabaseHubEvents the callback function will receive this object and do some work on it.

Here is how I handle an event in App.js:

  //changes has all changes that happened since we subscribed to the person table changes.
  //useState is a React function for creating state variables.
  const [changes, setChanges] = useState([]);

  const signalRHubService = new SignalRHubService()

  //useEffect is React's method for doing side effect work like calling APIs inside our component.
  useEffect(() => {
    //create connection
    signalRHubService.startConnection("http://localhost:5078/database-hub");
    //listen to event and update my state variable - changes.
    signalRHubService.addTableChangeListner("PersonTableChanged", (personChangeModel) => {
      setChanges((prevChanges) => [...prevChanges, personChangeModel]);
    });
  }, []);