Public API

Version: 1.0.1

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.Endpoint: an API for using the raw HTTP/2 framing layer. For documentation see the lib/protocol/endpoint.js file.

• Class: http2.Server

  • 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.

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

  • log: an optional bunyan logger object
  • plain: if true, the server will accept HTTP/2 connections over plain TCP instead of TLS

• Class: http2.ServerResponse

  • 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.

• Class: http2.Agent

  • new Agent(options): additional option:
    • log: an optional bunyan logger object
  • agent.sockets: only contains TCP sockets that corresponds to HTTP/1 requests.
  • agent.endpoints: contains Endpoint objects for HTTP/2 connections.

• http2.request(options, [callback]): additional option:

  • plain: if true, the client will not try to build a TLS tunnel, instead it will use the raw TCP stream for HTTP/2

• Class: http2.ClientRequest

  • 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.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
  • 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).

• 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
  • server.maxHeadersCount

API elements that are not applicable to HTTP/2

The reason may be deprecation of certain HTTP/1.1 features, or that some API elements simply don't make sense when using HTTP/2. These will not be present when a request is done with HTTP/2, but will function normally when falling back to using HTTP/1.1.

• Class: http2.Server

  • Event: 'checkContinue': not in the spec, yet (see http-spec#18)
  • Event: 'upgrade': upgrade is deprecated in HTTP/2
  • Event: 'timeout': HTTP/2 sockets won't timeout because of application level keepalive (PING frames)
  • Event: 'connect': not in the spec, yet (see http-spec#230)
  • server.setTimeout(msecs, [callback])
  • server.timeout

• Class: http2.ServerResponse

  • Event: 'close'
  • Event: 'timeout'
  • response.writeContinue()
  • response.writeHead(statusCode, [reasonPhrase], [headers]): reasonPhrase will always be ignored since it's not supported in HTTP/2
  • response.setTimeout(timeout, [callback])

• Class: http2.Agent

  • agent.maxSockets: only affects HTTP/1 connection pool. When using HTTP/2, there's always one connection per host.

• Class: http2.ClientRequest

  • Event: 'upgrade'
  • Event: 'connect'
  • Event: 'continue'
  • request.setTimeout(timeout, [callback])
  • request.setNoDelay([noDelay])
  • request.setSocketKeepAlive([enable], [initialDelay])

• Class: http2.IncomingMessage

  • Event: 'close'
  • message.setTimeout(timeout, [callback])