This Month in Reactive Graph

October 2024 in Reactive Graph

Andreas Schaeffer — Thu, 31 Oct 2024 00:00:00 GMT

{% import "header.tera" as header %} {% import "footer.tera" as footer %}

October 2024 was a very productive month for Reactive Graph. We focused on Continuous Integration and Delivery. The results are impressive:

Self Info

The Reactive Graph binary can now output information about itself. This includes the version number, the rust compiler version, the rust compiler channel, the target triple, and the git commit hash.

$ reactive-graph info

+---------+--------------------------+---------+------------------------------------------+---------------+---------------+
| version | target_triple            | git_tag | git_commit                               | rustc_channel | rustc_version |
+---------+--------------------------+---------+------------------------------------------+---------------+---------------+
| 0.10.0  | x86_64-unknown-linux-gnu |         | 7d8b37cf5549a12a4da5feff5184778d25110e62 | stable        | 1.82.0        |
+---------+--------------------------+---------+------------------------------------------+---------------+---------------+

$ reactive-graph info --output-format=json

[
  {
    "version": "0.10.0",
    "target_triple": "x86_64-unknown-linux-gnu",
    "git_tag": "",
    "git_commit": "7d8b37cf5549a12a4da5feff5184778d25110e62",
    "rustc_channel": "stable",
    "rustc_version": "1.82.0"
  }
]

Self Updater

What is probably most interesting for end users is that Reactive Graph now has the ability to update itself. Thanks to the Rust self_update library, implementation was relatively easy.

A new command has been implemented with which you can process the update:

$ reactive-graph update --help

Update the Reactive Graph binary

Usage: reactive-graph update [OPTIONS] [COMMAND]

Commands:
  info  Shows information about the selected release
  list  Lists the releases
  help  Print this message or the help of the given subcommand(s)

Options:
  -n, --nightly                 Updates to the nightly release
  -l, --latest                  Updates to the latest release. Currently, the latest release is the nightly release. This will change in the future
  -c, --current                 Updates to the current release
  -v, --version        Updates to a specific version
      --hide-download-progress  Hides the download progress
      --hide-output             Hides the output
  -q, --quiet                   Hides the download progress and the output
  -y, --no-confirm              Don’t ask
  -h, --help                    Print help

You can use the subcommand info to find out which version would be updated to.

$ reactive-graph update info

+---------------+---------+------------+------------------------------------------+------------------------------------------+
| Release Name  | Version | Date       | Asset Name                               | Download URL                             |
+---------------+---------+------------+------------------------------------------+------------------------------------------+
| Nightly Build | nightly | 2024-10-29 | reactive-graph-nightly-x86_64-unknown-li | https://api.github.com/repos/reactive-gr |
|               |         |            | nux-gnu.tar.gz                           | aph/reactive-graph/releases/assets/20270 |
|               |         |            |                                          | 9875                                     |
+---------------+---------+------------+------------------------------------------+------------------------------------------+

As you can see, the nightly version would be installed. It also shows the name of the asset to be downloaded and from which URL the download would occur.

If you finally want to carry out the update, you can do this with the command:

$ reactive-graph update

Checking target-arch... x86_64-unknown-linux-gnu
Checking current version... v0.10.0
Looking for tag: nightly

reactive-graph release status:
  * Current exe: "/home/user/.cargo/bin/reactive-graph"
  * New exe release: "reactive-graph-nightly-x86_64-unknown-linux-gnu.tar.gz"
  * New exe download url: "https://api.github.com/repos/reactive-graph/reactive-graph/releases/assets/202709875"

The new release will be downloaded/extracted and the existing binary will be replaced.
Do you want to continue? [Y/n] Y
Downloading...
[00:00:02] [====================>-------------------] 19.41 MiB/37.41 MiB (3s)  
Extracting archive... Done
Replacing binary file... Done
Successfully updated to version: nightly

You can use the --no-confirm option to ensure that the update is carried out without query.

Specify the version to update to

| Option | Description | |----------------------------|-----------------------------------------------------------------------------------------------------------------------| | --latest | Updates to the latest release. Currently, the latest release is the nightly release. This will change in the future. | | --nightly | Updates to the nightly release | | --version 0.10.0-alpha-2 | Updates to a specific version |

List of releases

You can find out which releases are available from the shell. These version numbers can be used with the --version option to install a specific version of Reactive Graph.

$ reactive-graph update list

