About Reactive Graph

What is a Graph?

A graph organizes highly interconnected data. The state of an Entity Component System can be ideally represented with the help of the graph.

graph TD;
    A(Entity A)===>|Relation A|B(Entity B);
    A(Entity A)===>|Relation B|C(Entity C);
    B(Entity B)===>|Relation C|D(Entity D);
    C(Entity C)===>|Relation D|D(Entity D);

Why do we need a graph?

The main benefits of a graph are:

• A universal data structure for everything
• Relations are first class citizens
• Benefit from types and instances which makes things intuitive
• Benefit from navigation which is fast and intuitive
• Benefit from the semantics of highly connected, intuitive data
• Properties can store not only certain primitive data but complete documents

What type of graph does Reactive Graph implement?

Internally, Reactive Graph is an in-memory graph database with the following characteristics:

In addition, Reactive Graph takes up concepts from entity component systems. Types, i.e. entity types and relation types, are assembled using components. The type system itself is flat and supports composition rather than inheritance. Components can be added or removed from instances, i.e. entity instances or relation instances.

What is Reactive?

Now that we understand how data is stored, here’s how data interacts. The approach is that the data itself is “alive”. To do this, Reactive Graph adopts a concept from reactive programming.

In computing, reactive programming is a declarative programming paradigm concerned with data streams and the propagation of change.

It is the ingenious combination of a graph with reactive programming. The property instances are not static and only contain data. Rather, they are streams of data. If you change the value of a property instance, you fill the data stream of this property instance. Data streams are linked together. For example, if the stream of one property instance is linked to the stream of another property instance and you change the value of the first property instance, the value of the second property instance will automatically change as well. Data is thus propagated from one station to the next, triggering a cascade of propagations.

graph TD;
    A(Property Instance 1)-->|stream|B(Property Instance 2);
    A-->|stream|C(Property Instance 3);
    B-->|stream|D(Property Instance 4);
    C-->|stream|D;
    D-->|stream|E(Property Instance 5);
    B-->|stream|F(Property Instance 6);

In addition, Reactive Graph remembers the last value in each property instance. This is done by subscribing to your own data stream and caching it. This allows subsequent querying of the value of a property instance.

Remember this basic concept:

1. Every property is a stream not only data
2. Property streams can be subscribed and published
3. The streams of two properties can be connected and changes will be propagated (cascade)

Behaviour driven design

The data flow is therefore automatic. Building on this, Reactive Graph applies the concept of behaviour-driven design. The goal is to use these data streams to simulate behaviour.

Behaviors can be implemented on components, entities and relations. To do this, one or more incoming data streams are combined, calculations are performed and written to one or more outgoing data streams.

For example, the entity type “AND gate” implements a behavior by subscribing to the two input properties, combining them into a combination data stream and performing an AND operation on the incoming pairs of values. The result of the AND operation is itself a data stream and this is linked to the output property.

This example shows how an entity type is wired internally. They are all data streams that are cleverly combined with one another and thus depict behavior.

It is interesting that this behavior also works for relations. For example, connectors are also implemented behaviors of streams. It is interesting that connectors connect the data stream from a property instance of the outgoing entity instance with the data stream from a property instance of the incoming entity instance.

graph TD;
    subgraph key_ctrl ["Entity Instance (Input Key)"]
    direction RL
    CTRL_KEY(Property<br><br>key_name=CTRL);
    CTRL_KD(Output Property<br><br>key_down);
    end

    subgraph key_f10 ["Entity Instance (Input Key)"]
    F10_KD(Output Property<br><br>key_down);
    F10_KEY(Property<br><br>key_name=F10);
    end

    CTRL_KD--->|connector|LHS;
    F10_KD--->|connector|RHS;

    subgraph logicalgate ["Entity Instance (Logical Gate)"]
    LHS(Input Property<br><br>LHS)o-->ZIP;
    RHS(Input Property<br><br>RHS)o-->ZIP;
    ZIP(Zipped stream of LHS and RHS)-->COMBINATOR;
    COMBINATOR(Combinator Function<br><br>AND)-->RESULT;
    RESULT(Output Property<br><br>Result);
    end

    RESULT--->|connector|CMD_EXIT;

    subgraph system_command_exit ["Entity Instance (System Command)"]
    CMD_COMMAND(Property<br><br>Command);
    CMD_EXIT(Input Property<br><br>trigger)
    end

For example the AND-Gate accepts inputs at the properties lhs and rhs. Both streams are subscribed and zipped. The zipped stream is calculated with a function - in this case the AND-Operator. This results in another (invisible) stream which is connected with the property result. The entity type AND-Gate defines that the properties lhs, rhs and result have to exist. Furthermore, the socket types are defined: lhs and rhs are Input-Sockets and result is a Output-Socket. The behaviour is like the internal wiring of entity instances and of relation instances. A behaviour can be added to entity instances and removed from entity/relation instances.

In the Reactive Graph Flow there are ComponentBehaviours, EntityBehaviours and RelationBehaviours.

Behaviours are provided by plugins.

What is a flow?

Control flows can be implemented based on the graph, the data streams and the behavior-driven design. It is important here that the available modules that implement the behavior are linked with connectors.

For example, a flow can consist of a logic that links several AND gates with each other using connectors. Both the AND gate and the connector are behaviors. But the arrangement of these behaviors within a flow makes them powerful.

Entire game modes can be implemented with the help of flows. Or just parts of it that are used in multiple game modes, such as a mechanism to pick up, drop, and score flags.

Flows are also useful for making maps more interactive. With the help of flows and behaviors, it can be ensured that a door opens in a map when you press switch 1 and switch 2. Or you determine the color of your own team’s base based on the current score. Or you control particle emitters, depending on how many players are near the emitter. The possibilities for this are endless and want to be used!

flowchart LR
    subgraph flow ["Flow"]
        direction LR
        subgraph key_ctrl ["Entity Instance (Input Key)"]
            CTRL_KD(Output Property<br><br>key_down);
        end
    
        subgraph key_f10 ["Entity Instance (Input Key)"]
            F10_KD(Output Property<br><br>key_down);
        end
    
        CTRL_KD-->|connector|LHS;
        F10_KD-->|connector|RHS;
    
        subgraph logicalgate ["Entity Instance (Logical Gate)"]
            LHS(Input Property<br><br>LHS)-.->RESULT;
            RHS(Input Property<br><br>RHS)-.->RESULT;
            RESULT(Output Property<br><br>Result);
        end
    
        RESULT-->|connector|CMD_EXIT(Input Property trigger);
    
        subgraph system_command_exit ["Entity Instance (System Command)"]
            CMD_COMMAND(Property<br><br>Command);
            CMD_EXIT(Input Property<br><br>trigger)
        end
    end

Design Goals

This chapter describes what the application’s design goals are and aren’t.

Plugin System

The plugin system is a central building block and is therefore mentioned first. The goal of the plugin system is to keep the core as small as possible. The core of the application is described in the next section. Plugins, on the other hand, contain the functionalities.

The aim of the plugin system is also that you don’t have to restart the core application completely just because a small part has changed. It should be sufficient to restart the modified plugin.

Also, if a plugin stops working, or if the plugin’s configuration is changed, restarting the plugin might avoid restarting the core application.

In addition, the file size of the binary file is reduced since only its libraries are compiled in the core application.

In addition, only what is actually used is loaded. Plugins that are not required for the application can be deactivated.

