From fb13967d1dd3aa7cc216b3f977a06d9718ae3678 Mon Sep 17 00:00:00 2001 From: Luca Casonato Date: Wed, 25 Nov 2020 15:09:22 +0100 Subject: [PATCH] docs: document the spec deviations in web apis (#8489) --- docs/runtime.md | 19 +----- docs/runtime/web_platform_apis.md | 97 +++++++++++++++++++++++++++++++ docs/toc.json | 1 + 3 files changed, 101 insertions(+), 16 deletions(-) create mode 100644 docs/runtime/web_platform_apis.md diff --git a/docs/runtime.md b/docs/runtime.md index 010884968e..6c64c4abf6 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -4,26 +4,13 @@ Documentation for all runtime functions (Web APIs + `Deno` global) can be found on [`doc.deno.land`](https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts). -## Web APIs +## Web Platform APIs For APIs where a web standard already exists, like `fetch` for HTTP requests, Deno uses these rather than inventing a new proprietary API. -The detailed documentation for implemented Web APIs can be found on -[doc.deno.land](https://doc.deno.land/https/raw.githubusercontent.com/denoland/deno/master/cli/dts/lib.deno.shared_globals.d.ts). -Additionally, a full list of the Web APIs which Deno implements is also -available -[in the repository](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/rt/README.md). - -The TypeScript definitions for the implemented web APIs can be found in the -[`lib.deno.shared_globals.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.shared_globals.d.ts) -and -[`lib.deno.window.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.window.d.ts) -files. - -Definitions that are specific to workers can be found in the -[`lib.deno.worker.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.worker.d.ts) -file. +For more details, view the chapter on +[Web Platform APIs](./runtime/web_platform_apis.md). ## `Deno` global diff --git a/docs/runtime/web_platform_apis.md b/docs/runtime/web_platform_apis.md new file mode 100644 index 0000000000..0a1015b68a --- /dev/null +++ b/docs/runtime/web_platform_apis.md @@ -0,0 +1,97 @@ +# Web Platform APIs + +Deno aims to use web platform APIs (like `fetch`) instead of inventing a new +proprietary API where it makes sense. These APIs generally follow the +specifications and should match the implementation in Chrome and Firefox. In +some cases it makes sense to deviate from the spec slightly, because of the +different security model Deno has. + +Here is a list of web platform APIs Deno implements: + +## `fetch` API + +### Overview + +The `fetch` API can be used to make HTTP requests. It is implemented as +specified in the [WHATWG `fetch` spec](https://fetch.spec.whatwg.org/). + +You can find documentation about this API on +[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). + +### Spec deviations + +- The Deno user agent does not have a cookie jar. As such, the `set-cookie` + header on a response is not processed, or filtered from the visible response + headers. +- Deno does not follow the same-origin policy, because the Deno user agent + currently does not have the concept of origins, and it does not have a cookie + jar. This means Deno does not need to protect against leaking authenticated + data cross origin. Because of this Deno does not implement the following + sections of the WHATWG `fetch` specification: + - Section `3.1. 'Origin' header`. + - Section `3.2. CORS protocol`. + - Section `3.5. CORB`. + - Section `3.6. 'Cross-Origin-Resource-Policy' header`. + - `Atomic HTTP redirect handling`. + - The `opaqueredirect` response type. +- A `fetch` with a `redirect` mode of `manual` will return a `basic` response + rather than an `opaqueredirect` response. + +## `CustomEvent`, `EventTarget` and `EventListener` + +### Overview + +The DOM Event API can be used to dispatch and listen to events happening in an +application. It is implemented as specified in the +[WHATWG DOM spec](https://dom.spec.whatwg.org/#events). + +You can find documentation about this API on +[MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget). + +### Spec deviations + +- Events do not bubble, because Deno does not have a DOM hierarchy, so there is + no tree for Events to bubble/capture through. + +## Web Worker API + +### Overview + +The WebWorker API can be used to executing code in a separate thread. It is +implemented as specified in the +[WHATWG HTML spec](https://html.spec.whatwg.org/multipage/workers.html#workers). + +You can find documentation about this API on +[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker). + +### Spec deviations + +- Currently creating workers from blob URLs is not supported. +- Currently posted data is serialized to JSON instead of structured cloning. +- Currently object ownership cannot be transferred between workers. + +## Other APIs + +- [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) +- [Console](https://developer.mozilla.org/en-US/docs/Web/API/Console) +- [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) +- [Performance](https://developer.mozilla.org/en-US/docs/Web/API/Performance) +- [setTimeout, setInterval, clearInterval](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout) +- [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) +- [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) +- [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) +- [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) + +--- + +## Typings + +The TypeScript definitions for the implemented web APIs can be found in the +[`lib.deno.shared_globals.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.shared_globals.d.ts) +and +[`lib.deno.window.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.window.d.ts) +files. + +Definitions that are specific to workers can be found in the +[`lib.deno.worker.d.ts`](https://github.com/denoland/deno/blob/$CLI_VERSION/cli/dts/lib.deno.worker.d.ts) +file. diff --git a/docs/toc.json b/docs/toc.json index f255b3fa19..e462649a1f 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -22,6 +22,7 @@ "program_lifecycle": "Program lifecycle", "permission_apis": "Permission APIs", "compiler_apis": "Compiler APIs", + "web_platform_apis": "Web Platform APIs", "workers": "Workers" } },