@valos/authority-spindle is a perspire worker plugin that implements a valosp: scheme authority as a set of @valos/web-spindle routes.

This document is part of the spindle workspace @valos/authority-spindle (of domain @valos/kernel) which has the description: `ValOS authority web route projectors spindle`.

Edit me - this is the first payload chapter. Abstract and SOTD are essential ReSpec boilerplate

See ReVDoc tutorial for instructions on how to write revdoc source documents.

See also ReVdoc specification and VDoc specification for reference documentation.

Goal is to create and populate a directory as an npm workspace so that executing vlm perspire in it will launch a https server as a node process. node and npm (or yarn) are required as global CLI dependencies.

Additionally, the valos manager tool vlm and the @valos/kernel domain need to be installed globally:

sudo npm install -g valma @valos/kernel

Once installed, create a new directory (example directory below is "taur") and start the interactive session to initialize the workspace:

vlm init

We will use this tool to create a worker workspace without a domain and with @valos/web-spindle and @valos/authority-spindle toolsets.

? Set 'vault' as the valos.type (workspace is outside a vault)? (y/N)

No

After answering, vlm will echo the internal commands it performs like so:

[1] >> [2] vlm .configure/.valos-stanza

[2] >> [3] vlm '.select/.domain/**/*' --show-name --show-description

[2] << [3] vlm '.select/.domain/**/*': [{"...":{"columns":[["name",{"text...

The echos are omitted for the rest of this guide. Now let's choose no domain and type to be worker.

? Choose a package.json:valos.domain for the new workspace

❯ <no domain> - <this workspace is not part of a domain>

? Choose a package.json:valos.type for the new workspace

❯ worker - Execute perspire gateway as a Node.js process in this workspace

? Confirm package.json:valos.type choice: 'worker'? (Y/n)

Yes

At this point vlm init asks to delegate package.json initialization to yarn init . We accept defaults if available and give sane values otherwise.

? Initialize package.json with 'yarn init'?

❯ Initialize

yarn init v1.21.1

question name (taur-worker):

question version (0.1.0): 0.1.0

question description: Test authority

question entry point (index.js):

question repository url:

question author: Iridian

question license (MIT):

question private (true):

Verify that the domain @valos/kernel is visible as it is the origin of @valos/web-spindle and @valos/authority-spindle toolsets (among other things). We don't need to add other domains, so we bypass adding them.

[1] init informs: Visible domains:

package |version |pool

-------------|-------------------|------

@valos/kernel|0.37.0-prerelease.0|global

? yarn add more domains as devDependencies directly to this workspace?

❯ Bypass

? Commit package.json valos stanza: {"type":"worker","domain":""}?

❯ Commit

At this point vlm init makes the first of several calls to yarn init . These separate calls are necessary as they bring in initialization and configuration code for subsequent stages.

[1] >> [4] vlm @ yarn add --dev @valos/type-worker@>=0.37.0-prerelease.0

yarn add v1.21.1

success Saved lockfile.

success Saved 224 new dependencies.

info Direct dependencies

└─ @valos/type-worker@0.37.0-prerelease.0

info All dependencies

└─ ...

Done in 38.60s.

At this point the init is complete and we proceed to configuring the workspace. The command vlm configure --reconfigure can always be manually re-executed from the CLI if something goes wrong after this point.

? Configure workspace with 'vlm configure --reconfigure'?

❯ Configure

Leave service chronicle URI empty. The basic authority setup does not involve any custom service logic.

? The service chronicle URI

Always select copy-templates-files when given the option

? Pick tools selection choices for the toolset '@valos/type-worker'

◉ copy-template-files - Copy toolset template files to the workspace

Now we get to select the toolsets we want. We need to manually install web-spindle only first as authority-spindle depends on it (and unfortunately automated dependency ordering is not implemented yet)

? Pick toolsets selection choices for the workspace

◯ @valos/authority-spindle - Host a standalone authority using web-spindle route projectors

◉ @valos/web-spindle - Project http/s requests to valospace-fabric via a gateway plugin

◯ @valos/toolset-revealer - Run 'vlm rouse-revealer' to serve local inspire sites with webpack-dev-server

◯ @valos/type-toolset - Make current workspace selectable as a toolset for other workspaces

[13] >> [18] vlm @ yarn add --dev @valos/web-spindle@>=0.37.0-prerelease.0

yarn add v1.21.1

Done in 12.25s.

We configure the web-spindle to have SSL enabled at localhost port 5443 and choose to have openssl to create insecure self-signed certificates for testing our authority.

? Enable SSL

True

? The port the Web API listens.

5443

? The local address the Web API is bound to.

localhost

? Pick tools selection choices for the toolset '@valos/web-spindle'

◉ copy-template-files - Copy toolset template files to the workspace

? Use 'openssl' to create insecure self-signed placeholder certificates?

Yes

[14] >> [19] vlm @ openssl req -x509 -newkey=rsa:4096 -keyout=env/local-authority.key.pem -out=env/local-authority.crt -days=7300 -nodes -subj=/CN=localhost

key |value

-------|-----

success|true

At this point the init completes for the first time. We still need to select the authority-spindle, so we re-execute configure:

vlm configure

These two copy-template-files are redundant

? Pick tools selection choices for the toolset '@valos/type-worker'

◉ copy-template-files

? Pick tools selection choices for the toolset '@valos/web-spindle'

◉ copy-template-files

Finally we get to select the authority-spindle toolset also.

? Pick toolsets selection choices for the workspace

◉ @valos/authority-spindle - Host a standalone authority using web-spindle route projectors

◉ @valos/web-spindle - Project http/s requests to valospace-fabric via a gateway plugin

◯ @valos/toolset-revealer - Run 'vlm rouse-revealer' to serve local inspire sites with webpack-dev-server

◯ @valos/type-toolset - Make current workspace selectable as a toolset for other workspaces

Let's use the default URI for the actual authority URI. While the port and host should match the ones used by web-spindle, the hierarchy part can be anything. taur is only inferred from the package name.

? The authority valosp URI.

valosp://localhost:5443/taur/

? Short description for the public authority config

Test authority

? Pick tools selection choices for the toolset '@valos/authority-spindle'

◉ copy-template-files

key |value

-------|-----

success|true

The setup of the authority is now complete. Let's start the perspire worker.

vlm perspire

If everything runs smoothly, we should have 15 routes on two prefixes:

[1] perspire informs: MapperService(MapperService$.1): listening @ { address: '127.0.0.1', family: 'IPv4', port: 5443 } prepared prefixes:

/: taur-worker@0.1.0 - openapi Example Title

valosp://localhost:5443/taur/: taur-worker@0.1.0 - Test authority