+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| Release Name    | Version        | Date       | Asset Name                               | Download URL                             |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| Nightly Build   | nightly        | 2024-10-29 | reactive-graph-nightly-x86_64-unknown-li | https://api.github.com/repos/reactive-gr |
|                 |                |            | nux-gnu.tar.gz                           | aph/reactive-graph/releases/assets/20270 |
|                 |                |            |                                          | 9875                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.10.0-alpha-2 | 0.10.0-alpha-2 | 2024-10-27 | reactive-graph-v0.10.0-alpha-2-x86_64-un | https://api.github.com/repos/reactive-gr |
|                 |                |            | known-linux-gnu.tar.gz                   | aph/reactive-graph/releases/assets/20211 |
|                 |                |            |                                          | 3533                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.10.0-alpha-1 | 0.10.0-alpha-1 | 2024-10-20 | reactive-graph-v0.10.0-alpha-1-x86_64-un | https://api.github.com/repos/reactive-gr |
|                 |                |            | known-linux-gnu.tar.gz                   | aph/reactive-graph/releases/assets/20031 |
|                 |                |            |                                          | 6307                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.9.1-25       | 0.9.1-25       | 2023-07-20 | inexor-rgf-rt-standalone-x86_64-unknown- | https://api.github.com/repos/reactive-gr |
|                 |                |            | linux-gnu.tar.gz                         | aph/reactive-graph/releases/assets/11789 |
|                 |                |            |                                          | 6809                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.9.1-22       | 0.9.1-22       | 2023-05-12 | inexor-rgf-rt-standalone-x86_64-unknown- | https://api.github.com/repos/reactive-gr |
|                 |                |            | linux-gnu.tar.gz                         | aph/reactive-graph/releases/assets/10790 |
|                 |                |            |                                          | 4471                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
|                 | 0.9.1-3        | 2023-05-07 | Not available                            |                                          |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.9.1          | 0.9.1          | 2023-05-01 | inexor-rgf-rt-standalone-x86_64-unknown- | https://api.github.com/repos/reactive-gr |
|                 |                |            | linux-gnu.tar.gz                         | aph/reactive-graph/releases/assets/10621 |
|                 |                |            |                                          | 6527                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.9.0-15       | 0.9.0-15       | 2023-05-01 | inexor-rgf-rt-standalone-x86_64-unknown- | https://api.github.com/repos/reactive-gr |
|                 |                |            | linux-gnu.tar.gz                         | aph/reactive-graph/releases/assets/10621 |
|                 |                |            |                                          | 3683                                     |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+
| v0.2.1-alpha    | 0.2.1-alpha    | 2021-08-29 | Not available                            |                                          |
+-----------------+----------------+------------+------------------------------------------+------------------------------------------+

Improved Release Process and Distribution Channels

In order for the self-updater to be useful, the release and distribution process needed to be improved. With the improved release process, different types of releases are now produced and distributed via a number of channels:

| Channel | Description | Status | |------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| | Source | The source code is available for download for each release. | Done | | Binary Packages | Binary packages are produced for each release. The binary distributions can be downloaded manually. See below for expanded support of supported platforms. | Done | | Self Updater | The self-updater is based on the binary distributions. | Done | | Debian Packages | Debian packages are produced for each release. The Debian packages can be downloaded manually. | Done | | Docker | Docker images are produced for each release. The Docker images are uploaded to ghcr.io and can be obtained from there. | Done | | Website Download | In the future, every release should be available for download via the website. | Planned | | crates.io | In the future, every regular release should be published on crates.io. | Planned | | APT | In the future, each release’s Debian packages should be available via an APT repository. | Planned |

In the following graphic you can see the process of a release.

A submitted pull request can only be merged if a number of prerequisites are met:

The code compiles under Rust Stable and Rust Nightly.
The code compiles on Linux, Windows and MacOSx.
Code Formatting is equivalent to automatic formatting.
The minimum Rust compiler version has not increased.
There are no warnings from the linter.

After the merge, the checks are also repeated on the main branch and if successful, release builds and Docker builds are triggered.

flowchart LR

A@{ shape: circle, label: "Start" }
PR[Pull Request]
CI[CI Build an <code>main</code> Branch]
Release[Release Build]
DB[Docker Build]
NBin@{ shape: doc, label: "Nightly Binary Package" }
RBin@{ shape: doc, label: "Release Binary Package" }
NDeb@{ shape: doc, label: "Nightly Debian Package" }
RDeb@{ shape: doc, label: "Release Debian Package" }
NDI@{ shape: doc, label: "Nightly Docker Image" }
RDI@{ shape: doc, label: "Release Docker Image" }

A-- created PR -->PR
PR-- merge into main -->CI
CI-- successful -->Release
Release --> NBin
Release-- <code>release tag</code> -->RBin
Release --> NDeb
Release-- <code>release tag</code> -->RDeb
CI-- successful -->DB
CI-- successful -->DB
DB-->NDI
DB-- <code>release tag</code> -->RDI

Nightly Builds

What’s new is that the release process produces nightly builds. This happens with every merge to the main branch. The existing nightly release is updated, the Git tag nightly is moved to the latest commit and finally new binary packages, new Debian packages and new Docker images are produced.

We won’t produce regular releases often in the near future because we can’t guarantee compatibility yet. Instead, the constantly updated nightly releases are available.


    
    Warning!

At this point, the software is not yet feature-complete and essential features are still missing, such as the flow editor, the persistence of the type system and instance system, and an authorization layer.

Platform Support

Rust is a compiled language. If the software should be able to run on different systems, we should ensure this during development. Reactive Graph has various application areas that go beyond the classic desktop system. For example, Reactive-Graph for smart home applications should run on a Raspberry Pi. This has an ARM processor.

Fortunately, Rust supports cross-compiling for other CPU and OS platforms. This month we added some new CPU architectures) to continuous integration and are producing binary packages and Debian packages for all of these platforms.

This is the updated list of supported platforms:

| target | New | Description | Tier | |--------------------------------|-----|---------------------------------------------------|------| | x86_64-unknown-linux-gnu | | 64-bit Linux (kernel 3.2+, glibc 2.17+) | 1 | | x86_64-pc-windows-msvc | | 64-bit MSVC (Windows 10+, Windows Server 2016+) | 1 | | aarch64-apple-darwin | | ARM64 macOS (11.0+, Big Sur+) | 1 | | x86_64-apple-darwin | | 64-bit macOS (10.12+, Sierra+) | 1 | | universal-apple-darwin | | | | | aarch64-unknown-linux-gnu | | ARM64 Linux (kernel 4.1, glibc 2.17+) | 1 | | aarch64-unknown-linux-musl | Yes | ARM64 Linux with musl 1.2.3 | 2 | | armv7-unknown-linux-gnueabihf | Yes | Armv7-A Linux, hardfloat (kernel 3.2, glibc 2.17) | 2 | | armv7-unknown-linux-musleabihf | Yes | Armv7-A Linux, hardfloat (kernel 3.2, glibc 2.17) | 2 | | i686-unknown-linux-gnu | Yes | 32-bit Linux (kernel 3.2+, glibc 2.17+) | 1 | | powerpc-unknown-linux-gnu | Yes | PowerPC Linux (kernel 3.2, glibc 2.17) | 2 | | powerpc64-unknown-linux-gnu | Yes | PPC64 Linux (kernel 3.2, glibc 2.17) | 2 | | powerpc64le-unknown-linux-gnu | Yes | PPC64LE Linux (kernel 3.10, glibc 2.17) | 2 | | riscv64gc-unknown-linux-gnu | Yes | RISC-V Linux (kernel 4.20, glibc 2.29) | 2 | | x86_64-pc-windows-gnu | Yes | 64-bit MinGW (Windows 10+, Windows Server 2016+) | 1 | | x86_64-unknown-linux-musl | Yes | 64-bit Linux with musl 1.2.3 | 2 |

Docker

Furthermore, the first Docker images are now available for both regular releases and as nightly builds. The Docker images are available via GitHub Packages (i.e. via ghcr.io).

Run

$ docker run -d -p 31415:31415 --name reactive-graph ghcr.io/reactive-graph/reactive-graph:latest

85b3a6868f4bc91e336fb1033d349b70c48b207f0122b5284f77002bae2894c4

$ docker ps

CONTAINER ID   IMAGE                                          COMMAND              CREATED              STATUS              PORTS                                           NAMES                                                                                                                                                   │
85b3a6868f4b   ghcr.io/reactive-graph/reactive-graph:latest   "./reactive-graph"   13 seconds ago       Up 12 seconds       0.0.0.0:31415->31415/tcp, :::31415->31415/tcp   reactive-graph

$ docker stop 85b3a6868f4b

85b3a6868f4b

Multiple Instances

It is possible to run multiple instances of Reactive Graph in parallel. All you have to do is bind another port on the host system.

$ docker run -d -p 31416:31415 --name reactive-graph-2 ghcr.io/reactive-graph/reactive-graph:latest

7f689869a76df29179478d74872c6d6b4c9d144415bd3fc9d16225ecf8ae8f62

$ docker ps

CONTAINER ID   IMAGE                                          COMMAND              CREATED              STATUS              PORTS                                           NAMES
85b3a6868f4b   ghcr.io/reactive-graph/reactive-graph:latest   "./reactive-graph"   13 seconds ago       Up 12 seconds       0.0.0.0:31415->31415/tcp, :::31415->31415/tcp   reactive-graph
7f689869a76d   ghcr.io/reactive-graph/reactive-graph:latest   "./reactive-graph"   53 seconds ago       Up 52 seconds       0.0.0.0:31417->31415/tcp, :::31417->31415/tcp   reactive-graph-2

Dockerfile

FROM alpine as reactive-graph
RUN apk add zsh nano curl
WORKDIR /opt/reactive-graph
COPY --from=builder --chown=reactive-graph:reactive-graph /app/target/release/reactive-graph .
RUN addgroup --gid 1000 reactive-graph
RUN adduser -h /opt/reactive-graph -s /bin/bash -G reactive-graph -u 1000 -D reactive-graph
USER reactive-graph
RUN ./reactive-graph instances init --uid 1000 --gid 1000
RUN ./reactive-graph instances config graphql --hostname "0.0.0.0" --secure true
RUN ./reactive-graph instances config instance --instance-name "Reactive Graph" --instance-description "Docker"
ENV PATH="$PATH:/opt/reactive-graph"
EXPOSE 31415

Debian Packages

More platforms are now supported. Debian packages are also provided for regular releases and as nightly builds. The new folder structure is now taken into account.

| Debian Package | Debian Target | Rust Target | |-------------------------------------------|---------------|-------------------------------| | reactive-graph0.10.0-nightlyamd64.deb | amd64 | x86_64-unknown-linux-gnu | | reactive-graph0.10.0-nightlyarm64.deb | arm64 | aarch64-unknown-linux-gnu | | reactive-graph0.10.0-nightlyarmhf.deb | armhf | armv7-unknown-linux-gnueabihf | | reactive-graph0.10.0-nightlyi386.deb | i386 | i686-unknown-linux-gnu | | reactive-graph0.10.0-nightlypowerpc.deb | powerpc | powerpc-unknown-linux-gnu | | reactive-graph0.10.0-nightlyppc64.deb | ppc64 | powerpc-unknown-linux-gnu | | reactive-graph0.10.0-nightlyppc64el.deb | ppc64el | powerpc64le-unknown-linux-gnu | | reactive-graph0.10.0-nightlyriscv64.deb | riscv64 | riscv64gc-unknown-linux-gnu |

CLI Instance Management

Instance Initialization

The Dockerfile benefits from another new feature: The Reactive Graph Binary can now initialize a folder structure for new instances.

$ reactive-graph instances init --uid 1000 --gid 1000

Created ./config
Created ./log
Created ./keys
Created ./plugins/deploy
Created ./plugins/installed
Created ./repositories
Created ./repositories/default/types/components
Created ./repositories/default/types/entities
Created ./repositories/default/types/relations
Created ./repositories/default/types/flows
Created ./repositories/default/instances/entities
Created ./repositories/default/instances/relations
Created ./repositories/default/instances/flows
Wrote file ./config/flow_locations.toml
Wrote file ./config/graphql.toml
Wrote file ./config/instance.toml
Wrote file ./config/logging.toml
Wrote file ./config/plugins.toml
Wrote file ./config/remotes.toml
Created file ./log/reactive-graph.log
Created file ./log/reactive-graph.error.log

Configure Instances via CLI

Another feature is that you can set or overwrite configurations using a command.

$ reactive-graph instances config graphql --hostname "0.0.0.0" --secure true

(no output)

Continuous Integration

Dependabot can automatically merge
Automatic Labeling
Upgraded nightly compiler version to 2024-10-19

Book

Redesigned the book using the design library

{{ footer::print(issuedateprevious="", issuedatenext="2024-09-30") }}

September 2024 in Reactive Graph

Andreas Schaeffer — Mon, 30 Sep 2024 00:00:00 GMT

{% import "header.tera" as header %} {% import "footer.tera" as footer %}

Build

Stable Rust

The biggest news this month is that we got managed to compile Reactive Graph with Stable Rust.

What has changed?

Implemented DashMap as container for subscribers of Stream and removed usage of the unstable feature unsized_tuple_coercion
Inlined implementation of feature path_file_prefix which will be stabilized soon, so that this is not a blocker
Removed usage of the unstable feature test and migrated to criterion (see Benchmarking with Criterion)
Removed usage of the unstable feature register_tool and make tarpaulin work again without this feature
Detect if the compiler is nightly and only if so, make use of the unstable features unboxed_closures and fn_traits

Support for musl builds

We introduced support MUSL builds.

What is musl?

musl is an implementation of the C standard library built on top of the Linux system call API, including interfaces defined in the base language standard, POSIX, and widely agreed-upon extensions. musl is lightweight, fast, simple, free, and strives to be correct in the sense of standards-conformance and safety.

https://musl.libc.org/

Setup and Compile using musl

In order to successfully compile, you also have to install the package musl-tools. For example for Debian / Ubuntu, you can install it like so:

$ apt install musl-tools

Next you have to add the musl target using rustup:

$ rustup target add x86_64-unknown-linux-musl

Finally you can compile reactive-graph for the target x86_64-unknown-linux-musl:

$ cargo build --target x86_64-unknown-linux-musl

rustls

We’ve finished work on replacing OpenSSL with rustls. OpenSSL is no more needed to build Reactive Graph.

Benchmarking with Criterion

Now the benchmark tests are run with criterion (which doesn’t need Nightly Rust). Furthermore, the benchmarks has been moved into its own benches/ folders.

Features of Criterion

Statistics: Statistical analysis detects if, and by how much, performance has changed since the last benchmark run
Charts: Uses gnuplot to generate detailed graphs of benchmark results
Stable-compatible: Benchmark your code without installing nightly Rust

A future task would be to write more benchmark tests and to execute benchmarking in the CI.

Continuous Integration

Upgrade Workflows and Improve CI performance

We’ve upgraded the workflow actions to recent versions. Furthermore, we made some changes to speed up the CI. We’ve merge workflow files and made build jobs and test jobs dependent on the formatting check job and linting jobs. With this change, no build time is wasted if linting and formatting doesn’t meet the requirements. Furthermore, we’re run linting and test suite on Linux GNU and Linux musl for Rust stable and Rust nightly. But we don’t run the complete test suite on Windows and macOS anymore. This is because running the test suite on Windows is 2x slower and on macOS is 6x slower compared to running on Linux. At a later point we may reintroduce a smaller subset of the test suite to run on Windows and macOS.

New Checks

Minimal Supported Rust Version (MSRV)
Dependabot now checks for outdated dependencies
Checks that the CHANGELOG was edited

Command Line Interface

Managing the Instance System

We finished the implementation of managing the instance system via CLI (entity instances and relation instances). Furthermore, the CLI lists the applied components of the reactive instances.

Documented Command Line Interface

The book now contains a section about the Command Line Interface. We’ve added a section about the interactive mode and a section about the command reference. For the command reference we make use of a new option to automatically generate the help in Markdown format:

$ reactive-graph --markdown-help

TODO: Insert output here

Output Format Count

We’ve added a new output format that simply prints the count instead of a table with the results. The purpose of the new feature is similar to count(*) in SQL and is also useful for shell automation.

$ reactive-graph client components list --output-format count
$ reactive-graph client entity-types list --output-format count
$ reactive-graph client relation-types list --output-format count
$ reactive-graph client entity-instances list --output-format count
$ reactive-graph client relation-instances list --output-format count

Examples

Print the count of components

$ reactive-graph client components list --output-format count
34 result(s)

Example: Print the count of entity-instances

$ reactive-graph client entity-instances list --output-format count
1554 result(s)

Example: Print the count of entity-instances that having the component core__action

$ reactive-graph client entity-instances list --components core__action --output-format count
2 result(s)

Output Format HTML

We have added a new option to output the result as HTML table. This applies to all type system and instance system operations.

List types and instances as HTML table

$ reactive-graph client components list --output-format html-table
$ reactive-graph client entity-types list --output-format html-table
$ reactive-graph client relation-types list --output-format html-table
$ reactive-graph client entity-instances list --output-format html-table
$ reactive-graph client relation-instances list --output-format html-table

List all components as HTML table

$ reactive-graph client components list --output-format html-table

 




    namespace
    name
    description
    properties
    extensions




    state
    state_object
    State of type object
    
        
            
            
                name
                data_type
                socket_type
                mutability
            
            
            
            
                state
                Object
                None
                Immutable
            
            
                set_state
                Object
                Input
                Mutable
            
            
        
    
    
    


    value
    value_debugger_trace
    
    
    


    arithmetic
    arithmetic_operation
    Arithmetic operation with one input and one result
    
        
            
            
                name
                data_type
                socket_type
                mutability
            
            
            
            
                result
                Number
                Output
                Immutable
            
            
                lhs
                Number
                Input
                Mutable
            
            
        
    
    
        
            
            
                Namespace
                TypeName
                Description
                Extension
            
            
            
            
                core
                component_category
                
                "math"
            
            
        
    


    base
    named
    The entity or relation has a name.
    
        
            
            
                name
                data_type
                socket_type
                mutability
            
            
            
            
                name
                String
                None
                Mutable
            
            
        
    
    
        
            
            
                Namespace
                TypeName
                Description
                Extension
            
            
            
            
                core
                component_category
                
                "base"
            
            
        
    


    value
    value_object
    Value of type object
    
        
            
            
                name
                data_type
                socket_type
                mutability
            
            
            
            
                value
                Object
                Output
                Mutable
            
            
        
    
    
    


    result
    result_boolean
    The entity returns a boolean
    
        
            
            
                name
                data_type
                socket_type
                mutability
            
            
            
            
                result
                Bool
                Output
                Immutable
            
            
        
    
    
        
            
            
                Namespace
                TypeName
                Description
                Extension
            
            
            
            
                core
                component_category
                
                "result"

Output a single type or a single instance as HTML table

$ reactive-graph client components get   --output-format html-table
$ reactive-graph client entity-types get   --output-format html-table
$ reactive-graph client relation-types get   --output-format html-table
$ reactive-graph client entity-instances get   --output-format html-table
$ reactive-graph client relation-instances get   --output-format html-table

Output a single component as HTML table

$ reactive-graph client components get value value_number --output-format html-table

namespace

name

description

properties

extensions

value

value_number

Value of type number

name	data_type	socket_type	mutability
value	Number	Output	Mutable

Output Format Markdown

Similar to the Output Format HTML, the Output Format Markdown prints the result as Markdown Table.

List types and instances as Markdown table

$ reactive-graph client components list --output-format markdown-table
$ reactive-graph client entity-types list --output-format markdown-table
$ reactive-graph client relation-types list --output-format markdown-table
$ reactive-graph client entity-instances list --output-format markdown-table
$ reactive-graph client relation-instances list --output-format markdown-table

List all components as Markdown table

$ reactive-graph client components list --output-format markdown-table

| namespace | name | description | properties | extensions | |------------|----------------------|---------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | state | stateobject | State of type object |

name	datatype	sockettype	mutability
setstate	Object	Input	Mutable
state	Object	None	Immutable

name	datatype	sockettype	mutability
result	Number	Output	Immutable
lhs	Number	Input	Mutable

Namespace	TypeName	Description	Extension
core	componentcategory		"math"

name	datatype	sockettype	mutability
name	String	None	Mutable

Namespace	TypeName	Description	Extension
core	component_category		"base"

name	datatype	socket_type	mutability
value	Object	Output	Mutable

name	datatype	sockettype	mutability
result	Bool	Output	Immutable

Namespace	TypeName	Description	Extension
core	componentcategory		"result"

Output a single type or a single instance as Markdown table

$ reactive-graph client components get --output-format markdown-table $ reactive-graph client entity-types get --output-format markdown-table $ reactive-graph client relation-types get --output-format markdown-table $ reactive-graph client entity-instances get --output-format markdown-table $ reactive-graph client relation-instances get --output-format markdown-table

Output a single component as Markdown table

$ reactive-graph client components get value value_number --output-format markdown-table

