The API tries to leverage as much of the web standards as is possible as well as tries to be simple and straight forward.

In order to accept requests, first you need to listen for a connection on a network port. To do this in Deno, you use Deno.listen():

If there is an issue with opening the network port, Deno.listen() will throw, so often in a server sense, you will want to wrap it in the try ... catch block in order to handle exceptions, like the port already being in use.

You can also listen for a TLS connection (e.g. HTTPS) using Deno.listenTls():

const server = Deno.listenTls({
  port: 8443,
  certFile: "localhost.crt",
  keyFile: "localhost.key",
  alpnProtocols: ["h2", "http/1.1"],
});

The certFile and keyFile options are required and point to the appropriate certificate and key files for the server. They are relative to the CWD for Deno. The alpnProtocols property is optional, but if you want to be able to support HTTP/2 on the server, you add the protocols here, as the protocol negotiation happens during the TLS negotiation with the client and server.

To use it as an async iterable we would do something like this:

const server = Deno.listen({ port: 8080 });
for await (const conn of server) {
  // ...handle the connection...
}

Every connection made would yielded up a Deno.Conn assigned to conn. Then further processing can be applied to the connection.

There is also the .accept() method on the listener which can be used:

Whether using the async iterator or the .accept() method, exceptions can be thrown and robust production code should handle these using try ... catch blocks. Especially when it comes to accepting TLS connections, there can be many conditions, like invalid or unknown certificates which can be surfaced on the listener and might need handling in the user code.

A listener also has a .close() method which can be used to close the listener.

Once a connection is accepted, you can use Deno.serveHttp() to handle HTTP requests and responses on the connection. Deno.serveHttp() returns a Deno.HttpConn. A Deno.HttpConn is like a Deno.Listener in that requests the connection receives from the client are asynchronously yielded up as a .

To deal with HTTP requests as async iterable it would look something like this:

const server = Deno.listen({ port: 8080 });
for await (const conn of server) {
  (async () => {
    const httpConn = Deno.serveHttp(conn);
      // ... handle requestEvent ...
    }
  })();
}

The Deno.HttpConn also has the method .nextRequest() which can be used to await the next request. It would look something like this:

const server = Deno.listen({ port: 8080 });
while (true) {
  try {
    const conn = await server.accept();
    (async () => {
      const httpConn = Deno.serveHttp(conn);
      while (true) {
        try {
          const requestEvent = await httpConn.nextRequest();
          // ... handle requestEvent ...
        } catch (err) {
          // the connection has finished
          break;
        }
      }
    })();
    // The listener has closed
    break;
  }
}

In the examples from this point on, we will focus on what would occur within an example handle() function and remove the listening and connection “boilerplate”.

HTTP requests and responses in Deno are essentially the inverse of web standard . The Deno HTTP Server API and the Fetch API leverage the and object classes. So if you are familiar with the Fetch API you just need to flip them around in your mind and now it is a server API.

As mentioned above, a Deno.HttpConn asynchronously yields up Deno.RequestEvents. These request events contain a .request property and a .respondWith() method.

The .request property is an instance of the Request class with the information about the request. For example, if we wanted to know what URL path was being requested, we would do something like this:

async function handle(conn: Deno.Conn) {
  const httpConn = Deno.serveHttp(conn);
  for await (const requestEvent of httpConn) {
    const url = new URL(requestEvent.request.url);
    console.log(`path: ${url.path}`);
  }
}

The .respondWith() method is how we complete a request. The method takes either a Response object or a Promise which resolves with a Response object. Responding with a basic “hello world” would look like this:

async function handle(conn: Deno.Conn) {
  const httpConn = Deno.serveHttp(conn);
  for await (const requestEvent of httpConn) {
    await requestEvent.respondWith(
      new Response("hello world", {
        status: 200,
      }),
    );
  }
}

Note that we awaited the .respondWith() method. It isn’t required, but in practice any errors in processing the response will cause the promise returned from the method to be rejected, like if the client disconnected before all the response could be sent. While there may not be anything your application needs to do, not handling the rejection will cause an “unhandled rejection” to occur which will terminate the Deno process, which isn’t so good for a server. In addition, you might want to await the promise returned in order to determine when to do any cleanup from for the request/response cycle.

The web standard Response object is pretty powerful, allowing easy creation of complex and rich responses to a client, and Deno strives to provide a Response object that as closely matches the web standard as possible, so if you are wondering how to send a particular response, checkout out the documentation for the web standard Response.

HTTP/2 support is effectively transparent within the Deno runtime. Typically HTTP/2 is negotiated between a client and a server during the TLS connection setup via . To enable this, you need to provide the protocols you want to support when you start listening via the alpnProtocols property. This will enable the negotiation to occur when the connection is made. For example:

Currently Deno does not support upgrading a plain-text HTTP/1.1 connection to an HTTP/2 cleartext connection via the header (see: #10275), so therefore HTTP/2 support is only available via a TLS/HTTPS connection.