From dbd8a543a569a7e9406b30a5c07a0937469128c2 Mon Sep 17 00:00:00 2001 From: Asher Gomez Date: Tue, 16 Jan 2024 17:17:44 +1100 Subject: [PATCH] docs(http): complete documentation (#4209) --- http/cookie.ts | 5 +++ http/etag.ts | 29 ++++++++++++----- http/negotiation.ts | 1 + http/server.ts | 38 ++++++++++++----------- http/server_sent_event_stream.ts | 2 ++ http/status.ts | 3 ++ http/user_agent.ts | 53 +++++++++++++++++++++++--------- 7 files changed, 91 insertions(+), 40 deletions(-) diff --git a/http/cookie.ts b/http/cookie.ts index be049002375f..443322ee4ce8 100644 --- a/http/cookie.ts +++ b/http/cookie.ts @@ -5,6 +5,11 @@ import { assert } from "../assert/assert.ts"; +/** + * Represents an HTTP Cookie. + * + * @see {@link https://tools.ietf.org/html/rfc6265#section-4.1.1} + */ export interface Cookie { /** Name of the cookie. */ name: string; diff --git a/http/etag.ts b/http/etag.ts index cd3887a6115f..88644a7cec6c 100644 --- a/http/etag.ts +++ b/http/etag.ts @@ -1,35 +1,47 @@ // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. -/** Provides functions for dealing with and matching ETags, including +/** + * Provides functions for dealing with and matching ETags, including * {@linkcode calculate} to calculate an etag for a given entity, * {@linkcode ifMatch} for validating if an ETag matches against a `If-Match` * header and {@linkcode ifNoneMatch} for validating an Etag against an * `If-None-Match` header. * * See further information on the `ETag` header on - * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag). + * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag | MDN}. * * @module */ import { encodeBase64 as base64Encode } from "../encoding/base64.ts"; -/** Just the part of `Deno.FileInfo` that is required to calculate an `ETag`, - * so partial or user generated file information can be passed. */ +/** + * Just the part of {@linkcode Deno.FileInfo} that is required to calculate an `ETag`, + * so partial or user generated file information can be passed. + */ export interface FileInfo { + /** The last modification time of the file. This corresponds to the `mtime` + * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This + * may not be available on all platforms. */ mtime: Date | null; + /** The size of the file, in bytes. */ size: number; } -type Entity = string | Uint8Array | FileInfo; +/** Represents an entity that can be used for generating an ETag. */ +export type Entity = string | Uint8Array | FileInfo; const encoder = new TextEncoder(); const DEFAULT_ALGORITHM: AlgorithmIdentifier = "SHA-256"; +/** Options for {@linkcode calculate}. */ export interface ETagOptions { - /** A digest algorithm to use to calculate the etag. Defaults to - * `"FNV32A"`. */ + /** + * A digest algorithm to use to calculate the etag. + * + * @default {"FNV32A"} + */ algorithm?: AlgorithmIdentifier; /** Override the default behavior of calculating the `ETag`, either forcing @@ -77,7 +89,8 @@ async function calcFileInfo( } } -/** Calculate an ETag for an entity. When the entity is a specific set of data +/** + * Calculate an ETag for an entity. When the entity is a specific set of data * it will be fingerprinted as a "strong" tag, otherwise if it is just file * information, it will be calculated as a weak tag. * diff --git a/http/negotiation.ts b/http/negotiation.ts index 411cfe947d1e..f05e11c531c2 100644 --- a/http/negotiation.ts +++ b/http/negotiation.ts @@ -12,6 +12,7 @@ import { preferredEncodings } from "./_negotiation/encoding.ts"; import { preferredLanguages } from "./_negotiation/language.ts"; import { preferredMediaTypes } from "./_negotiation/media_type.ts"; +/** Loose copy of {@linkcode Request}. */ export type Request = { headers: { get(key: string): string | null; diff --git a/http/server.ts b/http/server.ts index 0d558d2abe64..9c8b747c6130 100644 --- a/http/server.ts +++ b/http/server.ts @@ -17,9 +17,9 @@ const INITIAL_ACCEPT_BACKOFF_DELAY = 5; const MAX_ACCEPT_BACKOFF_DELAY = 1000; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandlerInfo} instead. - * * Information about the connection a request arrived on. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandlerInfo} instead. */ export interface ConnInfo { /** The local address of the connection. */ @@ -29,14 +29,14 @@ export interface ConnInfo { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandler} instead. - * * A handler for HTTP requests. Consumes a request and connection information * 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 close the underlying connection. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandler} instead. */ export type Handler = ( request: Request, @@ -44,9 +44,9 @@ export type Handler = ( ) => Response | Promise; /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead. - * * Options for running an HTTP server. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead. */ export interface ServerInit extends Partial { /** The handler to invoke for individual HTTP requests. */ @@ -61,9 +61,9 @@ export interface ServerInit extends Partial { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. - * * Used to construct an HTTP server. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. */ export class Server { #port?: number; @@ -498,9 +498,9 @@ export class Server { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead. - * * Additional serve options. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead. */ export interface ServeInit extends Partial { /** An AbortSignal to close the server and all connections. */ @@ -514,9 +514,9 @@ export interface ServeInit extends Partial { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeOptions} instead. - * * Additional serve listener options. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeOptions} instead. */ export interface ServeListenerOptions { /** An AbortSignal to close the server and all connections. */ @@ -530,8 +530,6 @@ export interface ServeListenerOptions { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. - * * Constructs a server, accepts incoming connections on the given listener, and * handles requests on these connections with the given handler. * @@ -554,6 +552,8 @@ export interface ServeListenerOptions { * @param listener The listener to accept connections from. * @param handler The handler for individual HTTP requests. * @param options Optional serve options. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. */ export async function serveListener( listener: Deno.Listener, @@ -577,8 +577,6 @@ function hostnameForDisplay(hostname: string) { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. - * * Serves HTTP requests with the given handler. * * You can specify an object with a port and hostname option, which is the @@ -622,6 +620,8 @@ function hostnameForDisplay(hostname: string) { * * @param handler The handler for individual HTTP requests. * @param options The options. See `ServeInit` documentation for details. + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. */ export async function serve( handler: Handler, @@ -664,6 +664,8 @@ export async function serve( } /** + * Initialization parameters for {@linkcode serveTls}. + * * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeTlsOptions} instead. */ export interface ServeTlsInit extends ServeInit { @@ -681,8 +683,6 @@ export interface ServeTlsInit extends ServeInit { } /** - * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. - * * Serves HTTPS requests with the given handler. * * You must specify `key` or `keyFile` and `cert` or `certFile` options. @@ -740,6 +740,8 @@ export interface ServeTlsInit extends ServeInit { * @param handler The handler for individual HTTPS requests. * @param options The options. See `ServeTlsInit` documentation for details. * @returns + * + * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead. */ export async function serveTls( handler: Handler, diff --git a/http/server_sent_event_stream.ts b/http/server_sent_event_stream.ts index b7ed6a05db41..fcd4953e81e3 100644 --- a/http/server_sent_event_stream.ts +++ b/http/server_sent_event_stream.ts @@ -5,6 +5,8 @@ const NEWLINE_REGEXP = /\r\n|\r|\n/; const encoder = new TextEncoder(); /** + * Represents a message in the Server-Sent Event (SSE) protocol. + * * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields} */ export interface ServerSentEventMessage { diff --git a/http/status.ts b/http/status.ts index 807b2f72928a..dfe088e38904 100644 --- a/http/status.ts +++ b/http/status.ts @@ -162,6 +162,7 @@ export const STATUS_CODE = { NetworkAuthenticationRequired: 511, } as const; +/** An HTTP status code. */ export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE]; /** A record of all the status codes text. */ @@ -231,6 +232,7 @@ export const STATUS_TEXT = { [STATUS_CODE.VariantAlsoNegotiates]: "Variant Also Negotiates", } as const; +/** An HTTP status text. */ export type StatusText = typeof STATUS_TEXT[keyof typeof STATUS_TEXT]; /** An HTTP status that is a informational (1XX). */ @@ -311,6 +313,7 @@ export type ServerErrorStatus = /** An HTTP status that is an error (4XX and 5XX). */ export type ErrorStatus = ClientErrorStatus | ServerErrorStatus; +/** Returns whether the provided number is a valid HTTP status code. */ export function isStatus(status: number): status is StatusCode { return Object.values(STATUS_CODE).includes(status as StatusCode); } diff --git a/http/user_agent.ts b/http/user_agent.ts index 78fa7418bbcb..56764d3155f3 100644 --- a/http/user_agent.ts +++ b/http/user_agent.ts @@ -71,19 +71,21 @@ interface Matchers { os: MatchingTuple[]; } +/** The browser as described by a user agent string. */ export interface Browser { - /** The major version of a browser as represented by a user agent string. */ + /** The major version of a browser. */ readonly major: string | undefined; - /** The name of a browser as represented by a user agent string. */ + /** The name of a browser. */ readonly name: string | undefined; - /** The version of a browser as represented by a user agent string. */ + /** The version of a browser. */ readonly version: string | undefined; } +/** The device as described by a user agent string. */ export interface Device { - /** The model of a device as represented by a user agent string. */ + /** The model of the device. */ readonly model: string | undefined; - /** The type of device as represented by a user agent string. */ + /** The type of device. */ readonly type: | "console" | "mobile" @@ -92,21 +94,29 @@ export interface Device { | "wearable" | "embedded" | undefined; - /** The vendor of a device as represented by a user agent string. */ + /** The vendor of the device. */ readonly vendor: string | undefined; } +/** The browser engine as described by a user agent string. */ export interface Engine { + /** The browser engine name. */ readonly name: string | undefined; + /** The browser engine version. */ readonly version: string | undefined; } +/** The OS as described by a user agent string. */ export interface Os { + /** The OS name. */ readonly name: string | undefined; + /** The OS version. */ readonly version: string | undefined; } +/** The CPU information as described by a user agent string. */ export interface Cpu { + /** The CPU architecture. */ readonly architecture: string | undefined; } @@ -968,7 +978,11 @@ const matchers: Matchers = { ], ], }; - +/** + * A representation of user agent string, which can be used to determine + * environmental information represented by the string. All properties are + * determined lazily. + */ export class UserAgent { #browser?: Browser; #cpu?: Cpu; @@ -977,10 +991,10 @@ export class UserAgent { #os?: Os; #ua: string; - /** A representation of user agent string, which can be used to determine - * environmental information represented by the string. All properties are - * determined lazily. + /** + * Constructs a new instance. * + * @example * ```ts * import { UserAgent } from "https://deno.land/std@$STD_VERSION/http/user_agent.ts"; * @@ -995,8 +1009,10 @@ export class UserAgent { this.#ua = ua ?? ""; } - /** The name and version of the browser extracted from the user agent - * string. */ + /** + * The name and version of the browser extracted from the user agent + * string. + */ get browser(): Browser { if (!this.#browser) { this.#browser = { name: undefined, version: undefined, major: undefined }; @@ -1018,8 +1034,10 @@ export class UserAgent { return this.#cpu; } - /** The model, type, and vendor of a device if present in a user agent - * string. */ + /** + * The model, type, and vendor of a device if present in a user agent + * string. + */ get device(): Device { if (!this.#device) { this.#device = { model: undefined, type: undefined, vendor: undefined }; @@ -1054,6 +1072,7 @@ export class UserAgent { return this.#ua; } + /** Converts the current instance to a JSON representation. */ toJSON(): { browser: Browser; cpu: Cpu; @@ -1066,10 +1085,12 @@ export class UserAgent { return { browser, cpu, device, engine, os, ua }; } + /** Converts the current instance to a string. */ toString(): string { return this.#ua; } + /** Custom output for {@linkcode Deno.inspect}. */ [Symbol.for("Deno.customInspect")]( inspect: (value: unknown) => string, ): string { @@ -1079,6 +1100,10 @@ export class UserAgent { }`; } + /** + * Custom output for Node's + * {@linkcode https://nodejs.org/api/util.html#utilinspectobject-options | util.inspect}. + */ [Symbol.for("nodejs.util.inspect.custom")]( depth: number, // deno-lint-ignore no-explicit-any