| namespace | name | description | properties | extensions | |-----------|--------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| | value | valuenumber | Value of type number |
name
datatype
socket_type
mutability
value
Number
Output
Mutable
| |

Shell Completions

In order to further improve the user experience with the command line interface we’ve implemented the feature to generate shell completions.

List of Supported Shells

bash

elvish

fish

powershell

zsh

On linux it’s possible to install the shell completions for the given shell by executing:

$ reactive-graph --install-shell-completions bash|fish|zsh

Then you have to restart the shell, for example:

$ zsh

Profit!

$ reactive-graph -- TAB

--daemon-group -- If set will drop privileges to the specified group. Note: Both must be given: user and group --daemon -- If true, the process will run as daemon --daemon-name -- Sets the name of the daemon --daemon-pid -- The location of the daemon PID file. By default, no PID file will be created --daemon-stderr -- Stderr will be written into this file --daemon-stdout -- Stdout will be written into this file --daemon-user -- If set will drop privileges to the specified user. Note: Both must be given: user and group --daemon-working-directory -- The working directory of the daemon --default-context-path -- The default context path which redirects the root context to a web resource provider --disable-all-plugins -- If true, all plugins will be disabled --disabled-plugins -- The list of plugins to disable --disable-hot-deploy -- If true, hot deployment will be disabled --enabled-plugins -- The list of plugins to enable --graphql-config -- The GraphQL config location --help -- Print help --hostname -- The hostname to bind the GraphQL HTTP server --hot-deploy-location -- The folder which is watched for hot deployment --install-location -- The folder which plugins are installed permanently --install-man-pages -- If true, installs man pages --install-shell-completions -- If true, installs shell completions --instance-config -- The instance config location --instance-description -- The description of the instance --instance-name -- The name of the instance --logging-config -- The logging config location --markdown-help -- If true, generates command line documentation --plugins-config -- The plugins config location --port -- The port to bind the GraphQL HTTP server --print-man-pages -- If true, generates man pages --print-shell-completions -- If true, prints shell completions --quiet -- If true, logging is disabled completely --secure -- If true, HTTPS is enabled --shutdown-timeout -- Timeout for graceful workers shutdown in seconds. After receiving a stop signal, workers have this much time to finish serving requests. Workers still alive after the timeout are force dropped. By default, shutdown timeout sets to 30 seconds --ssl-certificate-path -- The location of the certificate --ssl-private-key-path -- The location of the private key --stop-immediately -- If true, the runtime does not wait before exiting --version -- Print version --workers -- The number of workers to start. The default worker count is the number of physical CPU cores available

Man Pages (Linux only)

Similarly to shell completions, the command line interface can generate, print and install man pages.

What is a man page?

A man page (short for manual page) is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts. A user may invoke a man page by issuing the man command.

Wikipedia

First, you can install man pages:

$ reactive-graph --install-man-pages

Then you can use the man command:

$ man reactive-graph

reactive-graph(1) General Commands Manual reactive-graph(1) NAME reactive-graph - Reactive Graph is a reactive runtime based on a graph database, empowering everyone to build reliable and efficient software. SYNOPSIS reactive-graph [--logging-config] [--instance-config] [--graphql-config] [--plugins-config] [-n|--instance-name] [-d|--instance-description] [--hostname] [--port] [--secure] [--ssl-certificate-path] [--ssl-private-key-path] [--shutdown-timeout] [-w|--workers] [-c|--default-context-path] [-x|--disable-all-plugins] [-p|--dis‐ abled-plugins] [-P|--enabled-plugins] [--disable-hot-deploy] [--hot-deploy-location] [--install-location] [--stop-immediately] [-q|--quiet] [--print-man-pages] [--install-man-pages] [--print-shell-completions] [--install-shell-completions] [-D|--daemon] [--daemon-name] [--daemon-pid] [--daemon-working-directory] [--dae‐ mon-stdout] [--daemon-stderr] [--daemon-user] [--daemon-group] [-h|--help] [-V|--version] [subcommands] DESCRIPTION Reactive Graph is a reactive runtime based on a graph database, empowering everyone to build reliable and efficient software. OPTIONS --logging-config=LOGGING_CONFIG The logging config location May also be specified with the REACTIVE_GRAPH_LOGGING_CONFIG environment variable. --instance-config=INSTANCE_CONFIG The instance config location May also be specified with the REACTIVE_GRAPH_INSTANCE_CONFIG environment variable. ...

Dedicated client binary

We follow the approach to have one binary for all use cases (server & client).

Additionally, we now provide a second binary that only contains the client.

$ ls -lah target/debug/reactive-graph*

-rwxrwxr-x 2 rust rust 81M reactive-graph -rwxrwxr-x 2 rust rust 29M reactive-graph-client

$ reactive-graph-client relation-instances list --output-format count

9366 result(s)

Daemonize

On Linux, it’s now possible to start the process and run it in the background. Because the daemon has no stdout and stderr, a file can be given as output. Also, the process can drop privileges to a given user+group. Optionally, a PID and name can be specified.

$ reactive-graph --help