* [Plugins Configuration](./Configuration_Plugins.md)
* [Plugin System](./Plugin_System.md)
* [Building Plugins](./Development_Build.md#build-plugins)

Runtime

The Reactive Graph runtime (reactive_graph_runtime_api) consists of a few central building blocks. As already mentioned in the introduction, this includes a built-in graph database.

Based on this, the type system is managed by the runtime. This means that in the business logic layer there is a management service to edit the type system. With the help of these services, new types can be created, queried, searched for and deleted.

Furthermore, the instance system is managed. Similar to the type system, new instances can be created, queried, searched for and deleted.

Reactive instances are managed by the reactive instance system with reactive entity instances, reactive relation instances and reactive flow instances.

Finally, the two main approaches to the Reactive Graph Flow are provided.

One access to the Reactive Graph Flow is the plugin system, which is granted access to the business logic layer of the core application via the plugin API. Type system and reactive instance system are available to every (Rust) plugin.

Second access is the GraphQL server, which also provides access to the type system and the reactive instance system. It is possible to instantiate the runtime without an HTTP/GraphQL server. But still you can use the internal GraphQL Query Service to execute GraphQL queries and mutations. For more information about the possible use cases, please take a look at the System Architecture.

In addition, there are cross-sectional functionalities such as lifecycle management, logging and configuration.

For configurations, TOML should be used as the configuration format wherever possible.

The application should be able to be adapted to the application by means of configuration.

* [GraphQL API](./GraphQL_API.md)
* [Plugin API](./Plugin_System.md)
* [Data Model](./Model.md)
* [System Architecture](./System_Architecture.md)

Runtime Non-Goals

This section explains which goals are not pursued in the runtime.

• Configurations for purposes other than logging, plugins, GraphQL server
• System-Variables
• Meta data
• Implementation of certain reactive behaviors: e.g. logic gates, arithmetic gates
• Implementation of game modes, maps, mods
• Synchronization
• Flow-Editor
• Graphics-Rendering
• Octree-Editor

Usage Goals

The application should be able to be used as required in the specific case:

• Just run and use it
• Let two or multiple instances talk to each other
• Use the runtime as integration bus for different applications or systems
• Embed the runtime in your own application which empowers you have a platform for an embedded zero code flow control and an embedded graph database
• Embed any number of runtimes in your simulation application
• Use either the CLI, the flow editor or any other tool to manipulate the type system and/or the instance system

System Architecture

Roadmap

See Milestones

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• Type System: Generate rust types for the system based on the type definitions
• Documentation: Generate Markdown documentation for the type system based on the type definitions
• Plugins: Hot deploy archives (.tar.gz and .zip) containing plugins placed in the deploy folder
• CLI: Install plugins from a plugin repository (GitHub Releases)

Changed

• Type System: Hierarchical and typesafe namespaces
• Upgrade log4rs to 1.4.0
• Refactored dynamic graph using dependency injection

Fixed

• Avoid conflicting json schema fields in the dynamic graph
• Replaced crate fxhash with rustc-hash (Fixes RUSTSEC-2025-0057)

Distribution

• Provisioning standard library plugins or another set of plugins

Infrastructure

• CI: Update rust nightly toolchain to nightly-2025-12-05
• CI: Added CODEOWNERS
• Build: Use resolver version 3
• Build: Specify default members of the workspace (exclude utils and generators)
• Tooling: Added shell script to update the json schema files of the type system manually

[0.10.0-alpha-5] - 2025-08-01

Summary / Highlights

Improves plugin support in docker containers

Added

• CLI: Added arguments --danger_accept_invalid_certs and --danger_accept_invalid_hostnames

Changed

• Plugins: Improved error message if moving plugin from plugins/deploy to plugins/installed failed

Fixed

• Docker: Run configurations for docker containers mount the plugin deploy folder of the workspace on the container (note: this works only if you’re running a single container)
• Docker: Plugin system now correctly handles deploying plugins when the deploy folder is mounted as volume

Distribution

• Docker: Dockerfile now uses ubuntu 24.04 as runtime image
• Docker: Added Dockerfile.debian which uses bookworm-slim as base image
• Docker: Added docker-compose which contains an init container for installing plugins (respects arch + configurable with a tag/version)

Infrastructure

• The standard library plugins are now provided via GitHub Releases

[0.10.0-alpha-4] - 2025-07-28

Summary / Highlights

Improved schema support for the type-system, with JSON Schemas for every type – both in the generic GraphQL API and in the Dynamic Graph.

GraphQL schemas and JSON schemas are published on: schema.reactive-graph.io

Added

• CLI: Added entity instances to flow types
• CLI: Added introspection queries
• CLI: Added command for getting the JSON Schema for each type in the type system
• Client: Added request method for getting the JSON Schema for each type in the type system
• Server CLI: Print GraphQL schemas
• Server CLI: Print JSON schemas
• GraphQL: Added entity instances to flow types
• GraphQL: Sort fields and enums
• GraphQL: Generate static schema SDL files during build
• GraphQL: Added resolver for the dynamic JSON schema for each type in the type system
• GraphQL: Added resolver for the dynamic JSON schema identifier ($id) for each type in the type system
• Dynamic Graph: Sort components, entity types, relation types and properties
• Dynamic Graph: Export reactive entities, relations and flows using dynamic schemas
• Dynamic Graph: Type System Metrics
• Dynamic Graph: Refactored field resolvers of the entity types
• Dynamic Graph: Refactored object resolvers of the flow types
• JSON Schema: Include an unique JSON schema identifier ($id) in the JSON schemas
• JSON Schema: Provide an $id field when serializing types and instances
• JSON Schema: Type definitions and instance definitions can refer to the JSON schema using an $id field
• JSON Schema: Generate dynamic schemas for all registered types in the type system
• Reactive: Added delegates for reactive flow to its wrapper entity
• Reactive: Added method to get reactive flow by entity type
• Reactive: Implemented json serialization for reactive entities and reactive relations
• Type System: Added traits JsonSchemaGetter and JsonSchemaIdGetter

Changed

• Extended binary info with rustc_host_triple and rustc_commit_date
• Renamed test-utils to utils-test
• Configure lints on workspace level
• Replaced lazy_static with LazyLock
• CLI: Updated shell completions
• Dynamic Graph: Refactored GraphQL objects
• JSON schema: Refactored REST services
• Reactive: When creating a reactive flow from type a id can be provided

Fixed

Distribution

• Docker: Make debian bookworm slim the base image in order to allow plugins loading within the docker image

Infrastructure

• CI: Synchronize labels from config file
• CI: Publish graphql and json schemas to https://schema.reactive-graph.io/
• CI: Check for breaking changes in the GraphQL schemas

[0.10.0-alpha-3] - 2025-04-13

Summary / Highlights

Migrated to Rust Edition 2024

Added

• Interfaces: Provide JSON schemas of the type system and instance system via GraphQL API
• Interfaces: Query for JSON Schemas of the type system and instance system via the Rust Client
• CLI: Print the JSON Schemas of the type system and instance system
• CLI: Manage flow types
• CLI: Manage flow instances
• GraphQL: Manage flow types
• GraphQL: Manage flow instances

Changed

• Migrated to Rust Edition 2024
• Fixed clippy lints for Rust 1.85.0

Fixed

• #[unsafe(no_mangle)]

Distribution

• Docker: Added static labels (org.opencontainers.image)
• Docker: Added multi platform docker image (amd64 + arm64)

Infrastructure

• CI: Update rust nightly toolchain to nightly-2025-03-14
• CI: Added GitHub Actions runner for arm64 ubuntu-22.04-arm
• CI: Generate release binaries and debian packages for arm64 using the arm64 runner
• CI: Automatically label pull requests
• CI: Automatically mark pull requests as stale
• CI: Automatically assign assignee and reviewers

[0.10.0-alpha-2] - 2024-10-27

Summary / Highlights

Provisioning instances

Added

• CLI: Provisioning config files reactive-graph instances init
• CLI: Generate and provisioning certificates using reactive-graph instances generate-certificate
• CLI: Manage repositories of a local instance using reactive-graph instances repository
• CLI: Set config values of a local instance using reactive-graph instances config graphql --secure true
• Distribution: Dockerfile and run configurations for docker
• Docs: Documented installation via docker

Changed

• Docs: Moved book to root folder
• Docs: Applied Reactive Graph Design System

Fixed

• CLI: Self-Updater

Infrastructure

• CI: Update rust nightly toolchain to nightly-2024-10-19
• CI: Auto-merge dependabot PRs

[0.10.0-alpha-1] - 2024-10-20

Summary / Highlights

Self updater, shell completions and building for more targets in CI

Added

• CLI: Print or install shell completions (bash, fish, zsh, powershell) and man pages
• CLI: Self Update reactive-graph update
• CLI: Init instance reactive-graph instances init <path>

Infrastructure

• CI: Create tag nightly after merge and successful build on main branch
• CI: Publish nightly releases to GitHub Releases
• CI: Sign nightly tag with GPG
• CI: New layout for debian packages
• CI: Added support for i686-unknown-linux-gnu (32-bit)
• CI: Added support for armv7-unknown-linux-musleabihf (MUSL)
• CI: Added support for x86_64-pc-windows-gnu (MinGW)
• CI: Added support for powerpc-unknown-linux-gnu, powerpc64-unknown-linux-gnu and powerpc64le-unknown-linux-gnu
• CI: Added support for riscv64gc-unknown-linux-gnu
• CI: Check in lock file for security audit workflow
• CI: Automatic labeling

[0.10.0-alpha-0] - 2024-03-24

Summary / Highlights

This is a highly technical release with a lot of major refactorings and design changes.

Highlights

• Modularized code base
• API separation
• Replaced dependency injection framework

Added

• Added plural types (EntityTypes for a set of EntityTypes) + Changed API to use plural types
• Handle reactive instances ReactiveEntity + ReactiveRelation like smart pointers (is this an anti-pattern?)
• Introduced thiserror for lots of error types
• Added test mocks using default_test in order to write tests easier
• Added declarative reactive models (reactive-derive + TypedReactivePropertyContainer)
• Added RelationTypeProviderRegistry and FlowTypeProviderRegistry
• Provide and use preludes
• Support JSON, JSON5 and TOML formats for importing and exporting types
• Added configuration for the location to the SSL certificate and private key
• Remotes Management
• JSON-Schemas
• CLI REPL + Improved CLI

Changed

• Use TypedBuilder in core-model + migrate all calls to the new builders
• Refactored reactive layer out of core-model
• Moved reactive from core-model to reactive
• Refactored hashmap and vec to dashmap and dashset
• Implemented lots of conversions between types and instances
• Refactored import export managers into own services to separate concerns
• Grouped services in a business layer
• Moved tests into implementation classes to follow rust coding guidelines
• Modernized lots of tests with mocks
• Renamed model to inexor_rgf_graph
• Plugins can use springtime dependency injection + Added declarative macros for type providers
• Extended behaviour API: BehaviourFactoryCreator + BehaviourFunctions
• Moved behaviour functionality into behaviour_api and behaviour impl modules
• Moved reactive functionality into reactive_api and reactive impl modules
• Refactored error methods in dynamic graph to regular error types with thiserror
• Made handle_web_resource async
• Web resource providers must have an ID
• Make import export managers fully async
• Improved error types for import and export types

Removed

• Removed IndraDB

[0.9.1-25] - 2023-07-20

Highlights

• Remotes Management
• JSON-Schemas
• CLI REPL + Improved CLI
• Documentation

Added

• Remotes Management
• JSON-Schemas for all types and instances
• CLI REPL
• GraphQL: Filter types by properties, extensions and/or components
• GraphQL: Added counts in types
• GraphQL: Filter plugins by dependencies or unsatisfied dependencies
• GraphQL: Uninstall plugin
• GraphQL: Test getting all plugins
• Plugin System: Whitelist plugins with new configuration enabled_plugins
• Documentation: New chapter about the system architecture
• Documentation: New chapter about the RuntimeBuilder
• Documentation: New chapter limitations
• Documentation: Cross compilation and supported platforms
• Documentation: Packaging for debian

Changed

• All APIs: Delete methods returns boolean
• CLI: refactored CLI tables from the client to the CLI crate
• Runtime: Improved state management in runtime and RuntimeBuilder
• Plugin System: Configuration file accepts short names
• Documentation: Updated sections about the model
• Documentation: Updated lots of GraphQL examples
• Documentation: Updated installation instructions

Fixed

• Don’t block runtime shutdown at a specific situation

[0.9.1-22] - 2023-05-07

Added

• Publish debian package for x86_64, aarch64 and armv7

[0.9.1-14] - 2023-05-07

Added

• Publish binaries for more targets, including Raspberry Pi

[0.9.1-4] - 2023-05-07

Added

• Configure the application using environment variables
• Generate Debian Package

[0.9.1] - 2023-05-01

Added

• First public release on crates.io

[0.9.0-15] - 2023-03-26

Added

• Configuration: Configure the instance
• Configuration: Configure the graphql server
• Configuration: Configure the plugins
• Configuration: Added config manager
• Plugin Resolver: Disable all plugins
• Plugin Resolver: Disable specific plugins
• Plugin Repository Manager: Remove duplicate plugins in plugin installation folder
• Executable: Added cli argument for the instance name and description
• Executable: Added cli argument for disabling all plugins
• Executable: Added cli argument for disabling a specific plugin
• Executable: Added cli argument for disabling hot deployment
• Executable: Added cli argument for configuring the hostname and port of the GraphQL server
• Executable: Added cli argument for configuring the shutdown timeout
• Type System: Allow merging types into existing types and plugin type providers are now merging instead of ignoring changes
• GraphQL: Simplify trigger action by providing a dedicated GraphQL mutation
• GraphQL: Allow sorting of type properties
• GraphQL: Allow sorting of type extensions

Changed

• Workspace: Create mono repository
• Workspace: Migrate repository frp into workspace
• Workspace: Migrate repository model into workspace
• Workspace: Migrate repository builder into workspace
• Workspace: Migrate repository reactive into workspace
• Runtime: Refactor into runtime and binary
• Runtime: Use tokio as async runtime
• Plugin Resolver: Resolving plugins asynchronously
• Plugin Lifecycle: Make plugin activate and deactivate methods async
• GraphQL: Generate dynamic GraphQL schema using async-graphql 5.0.0

[0.8.0] - 2022-02-01

Added

• Plugins: Plugin resolver state machine
• Plugins: Plugin dependencies and plugin versioning
• Plugins: Plugin installation directory
• Plugins: Hot deployment
• Plugins: Gracefully shutdown and refresh plugins and their behaviours during deployment / hot deployment
• Plugins: GraphQL: List, start, stop and restart plugins
• Plugins: GraphQL: List unsatisfied dependencies
• Behaviours: Lifecycles (init, connect, disconnect, shutdown)
• Behaviours: A state machine manages the behaviour (connecting, disconnecting, reconnecting)
• Behaviours: Compute behaviour initially
• Behaviours: Validation layer for behaviours
• Behaviours: Factories can construct behaviour instances
• Behaviours: Handle behaviour construction errors
• Behaviours: Macro support for implementing behaviours
• Behaviours: Added GraphQL API for behaviours + Allow connecting and disconnecting behaviours manually (flow editor)
• Behaviours: Unit tests for lots of reactive behaviours
• Model: Introduce namespaces
• Model: Use concrete type system identifiers instead of strings
• API: Validate types on construction (validate that components or entity types are present)

Changed

• Behaviours: Centralized behaviour storage (no more store behaviours in the plugins)
• Behaviours: Reimplemented lots of reactive behaviours
• Plugins: Split most plugins into a model and plugin crate
• API: Make service API and plugin API more consistent (same/similar method names + use type system identifiers)
• Tooling: rustfmt uses separate lines per import

[0.7.0] - 2022-09-25

Added

• Flow Types: Replicate and instantiate flows multiple times (like flow templates)
• Dynamic Graph: A second GraphQL api make the access to the instance system more intuitive
• Plugins: Avoid boilerplate using plugin macros
• Plugins: Metadata about the plugin
• Plugins: Dependency information
• Plugins: Expose GraphQL query service to plugins

Changed

• Plugin: Dedicated error messages for the plugin API
• Plugin: Default trait implementations for the plugin API to reduce boilerplate
• Plugin: Return option none if a plugin doesn’t use certain functionality

[0.6.0] - 2022-02-26

Added

• Documentation: Added initial documentation as book (using mdBook)
• GraphQL: Navigate from components to entity types and to relation types
• GraphQL: Navigate from a property instance to the property type
• GraphQL: Shortcut labels
• GraphQL: Filter flows by flow type
• GraphQL: Get flow by label
• GraphQL: Search instances by property value
• GraphQL: Added method to add/remove component to/from an existing instances
• GraphQL: Added filters for instances for applied components/behaviours
• Model: Components can have extensions
• Core: Provide required components and entity types in the application core
• Core: Event System for Type System and Instance System

Changed

• GraphQL: Rename mutation types (Remove prefix GraphQl)
• GraphQL: Rename type_name to type
• GraphQL: Stream property instances in subscriptions instead of handcrafted JSONs
• GraphQL: Simplified label resolver
• GraphQL: Removed behaviour resolver from types
• Model: Make extensions a separate type (used in components, entity types and relation types)
• Model: Removed behaviours from types
• Model: Added list of applied components and behaviours to reactive instances
• Documentation: Convert code of conduct and changelog to markdown
• Documentation: Added code of conduct and changelog to book

[0.5.0] - 2022-01-20

Added

• Plugin API: Added find, import & export methods for all managers
• Core: Search for type names with wildcards

Changed

• Refactored dependency injection library
• Updated dependencies of the dependency injection library

Removed

• Plugin-API: Removed dependencies for faster builds and smaller plugin binaries: actix-http, actix-web, async-std, query_interface, inexor-rgf-core-reactive

MIT License

Copyright (c) 2011-2024 Andreas Schaeffer, the Reactive Graph Contributors and the Inexor Collective.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community
• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others’ private information, such as a physical or electronic address, without explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at info@reactive-graph.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

For answers to common questions about this code of conduct, see
[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)

2. Installation

Linux

Docker

Pull the docker image:

docker pull ghcr.io/reactive-graph/reactive-graph:latest

Create and start a container:

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

Ubuntu / Debian / Raspberry Pi OS

The installation instructions below are tested on:
* Ubuntu 24.04
* Ubuntu 22.04
* Raspberry Pi OS (Bullseye)

Other debian based distributions will also work if the following requirement is satisfied:
* libc6 (>= 2.35)

An APT repository is available at [https://apt.reactive-graph.io/](https://apt.reactive-graph.io/).

Packages are currently available for these architectures:
* amd64
* arm64
* armhf
* i386
* ppc64
* ppc64el
* riscv64

Setup APT repository and download GPG keys

echo "deb https://apt.reactive-graph.io/ focal main" | sudo tee -a /etc/apt/sources.list.d/reactive-graph.list
gpg --recv-keys --keyserver keyserver.ubuntu.com 1F7F762FFE6BF816DB4C41D218D6C25399307BA5
gpg --recv-keys --keyserver keyserver.ubuntu.com 18D6C25399307BA5
gpg --export 1F7F762FFE6BF816DB4C41D218D6C25399307BA5 | sudo tee /etc/apt/trusted.gpg.d/apt.reactive-graph.io.gpg
gpg --export 18D6C25399307BA5 | sudo tee /etc/apt/trusted.gpg.d/reactive-graph.gpg
sudo apt update

Install Reactive Graph

sudo apt install reactive-graph

Create the first (default) instance of the runtime

sudo systemctl daemon-reload
sudo systemctl start reactive-graph@default

Configure the default instance

The configuration files are located at `/etc/reactive-graph/{instance-name}/`.

sudo nano /etc/reactive-graph/default/graphql.toml
sudo systemctl restart reactive-graph@default

Optional: Create further instances

It's possible to run multiple instances by starting another instance with a different name. The necessary
configuration files are created at the first start. You propaply want to change the configuration files
since they are copied from the default instance.

sudo systemctl start reactive-graph@second
sudo nano /etc/reactive-graph/second/graphql.toml

Optional: Install plugins

Once you have the runtime running you can install the plugins.

The package names starts with libreactive-graph-plugin.

To get a list of available plugins, you can search for it like so:

apt search libreactive-graph-plugin

To install a plugin for the default instance you just have to install the package and restart the service:

sudo apt install libreactive-graph-plugin-base
sudo systemctl start reactive-graph@default

Similarly, you can just install all available plugins:

sudo apt install "libreactive-graph-plugin-*"
sudo systemctl start reactive-graph@default

If you want to run multiple instances, each instance has it's own set of plugins.

The installed plugins for the default instance are located at:
`/usr/share/reactive-graph/default/plugins/installed`

Likewise plugins for another instance are located at:
`/usr/share/reactive-graph/{instance-name}/plugins/installed`

To install a plugin you can copy it from the default instance install folder into the deploy folder
of the other instance like so:
`cp /usr/share/reactive-graph/default/plugins/installed/{plugin.so} /usr/share/reactive-graph/{instance-name}/plugins/deploy`

If the other instance is already running, it's not necessary to restart the instance runtime,
because the runtime is able to hot deploy plugins.

Manually Install Debian Package

Another way is to install the debian packages manually:

1. Download the debian package from GitHub

   mkdir -p /tmp/reactive-graph
   cd /tmp/reactive-graph
   wget https://github.com/reactive-graph/reactive-graph/releases/download/{version}/reactive-graph_{version}_amd64.deb
   

2. Install the package via dpkg

   sudo dpkg -i reactive-graph_0.10.0_amd64.deb
   

3. Reload systemctl units

   sudo systemctl daemon-reload
   

4. Start the default instance

   sudo systemctl start reactive-graph@default
   

Configure an instance

# Name, Description
sudo nano /etc/reactive-graph/instance-name/instance.toml
# Port
sudo nano /etc/reactive-graph/instance-name/graphql.toml
# Log levels
sudo nano /etc/reactive-graph/instance-name/logging.toml
# Enable / disable plugin(s)
sudo nano /etc/reactive-graph/instance-name/plugins.toml
# Manage remotes
sudo nano /etc/reactive-graph/instance-name/remotes.toml

Then restart the service:

sudo systemctl restart reactive-graph@instance-name

Create a new instance (system wide)

Create a new instance by using a new instance name:

sudo systemctl start reactive-graph@instance-name

Adjust the GraphQL configuration (port, hostname) and the instance configuration (name). Then restart

sudo systemctl restart reactive-graph@instance-name

Other distributions / Manually Install Binary

You can install the binary packages manually:

1. Download the binary from https://github.com/reactive-graph/reactive-graph/releases

   wget https://github.com/reactive-graph/reactive-graph/releases/download/v{version}/reactive-graph-x86_64-unknown-linux-gnu.tar.gz
   

2. Extract the binary

   tar xvf reactive-graph-x86_64-unknown-linux-gnu.tar.gz
   

3. Start the binary

   cd reactive-graph-x86_64-unknown-linux-gnu
   ./reactive-graph
   

From Source

Please follow the Build Instructions.

Windows

Windows Installer

We plan to provide an installer for windows.

Manually install binaries

1. Download the latest binary from https://github.com/reactive-graph/reactive-graph/releases
2. Unzip the archive
3. Change into the directory
4. Execute reactive-graph.exe

From Source

Please follow the Build Instructions.

MacOS

Manually install binaries

1. Download the latest binary from https://github.com/reactive-graph/reactive-graph/releases
2. Extract the archive
3. Change into the directory
4. Execute reactive-graph

From Source

Please follow the Build Instructions.

Configuration

• Configure Logging
• Configure Instance
• Configure HTTP / GraphQL Server
• Configure Plugins
• Configure Remotes

Configure Logging

Edit config/logging.toml

Appender

Stdout

Writes to stdout.

[appenders.stdout]
kind = "console"

[appenders.stdout.encoder]
pattern = "{d(%H:%M:%S%.3f)} [{l}] [{T}] {M}:{L} - {m}{n}"

Tip

Documentation of the date format library Date Formatting Syntax

Tip

On linux the systemd unit captures the stdout. Do not use any special characters or colors.

File

Writes to file.

[appenders.file-application]
kind = "file"
path = "log/reactive-graph.log"

[appenders.file-application.encoder]
pattern = "{d(%Y-%m-%d %H:%M:%S%.3f)} [{l}] [{T}] {M}:{L} - {m}{n}"

Default log level

Set the default logging level to “debug” and attach the stdout and file-application appender to the root.

[root]
level = "debug"
appenders = ["stdout", "file-application"]

Per Log levels

Set the log level for a specific module:

[loggers."reactive_graph_type_system_impl::component_manager_impl"]
level = "info"

Tip

Documentation of the logging library How to configure the loggers

Additive

Route log events sent to the reactive_graph_plugin_service_impl::plugin_resolver_impl logger to the plugin_resolver appender, and not the normal appenders installed at the root.

[loggers."reactive_graph_plugin_service_impl::plugin_resolver_impl"]
level = "debug"
appenders = ["plugin_resolver"]
additive = false

Configure Instance

To configure the name and description of the Runtime instance, edit config/instance.toml:

name = "Default"
description = "This is the default instance."

Configure HTTP/GraphQL server

1. Edit config/graphql.toml

Bind address and port

Configure the bind address and port:

hostname = "localhost"
port = 31415

Tip

If you bind on localhost the GraphQL server is not reachable from outside. Use the hostname or ip which is reachable from outside.

Secure connections (HTTPS/WSS)

Enable HTTPS/WSS:

secure = true

Shutdown timeout

The following setting Timeout for graceful worker 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 is set to 30 seconds.

shutdown_timeout = 3

Tip

If you have to restart often during development, set this to a low value.

Number of workers

This setting specifies the number of worker threads. The default number of worker threads is the number of physical CPU cores available.

workers = 16

Default web resource provider

Plugins can provide web resources using a WebResourceProvider. The URLs are prefixed with the base path of the web resource provider. For example, the plugin binary provides a WebResourceProvider with the base path binary. Therefore, the URL starts with http(s)://hostname:31415/binary/.

The default_context_path defines which web resource provider is the default by its base path. This means that the URL https://hostname:31415/entities/uuid/property_name will be handled by the WebResourceProvider binary and is doing the same as https://hostname:31415/binary/entities/uuid/property_name.

default_context_path = "binary"

Tip

In particular, this is very useful for web applications which shall handle the root URL: https://hostname:31415/

Logging

You can enable or disable logging of HTTP/GraphQL requests and specify the log format. If no format is specified the default log format is used.

[logging]
enabled = true
format = "%a \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\" %T"

Tip

See a list of log format variables here: https://docs.rs/actix-web/latest/actix_web/middleware/struct.Logger.html#format

Configure Plugins

Edit config/plugins.toml

Disable the plugin system

You can disable / enable the plugin system entirely:

disabled = false

Disable specific plugins

You can disable specific plugins

disabled_plugins = [
    "reactive-graph-plugin-arithmetic",
    "reactive-graph-plugin-numeric"
]

Important

Plugin Dependencies Some plugins depends on other plugins. Please note, that disabling a plugin may cause that other plugins cannot start!

Enable specific plugins

You can enable specific plugins. This take precedence over disabled_plugins (which will have no effect).

enabled_plugins = [
    "reactive-graph-plugin-base",
    "reactive-graph-plugin-trigger",
    "reactive-graph-plugin-result",
    "reactive-graph-plugin-file",
    "reactive-graph-plugin-connector",
    "reactive-graph-plugin-json",
    "reactive-graph-plugin-taxonomy",
]

Configure Remotes

Edit config/remotes.toml

Hostname, port, protocol

The address of a remote is set using hostname, port and secure. If no port is given, the default port 31415 is used.

secure defines if a secure connection shall be used (https or wss). By default, secure is false.

Examples

1. https://demo.reactive-graph.io/graphql

   [[remotes]]
   hostname = "demo.reactive-graph.io"
   port = 443
   secure = true
   

2. http://localhost:31415/graphql

   [[remotes]]
   hostname = "localhost"
   

Endpoint

Optionally, you can set the GraphQL endpoint. By default, the GraphQL endpoint is /graphql.

[[remotes]]
# hostname, port omitted
endpoint = "/graphql"

User Agent

You can configure the user agent which shall be used for communication with the remote. By default, the user agent is reactive_graph.

[[remotes]]
# hostname, port omitted
userAgent = "Noob Agent"

Bearer

You can configure the bearer token which shall be used for communication with the remote. By default, no bearer token is used.

[[remotes]]
# hostname, port omitted
bearer = "..."

Model

The data model of Reactive Graph can be divided into the type system and the instance system.

Type System

The type system is similar to type systems in programming languages. An object is of a specific, previously defined type.

The type says something about the semantic meaning. For example, just looking at the type name gives you an idea of what a “player” or a “camera” is, for example.

The type system also specifies the data model of such a semantic object. For example, a player has a name, is in a position, and you know how many frags he has scored. Therefore, it is defined that a player should have a property called “name”.

Types are also related to each other. For example, a teleport entrance has one or more teleport exits. This relationship between the teleport input type and the teleport output type is called a relation type. The relation type also has a semantic meaning. In this case, the relation type “teleports_to” means that a player who is directly at the teleport entrance should be teleported to the teleport exit.

Another example is a team that has one player as a member. There is a relation type called “is_member_of” that leads from the entity type team to the entity type relation. Note the direction of the relation type.

This becomes even more relevant when there can be multiple distinct relationships between two entity types. A player can be a member of a team and he can be the team captain at the same time. The first type of relationship has already been described, the second has the name “is_captain_of”.

ER Diagram

erDiagram
    Relation-Type
    Entity-Type
    Extension
    Component
    Property-Type
    Relation-Type ||--}o Component : composes
    Relation-Type o{--|| Entity-Type : outbound
    Relation-Type o{--|| Entity-Type : inbound
    Entity-Type ||--}o Component : composes
    Relation-Type ||--}o Property-Type : defines
    Entity-Type ||--}o Property-Type : defines
    Relation-Type ||--}o Property-Type : defines
    Component ||--}o Property-Type : defines
    Relation-Type ||--}o Extension : has
    Entity-Type ||--}o Extension : has
    Property-Type ||--}o Extension : has

