Prepare README for v0.5.0 release (#532)

* Add more points to features list * Same feature list on other file * Write a little bit about configuration * Update usage * Fix link * Add examples * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Wrap lines * Correct XDG directory * Add resources section * Small edits * Add GraphQL query examples * Move query comment into code snippet * Move comments back out of query snippet * Move query examples into own section * Update "what can i build" section * Update README.md * Review change requests * Fix query to use unix timestamps * Minor additions to aquadoggo/README.md * Include README.md in lib doc string * Remove empty line * Minor change * Don't run code snippet in README during tests --------- Co-authored-by: Sam Andreae <[email protected]>
p2panda · Aug 31, 2023 · c9882d0 · c9882d0
1 parent ca4edc3
commit c9882d0
Show file tree

Hide file tree

Showing 5 changed files with 617 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <h1 align="center">aquadoggo</h1>
 
 <div align="center">
-  <strong>Embeddable p2p network node</strong>
+  <strong>p2panda network node</strong>
 </div>
 
 <br />
@@ -43,31 +43,158 @@
 
 <br/>
 
-Configurable node server implementation for the [`p2panda`] network running as a
-[`command line application`] or embedded via the [`library`] inside your Rust program.
+`aquadoggo` is a reference node implementation for [p2panda](https://p2panda.org). It is a intended as a tool for making the design and build of local-first, collaborative p2p applications as simple as possible, and hopefully even a little fun!
 
-> The core p2panda [`specification`] is fully functional but still under review so
-> please be prepared for breaking API changes until we reach v1.0. Currently no
-> p2panda implementation has received a security audit.
+`aquadoggo` can run both on your own device for local-first applications, or on a public server when acting as shared community infrastructure. Nodes like `aquadoggo` perform a number of tasks ranging from core p2panda data replication and validation, aiding the discovery and establishment of connections between edge peers, and exposing a developer friendly API used for building applications.
 
-[`command line application`]: /aquadoggo_cli
-[`library`]: /aquadoggo
-[`p2panda`]: https://p2panda.org/
-[`specification`]: https://p2panda.org/specification
+> 📖 Read more about nodes in our [learn](https://p2panda.org/learn/networks) section
 
 ## Features
 
 - Awaits signed operations from clients via GraphQL.
 - Verifies the consistency, format and signature of operations and rejects invalid ones.
 - Stores operations of the network in an SQL database of your choice (SQLite, PostgreSQL).
 - Materializes views on top of the known data.
-- Answers filterable and paginated data queries via GraphQL.
+- Answers filtered, sorted and paginated data queries via GraphQL.
 - Discovers other nodes in local network and internet.
-- Replicates data with other nodes.
+- Establishes peer-to-peer connections via UDP holepunching or via relays.
+- Replicates data efficiently with other nodes.
 
-## Example
+## Who is this for?
 
-Embed the node server in your Rust application or web container like [`Tauri`]:
+`aquadoggo` might be interesting for anyone who wants to participate in a p2p network. This could be as a node maintainer, an application developer or simply someone wanting to learn more about p2p networking in a hands-on fashion.
+
+If you are familiar with (or are keen to learn) how to use command line interfaces then you're able to deploy a node on your own machine, you can then experiment with creating data schemas, publishing and replicating data, and then querying it again using the GraphQL playground. Check out the [resources](#Resources) section for ideas on next steps when you're ready.
+
+## What can I build with this?
+
+Many applications which rely on being able to store and retrieve data from a persistent store could likely be built using `aquadoggo` as their data layer. `aquadoggo` can be considered as a p2p "backend", which takes some of the complexity out of p2p development, leaving you to focus on building applications using your preferred tools.
+
+> If you want to build a client application which communicates with an `aquadoggo` you will need to have some experience with web development or the Rust programming language. For writing an application using Rust you can import `aquadoggo` directly in your code. If building a TypeScript web frontend which will interface with a local or remote node, you can import the small TypeScript client library [`shirokuma`](https://github.com/p2panda/shirokuma) to your project. We have plans for making it easier to interact with `aquadoggo` using other languages in the future.
+
+Some example applications which could be built on top of `aquadoggo` are:
+
+- 🥄 **Community centre resource management:** Members of the centre want to manage some shared resources (table tennis, tools, cooking equipment), they each run an app ([Tauri](https://tauri.app/) desktop app with a bundled `aquadoggo` inside) on their own devices, where they can add resources, view availability and making loan requests. Discovery and syncing of data occurs automatically when member's devices are on the same local network.
+    <details>
+    <summary>See config</summary>
+    <br>
+
+    ```toml
+    # Schemas needed for our resource management application
+    allow_schema_ids = [
+        "resource_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
+        "resource_booking_request_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
+        "resource_booking_accepted_00209a75d6f1440c188fa52555c8cdd60b3988e468e1db2e469b7d4425a225eba8ec",
+    ]
+
+    # Enable mDNS discovery to automatically find other nodes on the local network and share data with them
+    mdns = true
+    ```
+    </details>
+- 🐦 **Local ecology monitoring:** Village residents want to collect data on bird species which are sighted in their area over the year. They want anyone with the app to be able to upload a sighting. All the residents run a native Android app on their smartphone, and they make use of a number of relay nodes which enables discovery and p2p or relayed connection establishment.
+    <details>
+    <summary>See config</summary>
+    <br>
+
+    _app node config_
+    ```toml
+    # Schemas needed for our ecology monitoring application
+    allow_schema_ids = [
+        "bird_species_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
+        "bird_sighting_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
+    ]
+
+    # Addresses of the relay nodes helping us to connect the residents over the internet
+    relay_addresses = [
+        "203.0.113.1:2022",
+        "198.51.100.21:2022",
+    ]
+    ```
+
+    _relay node config_
+    ```toml
+    # A relay doesn't need to support any schemas
+    allow_schema_ids = []
+
+    # Enable relay mode
+    relay_mode = true
+    ```
+    </details>
+- 🗞️ **Coop notice boards:** residents of a group of housing coops want to start a collaborative notice board. Each coop deploys a node on their local network and residents access a web-app to post and view ads or news. They're already using a shared VPN so nodes can connect directly, but only some coops are allowed to join the noticeboard network.
+    <details>
+    <summary>See config</summary>
+    <br>
+
+    ```toml
+    # Schemas needed for our coop notice board application
+    allow_schema_ids = [
+        "notice_board_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d",
+        "notice_board_post_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0",
+    ]
+
+    # Addresses of already known nodes we can connect directly to
+    direct_node_addresses = [
+        "192.0.2.78:2022",
+        "198.51.100.22:2022",
+        "192.0.2.211:2022",
+        "203.0.114.123:2022",
+    ]
+
+    # Peer ids of allowed peers, these will be the expected identities for the nodes we are connecting
+    # directly to
+    allowed_peer_ids = [
+        "12D3KooWP1ahRHeNp6s1M9qDJD2oyqRsYFeKLYjcjmFxrq6KM8xd",
+        "12D3KooWPC9zdWXQ3aCEcxvuct9KUWU5tPsUT6KFo29Wf8jWRW24",
+        "12D3KooWDNNSdY8vxYKYZBGdfDTg1ZafxEVuEmh49jtF8rUeMkq2",
+        "12D3KooWMKiBvAxynLn7KmqbWdEzA8yq3of6yoLZF1cpmb4Z9fHf",
+    ]
+    ```
+    </details>
+
+We're excited to hear about your ideas! Join our [official chat](https://wald.liebechaos.org/) and reach out.
+
+## Installation
+
+### Command line application
+
+Check out our [Releases](/releases) section where we publish binaries for Linux, RaspberryPi, MacOS and Windows or read [how you can compile](/aquadoggo_cli/README.md#Installation) `aquadoggo` yourself.
+
+### Rust Crate
+
+For using `aquadoggo` in your Rust project, you can add it as a dependency with the following command:
+
+```bash
+cargo add aquadoggo
+```
+
+## Usage
+
+### Run node
+
+You can also run the node simply as a [command line application](/aquadoggo_cli). `aquadoggo` can be configured in countless ways for your needs, read our [configuration](/aquadoggo_cli/README.md#Usage) section for more examples, usecases and an overview of configuration options.
+
+```bash
+# Start a local node on your machine, go to http://localhost:2020/graphql for using the GraphQL playground
+aquadoggo
+
+# Check out all configuration options
+aquadoggo --help
+
+# Enable logging
+aquadoggo --log-level info
+```
+
+### Docker
+
+For server deployments you might prefer using [Docker](https://hub.docker.com/r/p2panda/aquadoggo) to run `aquadoggo`.
+
+```bash
+docker run -p 2020:2020 -p 2022:2022 -e LOG_LEVEL=info p2panda/aquadoggo
+```
+
+### Embed node
+
+Run the node directly next to the frontend you're building for full peer-to-peer applications by using the [`aquadoggo`](/aquadoggo) Rust crate. Check out our [Tauri](https://github.com/p2panda/tauri-example) example for writing a desktop app.
 
 ```rust
 use aquadoggo::{Configuration, Node};
@@ -78,29 +205,134 @@ let key_pair = KeyPair::new();
 let node = Node::start(key_pair, config).await;
 ```
 
-You can also run the node server simply as a [command line application][`command line application`]:
+### FFI bindings
 
-```bash
-# Compile and run local node at http://localhost:2020/graphql
-cargo run
+If you are not working with Rust you can create FFI bindings from the `aquadoggo` crate into your preferred programming language. Dealing with FFI bindings can be a bit cumbersome and we do not have much prepared for you (yet), but check out our [Meli](https://github.com/p2panda/meli/) Android project as an example on how we dealt with FFI bindings for Dart / Flutter.
 
-# Enable logging
-RUST_LOG=aquadoggo=info cargo run
+## Query API
+
+As an application developer the interface to `aquadoggo` you are likely to use the most is the GraphQL query API. For whichever schema your node supports a custom query api is generated, you use this to fetch data into your app. Results from a collection query can be paginated, filtered.
+
+Fetch one "mushroom" by it's id, returning values for only the selected fields:
+```graphql
+{
+  mushroom: mushroom_0020c3accb0b0c8822ecc0309190e23de5f7f6c82f660ce08023a1d74e055a3d7c4d(
+    id: "0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0"
+  ) {
+    fields {
+      description
+      edible
+      latin
+      title
+    }
+  }
+}
 ```
 
-.. or run it inside a [Docker](https://hub.docker.com/r/p2panda/aquadoggo) container:
+<details>
+<summary>Example query response</summary>
+<br>
 
-```bash
-docker run -p 2020:2020 -e RUST_LOG=aquadoggo=info p2panda/aquadoggo
+```json
+{
+  "mushroom": {
+    "description": "Its scientific name rhacodes comes from the Greek word rhakos, which means a piece of cloth. It does often have a soft, ragged fabric-like appearance.",
+    "edible": true,
+    "latin": "Chlorophyllum rhacodes",
+    "title": "Shaggy parasol"
+  }
+}
 ```
+</details>
 
-[`Tauri`]: https://tauri.studio
+A collection query for "events" which includes ordering and filtering as well as selecting some meta fields. Here only events between the specified dates and with a title containing the string 'funtastic' will be returned, they will be arranged in ascending chronological order:
+```graphql
+{
+  events: all_events_0020aaabb3edecb2e8b491b0c0cb6d7d175e4db0e9da6003b93de354feb9c52891d0(
+    first: 20
+    orderBy: "happening_at"
+    orderDirection: ASC
+    filter: {
+      title: { contains: "funtastic" }
+      happening_at: { gte: 1677676480, lte: 1696162480 }
+    }
+  ) {
+    totalCount
+    documents {
+      meta {
+        owner
+        documentId
+        viewId
+      }
+      fields {
+        title
+        happening_at
+      }
+    }
+  }
+}
+```
 
-## Installation
+<details>
+<summary>Example query response</summary>
+<br>
 
-```sh
-cargo add aquadoggo
+```json
+{
+  "events": {
+    "totalCount": 2,
+    "documents": [
+      {
+        "meta": {
+          "owner": "2f8e50c2ede6d936ecc3144187ff1c273808185cfbc5ff3d3748d1ff7353fc96",
+          "documentId": "0020f3214a136fd6d0a649e14432409bb28a59a6caf723fa329129c404c92574cb41",
+          "viewId": "00206e365e3a6a9b66dfe96ea4b3b3b7c61b250330a46b0c99134121603db5feef11"
+        },
+        "fields": {
+          "title": "Try funtasticize!!",
+          "happening_at": 1680264880
+        }
+      },
+      {
+        "meta": {
+          "owner": "2f8e50c2ede6d936ecc3144187ff1c273808185cfbc5ff3d3748d1ff7353fc96",
+          "documentId": "002048a55d9265a16ba44b5f3be3e457238e02d3219ecca777d7b4edf28ba2f6d011",
+          "viewId": "002048a55d9265a16ba44b5f3be3e457238e02d3219ecca777d7b4edf28ba2f6d011"
+        },
+        "fields": {
+          "title": "Is funtastic even a real word?",
+          "happening_at": 1693484080
+        }
+      }
+    ]
+  }
+}
 ```
+</details>
+
+From these examples you might already see how useful the query api will be when retrieving and displaying data in your application.
+
+## Resources
+
+- 🐬 Deploy your own `aquadoggo` following the [tutorial](https://p2panda.org/tutorials/aquadoggo)
+- 🛠️ Create your own schemas using [`fishy`](https://github.com/p2panda/fishy)
+- 🛼 Open the GraphQL playground in your browser, served under `http://localhost:2020/graphql`
+- 📖 Try the [mushroom app tutorial](https://p2panda.org/tutorials/mushroom-app)
+- 🔬 Manually publish data to a node [`send-to-node`](https://github.com/p2panda/send-to-node)
+- 🐼 [Learn more](https://p2panda.org/learn/) about how p2panda works
+
+## What shouldn't I do with `aquadoggo`?
+
+`aquadoggo` is built using the [p2panda](https://p2panda.org) protocol which is in development and some planned features are still missing, the main ones being:
+
+- **Capabilities:** Currently all data can be edited by any author who has access to the network. In many cases, permissions can be handled where needed on the client side (planned mid-2024).
+- **Privacy:** While node communication is encrypted with TLS the data stored on nodes itself is not. Integration of [MLS](https://p2panda.org/specification/encryption/) is underway but not complete yet.
+- **Deletion:** Network-wide purging of data is dependent on having a capabilities system already in place, so these two features will arrive together.
+- **Anonymity:** Networking exposes sensitive data about your used devices, we're waiting for [Arti](https://tpo.pages.torproject.net/core/arti/) supporting Onion Services to make this a configurable option.
+
+As well as these yet-to-be implemented features, there are also general networking concerns (exposing your IP address, sharing data with untrusted peers) that you should take into account when participating in any network, and particularily in peer-to-peer networks.
+
+So although `aquadoggo` is already very useful in many cases, there are others where it won't be a good fit yet or we would actively warn against use. For now, any uses which would be handling especially sensitive data are not recommended, and any users who have special network security requirements need to take extra precautions. Reach out on our [official chat](https://wald.liebechaos.org/) if you have any questions.
 
 ## License
 
@@ -114,4 +346,4 @@ GNU Affero General Public License v3.0 [`AGPL-3.0-or-later`](LICENSE)
 
 *This project has received funding from the European Union’s Horizon 2020
 research and innovation programme within the framework of the NGI-POINTER
-Project funded under grant agreement No 871528*
+Project funded under grant agreement No 871528 and NGI-ASSURE No 957073*