foster/deno
0
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2025-03-03 17:34:47 -05:00
Code Issues Packages 1 Wiki Activity

format

Browse source
This commit is contained in:
Bert Belder 2018-10-04 02:01:21 -07:00
parent 8ca082c508
commit b9cdf088e7
No known key found for this signature in database
GPG key ID: 7A77887B2E2ED461
4 changed files with 122 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
README.md
View file

@ -1,36 +1,32 @@
# deno # deno
| **Linux & Mac** | **Windows** | | **Linux & Mac** | **Windows** |
|:---------------:|:-----------:| | :------------------------: | :------------------------: |
| [![][tci badge]][tci link] | [![][avy badge]][avy link] | | [![][tci badge]][tci link] | [![][avy badge]][avy link] |
## A secure TypeScript runtime built on V8 ## A secure TypeScript runtime built on V8
* Supports TypeScript 3.0 out of the box. Uses V8 7.0. That is, it's - Supports TypeScript 3.0 out of the box. Uses V8 7.0. That is, it's very modern
very modern JavaScript. JavaScript.
* No `package.json`. No npm. Not explicitly compatible with Node. - No `package.json`. No npm. Not explicitly compatible with Node.
* Imports reference source code URLs only. - Imports reference source code URLs only.
``` `import { test } from "https://unpkg.com/deno_testing@0.0.5/testing.ts" import { log } from "./util.ts"`
import { test } from "https://unpkg.com/deno_testing@0.0.5/testing.ts"
import { log } from "./util.ts"
```
Remote code is fetched and cached on first execution, and never updated until Remote code is fetched and cached on first execution, and never updated until
the code is run with the `--reload` flag. (So, this will still work on an the code is run with the `--reload` flag. (So, this will still work on an
airplane. See `~/.deno/src` for details on the cache.) airplane. See `~/.deno/src` for details on the cache.)
* File system and network access can be controlled in order to run sandboxed - File system and network access can be controlled in order to run sandboxed
code. Defaults to read-only file system access and no network access. code. Defaults to read-only file system access and no network access. Access
Access between V8 (unprivileged) and Rust (privileged) is only done via between V8 (unprivileged) and Rust (privileged) is only done via serialized
serialized messages defined in this messages defined in this
[flatbuffer](https://github.com/denoland/deno/blob/master/src/msg.fbs). This makes it [flatbuffer](https://github.com/denoland/deno/blob/master/src/msg.fbs). This
easy to audit. makes it easy to audit. To enable write access explicitly use `--allow-write`
To enable write access explicitly use `--allow-write` and `--allow-net` for and `--allow-net` for network access.
network access.
- Single executable:
* Single executable:
``` ```
> ls -lh out/release/deno > ls -lh out/release/deno
-rwxr-xr-x 1 rld staff 48M Aug 2 13:24 out/release/deno -rwxr-xr-x 1 rld staff 48M Aug 2 13:24 out/release/deno
@ -43,11 +39,11 @@
> >
``` ```
* Always dies on uncaught errors. - Always dies on uncaught errors.
* [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471) - [Aims to support top-level `await`.](https://github.com/denoland/deno/issues/471)
* Aims to be browser compatible. - Aims to be browser compatible.
## Install ## Install
@ -63,16 +59,18 @@ curl -sSf https://raw.githubusercontent.com/denoland/deno_install/master/install
iex (iwr https://raw.githubusercontent.com/denoland/deno_install/master/install.ps1) iex (iwr https://raw.githubusercontent.com/denoland/deno_install/master/install.ps1)
``` ```
_Note: Depending on your security settings, you may have to run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` first to allow downloaded scripts to be executed._ _Note: Depending on your security settings, you may have to run
`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` first to allow downloaded
scripts to be executed._
Try it: Try it:
``` ```
> deno http://deno.land/thumb.ts > deno http://deno.land/thumb.ts
``` ```
See also [deno_install](https://github.com/denoland/deno_install). See also [deno_install](https://github.com/denoland/deno_install).
## Status ## Status
Under development. Under development.
@ -82,14 +80,13 @@ We make binary releases [here](https://github.com/denoland/deno/releases).
Progress towards future releases is tracked Progress towards future releases is tracked
[here](https://github.com/denoland/deno/milestones). [here](https://github.com/denoland/deno/milestones).
Roadmap is [here](https://github.com/denoland/deno/blob/master/Roadmap.md). Roadmap is [here](https://github.com/denoland/deno/blob/master/Roadmap.md). Also
Also see [this presentation](http://tinyclouds.org/jsconf2018.pdf). see [this presentation](http://tinyclouds.org/jsconf2018.pdf).
[Benchmarks](https://denoland.github.io/deno/) [Benchmarks](https://denoland.github.io/deno/)
[Chat room](https://gitter.im/denolife/Lobby). [Chat room](https://gitter.im/denolife/Lobby).
## Build instructions ## Build instructions
To ensure reproducible builds, Deno has most of its dependencies in a git To ensure reproducible builds, Deno has most of its dependencies in a git
@ -97,13 +94,17 @@ submodule. However, you need to install separately:
1. [Rust](https://www.rust-lang.org/en-US/install.html) 1. [Rust](https://www.rust-lang.org/en-US/install.html)
2. [Node](http://nodejs.org/) 2. [Node](http://nodejs.org/)
3. Python 2. [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578). 3. Python 2.
4. [ccache](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/ccache) (Optional but helpful for speeding up rebuilds of V8.). [Not 3](https://github.com/denoland/deno/issues/464#issuecomment-411795578).
4. [ccache](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/ccache)
(Optional but helpful for speeding up rebuilds of V8.).
5. Extra steps for Windows users: 5. Extra steps for Windows users:
1. Add `python.exe` to `PATH`. E.g. `set PATH=%PATH%;C:\Python27\python.exe` 1. Add `python.exe` to `PATH`. E.g. `set PATH=%PATH%;C:\Python27\python.exe`
2. Get [VS Community 2017](https://www.visualstudio.com/downloads/), make sure to select the option to install C++ tools and the Windows SDK 2. Get [VS Community 2017](https://www.visualstudio.com/downloads/), make
3. Enable `Debugging Tools for Windows`, Goto Control Panel -> Windows 10 SDK -> Right-Click -> Change -> Change -> Check Debugging Tools for Windows -> Change -> Finish sure to select the option to install C++ tools and the Windows SDK
3. Enable `Debugging Tools for Windows`, Goto Control Panel -> Windows 10 SDK
-> Right-Click -> Change -> Change -> Check Debugging Tools for Windows ->
Change -> Finish
#### To build: #### To build:
@ -144,13 +145,15 @@ Env vars: `DENO_BUILD_MODE`, `DENO_BUILD_PATH`, `DENO_BUILD_ARGS`.
## Contributing ## Contributing
1. Fork [this repository](https://github.com/denoland/deno) and create your branch from `master`. 1. Fork [this repository](https://github.com/denoland/deno) and create your
branch from `master`.
2. Make your change. 2. Make your change.
3. Ensure `./tools/test.py` passes. 3. Ensure `./tools/test.py` passes.
4. Format your code with `./tools/format.py`. 4. Format your code with `./tools/format.py`.
5. Make sure `./tools/lint.py` passes. 5. Make sure `./tools/lint.py` passes.
6. Send a pull request. 6. Send a pull request.
7. Sign the [CLA](https://cla-assistant.io/denoland/deno), if you haven't already. 7. Sign the [CLA](https://cla-assistant.io/denoland/deno), if you haven't
already.
<!-- prettier-ignore --> <!-- prettier-ignore -->
[avy badge]: https://ci.appveyor.com/api/projects/status/yel7wtcqwoy0to8x?branch=master&svg=true [avy badge]: https://ci.appveyor.com/api/projects/status/yel7wtcqwoy0to8x?branch=master&svg=true

114
Roadmap.md
View file

@ -42,29 +42,30 @@ https://github.com/denoland/deno/master/testing.js
## Security Model (partially implemented) ## Security Model (partially implemented)
* We want to be secure by default; user should be able to run untrusted code, - We want to be secure by default; user should be able to run untrusted code,
like the web. like the web.
* Threat model: - Threat model:
* Modifiying/deleting local files - Modifiying/deleting local files
* Leaking private information - Leaking private information
* Disallowed default: - Disallowed default:
* Network access - Network access
* Local write access - Local write access
* Non-JS extensions - Non-JS extensions
* Subprocesses - Subprocesses
* Env access - Env access
* Allowed default: - Allowed default:
* Local read access. - Local read access.
* argv, stdout, stderr, stdin access always allowed. - argv, stdout, stderr, stdin access always allowed.
* Maybe: temp dir write access. (But what if they create symlinks there?) - Maybe: temp dir write access. (But what if they create symlinks there?)
* The user gets prompted when the software tries to do something it doesn't have - The user gets prompted when the software tries to do something it doesn't have
the privilege for. the privilege for.
* Have an option to get a stack trace when access is requested. - Have an option to get a stack trace when access is requested.
* Worried that granting access per file will give a false sense of security due - Worried that granting access per file will give a false sense of security due
to monkey patching techniques. Access should be granted per program (js to monkey patching techniques. Access should be granted per program (js
context). context).
Example security prompts. Options are: YES, NO, PRINT STACK Example security prompts. Options are: YES, NO, PRINT STACK
``` ```
Program requests write access to "~/.ssh/id_rsa". Grant? [yNs] Program requests write access to "~/.ssh/id_rsa". Grant? [yNs]
http://gist.github.com/asdfasd.js requests network access to "www.facebook.com". Grant? [yNs] http://gist.github.com/asdfasd.js requests network access to "www.facebook.com". Grant? [yNs]
@ -72,9 +73,9 @@ Program requests access to environment variables. Grant? [yNs]
Program requests to spawn `rm -rf /`. Grant? [yNs] Program requests to spawn `rm -rf /`. Grant? [yNs]
``` ```
* cli flags to grant access ahead of time --allow-all --allow-write --allow-net - cli flags to grant access ahead of time --allow-all --allow-write --allow-net
--allow-env --allow-exec --allow-env --allow-exec
* in version two we will add ability to give finer grain access - in version two we will add ability to give finer grain access
--allow-net=facebook.com --allow-net=facebook.com
## Milestone 1: Rust rewrite / V8 snapshot ## Milestone 1: Rust rewrite / V8 snapshot
@ -89,17 +90,15 @@ libdeno. libdeno will include the entire JS runtime as a V8 snapshot. It still
follows the message passing paradigm. Rust will be bound to this library to follows the message passing paradigm. Rust will be bound to this library to
implement the privileged part of Deno. See deno2/README.md for more details. implement the privileged part of Deno. See deno2/README.md for more details.
V8 Snapshots allow Deno to avoid recompiling the TypeScript compiler at V8 Snapshots allow Deno to avoid recompiling the TypeScript compiler at startup.
startup. This is already working. This is already working.
When the rewrite is at feature parity with the Go prototype, we will release When the rewrite is at feature parity with the Go prototype, we will release
binaries for people to try. binaries for people to try.
## Milestone 2: Scale binding infrastructure ## Milestone 2: Scale binding infrastructure
ETA: October 2018 ETA: October 2018 https://github.com/denoland/deno/milestone/2
https://github.com/denoland/deno/milestone/2
We decided to use Tokio https://tokio.rs/ to provide asynchronous I/O, thread We decided to use Tokio https://tokio.rs/ to provide asynchronous I/O, thread
pool execution, and as a base for high level support for various internet pool execution, and as a base for high level support for various internet
@ -110,11 +109,10 @@ it. We expect this to result in preliminary file system operations, fetch() for
http. Additionally we are working on CI, release, and benchmarking http. Additionally we are working on CI, release, and benchmarking
infrastructure to scale development. infrastructure to scale development.
## libdeno C API. ## libdeno C API.
Deno's privileged side will primarily be programmed in Rust. However there Deno's privileged side will primarily be programmed in Rust. However there will
will be a small C API that wraps V8 to 1) define the low-level message passing be a small C API that wraps V8 to 1) define the low-level message passing
semantics 2) provide a low-level test target 3) provide an ANSI C API binding semantics 2) provide a low-level test target 3) provide an ANSI C API binding
interface for Rust. V8 plus this C API is called libdeno and the important bits interface for Rust. V8 plus this C API is called libdeno and the important bits
of the API is specified here: of the API is specified here:
@ -148,41 +146,43 @@ const char* deno_last_exception(Deno* d);
## TypeScript API. ## TypeScript API.
This section will not attempt to over all of the APIs This section will not attempt to over all of the APIs but give a general sense
but give a general sense of them. of them.
### Internal: libdeno ### Internal: libdeno
This is the lowest-level interface to the privileged side. This is the lowest-level interface to the privileged side. It provides little
It provides little more than passing ArrayBuffers in and more than passing ArrayBuffers in and out of the VM. The libdeno API is more or
out of the VM. less feature complete now. See
The libdeno API is more or less feature complete now. https://github.com/denoland/deno/blob/master/js/libdeno.ts
See https://github.com/denoland/deno/blob/master/js/libdeno.ts
### Internal: Shared data between Rust and V8 ### Internal: Shared data between Rust and V8
We use Flatbuffers to define common structs and enums between We use Flatbuffers to define common structs and enums between TypeScript and
TypeScript and Rust. These common data structures are defined in Rust. These common data structures are defined in
https://github.com/denoland/deno/blob/master/src/msg.fbs https://github.com/denoland/deno/blob/master/src/msg.fbs This is more or less
This is more or less working. working.
### Public API ### Public API
This is the global variables and various built-in modules, namely the This is the global variables and various built-in modules, namely the `"deno"`
`"deno"` module. module.
Deno will provide common browser global utilities like `fetch()` and Deno will provide common browser global utilities like `fetch()` and
`setTimeout()`. `setTimeout()`.
Deno has typescript built-in. Users can access the built-in typescript Deno has typescript built-in. Users can access the built-in typescript using:
using:
```ts ```ts
import * as ts from "typescript" import * as ts from "typescript";
``` ```
Deno has its own built-in module which is imported with: Deno has its own built-in module which is imported with:
```ts ```ts
import * as deno from "deno" import * as deno from "deno";
``` ```
The rest of this section discusses what will be in the `deno` module. The rest of this section discusses what will be in the `deno` module.
Within Deno this is the high-level user facing API. However, the intention is to Within Deno this is the high-level user facing API. However, the intention is to
@ -201,17 +201,16 @@ compatibility with Node.
#471 #471
This will be put off until at least deno2 Milestone1 is This will be put off until at least deno2 Milestone1 is complete. One of the
complete. One of the major problems is that top-level await calls are not major problems is that top-level await calls are not syntactically valid
syntactically valid TypeScript. TypeScript.
#### I/O (Not Implemented) #721 #### I/O (Not Implemented) #721
There are many OS constructs that perform I/O: files, sockets, pipes. There are many OS constructs that perform I/O: files, sockets, pipes. Deno aims
Deno aims to provide a unified lowest common denominator interface to work with to provide a unified lowest common denominator interface to work with these
these objects. Deno needs to operate on all of these asynchronously in order objects. Deno needs to operate on all of these asynchronously in order to not
to not block the event loop and it. block the event loop and it.
Sockets and pipes support non-blocking reads and write. Generally file I/O is Sockets and pipes support non-blocking reads and write. Generally file I/O is
blocking but it can be done in a thread pool to avoid blocking the main thread. blocking but it can be done in a thread pool to avoid blocking the main thread.
@ -220,8 +219,7 @@ non-blocking reads and writes that sockets and pipes do.
The following interfaces support files, socket, and pipes and are heavily The following interfaces support files, socket, and pipes and are heavily
inspired by Go. The main difference in porting to JavaScript is that errors will inspired by Go. The main difference in porting to JavaScript is that errors will
be handled by exceptions, modulo EOF, which is returned as part of be handled by exceptions, modulo EOF, which is returned as part of `ReadResult`.
`ReadResult`.
```ts ```ts
// The bytes read during an I/O call and a boolean indicating EOF. // The bytes read during an I/O call and a boolean indicating EOF.
@ -256,7 +254,7 @@ interface Reader {
// does not indicate EOF. // does not indicate EOF.
// //
// Implementations must not retain p. // Implementations must not retain p.
async read(p: ArrayBufferView): Promise<ReadResult>; read(p: ArrayBufferView): Promise<ReadResult>;
} }
// Writer is the interface that wraps the basic write() method. // Writer is the interface that wraps the basic write() method.
@ -269,7 +267,7 @@ interface Writer {
// slice data, even temporarily. // slice data, even temporarily.
// //
// Implementations must not retain p. // Implementations must not retain p.
async write(p: ArrayBufferView): Promise<number>; write(p: ArrayBufferView): Promise<number>;
} }
// https://golang.org/pkg/io/#Closer // https://golang.org/pkg/io/#Closer
@ -290,7 +288,7 @@ interface Seeker {
// Seeking to an offset before the start of the file is an error. Seeking to // Seeking to an offset before the start of the file is an error. Seeking to
// any positive offset is legal, but the behavior of subsequent I/O operations // any positive offset is legal, but the behavior of subsequent I/O operations
// on the underlying object is implementation-dependent. // on the underlying object is implementation-dependent.
async seek(offset: number, whence: number): Promise<void>; seek(offset: number, whence: number): Promise<void>;
} }
// https://golang.org/pkg/io/#ReadCloser // https://golang.org/pkg/io/#ReadCloser
@ -311,8 +309,10 @@ interface ReadWriteCloser extends Reader, Writer, Closer { }
// https://golang.org/pkg/io/#ReadWriteSeeker // https://golang.org/pkg/io/#ReadWriteSeeker
interface ReadWriteSeeker extends Reader, Writer, Seeker {} interface ReadWriteSeeker extends Reader, Writer, Seeker {}
``` ```
These interfaces are well specified, simple, and have very nice utility These interfaces are well specified, simple, and have very nice utility
functions that will be easy to port. Some example utilites: functions that will be easy to port. Some example utilites:
```ts ```ts
// copy() copies from src to dst until either EOF is reached on src or an error // copy() copies from src to dst until either EOF is reached on src or an error
// occurs. It returns the number of bytes copied and the first error encountered // occurs. It returns the number of bytes copied and the first error encountered

9
js/testing/testing.ts
View file

@ -57,12 +57,11 @@ const FG_RED = "\x1b[31m";
const FG_GREEN = "\x1b[32m"; const FG_GREEN = "\x1b[32m";
function red_failed() { function red_failed() {
return FG_RED + "FAILED" + RESET return FG_RED + "FAILED" + RESET;
} }
function green_ok() { function green_ok() {
return FG_GREEN + "ok" + RESET return FG_GREEN + "ok" + RESET;
} }
async function runTests() { async function runTests() {
@ -96,8 +95,8 @@ async function runTests() {
const result = failed > 0 ? red_failed() : green_ok(); const result = failed > 0 ? red_failed() : green_ok();
console.log( console.log(
`\ntest result: ${result}. ${passed} passed; ${failed} failed; ` + `\ntest result: ${result}. ${passed} passed; ${failed} failed; ` +
`${ignored} ignored; ${measured} measured; ${filtered} filtered out\n`); `${ignored} ignored; ${measured} measured; ${filtered} filtered out\n`
);
if (failed === 0) { if (failed === 0) {
// All good. // All good.

25
website/README.md
View file

@ -1,23 +1,24 @@
## About benchmark data ## About benchmark data
The benchmark chart supposes `//website/data.json` has the signature of `BenchmarkData[]` where `BenchmarkData` is defined like the below: The benchmark chart supposes `//website/data.json` has the signature of
`BenchmarkData[]` where `BenchmarkData` is defined like the below:
```typescript ```typescript
interface ExecTimeData { interface ExecTimeData {
mean: number mean: number;
stddev: number stddev: number;
user: number user: number;
system: number system: number;
min: number min: number;
max: number max: number;
} }
interface BenchmarkData { interface BenchmarkData {
created_at: string, created_at: string;
sha1: string, sha1: string;
binary_size?: number, binary_size?: number;
benchmark: { benchmark: {
[key: string]: ExecTimeData [key: string]: ExecTimeData;
} };
} }
``` ```