DEV Community: Pathik Desai

Software Architecture Basics: What, How & Why

Pathik Desai — Mon, 26 Sep 2022 14:28:14 +0000

Architecture and Design are widely used terms in software engineering. Every software has some architecture. But what is Software Architecture and why is it given so much importance? Or is it really important? The goal of this write-up is to gain a better understanding with help of some examples.

Let's start with basics.

What is Software Architecture?

There are many definitions of Software Architecture.

Wikipedia says "Software architecture refers to the fundamental structures of a software system and the discipline of creating such structures and systems"

Martin Fowler has defined architecture as "the decisions you wish you could get right early in a project and Architecture is about the important stuff. Whatever that is."

There will be many more definitions. They all are true, but I have found the description in Clean Architecture by Uncle Bob easier to start understanding the concept. Here is my explanation based on that:

There are two aspects (or "value" as Uncle Bob says) of a software:

Behavior: the reason for the software to exist like an email client to send and receive emails, a calculator to perform calculations, etc.
Shape / Structure: it is the foundation on which features (that provide behavior) are built.

Behaviors will change with time as the software needs to adapt to growing and changing user needs. A good architecture will provide shape / structure that makes the evolution of behaviors easier, faster and less expensive.

Architecture's goals are to make it easy to understand (for a developer), develop, maintain (change), deploy and operate a software.

A lot has been said in few lines! It will become clear as we go further.

What is Design?

The difference between Software Architecture and Design is confusing because they both are mixed and sometimes there is no clear differentiation. But still let's try to understand what is called Design.

Architecture is about shape / structure which is fundamental and difficult to change once done. Design is things that are built on the foundation and things that can be changed with relatively less difficultly.

Let's try to understand with an example:

An application has default system settings and user settings. User settings override default system settings. Default system settings are configurable via database and environment variables. Environment variables take priority over database config.
To implement this requires deciding many things like:
1. Configuration Parameter naming standardization
2. Database schema to store configuration
3. APIs / Interface used by other parts of system to fetch and update configuration
4. Classes and their relationships implementing the behaviour required for configurations
#1, #2 and #3 are things that are more expensive to change once implemented and deployed. So they are Architectural Decisions. #4 can be changed relatively easily even after implementation so it can be considered a Design Decision.

Process of Architecting

Architecture in a way is a set of decisions taken in a given scenario.
Most of the times, something can be done in multiple ways, but the Architecture selects one option from that. That choice of one option is the Architectural Decision. E.g.,
- There are multiple protocols to build an API: REST, GraphQL, SOAP.
- The decision to use GraphQL is the Architectural Decision.
So next questions should be how are these decisions made? Inputs to Architectural Decision Making:
1. Requirements
2. Architectural Characteristics (AC) (or Non-Functional Requirements) derived based on requirements and business domain. E.g.,
  - For a stock trading platform, Performance and Reliability are important ACs.
  - For a news aggregation portal, Responsiveness is important - meaning immediately load first 5 stories and load remaining stories asynchronously, so user doesn't have to wait longer to start consuming the content.
3. Implicit ACs: things that nobody will ask for but always expect like Security, Maintainability, etc.
4. Available resources: budget (cost), skills and time. Example:
  - It is identified that writing a serverless function (AWS Lambda) is good choice to perform some background tasks.
  - NodeJS may be the right choice to write a serverless function but do we have skills in the team to build it within the time we have to release the feature?
  - We don't have NodeJS developers but we have Java developers, so is it possible to use Java to write a serverless function?
Most Architectural Decisions are trade-offs. They have some bad outcomes, but still it may be right decision for the given circumstances. If we can live with it, it is easier otherwise we have to try to mitigate its effects. E.g.,
- Writing a serverless function (AWS Lambda) in Java has problem of Cold Start because JVM takes at least few hundred milliseconds to start-up.
- So we have following options. Each has its negative impact but we have to select the one right for current circumstances:
  1. Since the functions will be used in background processing so we decide to live with few milliseconds of performance hit for now and revisit this later if it becomes a serious issue.
  2. In case we cannot afford performance hit, we have to provision at least 1 (or more depending on load) Lambda instance to be active all the time. But this will add to Cost.
  3. Train a developer on NodeJS and then write function in NodeJS. But this will impact timeline.
  4. Find an alternate to serverless function.
Output of Architecting:
- Documentation with reasoning and decisions. It can be diagrams, write-ups, specs, etc.
- Common artefacts:
  - Components and relationships between them
  - Shared libraries and interfaces
  - Deployment view
  - Security scheme - authentication, authorization, secrets management
  - API Schema
  - DB Schema
  - Guidelines like naming conventions, exception handling practices, logging conventions, etc.

Case Study

Let's walkthrough the journey of an application to understand these concepts with an example.

Product Manager (PM) and Engineering Team (ET) discuss requirements.

Stage: Building MVP

PM: We need to build a mobile app that will allow users to send SMS in bulk and check the status of the delivery. Users can manage list of recipients by uploading a CSV or manage via the App.

ET: Do we need to send SMS for each request immediately on receiving request?

PM: No, we don't have to do that now. We put the request in queue and we process requests one by one. Expectation is that we will process it at least within an hour of user submitting the request. This is MVP so we will keep it simple.

ET: How will the user on-board and sign-in?

PM: They will use their mobile number. We will send an OTP and verify the number.

ET comes up with an architecture for MVP and produces artefacts.

Components

Deployment

The architecting process would produce other artefacts like Database Schema, Security Scheme, etc., but we are only including things relevant to the discussion.

1 month after MVP release

PM: We have got an enterprise customer who is interested in using our services.

ET: That's great!

PM: They right now use another provider. They generate a CSV file with requests at scheduled frequency. This file is uploaded to a shared location and the service provider processes the file to send messages. They are interested in trying out our service if they do not have to make any changes to their implementation. Can we make it work?

ET: It should be possible..Let us think about it.

ET comes up with a solution that can be implemented quickly.

Components

A new component FileRequestService is added that will read files and create requests from that. This was possible because core domain logic to manage requests, recipients, etc. was implemented in BulkSenderDomainLib so it can be re-used easily from any part of the system.

