X-ray StoneAssemblies.MassAuth with NDepend

Introduction

A long time ago, I wrote this post Why should you start using NDepend? which I consider as the best post I have ever written or almost ;)

NDepend is a static analysis tool for .NET, and helps us to analyze code without executing it, and is generally used to ensure conformance with the coding guidelines. As its authors use to say, it will likely find hundreds or even thousands of issues affecting your codebase.

After the first pre-releases of StoneAssemblies.MassAuth I decided to X-ray it with NDepend. I attach a new NDepend project to StoneAssemblies.MassAuth solution, filter out the test and demo assemblies, and hit the analyze button.

Attach new NDepend Project to Visual Studio Solution 

Now, I invite you to interpret some results with me. So, let's start.

Interpreting the NDepend analysis report

One of the outputs of the analysis is a web report. The main page includes a report summary with Diagrams, Application Metrics, Quality Gates summary, and Rules summary sections.

NDepend Report Summary

Navigation Menu

It also includes a navigation menu to drill through  more detailed information including Quality Gates, Rules, Trend Charts, Metrics, Dependencies, Hot Sports, Object-Oriented Design, API Breaking Changes, Code Coverage, Dead Code, Code Diff Summary, Build Order, Abstractness vs. Instability and Analysis Log.

But let's take a look at these summary sections.

Diagrams

The diagrams section includes Dependency Graph, Dependency Matrix, Treemap Metric View and Abstractness vs. Instability. 

Dependency Graph

Dependency Matrix

Treemap Metric View (Color Metric Coverage)

So far I understand these metrics, actually, I can interpret them relatively easily. 

But, wait for a second. What is this Abstractness versus Instability? 

Abstractness versus Instability

According to the documentation the Abstractness versus Instability diagram helps to detect which assemblies are potentially painful to maintain (i.e concrete and stable) and which assemblies are potentially useless (i.e abstract and instable).

Abstractness: If an assembly contains many abstract types (i.e interfaces and abstract classes) and few concrete types, it is considered as abstract.

Instability: An assembly is considered stable if its types are used by a lot of types from other assemblies. In this context stable means painful to modify.

Component	Abstractness (A)	Instability (I)	Distance (D)
StoneAssemblies.MassAuth	0	0.96	0.03
StoneAssemblies.MassAuth.Rules	1	0.4	0.28
StoneAssemblies.MassAuth.Messages	0.43	0.62	0.04
StoneAssemblies.MassAuth.Hosting	0.14	0.99	0.09
StoneAssemblies.MassAuth.Rules.SqlClient	0.17	1	0.12
StoneAssemblies.MassAuth.Server	0	1	0
StoneAssemblies.MassAuth.Proxy	0	1	0

None of StoneAssemblies.MassAuth's components seem potentially painful to maintain or potentially useless. But, I have to keep my eyes on StoneAssemblies.MassAuth.Rules, because of the distance (D) from the main sequence. Actually, another candidate to review is StoneAssemblies.MassAuth.Messages since ideal assemblies are either completely abstract and stable (I=0, A=1) or completely concrete and instable (I=1, A=0).

Application Metrics 

The application metrics section shows the following summary.

Application Metrics

Looks like some metrics depend on a codebase. Since this is the first I run NDepend's analysis over StoneAssemblies.MassAuth code, it hasn't noticed any difference with previous executions. But this help me to be alert about the low 66.99% value for the tests coverage, the 3 failures for quality gates, the violations of 2 critical rules and 15 high issues.

Quality Gates

In this section is possible to view more details on the failing quality gates. The percentage of coverage, the critical rules violated and the debt rating per namespace.

Quality Gates

Wait for a second again. What is debt rating per namespace means? 

According to the documentation the rule is about to forbid namespaces with a poor debt rating. By default, a value greater than 20% is considered a poor debt rating.

Namespaces	Debt Ratio	Issues
StoneAssemblies.MassAuth.Services	39.01	8
StoneAssemblies.MassAuth.Services.Attributes	37.62	3
StoneAssemblies.MassAuth.Server	23.67	6
StoneAssemblies.MassAuth.Rules.SqlClient .Rules	36.24	3

Rules summary

The final section is the Rules summary. It listed the issues per rules in the following table. 

Rules summary

NDepend indicates to me that I violated 2 critical rules. One to avoid namespaces mutually dependent and the other to avoid having different types with the same name. That sounds weird, but who knows, even I can make mistakes ;)

What's next?

I the near future, I will be integrating the NDepend analysis as part of the build process, therefore I could easily share with you the evolution of this library in terms of quality. If you are interested in such an experience wait for the next post.

