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.
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 |
$ npm install --save azure-functions-middlewares
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.resto output what you need. If you want to pass values to the next middlewares, use the context object reference.
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.
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_PROCESSINGconstant is equal to a"PRE_PROCESSING"string.
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');
});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_SIGNALconstant value are equal to a"!STOP!"string.
1️⃣ The
contextargument 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
contextargument 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().
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.
- @azure-functions-middlewares/jwt: Validates JWTs in
Authorizationrequest header (RFC 6750). - @azure-functions-middlewares/mongodb: Opens a MongoDB connection at the beggining of middleware cascade, makes it avaiable in any middleware at the
contextvariable and closes it at the end.
ℹ Middlewares officially developed by or reviwed by Azure Functions Middlewares maintainers are always under the
@azure-functions-middlewaresscope in NPM registry.
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.
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.
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
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
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).
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
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.
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.
- 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
- azure-monofunction: A router solution to Azure Functions using a single function and Azure Functions Middlewares.
Help us spreading the word or consider making a donation.
🙋♂️ Add your company to the used by section
Make a pull request or start an issue to add your company's name.
We follow Contributor Covenant Code of Conduct. If you want to contribute to this project, you must accept and follow it.
This project adheres to Semantic Versioning 2.0.0.
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
Licensed under the MIT License.
