Merge pull request #17 from m-ld/perf-test

#15: Initial benchmarking, in sim folder

.gitignore

@@ -4,4 +4,5 @@ node_modules/
 local/
 _site/
 *.private.env.json
-*.env
+*.env
+.clinic

doc/README.md

@@ -4,6 +4,6 @@ This `doc` folder forms the basis of the **m-ld** Gateway public documentation.
 
 The folder is built using Eleventy to the `_site` folder, and then served by the running Gateway in the class `GatewayWebsite`.
 
-cURLs in markdown files are generated from the corresponding .http files using `http-client.env.json`, please keep them in sync.
+cURLs in markdown files are generated from the corresponding .http files in the `http` folder using `http-client.env.json`, please keep them in sync.
 
 All files are treated as Liquid templates. They are processed once by Eleventy, and then _again_ by the gateway – hence the occasional use of double-encoded template tags such as `{{ '{{ origin }}' }}`.

doc/_data/eleventyComputed.cjs

@@ -0,0 +1,4 @@
+/**
+ * @see https://www.11ty.dev/docs/data-computed/#advanced-details
+ */
+module.exports = require('../_includes/http/http-client.env.json').doc;

doc/_includes/http/accounts/activation.http

@@ -0,0 +1,5 @@
+POST {{origin}}/api/v1/user/{{account}}/activation
+Accept: application/json
+Content-Type: application/json
+
+{ "email": "{{email}}" }

doc/_includes/http/accounts/insert-remotes-auth.http

@@ -0,0 +1,6 @@
+PATCH {{origin}}/api/v1/user/{{account}}
+Authorization: Basic {{digest}}
+Accept: application/json
+Content-Type: application/json
+
+{ "@insert": { "remotesAuth": "{{remotesAuth}}" } }

doc/_includes/http/accounts/key-using-activation.http

@@ -0,0 +1,4 @@
+POST {{origin}}/api/v1/user/{{account}}/key
+Authorization: Bearer {{jwe}}
+X-Activation-Code: {{activation}}
+Accept: application/json

doc/_includes/http/accounts/key-using-root.http

@@ -0,0 +1,3 @@
+POST {{origin}}/api/v1/user/{{account}}/key
+Authorization: Basic {{rootAccount}} {{rootKey}}
+Accept: application/json

doc/_includes/http/clone-api/async-read.http

@@ -0,0 +1,5 @@
+GET {{origin}}/api/v1/domain/{{account}}/{{subdomain}}/state
+Authorization: Basic {{digest}}
+Accept: application/json
+[QueryStringParams]
+q: {{read}} # to be URL-encoded as the query string

doc/_includes/http/clone-api/async-write.http

@@ -0,0 +1,8 @@
+POST {{origin}}/api/v1/domain/{{account}}/{{subdomain}}/state
+Authorization: Basic {{digest}}
+Content-Type: application/json
+
+{
+  "@id": "Client-0005",
+  "company_name": "The Flintstones"
+}

doc/_includes/http/http-client.env.json

@@ -0,0 +1,29 @@
+{
+  "local": {
+    "origin": "http://localhost:3000",
+    "account": "my-account",
+    "remotesAuth": "anon",
+    "subdomain": "my-subdomain",
+    "read": "{\"@describe\":\"?id\",\"@where\":{\"@id\":\"?id\"}}"
+  },
+  "doc": {
+    "origin": "{{ '{{ origin }}' }}",
+    "rootAccount": "{{ '{{ root }}' }}",
+    "rootKey": "≪root key≫",
+    "account": "≪account name≫",
+    "accountKey": "≪account key≫",
+    "email": "≪user email≫",
+    "jwe": "≪jwe≫",
+    "activation": "≪emailed activation code≫",
+    "remotesAuth": "≪remotes auth option≫",
+    "subdomain": "≪subdomain≫",
+    "read": "{\"@describe\":\"?id\",\"@where\":{\"@id\":\"?id\"}}",
+    "digest": "≪base64(≪account name≫:≪account key≫)≫"
+  },
+  "prod": {
+    "origin": "https://gw.m-ld.org",
+    "account": "public",
+    "remotesAuth": "anon",
+    "read": "{\"@describe\":\"?id\",\"@where\":{\"@id\":\"?id\"}}"
+  }
+}