Deployment

What went well?

Breaking down system in modules allowed a new requirement to be accommodated very easily and quickly. This kind of requirement was not expected during MVP, but the Architecture was able to handle it.

6 months after MVP

PM: There is lot of interest for our service. Customers really want to use it but we are getting lot of complaints that the messages are delivered after hours.

ET: Because we are getting lot of requests...

PM: But we need to fix this.In fact, we also want to introduce a quick delivery paid plan. We think we will get customers ready to pay for an immediate delivery commitment.

ET: That's going to require a lot of work..

PM: Why..??

ET: We kept is simple for the MVP. We did not provision for scaling for such load.

PM: We better do it right now!

What went wrong?

ET did not identify Scalability as AC\NFR in request processing in the original MVP architecture. That is now causing a problem when the solution needs to scale quickly. This lapse can be costly because it can either force a half-baked solution in hurry or delay business plans.

Should ET always design for scale even when they don't know what is going to be the scale?

Its a trade-off:

a. Building for scalability will add complexity to the solution meaning more time to release.

b. On the other hand, there may be kind of problem we just went to through.

There is no right or wrong approach. If MVP doesn't work, doing a quick release saved effort so (b) would be the right thing.

That's where the Architectural Decision Making is required to find a balance between Long Term Goals and Short-term Needs working with all stakeholders.

In the end..

There is no universally accepted definition or scope of Software Architecture. It also evolves continuously with change in technology e.g., Cloud has added lot of new possibilities that widens the scope of Architecture. We have tried to understand what can be considered Software Architecture. And now if you go back and read all definitions of Software Architecture, you may understand them better.

Instead of exactly defining what is Software Architecture, it is important get a good understanding of Process of Architecting and Importance of making good architecture and design decisions.

This is a vast topic with various perspectives. Lot of the insights come with experience. I have presented my understanding. Please comment if there is anything you would like to add (or remove too :)). Thanks for reading!

References

Clean Architecture by Robert C. Martin

Fundamentals of Software Architecture: An Engineering Approach by Mark Richards, Neal Foad

C4 Model by Simon Brown - Component Diagram uses C4 template

Application Configuration from Operations Viewpoint

Pathik Desai — Sat, 29 Aug 2020 11:00:43 +0000

All software applications would have some configuration. This post is about seeing the configuration from operations viewpoint: its challenges and some methods to manage it better.

Operations here simply means the process of running a software application in any environment like Dev, Test, UAT, Prod, etc.

First let's understand which configuration is being discussed here and what are the challenges.

The Problem

Configuration give broadly two capabilities without modifying the software:

Ability to change the behavior
Provide inputs from outside to make the same software work in different environments or work with different attributes e.g., database connection settings to make it work with different instances of a Database.

Configurability increases complexity but it is required to quickly adapt to the changes especially in Software Products which have to cater to different use-cases in different types of environments. Configurability provides capability to meet those requirements quickly.

The configurations will be of two types:

Settings set by the end users
Configured by the Operations team

#1 is generally well documented and managed by the end users. #2 is where there are some challenges such as:

It often happens that during the process of development, configurations are added by developers and they are very familiar with what should be the correct values but the Operations team / person doesn't have or get that clarity.
As a solution grows, number of configurations grow too and it becomes difficult if a new environment is to be set-up. One would often come across situations where only one or two people in the team can actually set-up the software in a new environment. This can be a serious bottleneck for Software Products where it can reduce the ability to quickly make the product available to customer.

Let's understand this with an example of simple file processor of the Biller Org. File processor processes the daily transaction files uploaded by parteners who accept payments on behalf of the Biller Org and provide transaction details to the Biller Org so that the Biller Org can update its systems to reflect the payments.

File Processor does the following:

Read files from FTP file share
Update the database
Store the original files to Archive, successfully processed to Success, files failed processing to Failed and the logs of each file processing to Log directories on a network share.
It can be set-up to run in two modes (a) process each item in file as one transaction i.e. write failed item to Failed but keep processing (b) proess entire file as one transaction i.e. either entire file is processed successfully or entire file is marked failed.

Let's see the configuration parameters we will need:

Database connection settings
FTP Share access settings
Paths of Archive, Success, Failed and Log shares
Flag to control the mode of transaction - File or Item

This needs to be set-up in every environment and for each partner, and in a real system there would many such jobs.

Mitigation

Configurability is beneficial and required so we can't completely do away with the problems discussed above, but there can be some ways it can be made more manageable as we see below - this is not an exhaustive list.

Documenting with configuration

Document each parameter in the configuration file itself - or add a column in database if it is being kept in a database.

Continuing with our example, the configuration file can be like this:

# USE: Control transaction mode of the processing.
# EXPECTED VALUE:
#  ITEM - Consider each item as one transaction
#  FILE - Consider entire file to be one transaction
app.transaction-mode: ITEM
#
# USE: Store original files after processing
# EXPECTED VALUE: Full path to the directory
app.archive-path: <some path>
#
# USE: Store failed files after processing
# EXPECTED VALUE: Full path to the directory
app.failed-path: <some path>

This could be made part of the Code Review process where a new configuration without enough documentation is not accepted.

This will make sure that anyone can get a good idea of what to do right in the place where the values need to be configured.

Convention over configuration

Convention over configuration is used by many frameworks to reduce the amount of configuration \ boilerplate code required - all MVC frameworks follow this pattern. The same can applied in application configurations.

In the above example, the number of configurations can be reduced:

# USE: Control transaction mode of the processing. Set if you want to change Default.
# EXPECTED VALUE:
#  ITEM - Consider each item as one transaction
#  FILE - Consider entire file to be one transaction
# DEFAULT: ITEM.
# app.transaction-mode: ITEM
#
# USE: Store output files after processing. Program will create Archive, Success, Failed and Log directory under this path.
# EXPECTED VALUE: Full path to the directory
app.output-path: <some path>

The reduction is due to following two conventions:

Default transaction mode is assumed to be ITEM if it is not set. So you only configure the parameter, if you need to change the default. Default can be decided based on commonly expected value.
Instead of taking four directory paths, take path of root and then always create directories under that: Archive, Success, Failed, Log. This will potentially reduce some flexibility, but improve maintainability.

Scripts / Tools to detect errors

If you have an application that runs on 100s or 1000s of desktops (or simply machines irrespective of they are servers or desktops) and the configuration resides on those machines, it is very difficult to troubleshoot issues as you do not have access to the machine and can't check whether all the configuration parameters are correct or not. Having some script or utility that can scan the configuration and highlight any problems can greatly help the operations.

AWS has a service named AWS Config which can be configured to monitor compliance to a desired configuration of your environment. It will highlight if it detects any violation from the desired state e.g., it is configured to monitor that only port 443 should be open on EC2 Instances so it will raise an alert if it finds some other port open on the server.

Configuration in Containerized Deployments

Containers are started from an image which has the application installed in it. Now, if configuration is included in the image along with application, an image is required for each environment - or each change to configuration.

Therefore, configuration needs to be externalized. Common pattern is to keep the configuration in a repository, vault, shared storage, etc. and provide the application access parameters to the store by setting environment variables in the container.

Configuration in Single Page Applications

Dynamic configuration is not straightforward in an SPA e.g, you want to toggle some features in some environments, feed API endpoints that SPA should use dynamically rather than at build time.

This is so because SPAs are bundled and the bundle is referenced in landing page. Browser retrieves the bundled file from server and executes it which loads the SPA and starts its lifecycle. So the SPA execution is entirely on the client i.e. browser and it is not possible to inject configuration like we do on server or an application installed on desktop.

This article explains the problem and possible solutions in the context of Angular.

Conclusion

Key takeaway is that running highly configurable software can also be a challenge: configurability can become a liability instead of an asset. Managing configuration should also be a criteria during design and development.

Exception Handling in Different Types of Applications

Pathik Desai — Fri, 24 Jul 2020 11:25:00 +0000

Introduction

Exception handling is common to most programming languages and the mechanisms and behaviours are similar in most languages: try\catch\finally. It is well documented. We are not going to discuss that.

However, different approach to exception handling is required in different types of applications like a Library, a UI application, a Framework, etc., and that is the focus of this post. We'll see how exception handling needs to change depending on the nature of the application.

Let's start with some fundamentals.

What is an exception?

Exception is an event during the execution of a program that disrupts the normal flow and prevents the program from doing what it is expected to do e.g., a program tries to write to a log file but the file cannot be opened.

In such error conditions, runtime looks for handlers (try-catch) that are registered to handle such excceptions and when a handler is found, it is invoked with an Exception object having information about the event. The following diagram shows the normal flow of the program (Runtime > main > Method1 > Method2) and the flow when an exception occurs in Method2.

When an exception is not handled by a program, it reaches the runtime where it will be considered an unhandled exception which may result in a crash.

Two Pass vs One Pass

.Net Runtime has Two Pass exception handling implementation. Two Pass means the runtime first traverses through entire call stack to find a handler, and after either finding a handler or determining that it is an unhandled exception, it runs all the finally blocks in the call stack.

JVM on the other hand runs finally block in a method if a handler is not found in that method and then it moves up the call stack.

See CLR Exception Handling and JVM Exception Handling for detailed explanation.

Asynchronous Execution

Exception handling in asynchronous execution is important to understand. Let's see with an example.

The following is a Java code that runs a method on new thread and exits.

public class AsyncRun implements Runnable {
  @Override
  public void run() {
        // TODO Auto-generated method stub
    System.out.println("AsyncRun.run on thread " + Thread.currentThread().getId());
    throw new ArithmeticException();
  }    
}

public static void main( String[] args ) {
  try {
    Thread t = new Thread(new AsyncRun());
    t.start();
    System.out.println( "main on thread " + Thread.currentThread().getId());
    throw new NullPointerException();
  }
  catch(Exception ex)
  {
    System.out.println(ex.getClass().getName() + " handled");
  }
}

This would be the output:

main on thread 1
AsyncRun.run on thread 15
java.lang.NullPointerException handled
Exception in thread "Thread-0" java.lang.ArithmeticException
        at exceptionhandling.AsyncRun.run(AsyncRun.java:13)
        at java.base/java.lang.Thread.run(Thread.java:835)

NullPointerException thrown by the main method is handled by the try-catch in main, but the exception in AsyncRun.run method is treated as an unhandled exception because JVM could not find a handler in the call stack on the thread running AsyncRun.run. AsyncRun.run is the first method to be called on the thread so the call stack ends there, the try-catch in the main method won't apply to AsyncRun.run.

However, unlike main thread, unhandled exception on a separate thread did not result in a crash. .Net has same behaviour as Java for asynchronous execution.

Alternative to Exceptions

Alternative to Exceptions is error handling, but for that program has to validate all scenarios and return different error codes e.g., a function writing to log files would have to first check if file exists and then return an error code if it doesn't, and the calling function needs to check the return value to see if the call was successful or not. This can be very unproductive and error prone.

Why handle exceptions?

Exception handling is required primarily for the following reasons:

Prevent crashes: Unhandled exception may result in application crash. So even to prevent a crash an application needs to handle exceptions.
Alternate flow: In some cases, there may be a need to change the flow of the program in the event of an error condition e.g., in online shopping portal, when a payment API request throws exception, user journey would require the application to handle it and take the user back to the basket page so that user can initiate the payment again.
Logging: This is required for troubleshooting.

Where to handle exceptions?

Where to handle exception is very important and broadly there are two types of places where exceptions should be handled:

All Entry Points in to the program \ application to prevent crashes. As we have seen above when an exception reaches the runtime or framework, it may cause a crash. Entry Points can be one or more like:
1. main method
2. Event handlers in a UI application - SPA or desktop application
3. Public methods on a Controller in MVC
4. Starting method of a background thread
To support different flows in the event of an error, exception handling is required where such diversions need to be implemented.

Exception Handling by Application Types

Now let's try to see how all this applies for different application types:

Library