-D, --daemon If true, the process will run as daemon [env: REACTIVE_GRAPH_DAEMON=] --daemon-name Sets the name of the daemon [env: REACTIVE_GRAPH_DAEMON_NAME=] --daemon-pid The location of the daemon PID file. By default, no PID file will be created [env: REACTIVE_GRAPH_DAEMON_PID=] --daemon-working-directory The working directory of the daemon [env: REACTIVE_GRAPH_DAEMON_WORKING_DIRECTORY=] --daemon-stdout Stdout will be written into this file [env: REACTIVE_GRAPH_DAEMON_STDOUT=] --daemon-stderr Stderr will be written into this file [env: REACTIVE_GRAPH_DAEMON_STDERR=] --daemon-user If set will drop privileges to the specified user. Note: Both must be given: user and group [env: REACTIVE_GRAPH_DAEMON_USER=] --daemon-group If set will drop privileges to the specified group. Note: Both must be given: user and group [env: REACTIVE_GRAPH_DAEMON_GROUP=]

In order to start Reactive Graph as a daemon, you have to pass the parameter -D or set the environment variable REACTIVE_GRAPH_DAEMON=true:

$ reactive-graph --daemon

Refactoring

Extracted table model

The table model has been refactored into its own crate. This allows to print tables in other command line applications.

The examples are now using the table model. The printed tables look better than before. Thanks to the table model, it is no more necessary to render tables manually.

GraphQL Schema

There are some changes to the GraphQL schema:

List of Changes

edgeKey has been renamed to relationInstanceId for consistency

EdgeKeyDefinition has been renamed to RelationInstanceIdDefinition for consistency

Extended mutation instances -> relations -> update() with the new parameters addProperties and removeProperties in order to add or remove one or multiple properties

Design System Enhancements

Circle Logos

We added a new set of logos with a circle around the inner graph symbol:

Black/White Malachite Selective Yellow Celestial Blue Mexican Pink Chartreuse

Horizontal Rules

Nothing special, but useful: horizontal rules

Project Maintenance

Social Media

We created a YouTube channel, a facebook profile and a mastodon account. We will start social media activities in near future.

Contribution Guidelines & Security Policy

We’ve extended the Contribution Guidelines and added a Security Policy.

{{ footer::print(issuedateprevious="2024-08-31", issuedatenext="") }}

August 2024 in Reactive Graph

Andreas Schaeffer — Sat, 31 Aug 2024 00:00:00 GMT

{% import "header.tera" as header %} {% import "footer.tera" as footer %}

{{ header::print(year="2024",month="August") }}

Table of Contents

Extended the Rust GraphQL Client

The Rust GraphQL Client is important to make Reactive Graph more useful and accessible. It allows to access the Reactive Graph programmatically by simply using the crate reactive-graph-client. The client crate is the foundation for the command line interface and for rust applications.

The Rust GraphQL Client is now capable to manage the type system. This means you can query or alter components, entity types and relation types. Furthermore, we started with the implementation of managing the instance system. This means you can query and alter entity instances and relation instances. Last but not least, we decided to defer work on the flow types and flow instances till instance system has been fully implemented.

The following diagram shows the importance of the Rust GraphQL Client:

flowchart TD

subgraph Runtime G[GraphQL API] A[Reactive Graph]

G --> A end

subgraph Client CLI[Command Line Interface] RC1[Rust Client]

CLI --> RC1 RC1 --> G end

subgraph Rust Application RA[Rust Application] RC2[Rust Client]

RA --> RC2 RC2 --> G end

Extended the Command Line Interface

The command line interface made big progress.

Manage Type System via CLI

➜ reactive-graph client entity-types get string title_case

Command Output

╔════════════════════════╦════════════════════════╦══════════════════════════════════╦══════════════════════════════════════╦══════════════════════════════════════════════════════════════════════════════╦════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ namespace ║ name ║ description ║ components ║ properties ║ extensions ║ ╠════════════════════════╬════════════════════════╬══════════════════════════════════╬══════════════════════════════════════╬══════════════════════════════════════════════════════════════════════════════╬════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ string ║ title_case ║ Converts the input to title case ║ namespace │ name ║ name │ data_type │ socket_type │ mutability ║ namespace │ name │ description │ extension ║ ║ ║ ║ ║ ─────────────────┼────────────────── ║ ─────────────────────────────────────┼───────────┼─────────────┼──────────── ║ ────────────────────────┼────────────────────────┼─────────────┼────────────────────────────────────────────────── ║ ║ ║ ║ ║ string │ string_operation ║ result │ String │ Output │ Immutable ║ core │ divergent │ │ [] ║ ║ ║ ║ ║ ║ ─────────────────────────────────────┼───────────┼─────────────┼──────────── ║ ────────────────────────┼────────────────────────┼─────────────┼────────────────────────────────────────────────── ║ ║ ║ ║ ║ ║ lhs │ String │ Input │ Mutable ║ metadata │ dublin-core │ │ { ║ ║ ║ ║ ║ ║ ║ │ │ │ "creator": "Hanack", ║ ║ ║ ║ ║ ║ ║ │ │ │ "subject": "Converts the input to title case", ║ ║ ║ ║ ║ ║ ║ │ │ │ "title": "Title Case" ║ ║ ║ ║ ║ ║ ║ │ │ │ } ║ ╚════════════════════════╩════════════════════════╩══════════════════════════════════╩══════════════════════════════════════╩══════════════════════════════════════════════════════════════════════════════╩════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Output Format Table