doc/_includes/http/named-subdomains/create.http

@@ -0,0 +1,3 @@
+PUT {{origin}}/api/v1/domain/{{account}}/{{subdomain}}
+Accept: application/json
+Authorization: Basic {{digest}}

doc/_includes/http/uuid-subdomains/generate.http

@@ -0,0 +1,2 @@
+POST {{origin}}/api/v1/domain/{{account}}
+Accept: application/json

doc/_includes/http/uuid-subdomains/setup.http

@@ -0,0 +1,5 @@
+PATCH {{origin}}/api/v1/user/{{account}}
+Authorization: Basic {{digest}}
+Content-Type: application/json
+
+{ "@insert": { "naming": "uuid" } }

doc/accounts.md

@@ -16,11 +16,8 @@ Account names (`≪account≫` in the below) must be composed only of **lowercas
 
 First, request an activation code with an email address.
 
-```bash
-curl -X POST --location "{{ '{{ origin }}' }}/api/v1/user/≪account≫/activation" \
-    -H "Accept: application/json" \
-    -H "Content-Type: application/json" \
-    -d "{ \"email\": \"≪email≫\" }"
+```
+{% include 'http/accounts/activation.http' %}
 ```
 
 The body of the response will have the form `{ "jwe": "≪base64Binary≫" }`. The value of the `jwe` key will be used in the next step.
@@ -29,11 +26,8 @@ An email will be sent to the given address, containing a six-digit activation co
 
 The account can then be created with another HTTP request:
 
-```bash
-curl -X POST --location "{{ '{{ origin }}' }}/api/v1/user/≪account≫/key" \
-    -H "Authorization: Bearer ≪jwe≫" \
-    -H "X-Activation-Code: ≪emailed activation code≫" \
-    -H "Accept: application/json"
+```
+{% include 'http/accounts/key-using-activation.http' %}
 ```
 
 The body of the response will be of the form `{ "auth": { "key": "≪my-key≫" } }`, where `≪my-key≫` is the new account's authorisation key.
@@ -42,10 +36,8 @@ The body of the response will be of the form `{ "auth": { "key": "≪my-key≫"
 
 The Gateway root account can be used to create any user account directly.
 
-```bash
-curl -X POST --location "{{ '{{ origin }}' }}/api/v1/user/≪account name≫/key" \
-    -H "Accept: application/json" \
-    --basic --user ≪root≫:≪root key≫
+```
+{% include 'http/accounts/key-using-root.http' %}
 ```
 
 The body of the response will be of the form `{ "auth": { "key": "≪my-key≫" } }`, where `≪my-key≫` is the new account's authorisation key.
@@ -59,12 +51,8 @@ When [connecting to subdomains](clone-subdomain), clients may need to provide au
 
 The required option can be set as follows.
 
-```bash
-curl -X PATCH --location "{{ '{{ origin }}' }}/api/v1/user/≪account name≫" \
-    -H "Accept: application/json" \
-    -H "Content-Type: application/json" \
-    -d "{ \"@insert\": { \"remotesAuth\": \"≪remotes auth option≫\" } }" \
-    --basic --user ≪account name≫:≪account key≫
+```
+{% include 'http/accounts/insert-remotes-auth.http' %}
 ```
 
 You can also remove a previously-set option by including a delete clause, for example: `{ "@delete": { "remotesAuth": "jwt" } }`.

doc/clone-api.md

@@ -15,30 +15,14 @@ The 'clone' (noun, not verb) API is provided for such a client to access the dat
 
 Some data can be added to the domain with:
 
-```bash
-curl -X POST --location "{{ '{{ origin }}' }}/api/v1/domain/≪account name≫/≪subdomain≫/state" \
-    -H "Content-Type: application/json" \
-    -d "{
-          \"@id\": \"Client-0005\",
-          \"company_name\": \"The Flintstones\"
-        }" \
-    --basic --user ≪account name≫:≪account key≫
+```
+{% include 'http/clone-api/async-write.http' %}
 ```
 
 Data in the domain can be queried with:
 
