
## TL;DR

- Use RFCs to create and refine technical proposals, this will improve not only your documentation but your decision making.
- Use ADRs to record a history of your technical decisions to improve the knowledge transfer in your team.
- It's recommended to implement templates to generate this documents: [Documented Software Decisions](https://github.com/emanuelcasco/document-software-decision-template).

## Introduction

Over a project life-cycle, **a great deal of time is spent in making decisions**, for example: how to design the solution to integrate a new service to our system, data migration from a legacy database, which third-party service use, and so on. The lack of a documentation process that follows the project growth can result in long-term problems, coming back your steps to recall why did you take a decision is usually a complicated task.

The passage of the time and the team rotation without documentation that enables the knowledge transfer results in the lost of lessons learned and valuable experiences. Citing the first lesson of History: **"Those who cannot remember the past are condemned to repeat it."**.

However, as I mentioned before this is a common problem in software development, therefore, there are a lot of possible solutions for it depending of your needs. In this post, I'm going to focus in two particular tools that have helped me in the past:

1. RFC to generate and iterate proposals.
1. ADR to record decisions.

## Request for Comments (RFC) to generate and iterate proposals

RFC usage is as old as the same Internet, or even more because [this tool was used to make decisions in the design of the WWW [World Wide Web](https://www.rfc-editor.org/rfc-index.html), besides, the use of this tool has increased over the last years guided by Open Source projects like [React](https://github.com/reactjs/rfcs) and [Rust](https://github.com/rust-lang/rfcs).

Basically, a RFC (Request for Comments) document **is a written technical proposal intended to encourage the iteration of a solution based on exhaustive analysis and peers feedback**. The objective is to come up the best possible solution for a problem and mitigate the risk of complications at the development, definitely, we are talking about **making better decisions**.

### Life-cycle

1. **Proposal**: Change proposal document is presented.
2. **Iteration**: The proposal is iterated based on feedback to find issues or improvements. At this moment, is possible that we find out the solution is inviable, in that case, the RFC should be marked as ""deprecated.
3. **Implementation**: When the proposal has matured enough then we can close the document and implement the solution.
4. **Maintaining**: Once implemented, the solution may require some modification, in that case you can either modify the original document or update set it as "deprecated" and reference it from a new RFC document with the change proposal.

👉 *It is not recommended to modify an already implemented RFC as doing it will reduce its value as "history".*

### Examples

- [Notion RFC](https://www.notion.so/RFC-Template-Title-8df1bd0d24b0440486fe133eecdf4a5e).
- [RFC Template | Emanuel Casco](https://github.com/emanuelcasco/document-software-decision-template/blob/main/rfc/template.md).

## Architectural Decision Records (ADRs) to record decisions

An Architectural Decision  is _software design related decision that could imply either functional as non-functional requirements and has a **significant** impact over our system architecture."*_

An Architectural Decision Records (ADR) is a document that **record an Architectural Decision**, with its context and consequences. Usually, an ADR is the last step of a full decision making process that included a RFC document creation, but this is not always true.

Some ADR benefits are:

- **Improve knowledge transfer** (onboardings or rotations), as the people joining the team can read the last team decision and infer how it works, and so on.
- **Improve alignment between members**. Unilateral decisions risk is mitigated as all impactful decisions are consensual.

### When to create an ADR?

To ask this question I like to make reference to the following post from Spotify Engineering blog:

As  Josef Blake from Spotify mention in [this post](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/): _"always you made a significant decision that impacts how engineers write software."_

What is a "significant decision" is something your team has to decide and depends on the context. There is no golden rule but it is more a construction based on your and your team experience. However, keep in mind the following topics:

- All RFC document must has an ADR.
- If your team take any "significant" in a meeting, it must be reflected in your ADRs.

Following links include RFC examples and tools:

- [ADR Tools | Nat Pryce](https://github.com/npryce/adr-tools).
- [ADR | GitHub](https://adr.github.io/).
- [ADR Examples | Joel Parker Henderson](https://github.com/npryce/adr-tools).
- [ADR Template | Emanuel Casco](https://github.com/emanuelcasco/document-software-decision-template/blob/main/adr/template.md).

## Last considerations

The adoption of these tools in your team could not be easy, documentation process are often a conflict point in the engineering teams. My first advice would be: be patient. **It is necessary, for this process to work, that your team get involved in it**.

### First Steps

- **KISS** (Keep It Stupid Simple), **it is important to keep the documentation methodology as simple as possible in order to succeed.**
- **The process must adapt your team, not the other way around**.
- **Take the first step.**. Once the tools and the platform your team is going to use to write the documents, it is a good idea to create the first documents as a reference for the rest of the team. You could even write a document recording that you decided to write documents using RFC and ADR.
- Also **is a good idea to create templates for your documents**, or an script to generate them. The [following link](https://github.com/emanuelcasco/document-software-decision-template) includes some documents templates.

### Graphic guide of when and how to document

![Diagram Flow to document](/assets/blog/document-with-rfc-and-adr/image01.png)

## Conclusions

That's all for now! Hopefully this post has been helpful to you, below you will find a list with useful resources in case you are interested in continuing reading about these topics:

- [Templates | Emanuel Casco](https://github.com/emanuelcasco/document-software-decision-template).
- [When should I write an ADR? | Spotify Engineering Blog](~https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-architecture-decision-record/~).
- [ADR Tools | Nat Pryce](https://github.com/npryce/adr-tools).
- [ADR | GitHub](https://adr.github.io/).
- [ADR Examples | Joel Parker Henderson](https://github.com/npryce/adr-tools).


Document your technical decisions using RFC and ADR


## Introduction

This article presents a **collection of good practices working with [Azure Functions](https://docs.microsoft.com/en-us/azure/azure-functions/) in Node.js**. Recommendations have been extracted and adapted from Azure documentation and personal experiences.

Although this post will focus on Node.js, good practices presented on it can be useful for any language.

This post was originally published on Medium, you can find it here: [Improve your Azure Functions with this best practices](https://medium.com/@emanuelcasco/improve-your-azure-functions-with-this-best-practices-da8fd0123318).

## TL;DR

- Avoid long running functions.
- Avoid cross-functions communication.
- Share and manage connections.
- Keep functions pure.
- Use an infrastructure orchestrator.
- Write defensive functions.
- Avoid code pollution.

## Avoid long running functions

A function can become large due many dependencies or heavy processing operations. This result in unexpected timeouts and unfinished procedures.
To prevent this, you can:

- Avoid large dependencies whenever possible.
- Refactor large functions into smaller pieces of code that work together and return responses fast.
- Respect the "single responsibility principle", each function should have a single responsibility over a single part of the functionality provided by the software.

![Refactor large functions into smaller pieces of code that work together and return responses fast.](/assets/blog/improve-your-azure-functions-with-this-best-practices/image01.png)

For example, imagine you have a HTTP trigger function. HTTP requests usually need a quick response, thus you can pass the HTTP trigger payload into a queue and process it with a queue trigger function

## Avoid cross-functions communication

Azure Functions are not built to manage communication between functions. **Prefer Azure Queue Storage for cross-function communication**. Queue storage gives you asynchronous message queueing for communication between functions.

![Prefer Azure Queue Storage for cross-function communication](/assets/blog/improve-your-azure-functions-with-this-best-practices/image02.png)

If you need build topologies with complex routing you can use [Service Bus](https://azure.microsoft.com/en-us/services/service-bus/) which helps you to deliver messages to multiple subscribers and filter them before processing. In the other hand, [Events Hubs](https://azure.microsoft.com/en-us/services/event-hubs/) are useful to support high volume communications.

## Share and manage connections

**Creating and destroying instances of a shareable object can hurt performance.** Here are some guidelines to follow when manage connections:

- Reuse client instances rather than creating new ones with each function invocation.
- Create a singleton client and reuse it for every function invocation.
- Maintain this singleton pure.

```js
// DO NOT ❌
// myFunction.js
const Redis = require('redis');
module.exports = function (ctx, input) {
   const redis = new Redis(config);
   ...
};

// DO ✅
// myFunction.js
const Redis = require('redis');
const redis = new Redis(config); // re-utiliced by Azure
module.exports = function (ctx, input) { ... };

// CONSIDER 👍
// redisWrapper.js
const Redis = require('redis');
let redis;​
const instanceService = config => redis || new Redis(config);
module.exports = config => instanceService(config);
// myFunction.js
const redis = require('redisWrapper');
module.exports = function (ctx, input) { ... };
```

If you want to know more, please visit [Manage connections in Azure Functions](https://docs.microsoft.com/en-us/azure/azure-functions/manage-connections).

## Keep functions pure

A pure function has two main characteristics:

- Is **stateless**, produces no side effects.
- Is **deterministic**, given the same input, will always return the same output.

**Azure Functions runs in stateless compute containers that are event-triggered**, ephemeral (may last for one invocation), and fully managed by the cloud provider. So it is not recommend storing state within the application itself. Associate any needed state information with your data and store it an external datastore like DocumentDB or Azure SQL.

## Use an infrastructure orchestrator

**Serverless still requires infrastructure management**. Managing serverless infrastructure requires discipline to ensure it can be effectively maintained.

To manage your infrastructure, and keep it documented, it is recommended to use an infrastructure orchestrator. Infrastructure as code is a way of managing your devices and servers. This is done through machine-readable definition files.
Basically, you write down how you want your infrastructure to look like and what code should be run on that infrastructure. A highly recommended tool is [Terraform](https://www.terraform.io/).

## Write defensive functions

**Assume your functions could throw an exception at any time**. They should be able to continue from a previous fail point in the next execution. If you are using a queue to communicate, consider a re-queue strategy in order to not lose information.

Azure will retry to process a failed function input when you pass an error with the `context.done` method. Retries number and time window between them are defined in your `host.js` file.

Also, you can implement a custom [exponential backoff strategy](https://en.wikipedia.org/wiki/Exponential_backoff) to re-queue your messages after an increasing range time. This is especially useful to dispel possible inconveniences caused by high traffic.

**Validate your inputs!** You can implement [Object Schema Validation](https://json-schema.org/understanding-json-schema/reference/object.html) in your functions before processing inputs. There are great tools out there but I recommend:

- [Joi](https://github.com/sideway/joi), the most widely adopted package for object schema validation. It has a great api and excellent documentation.
- [Ajv](https://ajv.js.org/).

Meet the **Meet the Dead Letter Queue (DLQ)**. Azure Service Bus stores messages in the queues until processed, but there are several reasons for such undelivered messages, like exceeding MaxDeliveryCount, exceeding TimeToLive, errors while processing subscription rules, etc.
What happens with undelivered messages? They are sent to an DLQ.

If you want to access the undelivered message from the Topic then, the syntax of reading the Dead Letter Queue will be:

`TopicName/Subscriptions/SubscriptionName/$DeadLetterQueue`

## Avoid code pollution

Serverless architectures biggest benefit is you can focus on implement your business logic. Problems begin when you have to **deal with common technical concerns outside your business logic**. For example: input parsing and validation, output serialization, error handling, and more.

All this necessary code ends up polluting your business logic, making it harder to read and maintain. [Azure Middleware Engine](https://www.npmjs.com/package/azure-middleware) helps developers to **divide the problem in smaller pieces**, isolating logic into “steps”, keeping your code clean, readable and easy to maintain.

If you are interested, I wrote a post about this tool, you can find it here: [Implement middleware pattern in Azure Functions](/en/blog/azure-functions-middlewares).

Example:

```js
const ChainedFunction = new MiddlewareHandler()
  .use((context, input) => {
    asyncFunction(input).then((res) => {
      context.log.info('Im called first');
      context.next();
    });
  })
  .use((context) => {
    context.log.info('Im called second');
    context.done(null, { status: 200 });
  })
  .catch((err, context, input) => {
    context.log.error(`Something went wrong. Error: ${err}`);
    context.done(err, { status: 500 });
  });

module.exports = ChainedFunction.listen();
```

## Wrap up

So, we conclude here. This good practices helped me and my team improve productivity, code quality and functions performance. I hope them benefit you and your team also. Let me know if it were useful to you, and if not you can share your experience with us in the comments.

Useful links:

- [Azure Functions Middleware](https://www.npmjs.com/package/azure-middleware).


Improve your Azure Functions with this best practices


## Introduction

I wrote this post to share my experience implementing **middleware pattern** in [Azure Functions](https://azure.microsoft.com/en-us/services/functions/).

Biggest advantage of serverless computing is that you can focus on building apps and don’t worry about provisioning or maintaining servers. **You can write code only for what truly matters to your business**.

But in real world applications you have to deal with some common technical concerns outside business logic, like input parsing and validation, output serialization, error handling, and more. All this necessary code ends up polluting the pure business logic code in your functions, making the code harder to read and to maintain.

I published this post originally on Medium, you can find it here: [Implement middleware pattern in Azure Functions](https://javascript.plainenglish.io/implement-middleware-pattern-in-azure-functions-d8e9f94626a5).

## Implementation

Web frameworks, like Express, Fastify or Hapi, has solved this problem using the middleware pattern. This pattern allows developers to isolate these common technical concerns into "steps" that decorate the main business logic code.

After deciding to implement this pattern in my project, I made a small search to check if someone had already implemented a similar solution.
Unfortunately, the few solutions I found didn't meet my needs, so I decided to implement it myself.

**That’s is how Azure-Middleware was born.**

See more:

- [NPM: Azure Functions Middleware](https://www.npmjs.com/package/azure-middleware).
- [GitHub: Azure Functions Middleware](https://github.com/emanuelcasco/azure-middleware).

## How it works

### Validation

In serverless architectures is essential to be able to determine the correct behavior of each function as separate pieces of code. Therefore, in order to avoid unexpected behaviors, is important ensure that function inputs belong to its domain.

To accomplish this mission Azure-Middleware uses Joi. It allows us to define a schema and check if the input message is valid or not.
With the validate method you can define the scheme that will be used to validate the messages. If your function is called with an invalid message then an exception will be thrown and your function won’t be executed.

```js
module.exports = new MiddlewareHandler()
   .validate(invalidJoiSchema)
   .use(functionHandler)
   .catch(errorHandler)
   .listen();
```

### Function chaining

The `use` method is used to chain different function handlers, or middlewares, as "steps". It expect a function handler as argument.
Each middleware is executed sequentially in the order in which the function was defined. Information flow passes to the next element of the chain when calling `context.next`.

```js
module.exports = new MiddlewareHandler()
   .validate(schema)
   .use((ctx, msg) => {
      ctx.log.info('Print first');
      ctx.next();
   })
   .use((ctx, msg) => {
      ctx.log.info('Print second');
      ctx.done();
   })
   .catch(errorHandler)
   .listen();
```

`next` is a method injected into context. It is used to iterate the middlewares chain.

### Error handling

Error handling is very similar as it works in web frameworks like Express. When an exception is thrown, the first error handler into the middlewares chain will be executed. While all function handlers before will be ignored.

Also, you can jump to the next error handler using context.next. If this method receives a non-nil value as first argument, it will be handled as an error. Unlike the function handlers, the error handlers receive an error as the first argument.

```js
module.exports = new MiddlewareHandler()
   .use((ctx, msg) => {
      ctx.log.info('Hello world');
      ctx.next('ERROR!');
   })
   .use((ctx, msg) => {
      ctx.log.info('Not executed :(');
      ctx.next();
   })
   .catch((error, ctx, msg) => {
      ctx.log.info(errors); // ERROR!
      ctx.next();
   })
   .listen();
```

## Wrap up

The package is still in development and I have some ideas to improve it. However, if you have any suggestion, please don’t doubt in contact me and let me know about it!

Links:
- [Azure Functions Middleware](https://www.npmjs.com/package/azure-middleware).


Blog.