Example: Relation Type

graph LR
    E1(Entity Type<br>Teleporter)
    E2(Entity Type<br>Teledestination)
    R1(Relation Type<br>Teleports_To)
    E1--->|outbound|R1
    R1--->|inbound|E2

Example: Relation Types & Entity Types

graph TB
    P(Player)
    C(Camera)
    F(Flag)
    T(Team)
    B(Base)
    S(Playerstart)
    C--->|looks_at|P
    C--->|looks_at|F
    C--->|looks_at|B
    P--->|is_member_of|T
    P--->|frags|P
    T--->|is_located_at|B
    T--->|owns|F
    B--->|provides|S
    P--->|has_spawned_at|S

Instance System

Having described the type system, this section describes the instance system.

The type system describes what could exist.

A type defines how an instance should look like. An instance itself fills this type with life. There can be any number of instances of a type. For example, there is the player named “peter” and the player named “penacka”. In this case there are two instances of the same type.

The following table shows that an instance and the corresponding type:

erDiagram
    Relation-Type
    Relation-Instance
    Entity-Type
    Entity-Instance
    Flow-Instance
    Relation-Instance o{--|| Relation-Type : is_a
    Entity-Instance o{--|| Entity-Type : is_a
    Flow-Instance o{--|| Entity-Type : is_a

Example: Relation Instances & Entity Instances

graph TB
    P1(Player 1)
    P2(Player 2)
    C1(Camera 1)
    C2(Camera 2)
    F1(Flag 1)
    F2(Flag 2)
    F3(Flag 3)
    F4(Flag 4)
    T1(Team Good)
    T2(Team Evil)
    B1(Base Good)
    B2(Base Evil)
    ST11(Playerstart Good 1)
    ST12(Playerstart Good 2)
    ST21(Playerstart Evil 1)
    ST22(Playerstart Evil 2)
    C1--->|looks_at|P1
    C2--->|looks_at|F2
    P1--->|is_member_of|T1
    P2--->|is_member_of|T2
    P1--->|fragged|P2
    P2--->|fragged|P1
    T1--->|is_located_at|B1
    T2--->|is_located_at|B2
    T1--->|owns|F1
    T1--->|owns|F2
    T2--->|owns|F3
    T2--->|owns|F4
    B1--->|provides|ST11
    B1--->|provides|ST12
    B2--->|provides|ST21
    B2--->|provides|ST22
    P1--->|has_spawned_at|ST11
    P2--->|has_spawned_at|ST22
    P1--->|stole|F3
    P2--->|stole|F2

Model: Component

A component is a reusable building block for entity types and relation types. A component semantically represents an aspect of one or more entity types or relation types.

For example, the component “named” represents that something has a name. In practice, the component has a property called “name” which contains the name. The “named” component can be used in a wide variety of cases. For example, a player has a name, a server has a name, and a player model also has a name. Apart from the name, they have little in common.

A component should provide at least one property. However, it is also possible to define several properties.

Another example is the “position” component, which defines the x, y, and z coordinates. Again, this is a perfect example of a Component. Because all things in a 3D world have a position. A player has a position, a camera, a flag or a light each have a position. But here, too, they have little in common. And yet they have at least one thing in common.

A player has a name and a position, i.e. an entity type (just like a relation type) can consist of several components. The properties of all components are merged.

Data Model

ER Diagram

erDiagram
    Component {
        string name
        string description
    }
    Property-Type {
        string name
        string description
    }
    Extension {
        string name
        JSON extension
    }
    Component ||--}o Property-Type : defines
    Property-Type ||--}o Extension : has
    Entity-Type o{--}o Component : composes
    Relation-Type o{--}o Component : composes

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Components.md)

JSON Schema

http://hostname:port/types/components/schema

Model: Entity Type

An entity type defines the characteristics that are common to all entity instances. In particular, an entity type defines which components it is combined from. Additional properties can also be defined.

Data Model

ER Diagram

erDiagram
    Entity-Type {
        string namespace
        string name
    }
    Entity-Instance {
        string id
        string label
    }
    Extension {
        string namespace
        string name
        JSON extension
    }
    Component {
        string namespace
        string name
    }
    Property-Type {
        string name
        enum DataType
        enum SocketType
        enum Mutability
    }
    Relation-Type {
        string namespace
        string name
    }
    Entity-Type ||--}o Property-Type : defines
    Relation-Type ||--}o Property-Type : defines
    Component ||--}o Property-Type : defines
    Entity-Type ||--}o Relation-Type : outbound
    Entity-Type ||--}o Relation-Type : inbound
    Relation-Type o{--}o Component : composes
    Entity-Type ||--}o Extension : has
    Relation-Type ||--}o Extension : has
    Property-Type ||--}o Extension : has
    Entity-Instance ||--}o Entity-Type : is-a
    Entity-Type o{--}o Component : composes

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Entity_Types.md)

JSON Schema

http://hostname:port/types/entities/schema

Model: Relation Type

A relation type defines the characteristics that are common to all relation instances. In particular, a relation type defines the entity type of the outbound entity instance and the entity type of the inbound entity instance.

Like entity types, it is also defined which components make up the relation type and which additional properties it contains.

As with entity types, extensions to the relation type can be defined, such as the appearance of edges in a graph or the appearance of a connector of this type in the flow editor.

Data Model

Graph

graph LR;
    A(Outbound Entity Type)===>|"Relation Type"|B(Inbound Entity Type);

ER Diagram

erDiagram
    Relation-Type {
        string namespace
        string name
    }
    Entity-Type {
        string namespace
        string name
    }
    Relation-Instance {
        string instanceId
    }
    Extension {
        string namespace
        string name
        JSON extension
    }
    Component {
        string namespace
        string name
    }
    Property-Type {
        string namespace
        string name
        enum DataType
        enum SocketType
        enum Mutability
    }
    Relation-Type ||--}o Component : composes
    Relation-Type o{--|| Entity-Type : outbound
    Relation-Type o{--|| Entity-Type : inbound
    Entity-Type ||--}o Component : composes
    Relation-Type ||--}o Property-Type : defines
    Entity-Type ||--}o Property-Type : defines
    Relation-Type ||--}o Property-Type : defines
    Component ||--}o Property-Type : defines
    Relation-Type ||--}o Extension : has
    Entity-Type ||--}o Extension : has
    Property-Type ||--}o Extension : has
    Relation-Instance o{--|| Relation-Type : is-a

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Relation_Types.md)

JSON Schema

http://hostname:port/types/relations/schema

Model: Property Type

Components, entity types and relation types define which properties they contain. The so-called property types define the name, the data type and whether the property is an input or an output.

Data Model

ER Diagram

erDiagram
    Property-Type {
        string name
        string description
        enum DataType
        enum SocketType
        enum Mutability
    }
    Extension {
        string namespace
        string name
        JSON extension
    }
    Property-Type ||--}o Extension : has
    Component ||--}o Property-Type : defines
    Entity-Type ||--}o Property-Type : defines
    Relation-Type ||--}o Property-Type : defines
    Flow-Type ||--}o Property-Type : defines

Enum Data Type

A property has a data type. This is derived from serde_json::Value and maps JSON values or documents.

Enum Socket Type

The socket type determines whether a property serves as an input or an output. It is also possible that a property is neither an input nor an output. Caution: At runtime, it is not prevented if an input is used as an output or an output is used as an input.

Enum Mutability

Defines if the property is either mutable or immutable.

Where is the value???

A property type only contains the definition of a property, but no data, since it is a type.

When an entity instance or a relation instance is created, the property types are used to create property instances. The property instances then contain a data stream and the last value.

Model: Flow Type

A flow type consists of entity instances and relation instances. Flow types are not runnable by itself, but you can create flow instances out of them.

Wrapper Entity Instance

Flow types can have input and output properties. These are provided by a so-called wrapper-entity-instance. The wrapper entity instance is the only mandatory entity instance of a flow type.

For the outside view, the input properties of the wrapper entity instance are the inputs. Inside the flow the input properties are output properties which can be consumed by the entity instances and relation instances within the flow type.

On the other hand, the output properties of the wrapper entity instance are outputs for the outside view. But inside the flow the output properties of the wrapper entity instance are inputs for the entity instances and relation instances within the flow type.

Nested Flow Types / Subflows / Subprograms

Nested flow types are possible. The outer flow type contains entity instances and relation instances which can interact with the wrapper entity instance and their properties of the inner flow type. This way it is possible to “call” subprograms / subflows / subactivities. The entity instances and relation instances of the inner flow type are hidden for the outer flow type.

Data Model

ER Diagram

erDiagram
    Flow-Type {
        string namespace
        string name
    }
    Entity-Type {
        string namespace
        string name
    }
    Entity-Instance {
        string id
        string label
    }
    Extension {
        string namespace
        string name
        JSON extension
    }
    Component {
        string namespace
        string name
    }
    Property-Type {
        string name
        enum DataType
        enum SocketType
    }
    Relation-Type {
        string namespace
        string name
    }
    Relation-Instance {
        string instanceId
    }
    Property-Instance {
        string name
        JSON value
    }
    Component ||--}o Property-Type : defines
    Entity-Type o{--}o Component : composes
    Entity-Type ||--}o Property-Type : defines
    Entity-Type ||--}o Extension : has
    Entity-Type ||--}o Relation-Type : outbound
    Entity-Type ||--}o Relation-Type : inbound
    Component ||--}o Extension : has
    Relation-Type ||--}o Property-Type : defines
    Relation-Type o{--}o Component : composes
    Relation-Type ||--}o Extension : has
    Property-Type ||--}o Extension : has
    Entity-Instance ||--}o Entity-Type : is-a
    Relation-Instance ||--}o Property-Instance : stores
    Entity-Instance ||--}o Property-Instance : stores
    Relation-Instance o{--|| Relation-Type : is-a
    Property-Instance o{--|| Property-Type : is-a
    Flow-Type ||--|| Entity-Instance : has-wrapper
    Flow-Type o{--}o Entity-Instance : has
    Flow-Type o{--}o Relation-Instance : has
    Flow-Type ||--}o Property-Type : has-variables
    Flow-Type ||--}o Extension : has

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Flow_Types.md)

JSON Schema

http://hostname:port/types/flows/schema

Model: Extension

There is information about a type that is useful for certain cases, but at the same time is not needed in every case. The data model of the types should remain lean and not be overloaded. Nevertheless, future changes and new functionalities should be made possible. However, this should be done in a way without becoming incompatible. This extended information is called extensions.

An extension consists of two fields. On the one hand the name of the extension and on the other hand a field with unstructured data in JSON format. This means that the data model of the extension is not specified. At the same time, however, it is possible to provide any conceivable information. Because a JSON value is used, any complex and nested information is possible. It is possible to deserialize the JSON value into a concrete data model.

An example of an extension is the information on how a flow editor should draw a shape of an entity type. The extension is called “flow_shape” and contains information about the color, size, label and alignment of the shape. This example shows that an extension can potentially contain very complex data structures and at the same time that an extension covers a case that is not relevant in all cases. For example, if the “Flow Editor” plugin is not installed or not activated, the extension is present but not used.

Data Model

ER Diagram

erDiagram
    Extension {
        string namespace
        string name
        JSON extension
    }
    Entity-Type ||--}o Extension : has
    Relation-Type ||--}o Extension : has
    Flow-Type ||--}o Extension : has
    Property-Type ||--}o Extension : has
    Entity-Instance ||--}o Extension : has
    Relation-Instance ||--}o Extension : has

List of known extensions

