Skip to content

Latest commit

 

History

History
605 lines (375 loc) · 18.6 KB

README.md

File metadata and controls

605 lines (375 loc) · 18.6 KB
Raw


Azure Functions Middlewares

The most complete middleware solution for ⚡ Azure Functions.

Azure Functions Middlewares is a full HTTP middleware cascade solution if you need to evolute your Azure Functions to composition and reusability, as you did before on APIs powered by Express, Koa or HAPI.

See all features.

Table of contents

Installation

Requirements

Azure Functions Middlewares was tested for the environments below. Even we believe it may works in older versions or other platforms, it is not intended to.

See tested environments
Environment Tested version
OS Ubuntu 20.04
Node.js 12.16.3
Package Manager npm 6.14.5
Platforms server, browser not supported

Installing

Via package manager

$ npm install --save azure-functions-middlewares

↟ Back to top

Usage

TL;DR

The most simple usage

const FunctionMiddlewares = require('azure-functions-middlewares');

const app = new FunctionMiddlewares();

app.use(async (context) => {

});

module.exports = app.listen();

⚠  Things you must pay attention

  • Always call listen() at the end of cascade to return the function entrypoint.
  • Always use async functions as middlewares. This project doesn't supports sync functions anymore, we are at 21th century.
  • Do not return anything inside your middleware function, unless you want to throw an error. Always use context.res to output what you need. If you want to pass values to the next middlewares, use the context object reference.

↟ Back to top

Capturing errors

If the middleware cascade encounters an error thrown by any middleware, it will stop the execution and will call the middleware registered with catch() method.

You can register a callback middleware to catch errors thrown in middleware cascade by passing a synchronous function with the arguments (context, error) , e.g.:

app.catch(async (context, error) => {
  context.res.status = 404;
  context.res.headers['X-Message'] = error;
});

If you don't register any catch middleware, a default function will be registered to log the error using context.error() and also to set a HTTP 500 status code.

↟ Back to top

Customizing the execution order

The middleware cascade is executed in three different phases: pre-execution, main execution and post-execution.

By default, all middlewares are pushed to the main execution phase, but you can customize the phase you are adding a middleware by passing a phase argument when registering a middleware using use() or useIf():

app.use(async (context) => {
  context.log('This will be executed at the last phase');
}, app.Phases.POST_PROCESSING);

app.use(async (context) => {
  context.log('This will be executed at the first phase');
}, app.Phases.PRE_PROCESSING);

app.use(async (context) => {
  context.log('This will be executed at the second phase');
});

Phases constants to use as phase argument are exposed into cascade's property Phases:

app.Phases.PRE_PROCESSING // => first phase
app.Phases.MAIN // => second phase
app.Phases.POST_PROCESSING // => last phase

ℹ These constant values are equal to its enums keys. So, the PRE_PROCESSING constant is equal to a "PRE_PROCESSING" string.

↟ Back to top

Conditional middlewares

You can conditionally using the method useIf() instead the traditional use() method.

To specify the evaluation function, pass to the first argument a synchronous function (context) => {} that always returns a boolean value.

Example:

const isPostRequest = (context) => context.req.method === 'POST';

app.useIf(isPostRequest, async (context) => {
  context.log('This will be executed only if is a HTTP POST');
});

↟ Back to top

Stoping the cascade execution

You can stop the cascade execution and prevent next middlewares to be executed in any following middleware, by returning the STOP_SIGNAL in the middleware.

It is useful when a middleware is used to validate the request before return any resource, just like Content-Type negotiation, authorization, etc.

The STOP_SIGNAL constant is avaiable as the second middleware's argument.

Example:

app.use(async (context, STOP_SIGNAL) => {
  if (!req.query.access_token) {
    context.res.status = 401;

    return STOP_SIGNAL;
  }
});

ℹ The STOP_SIGNAL constant value are equal to a "!STOP!" string.

↟ Back to top

Accessing and modifying the context

1️⃣  The context argument available in middlewares is the untouched reference to the Azure Function Context object.

This means you can access the request using context.req property, and also set the response using context.res property.

By default, context.res and context.res.headers are always initialized with empty objects {} to prevent attributions to undefined.

2️⃣  The context argument is an object reference and added properties are available through other references.

This means you can add your own custom properties to make them available to other middlewares.

For example, you could make an "User" property available to use user's information:

app.use(async (context) => {
  context.user = await database.getUser(context.req.query.userId);
});

app.use(async (context) => {
  context.res.body = await database.getOrdersByUser(context.user);
});

3️⃣  Azure Functions supports async functions and Azure Functions Middlewares handles everything needed in the function entrypoint generated by app.listen() method.

So, never call context.done().

↟ Back to top

Extending

Writing and publishing common middlewares

When we are talking about HTTP, some common middlewares is used by a lot of developers, just like authorization validation, content-type negotiation, parsing and output, and many more.

Azure Functions Middlewares doesn't have an API to extend it, because the middleware approach itself is extensible.

