I started to play with it and something was triggered in me because my mental model was under a challenge, so I started to study it deeply and my answer for the previous question is the type system. I was a NodeJS developer so the type system never catch me, but the Rust one attract me a lot.

In particolar the enumeration system captured my attention: it is very interesting and works differently from other languages.

The enums

An enumeration is commonly defined as set of predefined items called variants. In a lot of languages the enumerations are represented as an integer: the first item is identified by 0, the second with 1 and so on…

// C example
enum Direction {
    UP, // = 0
    LEFT, // = 1
    RIGTH, // = 2
    DOWN// = 3
};

In Rust you can specify as well a simple enumeration in the following way:

enum Direction {
    Up,
    Left,
    Rigth,
    Down,
};

The comments are removed because Rust abstracts it allowing us to refer to a variant only through its name, not using the index.

Another difference, actually the main one, is that Rust allows you to attach types to the variants. But not only that, you can attach different type to different variant of a enumeration.

This feature opens my mind to a new world.

Modelling your data type becomes much easier. But let’s try to make some examples.

struct GameState { /* ... */ }
struct GameOverReason { /* ... */ }

enum GameStatus {
    NotStarted,
    Playing(GameState),
    Paused(GameState),
    GameOver(GameOverReason)
};

let not_started = GameStatus::NotStarted;
let playing = GameStatus::Playing(GameState { /* ... */ } );
let paused = GameStatus::Paused(GameState { /* ... */ } );
let game_over = GameStatus::GameOver(GameOverReason { /* ... */ });

// The following line throws a compile error !!
let not_possible = GameStatus::GameOver(GameState{ /* ... */ });

In the example above, the GameStatus is enumeration that holds different types based on which variant the variable assumed.

Use enums in DDD

As previously said, an enum describes an exclusive or condition on own variants: an enum instance cannot identify 2 different variants at the same time.

This property, combined with the capability to hold data, allows your code to be more clear avoiding impossible states.

Let’s make some examples

A ticket system

We want to build a ticketing system to support the customer care: a client want to know why something went wrong with a product. For that, the customer creates the ticket inserting some data (texts, images and so on). Our business requires that the ticket is workable only if the customer care team accepts it. Otherwise the ticket is declined. At the end the customer closes the ticket.

In this situation, the application should consider:

• It is not possible to create ticket without the initial customer data
• After the open, only the customer care team can decide to accept or reject the ticket.
• If the ticket is accepted, the customer care has to reply with some data (texts, images, link to the documentation)

With those constraints, a possible solution could be the following one:

enum TicketState {
    Open,
    Taken,
    Declined,
    Closed,
}
struct CustomerInitialInformation { /* ... */ }
struct CustomerCareTakenInformation { /* ... */ }
struct DeclineReason { /* ... */ }
struct CloseInformation { /* ... */ }

struct Ticket {
    // Track the state of the ticket
    state: TicketState,
    // Track when the ticket is opened
    open_date: Date,
    // Hold the initial customer request
    customer_intial_information: CustomerInitialInformation,
    // Track when the ticket is taken by the customer care team
    taken_date: Option<Date>,
    // Hold the response from the customer care team
    customer_care_taken_information: Option<CustomerCareTakenInformation>,
    // Track when the ticket is declined
    declined_date: Option<Date>,
    // Hold the deline reason
    decline_reason: Option<DeclineReason>,
    // Track close date
    close_date: Option<Date>,
    // Hold the close information
    close_information: Option<CloseInformation>,
}

// But we can write something like:
let ticket1 = {
    taken_date: Some(Date::now()),
    customer_care_taken_information: None,
    // ...
};
let ticket2 = {
    close_date: Some(Date::now()),
    declined_date: Some(Date::now()),
    // ...
};

NB: In Rust there is not null. Option allows us to store the None value as null and Some to hold the not-null data.

Using the above structure, we could face up with some illegal states: what happen if we have the taken_date without customer_care_taken_information? And is a valid state if the close_date is set and also declined_date ? Our structure allows illegal states.

How can we improve this ? Using enums!

struct CustomerInitialInformation { /* ... */ }
struct CustomerCareTakenInformation { /* ... */ }
struct DeclineReason { /* ... */ }
struct CloseInformation { /* ... */ }

