From 9090023c33de7b64ae41425db71c9ab4d5b1237f Mon Sep 17 00:00:00 2001 From: Chris Knight Date: Tue, 26 May 2020 12:12:07 +0100 Subject: [PATCH] docs: "Getting started" manual updates (#5835) --- docs/getting_started.md | 2 + docs/getting_started/first_steps.md | 14 +++--- docs/getting_started/installation.md | 13 +++++- docs/getting_started/permissions.md | 46 +++++++++++++++++-- .../getting_started/setup_your_environment.md | 4 +- docs/getting_started/typescript.md | 15 ++++-- 6 files changed, 77 insertions(+), 17 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 159d3de648..7737f08d74 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -3,7 +3,9 @@ In this chapter we'll discuss: - Installing Deno +- Setting up your environment - Running a simple `Hello World` script - Writing our own script +- Understanding permissions - Using Deno with TypeScript - Using WebAssembly diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md index 4b3dd51086..9186af7302 100644 --- a/docs/getting_started/first_steps.md +++ b/docs/getting_started/first_steps.md @@ -14,7 +14,7 @@ before attempting to start with Deno. Deno is a runtime for JavaScript/TypeScript which tries to be web compatible and use modern features wherever possible. -Browser compatibility means, a simple `Hello World` program in Deno is the same +Browser compatibility means a simple `Hello World` program in Deno is the same as the one you can run in the browser: ```ts @@ -87,9 +87,9 @@ In this program each command-line argument is assumed to be a filename, the file is opened, and printed to stdout. ```ts -for (let i = 0; i < Deno.args.length; i++) { - let filename = Deno.args[i]; - let file = await Deno.open(filename); +const filenames = Deno.args; +for (const filename of filenames) { + const file = await Deno.open(filename); await Deno.copy(file, Deno.stdout); file.close(); } @@ -112,8 +112,10 @@ This is an example of a simple server which accepts connections on port 8080, and returns to the client anything it sends. ```ts -const listener = Deno.listen({ port: 8080 }); -console.log("listening on 0.0.0.0:8080"); +const hostname = "0.0.0.0"; +const port = 8080; +const listener = Deno.listen({ hostname, port }); +console.log(`Listening on ${hostname}:${port}`); for await (const conn of listener) { Deno.copy(conn, conn); } diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index 158e18133f..7d39e42516 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -59,11 +59,22 @@ Use `deno help` to see help text documenting Deno's flags and usage. Use ### Updating -To update a previously installed version of Deno, you can run `deno upgrade`. +To update a previously installed version of Deno, you can run: + +```shell +deno upgrade +``` + This will fetch the latest release from [github.com/denoland/deno/releases](https://github.com/denoland/deno/releases), unzip it, and replace your current executable with it. +You can also use this utility to install a specific version of Deno: + +```shell +deno upgrade --version 1.0.1 +``` + ### Building from source Information about how to build from source can be found in the `Contributing` diff --git a/docs/getting_started/permissions.md b/docs/getting_started/permissions.md index c5880225ac..317d850463 100644 --- a/docs/getting_started/permissions.md +++ b/docs/getting_started/permissions.md @@ -1,15 +1,50 @@ ## Permissions - +Deno is secure by default. Therefore, unless you specifically enable it, a deno +module has no file, network, or environment access for example. Access to +security sensitive areas or functions requires the use of permissions to be +granted to a deno process on the command line. - +For the following example, `mod.ts` has been granted read-only access to the +file system. It cannot write to it, or perform any other security sensitive +functions. + +```shell +deno run --allow-read mod.ts +``` + +### Permissions list + +The following permissions are available: + +- **-A, --allow-all** Allow all permissions. This disables all security. +- **--allow-env** Allow environment access for things like getting and setting + of environment variables. +- **--allow-hrtime** Allow high resolution time measurement. High resolution + time can be used in timing attacks and fingerprinting. +- **--allow-net=\** Allow network access. You can specify an + optional, comma separated list of domains to provide a whitelist of allowed + domains. +- **--allow-plugin** Allow loading plugins. Please note that --allow-plugin is + an unstable feature. +- **--allow-read=\** Allow file system read access. You can specify + an optional, comma separated list of directories or files to provide a + whitelist of allowed file system access. +- **--allow-run** Allow running subprocesses. Be aware that subprocesses are not + run in a sandbox and therefore do not have the same security restrictions as + the deno process. Therefore, use with caution. +- **--allow-write=\** Allow file system write access. You can + specify an optional, comma separated list of directories or files to provide a + whitelist of allowed file system access. ### Permissions whitelist -Deno also allows you to control the granularity of permissions with whitelists. +Deno also allows you to control the granularity of some permissions with +whitelists. This example restricts file system access by whitelisting only the `/usr` -directory: +directory, however the execution fails as the process was attempting to access a +file in the `/etc` directory: ```shell $ deno run --allow-read=/usr https://deno.land/std/examples/cat.ts /etc/passwd @@ -41,6 +76,9 @@ This is an example on how to whitelist hosts/urls: $ deno run --allow-net=github.com,deno.land fetch.ts ``` +If `fetch.ts` tries to establish network connections to any other domain, the +process will fail. + Allow net calls to any host/url: ```shell diff --git a/docs/getting_started/setup_your_environment.md b/docs/getting_started/setup_your_environment.md index a0d04b3850..70bcb58211 100644 --- a/docs/getting_started/setup_your_environment.md +++ b/docs/getting_started/setup_your_environment.md @@ -8,8 +8,8 @@ IDE of choice. There are several env vars that control how Deno behaves: -`DENO_DIR` defaults to `$HOME/.deno` but can be set to any path to control where -generated and cached source code is written and read to. +`DENO_DIR` defaults to `$HOME/.cache/deno` but can be set to any path to control +where generated and cached source code is written and read to. `NO_COLOR` will turn off color output if set. See https://no-color.org/. User code can test if `NO_COLOR` was set without having `--allow-env` by using the diff --git a/docs/getting_started/typescript.md b/docs/getting_started/typescript.md index 197c41482e..7689273db1 100644 --- a/docs/getting_started/typescript.md +++ b/docs/getting_started/typescript.md @@ -2,12 +2,19 @@ -### Using external type definitions - Deno supports both JavaScript and TypeScript as first class languages at runtime. This means it requires fully qualified module names, including the extension (or a server providing the correct media type). In addition, Deno has -no "magical" module resolution. +no "magical" module resolution. Instead, imported modules are specified as files +(including extensions) or fully qualified URL imports. Typescript modules can be +directly imported. E.g. + +``` +import { Response } from "https://deno.land/std@0.53.0/http/server.ts"; +import { queue } from "./collections.ts"; +``` + +### Using external type definitions The out of the box TypeScript compiler though relies on both extension-less modules and the Node.js module resolution logic to apply types to JavaScript @@ -98,7 +105,7 @@ way to support customization a configuration file such as `tsconfig.json` might be provided to Deno on program execution. You need to explicitly tell Deno where to look for this configuration by setting -the `-c` argument when executing your application. +the `-c` (or `--config`) argument when executing your application. ```shell deno run -c tsconfig.json mod.ts