A library is a set of functions / classes focusing on some problem domain.
Libraries do not control the flow of program. Functions of libraries are called by the main program with some input and they return some output or provide some behaviour e.g, RecommendationEngine executable uses libraries for logging, data access, etc. to perform its job but the flow of program is controlled by the executable only.

Responsibility to prevent a crash or implement an alternate flow lies with the main program.
Therefore, code in a library should not suppress exceptions because that would prevent the calling application from fulfilling alternate flow and logging requirements - it can catch exceptions and rethrow or provide expected output by catching exceptions.
There can be scenarios where a library needs to handle exceptions like in the following case, but it should not suppress the exceptions. E.g., continuing with the above example, let's say the data can come from MySQL or MongoDB so DataAccess library itself relies on other libraries. But to make RecommendataionEngine depend only on the DataAccess library, the DataAccess library can handle exception from MySQL and MongoDB and then throw its own exception. Re-throwing would ensure that RecommendationEngine gets a chance to decide what to do with the exception.

API

APIs can be thought of as a library of functions exposed over a network e.g., continuing earlier example, if there is a decision to expose Data Access APIs as REST APIs, it would look like the following.

As in the case of Library, the caller of API (RecommendationEgine) should handle the exception, but because of the change in nature of invocation of Data Access APIs, exceptions need to be handled for the following reasons:
- Data Access API as Library: in this case, when an exception occurs, the caller (RecommendationEngine) is in same process and the runtime lets it handle the exception - also the exception object would provide details about what happened so that caller can take appropriate action.
- Data Access API as REST API: here the caller (RecommendationEngine) is not in the same process. Caller is expecting a valid HTTP response from the REST API. So if the API itself doesn't handle exception, the framework (ASP.Net MVC, Spring MVC, etc.) has to handle it and return a valid HTTP response, which may not provide enough details to the caller about the error.
- So REST API itself should handle the exception and return a response that the caller can use to determine that there was an error. In this case, the response (API Response Body) will have to carry error codes and caller should perform actions based on error codes.

UI Application

Almost all UI applications are written using some framework with the framework calling the application when there is some event. This makes the event handlers an entry point in to the application so exceptions should be caught on event handlers.
Additional exception handling in a UI application will vary based on what the application is doing e.g, if the application is doing work on background threads, the entry points \ starting methods of the thread should handle exceptions.

Framework

Framework is an implementation of Inversion of Control pattern. Framework discovers, loads and calls its plug-ins on events a plug-in is interested in. Both the framework and the plug-ins communicate with each other using known public interfaces e.g,

This is how it works:
- (a) Spring (framework) discovers controllers with @Controller annotation on a Class
- (b) DI container would initialize the classes (or load plug-in) by calling their constructors
- (c) when a HTTP request for a matching URL is received, Spring MVC calls appropriate method on the plugin (Controller instance created in (b)) and returns the response.
In the above diagram the calls from Spring to the application - marked with X - are vulnerable points as Spring cannot assume that the application would not throw exceptions, so it would handle exceptions e.g., if UserController.create method throws exception, Spring MVC would handle it and trigger alternate flow to return an appropriate HTTP response indicating error.
So a framework must handle exception in all the places where it is invoking methods on its plug-in.
Framework itself cannot be the reason for a crash so it must make sure that it internally doesn't allow any exception to go unhandled and reach the runtime because that may result in a crash.

Summary

Any application should not let exceptions go unhandled with the exception of Libraries. At the minimum, all exceptions should be handled at the entry points in to the application.

Generics Implementation of Java and C#

Pathik Desai — Tue, 23 Jun 2020 05:29:04 +0000

Introduction

Generics are very powerful and commonly used in both Java and C# programming - especially in frameworks and libraries.

Generics primarily provide type safety and improved performance by avoiding the need to cast variables.

If you have been using C# generics and then use generics in Java - or vice versa, you will notice that both Java and C# generics look very similar. But they are very different in terms of how they are implemented and as a result what capabilities they have. We'll see that in the rest of this post.

Generics Implementation

Generics support in a language is required at both compile time and run time. Let's use an example to understand this better.

A library common-lib declares a generic type as shown below. This library is built and published which is then used in other programs.

public class GenericTest<T> {
    private T _ref;
}

An application named demo-app uses common-lib

public class App{
    public static void main(String[] args){
        GenericTest<MyClass> t = new GenericTest<MyClass>();
        GenericTest<SomeClass> s = new GenericTest<SomeClass>();
        //s = t; //allowed? type safety?
    }
}

common-lib and demo-app are physically different artifacts. When demo-app is compiled, the compiler needs to know that GenericTest<T> is a generic type so it should be treated differently. Therefore when common-lib is compiled, the compiled output should have information about the generic type. This will allow compiler to ensure type safety in demo-app at compile time - both Java and C# guarantee compile time type safety.
Reflection is supported by both Java and C#. Reflection APIs allow accessing type information at run time and create new objects, call methods on an object, etc. at run time. To support all these operations on generic types, generics support is required at run time also.

Java Generic Code Lifecycle

Compilation

Java uses the concept of Type Erasure to support Generics in Java. Through Type Erasure, Java compiler converts all Generic type references to non-generic types at the time of compilation. Type Erasure approach was used to provide backward compatibility so that non-generic types can be passed to newer code written using generics.

Let's understand with an example. The following is a simple generic class.

public class GenericTest<T> {

    private T _ref;

    public <T1 extends Comparable<T>> boolean isEqual(T1 obj){
        return obj.compareTo(this._ref) == 0 ? true : false;
    }
}

When this class is compiled, the generic type parameters are removed and replaced with non-generic equivalents. Following is the generated byte code - shown by Bytecode Viewer:

See the difference between source code and the compiled version:

//source code
public class GenericTest<T>
//compiled code - GenericTest<T> became just GenericTest
public class generics/example/application/GenericTest

//source code
private T _ref;
//compiled code - T was replaced with Object
private java.lang.Object _ref;

//source code
public <T1 extends Comparable<T>> boolean isEqual(T1 obj)
//compiled code - T1 became Comparable because
//of constraint that T1 should be subtype of Comparable<T>
public isEqual(java.lang.Comparable arg0)

Compiled Java code does not have any trace of generic types. Everything is mapped to a raw Java type.

One of the side effects of Type Erasure is that GenericTest<T> and GenericTest are same after Type Erasure by the compiler, so it is not possible to have both in same package.

Runtime

At JVM level, there are no generic types. As explained in the earlier section, Java compiler removes all traces of generic types so the JVM doesn't have to do anything different to handle generic types.

C# Generic Code Lifecycle

Compilation

Following is the equivalent C# code of the above example in Java:

public class GenericTest<T>
{
    private T _ref;

    public bool IsEqual<T1>(T1 obj) where T1 : IComparable<T>
    {
        return obj.CompareTo(this._ref) == 0 ? true : false;
    }
}

When the above code is compiled, the C# compiler retains the generic type information, which is used by the .Net Runtime to support generics.

A peek in to compiled library using IL Disassembler:

IL Code of IsEqual method (same as byte code of Java) - see underlined sections:

Runtime

.Net Runtime (CLR) uses the generic type information in the compiled code to create concrete types at runtime. Let's understand with an example.

Following code creates three objects of GenericTest<T> for three different types.

GenericTest<int> intObj = new GenericTest<int>();
GenericTest<double> doubleObj = new GenericTest<double>();
GenericTest<string> strObj = new GenericTest<string>();

When this code is run, the .Net Runtime would create three concrete types dynamically based on the original GenericTest<T> generic type definition:

GenericTest<int>: T replaced with int. This type will be used to create all new objects of type GenericTest<int>
GenericTest<double>: T replaced with double. This type will be used to create all new objects of type GenericTest<double>
GenericTest<Object>: T replaced with System.Object. This type will be used to create all new objects of any reference type like GenericTest<String>, GenericTest<FileStream>, GenericTest<SomeClass>, etc.

.Net Runtime creates a new type for each primitive \ value type, which gives both type safety and performance benefit by avoiding boxing operations.

For reference type, there is only type and the .Net Runtime type safety mechanism ensures type safety.

What's the impact?

Due to the nature of implementation, there are few areas of differences between Java and C#:

Primitive Types support
- Java generics do not support primitive types - because Type Erasure cannot work in that case.
- C# supports primitive types (or Value Types in C#) in generics which gives two benefits (a) type safety and (b) performance benefits by removing boxing and unboxing needs - this is achieved by .Net Runtime's dynamic concrete type creation.
- There is an open item JEP 218: Generics over Primitive Types to support primitive types in Java generics
- An outcome of the above limitation in Java are number of Functional Interfaces like IntFunction, LongFunction, etc. If primitive types can be supported by generics, only one interface can be enough:

public interface Function<T,R> {
    R apply(T value);
}

Type Erasure inserts casts wherever required to ensure type safety, but this will add to performance cost rather than improving performance by avoiding casts with Generics. E.g.,

public void test() {
    ArrayList<MyClass> al = new ArrayList<MyClass>();
    al.add(new MyClass());
    //Compiler would add cast
    MyClass m = al.get(0); //source
    //MyClass m = (MyClass)al.get(0) //compiled
    //this will be fine as al.get(0) anyway returns Object.
    Object o = al.get(0);
}

Run time operations - If you have to do runtime type checks on T (T instance of IEnumerable), reflect on generic types, or do new T() kind of operations, it is either not possible in Java or you have to use workarounds. Let's see an example.

Let's write a function that deserializes Json string to an object using generic parameters.

Following is the C# code for the same that would work:

public static T getObject<T>(string json)
{
    return (T)JsonConvert.DeserializeObject(json, typeof(T));
}
// usage
// MyClass m = getObject<MyClass>("json string");

But same thing can't work in Java as T.class would not compile.

public static <T> T getObject(String json) {
    ObjectMapper m = new ObjectMapper();
    return (T)m.readValue(json, T.class);
}

To make the above code work, getObject method has to receive the Type.

public static <T> T getObject(String json, Type t) {
    ObjectMapper m = new ObjectMapper();
    return (T)m.readValue(json, t.getClass());
}
//usage
// MyClass m = getObject<MyClass>("json string", MyClass.class);

Summary

In the end, both Java and C# provide compile time type safety using different approaches. Due to support at runtime level, C# is able to provide performance benefits and more run time operations support.

References

C# Generics Internals
If you want to go to memory level details, read .Net Generics under the hood
Very detailed comparison of features - Comparing Java and C# Generics - Jonathan Pryor's web log
Core Java SE 9 for the Impatient

Software Security Overview

Pathik Desai — Sat, 16 May 2020 12:32:12 +0000

Introduction

As a developer, when you think of security, what comes to your mind? Is it clear what are different aspects that need to be handled to make your software secure? And why you need to do that?

Objective of this post is to provide that view and articulate what controls should be in place and how. Details of how to apply those controls would require separate posts and are not covered here - and lot of content is available on the web.

What is Software Security?

Security implementation of a software application can be classified in two parts:

Pre-deployment - building a secure software
Post-deployment - security of the environment where software is running

Software Security is pre-deployment. It is the process of identifying risks and building controls (or Countermeasures as it is called in security terminology) in the software itself while it is being built.

Software Security is the focus of this post. We will see controls commonly used and what risks they mitigate.

For more details on the topic, see What is Software Security by Gary McGrow

Nature of security

A software application would generally have two aspects:

a. Services that provide some functionality
a. Data generated and consumed by the services

Security can be defined as defending services and data from unauthorized and malicious usage at all times.

Defending is the key word here. Defense literally means an act of resisting an attack. That means attacks can happen anytime and any number of times, and we need to keep protecting the system from these attacks.

That's what makes security of a software application very difficult because to it is not easy to to get it right all the time.

Also, there is no room for error. One incident may be enough to destroy the reputation and business built over the years.

How to approach security?

The following is the minimum that should be done:

Follow industry best practices rather than inventing our own mechanisms. These best practices have come out of years of learning and it is better to rely on that tried and tested knowledge.
Secure by design: make security a criteria in all aspects like Requirements, Architecture, DevOps, Engineering Practices like code reviews, unit testing, application testing, etc. This would ensure that everything is built secure by default - security is not thought of after delivering the functionality which happens on many projects.

What would make a software secure?

CIA triad (or AIC triad) is commonly used for Information Security, but it also helps to better understand security in general. A software should have the following properties to be secure:

Confidentiality: Authorized access to services and data e.g., to view your GMail mailbox and send emails, you must successfully login to GMail.
Integrity: Integrity and authenticity of data presented (in transit) and stored (at rest) e.g., the emails shown by GMail are exactly how they were sent by the sender and content is same as that stored on GMail servers.
Availability: Software is always available to all authorized users for all legitimate use-cases e.g., GMail services are always available to its users.

Design Principles

See Secure Design Principles by OWASP for details.

Defense in depth is a very important principle to follow while designing the software. In simple terms, it means to have controls at different layers. It will ensure breach at one layer will not result in failure. We'll see some examples later in the post.

Controls

The following are the controls that are commonly used. A combination of these controls can be implemented depending on the risk.

These are commonly used controls. This is not an exhaustive list e.g., though it is not included above, applying signatures on every request and response can be used if the risk is high and require that level of security.

We will look at each of these. However, they build on the security building blocks like authentication, cryptography, certificates, etc. If you are not familiar with these concepts, recommend to go through Software Security Building Blocks

Authentication

Why?

Authentication is required to perform authorization. Authentication will establish the identity of the entity trying to access the software, and based on that authorization can be applied.

How?

There can be two types of authentication:

Authenticating an end user
- OAuth2 and OpenID Connect are widely used protocols for this.
- There are number of identity management services that support these protocols.
- Using standard protocol rather than custom authentication mechanism would make integrations with other systems easier.
Authenticating a client
- Two commonly used methods to authenticate a Client (a program calling an API):
  1. OAuth2 - Client Credentials Grant: This is an OAuth2 workflow that allows a client to authenticate itself using a client-id and a client-secret and acquire a token which it can then use to call APIs.
  2. TLS Mutual Authentication: both Client and the Server trust each other's X.509 certificates used to establish TLS connection. Connection is established only if trusted parties try to connect. This is suitable in server-to-server communications e.g., when you call external APIs from your backend.
- For Web Applications that rely on cookie based session tracking, authenticating legitimate requests from client (Browser) is required to avoid Cross Site Request Forgery (CSRF). Watch this video to see a demo.

Authorization - for Confidentiality

Why?

Authorization in this context is required for the following objective:

Authenticated entity - a user or a client - can access only the data that they are supposed to access
- When you login to GMail, GMail does not show someone else's emails to you.

How?

All read operations on data associated with a user should have the following checks:
1. The logged-in user is same as the user associated with data e.g., User Id on a payment transaction record must match the User Id of logged in user. The same check can be applied to clients if required.
2. If 1 is not true, the logged-in user has privileges to access other user's data.

Authorization - for Integrity

Why?

Authorization in this context is required for the following objective:

Authenticated entity - a user or a client - can perform only those data manipulation actions that they are authorized to.
- When you login to Outlook, you cannot manage someone else's calendar unless the other person has given you permissions to manage his or her calendar.

How?

All operations should have the following check:
- Is the logged-in user authorized to perform the operation?
  - If Role Based Access Control (RBAC) is used, is a role required to perform this operation assigned to the logged-in user? Spring Security and .Net Framework easily allow such access control using declarative methods - annotations \ attributes.
- The logged-in user is same as the user associated with data that is being modified e.g., User Id on a payment transaction request must match the User Id of the logged in user.
Client Authorization
- When you have APIs that can be consumed by multiple clients, authorizing clients is also important e.g., in a Microservice architecture, API gateway can block requests if client is not authorized to use an API

An admin can disable a user so it should be allowed from Admin Portal client only. If you use OAuth2, the tokens carry Client information and this can be done easily.

The same check should also be applied on the microservice - remember Defense in depth? In case someone mistakenly removes check on API Gateway, microservice will still block the client.

Data Privacy

Why?

Personally Identifiable Information (PII) is any data that can identify an individual e.g., Mobile Number, Email address, etc. Unauthorized access to such information can be a breach of privacy.

How?

Identify PIIs captured by the software.
Do not display PIIs without masking e.g., mobile number as 98XXX XXX76.
All communications like email, SMS, etc. should mask PIIs.
Do not write PIIs to the log files in plain text.

Input Validation

Why?

Accepting invalid input can compromise the integrity of the data e.g., accepting a past date on payment transaction request would result in incorrect state of the system.

Lack of input validation can pose a vulnerability for Cross Site Scripting (XSS) attacks. Watch this video for quick intro to XSS.

How?

Inputs should be validated at all layers - remember Defense in depth!
Sanitize all text input to remove <script> tags. Otherwise the same text might end-up in a malicious script being executed when it is displayed on the browser - that's XSS in nutshell.
If a file is being uploaded as part of some functionality, it should also be treated as an input and be validated - scanned and format validated if required.

TLS \ HTTPS

Why?

Security of data when it is in transit. It protects against Man-in-the-middle attack which can compromise both integrity and confidentiality of the system.

How?

Always use TLS 1.2 (currently latest) and HTTPS for all internet traffic.
In mobile applications, implement SSL Pinning to make sure the mobile app always talks to "your" server only. See Android Security: SSL Pinning for details.

Encryption and Hashing

Why?

Security of data at rest (when stored) is as important as security in transit. Storing encrypted or hashed data will protect unauthorized access to data at rest.

How?

Identify data that needs to be stored encrypted or hashed. Hash of a password is stored so it is irreversible even with the keys.
Encryption key and the data should not be stored together e.g., in same database.
Challenges
- Encrypted data is as secure as the key it is encrypted with. Therefore, management of encryption key is very important when encrypting data at rest.
- Performance trade-off
  - having to decrypt data on all read operations will impact the overall responsiveness of the system if frequently used data fields are stored encrypted.