enum Ticket {
    Open(CustomerInitialInformation),
    Taken(CustomerInitialInformation, CustomerCareTakenInformation),
    Declined(CustomerInitialInformation, DeclineReason),
    Closed(CustomerInitialInformation, CustomerCareTakenInformation, CloseInformation),
}

In this way, the code doesn’t contain Option anymore. And illegal states are not possibile: your domain is safer.

A shopping cart

A common problem is the shopping cart.
Suppose an e-commerce needs to implement that feature with the following requirements:

• A customer creates a shopping cart only adding an item
• A customer adds or remores an item from the cart
• A customer finalizes the a not-empty cart paying it
• No change can be made after the payment

In this situation your application has to be designed to avoid inconsistent states.

A possible design can be the following one:

struct Item { /* ... */ }

enum ShoppingCartState {
    Empty,
    Full,
    Paid,
}
struct PaymentInformation { /* ... */ }

struct ShoppingCart {
    // Track the state of the cart
    state: ShoppingCartState,
    // Hold the items
    items: Vec<Item>,
    // Hold payment information
    payment_information: Option<PaymentInformation>,
}

// But we can write something like:
let cart1 = ShoppingCart {
    items: Vec::new(),
    payment_information: Some(PaymentInformation { /* ... */ }),
    // ...
};
let cart2 = ShoppingCart {
    state: ShoppingCartState::Full,
    payment_information: Some(PaymentInformation { /* ... */ }),
    // ...
};

In the above code, the data type doesn’t enforce inconsistent state: in fact who guarantee that the items array is not empty when the payment_information is fulfilled ? payment_information can be set also when the state is Full ? Again, we can do it better.

Let’s have a look instead to the following code:

struct Item { /* ... */ }

struct PaymentInformation { /* ... */ }
struct FullCart { items: Vec<Item> }
struct PaidCart {
    paid_items: Vec<Item>,
    payment_information: PaymentInformation,
}

enum ShoppingCart {
    Empty,
    Full(FullCart),
    Paid(PaidCart),
}

Now we are not able to have a ShoppingCart in illegal state: our domain is safe, much better!

Conclusion

Rust has a strong type system. The capabilities of the enumerations are amazing allowing your application to consider only the valid state.

In the next article we will see how to translate safety your enumeration from one state to another one!

Did you tried it? Which is your experience on using enumerations?

In the past years the microservice architecture pattern has become more and more widespread. A lot of articles have been published telling the benefits that this architecture brings to the table. Today I would like to tell my story about this approach from the points of view of a developer and a business.

During this pandemic global issue, some colleagues had an idea to allow people to know which shop deliveries its good to consumers at home. From this idea born https://acasatua.app/: a website where users find shops and their information. This idea is simple and we wanted to make a POC as soon as possible because the users are in need of a tool like this right now.

Currently working for Mia Platform, we asking to our boss to use our product to design e build this project. So, after writing a mini-backlog, we structured the architecture using microservice pattern. Mia Platform suite helps us to make:

• a shop service is responsible for sending the customers a list of shops ordered by user distance;
• a CMS enable us to check which shop is published;
• a DevOps pipeline supports us to build and deploy what we need ;
• Logs & Monitoring;
• Kubernetes managements

First implementation

For the first implementation, we have built the shop service using Node.js and use MongoDB as database. Fortunately MongoDB supports geo-spatial queries natively so we are able to sort the shops by user distance easly. So the first implementation was based on this kind of query and written in Node.js.

Second implementation

On the first days the amount of registered shop on database was about 200. The days after we introduced other shops reaching 500, the most of them based on Milan. The first implementation has a limitation: every API request triggered a geo-spatial query to the database. To avoid that, I have used setInterval to fetch all shops from database and stored them into process memory. On every invocation, the web server made a copy of the array, calculated the user distance and sorted the array by that value. With this implementation the database is not stressed at all and we can use kubernetes Horizontal Pod Autoscaler for handling potentially spikes of traffic.

The problem

Anyway after some weeks, our database grew up reaching 2000 shops. So, in memory, our API calculated the distance and sorted an array of 2000 elements. From our dashboard we saw that the API performance dropped down reaching 400ms response time. After a debug session with clinicjs, I have realized that the problem wasn’t the distance calculation or the array sorting: the issue was rendering the JSON output.