Extension dublin_core

    {
      "name": "dublin-core",
      "extension":{
        "title": "Decrement number",
        "subject": "Decrement number",
        "creator": "Hanack"
      }
    }

Extension flow_editor_palette

{
  "name": "flow_editor_palette",
  "extension": {
    "content": "Decrement",
    "styles": {
      "font-family": "Fira Code",
      "font-size": "12px",
      "padding": "5px"
    }
  }
}

Extension flow_editor_shape

{
  "name": "flow_editor_shape",
  "extension": {
    "width": 200,
    "socket": {
      "width": 60,
      "height": 30,
      "offset": 5
    },
    "offset": {
      "top": "socket.height",
      "bottom": "socket.height"
    },
    "elements": {
      "title": {
        "show": true,
        "type": "text",
        "content": "element.description",
        "position": {
          "left": 0,
          "top": 0,
          "width": "shape.width",
          "height": "socket.height"
        },
        "styles": {
          "font-size": "12px",
          "color": "black"
        }
      },
      "symbol": {
        "show": true,
        "type": "text",
        "content": "--",
        "position": {
          "left": 0,
          "top": 0,
          "width": "shape.width",
          "height": "shape.height"
        },
        "styles": {
          "fill": "steelblue",
          "font-size": "80px",
          "font-family": "Fira Code"
        }
      },
      "id": {
        "show": true,
        "type": "text",
        "content": "shape.id",
        "position": {
          "left": 0,
          "top": "shape.height-socket.height",
          "width": "shape.width",
          "height": "socket.height"
        },
        "styles": {
          "font-size": "9px",
          "color": "black"
        }
      }
    }
  }
}

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Extension.md)

Model: Entity Instance

An entity instance is an object with characteristics that is of a specific entity type. An entity instance contains a property instance for each property type defined either in the entity type or in one of the entity type’s components.

In contrast to entity types, property instances are contained and each property instance contains a data stream and its last value.

UUIDs

Entity instances can be uniquely identified via a UUID. This is particularly important when entity instances are synchronized in a distributed system. For example, a player’s representation exists not only in the local client, but also on the server and on clients connected to it.

* UUIDs are unique and unique across distributed systems
* UUIDs can be represented as string and as a 128 bit unsigned integer

Labels

Labels are also unique, but optional. While UUIDs are hard to remember, labels are easier to remember. This allows entity instances to be addressed using labels, for example in GraphQL queries.

If you compare the query with and without a label, you will find that the query is easier to understand thanks to the label and transports significantly more information about what is actually happening.

Labels are optional

query {
  instances {
    entities(label: "/io/reactive-graph/input/any_device/key/key_f7") {
      properties(name: "key_down") {
        value
      }
    }
  }
}

query {
  instances {
    entities(id: "c7ec76e0-40e8-587e-bc89-e9cd31fa75a0") {
      properties(name: "key_down") {
        value
      }
    }
  }
}

Data Model

Graph

graph LR;
    EI(Entity Instance);
    I1(Entity Instance)===>|"Relation Instance"|EI;
    I2(Entity Instance)===>|"Relation Instance"|EI;
    I3(Entity Instance)===>|"Relation Instance"|EI;
    EI===>|"Relation Instance"|O1(Entity Instance);
    EI===>|"Relation Instance"|O2(Entity Instance);
    EI===>|"Relation Instance"|O3(Entity Instance);

ER Diagram

erDiagram
    Entity-Type {
        string namespace
        string name
    }
    Entity-Instance {
        string id
        string label
    }
    Relation-Type {
        string namespace
        string name
    }
    Relation-Instance {
        string namespace
        string name
        string instanceId
    }
    Property-Type {
        string name
        enum DataType
        enum SocketType
        enum Mutability
    }
    Property-Instance {
        string name
        JSON value
    }
    Entity-Instance ||--}o Property-Instance : stores
    Entity-Instance o{--}o Relation-Instance : outbound
    Entity-Instance o{--}o Relation-Instance : inbound
    Relation-Instance ||--}o Property-Instance : stores
    Relation-Instance o{--|| Relation-Type : is-a
    Property-Instance o{--|| Property-Type : is-a
    Entity-Instance o{--|| Entity-Type : is-a
    Relation-Type ||--}o Property-Type : defines
    Entity-Type ||--}o Relation-Type : outbound
    Entity-Type ||--}o Relation-Type : inbound
    Entity-Type ||--}o Property-Type : defines

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Entity_Instances.md)

JSON Schema

http://hostname:port/instances/entities/schema

Model: Relation Instance

A relation instance is a connection between an outbound entity instance and an inbound entity instance. The relation instance has a type, the relation type. The relation type defines which entity type the outbound entity type and which entity type the inbound entity type must have.

Instance Id / Cardinality

The relation instance is a unique link for the following combination:

• Outbound Entity Instance
• Inbound Entity Instance
• Relation Type
• Instance Id

Warning

It’s not possible to add a relation instance with the same outbound, inbound, type and instance_id.

There are multiple types of instance ids:

1. Only one instance of the same relation type is allowed between the outbound entity instance and the inbound entity instance (Cardinality: 0..1). In this case the instance id is an empty string.
2. The relation instance depends on properties. For example, only one connector can exist between an output property of the outbound entity instance and an input property of the inbound entity instance. In this case the instance id is a string calculated by the property names of the output property and the input property. This will prevent that multiple connectors of the same type exist between the same properties.
3. There is no restriction for a relation instance between the outbound entity instance and the inbound entity instance (Cardinality: 0..N). In this case a random string will be generated as instance id. This allows to create multiple relation instances of the same type between the same outbound entity instance and inbound entity instance.

The uniqueness of entity instances is much simpler: A simple UUID is sufficient.

Data Model

Graph

graph LR;
    A(Outbound Entity Instance)===>|"Relation Instance"|B(Inbound Entity Instance);

ER Diagram

erDiagram
    Entity-Type {
        string namespace
        string name
    }
    Entity-Instance {
        string id
        string label
    }
    Relation-Type {
        string namespace
        string name
    }
    Relation-Instance {
        string instanceId
    }
    Property-Type {
        string name
        enum DataType
        enum SocketType
        enum Mutability
    }
    Property-Instance {
        string name
        JSON value
    }
    Entity-Instance ||--}o Property-Instance : stores
    Entity-Instance o{--}o Relation-Instance : outbound
    Entity-Instance o{--}o Relation-Instance : inbound
    Relation-Instance ||--}o Property-Instance : stores
    Relation-Instance o{--|| Relation-Type : is-a
    Property-Instance o{--|| Property-Type : is-a
    Entity-Instance o{--|| Entity-Type : is-a
    Relation-Type ||--}o Property-Type : defines
    Entity-Type ||--}o Relation-Type : outbound
    Entity-Type ||--}o Relation-Type : inbound
    Entity-Type ||--}o Property-Type : defines

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Relation_Instances.md)

JSON Schema

http://hostname:port/instances/relations/schema

Model: Property Instance

A property instance is a data stream. The current value of the property instance can be queried. Data streams can be connected to each other (both within an instance and to data streams from property instances of other entity or relation instances).

The property type defines the name, data type and socket type of the property instance.

Data Model

Graph

graph TD;
    PI1(Property Instance);
    PI2(Property Instance);
    PI3(Property Instance);
    EI(Entity Instance)--->PI1;
    EI(Entity Instance)--->PI2;
    EI(Entity Instance)--->PI3;

    PI4(Property Instance);
    PI5(Property Instance);
    PI6(Property Instance);
    RI(Relation Instance)--->PI4;
    RI(Relation Instance)--->PI5;
    RI(Relation Instance)--->PI6;

ER Diagram

erDiagram
    Property-Type {
        string name
        enum DataType
        enum SocketType
        enum Mutability
    }
    Property-Instance {
        string name
        string value
    }
    Entity-Instance {
        string id
        string label
    }
    Relation-Instance {
        string instanceId
    }
    Property-Type ||--}o Property-Instance : is-a
    Entity-Instance ||--}o Property-Instance : stores
    Entity-Instance o{--}o Relation-Instance : outbound
    Entity-Instance o{--}o Relation-Instance : inbound
    Relation-Instance ||--}o Property-Instance : stores

Model: Flow Instances

What is a flow instance?

A flow instance is a collection of entity instances and relation instances. Most of the time, a flow instance serves a specific purpose.

Wrapper Entity Instance

A flow instance is itself an entity instance. The properties of the entity instance can be viewed as inputs and outputs for the entire flow instance. The entity instance which is the flow instance is called wrapper entity instance.

graph LR;
    F(Flow Instance = Entity Instance);
    IPI1(Input Property Instance)===>F;
    IPI2(Input Property Instance)===>F;
    IPI3(Input Property Instance)===>F;
    F===>OPI1(Output Property Instance);
    F===>OPI2(Output Property Instance);
    F===>OPI3(Output Property Instance);

Nested Flows

Flow instances are nestable. That is, an entity instance that is itself a flow instance can be used in another flow instance. These nested flow instances can be thought of as subprograms or sub flows. The input properties of the subflow can be considered as parameters of the subprogram and the output properties of the subflow can be considered as the function result of the subprogram.

An entity instance can exist in several flow instances at the same time. For example, a TOML configuration loaded into an entity instance can be used in multiple flow instances.

Nested Flow Instance Example

graph LR;
    subgraph Outer-Flow-Instance
        direction LR
        E1(Entity Instance);
        E2(Entity Instance);
        E3(Entity Instance);
        E4(Entity Instance);
        E5(Entity Instance);
        E1--->|connector|IF1E1
        E4--->|connector|IF1E1
        E4--->|connector|E5
        subgraph Inner-Flow-Instance-1
            direction LR
            IF1E1-->|connector|IF1E2
        end
        IF1E2--->E2
        E2--->|connector|IF2E1
        E5--->|connector|IF2E1
        subgraph Inner-Flow-2
            direction LR
            IF2E1-->|connector|IF2E2
        end
        IF2E2--->|connector|E3
    end

GraphQL

* [GraphQL Queries and Mutations](./GraphQL_API_Flow_Instances.md)

JSON Schema

http://hostname:port/instances/flows/schema

GraphQL API

GraphQL is the most important interface for interaction with the Reactive Graph Flow.

What is GraphQL?

GraphQL stands for “Graph Query Language”. It is a query language with which data present in graphs can be efficiently queried and selectively modified.

Why do we use GraphQL?

As already described, Reactive Graph uses a graph to hold the highly interconnected data of the Entity Component System. A query language like GraphQL allows navigating on this graph. For example, it is possible to navigate from an entity instance to its entity type. It is best described by the three graphics that show the possibilities available through the GraphQL interface.

GraphQL was chosen as the query language because it is independent of a specific programming language and because it can be used across technologies.

GraphQL also supports subscribing to change to data. This is also the case, for example, in the reactive property instances. It is possible to subscribe to a property of an entity instance via GraphQL and get changes to this property in real time.

Other advantages of GraphQL are type safety and the fact that semantics can be mapped better.

Queries