- Key rotation is challenge
  - Once data is stored with an encryption key, it has to be decrypted with the same key.
  - When data starts accumulating over the years, rotating the encryption key becomes a challenge because existing data needs to either (a) be re-encrypted with new key, which may be challenging in a live system or (b) handle multiple keys and key-data mapping in program itself, which can also become very complicated.

Auditing and Logging

Why?

Auditing helps to track the change in state and who caused that change e.g., if a user's name was updated, audit records will capture when it was updated and who updated it. This can be useful in event of an incident.
Logging also helps to trace errors and troubleshoot issues.

How?

Auditing is straightforward. Hibernate makes it very easy in Java.
Logging to is straightforward, but in distributed architecture using ELK Stack or something similar is important to see all logs in one place.

Secrets Management

Why?

Secrets are database password, API access credentials, encryption key, etc.
Most of these are configurations but if they are left in plain text, it poses risk as they can be misused.
- Let's say you use an external SMS service provider to send SMS. If the API access credentials for this external service are not protected, there is a risk of someone being able to send SMS on behalf of you.
- Comprised encryption key is even bigger risk.

How?

You can use AWS Secrets Manager, Vault, etc. to store such secrets.
Alternative is
1. Keep secrets encrypted in normal configuration - properties file or web.config.
2. The encryption key is stored in AWS Secrets Manager, vault, etc.
In a Single Page Application (SPA) and Mobile Application, a JWT token would be used to call APIs - token is passed in Authorization header with every request. Since it is a bearer token, anyone with the token can use the APIs. The token should not be stored on clients more than required

NOTE: There is trade-off between security and usability. Most applications (web and mobile) keep users logged in forever, which means they have to keep a token with long validity on the client - in browser local storage or mobile. This is a risk. So a decision has to be made based on nature of the application.

Sender Policy Framework

Why?

Let's say your application sends emails from connect@myapp.co address. If someone else is able to send emails using the same domain myapp.co, it can impact your reputation and business. This is called Spoofing.
Sender Policy Framework prevents such misuse of your domain and assures authenticity of emails.

How?

This is configured with a DNS entry. See What is SPF for details.

Resiliency

Why?

Resiliency here means ability of the application to be responsive (operational) in the event of a failure. Read Reactive Manifesto for detailed explanation.
In the context of security, we can loosely define resiliency to the following:
- In the event of a sudden increase in load (with malicious intent i.e. Denial of Service (DoS) attack), can the system remain operational?
  - All cloud providers have services that provide protection against DoS \ DDoS attacks, but these are reactive in nature and may take a little time to react. The application should be able to withstand that otherwise the protection is of no use.
- How quickly the application can recover in the event of a downtime?

How?

There are different modern architecture patterns to achieve resiliency, but in any case - even monolith architecture, the system can be resilient with following implementation:

Elasticity
- Elasticity means ability to scale up or down depending on the load.
- It is easy implement with Load Balancing and Auto Scaling in any cloud environment.
Automation
- Automated builds and deployments is critical to quickly recover in the case of a failure.
- Unit testing and Test Automation would also help to do quick releases for urgent patches.
Configuration Simplicity
- Configurations keep getting added to a software as it evolves and often it become very difficult to correctly configure the software.
- This is important to have quick recovery in case of a failure.

If you have reached this far, you are patient and dedicated person! Thanks for reading :)

Software Security Building Blocks

Pathik Desai — Sat, 16 May 2020 08:04:30 +0000

We'll cover the following building blocks:

Secure communication
Authorization

Secure Communication

TLS \ HTTPS is the means for secure communication between a service and a client. However, for TLS to work, the following are required:

Cryptography
Cryptographic Hash Function
A way to exchange cryptographic keys - done using X.509 certificates
Authenticating certificates

Once all these things are in place, TLS protocol can establish a secure communication channel. We'll go through these one by one.

Cryptography - Encryption & Decryption

Cryptography is process of converting plain text in to unintelligible text and vice versa. Encryption converts plain text to unintelligible text and decryption does the revers of it.

Cryptographic algorithms can be divided in to two types: Symmetric Key and Asymmetric Key.

Criteria	Symmetric Key	Asymmetric Key
Keys	Same key is used to encrypt and decrypt	A key pair private key-public key is used. Private key is not shared with anyone. Public key shared with everyone. Data encrypted with private key can be decrypted ONLY with public key and vice versa
Algorithms	AES 256	RSA

See How Symmetric Key and Asymmetric Key cryptography works explained in very simple terms.

Hashing

Hash functions are algorithms that take a text of any length and produce a fixed length text. The output is same as long as the input is same e.g., Input = "This is test" and Output of Hash function = "112345", it will always give this output for same input.
The reverse is not possible. "112345" cannot be converted to "This is test"
Passwords are stored as hash values so that they can only be compared (hash of entered password = hash stored in database) but cannot be recovered by anyone.
SHA family of algorithms for hashing.

X.509 Certificate

X.509 certificates are used to associate a public key to the entity that owns it - it can be an organization, a website, or an individual.

Clicking on padlock in any browser shows the X.509 certificate associated with the domain. It has public key and many other information.

Certificates are issued by Certificate Authorities (CA) who are trusted by browsers. In Chrome, Go to Settings > Privacy and Security > More > Manage Certificates, to see root and intermediate CAs trusted by the browser.

Digital Signatures

Digital Signatures ensure the following:

Integrity of message - message is as it was sent
Authenticity of message - message has come from original source
Non-repudiation - sender cannot deny sending the message

Digital Signatures are not limited to internet but it is easy to understand it in the context of traffic on internet. This is how it will work:

Let's see how the three objectives are met:

Integrity - if hash values match, message was not modified in transit
Authenticity - signature decrypted with public key and hash values match, so the signature was generated with private key.
Non-repudiation - if #1 and #2 are met, sender cannot deny sending it because otherwise both #1 and #2 would fail.

X.509 certificates are signed by the CA and browser validate the signatures in similar way e.g.,

