HTTP Server (Deno.serve)

Relevant source files

• ext/http/00_serve.ts
• ext/http/http_next.rs
• ext/http/lib.rs
• ext/http/response_body.rs
• ext/http/service.rs
• ext/web/stream_resource.rs
• tests/integration/serve_tests.rs
• tests/specs/serve/trust_proxy_headers/main.out
• tests/specs/serve/trust_proxy_headers/main.ts
• tests/testdata/serve/parallel.ts
• tests/unit/http_test.ts
• tests/unit/serve_test.ts

This document covers Deno's HTTP server implementation, primarily accessible via the Deno.serve() API. This system is a high-performance HTTP server built on the Hyper library, supporting HTTP/1.1 and HTTP/2 with automatic compression and WebSocket upgrade capabilities.

Architecture Overview

Deno's HTTP server bridges JavaScript APIs to Rust networking primitives through the deno_http extension. The implementation leverages hyper for protocol handling and deno_core for resource management.

Diagram: HTTP Server Architecture Layers

Sources: ext/http/lib.rs203-239 ext/http/http_next.rs1-120 ext/http/service.rs92-125 ext/http/00_serve.ts186-235

Server Lifecycle and Deno.serve

The modern Deno.serve API is implemented in 00_serve.ts. It utilizes op_http_serve to initialize the server state and op_http_wait to poll for incoming requests.

Server Initialization

When Deno.serve is called, it creates a listener (TCP or TLS) and sets up an HttpServerState. This state manages a pool of HttpRecord objects to minimize allocations.

Component	Description
HttpServerState	Holds the server's shared state, including the HttpRecord pool and active WebSockets.
HttpRecord	Represents a single HTTP request/response exchange.
ActiveWebSockets	A registry of upgraded WebSockets to ensure they are closed during server shutdown.

Sources: ext/http/service.rs92-125 ext/http/00_serve.ts511-700

Protocol Detection and Handling

Deno supports automatic protocol switching. It detects HTTP/2 via ALPN or by checking for the client connection preface.

Diagram: Connection Upgrade and Protocol Detection

The HTTP2_PREFIX is defined as b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n" ext/http/http_next.rs120 If a connection starts with this string, or if ALPN negotiates h2, the server uses the HTTP/2 stack.

Sources: ext/http/http_next.rs108-127 ext/http/http_next.rs815-900

HttpRecord Lifecycle

The HttpRecord is the central entity for request handling. It is exposed to JavaScript as an ExternalPointer.

1. Creation: An HttpRecord is taken from the HttpServerState pool or newly allocated ext/http/service.rs93-95
2. Request Dispatch: The request parts (method, URL, headers) are extracted and passed to the JS handler ext/http/http_next.rs262-366
3. Response Handling: The JS handler returns a Response. Ops like op_http_set_response_body_bytes update the HttpRecord ext/http/http_next.rs475-548
4. Completion/Recycling: Once the response is sent, HttpRecord::complete is called, and the record is returned to the pool ext/http/http_next.rs169-180

Request Information Extraction

JavaScript retrieves request data using the HttpRecord pointer:

• op_http_get_request_method_and_url: Returns method and URL as a V8 array ext/http/http_next.rs381-449
• op_http_get_request_headers: Fetches all headers ext/http/http_next.rs335-366

Sources: ext/http/http_next.rs132-180 ext/http/service.rs92-100 ext/http/00_serve.ts198-235

Response Generation and Compression

Deno supports automatic response compression (Gzip and Brotli) based on the Accept-Encoding header.

Response Body Variants

The ResponseBytesInner enum in ext/http/response_body.rs defines how the body is stored and processed:

Variant	Description
Bytes(BufView)	A static buffer, potentially pre-compressed.
UncompressedStream	A streaming body from a Deno resource.
GZipStream	A stream wrapped in a Gzip encoder.
BrotliStream	A stream wrapped in a Brotli encoder.

Sources: ext/http/response_body.rs103-117

Compression Logic

If automatic_compression is enabled in Options ext/http/lib.rs199 the server checks is_content_compressible ext/http/compressible.rs1-50

• Brotli: Uses brotli_compressor with quality level 6 ext/http/response_body.rs23-40
• Gzip: Uses flate2::write::GzEncoder ext/http/response_body.rs159-164

Sources: ext/http/response_body.rs78-117 ext/http/lib.rs198-200 ext/http/compressible.rs1-50

WebSocket Upgrades

Upgrading an HTTP connection to a WebSocket is handled by op_http_upgrade_websocket_next.

Diagram: WebSocket Upgrade Flow

The server tracks active WebSockets in ActiveWebSockets ext/http/service.rs115-125 During server shutdown, begin_shutdown is called to either gracefully (Close frame) or forcefully close all active sockets ext/http/service.rs163-191

Sources: ext/http/http_next.rs221-242 ext/http/service.rs115-191 ext/websocket/lib.rs58

Shutdown and Resource Cleanup

Deno provides two shutdown modes: abrupt (abort) and graceful.

• Graceful Shutdown: Triggered by server.shutdown(). It stops accepting new connections and waits for existing requests to finish.
• Abrupt Shutdown: Triggered by an AbortController signal. It cancels all in-progress HttpRecord operations.

The WebSocketGuard and SignallingRc are used to ensure the server stays alive as long as there are active requests or upgraded connections ext/http/service.rs207-214

Sources: ext/http/service.rs90-132 ext/http/00_serve.ts206-235 tests/unit/serve_test.ts167-226