Node.js webserver is a single thread process: using the event loop Node.js is able to handle multiple request. Anyway when your process does a CPU intensive task like object serialization, the event loop doesn’t loop fluently. For this reason Node.js doesn’t perform well on this kind of operation: to solve this kind of problem, we thought it could be interesting to experiment with other languages.

Because this project is for fun, I wanted to experiment with something new: Rust or Go. Keeping Node.js as base of my comparison, I wrote 3 little webserver that serving an array of 2000 elements serializing them as JSON:

• fastify: a Node.js web framework. Under the hood it use fast-json-stringify for json serialization.
• Go: a plain webserver with json.Marshall
• Actix web: a web framwork with serde for JSON serialization

Below a table that shows the result on my Mac (2,4 GHz Intel Core i5 quad-core 16 GB):
DISCLAIMER: I didn’t want to spend too much time on creating an extremely accurate benchmark suite, I just wanted a rough idea of the performance differences between languages for this specific use case, so don’t take this data too seriously

+-----------------------+--------------+
|  Framwork / language  |     Req/sec  |
+--------------------------------------+
|  Fastify (Node.js)    |       65     |
+--------------------------------------+
|  Go                   |     1400     |
+--------------------------------------+
|  Actix web (Rust)     |     1600     |
+-----------------------+--------------+

Third implementation

The third implementation was written in Rust in 3 days (3 night truly). The response time drop down to 80ms: not so bad.

Always just for fun, I wasn’t so happy: the code was not structured well and the code makes a lot of memory copy. In order to avoid that, I start to use Arc that allows you to copy a pointer instead of entire string.

Fourth implementation

So the fourth implementation use massively Arc in the code. The response time now is 15ms per request: this is a huge improvement!

What I have learnt

I’ve used Node.js for the first 2 implementation because I have experience with that language and I’m able to develop fast. Develop fast means reaching the user early. And reaching user early means has feedback. We use that feedback to see if the project makes sense for the end-user, which improvements the user want and which part is not so interested. For that reason choosing your favourite language helps you to get feedback as soon as possible. This is a big deal.

Anyway problems always came. When they came, you should be ready to handle it. The microservice pattern allows you to handle problems: in this case we have to change only the issued microservice without impact other pieces of project. For this project the issue was a performance one: the users was waiting for a long before seeing the results. This was a bad user experience.

Another hidden problem was the cost: Kubernetes has deployed 3 replicas for handling all incoming requests, with Rust only one. The four implementation uses less resource and spend less that the third one.

The performance issue is only an example: in general as a developer you will meet a lot of features or issues to implement. Depends on which impact those features/issues have, part of the software has to be rewritten entirely or partially. If your microservices are small, the cost of rewriting one or more services entirely may be sustainable.

Conclusion

When we talk about microservice we say a lot of things. In this article we have seen how that pattern helps us to reach the user as soon as possible with an example. When the problem arrives, you can choose to keep the same codebase (such as the first and the second implementations have the same same code base mostly) or change language completely (as the third implementation).

Anyway the business reaches the user early and the developers don’t create a lock-in on the technology used initially.

This is my story about microservice rework by replacement. Which one is yours? Tell me!

In microservice environment, the first gate we can thought to is the API access point. There, all your requests arrive. There, your security is important. There, your company should invest its attention for security enhancement. It is important.

The permission management

The first kind of security is user permission. But the permission management is hard. In the most of case, the tools that implement this kind of security are very complex and difficult to manage without some expertise. So, your company should make a choice: uses some commercial solution or builds the own one. But in every enterprise context, there’s need one. In this article, we’ll see how it could be implemented using nginx.

The simplest security enhancement could be implemented checking if the user is able to access to an endpoint. This is our goal in this article. In particular we’ll able to declare that a path can be called by a subset of our user base. To manage that requirement, let’s say we are tagging our users with some labels called groups: each user can have zero, one or more strings that represent the grants given to him.

So, our goal is to find a technical solution to implement, for instance, those restrictions:

• GET /service1: all users
• POST /service1: only logged users
• DELETE /service1: only admin users
• GET /service2: only the users that are admin and editor
• POST /service2: only the user that are admin or editor
• GET /service3: only the users that are either admin or editor but not both
• POST /service3: users that are admin but not editor
• all other APIs are forbidden for all users

In this article we’ll see how to build this simple access management using only nginx and a little custom application.

