servie

Servie provides standard, framework-agnostic HTTP interfaces for servers and clients.

Installation

npm install servie --save

Usage

• throwback Compose middleware functions into a single function
• servie-lambda Servie transport layer for AWS Lambda
• busboy A streaming parser for HTML form data
• qs and querystring Parse the HTTP query string to an object
• consolidate Template rendering
• get-body General body parser for forms, JSON and text
• servie-cors CORS middleware for Servie
• servie-route Routing middleware for Servie
• servie-mount Mount Servie middleware on a path prefix
• servie-compat-http Mimic node.js HTTP using Servie
• servie-redirect Create response objects for redirection
• servie-cookie-store API for managing client-side cookies

Common

Base HTTP class for common request and response logic.

import { Common } from 'servie'

Options

• headers? HTTP headers (Headers | HeadersObject | string[])
• trailers? HTTP trailers (Headers | HeadersObject | string[])
• events? An event emitter object (EventEmitter)
• body? Allowed HTTP bodies (string | Buffer | Readable | object)

Properties

• events An event emitter for listening to the request and response lifecycles
• headers The headers as a Headers instance
• trailers The trailers as a Headers instance
• body The request or response payload
• bodyUsed A boolean indicating whether the body has been read
• type A shorthand property for reading and writing the Content-Type header
• length A shorthand property for reading and writing Content-Length as a number
• started Boolean indicating if a request/response has started
• finished Boolean indicating if a request/response has finished
• bytesTransferred The number of bytes sent in the HTTP request/response

Methods

• buffer(maxBufferSize): Promise<Buffer> Read the body into a Buffer object
• text(maxBufferSize): Promise<string> Read the body as a string
• stream(): Readable Read the body as a Readable stream

Events

• headers Emitted when the headers object is available
• trailers Emitted when the trailers object is available
• started Emitted when started === true
• finished Emitted when finished === true
• progress Emitted when bytesTransferred is incremented

Request

HTTP class for encapsulating a Request, extends Common.

import { Request } from 'servie'

Options

const request = new Request({
  url: '/',
  method: 'GET'
})

Extends Common options.

• url The HTTP request url (string)
• method? The HTTP request method (string, default: GET)
• connection? Connection information ({ remoteAddress?: string, remotePort?: number, localAddress?: string, localPort?: number, encrypted?: boolean })

Properties

• url The HTTP request url (string)
• method The HTTP request method upper-cased (string)
• Url The HTTP request url as a read-only parsed object (object)
• connection Connection information ({})

Methods

• abort(): boolean Emit an abort event
• error(message, code, status?, original?): HttpError Create a HTTP error instance

Events

• abort Emitted when the request is aborted and MUST be handled by transport
• error Emitted when an out-of-band error occurs (e.g. abort) and MUST be handled by the transport
• response Emitted when the response object is being handled

Response

HTTP class for encapsulating a Response, extends Common.

import { Response } from 'servie'

Options

const response = new Response({})

Extends Common options.

• status? The HTTP response status code (number)
• statusText? The HTTP response status message (string)

Properties

• status? The HTTP response status code (number)
• statusText? The HTTP response status message (string)

Headers

Used by Common for Request and Response objects.

Options

Take a single parameter with the headers in object, array or Headers format.

Properties

• raw The raw HTTP headers list (string[])

Methods

• object(obj?: HeadersObject | null): HeadersObject | void A getter/setter method for reading the headers as a lower-cased object (like node.js)
• set(name: string, value: string | string[]): this Set a HTTP header by overriding case-insensitive headers of the same name
• append(name: string, value: string | string[]): this Append a HTTP header
• get(name: string): string | undefined Retrieve a case-insensitive HTTP header
• getAll(name: string): string[] Retrieve a list of matching case-insensitive HTTP headers
• has(name: string): boolean Check if a case-insensitive header is already set
• delete(name: string): this Delete a case-insensitive header

HttpError

Internally and externally triggered HTTP errors.

Properties

• code A unique error code (string)
• status A HTTP status code (number)
• request The Request instance that triggered the error (Request)
• message Standard error message (string)
• cause Specified when the HTTP error was triggered by an underlying error

Implementers

If you're building the transports for Servie, there are some life cycle events you need to be aware of and emit yourself:

1. Listen to the error event on Request for out-of-band errors and respond accordingly (e.g. app-level logging)
2. Listen to the abort event on Request to destroy the HTTP request
3. Emit the response event on Request when handling the response
4. Set started === true and finished === true on Request and Response, as appropriate
5. Set bytesTransferred on Request and Response when monitoring HTTP transfer progress

JavaScript

This module is designed for ES5 environments, but also requires Promise to be available.

TypeScript

This project is written using TypeScript and publishes the definitions directly to NPM.

License

Apache 2.0