Public API

Version: 0.2.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: '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.

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

  • Event: 'socket' (socket): it's not emitted in case of an HTTP/2 incoming message.
  • Event: 'stream' (stream): in case of an HTTP/2 incoming message, a reference to the associated HTTP/2 Stream object is emitted.
  • 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

• Class: http2.IncomingMessage

  • has two subclasses for easier interface description: IncomingRequest and IncomingResponse
  • message.socket: it's not present in case of an HTTP/2 incoming message.
  • message.stream: in case of an HTTP/2 incoming message, it's a reference to the associated HTTP/2 Stream object.
  • 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.IncomingResponse (IncomingMessage)

  • Event: 'push' (promise): signals the intention of a server push. promise is an IncomingPromise. If there's no listener for this event, the server push is cancelled.

• 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.
  • promise.cancel(): cancels the promised server push.

API elements not yet implemented:

• Class: http2.Server

  • Event: 'checkContinue'
  • Event: 'connect'
  • Event: 'upgrade'
  • Event: 'clientError'
  • server.maxHeadersCount
  • server.setTimeout(msecs, callback)
  • server.timeout

• Class: http2.ServerResponse

  • Event: 'close'
  • response.writeContinue()
  • response.addTrailers(headers)

• http.request(options, callback): not implemented options:

  • auth
  • agent

• Class: http2.Agent

  • agent.maxSockets
  • agent.sockets
  • agent.requests

• Class: http2.ClientRequest

  • Event: 'connect'
  • Event: 'upgrade'
  • Event: 'continue'
  • request.abort()

• Class: http2.IncomingMessage

  • Event: 'close'
  • message.trailers