azure-functions-middlewares
Advanced tools
The most complete middleware solution for ⚡ Azure Functions.
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.
| 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
listen() at the end of cascade to return the function entrypoint.context.res to 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((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((context) => {
context.log('This will be executed at the last phase');
}, app.Phases.POST_PROCESSING);
app.use((context) => {
context.log('This will be executed at the first phase');
}, app.Phases.PRE_PROCESSING);
app.use((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, (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 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((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.
contextThe
contextargument avaiable 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.
The
contextargument is an object reference and added properties are avaiable 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);
});
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 organization @azure-functions-middlewares.
Authorization request header (RFC 6750).context variable 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.
AzureFunctionCascade classpreProcessingPipeline
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!' | null` | false |
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.
Help us spreading the word or consider making a donation.
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.
Licensed under the MIT License.
FAQs
The most complete middleware solution for ⚡ Azure Functions.
We found that azure-functions-middlewares demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.
