mirror of
https://github.com/denoland/deno.git
synced 2025-03-03 09:31:22 -05:00
feat: Stabilize Deno.serve() API (#19141)
This commit stabilizes "Deno.serve()", which becomes the preferred way to create HTTP servers in Deno. Documentation was adjusted for each overload of "Deno.serve()" API and the API always binds to "127.0.0.1:8000" by default.
This commit is contained in:
Bartek Iwańczuk
GitHub
parent
7a7e0748e3
commit
3c8bbc434d
6 changed files with 202 additions and 297 deletions
|
|
@ -4788,7 +4788,7 @@ fn lsp_completions_auto_import() {
|
|||
"source": "./b.ts",
|
||||
"data": {
|
||||
"exportName": "foo",
|
||||
"exportMapKey": "foo|6768|file:///a/b",
|
||||
"exportMapKey": "foo|6799|file:///a/b",
|
||||
"moduleSpecifier": "./b.ts",
|
||||
"fileName": "file:///a/b.ts"
|
||||
},
|
||||
|
|
|
|||
|
|
@ -3077,16 +3077,16 @@ Deno.test(
|
|||
|
||||
assertEquals(
|
||||
"hello world!",
|
||||
await curlRequest(["https://localhost:9000/path", "-k"]),
|
||||
await curlRequest(["https://localhost:8000/path", "-k"]),
|
||||
);
|
||||
assertEquals(
|
||||
"hello world!",
|
||||
await curlRequest(["https://localhost:9000/path", "-k", "--http2"]),
|
||||
await curlRequest(["https://localhost:8000/path", "-k", "--http2"]),
|
||||
);
|
||||
assertEquals(
|
||||
"hello world!",
|
||||
await curlRequest([
|
||||
"https://localhost:9000/path",
|
||||
"https://localhost:8000/path",
|
||||
"-k",
|
||||
"--http2",
|
||||
"--http2-prior-knowledge",
|
||||
|
|
|
|||
|
|
@ -22,18 +22,12 @@ const UNSTABLE_DENO_PROPS: &[&str] = &[
|
|||
"UnixListenOptions",
|
||||
"connect",
|
||||
"createHttpClient",
|
||||
"kill",
|
||||
"listen",
|
||||
"listenDatagram",
|
||||
"dlopen",
|
||||
"removeSignalListener",
|
||||
"shutdown",
|
||||
"umask",
|
||||
"serve",
|
||||
"ServeInit",
|
||||
"ServeTlsInit",
|
||||
"Handler",
|
||||
"osUptime",
|
||||
];
|
||||
|
||||
static MSG_MISSING_PROPERTY_DENO: Lazy<Regex> =
|
||||
|
|
|
|||
197
cli/tsc/dts/lib.deno.ns.d.ts
vendored
197
cli/tsc/dts/lib.deno.ns.d.ts
vendored
|
|
@ -5668,4 +5668,201 @@ declare namespace Deno {
|
|||
* @category Runtime Environment
|
||||
*/
|
||||
export function gid(): number | null;
|
||||
|
||||
/** Information for a HTTP request.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeHandlerInfo {
|
||||
/** The remote address of the connection. */
|
||||
remoteAddr: Deno.NetAddr;
|
||||
}
|
||||
|
||||
/** 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.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export type ServeHandler = (
|
||||
request: Request,
|
||||
info: ServeHandlerInfo,
|
||||
) => Response | Promise<Response>;
|
||||
|
||||
/** Options which can be set when calling {@linkcode Deno.serve}.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeOptions {
|
||||
/** The port to listen on.
|
||||
*
|
||||
* @default {8000} */
|
||||
port?: number;
|
||||
|
||||
/** 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.
|
||||
*
|
||||
* @default {"0.0.0.0"} */
|
||||
hostname?: string;
|
||||
|
||||
/** An {@linkcode AbortSignal} to close the server and all connections. */
|
||||
signal?: AbortSignal;
|
||||
|
||||
/** Sets `SO_REUSEPORT` on POSIX systems. */
|
||||
reusePort?: boolean;
|
||||
|
||||
/** The handler to invoke when route handlers throw an error. */
|
||||
onError?: (error: unknown) => Response | Promise<Response>;
|
||||
|
||||
/** The callback which is called when the server starts listening. */
|
||||
onListen?: (params: { hostname: string; port: number }) => void;
|
||||
}
|
||||
|
||||
/** Additional options which are used when opening a TLS (HTTPS) server.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeTlsOptions extends ServeOptions {
|
||||
/** Server private key in PEM format */
|
||||
cert: string;
|
||||
|
||||
/** Cert chain in PEM format */
|
||||
key: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeInit {
|
||||
/** The handler to invoke to process each incoming request. */
|
||||
handler: ServeHandler;
|
||||
}
|
||||
|
||||
/** An instance of the server created using `Deno.serve()` API.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface Server {
|
||||
/** A promise that resolves once server finishes - eg. when aborted using
|
||||
* the signal passed to {@linkcode ServeOptions.signal}.
|
||||
*/
|
||||
finished: Promise<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.
|
||||
*/
|
||||
ref(): void;
|
||||
|
||||
/** Make the server not block the event loop from finishing. */
|
||||
unref(): void;
|
||||
}
|
||||
|
||||
/** Serves HTTP requests with the given handler.
|
||||
*
|
||||
* The below example serves with the port `8000` on hostname `"127.0.0.1"`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve((_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(handler: ServeHandler): Server;
|
||||
/** 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 `"127.0.0.1"`.
|
||||
*
|
||||
* You can change the address to listen on using the `hostname` and `port`
|
||||
* options. The below example serves on port `3000` and hostname `"0.0.0.0"`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve(
|
||||
* { port: 3000, hostname: "0.0.0.0" },
|
||||
* (_req) => new Response("Hello, world")
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* You can stop the server with an {@linkcode 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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"));
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(
|
||||
options: ServeOptions | ServeTlsOptions,
|
||||
handler: ServeHandler,
|
||||
): Server;
|
||||
/** 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 `"127.0.0.1"`.
|
||||
*
|
||||
* ```ts
|
||||
* const ac = new AbortController();
|
||||
*
|
||||
* const server = Deno.serve({
|
||||
* port: 3000,
|
||||
* hostname: "0.0.0.0",
|
||||
* 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();
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(
|
||||
options: ServeInit & (ServeOptions | ServeTlsOptions),
|
||||
): Server;
|
||||
}
|
||||
|
|
|
|||
286
cli/tsc/dts/lib.deno.unstable.d.ts
vendored
286
cli/tsc/dts/lib.deno.unstable.d.ts
vendored
|
|
@ -1250,292 +1250,6 @@ declare namespace Deno {
|
|||
*/
|
||||
export function funlockSync(rid: number): void;
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Information for a HTTP request.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeHandlerInfo {
|
||||
/** The remote address of the connection. */
|
||||
remoteAddr: Deno.NetAddr;
|
||||
}
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export type ServeHandler = (
|
||||
request: Request,
|
||||
info: ServeHandlerInfo,
|
||||
) => Response | Promise<Response>;
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Options which can be set when calling {@linkcode Deno.serve}.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeOptions extends Partial<Deno.ListenOptions> {
|
||||
/** An {@linkcode AbortSignal} to close the server and all connections. */
|
||||
signal?: AbortSignal;
|
||||
|
||||
/** Sets `SO_REUSEPORT` on POSIX systems. */
|
||||
reusePort?: boolean;
|
||||
|
||||
/** The handler to invoke when route handlers throw an error. */
|
||||
onError?: (error: unknown) => Response | Promise<Response>;
|
||||
|
||||
/** The callback which is called when the server starts listening. */
|
||||
onListen?: (params: { hostname: string; port: number }) => void;
|
||||
}
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Additional options which are used when opening a TLS (HTTPS) server.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeTlsOptions extends ServeOptions {
|
||||
/** Server private key in PEM format */
|
||||
cert: string;
|
||||
|
||||
/** Cert chain in PEM format */
|
||||
key: string;
|
||||
}
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface ServeInit {
|
||||
/** The handler to invoke to process each incoming request. */
|
||||
handler: ServeHandler;
|
||||
}
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export interface Server {
|
||||
/** A promise that resolves once server finishes - eg. when aborted using
|
||||
* the signal passed to {@linkcode ServeOptions.signal}.
|
||||
*/
|
||||
finished: Promise<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.
|
||||
*/
|
||||
ref(): void;
|
||||
|
||||
/** Make the server not block the event loop from finishing. */
|
||||
unref(): void;
|
||||
}
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Serves HTTP requests with the given handler.
|
||||
*
|
||||
* You can specify an object with a port and hostname option, which is the
|
||||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||||
*
|
||||
* The below example serves with the port `9000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve((_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can change the address to listen on using the `hostname` and `port`
|
||||
* options. The below example serves on port `3000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can stop the server with an {@linkcode 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({
|
||||
* onListen({ port, hostname }) {
|
||||
* console.log(`Server started at http://${hostname}:${port}`);
|
||||
* // ... more info specific to your server ..
|
||||
* },
|
||||
* handler: (_req) => new Response("Hello, world"),
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* To enable TLS you must specify the `key` and `cert` options.
|
||||
*
|
||||
* ```ts
|
||||
* 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"));
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(handler: ServeHandler): Server;
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Serves HTTP requests with the given handler.
|
||||
*
|
||||
* You can specify an object with a port and hostname option, which is the
|
||||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||||
*
|
||||
* The below example serves with the port `9000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve((_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can change the address to listen on using the `hostname` and `port`
|
||||
* options. The below example serves on port `3000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can stop the server with an {@linkcode 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({
|
||||
* onListen({ port, hostname }) {
|
||||
* console.log(`Server started at http://${hostname}:${port}`);
|
||||
* // ... more info specific to your server ..
|
||||
* },
|
||||
* handler: (_req) => new Response("Hello, world"),
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* To enable TLS you must specify the `key` and `cert` options.
|
||||
*
|
||||
* ```ts
|
||||
* 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"));
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(
|
||||
options: ServeOptions | ServeTlsOptions,
|
||||
handler: ServeHandler,
|
||||
): Server;
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Serves HTTP requests with the given handler.
|
||||
*
|
||||
* You can specify an object with a port and hostname option, which is the
|
||||
* address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
|
||||
*
|
||||
* The below example serves with the port `9000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve((_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can change the address to listen on using the `hostname` and `port`
|
||||
* options. The below example serves on port `3000`.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
|
||||
* ```
|
||||
*
|
||||
* You can stop the server with an {@linkcode 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.
|
||||
*
|
||||
* ```ts
|
||||
* 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.
|
||||
*
|
||||
* ```ts
|
||||
* Deno.serve({
|
||||
* onListen({ port, hostname }) {
|
||||
* console.log(`Server started at http://${hostname}:${port}`);
|
||||
* // ... more info specific to your server ..
|
||||
* },
|
||||
* handler: (_req) => new Response("Hello, world"),
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* To enable TLS you must specify the `key` and `cert` options.
|
||||
*
|
||||
* ```ts
|
||||
* 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"));
|
||||
* ```
|
||||
*
|
||||
* @category HTTP Server
|
||||
*/
|
||||
export function serve(
|
||||
options: ServeInit & (ServeOptions | ServeTlsOptions),
|
||||
): Server;
|
||||
|
||||
/** **UNSTABLE**: New API, yet to be vetted.
|
||||
*
|
||||
* Allows "hijacking" the connection that the request is associated with. This
|
||||
|
|
|
|||
|
|
@ -623,7 +623,7 @@ function serve(arg1, arg2) {
|
|||
};
|
||||
const listenOpts = {
|
||||
hostname: options.hostname ?? "0.0.0.0",
|
||||
port: options.port ?? (wantsHttps ? 9000 : 8000),
|
||||
port: options.port ?? 8000,
|
||||
reusePort: options.reusePort ?? false,
|
||||
};
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue