README.md

Middy http-content-negotiation middleware

HTTP content negotiation middleware for the middy framework, the stylish Node.js middleware engine for AWS Lambda

This middleware parses Accept-* headers and provides utilities for HTTP content negotiation (charset, encoding, language and media type).

By default the middleware parses charsets (Accept-Charset), languages (Accept-Language), encodings (Accept-Encoding) and media types (Accept) during the before phase and expands the event object by adding the following properties:

• preferredCharsets (array) - The list of charsets that can be safely used by the app (as the result of the negotiation)
• preferredCharset (string) - The preferred charset (as the result of the negotiation)
• preferredEncodings (array) - The list of encodings that can be safely used by the app (as the result of the negotiation)
• preferredEncoding (string) - The preferred encoding (as the result of the negotiation)
• preferredLanguages (array) - The list of languages that can be safely used by the app (as the result of the negotiation)
• preferredLanguage (string) - The preferred language (as the result of the negotiation)
• preferredMediaTypes (array) - The list of media types that can be safely used by the app (as the result of the negotiation)
• preferredMediaType (string) - The preferred media types (as the result of the negotiation)

This middleware expects the headers in canonical format, so it should be attached after the httpHeaderNormalizer middleware. It also can throw an HTTP exception, so it can be convenient to use it in combination with the httpErrorHandler.

Install

To install this middleware you can use NPM:

npm install --save @middy/http-content-negotiation

Options

• parseCharsets (defaults to true) - Allows enabling/disabling the charsets parsing
• availableCharsets (defaults to undefined) - Allows defining the list of charsets supported by the Lambda function
• parseEncodings (defaults to true) - Allows enabling/disabling the encodings parsing
• availableEncodings (defaults to undefined) - Allows defining the list of encodings supported by the Lambda function
• parseLanguages (defaults to true) - Allows enabling/disabling the languages parsing
• availableLanguages (defaults to undefined) - Allows defining the list of languages supported by the Lambda function
• parseMediaTypes (defaults to true) - Allows enabling/disabling the media types parsing
• availableMediaTypes (defaults to undefined) - Allows defining the list of media types supported by the Lambda function
• failOnMismatch (defaults to true) - If set to true it will throw an HTTP NotAcceptable (406) exception when the negotiation fails for one of the headers (e.g. none of the languages requested are supported by the app)

Sample usage

import middy from '@middy/core'
import httpContentNegotiation from '@middy/http-content-negotiation'
import httpHeaderNormalizer from '@middy/http-header-normalizer'
import httpErrorHandler from '@middy/http-error-handler'

const handler = middy((event, context) => {
  let message, body

  switch (event.preferredLanguage) {
    case 'it-it':
      message = 'Ciao Mondo'
      break
    case 'fr-fr':
      message = 'Bonjour le monde'
      break
    default:
      message = 'Hello world'
  }

  switch (event.preferredMediaType) {
    case 'application/xml':
      body = `<message>${message}</message>`
      break
    case 'application/yaml':
      body = `---\nmessage: ${message}`
      break
    case 'application/json':
      body = JSON.stringify({ message })
      break
    default:
      body = message
  }

  return {
    statusCode: 200,
    body
  }
})

handler
  .use(httpHeaderNormalizer())
  .use(httpContentNegotiation({
    parseCharsets: false,
    parseEncodings: false,
    availableLanguages: ['it-it', 'fr-fr', 'en'],
    availableMediaTypes: ['application/xml', 'application/yaml', 'application/json', 'text/plain']
  }))
  .use(httpErrorHandler())

module.exports = { handler }

Middy documentation and examples

For more documentation and examples, refers to the main Middy monorepo on GitHub or Middy official website.

Contributing

Everyone is very welcome to contribute to this repository. Feel free to raise issues or to submit Pull Requests.

License

Licensed under MIT License. Copyright (c) 2017-2021 Luciano Mammino, will Farrell, and the Middy team.