From ab42cd7d13eb52abb1ae20f24038c77989e5a48d Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 3 Apr 2022 12:10:45 +0200 Subject: [PATCH 1/4] Doc directory was structured and raw guides were added --- docs/{ => api}/api-client.md | 0 docs/{ => api}/api-glossary.md | 0 docs/{ => api}/api-schema.md | 0 docs/{ => apiDocs}/apidocs-client.md | 0 .../architecture-hyperstack.md | 0 docs/{ => architecture}/architecture-kappa.md | 0 docs/{ => architecture}/architecture-sonar.md | 0 .../architecture-tantivy.md | 0 docs/guides/collections.md | 13 ++++ docs/guides/handleData.md | 15 +++++ docs/guides/runServer.md | 67 +++++++++++++++++++ docs/guides/search.md | 11 +++ sidebars.js | 22 +++--- 13 files changed, 120 insertions(+), 8 deletions(-) rename docs/{ => api}/api-client.md (100%) rename docs/{ => api}/api-glossary.md (100%) rename docs/{ => api}/api-schema.md (100%) rename docs/{ => apiDocs}/apidocs-client.md (100%) rename docs/{ => architecture}/architecture-hyperstack.md (100%) rename docs/{ => architecture}/architecture-kappa.md (100%) rename docs/{ => architecture}/architecture-sonar.md (100%) rename docs/{ => architecture}/architecture-tantivy.md (100%) create mode 100644 docs/guides/collections.md create mode 100644 docs/guides/handleData.md create mode 100644 docs/guides/runServer.md create mode 100644 docs/guides/search.md diff --git a/docs/api-client.md b/docs/api/api-client.md similarity index 100% rename from docs/api-client.md rename to docs/api/api-client.md diff --git a/docs/api-glossary.md b/docs/api/api-glossary.md similarity index 100% rename from docs/api-glossary.md rename to docs/api/api-glossary.md diff --git a/docs/api-schema.md b/docs/api/api-schema.md similarity index 100% rename from docs/api-schema.md rename to docs/api/api-schema.md diff --git a/docs/apidocs-client.md b/docs/apiDocs/apidocs-client.md similarity index 100% rename from docs/apidocs-client.md rename to docs/apiDocs/apidocs-client.md diff --git a/docs/architecture-hyperstack.md b/docs/architecture/architecture-hyperstack.md similarity index 100% rename from docs/architecture-hyperstack.md rename to docs/architecture/architecture-hyperstack.md diff --git a/docs/architecture-kappa.md b/docs/architecture/architecture-kappa.md similarity index 100% rename from docs/architecture-kappa.md rename to docs/architecture/architecture-kappa.md diff --git a/docs/architecture-sonar.md b/docs/architecture/architecture-sonar.md similarity index 100% rename from docs/architecture-sonar.md rename to docs/architecture/architecture-sonar.md diff --git a/docs/architecture-tantivy.md b/docs/architecture/architecture-tantivy.md similarity index 100% rename from docs/architecture-tantivy.md rename to docs/architecture/architecture-tantivy.md diff --git a/docs/guides/collections.md b/docs/guides/collections.md new file mode 100644 index 0000000..b391af7 --- /dev/null +++ b/docs/guides/collections.md @@ -0,0 +1,13 @@ +--- +title: Collections +id: collections +--- + + +## local collection by default + +## add a new collection + +## delete a collection + +## share a collection diff --git a/docs/guides/handleData.md b/docs/guides/handleData.md new file mode 100644 index 0000000..bbddf59 --- /dev/null +++ b/docs/guides/handleData.md @@ -0,0 +1,15 @@ +--- +title: handle Data +id: handleData +--- + + +## upload + +## download + +## share + +## block + +## delete \ No newline at end of file diff --git a/docs/guides/runServer.md b/docs/guides/runServer.md new file mode 100644 index 0000000..4e6cefe --- /dev/null +++ b/docs/guides/runServer.md @@ -0,0 +1,67 @@ +--- +title: Run a Server +id: runServer +--- + +The usual setup is that you run sonar-server on localhost and then interact with Sonar through the client, the UI running on http://localhost:9191 or the CLI. The CLI can be invoked with ./sonar from the root of this repository, and is also used to start the server. + +## Installation + +```sh +npm install -g @arsonar/server +sonar help +sonar start +``` + +## Development + +> Note: At the moment [yarn 1](https://classic.yarnpkg.com/) is recommended, please [install it according to the instructions](https://classic.yarnpkg.com/en/docs/install#debian-stable). + +```sh +# clone the sonar repository +git clone https://github.com/arso-project/sonar.git +cd sonar +# install dependencies of all workspaces +yarn +# (re)build the user interface and docs +yarn run rebuild +# when developing on something that uses the ESM version of the +# `@arsonar/client` library: watch and rebuild on changes. +yarn dev:client +``` + +You can start sonar with `./sonar` from the repository root. + +If the start fails with errors related to `sonar-tantivy`, try to redownload or rebuild sonar-tantivy (the search engine included in sonar): + +``` +yarn run build:sonar-tantivy +``` + +If the start fails with errors related to `client`, try to rebuild client : + +``` +yarn run build:client +``` + +```sh +# start the sonar server +./sonar start + +# start the sonar server in dev mode +./sonar start --dev + +``` + +## Running the examples + +This repo includes a few examples. To run them locally, do the following: + +```sh +# build the client library +yarn build:client +# start sonar +./sonar start --disable-authentication --dev +# run the example from the examples/ folder +yarn example react +``` diff --git a/docs/guides/search.md b/docs/guides/search.md new file mode 100644 index 0000000..4943075 --- /dev/null +++ b/docs/guides/search.md @@ -0,0 +1,11 @@ +--- +title: Search +id: search +--- + + +## search or files + +## search for Collections + +## search with params \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 999b4c1..12e2098 100644 --- a/sidebars.js +++ b/sidebars.js @@ -3,19 +3,25 @@ module.exports = { 'Getting started': [ 'intro-start' ], + Guides: [ + 'guides/runServer', + 'guides/collections', + 'guides/handleData', + 'guides/search' + ], Architecture: [ - 'hyperstack', - 'kappa', - 'tantivy', - 'architecture-sonar' + 'architecture/hyperstack', + 'architecture/kappa', + 'architecture/tantivy', + 'architecture/architecture-sonar' ], 'API docs': [ - 'apidocs-client' + 'apiDocs/apidocs-client' ], API: [ - 'api-client', - 'api-schema', - 'api-glossary' + 'api/api-client', + 'api/api-schema', + 'api/api-glossary' ] } } From 5b9c05958c9afb56c257c162e9fa536eb2d33c7b Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 3 Apr 2022 14:14:05 +0200 Subject: [PATCH 2/4] add some content --- docs/guides/collections.md | 61 ++++++++++++++++++++++++++++++++++++-- docs/guides/filesystem.md | 9 ++++++ docs/guides/handleData.md | 11 ++++++- docs/guides/runServer.md | 8 ++--- docs/guides/search.md | 15 ++++++++-- docs/guides/workspace.md | 29 ++++++++++++++++++ sidebars.js | 2 ++ 7 files changed, 124 insertions(+), 11 deletions(-) create mode 100644 docs/guides/filesystem.md create mode 100644 docs/guides/workspace.md diff --git a/docs/guides/collections.md b/docs/guides/collections.md index b391af7..44fddf5 100644 --- a/docs/guides/collections.md +++ b/docs/guides/collections.md @@ -3,11 +3,66 @@ title: Collections id: collections --- +## What is a Collection +An collection is a set of feeds that are shared among peers. +A feed is an append-only log of records. Each feed is only writable from a single device. +A record is a unit of data. Each record has a type, a ref and a value. -## local collection by default +When sonar is started a local collection is available by default. -## add a new collection +Collections sind einem Workspace zugeordnet. + + +## add or open collection + +To add a new collection to the workspace we simply call the ``createCollection()``` function to open it we use ``openCollection()``` as for example in this code snippet: + + +```js +/** + * Check if the collection already exists if not create a new collection + * @returns opened || new collection + */ +export async function Collection(): Promise { + if (!collection) { + try { + collection = await workspace.openCollection(collectionName) + } catch (err: any) { + collection = await workspace.createCollection(collectionName) + } + // console.log('opened collection', collection.key.toString('hex')) + await ensureSchema(collection, schema) + } + return collection +} +``` ## delete a collection +???? + +## getters + +Various getters are available to retrieve the parameters of the collection: + -## share a collection +```js + get name () { + if (this._info) return this._info.name + return this._nameOrKey + } + get key () { + return this._info && this._info.key + } + get localKey () { + return this._info && this._info.localKey + } + get info () { + return this._info + } + get id () { + return this._info && this._info.id + } + get length () { + return this._length || this._info.length || 0 + } +``` diff --git a/docs/guides/filesystem.md b/docs/guides/filesystem.md new file mode 100644 index 0000000..1aacf28 --- /dev/null +++ b/docs/guides/filesystem.md @@ -0,0 +1,9 @@ +--- +title: Filesystem +id: filesystem +--- + +In order to add files to our collection we need a tile system to manage this. + +Dieses erlaubt uns nun Dateien anzulegen zu lesen oder die entsprechenden Metadaten abzurufen. Weitere Infos unter [FS](https://sonar-apidocs.dev.arso.xyz/fs.js.html) +... \ No newline at end of file diff --git a/docs/guides/handleData.md b/docs/guides/handleData.md index bbddf59..09dc3d6 100644 --- a/docs/guides/handleData.md +++ b/docs/guides/handleData.md @@ -3,6 +3,7 @@ title: handle Data id: handleData --- +# Files ## upload @@ -12,4 +13,12 @@ id: handleData ## block -## delete \ No newline at end of file +## delete + +# Schema + +# Feeds + +# Streams + +..... \ No newline at end of file diff --git a/docs/guides/runServer.md b/docs/guides/runServer.md index 4e6cefe..6357e73 100644 --- a/docs/guides/runServer.md +++ b/docs/guides/runServer.md @@ -7,7 +7,7 @@ The usual setup is that you run sonar-server on localhost and then interact with ## Installation -```sh +```bash npm install -g @arsonar/server sonar help sonar start @@ -17,7 +17,7 @@ sonar start > Note: At the moment [yarn 1](https://classic.yarnpkg.com/) is recommended, please [install it according to the instructions](https://classic.yarnpkg.com/en/docs/install#debian-stable). -```sh +```bash # clone the sonar repository git clone https://github.com/arso-project/sonar.git cd sonar @@ -44,7 +44,7 @@ If the start fails with errors related to `client`, try to rebuild client : yarn run build:client ``` -```sh +```bash # start the sonar server ./sonar start @@ -57,7 +57,7 @@ yarn run build:client This repo includes a few examples. To run them locally, do the following: -```sh +```bash # build the client library yarn build:client # start sonar diff --git a/docs/guides/search.md b/docs/guides/search.md index 4943075..ca3b1e6 100644 --- a/docs/guides/search.md +++ b/docs/guides/search.md @@ -3,9 +3,18 @@ title: Search id: search --- +To search the records of a collection we can issue a query which returns an array with the matching records. -## search or files +```js +(async) query(name, args, optsopt) → {Promise.>} +``` -## search for Collections +The arguments for the query. Depends on the query being used. For records: `{ schema, name, id }` For history: `{ from: timestamp, to: timestamp }` For search: Either a "string" for a simple full-text search, or a tantivy query object. For indexes: `{ schema, prop, value, from, to, reverse, limit }` (to be documented) For relations: `{ subject, object, predicate }` where subject and object are ids and predicate is type #field -## search with params \ No newline at end of file +Here is a small example from our peerBooks App which will return the records for the schema Book: + +```js + const records = await collection.query('records', { + type: 'sonar-peerBooks/Book' + }) +``` \ No newline at end of file diff --git a/docs/guides/workspace.md b/docs/guides/workspace.md new file mode 100644 index 0000000..ca2e11f --- /dev/null +++ b/docs/guides/workspace.md @@ -0,0 +1,29 @@ +--- +title: Workspace +id: workspace +--- +If you start Sonar it comes with a Default Workspace + +When you start Sonar it provides a default workspace. Workspaces are our endpoints in which collections can be managed, more about this under the point Collections. + +There can be multiple workspaces on one Sonar server. + +To create a new workspace you have to pass token and URL of the server for example like this in JavaScript: + +```js +/** + * Get the URL and access token for + * the Sonar instance running in the background. + */ +const url = process.env.SONAR_URL || 'http://localhost:9191/api/v1/default' +const token = process.env.SONAR_TOKEN +/** + * Initializing a client + */ +export const workspace = new Workspace({ + url, + accessCode: token +}); +``` + +Now you can create, update, open and display collections on the workspace. Furthermore the workspace offers the possibility to manage the login of the client. More about the workspace can be found in the API description: [Workspace](https://sonar-apidocs.dev.arso.xyz/Workspace.html) \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 12e2098..63fbf58 100644 --- a/sidebars.js +++ b/sidebars.js @@ -5,6 +5,8 @@ module.exports = { ], Guides: [ 'guides/runServer', + 'guides/workspace', + 'guides/filesystem', 'guides/collections', 'guides/handleData', 'guides/search' From e8c6714bc17b5c31de6c0c612fd314cd43fe968f Mon Sep 17 00:00:00 2001 From: "Franz Heinzmann (Frando)" Date: Thu, 5 May 2022 13:15:34 +0200 Subject: [PATCH 3/4] Update dependencies, fix some docs --- blog/2019-05-29-hello-world.md | 3 +- docs/api/api-client.md | 2 + docs/apiDocs/apidocs-client.md | 2 +- docs/guides/collections.md | 44 +- docs/guides/files.md | 31 + docs/guides/filesystem.md | 8 +- docs/guides/handleData.md | 24 - docs/guides/workspace.md | 3 +- docusaurus.config.js | 76 +- package.json | 25 +- sidebars.js | 17 +- src/pages/index.js | 76 +- yarn.lock | 11957 +++++++++++++++---------------- 13 files changed, 6049 insertions(+), 6219 deletions(-) create mode 100644 docs/guides/files.md delete mode 100644 docs/guides/handleData.md diff --git a/blog/2019-05-29-hello-world.md b/blog/2019-05-29-hello-world.md index 612aae6..2f57f6d 100644 --- a/blog/2019-05-29-hello-world.md +++ b/blog/2019-05-29-hello-world.md @@ -1,10 +1,9 @@ --- -id: hello-world +slug: hello-world title: Hello author: arso-project author_title: coop author_url: https://github.com/arso-project -author_image_url: tags: [hello, sonar] --- diff --git a/docs/api/api-client.md b/docs/api/api-client.md index 78262e7..e792b50 100644 --- a/docs/api/api-client.md +++ b/docs/api/api-client.md @@ -6,6 +6,8 @@ title: Client The primary way to interact with Sonar is through the *Sonar Client*. The Client talks to the Sonar daemon over HTTP. The Sonar daemon is part of the P2P network, exchanges data with other peers and indexes the data in your islands. +