Explore the GraphQL queries using the [Plugin GraphQL Schema Visualization](./Plugins_GraphQL_Schema_Visualization.md):
[https://hostname:31415/graphql-schema-visualization/graph/query](https://hostname:31415/graphql-schema-visualization/graph/query)

Mutations

Explore the GraphQL mutations using the [Plugin GraphQL Schema Visualization](./Plugins_GraphQL_Schema_Visualization.md)
[https://hostname:31415/graphql-schema-visualization/graph/mutation](https://hostname:31415/graphql-schema-visualization/graph/mutation)

Subscriptions

Explore the GraphQL subscriptions using the [Plugin GraphQL Schema Visualization](./Plugins_GraphQL_Schema_Visualization.md):
[https://hostname:31415/graphql-schema-visualization/graph/subscription](https://hostname:31415/graphql-schema-visualization/graph/subscription)

GraphQL Endpoint

The GraphQL endpoint can be reached at http://hostname/31415/graphql or ws://hostname/31415/graphql.

The GraphQL schema is well documented.

Schema Introspection

The GraphQL Server allows introspection and returns a GraphQL schema including documentation. With this it is possible to validate queries and mutations and some tools can use the schema to provide autocompletion for creating queries.

GraphQL Tools

• Altair
• GraphQL Voyager
• Firefox Addon GraphQL Developer Tools

GraphQL API: Components

GraphQL API: Entity Types

Relation Types

Flow Types

Extension

Query extensions of an entity type

query {
  types {
    entities(name: "example_entity") {
      name
      properties {
        extensions {
          name
          extension
        }
      }
    }
  }
}

Query extension by name

query {
  types {
    entities(name: "example_entity") {
      name
      properties {
        extensions(name: "flow_editor_palette") {
          extension
        }
      }
    }
  }
}

Entity Instances

Query an entity instance by id

query {
  instances {
    entities(id: "0-0-0-0") {
      id
      type {
        name
      }
      properties {
        name
        value
      }
    }
  }
}

Query a property instance by name of an entity instance by label

query {
  instances {
    entities(label: "/io/reactive-graph/input/any_device/key_f10") {
      properties(name: "key_down") {
        value
      }
    }
  }
}

Query the positions of all cameras that are looking at a player

query {
  instances {
    entities(type: "player", label: "/io/reactive-graph/game/players/Hanack") {
      inbound(type: "look_at") {
        outbound {
          properties(name: "position") {
            value
          }
        }
      }
    }
  }
}

Relation Instances

Get pairs of outbound + inbound entity instances of all relations of a specific type

query {
  instances {
    relations(type: "looks_at") {
      outbound {
        id
      }
      inbound {
        id
      }
    }
  }
}

Get all inbound relation instances of an entity instance

query {
  instances {
    entities(id: "uuid") {
      inbound {
        type {
          name
        }
        properties {
          name
          value
        }
      }
    }
  }
}

Get the entity instances which are inbound relations to an entity instance

query {
  instances {
    entities(type: "player") {
      inbound {
        outbound {
          id
          type {
            name
          }
          properties {
            name
            value
          }
        }
      }
    }
  }
}

Get the entity instances which are outbound relations to an entity instance

query {
  instances {
    entities(type: "player") {
      outbound {
        inbound {
          id
          type {
            name
          }
          properties {
            name
            value
          }
        }
      }
    }
  }
}

Flow Instance

Get all flow ids

query {
  instances {
    flows {
      id
    }
  }
}

Get all flows of a particular entity type

query {
  instances {
    flows(type: "generic_flow") {
      id
    }
  }
}

Get the label of a flows by id

query {
  instances {
    flows(id: "uuid") {
      label
    }
  }
}

Get the id of a flows by label

query {
  instances {
    flows(label: "/io/reactive-graph/flows/game-servers") {
      id
    }
  }
}

Get the entity instance which are contained by a flow

query {
  instances {
    flows(id: "uuid") {
      entities {
        id
      }
    }
  }
}

Get the properties of the wrapper entity instance of a flow

query {
  instances {
    flows(id: "uuid") {
      wrapper {
        properties {
          name
          value
          type {
            dataType
            socketType
          }
        }
      }
    }
  }
}

Get the relation instances which are contained by a flow

query {
  instances {
    flows(id: "uuid") {
      relations {
        outbound {
          id
        }
        type {
          name
        }
        inbound {
          id
        }
      }
    }
  }
}

Get all entity instances and all relation instances of a flow

query {
  instances {
    flows(id: "uuid") {
      type {
        name
      }
      label
      entities {
        id
        label
        type {
          name
        }
        properties {
          name
          value
        }
      }
      relations {
        type {
          name
        }
        outbound {
          id
        }
        inbound {
          id
        }
        properties {
          name
          value
        }
      }
    }
  }
}

Property Instance Subscriptions

Explore the subscriptions using the [Plugin GraphQL Schema Visualization](./Plugins_GraphQL_Schema_Visualization.md)
[https://hostname:31415/graphql-schema-visualization/subscription](https://hostname:31415/graphql-schema-visualization/subscription)

Subscribe changes of the key right-ctrl

subscription keyDownRightCtrl {
  entity(
    label: "/io/reactive-graph/input/any_device/key/key_rightctrl",
    propertyName: "key_down"
  ) {
    name
    value
    type {
      name
      dataType
      socketType
      extensions {
        name
        extension
      }
    }
  }
}

GraphQL API: Instance Info

Functionality

• Self-Information
  • Name
  • Description
  • Version
  • Endpoint
    • hostname
    • port
    • secure
  • Git
    • branch
    • commit
  • Build
    • date
    • rust compiler version
    • plugin API version

GraphQL API: Plugins

Functionality

• List Plugins
• Plugin State
• Start Plugin
• Stop Plugin
• Restart Plugin
• Redeploy Plugin
• Uninstall Plugin
• Plugin dependencies and their state
• Dependents of a plugin and their state
• Unsatisfied dependencies

GraphQL API: Remotes

Functionality

• List Remotes
• Add Remote
• Remove Remote
• Update Remote Self-Information
  • Updates the lastSeen property
• Fetch Remotes from another Remote
  • Queries the remotes of another remote and adds them to the own list of remotes (except duplicate and offline remotes)

GraphQL API: Shutdown

Dynamic Graph API

Advantages

1. It is easier to query or modify because you operate on real types not abstract types
2. Queries and mutations are more readable
3. The navigation through the Dynamic Graph is much easier and more natural 4It is easier to use by the consumer because it’s not necessary to convert the abstract types into the real types as you already operate on real types 5It is possible to use a code generator to generate types from the Dynamic Graph schema

Limitations

1. Not everything is possible
2. The Dynamic Graph schema contains all Components, Entity Types and Relation Types as defined by the type system. The Reactive Graph Flow enables you to add further components to existing Entity Instances or Relation Instances. The schema simply cannot contain which components have been added to which instances at runtime. Querying for these properties is possible but makes the query invalid.
3. Due to the parsing and resolving at runtime the Dynamic Graph is notable slower than the GraphQL API which is generated at compile time.

GraphQL Endpoint

The GraphQL endpoint can be reached at http://hostname/31415/dynamic-graph or ws://hostname/31415/dynamic-graph.

The GraphQL schema documentation is automatically generated using the documentation of the Components, Entity Types or Relation Types.

Schema Introspection

The GraphQL Server allows introspection and returns a GraphQL schema including documentation. With this it is possible to validate queries and mutations and some tools can use the schema to provide autocompletion for creating queries.

The GraphQL schema is regenerated each time a [Component](./Model_Component.md), an
[Entity Type](./Model_Entity_Type.md) or a [Relation Type](./Model_Relation_Type.md) is added or removed.

GraphQL Tools

• Altair
• GraphQL Voyager
• Firefox Addon GraphQL Developer Tools

Usage

5. Plugin System

The plugin system is a central building block and is therefore mentioned first. The goal of the plugin system is to keep the core as small as possible. The core of the application is described in the next section. Plugins, on the other hand, contain the functionalities.

The aim of the plugin system is also that you don’t have to restart the core application completely just because a small part has changed. It should be sufficient to restart the modified plugin.

Also, if a plugin stops working, or if the plugin’s configuration is changed, restarting the plugin might avoid restarting the core application.

In addition, the file size of the binary file is reduced since only its libraries are compiled in the core application.

In addition, only what is actually used is loaded. Plugins that are not required for the application can be deactivated.

Trait Plugin

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {

    // ===== Metadata =====

    fn metadata(&self) -> Result<PluginMetadata, PluginError> {}

    // ===== Lifecycle =====

    fn init(&self) -> Result<(), PluginError> {}

    fn post_init(&self) -> Result<(), PluginError> {}

    fn pre_shutdown(&self) -> Result<(), PluginError> {}

    fn shutdown(&self) -> Result<(), PluginError> {}

    // ===== Context =====

    fn set_context(&self, context: Arc<dyn PluginContext>) -> Result<(), PluginError> {}

    // ===== Providers =====
    
    fn get_component_provider(&self) -> Result<Arc<dyn ComponentProvider>, PluginError> {}

    fn get_entity_type_provider(&self) -> Result<Arc<dyn EntityTypeProvider>, PluginError> {}

    fn get_relation_type_provider(&self) -> Result<Arc<dyn RelationTypeProvider>, PluginError> {}

    fn get_component_behaviour_provider(&self) -> Result<Arc<dyn ComponentBehaviourProvider>, PluginError> {}

    fn get_entity_behaviour_provider(&self) -> Result<Arc<dyn EntityBehaviourProvider>, PluginError> {}

    fn get_relation_behaviour_provider(&self) -> Result<Arc<dyn RelationBehaviourProvider>, PluginError> {}

    fn get_flow_provider(&self) -> Result<Arc<dyn FlowProvider>, PluginError> {}

    fn get_web_resource_provider(&self) -> Result<Arc<dyn WebResourceProvider>, PluginError> {}
}
}

Provide plugin metadata

Built-in metadata of the plugin:

• The name of the plugin (use environment variable CARGO_PKG_NAME)
• The description of the plugin (use environment variable CARGO_PKG_DESCRIPTION)
• The version of the plugin (use environment variable CARGO_PKG_VERSION)

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {
    fn metadata(&self) -> Result<PluginMetadata, PluginError> {
        Ok(PluginMetadata {
            name: env!("CARGO_PKG_NAME").into(),
            description: env!("CARGO_PKG_DESCRIPTION").into(),
            version: env!("CARGO_PKG_VERSION").into(),
        })
    }
}
}

Lifecycle

The plugin trait provides methods to do initialization and shutdown before and after setting up and shutting down providers.

TODO: Lifecycle Image

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {
    fn init(&self) -> Result<(), PluginError> {
        // Called before initialization of the providers
        Ok(())
    }

    fn post_init(&self) -> Result<(), PluginError> {
        // Called after initialization of the providers
        Ok(())
    }

    fn pre_shutdown(&self) -> Result<(), PluginError> {
        // Called before shutdown of the providers
        Ok(())
    }

    fn shutdown(&self) -> Result<(), PluginError> {
        // Called after shutdown of the providers
        Ok(())
    }
}
}

Trait PluginContext

#![allow(unused)]
fn main() {
pub trait PluginContext: Send + Sync {
    /// Returns the component manager.
    fn get_component_manager(&self) -> Arc<dyn ComponentManager>;

    /// Returns the entity type manager.
    fn get_entity_type_manager(&self) -> Arc<dyn EntityTypeManager>;

    /// Returns the relation type manager.
    fn get_relation_type_manager(&self) -> Arc<dyn RelationTypeManager>;

    /// Returns the entity instance manager.
    fn get_entity_instance_manager(&self) -> Arc<dyn EntityInstanceManager>;

    /// Returns the relation instance manager.
    fn get_relation_instance_manager(&self) -> Arc<dyn RelationInstanceManager>;

    /// Returns the flow manager.
    fn get_flow_manager(&self) -> Arc<dyn FlowManager>;
}
}

Make use of the plugin context

The plugin have to store a reference to the plugin context. Therefore, you have to implement the method set_context which is called during initialization:

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {
    fn set_context(&self, context: Arc<dyn PluginContext>) -> Result<(), PluginError> {
        self.context.0.write().unwrap().replace(context);
        Ok(())
    }
}
}

If you want to make use of the EntityInstanceManager you have to:

1. Get a RwLock on the context
2. Get a reference of the EntityInstanceManager using get_entity_instance_manager
3. Create the entity instance using a builder (non-reactive)
4. Create/register the entity instance using create returns a reactive entity instance

#![allow(unused)]
fn main() {
impl TestManager {
    fn create_entity(&self) {
        let reader = self.context.0.read().unwrap();
        let entity_instance_manager = reader.as_ref().unwrap().get_entity_instance_manager().clone();
        let entity_instance = EntityInstanceBuilder::new("entity_type_name")
            .property("property_name", json!("property_value"))
            .get();
        let reactive_entity_instance = entity_instance_manager.create(entity_instance);
    }
}
}

Implement or ignore providers

If your plugin provide components you have to return a reference of the ComponentProvider:

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {
    fn get_component_provider(&self) -> Result<Arc<dyn ComponentProvider>, PluginError> {
        let component_provider = self.component_provider.clone();
        let component_provider: Result<Arc<dyn ComponentProvider>, _> = <dyn query_interface::Object>::query_arc(component_provider);
        if component_provider.is_err() {
            return Err(PluginError::NoComponentProvider);
        }
        Ok(component_provider.unwrap())
    }
}
}

If your plugin doesn’t provide components:

#![allow(unused)]
fn main() {
impl Plugin for ComparisonPluginImpl {
    fn get_component_provider(&self) -> Result<Arc<dyn ComponentProvider>, PluginError> {
        Err(PluginError::NoComponentProvider)
    }
}
}

The same applies to all other providers:

• ComponentProvider
• EntityTypeProvider
• RelationTypeProvider
• EntityBehaviourProvider
• RelationBehaviourProvider
• FlowProvider
• WebResourceProvider

Component Provider

Plugins can implement the trait ComponentProvider in order to register components during initialization of the plugin.

Trait ComponentProvider

#![allow(unused)]
fn main() {
impl ComponentProvider for ExampleComponentProviderImpl {
    fn get_components(&self) -> Vec<Component> {
        // Return a vector of components
    }
}
}

Use cases

• Read Components from external JSON-file from a specific location
• Build JSON-file into plugin binary using RustEmbed
• Programmatically create Components

Entity Type Provider

Plugins can implement the trait EntityTypeProvider in order to register entity types during initialization of the plugin.

Trait EntityTypeProvider

#![allow(unused)]
fn main() {
impl EntityTypeProvider for ExampleEntityTypeProviderProviderImpl {
    fn get_entity_types(&self) -> Vec<EntityType> {
        // Return a vector of entity types
    }
}
}

Use cases

• Read EntityTypes from external JSON-file from a specific location
• Build JSON-file into plugin binary using RustEmbed
• Programmatically create EntityTypes

Relation Type Provider

Plugins can implement the trait RelationTypeProvider in order to register relation types during initialization of the plugin.

Trait RelationTypeProvider

#![allow(unused)]
fn main() {
impl RelationTypeProvider for ExampleRelationTypeProviderProviderImpl {
    fn get_relation_types(&self) -> Vec<RelationType> {
        // Return a vector of relation types
    }
}
}

Use cases

• Read RelationTypes from external JSON-file from a specific location
• Build JSON-file into plugin binary using RustEmbed
• Programmatically create RelationTypes

Flow Provider

Plugins can implement the trait FlowProvider in order to create a flow during initialization of the plugin.

Trait FlowProvider

#![allow(unused)]
fn main() {
impl FlowProvider for ExampleFlowProviderProviderImpl {
    fn get_flows(&self) -> Vec<Flow> {
        // Return a vector of flows
    }
}
}

Use cases

• Read Flows from external JSON-file from a specific location
• Build JSON-file into plugin binary using RustEmbed
• Programmatically create Flows

Component Behaviour Provider

Entity Behaviour Provider

Trait EntityBehaviourProvider

#![allow(unused)]
fn main() {
const EXAMPLE: &'static str = "example";

pub struct ExampleStorage(std::sync::RwLock<std::collections::HashMap<Uuid, std::sync::Arc<Example>>>);

#[provides]
fn create_example_storage() -> ExampleStorage {
    ExampleStorage(std::sync::RwLock::new(std::collections::HashMap::new()))
}

#[async_trait]
pub trait ExampleEntityBehaviourProvider: EntityBehaviourProvider + Send + Sync {
    fn create_example(&self, entity_instance: ReactiveEntity);

    fn remove_example(&self, entity_instance: ReactiveEntity);

    fn remove_by_id(&self, id: Uuid);
}

pub struct ExampleEntityBehaviourProviderImpl {
    example_behaviours: ExampleStorage,
}

interfaces!(ExampleEntityBehaviourProviderImpl: dyn EntityBehaviourProvider);

#[component]
impl ExampleEntityBehaviourProviderImpl {
    #[provides]
    fn new() -> Self {
        Self {
            example_behaviours: create_example_storage(),
        }
    }
}

#[async_trait]
#[provides]
impl ExampleEntityBehaviourProvider for ExampleEntityBehaviourProviderImpl {
    fn create_example(&self, entity_instance: ReactiveEntity) {
        let id = entity_instance.id;
        let example_behaviour = Example::new(entity_instance);
        if example_behaviour.is_ok() {
            let example_behaviour = Arc::new(example_behaviour.unwrap());
            self.example_behaviours.0.write().unwrap().insert(id, example_behaviour);
            debug!("Added behaviour {} to entity instance {}", EXAMPLE, id);
        }
    }

    fn remove_example(&self, entity_instance: ReactiveEntity) {
        self.example_behaviours.0.write().unwrap().remove(&entity_instance.id);
        debug!("Removed behaviour {} from entity instance {}", EXAMPLE, entity_instance.id);
    }

    fn remove_by_id(&self, id: Uuid) {
        if self.example_behaviours.0.write().unwrap().contains_key(&id) {
            self.example_behaviours.0.write().unwrap().remove(&id);
            debug!("Removed behaviour {} from entity instance {}", EXAMPLE, id);
        }
    }
}

impl EntityBehaviourProvider for ExampleEntityBehaviourProviderImpl {
    fn add_behaviours(&self, entity_instance: ReactiveEntity) {
        match entity_instance.clone().type_name.as_str() {
            EXAMPLE => self.create_example(entity_instance),
            _ => {}
        }
    }

    fn remove_behaviours(&self, entity_instance: ReactiveEntity) {
        match entity_instance.clone().type_name.as_str() {
            EXAMPLE => self.remove_example(entity_instance),
            _ => {}
        }
    }

    fn remove_behaviours_by_id(&self, id: Uuid) {
        self.remove_by_id(id);
    }
}
}

Relation Behaviour Provider

Web Resource Provider

Plugins can implement the trait WebResourceProvider in order to register handlers for endpoints.

Use Cases

• Deliver static files & web applications
• Provide REST endpoints

Trait WebResourceProvider

#![allow(unused)]
fn main() {
impl WebResourceProvider for ExampleWebResourceProviderImpl {
    fn get_context_path(&self) -> String {
        String::from("example")
    }

    fn handle_web_resource(
        &self,
        path: String,
        _request: Request<HttpBody>,
    ) -> Result<Response<HttpBody>> {
        let asset = FlowEditorWebResourceAsset::get(path.as_ref());
        match asset {
            Some(asset) => {
                let body: HttpBody = match asset.data {
                    Cow::Borrowed(bytes) => HttpBody::Binary(bytes.to_vec()),
                    Cow::Owned(bytes) => HttpBody::Binary(bytes.to_vec()),
                };
                let mime_type = from_path(path.as_str()).first_or_octet_stream();
                Response::builder()
                    .status(StatusCode::OK)
                    .header(CONTENT_TYPE, mime_type.to_string())
                    .body(body)
            }
            None => Response::builder()
                .status(StatusCode::NOT_FOUND)
                .body(HttpBody::None),
        }
    }
}
}

Plugins

Plugin Arithmetic

This plugin provides arithmetic gates and operations.

Components

Entity Types

| | add | arithmetic_gate | lhs | number | input | Addition | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | counter | action | trigger | bool | input | If triggered, the result will be incremented by 1 | | | action | result | number | output | | | | decrement | arithmetic_operation | lhs | number | input | Decrements the input by 1 | | | arithmetic_operation | result | number | output | | | | div | arithmetic_gate | lhs | number | input | Division | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | increment | arithmetic_operation | lhs | number | input | Increments the input by 1 | | | arithmetic_operation | result | number | output | | | | max | arithmetic_gate | lhs | number | input | Max value | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | min | arithmetic_gate | lhs | number | input | Min value | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | mod | arithmetic_gate | lhs | number | input | Modulo | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | mul | arithmetic_gate | lhs | number | input | Multiplication | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | | | | sub | arithmetic_gate | lhs | number | input | Subtraction | | | arithmetic_gate | rhs | number | input | | | | arithmetic_gate | result | number | output | |

Platform Compatibility

Repository

Usage

Asset

Platform Compatibility

Repository

Usage

Plugin Base

Basic components and entity types.

Components

Entity Types

Platform Compatibility

Repository

Plugin Binary

This plugin provides two entity types for loading binary data from a file into a property as a Data-URL with BASE64 encoding and for storing da property which contains a Data-URL with BASE64 encoding into a file.

This is the base for loading textures, sounds, maps and any other type of binary data.

Data URL

Example of a data URL:

data:image/png;base64,
iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGP
C/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IA
AAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBHSU1Q72QlbgAAAF1J
REFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jq
ch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0
vr4MkhoXe0rZigAAAABJRU5ErkJggg==

Components

Entity Types

Feed the streams with binary data from files.

Web Resources

Download binary resources via HTTP.

