From 9990a5fd30e48f5337a5f71bf512b000337be67e Mon Sep 17 00:00:00 2001 From: Vivek Date: Thu, 25 Jul 2024 18:13:51 +0530 Subject: [PATCH 01/12] add more context to pear.links --- reference/pear/configuration.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/pear/configuration.md b/reference/pear/configuration.md index f972149..48312d8 100644 --- a/reference/pear/configuration.md +++ b/reference/pear/configuration.md @@ -126,7 +126,11 @@ Storing and managing Pear application links and domains. `links` can be an object or an array. If it's an object, naming the key makes it easy to reference from [`Pear.config.links`](./api.md#pearconfiglinks-objectarray) -The links and domains inside need to be trusted. Any pear links that the app trusts to run (eg as a worker) must be added and any http(s) domains that the app wants to access must also be added, including localhost. +By default in Pear apps, only requests to the sidecar host (127.0.0.1:9342) are allowed. Additional hosts and trusted keys must be added in `pear.links` to allow access. + +Any Pear links that the app trusts to run (eg as a worker) must be added and any http(s) domains that the app wants to access must also be added, including localhost. + +Note that this is only for requests that the Pear app makes itself such as loading assets. ```json { From ad3f757d8db0933d8b726af465548f48b4c63766 Mon Sep 17 00:00:00 2001 From: Vivek Singh <47470314+heyitsvi@users.noreply.github.com> Date: Mon, 5 Aug 2024 06:37:50 -0700 Subject: [PATCH 02/12] update pear-init (#121) --- reference/pear/cli.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/reference/pear/cli.md b/reference/pear/cli.md index 1e24164..9c65ef5 100644 --- a/reference/pear/cli.md +++ b/reference/pear/cli.md @@ -4,15 +4,18 @@ The Command Line Interface is the primary interface for Pear Development. -## `pear init [dir]` +## `pear init [flags] [dir]` Create initial project files. +Template Types: desktop, terminal, terminal-node + ``` --yes|-y Autoselect all defaults ---type|-t=type Project type: desktop (default) or terminal +--type|-t=type Template type. Overrides --force|-f Force overwrite existing files --with|-w=name Additional functionality. Available: node +--help|-h Show help ``` ## `pear dev [flags] [dir] [...app-args]` From ca36ca514c977347c833e9087bbd0b78849111d3 Mon Sep 17 00:00:00 2001 From: Sean Zellmer Date: Wed, 14 Aug 2024 02:48:25 -0500 Subject: [PATCH 03/12] Adjust hyperswarm example to pass topic arg directly (#112) Added explicit `.` for the first run of the app to make it more obvious that the second run of the app is just passing the topic instead of automatically generating one. --- howto/connect-to-many-peers-by-topic-with-hyperswarm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/howto/connect-to-many-peers-by-topic-with-hyperswarm.md b/howto/connect-to-many-peers-by-topic-with-hyperswarm.md index 922d7c2..3aba393 100644 --- a/howto/connect-to-many-peers-by-topic-with-hyperswarm.md +++ b/howto/connect-to-many-peers-by-topic-with-hyperswarm.md @@ -49,7 +49,7 @@ process.stdin.on('data', d => { }) // Join a common topic -const topic = process.argv[2] ? b4a.from(process.argv[2], 'hex') : crypto.randomBytes(32) +const topic = process.argv[3] ? b4a.from(process.argv[3], 'hex') : crypto.randomBytes(32) const discovery = swarm.join(topic, { client: true, server: true }) // The flushed promise will resolve when the topic has been fully announced to the DHT @@ -62,9 +62,9 @@ In one terminal, open `peer-app` with `pear dev` ``` cd peer-app -pear dev +pear dev . ``` -This will display the topic. Copy/paste that topic into as many additional terminals as desired with `pear dev -- ` (assuming that the current working directory of each terminal is the `peer-app` folder). Each peer will log information about the other connected peers. +This will display the topic. Copy/paste that topic into as many additional terminals as desired with `pear dev . ` (assuming that the current working directory of each terminal is the `peer-app` folder). Each peer will log information about the other connected peers. Start typing into any terminal, and it will be broadcast to all connected peers. From c2de1e14d80e9941f8375fab89413c7bb41b6397 Mon Sep 17 00:00:00 2001 From: d61b292b-2859-4ed6-8c7c-b7397ad8e351 Date: Wed, 14 Aug 2024 09:50:01 +0200 Subject: [PATCH 04/12] Fix typo (#125) --- howto/work-with-many-hypercores-using-corestore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/howto/work-with-many-hypercores-using-corestore.md b/howto/work-with-many-hypercores-using-corestore.md index 7194664..a97d926 100644 --- a/howto/work-with-many-hypercores-using-corestore.md +++ b/howto/work-with-many-hypercores-using-corestore.md @@ -130,7 +130,7 @@ for (const key of otherKeys) { In one terminal, open `multicore-writer-app` with `pear dev`. ``` -cd mutlicore-writer-app +cd multicore-writer-app pear dev ``` @@ -143,4 +143,4 @@ cd multicore-reader-app pear dev . ``` -As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application. \ No newline at end of file +As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application. From e28cf00b1026432500cb98d6000050c457f2530f Mon Sep 17 00:00:00 2001 From: Md Tanjin Alam Date: Wed, 14 Aug 2024 13:52:15 +0600 Subject: [PATCH 05/12] Fixed command-line argument parameter parsing across files from process.argv[2] to process.argv[3] (#115) --- howto/connect-two-peers-by-key-with-hyperdht.md | 4 ++-- .../create-a-full-peer-to-peer-filesystem-with-hyperdrive.md | 2 +- howto/share-append-only-databases-with-hyperbee.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/howto/connect-two-peers-by-key-with-hyperdht.md b/howto/connect-two-peers-by-key-with-hyperdht.md index c0027bd..b49e0ac 100644 --- a/howto/connect-two-peers-by-key-with-hyperdht.md +++ b/howto/connect-two-peers-by-key-with-hyperdht.md @@ -67,8 +67,8 @@ import DHT from 'hyperdht' import b4a from 'b4a' import process from 'bare-process' -console.log('Connecting to:', process.argv[2]) -const publicKey = b4a.from(process.argv[2], 'hex') +console.log('Connecting to:', process.argv[3]) +const publicKey = b4a.from(process.argv[3], 'hex') const dht = new DHT() const conn = dht.connect(publicKey) diff --git a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md index 4f5f0c8..1859ae9 100644 --- a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md +++ b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md @@ -188,7 +188,7 @@ Pear.teardown(() => swarm.destroy()) swarm.on('connection', conn => store.replicate(conn)) // create/get the hypercore instance using the public key supplied as command-line arg -const core = store.get({ key: b4a.from(process.argv[2], 'hex') }) +const core = store.get({ key: b4a.from(process.argv[3], 'hex') }) // create a hyperbee instance using the hypercore instance const bee = new Hyperbee(core, { diff --git a/howto/share-append-only-databases-with-hyperbee.md b/howto/share-append-only-databases-with-hyperbee.md index 7d62a36..266c2ae 100644 --- a/howto/share-append-only-databases-with-hyperbee.md +++ b/howto/share-append-only-databases-with-hyperbee.md @@ -188,7 +188,7 @@ Pear.teardown(() => swarm.destroy()) swarm.on('connection', conn => store.replicate(conn)) // create or get the hypercore using the public key supplied as command-line argument -const core = store.get({ key: b4a.from(process.argv[2], 'hex') }) +const core = store.get({ key: b4a.from(process.argv[3], 'hex') }) // wait till the properties of the hypercore instance are initialized await core.ready() From 1a4f97138f57baf030b08bd3f23c4d1d5efe60b4 Mon Sep 17 00:00:00 2001 From: Vivek Singh <47470314+heyitsvi@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:09:34 +0530 Subject: [PATCH 06/12] fixes (#126) --- building-blocks/hyperdht.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/building-blocks/hyperdht.md b/building-blocks/hyperdht.md index 33ba2aa..282ff84 100644 --- a/building-blocks/hyperdht.md +++ b/building-blocks/hyperdht.md @@ -42,8 +42,8 @@ Notable features include: * [node.unannounce(topic, keyPair, \[options\])](hyperdht.md#node.unannounce) * [Mutable/immutable records:](hyperdht.md#mutable-immutable-records) * Methods: - * [node.immutablePut(value, \[options\])](hyperdht.md#node.inmutableput) - * [node.immutableGet(hash, \[options\])](hyperdht.md#node.inmutableget) + * [node.immutablePut(value, \[options\])](hyperdht.md#node.immutableput) + * [node.immutableGet(hash, \[options\])](hyperdht.md#node.immutableget) * [node.mutablePut(keyPair, value, \[options\])](hyperdht.md#node.mutableput) * [node.mutableGet(publicKey, \[options\])](hyperdht.md#node.mutableget) @@ -243,17 +243,17 @@ Unannounces a key pair. Any passed options are forwarded to dht-rpc. -### Mutable/Immutable Records {#mutable-inmutable-records} +### Mutable/Immutable Records {#mutable-immutable-records} #### Methods -#### **`const { hash, closestNodes } = await node.immutablePut(value, [options])`** {#node.inmutableput} +#### **`const { hash, closestNodes } = await node.immutablePut(value, [options])`** {#node.immutableput} Stores an immutable value in the DHT. When successful, the hash of the value is returned. Any passed options are forwarded to dht-rpc. -#### **`const { value, from } = await node.immutableGet(hash, [options])`** {#node.inmutableget} +#### **`const { value, from } = await node.immutableGet(hash, [options])`** {#node.immutableget} Fetch an immutable value from the DHT. When successful, it returns the value corresponding to the hash. From 6b7ca689cb8ec38909fef9925d9f7d76ab729394 Mon Sep 17 00:00:00 2001 From: d61b292b-2859-4ed6-8c7c-b7397ad8e351 Date: Wed, 14 Aug 2024 13:13:54 +0200 Subject: [PATCH 07/12] Fix URL fragment (#127) Link to join method was broken --- building-blocks/hyperswarm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/building-blocks/hyperswarm.md b/building-blocks/hyperswarm.md index 350da78..465547f 100644 --- a/building-blocks/hyperswarm.md +++ b/building-blocks/hyperswarm.md @@ -21,7 +21,7 @@ Notable features include: * [swarm.peers](hyperswarm.md#swarm.peers) * [swarm.dht](hyperswarm.md#swarm.dht) * Methods: - * [swarm.join(topic, [options])](hyperswarm.md#const-discovery--swarmjointopic-options) + * [swarm.join(topic, [options])](hyperswarm.md#swarm.join) * Events: * [connection](hyperswarm.md#swarm.onconnection) * [update](hyperswarm.md#swarm.onupdate) From 928bb27b3e32b4d35e796d8f2a241909a02a1647 Mon Sep 17 00:00:00 2001 From: d61b292b-2859-4ed6-8c7c-b7397ad8e351 Date: Thu, 15 Aug 2024 14:18:53 +0200 Subject: [PATCH 08/12] Fix dependencies (#128) Add `hyperbee` to installed packages Remove `debounceify` since it's not used --- .../create-a-full-peer-to-peer-filesystem-with-hyperdrive.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md index 1859ae9..8c4bb79 100644 --- a/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md +++ b/howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md @@ -165,7 +165,7 @@ In a new terminal, create the `bee-reader-app` project with these commands: mkdir bee-reader-app cd bee-reader-app pear init -y -t terminal -npm install corestore hyperswarm hyperdrive debounceify b4a bare-process +npm install corestore hyperswarm hyperdrive hyperbee b4a bare-process ``` Adjust the `bee-reader-app/index.js` file to: @@ -174,7 +174,6 @@ Adjust the `bee-reader-app/index.js` file to: import Hyperswarm from 'hyperswarm' import Corestore from 'corestore' import Hyperbee from 'hyperbee' -import debounce from 'debounceify' import b4a from 'b4a' import process from 'bare-process' @@ -229,4 +228,4 @@ pear dev The `bee-reader-app` creates a Hyperbee instance using the Hypercore instance created with the copied public key. Every time the Hyperbee is updated (an `append` event is emitted on the underlying Hypercore), all file metadata nodes will be logged out. -Try adding or removing a few files from the writer's data directory, then pressing `Enter` in the writer's terminal to mirror the changes. \ No newline at end of file +Try adding or removing a few files from the writer's data directory, then pressing `Enter` in the writer's terminal to mirror the changes. From 74a3e1a3f6b8faba77cc36b4cf053f5cb614d0ab Mon Sep 17 00:00:00 2001 From: rafapaezbas <15270736+rafapaezbas@users.noreply.github.com> Date: Thu, 15 Aug 2024 19:12:03 +0200 Subject: [PATCH 09/12] fix pear worker docs (#129) --- reference/pear/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/pear/api.md b/reference/pear/api.md index 896846a..7e8bdc1 100644 --- a/reference/pear/api.md +++ b/reference/pear/api.md @@ -280,9 +280,9 @@ A bidirectional pipe is also created which enables communication between the par Reference counting is handled automatically to manage the sidecar lifecycle. -### `const pipe = Pear.worker.run(key )` +### `const pipe = Pear.worker.run(link , args >)` -Spawns a new process with the specified key as the entry point. Resolves to a `Duplex` stream object representing a pipe. +Runs a Pear Worker by spawning a Pear Terminal Application process from the specified `link` parameter. The Worker uses the flags of the parent application but any application arguments must be passed using the `args` parameter. Returns a pipe (a [`streamx`](https://github.com/mafintosh/streamx) `Duplex` stream) for Worker communication. ### `const pipe = Pear.worker.pipe()` From b11083fc8dbe4535407db3f9e955aaa46f7c692b Mon Sep 17 00:00:00 2001 From: d61b292b-2859-4ed6-8c7c-b7397ad8e351 Date: Tue, 20 Aug 2024 10:48:50 +0200 Subject: [PATCH 10/12] Fix typo (#130) --- guide/starting-a-pear-desktop-project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/starting-a-pear-desktop-project.md b/guide/starting-a-pear-desktop-project.md index e254862..5729a28 100644 --- a/guide/starting-a-pear-desktop-project.md +++ b/guide/starting-a-pear-desktop-project.md @@ -17,7 +17,7 @@ pear init --yes This creates the base project structure. - `package.json`. App configuration. Notice the `pear` property. -- `index.js`. App entrypoint. +- `index.html`. App entrypoint. - `app.js`. Main code. - `test/index.test.js`. Test skeleton. From 7d3d2790595c3a36b39c55e1ff776536a4b68a1e Mon Sep 17 00:00:00 2001 From: Vivek Singh Date: Tue, 20 Aug 2024 14:51:47 +0530 Subject: [PATCH 11/12] simplify bare overview --- reference/bare/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/bare/overview.md b/reference/bare/overview.md index 55c3a06..b5e60ae 100644 --- a/reference/bare/overview.md +++ b/reference/bare/overview.md @@ -26,7 +26,7 @@ Bare is built on top of [libjs](https://github.com/holepunchto/libjs), which pro 2. A native addon system supporting both statically and dynamically linked addons. 3. Light-weight thread support with synchronous joins and shared array buffer support. -Everything else if left to userland modules to be implemented using these primitives, keeping the runtime itself succinct and _bare_. +All additional features are implemented by userland modules using these primitives, keeping the runtime itself lean and _bare_. ## API From 884211abcb258f525fc898111ecd648ca4168cf6 Mon Sep 17 00:00:00 2001 From: Vivek Singh <47470314+heyitsvi@users.noreply.github.com> Date: Thu, 22 Aug 2024 17:44:14 +0530 Subject: [PATCH 12/12] Release alignment (#133) * update pear worker * update pear dump * update pear run * update pear versions * typo fix * update pear wakeups * fix * fix pear versions * fix cli --- reference/pear/api.md | 24 ++++++++++++++++++------ reference/pear/cli.md | 18 +++++++++++++----- 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/reference/pear/api.md b/reference/pear/api.md index 7e8bdc1..151abf3 100644 --- a/reference/pear/api.md +++ b/reference/pear/api.md @@ -282,7 +282,7 @@ Reference counting is handled automatically to manage the sidecar lifecycle. ### `const pipe = Pear.worker.run(link , args >)` -Runs a Pear Worker by spawning a Pear Terminal Application process from the specified `link` parameter. The Worker uses the flags of the parent application but any application arguments must be passed using the `args` parameter. Returns a pipe (a [`streamx`](https://github.com/mafintosh/streamx) `Duplex` stream) for Worker communication. +Runs a Pear Worker by spawning a Pear Terminal Application process from the specified `link` parameter. The Worker uses the flags of the parent application but any application arguments must be passed using the `args` parameter, the `args` parameter also sets `Pear.config.args`. Returns a pipe (a [`streamx`](https://github.com/mafintosh/streamx) `Duplex` stream) for Worker communication. ### `const pipe = Pear.worker.pipe()` @@ -354,9 +354,9 @@ Captures available desktop sources. Resolves to an array of objects with shape ` * https://www.electronjs.org/docs/latest/api/structures/desktop-capturer-source * [``](https://www.electronjs.org/docs/latest/api/native-image) -### `Pear.versions ` +### `Pear.versions ` -Versions object. Pear versions are objects with the shape `{ fork , length , key }`. +Function that returns a promise which resolves to a Pear versions object with the shape `{ fork , length , key }`. The `key` is a Buffer of the run key. The `length` is the size of the relevant Hypercore. The `fork` property is determined by data truncation. @@ -366,10 +366,14 @@ These three properties together are a unique identifier for the entire state of The platform version. -### `Pear.versions.application { fork , length , key }` +### `Pear.versions.app { fork , length , key }` The application version. +### `Pear.versions.runtimes { bare , electron , pear }` + +The versions of runtimes. + **References** * [Pear.config.key](#pearconfigkey-objectnull) @@ -385,6 +389,10 @@ Functions supplied to teardown will be executed in order of registration when an application begins to unload. Any promise returned from each supplied function will be waited upon until resolution before calling the next teardown handler. +### Pear.reload() + +Soft-restart Terminal applications (keeps I/O), refresh application in Desktop applications. + ### `Pear.restart()` Restart the application. @@ -427,12 +435,16 @@ The `listener` function is called for every incoming wakeup with a `wakeup` obje { type: 'pear/wakeup', link: , - data: + linkData: , + fragment: , + entrypoint: } ``` * `link` is the `pear://` link for the application receiving the wakeup -* `data` is everything after the key in the `pear://` link - this would be `pathname` of a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) object but without the leading slash (`/`). Given `pear://8ts9yz9dtucxzwbxafygnjasqe9ti3dt3w7rm6sbiu8prmidacao/some/more/stuff` the `data` string would hold `some/more/stuff`. +* `linkData` is everything after the key in the `pear://` link - this would be `pathname` of a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) object but without the leading slash (`/`). Given `pear://8ts9yz9dtucxzwbxafygnjasqe9ti3dt3w7rm6sbiu8prmidacao/some/more/stuff` the `data` string would hold `some/more/stuff`. +* `fragment` is the `fragment` part of `pear://link#fragment` (location hash without the `#` prefix). +* `entrypoint` includes `entrypoint` of `pear://link/some/entry/point` (URL pathname). Also returns a [`streamx`](https://github.com/mafintosh/streamx) `Readable`) stream. diff --git a/reference/pear/cli.md b/reference/pear/cli.md index 9c65ef5..f7a350f 100644 --- a/reference/pear/cli.md +++ b/reference/pear/cli.md @@ -10,6 +10,10 @@ Create initial project files. Template Types: desktop, terminal, terminal-node +> Default Project directory path is `.` + +Template can also be initialized from a pear:// link, the template should contain a `_template.json` file. This file defines the prompts which are converted to locals that are injected into the template. + ``` --yes|-y Autoselect all defaults --type|-t=type Template type. Overrides @@ -61,15 +65,14 @@ Specify a remote key to reseed. --verbose|-v Additional output ``` -## `pear run [flags] [...app-args]` +## `pear run [flags] [...app-args]` Run an application from a key or dir. | | | |-------|---------------------------------------------------| -| key | `pear://` | +| link | `pear://` \| `pear://` | | dir | `file://` \| `` \| `` | -| alias | `pear://` | ``` @@ -80,6 +83,7 @@ Run an application from a key or dir. --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 + --links Override configured links with comma-separated key-values --chrome-webrtc-internals Enable chrome://webrtc-internals --unsafe-clear-app-storage Clear app storage --unsafe-clear-preferences Clear preferences (such as trustlist) @@ -89,6 +93,7 @@ Run an application from a key or dir. --checkout=staged Run checkout from latest version length --no-ask-trust Exit instead of asking to trust unknown keys --detached Wakeup existing app or run detached + --help|-h Show help ``` ### Examples @@ -138,13 +143,16 @@ Supply no argument to view platform information. --json Newline delimited JSON output ``` -## `pear dump [dir]` +## `pear dump [flags] ` Synchronize files from key to dir. +> To dump to stdout use `-` in place of `` + ``` + --checkout=n Dump from specified checkout, n is version length --json Newline delimited JSON output - --checkout=n Dump from a custom release length (version) + --help|-h Show help ``` ## `pear sidecar`