-```bash
-curl -X GET --location "{{ '{{ origin }}' }}/api/v1/domain/≪account name≫/≪subdomain≫/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" \
-    -H "Accept: application/json" \
-    --basic --user ≪account name≫:≪account key≫
 ```
-
-Note that the query string includes the URL-encoded json-rql query, for example the describe-all query:
-```json
-{
-  "@describe": "?id",
-  "@where": {
-    "@id": "?id"
-  }
-}
+{% include 'http/clone-api/async-read.http' %}
 ```
+
+This example query describes all the subjects in the domain, which is to say, their top-level properties.

doc/named-subdomains.md

@@ -12,10 +12,8 @@ To use named subdomains, you first need [an account](accounts). (If your Gateway
 
 A new domain can be created with:
 
-```bash
-curl -X PUT --location "{{ '{{ origin }}' }}/api/v1/domain/≪account name≫/≪subdomain≫" \
-    -H "Accept: application/json" \
-    --basic --user ≪account name≫:≪account key≫
+```
+{% include 'http/named-subdomains/create.http' %}
 ```
 
 This creates the domain `≪subdomain≫` in the account. Domain names must be composed only of **lowercase** letters, numbers, hyphens `-` and underscores `_`.

doc/self-host.md

@@ -5,7 +5,7 @@ title: self-hosting setup
 # Hosting a Gateway
 
 ## build
-```bash
+```
 npm run build
 ```
 
@@ -32,7 +32,7 @@ The data path can be omitted, in which case a local path will be used in an OS-s
 
 For convenience these variables can be specified in a `.env` file in the working directory.
 
-```bash
+```
 npm run start -- --genesis true
 ```
 

doc/uuid-subdomains.md

@@ -15,11 +15,8 @@ To use UUID subdomains, you first need [an account](accounts).
 
 By default, a Gateway account only allows [named subdomains](named-subdomains). To enable UUID subdomains for an account:
 
-```bash
-curl -X PATCH --location "{{ '{{ origin }}' }}/api/v1/user/≪account name≫" \
-    -H "Content-Type: application/json" \
-    -d "{ \"@insert\": { \"naming\": \"uuid\" } }" \
-    --basic --user ≪account name≫:≪account key≫
+```
+{% include 'http/uuid-subdomains/setup.http' %}
 ```
 
 ## creating a UUID domain
@@ -30,9 +27,8 @@ The domain name must take the form `≪uuid≫.my-account.my-gateway`, where `
 
 For convenience, you can request suitable configuration for a new UUID subdomain from the Gateway, as follows. Note that this does not create anything new on the Gateway, but it will generate a compliant UUID for the domain name.
 
-```bash
-curl -X POST --location "{{ '{{ origin }}' }}/api/v1/domain/≪account name≫" \
-    -H "Accept: application/json"
+```
+{% include 'http/uuid-subdomains/generate.http' %}
 ```
 
 With the resultant configuration (or one you have created from scratch) you can [clone the subdomain](clone-subdomain).

eleventy.config.cjs

@@ -2,6 +2,9 @@ const { default11tyConfig, packageDir } = require('@m-ld/io-web-build');
 const syntaxHighlight = require('@11ty/eleventy-plugin-syntaxhighlight');
 const { join } = require('path');
 
+/**
+ * @param {import('@11ty/eleventy').UserConfig} eleventy
+ */
 module.exports = function (eleventy) {
   eleventy.ignores.add('doc/README.md');
   eleventy.addPlugin(syntaxHighlight);