Examples

Platform Compatibility

Repository

Resources

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs

Usage

Plugin Comparison

Components

Entity Types

Platform Compatibility

Repository

Usage

Plugin Config

Read configuration files (TOML) into an entity instance.

Entity Types

Platform Compatibility

Repository

Usage

Usage (GraphQL)

Read in a configuration

mutation {
  instances {
    entities {
      create(
        type: "config_file"
        id: "aed6c9b0-e495-4423-baeb-5597b66416f4"
        properties: [
          {
            name: "filename"
            value: "config/plugins.toml"
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "filename"
            "configuration"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Get all configurations

query getAllConfigs {
  instances {
    entities(type: "config_file") {
      id
      label
      description
      properties {
        name
        value
      }
    }
  }
}

“Reload” a configuration

By triggering the property `filename’ the configuration file will be read again:

mutation reloadPluginsConfig {
  instances {
    entities {
      update(
        id: "aed6c9b0-e495-4423-baeb-5597b66416f4",
        properties: [
          {
            name: "filename",
            value: "config/plugins.toml"
          }
        ]
      ) {
        id
        type {
          name
        }
        properties {
          name
          value
        }
      }
    }
  }
}

Plugin Connector

What is a Connector?

A connector connects a property of the outbound entity instance with a property of the inbound entity instance and propagates the changes of the value.

During propagation a propagation function is called. The propagation function has one single input (the incoming value). Connectors of different types has different propagation functions.

The propagation function can only do simple things (like casting or logging) but in fact even these simple operations makes the control flow much simpler and much more readable.

How does a connector work?

The connector is a relation instance which connects two entity instances. The relation itself stores the names of the output property and the input property.

In theory, it’s also possible to connect two properties of the same entity instance.

On construction the streams are connected.

On destruction of the connector, the stream will be removed.

Warning

1. Connecting properties of the same entity instance is discouraged to prevent feedback loops
2. No type checks are performed on construction (yet; you are responsible)
3. There is no check about feedback loops (yet; you are responsible)
4. Renaming the relation properties (outbound_property_name, inbound_property_name) doesn’t have any effect (yet). You have to remove the old connector and recreate a new connector.

Components

Relation Types

Future: More (useful) connectors

Platform Compatibility

Repository

Usage

Usage

GraphQL: Create a new connector

mutation {
  instances {
    relations {
      createConnector: create(
        edgeKey: {
          outboundId: "dc82735e-28ec-4c24-aedb-d968b73b288f",
          typeName: "default_connector--value--value"
          inboundId: "4cf8e6d8-f92e-4ffa-9610-ec0635f55e08",
        },
        properties: [
          {
            name: "outbound_property_name",
            value: "value"
          },
          {
            name: "inbound_property_name",
            value: "value"
          }
        ]
      ) {
        type {
          name
          fullName
        },
        properties(
          names: [
            "outbound_property_name",
            "inbound_property_name"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Plugin GraphQL Client

This plugin provides a web based GraphQL client.

Tip

This plugin uses Altair. Altair GraphQL Client helps you debug GraphQL queries and implementations - taking care of the hard part so you can focus on actually getting things done. Btw: You can also use Altair as standalone application or as firefox addon.

Platform Compatibility

Repositories

Plugin GraphQL Schema Visualization

This plugin represents the GraphQL API as an interactive graph.

| | http://hostname:31415/graphql-schema-visualization/graph/query | GraphQL API | Queries | | http://hostname:31415/graphql-schema-visualization/graph/mutation | GraphQL API | Mutations | | http://hostname:31415/graphql-schema-visualization/graph/subscription | GraphQL API | Subscriptions | | | http://hostname:31415/graphql-schema-visualization/dynamic-graph/query | Dynamic Graph API | Queries | | http://hostname:31415/graphql-schema-visualization/dynamic-graph/mutation | Dynamic Graph API | Mutations | | http://hostname:31415/graphql-schema-visualization/dynamic-graph/subscription | Dynamic Graph API | Subscriptions |

Platform Compatibility

Repository

Plugin: HTTP

This plugin provides a reactive http client integration. Using entities of type http requests via HTTP can be made.

With this plugin it’s possible to integrate external services into your home automation.

Entity Types

| | jsonrpc | url | string | input | | | jsonrpc_version | string | input | | | method | string | none | | | params | object | input | | | result | object | output | | | error | object | output |

Platform Compatibility

Repository

Usage

Usage

GraphQL

Create HTTP Request

First create an entity instance of type http and specify the URL and the method.

By creating the entity instance no request will be made. The next example explains how to execute the request.

mutation {
  instances {
    entities {
      create(
        type: "http",
        id: "a3370278-b05c-4d1a-ad57-cabd575c37e4",
        properties: [
          {
            name: "url",
            value: "https://api.sunrise-sunset.org/json?lat=47.557400&lng=9.707209&formatted=0"
          },
          {
            name: "method",
            value: "GET"
          },
          {
            name: "request_headers",
            value: {}
          },
          {
            name: "payload",
            value: {}
          },
          {
            name: "response_headers",
            value: {}
          },
          {
            name: "result",
            value: {}
          },
          {
            name: "status",
            value: 500
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "url",
            "method",
            "request_headers",
            "payload",
            "response_headers",
            "result",
            "status"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Execute HTTP Request

By triggering the property payload the HTTP request will be executed and the results will be written into the property result.

mutation {
  instances {
    entities {
      update(
        id: "a3370278-b05c-4d1a-ad57-cabd575c37e4",
        properties: [
          {
            name: "payload",
            value: {}
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "url",
            "method",
            "request_headers",
            "payload",
            "response_headers",
            "result",
            "status"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Plugin: JSON

This plugin adds functionality to operate with complex data structures. Properties of entity instances or relation instances can have different data types. It’s possible to store even complex data using the data types array and object. This is handy if you receive data from an MQTT endpoint or if you want to represent more complex data. But it makes it also necessary to unpack or pack these data in order to operate with it.

Entity Types

Platform Compatibility

Repository

Usage

Plugin Logical

This plugin provides logical gates and operations.

Components

Entity Types

Platform Compatibility

Repository

Usage

Plugin Meta Data

This plugin provides generic components for meta data.

Components

Platform Compatibility

Repositories

Usage

Plugin: Notification

Create desktop notifications.

Entity Types

Platform Compatibility

Repository

Usage

GraphQL

Create Desktop Notification

mutation {
  instances {
    entities {
      create(
        type: "desktop_notification",
        id: "dfe30808-9242-4af8-aced-556ffe617038",
        properties: [
          {
            name: "show",
            value: false
          },
          {
            name: "body",
            value: "Test"
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "show",
            "app_name",
            "summary",
            "body",
            "icon",
            "timeout"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Show Desktop Notification

The property show=true triggers the notification.

mutation {
  instances {
    entities {
      update(
        id: "dfe30808-9242-4af8-aced-556ffe617038",
        properties: [
          {
            name: "show",
            value: true
          },
          {
            name: "summary",
            value: "Important Message"
          },
          {
            name: "body",
            value: "Lorem Ipsum"
          },
          {
            name: "icon",
            value: "computer"
          },
          {
            name: "timeout",
            value: 1000
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "show",
            "app_name",
            "summary",
            "body",
            "icon",
            "timeout"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Plugin: Numeric

Numeric operations

Components

Entity Types

Platform Compatibility

Repository

Usage

Plugin: Random

Generate random numbers, strings, UUIDs or booleans.

Entity Types

Platform Compatibility

Repository

Usage

Plugin: State

This plugin provides state components. States extends values with debounce mechanism. States are important for several use cases, for example user interfaces and digital twins.

State Management

The state management is an essential part of controlling external things which can change it’s state by itself. An example is a user interface checkbox, which can be toggled by the user. The state of the checkbox should be reflected in the state property. On the other hand, the reactive graph flow should be able to change the state which should be reflected by the user interface checkbox. This double-binding requires that the old internal state is stored and the new state is compared with the old state. Debouncing the state is necessary to prevent feedback loops and undefined behaviour.

Use Cases

• User Interfaces: Checkboxes, Switches, …
• States on remote systems (HTTP, GraphQL, MQTT)
• Digital Twins

Components

Entity Types

Platform Compatibility

Repositories

Plugin: Scheduler

Timers and scheduled jobs

Scheduled Jobs

A scheduled job triggers periodically using a cron expression.

Cron Expression

Comma separated values such as 5,8,10 represent more than one time value. So for example, a schedule of 0 2,14,26 * * * * would execute on the 2nd, 14th, and 26th minute of every hour.

Ranges can be specified with a dash. A schedule of 0 0 * 5-10 * * would execute once per hour but only on day 5 through 10 of the month.

Day of the week can be specified as an abbreviation or the full name. A schedule of 0 0 6 * * Sun,Sat would execute at 6am on Sunday and Saturday.

Note that the year may be omitted.

Examples

Timers

A timer triggers after a given duration. The duration can be specified either as a number in milliseconds or as a string in ISO 8601 Duration Format.

ISO 8601 Duration Format

Note

What is the ISO 8601 Duration Format?

Durations define the amount of intervening time in a time interval and are represented by the format P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W. In these representations, the [n] is replaced by the value for each of the date and time elements that follow the [n]. Leading zeros are not required, but the maximum number of digits for each element should be agreed to by the communicating parties. The capital letters P, Y, M, W, D, T, H, M, and S are designators for each of the date and time elements and are not replaced.

https://en.wikipedia.org/wiki/ISO_8601#Durations

Designators

Examples

Entity Types

Platform Compatibility

Repositories

Usage

Usage

GraphQL: Create a new timer

mutation {
  instances {
    entities {
      create(
        type: "timer",
        id: "46e2ecd0-3e91-4205-99c9-d9543923a73a",
        properties: [
          {
            name: "duration",
            value: 1000
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "duration",
            "trigger"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

GraphQL: Update duration of an existing timer

mutation {
  instances {
    entities {
      update(
        id: "46e2ecd0-3e91-4205-99c9-d9543923a73a",
        properties: [
          {
            name: "duration",
            value: 1500
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "duration",
            "trigger"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Plugin: String

Components

Entity Types / Behaviours

Rust Crate / Rust Reference

• https://doc.rust-lang.org/std/string/struct.String.html
• https://docs.rs/voca_rs/latest/voca_rs/index.html

Platform Compatibility

Repository

Usage

Plugin: System Command

This plugin enables system commands to be executed. This is useful in home automation applications, e.g. if you want to control a headless Raspberry Pi Zero.

It can be configured in which directory the system command is executed.

A system command is executed by triggering (i.e. changing) the spawn property. Please see the GraphQL example.

When a program runs, it writes to stdout and stderr. These outputs are available in the corresponding properties after the program has ended.

Warning

Only activate the plugin if you know what you are doing. Do not run the Reactive Graph Flow as root user, because the system command will be executed as the same user! The GraphQL endpoint should also be specially protected.

Entity Types

Usage

GraphQL: Create System Command “List Current Directory”

The system command is only generated but not yet executed.

mutation {
  instances {
    entities {
      create(
        type: "system_command",
        id: "57cd91ba-b437-4ba9-b274-b5e1ad4abbe5",
        properties: [
          {
            name: "name",
            value: "List files in the current directory"
          },
          {
            name: "current_dir",
            value: "."
          },
          {
            name: "command",
            value: "ls"
          },
          {
            name: "spawn",
            value: []
          },
          {
            name: "stdin",
            value: ""
          },
          {
            name: "stdout",
            value: ""
          },
          {
            name: "stderr",
            value: ""
          }
        ]
      ) {
        id,
        type {name},
        properties(
          names: [
            "name",
            "current_dir",
            "command",
            "spawn",
            "stdin",
            "stdout",
            "stderr"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

GraphQL: Execute System Command “List Current Directory”

A system command is executed when the property spawn is changed. This property expects an array with arguments. If the command is to be executed without arguments, an empty array can be passed.

mutation {
  instances {
    entities {
      update(
        id: "57cd91ba-b437-4ba9-b274-b5e1ad4abbe5",
        properties: [
          {
            name: "spawn",
            value: [
              "-l",
              "-a"
            ]
          }
        ]
      ) {
        id,
        type {name},
        properties(
          names: [
            "name",
            "current_dir",
            "command",
            "spawn",
            "stdin",
            "stdout",
            "stderr"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Platform Compatibility

Repository

Plugin: System Environment

The plugin creates entity instances for each environment variable. As environment variables doesn’t change at runtime this happens only at initialization.

UUIDs

Note

The UUIDs of the entity instances are stable.

Labels

Each entity instance which represents a system environment variable has a label.

Entity Types

Platform Compatibility

Repository

Usage

Plugin: Taxonomy

This plugin provides a generic taxonomy system with categories and tags.

Use Cases

• Categorization of assets
• Categorization of servers
• Categorization of teams

Categories and Tagging

Components

Entity Types

Relation Types

Platform Compatibility

Repositories

Usage

Plugin: Value

This plugin provides value components. Value components contains a single property of a specific data type. State components build on value components.

Components

Entity Types

Platform Compatibility

Repositories

See also

• States

Events

Events are (of course!) represented as reactive entity instances that have a component event. Since Reactive Graph is already a reactive system it wouldn’t make sense to implement another event system. So, basically the events are conventions rather than implementation.

Component

Entity types or relation types can be composed with the component event in order to have an property event.

Events: System Events

System events are events that are emitted by the system itself. There is no other way to get this information than through these events.

Entity Types

Types of Events

Subscribing to these events is easily possible with a label.

GraphQL Subscription

It is possible to subscribe to these events via GraphQL subscription.

Instead of subscribing multiple events directly you can zip multiple events and subscribe to the result.

Get new components

subscription getSystemEventComponentCreated {
  entity(label: "/io/reactive-graph/event/type/component/created", propertyName: "event") {
    name
    value
    type {
      dataType
      socketType
    }
  }
}

Get which components have been deleted

subscription getSystemEventComponentDeleted {
  entity(label: "/io/reactive-graph/event/type/component/deleted", propertyName: "event") {
    name
    value
    type {
      dataType
      socketType
    }
  }
}

Get new flows

subscription getSystemEventFlowCreated {
  entity(label: "/io/reactive-graph/event/instance/flow/created", propertyName: "event") {
    name
    value
    type {
      dataType
      socketType
    }
  }
}

Get which flows have been deleted

subscription getSystemEventCFlowDeleted {
  entity(label: "/io/reactive-graph/event/instance/flow/deleted", propertyName: "event") {
    name
    value
    type {
      dataType
      socketType
    }
  }
}

Events: Shutdown

Shutting down

GraphQL

mutation {
  instances {
    entities {
      update(
        label: "/io/reactive-graph/commands/core/shutdown"
        properties: [
          {
            name: "shutdown"
            value: 5
          }
        ]
      ) {
        id
        type {
          name
        }
        properties(
          names: [
            "shutdown"
          ]
        ) {
          name
          value
        }
      }
    }
  }
}

Reactive Graph Patterns

Reactive Graph Flow allows the best of three worlds:

• Graph Databases => Graph Patterns
• Flow Control System => Flow Patterns

Generators and Actions

flowchart LR
    subgraph Generator
      trigger_1(trigger)
    end
    subgraph Action
      trigger_2(trigger)
    end
    trigger_1--->trigger_2

What is a generator?

A generator produces boolean trues and sends them via the output property trigger.

There are many types of generators:

• A periodic timer
• A scheduler
• A changed file on the filesystem (fs_notify)
• A random bool generator
• An user which has pressed a button on the user interface
• A physical event from an input device like a keystroke

What is a action?

A action is something which should be executed or processed only and only if the input property trigger receives a boolean true.

Combine triggers and actions within a single entity using components

An entity instance can have multiple components.

For example, you can combine file with fs_notify and load_binary.

By doing so, the trigger property is both:

• A generator: The component fs_notify fires trigger when the file has been modified on the filesystem
• A action: The component load_binary gets triggered immediately and loads the content of the file into a property

This example shows the great possibilities of the component system and how to use the generator-action-system. By combining components into one single entity instance, the behaviour of the entity instance can get more complex. At the same time a flow is more compact.

Another example is to combine a user-interface-button as generator with an update-the-asset-repository as an action.

flowchart LR
    subgraph entity[Entity]
        direction LR
        subgraph action
          trigger
        end
        subgraph fs_notify
          file[(File)]
        end
        subgraph load_binary
          binary_data
        end
    end
    file -->|behaviour: fs_notify| trigger
    trigger -->|behaviour: load_binary_data| binary_data

Time Series

flowchart TB

  subgraph g2024[ ]
    direction TB

    2022
    2022_jan(Jan)
    2022_feb(Feb)
    2022_next(...)
    2022_nov(Nov)
    2022_dec(Dec)

    2023
    2023_jan(Jan)
    2023_feb(Feb)
    2023_next(...)
    2023_nov(Nov)
    2023_dec(Dec)

    2024
    2024_jan(Jan)
    2024_feb(Feb)
    2024_next(...)
    2024_nov(Nov)
    2024_dec(Dec)

  end


  2022 -->|next_year| 2023
  2023 -->|next_year| 2024

  2022 -->|first_month| 2022_jan
  2022 -->|last_month| 2022_dec

  2023 -->|first_month| 2023_jan
  2023 -->|last_month| 2023_dec

  2024 -->|first_month| 2024_jan
  2024 -->|last_month| 2024_dec

  2022_jan -->|next_month| 2022_feb
  2022_feb -->|next_month| 2022_next
  2022_next -->|next_month| 2022_nov
  2022_nov -->|next_month| 2022_dec
  2022_dec -->|next_month| 2023_jan
  2023_jan -->|next_month| 2023_feb
  2023_feb -->|next_month| 2023_next
  2023_next -->|next_month| 2023_nov
  2023_nov -->|next_month| 2023_dec
  2023_dec -->|next_month| 2024_jan
  2024_jan -->|next_month| 2024_feb
  2024_feb -->|next_month| 2024_next
  2024_next -->|next_month| 2024_nov
  2024_nov -->|next_month| 2024_dec

System Architecture

In this document we describe…

• which components exists
• what they are doing
• how they are used
• and which use cases they fulfill

Components

First things first: It’s important to understand which component is responsible for which task and how they are connected.

Reactive Graph Client API reactive_graph_client

The Client API (reactive_graph_client) is a rust crate which can be used to communicate with a runtime via it’s GraphQL API. Instead of writing GraphQL queries one just have to call a (rust) method of the Client API.

GraphQL Server reactive_graph_server

The GraphQL Server is part of the standalone executable. It is integrated in a HTTP webserver and accepts requests with GraphQL queries and mutations. The GraphQL Server calls the GraphQL Query Service of the runtime.

GraphQL Query Service reactive-graph-graphql-api

The GraphQL Query Service is part of the runtime. It can be used to execute GraphQL queries and mutations. The GraphQL Query Service uses the GraphQL API.

GraphQL API reactive-graph-graphql-web

The GraphQL API is part of the runtime. The GraphQL API encapsulates calls to the APIs of the Type System API, the Instance System API and the System API in GraphQL resolvers. It converts internal data structures to and from the types of the GraphQL schema.

Type System API reactive-graph-type-system-api

The Type System API is part of the runtime. It manages the type system, allows to create, read, update and delete types of the reactive graph. You can manage components, entity types, relation types and flow types.

Instance System API reactive-graph-instance-system-api

The Instance System API is part of the runtime. It manages the reactive instances, allows to create, read, update and delete reactive instances within the Reactive Graph. You can manage entity instances, relation instances (including flow connectors) and flow instances.

Runtime Service API reactive-graph-runtime-service-api

The System API is part of the runtime. It manages commands, plugins, the instance information and remote instances.

Command Line Interface API reactive-graph

The Command Line Interface API (CLI) is part of the standalone executable.

It is possible to use the standalone executable as

• Server (GraphQL Server + Runtime)
• Client (CLI)

The CLI uses the Client API to communicate via GraphQL with a runtime. You can specify the hostname and port of the runtime to connect to.

Use Cases

The components can be used for different use cases:

• Command Line Interface within the standalone executable
• Embed the runtime reactive-graph-runtime-api in your application
• Communicate from one runtime to another
• Let your application communicate with a (remote) runtime
• Integration tests

Command Line Interface reactive-graph

The executable can act as CLI. The CLI can connect to any Reactive Graph GraphQL Server (local or remote). You can specify to hostname and port of the GraphQL server to connect to.

graph TD
subgraph Command Line Interface[ ]
    USR([User])
    
    subgraph Reactive Graph Client
      direction LR
      CLI[Command Line Interface]
      subgraph `reactive_graph_client`
        CA(Client API)
      end
      subgraph `reactive_graph_client`[reactive_graph_runtime]
        UNUSED(Unused if in CLI mode)
      end
    end

    subgraph Reactive Graph Server
      GS[GraphQL Server]
      subgraph `reactive_graph_server`[reactive_graph_runtime]
        GQS[GraphQL Query Service]
        GA[GraphQL API]
        TSA[Type System API]
        ISA[Instance System API]
        SYSA[System API]
      end
    end
    
    USR -->|command| CLI
    CLI -->|call| CA
    CA -->|query| GS
    GS -->|query| GQS
    GQS --->|query| GA
    GA --->|call| TSA
    GA --->|call| ISA
    GA --->|call| SYSA
end

Embedded runtime in an application reactive-graph-runtime-service-api

Any rust application can embed the Reactive Graph runtime (reactive-graph-runtime-service-api).

The following diagram shows that the application can:

• Call the Type System API, Instance System API and System API directly via the runtime.
• Execute GraphQL queries or mutations via the GraphQL Query Service.

graph TD
subgraph Embedded Runtime[ ]

  subgraph Application
    direction TB
  
    SRV1[Application's Service 1]
    SRV2[Application's Service 2]
  
    subgraph "reactive_graph_runtime"
      GQS[GraphQL Query Service]
      GA[GraphQL API]
      TSA[Type System API]
      ISA[Instance System API]
      SYSA[System API]
    end
  end

  GQS -->|query| GA
  GA --->|call| TSA
  GA --->|call| ISA
  GA --->|call| SYSA

  SRV1 -->|call| TSA
  SRV1 -->|call| ISA
  SRV1 -->|query| GQS
  SRV2 -->|call| TSA
  SRV2 -->|call| ISA
  SRV2 -->|query| GQS

end

Communicate from the runtime with another runtime

In order to communicate from one runtime to another runtime you can use the Reactive Graph Client (reactive_graph_client).

In this example two runtimes are calling methods of the own runtime and execute queries on the other runtime via the Reactive Graph Client.

graph TD
subgraph RuntimeToRuntime[ ]
  direction LR

  subgraph "Runtime 1"
    direction TB
  
    SRV1_1[Service 1]
    SRV1_2[Service 2]
  
    subgraph "reactive_graph_runtime_1"[reactive_graph_runtime]
      GQS1[GraphQL Query Service]
      GA1[GraphQL API]
      TSA1[Type System API]
      ISA1[Instance System API]
      SYSA1[System API]
    end
    
    subgraph "reactive_graph_client_1"[reactive_graph_client]
      CA1(Client API)
    end

  end

  subgraph "Runtime 2"
    direction TB
    
    SRV2_1[Service 1]
    SRV2_2[Service 2]
  
    subgraph "reactive_graph_runtime_2"[reactive_graph_runtime]
      GQS2[GraphQL Query Service]
      GA2[GraphQL API]
      TSA2[Type System API]
      ISA2[Instance System API]
      SYSA2[System API]
    end
    
    subgraph "reactive_graph_client_2"[reactive_graph_client]
      CA2(Client API)
    end
  end

  GQS1 -->|query| GA1
  GA1 --->|call| TSA1
  GA1 --->|call| ISA1
  GA1 --->|call| SYSA1
  CA1 -->|query| GQS2
  SRV1_1 -->|call| TSA1
  SRV1_1 -->|query| CA1
  SRV1_2 -->|call| ISA1
  SRV1_2 -->|query| CA1

  GQS2 -->|query| GA2
  GA2 --->|call| TSA2
  GA2 --->|call| ISA2
  GA2 --->|call| SYSA2
  CA2 -->|query| GQS1
  SRV2_1 -->|call| TSA2
  SRV2_1 -->|query| CA2
  SRV2_2 -->|call| ISA2
  SRV2_2 -->|query| CA2

end

The same applies to two applications which have embedded runtimes.

Let your application communicate with a (remote) runtime

In order to communicate from your application to a (remote) runtime you can use the Reactive Graph Client (reactive_graph_client).

This example shows the application which uses the Reactive Graph Client to execute queries on the (remote) runtime:

graph TD
subgraph ApplicationToRuntime[ ]
  direction LR

  subgraph "Application"
    direction TB
  
    SRV1[Service 1]
    SRV2[Service 2]
  
    subgraph "reactive_graph_client_1"[reactive_graph_client]
      CA(Client API)
    end

  end

  subgraph Reactive Graph Server
    direction TB
    GS[GraphQL Server]
    subgraph reactive_graph_runtime
      GQS[GraphQL Query Service]
      GA[GraphQL API]
      TSA[Type System API]
      ISA[Instance System API]
      SYSA[System API]
    end
  end

  SRV1 -->|call| CA
  SRV2 -->|call| CA
  CA -->|query| GS
  GS -->|query| GQS
  GQS -->|query| GA
  GA --->|call| TSA
  GA --->|call| ISA
  GA --->|call| SYSA
end

Integration Tests

An integration test verifies the correctness of:

• The Client API, because the Integration Test calls methods of the Client API.
• The GraphQL API, because the Client API queries the GraphQL API.
• The GraphQL API, because the Integration Test queries the GraphQL API of a started runtime directly.
• The APIs of the runtime, because the GraphQL API calls methods of the runtime.
• The APIs of the runtime, because the Integration Test calls methods of a started runtime directly.

graph TD
subgraph Integration Tests[ ]

  IT[Integration Test]
  CA(Client API)
  style IT fill:#333,stroke:#633,stroke-width:4px,margin-top:10px

  subgraph "reactive_graph_runtime"
    GQS[GraphQL Query Service]
    GA[GraphQL API]
    TSA[Type System API]
    ISA[Instance System API]
    SYSA[System API]
  end

  subgraph "reactive_graph_client"
    CA -->|query| GQS
  end

  IT -->|call| CA
  IT --->|query| GQS
  IT -->|call| TSA
  IT -->|call| ISA

  GQS -->|query| GA
  GA --->|call| TSA
  GA --->|call| ISA
  GA --->|call| SYSA

  IT -->|call| SYSA

end

Application Programming Interface

• Builders
• RuntimeBuilder

Builders

The builder pattern is useful when you would otherwise require many constructors or where construction has side effects.

Component Builder

Constructs a new component programmatically.

#![allow(unused)]
fn main() {
fn build_component() -> Component {
    ComponentBuilder::new("namespace", "component_name")
        .description("A test component with several properties")
        // Provide properties
        .property("property_1", DataType::String)
        .property_from(PropertyType::new("property_2", DataType::Bool))
        .string_property("property_3")
        .bool_property("property_4")
        .number_property("property_5")
        .array_property("property_6")
        .object_property("property_7")
        .input_property("property_8", DataType::Bool)
        .output_property("property_9", DataType::Bool)
        // Provide extensions
        .extension("security", json!({
            roles: [
                "ADMIN"
            ]
        }))
        .build()
}
}

Tip

The component is not yet registered. Register the component using ComponentManager::register

Entity Type Builder

Constructs a new entity type programmatically.

#![allow(unused)]
fn main() {
fn build_entity_type() -> EntityType {
    EntityTypeBuilder::new("namespace", "entity_type_name")
        .description("A test entity type")
        // Compose with the labeled component
        .component("labeled")
        // Provide additional properties
        .property("property_1", DataType::String)
        .property_from(PropertyType::new("property_2", DataType::Bool))
        .string_property("property_3")
        .bool_property("property_4")
        .number_property("property_5")
        .input_property("property_6", DataType::Bool)
        .output_property("property_7", DataType::Bool)
        // Provide extensions
        .extension("usage", json!("ls [OPTION]... [FILE]..."))
        .build()
}
}

Tip

The entity type is not yet registered. Register the entity type using EntityTypeManager::register

Relation Type Builder

Constructs a new relation type programmatically.

#![allow(unused)]
fn main() {
fn build_relation_type() -> RelationType {
    RelationTypeBuilder::new(
        // Outbound Entity Type
        "teleport",
        // Relation Type Name
        "teleports_to",
        // Inbound Entity Type
        "tele_destination"
    )
        .description("A relation type which connects a teleport with a tele destination. The property weight defines the probability")
        // Compose with the weighted component
        .component("weighted")
        // Provide additional properties
        .property("property_1", DataType::String)
        .property_from(PropertyType::new("property_2", DataType::Bool))
        .string_property("property_3")
        .bool_property("property_4")
        .number_property("property_5")
        .input_property("property_6", DataType::Bool)
        .output_property("property_7", DataType::Bool)
        // Provide extensions
        .extension("flow_arrow_color", json!("#ff7700"))
        .extension("flow_arrow_labeling", json!("teleports from {outbound.name} to {inbound.name}"))
        .build()
}
}

Tip

The relation type is not yet registered. Register the relation type using RelationTypeManager::register

Entity Instance Builder

Constructs a new entity instance programmatically. This is the non-reactive variant.

#![allow(unused)]
fn main() {
fn build_entity_instance(type_name: String) -> EntityInstance {
    EntityInstanceBuilder::new(type_name)
        .id(id)
        .property("property_1", json!("value_1"))
        .get()
}

fn build_entity_instance_from_type(entity_type: EntityType) -> EntityInstance {
    EntityInstanceBuilder::from(entity_type)
        .id(id)
        .property("property_1", json!("value_1"))
        .get()
}
}

Tip

The entity instance is non-reactive and not yet registered. Create a reactive instance and register it using ReactiveEntityManager::create_reactive_instance

Relation Instance Builder

Constructs a new relation instance programmatically. This is the non-reactive variant.

Tip

The relation instance is non-reactive and not yet registered. Create a reactive instance and register it using ReactiveRelationManager::create_reactive_instance

Reactive Entity Instance Builder

Constructs a new reactive entity instance programmatically.

Tip

The reactive entity instance is fully functional, but not yet registered. Register the reactive entity instance using ReactiveEntityManager::register_reactive_instance

Reactive Relation Instance Builder

Constructs a new reactive relation instance programmatically.

Tip

The reactive relation instance is fully functional, but not yet registered. Register the reactive relation instance using ReactiveRelationManager::register_reactive_instance

Flow Builder

Runtime Builder

The RuntimeBuilder is a builder for reactive_graph_runtime_api.

Tip

Read about the use cases of the RuntimeBuilder in System Architecture.

States

The RuntimeBuilder is stateful:

stateDiagram-v2
    [*] --> SetConfigLocations
    SetConfigLocations --> SetConfigLocations : Set config file locations
    SetConfigLocations --> ConfigFilesLoaded : load_config_files()
    SetConfigLocations --> ConfigFilesLoaded : ignore_config_files()
    ConfigFilesLoaded --> ConfigFilesLoaded : Set / overwrite config options
    ConfigFilesLoaded --> Initialized : init
    ConfigFilesLoaded --> Shutdown : block_on
    Initialized --> Ready : post_init
    Ready --> Ready : with_runtime
    Ready --> Running : spawn
    Ready --> Finished : spawn_blocking
    Ready --> Finished : run_for
    Ready --> Finished : do_no_run
    Running --> Running : with_runtime
    Running --> Finished : stop
    Running --> Finished : wait_for_stopped
    Finished --> Finished : with_runtime
    Finished --> PreShutdown : pre_shutdown
    PreShutdown --> Shutdown : shutdown
    Shutdown --> Shutdown : wait_for
    Shutdown --> [*]

SetConfigLocations

In this state it is possible to configure the locations of the config files or to skip loading config files at all.

Methods

• instance_config(path) sets the location of the instance configuration
• graphql_server_config(path) sets the location of the graphql server configuration
• plugins_config(path) sets the location of the plugins configuration

Transitions

• Transition load_config_files loads the config files and transits to state ConfigFilesLoaded. This is used in the executable.
• Transition ignore_config_files doesn’t load the config files and transits to state ConfigFilesLoaded. This is useful for integration tests and hard coded initialization.

ConfigFilesLoaded

In this state either the defaults are set or the the config files are loaded. The RuntimeBuilder can be used to overwrite configurations or defaults.

Methods

• instance_name() sets the name of the instance.
• instance_description() sets the description of the instance.
• hostname() sets the hostname of the GraphQL server.
• port() sets the port number of the GraphQL server
• pick_free_port() picks a free port instead of a fixed port number. This is useful for integration tests or temporary applications
• secure() sets if the GraphQL server shall use https or http
• shutdown_timeout() sets timeout of the shutdown of the GraphQL server
• workers() sets the number of workers of the GraphQL server
• default_context_path() sets context path of a web resource provider which shall be used as default context path
• disable_all_plugins() disables all plugins. This is useful for integration tests.
• disabled_plugins() sets which plugins will be disabled
• disable_hot_deploy() disables hot deployment of plugins
• hot_deploy_location() sets the directory where plugins can be hot deployed
• install_location() sets the directory where plugins are located. During hot deployment new plugins will be moved into this directory.

Transitions

• Transition init calls the init method of the runtime which will run the initialization phase of the services. Transits to state Initialized.
• Transition block_on initializes, runs and shutdowns the Runtime. After shutdown transits to state Shutdown.

Initialized

In this state the Runtime has been initialized with the init method. The next step is to run the post_init method.

Transitions

• Transition post_init calls the post_init method

Ready

In this state the Runtime has been fully initialized with the post_init method. The Runtime is now ready to be started.

Methods

• get to get the Runtime and leave the builder
• with_runtime executes a closure which can operate with the runtime. Stays in state Ready.

Transitions

• Transition spawn spawns a new green thread in which the GraphQL server will be run. This operation is non-blocking and results in a state transition to the Running state.
• Transition spawn_blocking calls the run method of the runtime which starts the GraphQL server. This operation is blocking and results in a state transition to the Finshed state after the GraphQL server has been stopped.
• Transition run_for starts the GraphQL server and spawns a new green thread that shuts down the GraphQL server after a given duration. The operation is blocking and results in a state transition to the Finshed state after the GraphQL server has been stopped by the timeout.
• Transition do_not_run does not start a GraphQL server and transits to the state Finshed. This is useful for integration tests in combination with with_runtime.

Running

In this state the GraphQL server of the Runtime is running.

Methods

• get to get the Runtime and leave the builder
• with_runtime executes a closure which can operate with the runtime. Stays in state Running.

Transitions

• stop stops the runtime. It waits for the GraphQL server to be stopped. This operation is blocking until the GraphQL server has been shutdown gracefully and results in a transition to state Finished.
• stop_with_timeout is like stop but with a timeout. In contrast to stop, it is NOT guaranteed that the GraphQL server has been stopped actually.
• wait_for_stopped waits until the GraphQL server has been stopped. This can happen by using the ShutdownManager or by sending SIGINT signal to the process. This operation is blocking and results in a transition to state Finished.
• wait_for_stopped_with_timeout is like wait_for_stopped but with a timeout. In contrast to stop, it is NOT guaranteed that the GraphQL server has been stopped actually.

Finished

In this state the GraphQL server of the Runtime is no more running (or has never been started). The services of the runtime are up und running.

Methods

• get to get the Runtime and leave the builder
• with_runtime executes a closure which can operate with the runtime. Stays in state Finished.

Transitions

• Transition pre_shutdown calls the pre_shutdown method of the Runtime and transits to state PreShutdown.

PreShutdown

In this state the services of the Runtime has executed their pre_shutdown methods. The next step is to call the shutdown method.

Transitions

• Transition shutdown calls the shutdown method of the Runtime and transits to state Shutdown.

Shutdown

In this state the services of the Runtime has executed their shutdown methods. This is the end of the lifetime of a Runtime.

Methods

• wait_for to wait for a given duration

Command Line Interface

• General Usage
• Interactive Command Line Interface
• Command Reference
• Command Reference Client
• Command Reference Server
• Command Reference Tooling

Command Line Interface - General Usage

How to use the command line interface

$ reactive-graph client [OPTIONS] [COMMAND]

Example

To get the instance information of the local server:

$ reactive-graph client instance-info get

To get the instance information of a remote server:

$ reactive-graph client --hostname=localhost --port=31415 instance-info get

Commands

Options

Command Line Interface - Interactive

The interactive mode of the command line interface supports:

• Sub-Commands are suggested
• Auto-Completion
• History
• Reverse Search

Usage

In order to start an interactive session, use the subcommand client (without any further subcommands):

$ reactive-graph client

You can also start an interactive session to a remote server by specifying the hostname and/or port:

$ reactive-graph client --hostname=<hostname> --port=<port>

Actions

For all modes:

Emacs mode (default mode)

Readline Emacs Editing Mode Cheat Sheet

vi command mode

vi insert mode

Readline vi Editing Mode Cheat Sheet

Terminal codes (ANSI/VT100)

Command-Line Help for reactive-graph

This document contains the help content for the reactive-graph command-line program.

Command Overview:

• reactive-graph↴
• reactive-graph shell-completions↴
• reactive-graph shell-completions print↴
• reactive-graph shell-completions install↴
• reactive-graph man-pages↴
• reactive-graph man-pages print↴
• reactive-graph man-pages install↴
• reactive-graph print-markdown-help↴
• reactive-graph info↴
• reactive-graph daemon↴
• reactive-graph graphql-schema↴
• reactive-graph graphql-schema reactive-graph-schema↴
• reactive-graph graphql-schema dynamic-graph-schema↴
• reactive-graph graphql-schema reactive-graph-plugin-schema↴
• reactive-graph graphql-schema reactive-graph-runtime-schema↴
• reactive-graph json-schema↴
• reactive-graph json-schema types↴
• reactive-graph json-schema types components↴
• reactive-graph json-schema types entities↴
• reactive-graph json-schema types relations↴
• reactive-graph json-schema types flows↴
• reactive-graph json-schema instances↴
• reactive-graph json-schema instances entities↴
• reactive-graph json-schema instances relations↴
• reactive-graph json-schema instances flows↴
• reactive-graph execute-command↴
• reactive-graph instance-info↴
• reactive-graph instance-info get↴
• reactive-graph plugins↴
• reactive-graph plugins list↴
• reactive-graph plugins search↴
• reactive-graph plugins get↴
• reactive-graph plugins dependencies↴
• reactive-graph plugins dependents↴
• reactive-graph plugins start↴
• reactive-graph plugins stop↴
• reactive-graph plugins restart↴
• reactive-graph plugins uninstall↴
• reactive-graph remotes↴
• reactive-graph remotes list↴
• reactive-graph remotes add↴
• reactive-graph remotes remove↴
• reactive-graph remotes remove-all↴
• reactive-graph remotes update↴
• reactive-graph remotes update-all↴
• reactive-graph remotes fetch-remotes-from-remote↴
• reactive-graph remotes fetch-remotes-from-all-remotes↴
• reactive-graph shutdown↴
• reactive-graph components↴
• reactive-graph components list↴
• reactive-graph components get↴
• reactive-graph components list-properties↴
• reactive-graph components list-extensions↴
• reactive-graph components get-json-schema↴
• reactive-graph components create↴
• reactive-graph components delete↴
• reactive-graph components add-property↴
• reactive-graph components remove-property↴
• reactive-graph components add-extension↴
• reactive-graph components remove-extension↴
• reactive-graph components update-description↴
• reactive-graph components json-schema↴
• reactive-graph entity-types↴
• reactive-graph entity-types list↴
• reactive-graph entity-types get↴
• reactive-graph entity-types list-properties↴
• reactive-graph entity-types list-extensions↴
• reactive-graph entity-types list-components↴
• reactive-graph entity-types get-json-schema↴
• reactive-graph entity-types create↴
• reactive-graph entity-types delete↴
• reactive-graph entity-types add-property↴
• reactive-graph entity-types remove-property↴
• reactive-graph entity-types add-extension↴
• reactive-graph entity-types remove-extension↴
• reactive-graph entity-types add-component↴
• reactive-graph entity-types remove-component↴
• reactive-graph entity-types update-description↴
• reactive-graph entity-types json-schema↴
• reactive-graph relation-types↴
• reactive-graph relation-types list↴
• reactive-graph relation-types get↴
• reactive-graph relation-types list-properties↴
• reactive-graph relation-types list-extensions↴
• reactive-graph relation-types list-components↴
• reactive-graph relation-types get-json-schema↴
• reactive-graph relation-types create↴
• reactive-graph relation-types delete↴
• reactive-graph relation-types add-property↴
• reactive-graph relation-types remove-property↴
• reactive-graph relation-types add-extension↴
• reactive-graph relation-types remove-extension↴
• reactive-graph relation-types add-component↴
• reactive-graph relation-types remove-component↴
• reactive-graph relation-types update-description↴
• reactive-graph relation-types json-schema↴
• reactive-graph flow-types↴
• reactive-graph flow-types list↴
• reactive-graph flow-types get↴
• reactive-graph flow-types list-variables↴
• reactive-graph flow-types list-extensions↴
• reactive-graph flow-types get-json-schema↴
• reactive-graph flow-types create↴
• reactive-graph flow-types delete↴
• reactive-graph flow-types add-variable↴
• reactive-graph flow-types remove-variable↴
• reactive-graph flow-types add-extension↴
• reactive-graph flow-types remove-extension↴
• reactive-graph flow-types update-description↴
• reactive-graph flow-types add-entity-instance↴
• reactive-graph flow-types remove-entity-instance↴
• reactive-graph flow-types json-schema↴
• reactive-graph entity-instances↴
• reactive-graph entity-instances list↴
• reactive-graph entity-instances get↴
• reactive-graph entity-instances get-by-label↴
• reactive-graph entity-instances list-properties↴
• reactive-graph entity-instances get-property↴
• reactive-graph entity-instances set-property↴
• reactive-graph entity-instances add-property↴
• reactive-graph entity-instances remove-property↴
• reactive-graph entity-instances list-components↴
• reactive-graph entity-instances add-component↴
• reactive-graph entity-instances remove-component↴
• reactive-graph entity-instances create↴
• reactive-graph entity-instances delete↴
• reactive-graph entity-instances json-schema↴
• reactive-graph relation-instances↴
• reactive-graph relation-instances list↴
• reactive-graph relation-instances get↴
• reactive-graph relation-instances list-properties↴
• reactive-graph relation-instances get-property↴
• reactive-graph relation-instances set-property↴
• reactive-graph relation-instances add-property↴
• reactive-graph relation-instances remove-property↴
• reactive-graph relation-instances list-components↴
• reactive-graph relation-instances add-component↴
• reactive-graph relation-instances remove-component↴
• reactive-graph relation-instances create↴
• reactive-graph relation-instances delete↴
• reactive-graph relation-instances json-schema↴
• reactive-graph flow-instances↴
• reactive-graph flow-instances list↴
• reactive-graph flow-instances get↴
• reactive-graph flow-instances get-by-label↴
• reactive-graph flow-instances create-from-type↴
• reactive-graph flow-instances delete↴
• reactive-graph flow-instances json-schema↴
• reactive-graph introspection↴
• reactive-graph introspection reactive-graph↴
• reactive-graph introspection dynamic-graph↴
• reactive-graph introspection reactive-graph-runtime↴
• reactive-graph introspection reactive-graph-plugins↴
• reactive-graph instances↴
• reactive-graph instances config↴
• reactive-graph instances config graphql↴
• reactive-graph instances config instance↴
• reactive-graph instances config plugins↴
• reactive-graph instances generate-certificate↴
• reactive-graph instances init↴
• reactive-graph instances plugins↴
• reactive-graph instances plugins install↴
• reactive-graph instances plugins uninstall↴
• reactive-graph instances repository↴
• reactive-graph instances repository init↴
• reactive-graph instances repository remove↴
• reactive-graph update↴
• reactive-graph update info↴
• reactive-graph update list↴

reactive-graph

Reactive Graph is a reactive runtime based on a graph database, empowering everyone to build reliable and efficient software.

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

Subcommands:

• shell-completions — Prints or installs Shell completions
• man-pages — Prints or installs man pages
• print-markdown-help — Prints the markdown help to stdout
• info — Prints info about this binary
• daemon — Runs the server as daemon
• graphql-schema — Prints the GraphQL schema and exits
• json-schema — Prints the JSON schema and exits
• execute-command — Executes a command on the client
• instance-info — Prints information about the instance
• plugins — Manage plugins
• remotes — Manage remotes
• shutdown — Shutdown the runtime
• components — Manage components
• entity-types — Manage entity types
• relation-types — Manage entity types
• flow-types — Manage entity types
• entity-instances — Manage entity instances
• relation-instances — Manage relation instances
• flow-instances — Manage flow instances
• introspection — Execute GraphQL introspection queries
• instances — Manage instances
• update — Update the Reactive Graph binary

Arguments:

• <DANGER_ACCEPT_INVALID_HOSTNAMES> — Controls the use of hostname verification.

  Defaults to false.

  Warning: You should think very carefully before you use this method. If hostname verification is not used, any valid certificate for any site will be trusted for use from any other. This introduces a significant vulnerability to man-in-the-middle attacks.

  Possible values: true, false

Options:

• --logging-config <LOGGING_CONFIG> — The logging config location

• --instance-config <INSTANCE_CONFIG> — The instance config location

• --graphql-config <GRAPHQL_CONFIG> — The GraphQL config location

• --plugins-config <PLUGINS_CONFIG> — The plugins config location

• -n, --instance-name <NAME> — The name of the instance

• -d, --instance-description <DESCRIPTION> — The description of the instance

• --hostname <HOSTNAME> — The hostname to bind the GraphQL HTTP server

• --port <PORT> — The port to bind the GraphQL HTTP server

• --secure <SECURE> — If true, HTTPS is enabled

  Possible values: true, false

• --ssl-certificate-path <SSL_CERTIFICATE_PATH> — The location of the certificate

• --ssl-private-key-path <SSL_PRIVATE_KEY_PATH> — The location of the private key

• --shutdown-timeout <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

• -w, --workers <WORKERS> — The number of workers to start. The default worker count is the number of physical CPU cores available

• -c, --default-context-path <DEFAULT_CONTEXT_PATH> — The default context path which redirects the root context to a web resource provider

• -x, --disable-all-plugins <DISABLE_ALL_PLUGINS> — If true, all plugins will be disabled

  Possible values: true, false

• -p, --disabled-plugins <DISABLED_PLUGINS> — The list of plugins to disable

• -P, --enabled-plugins <ENABLED_PLUGINS> — The list of plugins to enable

• --disable-hot-deploy <DISABLE_HOT_DEPLOY> — If true, hot deployment will be disabled

  Possible values: true, false

• --hot-deploy-location <HOT_DEPLOY_LOCATION> — The folder which is watched for hot deployment

• --install-location <INSTALL_LOCATION> — The folder which plugins are installed permanently

• --stop-immediately <STOP_IMMEDIATELY> — If true, the runtime does not wait before exiting

  Possible values: true, false

• -q, --quiet <QUIET> — If true, logging is disabled completely

  Possible values: true, false

• --client-hostname <CLIENT_HOSTNAME> — The hostname to connect to

• --client-port <CLIENT_PORT> — The port to connect to

• --client-secure <CLIENT_SECURE> — If true, connects via HTTPS

  Possible values: true, false

• --endpoint-graphql <ENDPOINT_GRAPHQL> — The endpoint to use

• --endpoint-dynamic-graph <ENDPOINT_DYNAMIC_GRAPH> — The endpoint to use

• --endpoint-runtime <ENDPOINT_RUNTIME> — The endpoint to use

• --endpoint-plugins <ENDPOINT_PLUGINS> — The endpoint to use

• --bearer <BEARER> — The authentication token

• --danger-accept-invalid-certs <DANGER_ACCEPT_INVALID_CERTS> — Controls the use of certificate validation.

  Defaults to false.

  Warning: You should think very carefully before using this method. If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

  Possible values: true, false

• -i, --interactive — Enter the interactive client mode

reactive-graph shell-completions

Prints or installs Shell completions

Usage: reactive-graph shell-completions <COMMAND>

Subcommands:

• print — Prints the shell completions to stdout
• install — Installs the shell completions

reactive-graph shell-completions print

Prints the shell completions to stdout

Usage: reactive-graph shell-completions print <SHELL>

Arguments:

• <SHELL> — The shell

  Possible values: bash, elvish, fish, powershell, zsh

reactive-graph shell-completions install

Installs the shell completions

Usage: reactive-graph shell-completions install <SHELL>

Arguments:

• <SHELL> — The shell

  Possible values: bash, elvish, fish, powershell, zsh