With the new parameter --output-format it is possible to output the data in table format (default), or as JSON or as TOML.

You can explicitly define the output format is table:

➜ reactive-graph client entity-instances list-properties 6ba7b810-9e15-11d1-50b4-00c04fd530c7 --output-format=table

Or you can just omit the option, because table is the default output format:

➜ reactive-graph client entity-instances list-properties 6ba7b810-9e15-11d1-50b4-00c04fd530c7

Command Output

╔════════════╦═════════════════════════════════════════════════════════════════════════════════════════════════════╗ ║ name ║ value ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ args ║ [{"help":"Delay shutdown by N seconds","long":"delay","name":"delay","required":false,"short":"d"}] ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ cmd_result ║ 0 ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ prop_name ║ "New Value" ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ label ║ "/org/inexor/commands/core/shutdown" ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ delay ║ 0 ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ command ║ "shutdown" ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ trigger ║ false ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ namespace ║ "core" ║ ╠════════════╬═════════════════════════════════════════════════════════════════════════════════════════════════════╣ ║ help ║ "Shutdown the application" ║ ╚════════════╩═════════════════════════════════════════════════════════════════════════════════════════════════════╝

Output Format JSON

Additionally to the output format table, two new output formats have been implemented json and toml. This allows to use the Reactive Graph CLI as tool for exporting types and instances.

➜ reactive-graph client entity-instances list-properties 6ba7b810-9e15-11d1-50b4-00c04fd530c7 --output-format=json

Command Output

[ { "name": "help", "value": "Shutdown the application" }, { "name": "label", "value": "/org/inexor/commands/core/shutdown" }, { "name": "trigger", "value": false }, { "name": "cmd_result", "value": 0 }, { "name": "prop_name", "value": "New Value" }, { "name": "args", "value": [ { "help": "Delay shutdown by N seconds", "long": "delay", "name": "delay", "required": false, "short": "d" } ] }, { "name": "delay", "value": 0 }, { "name": "namespace", "value": "core" }, { "name": "command", "value": "shutdown" } ]

Also, it allows to use the CLI as stdin for other CLI programs by using shell pipes. For example:

reactive-graph client entity-type get namespace type_name --output-format=JSON | less

Replacing OpenSSL with rustls

Started work on replacing OpenSSL with rustls

Actix Web now supports rustls

Patched the gql-client crate for rustls support

Waiting for a PR in aws-lc-rs to be merged (https://github.com/aws/aws-lc-rs/pull/491) since aws-lc-rs requires NASM on windows and this breaks the CI

Continuous Modernization

Fixed a bunch of clippy lints

Upgraded builds to use the latest nightly rust compiler

Replaced old GitHub Actions (actions-rs) with modern GitHub Actions

We are not quite happy that windows builds needs more than an hour and mac builds more than three hours, so we added another layer of cache to speed up the CI

Pinned the nightly version in order to make caching in the CI more effective

Java GraphQL Client

The goal was to show that it’s possible to manage the Reactive Graph from a programming language other than Rust

A gradle plugin generates POJOs and interfaces from the GraphQL schema (schema first approach). It’s even possible to implement Spring Data alike repositories

The status of the Java GraphQL Client is only a proof of concept. In the future, the Java GraphQL Client shall be on feature parity with the Rust GraphQL Client

The following diagram shows how the GraphQL Client APIs are used by applications:

flowchart TD

subgraph Runtime G[GraphQL API] A[Reactive Graph]

G --> A end

subgraph Client CLI[Command Line Interface] RC1[Rust Client]

CLI --> RC1 RC1 --> G end

subgraph Rust Application RA[Rust Application] RC2[Rust Client]

RA --> RC2 RC2 --> G end

subgraph Java Application JA[Java Application] JC[Java Client]

JA --> JC JC --> G end

As you can see, thanks to the GraphQL API it is possible to build applications in different programming languages.

POC WASM / WASI

We implemented a POC to check the current status of WASM. WASM will be an important part of the Reactive Graph. One use case is that the Reactive Graph could use WASM to load plugins written in "any" language that compiles to WASM. Another use case is that the Reactive Graph could use WASM to load behaviours for reactive entities or reactive relations. The POC showed that it now possible to interop with more complex data than primitive data types like integers.

Identity and Permission System

Currently, Reactive Graph lacks an Identity and Permission System. One of the next steps will be to implement it. We decided to not use an existing framework. The type system has to be threatened a bit different from the instance system. Also, the permission system is more complex for the instance system. In a first step we specified the requirements and the data model of the upcoming identity management and the permission system (https://github.com/reactive-graph/reactive-graph/issues/26).

Goals for September 2024

(highest priority on top)

Finish work on the rust GraphQL client and the Command Line Interface

Finish replacing OpenSSL with rustls

Start work on the Identity and Permission System

Specify the Type System Persistence (Graph Relational Mapper)

{{ footer::print(issuedateprevious="", issuedatenext="2024-09-30") }}

Black/White	Malachite	Selective Yellow	Celestial Blue	Mexican Pink	Chartreuse