HTTP Server

Handling HTTP requests, serving responses, and managing server behavior.

Eg Deno.serveHttp, Deno.serve

function Deno.serve

unstable

Overload 1

serve(handler: ServeHandler<Deno.NetAddr>): HttpServer<Deno.NetAddr>

Serves HTTP requests with the given handler.

The below example serves with the port 8000 on hostname "127.0.0.1".

Deno.serve((_req) => new Response("Hello, world"));

Parameters

handler: ServeHandler<Deno.NetAddr>

Return Type

HttpServer<Deno.NetAddr>

Overload 2

serve(

options: ServeUnixOptions,

handler: ServeHandler<Deno.UnixAddr>,
): HttpServer<Deno.UnixAddr>

Serves HTTP requests with the given option bag and handler.

You can specify the socket path with path option.

Deno.serve(
  { path: "path/to/socket" },
  (_req) => new Response("Hello, world")
);

You can stop the server with an AbortSignal. The abort signal needs to be passed as the signal option in the options bag. The server aborts when the abort signal is aborted. To wait for the server to close, await the promise returned from the Deno.serve API.

const ac = new AbortController();

const server = Deno.serve(
   { signal: ac.signal, path: "path/to/socket" },
   (_req) => new Response("Hello, world")
);
server.finished.then(() => console.log("Server closed"));

console.log("Closing server...");
ac.abort();

By default Deno.serve prints the message Listening on path/to/socket on listening. If you like to change this behavior, you can specify a custom onListen callback.

Deno.serve({
  onListen({ path }) {
    console.log(`Server started at ${path}`);
    // ... more info specific to your server ..
  },
  path: "path/to/socket",
}, (_req) => new Response("Hello, world"));

Parameters

options: ServeUnixOptions

handler: ServeHandler<Deno.UnixAddr>

Return Type

HttpServer<Deno.UnixAddr>

Overload 3

serve(

options: ServeVsockOptions,

handler: ServeHandler<Deno.VsockAddr>,
): HttpServer<Deno.VsockAddr>

Serves HTTP requests with the given option bag and handler.

Parameters

options: ServeVsockOptions

handler: ServeHandler<Deno.VsockAddr>

Return Type

HttpServer<Deno.VsockAddr>

Overload 4

serve(

options: ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem),

handler: ServeHandler<Deno.NetAddr>,
): HttpServer<Deno.NetAddr>

Serves HTTP requests with the given option bag and handler.

You can specify an object with a port and hostname option, which is the address to listen on. The default is port 8000 on hostname "0.0.0.0".

You can change the address to listen on using the hostname and port options. The below example serves on port 3000 and hostname "127.0.0.1".

Deno.serve(
  { port: 3000, hostname: "127.0.0.1" },
  (_req) => new Response("Hello, world")
);

const ac = new AbortController();

const server = Deno.serve(
   { signal: ac.signal },
   (_req) => new Response("Hello, world")
);
server.finished.then(() => console.log("Server closed"));

console.log("Closing server...");
ac.abort();

By default Deno.serve prints the message Listening on http://<hostname>:<port>/ on listening. If you like to change this behavior, you can specify a custom onListen callback.

Deno.serve({
  onListen({ port, hostname }) {
    console.log(`Server started at http://${hostname}:${port}`);
    // ... more info specific to your server ..
  },
}, (_req) => new Response("Hello, world"));

To enable TLS you must specify the key and cert options.

const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));

Parameters

options: ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem)

handler: ServeHandler<Deno.NetAddr>

Return Type

HttpServer<Deno.NetAddr>

Overload 5

serve(options: ServeUnixOptions & ServeInit<Deno.UnixAddr>): HttpServer<Deno.UnixAddr>

Serves HTTP requests with the given option bag.

You can specify an object with the path option, which is the unix domain socket to listen on.

const ac = new AbortController();

const server = Deno.serve({
  path: "path/to/socket",
  handler: (_req) => new Response("Hello, world"),
  signal: ac.signal,
  onListen({ path }) {
    console.log(`Server started at ${path}`);
  },
});
server.finished.then(() => console.log("Server closed"));

console.log("Closing server...");
ac.abort();

Parameters

options: ServeUnixOptions & ServeInit<Deno.UnixAddr>

Return Type

HttpServer<Deno.UnixAddr>

Overload 6

serve(options: ServeVsockOptions & ServeInit<Deno.VsockAddr>): HttpServer<Deno.VsockAddr>

Serves HTTP requests with the given option bag.

The VSOCK address family facilitates communication between virtual machines and the host they are running on: https://man7.org/linux/man-pages/man7/vsock.7.html

Parameters

options: ServeVsockOptions & ServeInit<Deno.VsockAddr>

Return Type

HttpServer<Deno.VsockAddr>

Overload 7

serve(options: (ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem)) & ServeInit<Deno.NetAddr>): HttpServer<Deno.NetAddr>

Serves HTTP requests with the given option bag.

You can specify an object with a port and hostname option, which is the address to listen on. The default is port 8000 on hostname "0.0.0.0".

const ac = new AbortController();