Group login expression

Before staring, we should translate the restriction requirements into a logic expressions: in this way, we’ll use the logic expression to checking the user grants.

• GET /service1: all users ⇔ true
• POST /service1: only logged users ⇔ logged
• DELETE /service1: only admin users ⇔ admin
• GET /service2: only the users that are admin and editor ⇔ admin && editor
• POST /service2: only the user that are admin or editor ⇔ admin || editor
• GET /service3: only the users that are either admin or editor but not both ⇔ (!admin && editor) || (admin && !editor)
• POST /service3: users that are admin but not editor ⇔ admin && !editor
• the other paths are forbidden for all users ⇔ false

NB: the logged group is a special group used to identify all logged users.

Now we have the requirements formatted in logic expression!

This is powerful. For each request, we should understand which user calls the backend resolving its session, fetches its groups and evaluates the logic expression associated to that path to know if he has the grant to make that request or not.

In the next chapter we’ll see which tools allow us to make those checks.

Set up

In my previous article Nginx for surviving in microservice era, we had seen how to setup docker, docker-compose and how we use them to simulate a production environment. If you don’t read it yet, please do it!

For our purpose, we need some files:

• my-server.conf nginx configuration file
• docker-compose.yml file

For our purpose, the following docker-compose.yml fits well

version: '3'

services:
  reverse-proxy:
    image: nginx
    ports:
      - "8888:80"
    volumes:
      - ./my-server.conf:/etc/nginx/conf.d/default.conf:ro
  be1:
    image: jmalloc/echo-server
    environment:
    - PORT=80
  be2:
    image: tutum/hello-world
  be3:
    image: breerly/hello-server
    environment:
    - HELLO_PORT=80
    - HELLO_RESPONSE_DELAY=1
  auth:
    image: allevo/nginx_cerbero
    environment:
    - MONGODB_URL=mongodb://mongo/auth
    - REDIS_URL=redis://redis
    - HTTP_PORT=80
    link:
    - mongo
    - redis

  mongo:
    image: mongo
  redis:
    image: redis

The first part of this file is the same of my previous post: three application backend and a reverse-proxy implemented by nginx. We added auth service that will be described in the follow chapters. mongo and redis services are used by auth service for storing the users and their sessions respectively.

We’ll study my-server.conf nginx configuration file in the next chapters too.

auth_request directive

We’ll use reverse-proxy service as entry point in our system. Before each request reaches the backend, the auth service is queried to ask if the current user is able to access to that backend.

To do that, nginx offers a simple directive called auth_request. That directive allows us to make a subrequest to another service to check if the incoming request could be performed. From documentation:

If the subrequest returns a 2xx response code, the access is allowed. If it returns 401 or 403, the access is denied with the corresponding error code. Any other response code returned by the subrequest is considered an error.

So the auth service interface is clear: nginx automatically blocks the incoming requests if the auth service return a non 2xx status code.

Our auth service implements this interface: it responses 204 No Content if the group logic expression returns true; 403 Forbidden otherwise.

Because we want to keep our permission configuration in a one place, we will store it in the nginx conf. So let’s start to write it!

map $request_method-$uri $groupExpression {
  default "0";

  "~^GET-/auth/" "true";
  "POST-/auth/login" "true";
  "POST-/auth/signup" "true";

  "GET-/service1" "true";
  "POST-/service1" "logged";
  "DELETE-/service1" "admin";
  "GET-/service2" "admin && editor";
  "POST-/service2" "admin || editor";
  "GET-/service3" "(!admin && editor) || (admin && !editor)";
  "POST-/service3" "admin && !editor";

}

map $uri $upstreamName {
  "~^/auth" auth;
  "~^/my-service1" service1;
  "~^/my-service2" service2;
  "~^/my-service3" service3;
}
server {
  listen 80;
  server_name localhost;
  default_type text/plain;

  location / { # A
    auth_request /auth; # 1
    
    proxy_pass http://$upstreamName; # 4
  }

  location = /auth { # B
    proxy_set_header 'group-expression' $groupExpression; # 2

    proxy_pass http://auth; # 3
  }
}

For each request, nginx check witch location block matches. It found the (A) block.

In that block the first thing defined there is the auth_request directive(1). Because of this directive, nginx makes another request before continuing with the incoming one. So, nginx “forwards” the request to /auth.

