Public API

Version: 0.3.0

The main governing power behind the http2 API design is that it should look very similar to the existing node.js HTTPS API (which is, in turn, almost identical to the HTTP API). The additional features of HTTP/2 are exposed as extensions to this API. Furthermore, node-http2 should fall back to using HTTP/1.1 if needed. Compatibility with undocumented or deprecated elements of the node.js HTTP/HTTPS API is a non-goal.

Additional and modified API elements:

• Class: http2.Server

  • Event: 'upgrade': upgrade is deprecated in HTTP/2 so it will never be emitted for HTTP/2 requests.
  • Event: 'connection' (socket, [endpoint]): there's a second argument if the negotiation of HTTP/2 was successful: the reference to the Endpoint object tied to the socket.
  • Event: 'timeout': only emitted for HTTP/1 responses.
  • server.setTimeout(msecs, callback): only affects HTTP/1 connections.
  • server.timeout: only affects HTTP/1 connections.

• http2.createServer(options, [requestListener]): additional option:

  • log: an optional bunyan logger object

• Class: http2.ServerResponse

  • Event: 'close': only emitted for HTTP/1 responses.
  • Event: 'timeout': only emitted for HTTP/1 responses.
  • response.push(options): initiates a server push. options describes the 'imaginary' request to which the push stream is a response; the possible options are identical to the ones accepted by http2.request. Returns a ServerResponse object that can be used to send the response headers and content.
  • response.writeHead(statusCode, [reasonPhrase], [headers]): reasonPhrase will always be ignored since it's not supported in HTTP/2
  • response.setTimeout(timeout, [callback]): will be ignored for HTTP/2 requests

• Class: http2.Agent

  • new Agent(options): additional option:
    • log: an optional bunyan logger object
  • agent.maxSockets: only affects HTTP/1 connection pool. For HTTP/2, there's always one connection per host.
  • agent.sockets: only contains TCP sockets that corresponds to HTTP/1 requests.
  • agent.endpoints: contains Endpoint objects for HTTP/2 connections.

• Class: http2.ClientRequest

  • Event: 'upgrade': upgrade is deprecated in HTTP/2 so it will never be emitted for HTTP/2 requests.
  • Event: 'socket' (socket): in case of an HTTP/2 incoming message, socket is a reference to the associated HTTP/2 Stream object (and not to the TCP socket).
  • Event: 'push' (promise): signals the intention of a server push associated to this request. promise is an IncomingPromise. If there's no listener for this event, the server push is cancelled.
  • request.setTimeout(timeout, [callback]): will be ignored for HTTP/2 requests
  • request.setNoDelay([noDelay]): will be ignored for HTTP/2 requests
  • request.setSocketKeepAlive([enable], [initialDelay]): will be ignored for HTTP/2 requests
  • request.setPriority(priority): assign a priority to this request. priority is a number between 0 (highest priority) and 2^31-1 (lowest priority). Default value is 2^30.

• Class: http2.IncomingMessage

  • has two subclasses for easier interface description: IncomingRequest and IncomingResponse
  • Event: 'close': only emitted for HTTP/1 messages.
  • message.socket: in case of an HTTP/2 incoming message, it's a reference to the associated HTTP/2 Stream object (and not to the TCP socket).
  • message.setTimeout(timeout, [callback]): will be ignored for HTTP/2 requests

• Class: http2.IncomingRequest (IncomingMessage)

  • message.url: in case of an HTTP/2 incoming request, the url field always contains the path, and never a full url (it contains the path in most cases in the HTTPS api as well).
  • message.scheme: additional field. Mandatory HTTP/2 request metadata.
  • message.host: additional field. Mandatory HTTP/2 request metadata. Note that this replaces the old Host header field, but node-http2 will add Host to the message.headers for backwards compatibility.

• Class: http2.IncomingPromise (IncomingRequest)

  • contains the metadata of the 'imaginary' request to which the server push is an answer.
  • Event: 'response' (response): signals the arrival of the actual push stream. response is an IncomingResponse.
  • Event: 'push' (promise): signals the intention of a server push associated to this request. promise is an IncomingPromise. If there's no listener for this event, the server push is cancelled.
  • promise.cancel(): cancels the promised server push.
  • promise.setPriority(priority): assign a priority to this push stream. priority is a number between 0 (highest priority) and 2^31-1 (lowest priority). Default value is 2^30.

API elements not yet implemented:

• Class: http2.Server

  • Event: 'checkContinue'
  • Event: 'connect'
  • server.maxHeadersCount

• Class: http2.ServerResponse

  • response.writeContinue()
  • response.addTrailers(headers)

• Class: http2.ClientRequest

  • Event: 'connect'
  • Event: 'continue'

• Class: http2.IncomingMessage

  • message.trailers