diff --git a/README.md b/README.md index a61affc..fae8cde 100644 --- a/README.md +++ b/README.md @@ -12,19 +12,19 @@ Welcome to the Internet of Peers ## Table of Contents -### Pear runtime +### Pear Runtime -References for utilizing the Pear runtime. +References for Pear Runtime. * [Command-Line-Interface (CLI)](./reference/pear/cli.md) * [Application-Programming-Interface (API)](./reference/pear/api.md) * [Application Configuration](./reference/pear/configuration.md) -> The Pear runtime uses [Bare](https://github.com/holepunchto/bare) JavaScript runtime, which is a small and modular JavaScript runtime for desktop and mobile. To learn more, see [Bare Reference](./reference/bare/overview.md). +> The Pear Runtime uses [Bare](https://github.com/holepunchto/bare) JavaScript runtime, which is a small and modular JavaScript runtime for desktop and mobile. To learn more, see [Bare Reference](./reference/bare/overview.md). ### Guides -Guides on using the pear runtime to build and share P2P applications. +Guides on using the Pear Runtime to build and share P2P applications. * [Getting Started](./guide/getting-started.md) * [Starting a Pear Desktop Project](./guide/starting-a-pear-desktop-project.md) diff --git a/assets/trust-dialog.png b/assets/trust-dialog.png new file mode 100644 index 0000000..bd9c63e Binary files /dev/null and b/assets/trust-dialog.png differ diff --git a/guide/sharing-a-pear-app.md b/guide/sharing-a-pear-app.md index b280f66..952e04a 100644 --- a/guide/sharing-a-pear-app.md +++ b/guide/sharing-a-pear-app.md @@ -93,7 +93,27 @@ With another machine or friend that has `pear` installed execute the `pear run < pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o ``` -When `pear run` is executed on the peer machine the staged application should open on that peer. If the application is being opened for the first time on the peer it has no state at all, so the application may show a loader until it's ready to reveal. +When `pear run` is executed on the peer machine there will be a security prompt to add the key to a list of trusted applications by typing 'TRUST'. + +When running a terminal application using an untrusted key for the first time the prompt would be: + +``` +pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o +✖ Key pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o is not known + +Be sure that software is trusted before running it + +Type "TRUST" to allow execution or anything else to exit + +Trust application? +``` +The trust dialog is a security mechanism in Pear that appears when the user tries to run an application from an unknown or untrusted key for the first time. In case that the app is run in detached mode, for example, when clicking on a pear link in the browser, the trust dialog is a GUI (Graphical User Interface). + +![Trust dialog](../assets/trust-dialog.png) + +> During development with `pear dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys. + +The application has no state when it's opened for the first time, so the application may show a loader until it's ready to reveal. The application staging machine that is running the seeding process should show output similar to: diff --git a/howto/work-with-many-hypercores-using-corestore.md b/howto/work-with-many-hypercores-using-corestore.md index 66770b7..7194664 100644 --- a/howto/work-with-many-hypercores-using-corestore.md +++ b/howto/work-with-many-hypercores-using-corestore.md @@ -37,7 +37,7 @@ await Promise.all([core1.ready(), core2.ready(), core3.ready()]) console.log('main core key:', b4a.toString(core1.key, 'hex')) // Here we'll only join the swarm with the core1's discovery key -// We don't need to announce core2 and core3, because they'll replicated with core1 +// We don't need to announce core2 and core3, because they'll be replicated with core1 swarm.join(core1.discoveryKey) // Corestore replication internally manages to replicate every loaded core diff --git a/reference/bare/nodejs-compatibility-with-bare.md b/reference/bare/nodejs-compatibility-with-bare.md index 23dbe5a..693eee8 100644 --- a/reference/bare/nodejs-compatibility-with-bare.md +++ b/reference/bare/nodejs-compatibility-with-bare.md @@ -1,22 +1,32 @@ # Node.js Compatibility with Bare -Bare offers seamless compatibility with Node.js counterparts. +Bare offers great compatibility with Node.js counterparts. Most of the modules and APIs used by developers are covered and supported. ## Currently supported modules - +* `assert`: [`bare-assert`](https://github.com/holepunchto/bare-assert) (through `npm:bare-node-assert)` +* `buffer`: [`bare-buffer`](https://github.com/holepunchto/bare-buffer) (through `npm:bare-node-buffer)` * `child_process`: [`bare-subprocess`](https://github.com/holepunchto/bare-subprocess) (through `npm:bare-node-child-process)` * `console`: [`bare-console`](https://github.com/holepunchto/bare-console) (through `npm:bare-node-console)` +* `crypto`: [`bare-crypto`](https://github.com/holepunchto/bare-crypto) (through `npm:bare-node-crypto)` * `events`: [`bare-events`](https://github.com/holepunchto/bare-events) (through `npm:bare-node-events)` * `fs`: [`bare-fs`](https://github.com/holepunchto/bare-fs) (through `npm:bare-node-fs)` * `http`: [`bare-http1`](https://github.com/holepunchto/bare-http1) (through `npm:bare-node-http)` +* `https`: [`bare-https`](https://github.com/holepunchto/bare-https) (through `npm:bare-node-https)` * `inspector`: [`bare-inspector`](https://github.com/holepunchto/bare-inspector) (through `npm:bare-node-inspector)` +* `module`: [`bare-module`](https://github.com/holepunchto/bare-module) (through `npm:bare-node-module)` * `os`: [`bare-os`](https://github.com/holepunchto/bare-os) (through `npm:bare-node-os)` * `path`: [`bare-path`](https://github.com/holepunchto/bare-path) (through `npm:bare-node-path)` * `process`: [`bare-process`](https://github.com/holepunchto/bare-process) (through `npm:bare-node-process)` * `readline`: [`bare-readline`](https://github.com/holepunchto/bare-readline) (through `npm:bare-node-readline)` * `repl`: [`bare-repl`](https://github.com/holepunchto/bare-repl) (through `npm:bare-node-repl)` +* `stream`: [`bare-stream`](https://github.com/holepunchto/bare-stream) (through `npm:bare-node-stream)` +* `timers`: [`bare-timers`](https://github.com/holepunchto/bare-timers) (through `npm:bare-node-timers)` +* `tls`: [`bare-tls`](https://github.com/holepunchto/bare-tls) (through `npm:bare-node-tls)` * `tty`: [`bare-tty`](https://github.com/holepunchto/bare-tty) (through `npm:bare-node-tty)` * `url`: [`bare-url`](https://github.com/holepunchto/bare-url) (through `npm:bare-node-url)` +* `util`: [`bare-utils`](https://github.com/holepunchto/bare-utils) (through `npm:bare-node-util)` +* `worker_threads`: [`bare-worker`](https://github.com/holepunchto/bare-worker) (through `npm:bare-node-worker-threads)` +* `zlib`: [`bare-zlib`](bhttps://github.com/holepunchto/bare-zlib) (through `npm:bare-node-zlib)` ## Config for the Node.js stdlib @@ -25,18 +35,28 @@ To get the full Node.js compatible layer that Bare currently supports add the fo ```json { "dependencies": { + "bare-assert": "^1.0.1", + "assert": "npm:bare-node-assert", + "bare-buffer": "^2.3.0", + "buffer": "npm:bare-node-buffer", "bare-subprocess": "^2.0.4", "child_process": "npm:bare-node-child-process", "bare-console": "^4.1.0", "console": "npm:bare-node-console", + "bare-crypto": "^1.0.0", + "crypto": "npm:bare-node-crypto", "bare-events": "^2.2.0", "events": "npm:bare-node-events", "bare-fs": "^2.1.5", "fs": "npm:bare-node-fs", "bare-http1": "^2.0.3", "http": "npm:bare-node-http", + "bare-https": "^1.0.0", + "https": "npm:bare-node-https", "bare-inspector": "^1.1.2", "inspector": "npm:bare-node-inspector", + "bare-module": "^1.2.5", + "module": "npm:bare-node-module", "bare-os": "^2.2.0", "os": "npm:bare-node-os", "bare-path": "^2.1.0", @@ -47,10 +67,22 @@ To get the full Node.js compatible layer that Bare currently supports add the fo "readline": "npm:bare-node-readline", "bare-repl": "^1.0.3", "repl": "npm:bare-node-repl", + "bare-stream": "^1.0.0", + "stream": "npm:bare-node-stream", + "bare-timers" : "^1.0.0", + "timers": "npm:bare-node-timers", + "bare-tls": "^1.0.0", + "tls": "npm:bare-node-tls", "bare-tty": "^3.2.0", "tty": "npm:bare-node-tty", "bare-url": "^1.0.7", - "url": "npm:bare-node-url" + "url": "npm:bare-node-url", + "bare-utils": "^1.0.0", + "util": "npm:bare-node-util", + "bare-worker": "^1.0.0", + "worker_threads": "npm:bare-node-worker-threads", + "bare-zlib": "^1.0.0", + "zlib": "npm:bare-node-zlib" } } ``` diff --git a/reference/pear/api.md b/reference/pear/api.md index 8572c14..a93664e 100644 --- a/reference/pear/api.md +++ b/reference/pear/api.md @@ -261,6 +261,24 @@ async function logPrefUpdates () { logPrefUpdates().catch(console.error) ``` +## `Pear.worker ` + +Pear Worker is used to spawn processes and facilitate communication between the parent and child processes in the Pear Runtime. + +The spawned worker process inherits standard input, output, and error from the parent process. + +A bidirectional pipe is also created which enables communication between the parent and worker process. + +Reference counting is handled automatically to manage the sidecar lifecycle. + +### `const pipe = Pear.worker.run(key )` + +Spawns a new process with the specified key as the entry point. Resolves to a `Duplex` stream object representing a pipe. + +### `const pipe = Pear.worker.pipe()` + +Returns the communication pipe created to the worker process. Resolves to a `Duplex` stream object representing a pipe. + ## `Pear.media ` Media interface @@ -362,6 +380,10 @@ will be waited upon until resolution before calling the next teardown handler. Restart the application. +### `Pear.exit(code)` + +Exits the process with the provided exit code. + ### `Pear.updates(listener ) => streamx.Readable` The `listener` function is called for every incoming update with an `update` object of the form: diff --git a/reference/pear/cli.md b/reference/pear/cli.md index 3df802a..1e24164 100644 --- a/reference/pear/cli.md +++ b/reference/pear/cli.md @@ -70,13 +70,17 @@ Run an application from a key or dir. ``` - --dev Enable --devtools & --updates-diff + --dev|-d Enable --devtools & --updates-diff --devtools Open devtools with application [Desktop] --updates-diff Enable diff computation for Pear.updates --no-updates Disable updates firing via Pear.updates --link=url Simulate deep-link click open --store|-s=path Set the Application Storage path --tmp-store|-t Automatic new tmp folder as store path + --chrome-webrtc-internals Enable chrome://webrtc-internals + --unsafe-clear-app-storage Clear app storage + --unsafe-clear-preferences Clear preferences (such as trustlist) + --appling=path Set application shell path --checkout=n Run a checkout, n is version length --checkout=release Run checkout from marked released length --checkout=staged Run checkout from latest version length @@ -115,16 +119,20 @@ Use this to indicate production release points. --checkout=n|current Set a custom release length (version) ``` -## `pear info [key]` +## `pear info [channel|key]` Read project information. -Supply a key to view application info +Supply a key or channel to view application information. -Without a key pear info shows Pear info +Supply no argument to view platform information. ``` - --json Newline delimited JSON output + --changelog View changelog only + --full-changelog Full record of changes + --metadata View metadata only + --key View key only + --json Newline delimited JSON output ``` ## `pear dump [dir]` @@ -148,12 +156,6 @@ and then becomes the sidecar. --mem memory mode: RAM corestore --attach-boot-io include initial sidecar I/O (if applicable) ``` - -## `pear repl` - -Connect to a Read-Eval-Print-Loop session with sidecar. - -A key is printed out, use with repl-swarm module to connect. ## `pear versions` @@ -172,7 +174,19 @@ Move user application storage between applications. --json Newline delimited JSON output ``` +## `pear gc [flags] [command]` +Perform garbage collection and remove unused resources. + +| Commands | Description | +|-------|---------------------------------------------------| +| releases | Clear inactive releases | +| sidecars | Clear running sidecars | + +``` + --json Newline delimited JSON output + --help|-h Show help +``` diff --git a/reference/pear/configuration.md b/reference/pear/configuration.md index 400dd36..56a2735 100644 --- a/reference/pear/configuration.md +++ b/reference/pear/configuration.md @@ -120,6 +120,14 @@ Enable transparency. Must be set for opacity to work. Background color (Hex, RGB, RGBA, HSL, HSLA, CSS color). +### `pear.links ` + +An array or object containing trusted Pear application keys. + +#### `pear.links.worker ` + +The key of the Pear application that contains the worker script. For more info, please check the [terminal](https://github.com/holepunchto/pear/blob/main/examples/terminal/index.js#L21) and [desktop](https://github.com/holepunchto/pear/blob/main/examples/desktop/app.js#L27) examples. + ### `pear.stage ` Staging configuration options.