From f3bde1d53b4710fb526286e27af29a55f5da18c7 Mon Sep 17 00:00:00 2001 From: Luca Casonato Date: Wed, 24 Aug 2022 14:10:57 +0200 Subject: feat(ext/flash): split upgradeHttp into two APIs (#15557) This commit splits `Deno.upgradeHttp` into two different APIs, because the same API is currently overloaded with two different functions. Flash requests upgrade immediately, with no need to return a `Response` object. Instead you have to manually write the response to the socket. Hyper requests only upgrade once a `Response` object has been sent. These two behaviours are now split into `Deno.upgradeHttp` and `Deno.upgradeHttpRaw`. The latter is flash only. The former only supports hyper requests at the moment, but can be updated to support flash in the future. Additionally this removes `void | Promise` as valid return types for the handler function. If one wants to use `Deno.upgradeHttpRaw`, they will have to type cast the handler signature - the signature is meant for the 99.99%, and should not be complicated for the 0.01% that use `Deno.upgradeHttpRaw()`. --- cli/dts/lib.deno.unstable.d.ts | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) (limited to 'cli/dts') diff --git a/cli/dts/lib.deno.unstable.d.ts b/cli/dts/lib.deno.unstable.d.ts index a1817deb0..2f6a197bc 100644 --- a/cli/dts/lib.deno.unstable.d.ts +++ b/cli/dts/lib.deno.unstable.d.ts @@ -1344,25 +1344,51 @@ declare namespace Deno { options: ServeInit & (ServeOptions | ServeTlsOptions), ): Promise; - /** **UNSTABLE**: new API, yet to be vetter. + /** **UNSTABLE**: new API, yet to be vetted. * - * Allows to "hijack" a connection that the request is associated with. - * Can be used to implement protocols that build on top of HTTP (eg. + * Allows "hijacking" the connection that the request is associated with. + * This can be used to implement protocols that build on top of HTTP (eg. * WebSockets). * - * The return type depends if `request` is coming from `Deno.serve()` API - * or `Deno.serveHttp()`; for former it returns the connection and first - * packet, for latter it returns a promise. - * * The returned promise returns underlying connection and first packet * received. The promise shouldn't be awaited before responding to the * `request`, otherwise event loop might deadlock. * + * ```ts + * function handler(req: Request): Response { + * Deno.upgradeHttp(req).then(([conn, firstPacket]) => { + * // ... + * }); + * return new Response(null, { status: 101 }); + * } + * ``` + * + * This method can only be called on requests originating the `Deno.serveHttp` + * server. + * * @category HTTP Server */ export function upgradeHttp( request: Request, - ): [Deno.Conn, Uint8Array] | Promise<[Deno.Conn, Uint8Array]>; + ): Promise<[Deno.Conn, Uint8Array]>; + + /** **UNSTABLE**: new API, yet to be vetted. + * + * Allows "hijacking" the connection that the request is associated with. + * This can be used to implement protocols that build on top of HTTP (eg. + * WebSockets). + + * Unlike `Deno.upgradeHttp` this function does not require that you respond + * to the request with a `Response` object. Instead this function returns + * the underlying connection and first packet received immediately, and then + * the caller is responsible for writing the response to the connection. + * + * This method can only be called on requests originating the `Deno.serve` + * server. + * + * @category HTTP Server + */ + export function upgradeHttpRaw(request: Request): [Deno.Conn, Uint8Array]; /** @category Sub Process */ export interface SpawnOptions { -- cgit v1.2.3