const server = Deno.serve({
  port: 3000,
  hostname: "127.0.0.1",
  handler: (_req) => new Response("Hello, world"),
  signal: ac.signal,
  onListen({ port, hostname }) {
    console.log(`Server started at http://${hostname}:${port}`);
  },
});
server.finished.then(() => console.log("Server closed"));

console.log("Closing server...");
ac.abort();

Parameters

options: (ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem)) & ServeInit<Deno.NetAddr>

Return Type

HttpServer<Deno.NetAddr>

interface Deno.HttpServer

extends AsyncDisposable

An instance of the server created using Deno.serve() API.

Type Parameters

Addr extends Deno.Addr = Deno.Addr

Properties

finished: Promise<void>

A promise that resolves once server finishes - eg. when aborted using the signal passed to ServeOptions.signal.

addr: Addr

The local address this server is listening on.

Methods

ref(): void

Make the server block the event loop from finishing.

Note: the server blocks the event loop from finishing by default. This method is only meaningful after .unref() is called.

unref(): void

Make the server not block the event loop from finishing.

shutdown(): Promise<void>

Gracefully close the server. No more new connections will be accepted, while pending requests will be allowed to finish.

interface Deno.ServeDefaultExport

Interface that module run with deno serve subcommand must conform to.

To ensure your code is type-checked properly, make sure to add satisfies Deno.ServeDefaultExport to the export default { ... } like so:

export default {
  fetch(req) {
    return new Response("Hello world");
  }
} satisfies Deno.ServeDefaultExport;

Properties

fetch: ServeHandler

A handler for HTTP requests. Consumes a request and returns a response.

If a handler throws, the server calling the handler will assume the impact of the error is isolated to the individual request. It will catch the error and if necessary will close the underlying connection.

onListen: (localAddr: Deno.Addr) => void

optional

The callback which is called when the server starts listening.

interface Deno.ServeHandlerInfo

Additional information for an HTTP request and its connection.

Type Parameters

Addr extends Deno.Addr = Deno.Addr

Properties

remoteAddr: Addr

The remote address of the connection.

completed: Promise<void>

A promise that settles when the request has been fully handled and the response has been sent.

It resolves once the response (including its body) has been completely delivered to the client. It rejects with a Deno.errors.Interrupted error if the response could not be sent successfully — for example when the client disconnects before the response body has been fully written. Attach a .catch() (or wrap an await in try/catch) if you need to observe these failures.

interface Deno.ServeInit

Type Parameters

Addr extends Deno.Addr = Deno.Addr

Properties

handler: ServeHandler<Addr>

The handler to invoke to process each incoming request.

interface Deno.ServeOptions

Options which can be set when calling Deno.serve.

Type Parameters

Addr extends Deno.Addr = Deno.Addr

Properties

signal: AbortSignal

optional

An AbortSignal to close the server and all connections.

onError: (error: unknown) => Response | Promise<Response>

optional

The handler to invoke when route handlers throw an error.

onListen: (localAddr: Addr) => void

optional

The callback which is called when the server starts listening.

automaticCompression: boolean = false

optional

Whether to automatically compress response bodies when the client accepts a supported encoding and the response is compressible.

interface Deno.ServeTcpOptions

extends ServeOptions<Deno.NetAddr>

Options that can be passed to Deno.serve to create a server listening on a TCP port.

Properties

transport: "tcp"

optional

The transport to use.

port: number = 8000

optional

The port to listen on.

Set to 0 to listen on any available port.

hostname: string = "0.0.0.0"

optional

A literal IP address or host name that can be resolved to an IP address.

Note about 0.0.0.0 While listening 0.0.0.0 works on all platforms, the browsers on Windows don't work with the address 0.0.0.0. You should show the message like server running on localhost:8080 instead of server running on 0.0.0.0:8080 if your program supports Windows.

reusePort: boolean

optional

Sets SO_REUSEPORT on POSIX systems.

tcpBacklog: number = 511

optional

Maximum number of pending connections in the listen queue.

This parameter controls how many incoming connections can be queued by the operating system while waiting for the application to accept them. If more connections arrive when the queue is full, they will be refused.

The kernel may adjust this value (e.g., rounding up to the next power of 2 plus 1). Different operating systems have different maximum limits.

interface Deno.ServeUnixOptions

extends ServeOptions<Deno.UnixAddr>

Options that can be passed to Deno.serve to create a server listening on a Unix domain socket.

Properties

transport: "unix"

optional

The transport to use.

path: string

The unix domain socket path to listen on.

interface Deno.ServeVsockOptions

extends ServeOptions<Deno.VsockAddr>

unstable

Options that can be passed to Deno.serve to create a server listening on a VSOCK socket.

Properties

transport: "vsock"

optional

The transport to use.

cid: number

The context identifier to use.

port: number

The port to use.

type alias Deno.ServeHandler

A handler for HTTP requests. Consumes a request and returns a response.

The request argument is a standard Web platform Request, and the handler must return a standard Web platform Response (or a promise resolving to one). These are the same Request and Response classes available as globals in Deno and in browsers, so the body, headers, URL, and method can all be read from the incoming Request.

Type Parameters

Addr extends Deno.Addr = Deno.Addr

Definition

(

request: Request,

info: ServeHandlerInfo<Addr>,
) => Response | Promise<Response>