HTTP-сервер

Обработка HTTP-запросов, отправка ответов и управление поведением сервера.

Например, Deno.serveHttp, Deno.serve

функция Deno.serve

нестабильный

Перегрузка 1

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

Обрабатывает HTTP-запросы с помощью указанного обработчика.

В приведённом ниже примере сервер запускается на порту 8000 и имени узла "127.0.0.1".

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

Параметры

handler: ServeHandler<Deno.NetAddr>

Тип возвращаемого значения

HttpServer<Deno.NetAddr>

Перегрузка 2

serve(

options: ServeUnixOptions,

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров и обработчика.

Путь к сокету можно указать с помощью параметра path.

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

Сервер можно остановить с помощью AbortSignal. Сигнал отмены необходимо передать в наборе параметров в параметре signal. Сервер останавливается при отмене сигнала. Чтобы дождаться закрытия сервера, дождитесь выполнения промиса, возвращаемого API Deno.serve.

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();

По умолчанию Deno.serve выводит при запуске на прослушивание сообщение Listening on path/to/socket. Чтобы изменить это поведение, можно указать пользовательский callback onListen.

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"));

Параметры

options: ServeUnixOptions

handler: ServeHandler<Deno.UnixAddr>

Тип возвращаемого значения

HttpServer<Deno.UnixAddr>

Перегрузка 3

serve(

options: ServeVsockOptions,

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров и обработчика.

Параметры

options: ServeVsockOptions

handler: ServeHandler<Deno.VsockAddr>

Тип возвращаемого значения

HttpServer<Deno.VsockAddr>

Перегрузка 4

serve(

options: ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem),

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров и обработчика.

Можно указать объект с параметрами порта и имени узла — адресом, на котором сервер будет прослушивать подключения. По умолчанию используется порт 8000 и имя узла "0.0.0.0".

Адрес прослушивания можно изменить с помощью параметров hostname и port. В приведённом ниже примере сервер запускается на порту 3000 и имени узла "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();

По умолчанию Deno.serve выводит при запуске на прослушивание сообщение Listening on http://<hostname>:<port>/. Чтобы изменить это поведение, можно указать пользовательский callback onListen.

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

Чтобы включить TLS, необходимо указать параметры key и cert.

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"));

Параметры

options: ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyPem)

handler: ServeHandler<Deno.NetAddr>

Тип возвращаемого значения

HttpServer<Deno.NetAddr>

Перегрузка 5

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров.

Можно указать объект с параметром пути, который задаёт путь к доменному сокету Unix для прослушивания подключений.

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();

Параметры

options: ServeUnixOptions & ServeInit<Deno.UnixAddr>

Тип возвращаемого значения

HttpServer<Deno.UnixAddr>

Перегрузка 6

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров.

Семейство адресов VSOCK обеспечивает связь между виртуальными машинами и хостом, на котором они работают: https://man7.org/linux/man-pages/man7/vsock.7.html

Параметры

options: ServeVsockOptions & ServeInit<Deno.VsockAddr>

Тип возвращаемого значения

HttpServer<Deno.VsockAddr>

Перегрузка 7

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

Обрабатывает HTTP-запросы с помощью указанного набора параметров.

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();

Параметры

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

Тип возвращаемого значения

HttpServer<Deno.NetAddr>

интерфейс Deno.HttpServer

расширяет AsyncDisposable

Экземпляр сервера, созданный с помощью API Deno.serve().

Параметры типа

Addr extends Deno.Addr = Deno.Addr

Свойства

finished: Promise<void>

Промис, который выполняется после завершения работы сервера, например, при отмене с помощью сигнала, переданного в ServeOptions.signal.

addr: Addr

Локальный адрес, на котором сервер прослушивает подключения.

Методы

ref(): void

Запрещает циклу событий завершаться, пока работает сервер.

Примечание: по умолчанию сервер препятствует завершению цикла событий. Этот метод имеет смысл только после вызова .unref().

unref(): void

Позволяет циклу событий завершиться, не дожидаясь завершения работы сервера.

shutdown(): Promise<void>

Корректно закрывает сервер. Новые подключения больше не принимаются, а обработка уже принятых запросов завершается.

интерфейс Deno.ServeDefaultExport

Модуль, запускаемый с помощью подкоманды deno serve, должен соответствовать этому интерфейсу.

Чтобы обеспечить корректную проверку типов кода, добавьте satisfies Deno.ServeDefaultExport в export default { ... }, например:

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

Свойства

fetch: ServeHandler

Обработчик HTTP-запросов. Принимает запрос и возвращает ответ.

Если обработчик выбрасывает исключение, сервер, вызывающий его, предполагает, что ошибка затрагивает только отдельный запрос. Сервер перехватит ошибку и при необходимости закроет базовое соединение.

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

необязательный

Callback, вызываемый при запуске сервера на прослушивание.

интерфейс Deno.ServeHandlerInfo

Дополнительная информация об HTTP-запросе и его соединении.

Параметры типа

Addr extends Deno.Addr = Deno.Addr

Свойства

remoteAddr: Addr

Удалённый адрес соединения.

completed: Promise<void>

Промис, который завершается после полной обработки запроса и отправки ответа.

Он выполняется после того, как ответ (включая его тело) полностью доставлен клиенту. Промис отклоняется с ошибкой Deno.errors.Interrupted, если ответ не удалось отправить — например, когда клиент отключается до полной записи тела ответа. Если необходимо отслеживать такие ошибки, добавьте обработчик .catch() (или оберните await в try/catch).

интерфейс Deno.ServeInit

Параметры типа

Addr extends Deno.Addr = Deno.Addr

Свойства

handler: ServeHandler<Addr>

Обработчик, вызываемый для обработки каждого входящего запроса.

интерфейс Deno.ServeOptions

Параметры, которые можно задать при вызове Deno.serve.

Параметры типа

Addr extends Deno.Addr = Deno.Addr

Свойства

signal: AbortSignal

необязательный

AbortSignal для закрытия сервера и всех соединений.

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

необязательный

Обработчик, вызываемый при возникновении ошибки в обработчиках маршрутов.

onListen: (localAddr: Addr) => void

необязательный

Callback, вызываемый при запуске сервера на прослушивание.

automaticCompression: boolean = false

необязательный

Автоматически ли сжимать тела ответов, если клиент поддерживает соответствующий формат кодирования, а ответ можно сжать.

интерфейс Deno.ServeTcpOptions

расширяет ServeOptions<Deno.NetAddr>

Параметры, которые можно передать в Deno.serve для создания сервера, прослушивающего TCP-порт.

Свойства

transport: "tcp"

необязательный

Используемый транспорт.

port: number = 8000

необязательный

Порт для прослушивания подключений.

Укажите 0, чтобы прослушивать подключения на любом доступном порту.

hostname: string = "0.0.0.0"

необязательный

IP-адрес в буквальном виде или имя хоста, которое можно преобразовать в IP-адрес.

Примечание о 0.0.0.0 Прослушивание адреса 0.0.0.0 работает на всех платформах, однако браузеры в Windows не работают с адресом 0.0.0.0. Если ваша программа поддерживает Windows, следует показывать сообщение server running on localhost:8080 вместо server running on 0.0.0.0:8080.

reusePort: boolean

необязательный

Устанавливает SO_REUSEPORT в POSIX-системах.

tcpBacklog: number = 511

необязательный

Максимальное количество ожидающих подключений в очереди прослушивания.

Этот параметр определяет, сколько входящих подключений операционная система может поставить в очередь, пока приложение ожидает их принятия. Если при заполненной очереди поступают новые подключения, они будут отклонены.

Ядро может скорректировать это значение (например, округлить его до ближайшей большей степени двойки плюс 1). В разных операционных системах установлены разные максимальные пределы.

интерфейс Deno.ServeUnixOptions

расширяет ServeOptions<Deno.UnixAddr>

Параметры, которые можно передать в Deno.serve для создания сервера, прослушивающего доменный сокет Unix.

Свойства

transport: "unix"

необязательный

Используемый транспорт.

path: string

Путь к доменному сокету Unix для прослушивания подключений.

интерфейс Deno.ServeVsockOptions

расширяет ServeOptions<Deno.VsockAddr>

нестабильный

Параметры, которые можно передать в Deno.serve для создания сервера, прослушивающего сокет VSOCK.

Свойства

transport: "vsock"

необязательный

Используемый транспорт.

cid: number

Идентификатор контекста.

port: number

Используемый порт.

псевдоним типа Deno.ServeHandler

Обработчик HTTP-запросов. Принимает запрос и возвращает ответ.

Аргумент request — это стандартный Request веб-платформы, а обработчик должен возвращать стандартный Response веб-платформы (или промис, разрешающийся в него). Это те же классы Request и Response, доступные как глобальные объекты в Deno и браузерах, поэтому тело запроса, заголовки, URL и метод можно прочитать из входящего Request.

Если обработчик выбрасывает исключение, сервер, вызывающий его, предполагает, что последствия ошибки ограничены отдельным запросом. Он перехватит ошибку и при необходимости закроет нижележащее соединение.

Параметры типа

Addr extends Deno.Addr = Deno.Addr

Определение

(

request: Request,

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