nginx looks for which block matches that path finding the location (B). In this block, nginx add a new header to the request called group-expression (2). The value of this header is calculated by the $groupExpression map. As you can see, the group logic expressions are defined there. Than, forwards the request to the auth service (3). This service resolves the group check and returns 204 or 403.

If auth responses 204, nginx continues with the incoming request. Finally, nginx proxies the incoming request to the backend evaluating $upstreamName map.

The tests

For our purpose some CURLs work fine.

First of all we need to register an user. In this example, auth exposes /signup API to insert the user in mongo database. In your context, this is made by your application.

curl http://localhost:8888/auth/signup -XPOST -d '{"username":"my_user","password":"my_password","groups":["admin", "editor"]}' -H'Content-type: application/json'

With this CURL, a new user is registered. Obviously during the user registration, the client should not declare him groups!

After the user registration, we need to log in.

curl http://localhost:8888/auth/login -XPOST -d '{"username":"my_user","password":"my_password"}' -H'Content-type: application/json' -vvvv

The output of this CURL is like this:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8888 (#0)
> POST /auth/login HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/7.54.0
> Accept: */*
> Content-type: application/json
> Content-Length: 47
>
* upload completely sent off: 47 out of 47 bytes
< HTTP/1.1 200 OK
< Server: nginx/1.13.8
< Date: Fri, 26 Jan 2018 21:39:28 GMT
< Content-Type: application/json
< Content-Length: 83
< Connection: keep-alive
< Set-Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW; Path=/
<
* Connection #0 to host localhost left intact
{"_id":"5a6b9f61af897500108d1dcc","username":"my_user","groups":["admin","editor"]}

As you can see, the backend sends a cookie. Please copy it: we’ll use it for the following CURLs.

Now we are ready to start our test!

Our user has the groups “admin” and “editor”. So, we expect that GET /service1 (true), POST /service1 (logged), DELETE /service1 (admin), GET /service2 (admin && editor), POST /service2 (admin || editor) work well.

In fact the following CURLs work fine!

curl http://localhost:8888/service1 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW'
curl http://localhost:8888/service1 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW' -X POST
curl http://localhost:8888/service1 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW' -X DELETE
curl http://localhost:8888/service2 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW'
curl http://localhost:8888/service2 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW' -X POST

Instead the “my_user” user has not grant to access to GET /service3 ((!admin && editor) || (admin && !editor)) and POST /service3 (admin && !editor).

curl http://localhost:8888/service3 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW'
curl http://localhost:8888/service3 -H 'Cookie: sid=Wn4E5hZjwcssv90eCOj00dsZUi3897tW' -X POST

Both of last CURLs return 403 Forbidden.

Conclusion

As you can see, using this approach, you configuration

Nginx for managing your API access was originally published in Mia-Platform on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the microservices ecosystem the network is the base upon you build your application. Managing it with the right tool could help you.

nginx is a great tool but, sometimes, its configuration can be tricky: the copy-paste approach is an evil friend making the refactoring not simple. In this article we will introduce some concepts to help you with your network configuration. We’ll make an overview how your network can be managed to dispatch the requests to the right backend.

Nginx is a great tool

From nginx website:

nginx [engine x] is an HTTP and reverse proxy server, a mail proxy server, and a generic TCP/UDP proxy server,

In other words: nginx receives all your requests and forwards them to the right backend. But why should we have to bring an application behind another network layer?

There’re lots of benefits. Only for making some examples:

• resolves SSL
• makes HTTP compression as gzip or deflate
• adds/removes headers
• is single entry point to dispatch requests to the right place
• hides your real application backend

nginx is a very good tool, but it has a lot of feature: we are going to cover a little piece of the whole its world to see how the growing complexity can be managed easier. So, let’s start from the beginning!

Set up

In this article we’ll use docker containers for our examples to keep the setup independent from the underlying operative system. In particular, docker-compose is very useful to simulate a production environment containing more than one application backends.

We are going to write two files: docker-compose.yml and my-server.conf. The former contains the docker compose services definition; the latter will be used to study and play with nginx configuration. For simplicity, keep those files in the same directory.

First of all, install docker and docker-compose. Then we create a new file docker-compose.yml with the following content:

version: '3'

services:
  reverse-proxy:
    image: nginx
    ports:
      - "8888:80"
    volumes:
      - ./my-server.conf:/etc/nginx/conf.d/default.conf:ro
  be1:
    image: jmalloc/echo-server
    environment:
    - PORT=80
  be2:
    image: tutum/hello-world
  be3:
    image: breerly/hello-server
    environment:
    - HELLO_PORT=80
    - HELLO_RESPONSE_DELAY=1

This file describes four services: a reverse proxy implemented by nginx and three application backends for simulating real backends. The reverse proxy configuration describe that we’ll use the 8888 port on localhost to make requests to it. We are mounting the volumes to change the nginx configuration easily.

The configuration for the application backends is not important: be1, be2, be3 services listen on 80 port. In this way we can “forget the ports” in nginx configuration during the service definitions because the 80 is the HTTP standard port.

Now we are ready to play with nginx configuration! First of all, our configuration is kept as simple as possible to add complexity little by little.

So, let’s start creating the simplest possible configuration: in this first iteration, nginx will always respond directly with “200 OK” to every request, without forwarding the request to an application backend.

Create another file in the same directory called my-server.conf with the following content:

server {
  listen 80;
  
  default_type text/plain;
  
  location / {
    return 200 'OK!';
  }
}

To use our configuration with nginx, we’ll use the following command in a terminal:

docker-compose up

Our configuration servers “OK!” at http://localhost:8888. In the terminal, the previous command has an output like:

reverse-proxy_1  | 172.21.0.1 - - [19/Dec/2017:22:41:10 +0000] "GET / HTTP/1.1" 200 3 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36" "-"

This output proves that the service called reverse-proxy numbered 1 has received and served the request returning 200 status code. Well done!

To stop docker compose, please send it a SIGINT signal using the ctrl+C.

All requests have the same response for all HTTP methods. This is not a big deal but is a good baseline to explore and to understand nginx better.

Your first proxy to an application backend

In the microservices era your application is made by one or more backends. For starting easier, we’ll consider only one service.

We simulate it using the docker image jmalloc/echo-server. In our docker compose we have already declared that the be1 uses that image for running.

So, let’s overwrite the previous nginx configuration with the following:

upstream service1 { server be1; }

server {
  listen 80;

  location /my-service1 {
    proxy_pass http://service1;
  }
}

This configuration tells to nginx that all requests that have /my-service1 as path prefix will be proxied to the upstream service1. For our purpose we can consider upstreams as aliases for the given hostname. Thanks to docker compose the be1 hostname is resolved pointing to the “jmalloc/echo-service” container.

So, CURLing http://localhost:8888/my-service1, the request reaches nginx that sees the path matches the location block and, though the service1 upstream, proxies it to the be1 “aka” jmalloc/echo-service image.

In the output in your terminal there’re lines like those:

be1_1 | 172.21.0.5:48330 | GET /my-service1
reverse-proxy_1 | 172.21.0.1 — — [28/Dec/2017:19:29:02 +0000] “GET /my-service1 HTTP/1.1” 200 538 “-” “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.84 Safari/537.36” “-”

As you can see, the request reached the be1 service numbered 1 through the reverse-proxy numbered 1.

Add a lot of services

Your webserver may be built using a lot of application backends. So, we suppose three application backends (be1, be2, be3). We are already defined them in our docker-compose-yml. nginx proxies the requests based on the first part of the url.

upstream service1 { server be1; }
upstream service2 { server be2; }
upstream service3 { server be3; }

server {
  listen 80;
  default_type text/plain;

  location /my-service1 {
    proxy_pass http://service1;
  }

  location /my-service2 {
    proxy_pass http://service2;
  }

  location /my-service3 {
    proxy_pass http://service3;
  }
}

In this configuration, we have described three locations to handle the three different urls, one for each application backend.

Now you can request http://localhost:8888/my-service1, http://localhost:8888/my-service2 and http://localhost:8888/my-service3 and retrieve right responses.

But… how can we manage a lot of microservices? Or how can we write the configuration better avoiding listing all locations?

Simplify the configuration

Our goal is to keep the network configuration as simple as possible and in only one place. In the previous configuration we have three location blocks with three different proxy_pass definitions. We can do better!

nginx defines some default variable like $uri, $request_method and so on. We can use them to map the request to the upstream name.

We are going to use map. From nginx documentation:

Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter.

The following configuration defines a map called $upstreamName. For each request, the map defines the $upstreamName variable using the url path mapping the incoming request url to upstream name.

upstream service1 { server be1; }
upstream service2 { server be2; }
upstream service3 { server be3; }

map $uri $upstreamName {
  "~^/my-service1" service1;
  "~^/my-service2" service2;
  "~^/my-service3" service3;
}

server {
  listen 80;
  server_name localhost;
  default_type text/plain;

  location / {
    proxy_pass http://$upstreamName;
  }
}

$upstreamName map is valorized according to the map:

• GET /my-service1: $upstreamName is set to service1
• DELETE /my-service2: $upstreamName is set to service2
• GET /my-service3/foo/bar: $upstreamName is set to service3
• GET /my-service15: $upstreamName is set to service1

When a request arrives, the nginx finds the right location, set the $upstreamName variable according to the regexes above and proxies the request to the right upstream.

Now we have only one place to write out configuration! With this configuration the output is the same.

We can complicate the $upstreamName definition using other predefined variables to send the requests to the right backend.

map $request_method-$uri $upstreamName {
  "~^(GET|POST|PUT|DELETE)-/my-service1" service1;
  "~^POST-/my-service2" service2;
  "~^(GET|DELETE)-/my-service3" service3;
}

The above example builds a map using the HTTP method and the request url.

• The GET, POST, PUT and DELETE requests that have the url path that starts with /myservice1 will be proxied to service1 aka be1.
• Only the POST requests that have the url path that starts with /my-service2 will be proxies to service2 aka be2.
• The GET and DELETE requests that have the url path that start with /myservice3 will be proxied to service3 aka be3

The following CULRs work well:

curl -X GET http://localhost:8888/my-service1
curl -X POST http://localhost:8888/my-service1
curl -X PUT http://localhost:8888/my-service1
curl -X DELETE http://localhost:8888/my-service1

curl -X POST http://localhost:8888/my-service2

curl -X GET http://localhost:8888/my-service3
curl -X DELETE http://localhost:8888/my-service3

Instead, the following ones don’t:

curl -X CUSTOM_METHOD http://localhost:8888/my-service1

curl -X GET http://localhost:8888/my-service2
curl -X PUT http://localhost:8888/my-service2
curl -X DELETE http://localhost:8888/my-service2

curl -X POST http://localhost:8888/my-service3
curl -X PUT http://localhost:8888/my-service3

curl -X GET http://localhost:8888/unknown-service

This last block of CURLs returns always 500 response code. It is not nice: another HTTP status can be used. The following chapter explains how the different status code can be managed.

Add HTTP server utilities

nginx allows us to define multiple servers in the same configuration file. Previously our server listens on 80 TCP port. Another way to create an HTTP server is to bind a unix socket. This allows us to speed the TCP connection up but with the drawback that the connections can be made only from localhost.

Let’s define a simple nginx server that responses always 404 Not found page.

server {
  listen unix:/var/run/not-found.sock;
  return 404;
}

We can use it to proxy all requests that not matching any map rules. Update the nginx configuration as following:

server {
  listen unix:/var/run/not-found.sock;
  return 404;
}

upstream not_found { server unix:/var/run/not-found.sock; }

upstream service1 { server be1; }
upstream service2 { server be2; }
upstream service3 { server be3; }

map $request_method-$uri $upstreamName {
  default not_found;

  "~^(GET|POST|PUT|DELETE)-/my-service1" service1;
  "~^POST-/my-service2" service2;
  "~^(GET|DELETE)-/my-service3" service3;
}

server {
  listen 80;
  server_name localhost;
  default_type text/plain;

  location / {
    proxy_pass http://$upstreamName;
  }
}

The above configuration defines the not_found upstream used as default value of $upstreamName map using the default keyword. If an incoming request doesn’t match any rules, the map will assign the default value not_found to $upstreamName variable.

TIP: the not_found server can be customized serving your HTML page.

With the previous configuration, a GET to /my-service2 path returns a 404 Not found. In REST the right status code is 405 Method not allowed. So, let’s add another server that responses always that status code and use it in the $upstreamName map definition:

server {
  listen unix:/var/run/not-found.sock;
  return 404;
}

server {
  listen unix:/var/run/not-allowed.sock;
  return 405;
}

upstream not_found { server unix:/var/run/not-found.sock; }
upstream not_allowed { server unix:/var/run/not-allowed.sock; }

upstream service1 { server be1; }
upstream service2 { server be2; }
upstream service3 { server be3; }

map $request_method-$uri $upstreamName {
  default not_found;
  "~^(GET|POST|PUT|DELETE)-/my-service1" service1;
  "~^\w+-/my-service1" not_allowed;
  "~^POST-/my-service2" service2;
  "~^\w+-/my-service2" not_allowed;
  "~^(GET|DELETE)-/my-service3" service3;
  "~^\w+-/my-service3" not_allowed;
}

server {
  listen 80;
  server_name localhost;
  default_type text/plain;

  location / {
    proxy_pass http://$upstreamName;
  }
}

The not_found and not_allowed upstreams are used for all not matching requests or for not allowed methods respectively.

Handle secreted API

Continuing with the map usage, we are able to manage the API secrets automatically.

As we have defined not-found and not-allowed servers, we can define an unauthorized HTTP server too.

server {
  listen unix:/var/run/unauthorized.sock;
  return 401;
}

The above server always responses 401 Unauthorized status code.

Assuming that our APIs are under authorization: a secret has to be provided to access to the backend. For instance, my-secret and another-secret are the only right value of the secret HTTP header to access the backend.

To check the secret correctness, we can build a map called $secretResolution defined as below:

map $http_secret $secretResolution {
  default n;
  "my-secret" y;
  "another-secret" y;
}

nginx defines the $http_* variables with the right HTTP header. In our case the $http_secret variable is valorized with the value of the “secret” HTTP header. For each request, $secretResolution is y if the request has the right value in the HTTP secret header, n otherwise.

We change the $upstreamName map to include the new $secretResolution variable. Adding the right upstreams, we are able to list our network dispatcher. Use the following configuration:

server {
  listen unix:/var/run/not-found.sock;
  return 404;
}
server {
  listen unix:/var/run/not-allowed.sock;
  return 405;
}
server {
  listen unix:/var/run/unauthorized.sock;
  return 401;
}
upstream not_found { server unix:/var/run/not-found.sock; }
upstream not_allowed { server unix:/var/run/not-allowed.sock; }
upstream unauthorized { server unix:/var/run/unauthorized.sock; }

upstream service1 { server be1; }
upstream service2 { server be2; }
upstream service3 { server be3; }

map $http_secret $secretResolution {
  default n;
  my-secret y;
  another-secret y;
}

map $secretResolution-$request_method-$uri $upstreamName {
  default not_found;
  "~^n" unauthorized;
  "~^y-(GET|POST|PUT|DELETE)-/my-service1" service1;
  "~^y-\w+-/my-service1" not_allowed;
  "~^y-POST-/my-service2" service2;
  "~^y-\w+-/my-service2" not_allowed;
  "~^y-(GET|DELETE)-/my-service3" service3;
  "~^y-\w+-/my-service3" not_allowed;
}

server {
  listen 80;
  server_name localhost;
  default_type text/plain;
  location / {
    proxy_pass http://$upstreamName;
  }
}

The $upstreamName map now includes the new $secretResolution variable too. Only if the secret, HTTP method and the first path of url match, the request is proxied to the right backend.

The following CURLs work well:

curl -X GET -H 'secret: my-secret' http://localhost:8888/my-service1
curl -X GET -H 'secret: another-secret' http://localhost:8888/my-service1
curl -X GET -H 'secret: my-secret' http://localhost:8888/my-service1/foo/bar

Instead the following ones return 401:

curl -X GET http://localhost:8888/my-service1
curl -X GET -H 'secret: ' http://localhost:8888/my-service1
curl -X GET -H 'secret: unknown-secret' http://localhost:8888/my-service1

Conclusion

nginx is a great tool. Writing nginx configuration is not easy. map is a good feature. Be wise!

If you liked this article, please clap it!

I will share other nginx tips, so stay tuned!

For more infos:

• http://nginx.org/en/docs/http/ngx_http_core_module.html
• http://nginx.org/en/docs/http/ngx_http_upstream_module.html
• http://nginx.org/en/docs/http/ngx_http_map_module.html

A special thanks go to Luciano Mammino for helping me to write this article better.