Merge pull request #12 from m-ld/anonymous-users

Anonymous users

.gitignore

@@ -2,4 +2,6 @@
 ext/
 node_modules/
 local/
-.env
+_site/
+*.private.env.json
+*.env

README.md

@@ -1,67 +1,32 @@
-# m-ld Gateway
-
-## build
-```shell
-npm run build
-```
-
-## start
-The server needs at least the following environment variables:
-
-| variable                | example                                 | comments            |
-|-------------------------|-----------------------------------------|---------------------|
-| M_LD_GATEWAY_AUTH__KEY  | `rootacc.keyid:0gcsqgsib3dqebaquaa4gna` | Root API access key |
-| M_LD_GATEWAY_GATEWAY    | `my-imac.local`                         | Deployed domain name |
-| M_LD_GATEWAY_DATA_PATH  | `./local/edge/gw/data`                  | Path for data       |
-
-The root API access key must be of the form `rootacc.keyid:secret`, where `rootacc` and `keyid` are at least 5 characters of lowercase text. The `rootacc` will be the root account name.
-
-The deployed domain name can be anything if the gateway is local (will be used in future).
-
-The data path can be omitted, in which case a local path will be used in an OS-specific application data area.
+<pre></pre>
+<!--suppress HtmlDeprecatedAttribute -->
+<p align="center">
+  <a href="https://m-ld.org/">
+    <picture>
+      <!--suppress HtmlUnknownTarget -->
+      <source media="(prefers-color-scheme: light)" srcset="https://m-ld.org/m-ld.svg"/>
+      <!--suppress HtmlUnknownTarget -->
+      <source media="(prefers-color-scheme: dark)" srcset="https://m-ld.org/m-ld.inverse.svg"/>
+      <img alt="m-ld" src="https://m-ld.org/m-ld.svg" width="300em" />
+    </picture>
+  </a>
+</p>
+<pre></pre>
+
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/m-ld/m-ld-gateway/node.js.yml?branch=main)](https://github.com/m-ld/m-ld-js/actions)
+[![Gitter](https://img.shields.io/gitter/room/m-ld/community)](https://gitter.im/m-ld/community)
+[![GitHub Discussions](https://img.shields.io/github/discussions/m-ld/m-ld-spec)](https://github.com/m-ld/m-ld-spec/discussions)
 
-For convenience these variables can be specified in a `.env` file in the working directory.
-
-```shell
-npm run start -- --genesis true
-```
-
-The `genesis` flag indicates that this is the first gateway of a potential cluster and must be included for the first startup.
-
-## API getting started guide
-
-A new domain can be created with:
-```
-PUT http://localhost:8080/api/v1/domain/rootacc/t1
-Authorization: Basic rootacc rootacc.keyid:0gcsqgsib3dqebaquaa4gna
-```
-This creates the domain `t1` in the root account. Domain names must be composed only of lowercase letters, numbers, hyphens `-` and underscores `_`.
-
-Some data can be added to the domain with:
-```
-POST http://localhost:8080/api/v1/domain/rootacc/t1/state
-Authorization: Basic rootacc rootacc.keyid:0gcsqgsib3dqebaquaa4gna
-Content-Type: application/json
+# m-ld Gateway
 
-{
-  "@id": "Client-0005",
-  "company_name": "The Flintstones"
-}
-```
+The Gateway is an open source service that provides secure message delivery
+and durable storage of data, for collaborative apps using [**m-ld**](https://m-ld.org/).
 
-All data in the domain can be queried with:
-```
-GET http://localhost:8080/api/v1/domain/rootacc/t1/state?q=%7B%22%40describe%22%3A%22%3Fid%22%2C%22%40where%22%3A%7B%22%40id%22%3A%22%3Fid%22%7D%7D
-Authorization: Basic rootacc rootacc.keyid:0gcsqgsib3dqebaquaa4gna
-Content-Type: application/json
-```
+It can be used as:
+- 📨 A **message relay server**, so apps don't have to deploy a message broker or other pub-sub system.
+- 🗄 A **backup data store** for **m-ld** domains, so an app doesn't have to provide durable persistence of its own.
+- 📠 A **"sidecar" container** of **m-ld** domains for server-based environments which not have a native **m-ld** engine.
+- 🧱 A building block for **custom gateway services** dedicated to specific apps.
 
-Note that the query string includes the URL-encoded json-rql query, for example the describe-all query:
-```json
-{
-  "@describe": "?id",
-  "@where": {
-    "@id": "?id"
-  }
-}
-```
+[Let's get started.](doc/getting-started.md)

architecture/api/clone/README.md

@@ -1,3 +1,9 @@
+# clone API
+
+The "clone API" allows the Gateway to act as a pseudo-local clone on platforms for which a clone engine does not exist, or for an app that does not want to embed the clone in-process. In this capacity, the Gateway is providing a "synchronous" API to one or more of its managed clones, which in other circumstances are only used for domain backup.
+
+This usage pattern may require close collaboration between the app service tier and the Gateway, with the former able to hold open clone state, in the same way that a clone engine can normally do.
+
 ## requirements
 
 ### app simplicity

architecture/api/clone/http/1-basic-write.seq.puml

@@ -17,7 +17,7 @@ return 201 Created ETag: "1" Location: \~/state?lock {Update 1}
 app -> app: process\nUpdate 1
 app -> gw ++: DELETE \~/state?lock If-Match: "1"
 note left
-Update deletion is //not//
+Lock deletion is //not//
 like ACID commit –
 operation has already
 been sent

architecture/api/domain/README.md

@@ -0,0 +1,3 @@
+# domain API
+
+The domain API sets up and manages **m-ld** domains belonging to an account.

architecture/api/domain/account-domain.seq.puml

@@ -0,0 +1,32 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+hide footbox
+
+title App with Gateway account
+
+participant "App\nClient" as client
+participant "App Service\nor lambda" as service
+
+service -> Gateway: PUT /domain/<<account>>/<<name>> ""{authKey}""
+return config for new clones
+note left
+<code>
+{
+  @domain:"<<name>>.<<account>>.<<hostname>>",
+  genesis:true,
+  io
+}
+</code>
+end note
+note right
+if backup clone
+or domain exists,
+genesis is false
+end note
+client <--> service: Authenticate user (or anon)
+service -> service: Create client JWT,\nsign with authKey
+service -> client: ""{config, jwt}""
+client -> client ++: Create clone
+client <--> Gateway: socket.io remotes ""{jwt}""
+
+@enduml