So, if you want to publish a middleware (or an evaluation function) you developed and think it will be useful for any other developer, fork this repository, add your middleware folder to the middlewares directory and make a pull request!

We will review it and publish it to the NPM scope @azure-functions-middlewares.

Avaiable community middlewares

ℹ Middlewares officially developed by or reviwed by Azure Functions Middlewares maintainers are always under the @azure-functions-middlewares scope in NPM registry.

↟ Back to top

Help

Support

If you need help or have a problem with this project, start an issue.

We will not provide a SLA to your issue, so, don't expect it to be answered in a short time.


↟ Back to top

API

AzureFunctionCascade class

Properties

preProcessingPipeline AsyncFunctionGenerator[]

Returns all the middlewares added to the 'PRE_PROCESSING' phase.

mainProcessingPipeline AsyncFunctionGenerator[]

Returns all the middlewares added to the 'MAIN' phase.

postProcessingPipeline AsyncFunctionGenerator[]

Returns all the middlewares added to the 'POST_PROCESSING' phase.

Methods

use()

function(asyncMiddleware, phase?):AzureFunctionCascade

Adds a middleware to the middleware cascade.

Arguments

Argument Type Required Default Description
asyncMiddleware AsyncFunctionGenerator true An asynchronous function that takes two arguments (context, STOP_SIGNAL)
phase `'PRE_PROCESSING' 'MAIN' 'POST_PROCESSING'` false

Returns

AzureFunctionCascade the current instance of AzureFunctionCascade.

Callbacks

asyncMiddleware

async function (context, STOP_SIGNAL?):any

Argument Type Required Default Description
context Context ℹ true The Azure Function context object.
STOP_SIGNAL '!STOP!' false undefined

Returns: anything returned by the middleware will be thrown as an error, except the STOP_SIGNAL constant.

useIf()

function(expression, asyncMiddleware, phase?):AzureFunctionCascade

Adds a conditional middleware to the middleware cascade.

Arguments

Argument Type Required Default Description
expression function true A function that takes a single argument (context) to check whether the middleware should be executed or not.
asyncMiddleware AsyncFunctionGenerator true Same as in use() method.
phase `'PRE_PROCESSING' 'MAIN' 'POST_PROCESSING'` false

Returns

AzureFunctionCascade the current instance of AzureFunctionCascade.

Callbacks

expression

function (context):boolean

Argument Type Required Default Description
context Context ℹ true The Azure Function context object.

Returns: the expression must always return a boolean indicating if the middleware should be executed (true) or not (false).

asyncMiddleware

Same as in use() method.

catch()

function(catchCallback):AzureFunctionCascade

Registers an error callback to be called when a middleware throws an error.

Arguments

Argument Type Required Default Description
catchCallback function true A callback function that takes one argument (context)

Returns

AzureFunctionCascade the current instance of AzureFunctionCascade.

Callbacks

catchCallback

async function (context, STOP_SIGNAL?):any

Argument Type Required Default Description
context Context ℹ true The Azure Function context object.

Returns: anything returned by the callback will be ignored.

listen()

function():AzureFunction

Returns the Azure Functions entrypoint async (context) => {} that will be triggered by the function HTTP trigger and will execute the entire middleware cascade.

Returns

AzureFunction: the Azure Functions entrypoint.

↟ Back to top

Tecnhical concepts

Azure Functions Middlewares was inspired from famous middleware cascades for Node.js, like Express, Koa and HAPI.

Our goal is to provide easy functions shareability and reusing to the entire Azure Functions ecosystem and community.

We knew some similar solutions at the time of our development, but they lack some crucial features, like async support, middleware stop signal and execution phases.

The design of AzureFunctionCascade class inside the project's core is really simple. It is almost just three arrays of pipeline phases that are iterated when the function entrypoint is called by the Functions Host.

Features

  • Async middleware support
  • Error event middleware (a.k.a. "catch middleware")
  • Execution order customization (pre-execution, main execution and post-execution phases)
  • Middleware execution prevention (a.k.a. "stop signal")
  • Conditional middlewares

Related projects

  • azure-monofunction: A router solution to Azure Functions using a single function and Azure Functions Middlewares.

Similar projects


↟ Back to top

Contributing

If you don't want to code

Help us spreading the word or consider making a donation.

⭐ Star the project

🐤 Tweet it

🙋‍♂️ Add your company to the used by section

Make a pull request or start an issue to add your company's name.

If you want to code

Code of conduct

We follow Contributor Covenant Code of Conduct. If you want to contribute to this project, you must accept and follow it.

SemVer

This project adheres to Semantic Versioning 2.0.0.

Roadmap

If you are not solving an issue or fixing a bug, you can help developing the roadmap below.

See the roadmap
  • Improve docs/FAQ
  • Support async functions also on conditional evaluators and catch callback
  • Create a "priority" score to manually sort middlewares

↟ Back to top

Hall of fame

Used in production by companies

↟ Back to top

License

Licensed under the MIT License.


↟ Back to top