As you already know, StoneAssemblies.MassAuth is a work in progress, which includes some unresolved technical debts. But, as I told you once, it is possible to make mistakes (critical or not), but be aware of your code quality constantly makes the difference between the apparent and intrinsic quality of your sources. If you are a dotnet developer, NDepend is a great tool to be aware of your code quality. 

Yeah, you are right, I have some work to do here in order to fix this as soon as possible but also remember, StoneAssemblies.MassAuth is also an open-source project, so you are welcome to contribute ;)

StoneAssemblies.MassAuth Hands-on Lab

A few days ago, I introduced you StoneAssemblies.MassAuth as a  Gatekeeper implementation.

Today, as promised, I bring you a hands-on lab that consists of the following steps:

1. Set up the workspace
2. Contract first
3. Implementing rules
4. Implementing services
5. Hosting rules
6. Build, run and test

So, let’s do this straightforward. 

Prerequisites

• Visual Studio 2019 (16.9.3)
• Docker (2.3.0.4)
• Cake (1.1.0)
• Tye (0.9.0-alpha.21380.1)

Step 1: Set up the workspace

To set up the workspace, open a PowerShell console and run the following commands:

After executing these commands, StoneAssemblies.MassAuth.QuickStart.sln Visual Studio solution file is created, which includes the following projects:

• StoneAssemblies.MassAuth.QuickStart.Messages:  Class library for messages specification. 
• StoneAssemblies.MassAuth.QuickStart.Rules: Class library to implement rules for messages.
• StoneAssemblies.MassAuth.QuickStart.Services: Web API to host the services that require to be authorized by rules.
• StoneAssemblies.MassAuth.QuickStart.AuthServer: Authorization server to host the rules for messages. 

The commands also add the required NuGet packages and project references.

If you review the content of the StoneAssemblies.MassAuth.QuickStart.AuthServer.csproj project file, you should notice a package reference to StoneAssemblies.Extensibility. This is required because all rules will be provisioned as plugins for the authorization server. 

The extensibility system is NuGet based, so we need to set up the build to provision the rules and messages as NuGet packages. For that is the purpose, this workspace configuration includes two more files. The build.cake, a cake based build script to ensure the required package output,  

and the tye.yaml that will help us to run and debug the solution.

 

Step 2: Contract first

Let's add a bit of complexity to the generated problem, related to the weather forecast. For instance, let's say we will allow requesting forecasts from a certain date, as some forecasts may not be available due to the complexity of the calculations.

For that purpose, we will add the following class to the message project, to request the weather forecast with the start date as an argument.

Step 3: Implementing rules

Now we are ready to implement some rules for such a message. Continuing with our scenario, let's say the forecast data is only available from today and up to 10 days. This operation could be more complex through a query to an external database, but for simplicity, it will be implemented as follows.

Step 4: Implementing services

It's time to complete the WeatherForecastController implementation in the service project. It should look like this. 

Notice the usage of AuthorizeByRule attribute on the Get method, to indicate that the input message WeatherForecastRequestMessage must be processed and validated by the authorization engine before the method execution.

We also have to update the Startup class implementation.

  

Basically, the AddMassAuth service collection extension method is called to register the library services and also ensure communication through the message broker. Remember, StoneAssemblies.MassAuth is built on top of MassTransit.  Finally, to read the configuration via environment variables we must update the Program class to this. 

Step 5: Hosting rules

To host rules, we provide a production-ready of StoneAssemblies.MassAuth.Server as docker image available in DockerHub. But for debugging or even for customization purpose could be useful build your own rule host server. So, in the server project, we also have to update the Startup class implementation, to initialize the extensibility system and load rules. 

Again, to read the configuration via environment variables the Program file must be updated like this. 

Step 6: Build, run and test

Let's see if this works. So, cross your fingers first ;)

To build and run the project, open a PowerShell terminal in the working directory and run the following commands.

Open your browser and navigate to http://localhost:8000 to display the Tye user interface. 

You can see the logs of the rules host server to notice how extensibility works.

Let's do some weather forecast requests. For instance with a valid request

the output looks like this

but with an out of range request

the output shows an unauthorized response.

So, as expected, it works ;)

Closing

In case it doesn't work for you, you can always try to review the final and complete source code of this hands-on lab is in the StoneAssemblies.MassAuth.QuickStart repository is available on GitHub. 

Remember StoneAssemblies.MassAuth is a work in progress, we are continuously releasing new versions, so your feedback is welcome. Also, remember that it is an open-source project, so you can contribute too.

Enjoy «authorizing» with pleasure and endless possibilities.