SecureOne, Inc is a root CA and trusted in chrome. It has issued a X.509 certificate to yourapp.co
when you open yourapp.co in browser, browser gets X.509 certificate from yourapp.co server.
It tries to validate the certificate by validating its signature - it has public key of the root CA in its store.

See How the X.509 certificates are validated explained in very simple way.

Transport Layer Security (TLS)

TLS builds on everything we discussed above. Its predecessor is SSL (Secure Socket Layer). TLS is meant for a secure connection at Layer 4 \ transport layer.

HTTPS is HTTP on TLS. TLS 1.2 is the latest version supported by browsers.

See TLS and HTTPS explained in simple terms.

Whenever you open a website in browser, underneath a process happens called TLS Handshake which establishes a secure channel between browser and server. See How certificates play a crucial role in securing traffic on internet for simple explanation of the handshake.

Authentication

Authentication is the process of validating whether an entity is who it claims to be e.g., when you login to Gmail with youremail@gmail.com, "youremail@gmail.com" is the entity and Gmail validates that by matching the password you provide with what is stored in its database.

Credentials are required to validate the identity. There are three types of credentials that are generally used:

What user knows e.g., password
What user possesses e.g., OTP on mobile, link in email, etc.
What user is e.g., fingerprint

When a combination of these types is used, it is called Two-Factor \ Multi-Factor Authentication. This is decided based on criticality and usability of application.

Authorization

Once authenticated, authorization is the process of evaluating whether the authenticated identity can perform an action or not.

For most applications, real need is Authorization but it is not possible without Authentication.

Now that you have understood the basics, read Software Security Overview to get an overall view of building a secure software.

Modularity in Java and .Net

Pathik Desai — Thu, 14 May 2020 11:53:49 +0000

We’ll explore modularity in Java and .Net platforms, but before let’s first spend a little time on understanding what and why of modularity.

What is a Module?

Dictionary say a module is “one of a set of separate parts that, when combined, form a complete whole”

So a module needs to have two main characteristics:

Provide one or more related set of services via a standard interface — having standard interface would make a module reusable and replaceable
Hide implementation details from the consumers of the services

What is Modular thinking?

Modular thinking would involve the following:

Break down the problem in small parts i.e. modules. Each part would satisfy the following:
- Each module is focused on one or more related services \ functions
- Services are exposed using a standard interface
- Each module can potentially be used in any place where the same services are required
Create the final solution by composing different modules together

Almost everything around us is an example of modular thinking e.g. Automobiles, Personal Computer, Electronic Devices, etc.

Most of today’s software are built using tools and platforms that are built in modular approach e.g., Spring Framework and .Net Framework, two very popular frameworks in Java and .Net, are both modular in nature. Both have number of modules (libraries) and those modules can be used (or reused!) in solutions for different problems.

But why Modularity?

What do we gain from modular approach to the solution? I think the following three are the primary benefits:

Reuse : Same module can be reused elsewhere, saving time and effort
Stability: A change in the system is reduced to small area (implementation is hidden from consumers) and that allows more complete testing in shorter time.
Parallel Execution: Multiple modules can be developed by different teams in parallel and final solution built by composing those modules. Saving time to market.

Logical & Physical Modules

In software applications, logical grouping of functions and services is done to create a modular design. This would be an outcome of the application of Software Architecture principles on the problem domain e.g., the following modules may be identified for a Ticket Booking application, each focused on a specific area of the solution.

However, that’s still a design of the software application. Working software (application binaries) they can be in one of the two forms shown below:

a. an executable file containing all the modules. Here, the modules may internally be organized separately in the source tree of the application, but physically they all are in one executable file produced by building the application.

b. each module is a library and the application is using the libraries. Libraries are built and released separately from the main Application.

Option (b) is the modular approach that we all are familiar with and use everyday. Option (b) gives all the benefits of modularity listed above.

It is said that Unit of Release is the Unit of Reuse. There is no scope for reuse in Option (a).

Required Platform Capabilities

To support the modularity of option (b), a platform needs to have at least the following capabilities:

Encapsulation : Encapsulation at module level. This is to ensure consumer uses only standard public interface and the details are hidden. Consumers cannot build dependency on “details” so that details can change without breaking anything e.g., in a logging library, com.mylogger.api.Logger is public interface and com.mylogger.service.impl.FileLogger is the class implementing logging to file. Users of logging library should not have access to FileLogger so that FileLogger can change without breaking any dependent application.
Dependency Management : Since each module would also depend on some other module, there needs to be a way for each module to declare its dependencies.
Dependency Discovery : Once a module has declared its dependencies, the platform needs to discover those dependencies (modules i.e. libraries) at runtime, load them and make them available.
Versioning : Versioning of modules is required to let each module evolve independently without breaking other modules depending on it.

Comparison of Java and .Net platforms

Let’s compare Java and .Net on these parameters

*The package structure at runtime is used to locate .class files. JVM would look for exact same directory structure as the package name e.g. all types under “com.covidservice.api.service” should be found under “com/covidservice/api/service” on the Classpath JARs. So a package is not really treated as a dependency by JVM. JVM searches for .Class file when it has to create a new Class or Instance — this is different from how dependencies are managed in Java 9 and .Net.

**Java does not support versioning at JVM layer. The versions of JARs are maintained using naming convention i.e. including version in JAR filenames like spring-web-1.0.0-RELEASE.jar. If you have wrong version on Classpath or Modulepath, JVM would use that as long as the .Class file (Java 8) or Module (Java 9) are found.

OSGi — Dynamic module system for Java

OSGi is an industry alliance for “a vendor-independent, standards-based approach to modularizing Java software applications and infrastructure”. OSGi was formed in late 1990s.

There are many implementations of OSGi specifications like Apache Felix, Eclipise Equinox, etc.

OSGi component system is used to build Eclipse IDE, JBoss, WebLogic, etc.

Summary

Modular architecture is a necessity once complexity and scope grows beyond certain point. It is difficult to introduce modularity at a later stage so better to do it from beginning.

Modular design can be created by applying principles of Software Architecture, but platforms used to build the software need to support modular architecture. Java 9 and .Net are more capable than Java 8 — for reasons explained above — to enforce modularity