Graph

In the NYRA framework, there are two types of graphs:

Flexible
Predefined

Flexible

Predefined

Time to start

When the NYRA app receives a start_graph command.

When the NYRA app starts or when the NYRA app receives a start_graph command.

Graph content

Specified in the start_graph command.

Specified in the NYRA app’s properties.

Graph ID

A random UUID.

Two Types of Graph

For predefined graphs, there is an auto_start attribute indicating whether the predefined graph will start automatically when the NYRA app starts. There is also a singleton attribute indicating whether the predefined graph can only generate one engine instance in the NYRA app.

Graph ID and Graph Name

Each graph instance (engine instance) that a NYRA app spawns has a unique UUID4 string, the graph ID.

For predefined graphs, you can assign a more memorable graph name. If a predefined graph is marked as singleton, then only one instance of that graph can exist, and the graph name becomes a unique identifier for that single instance.

Flexible Graph

When the NYRA app receives the start_graph command to create this type of graph, it assigns a random UUID as the graph ID. If other clients know this ID, they can also connect to the same graph.

Example of a flexible graph ID:

123e4567-e89b-12d3-a456-426614174000

Predefined Graph

Predefined graphs are nearly the same as flexible graphs, except their contents are defined by the NYRA app rather than provided in the start_graph command. Clients only need to specify the name of the predefined graph they want to start, rather than providing full details.

This approach can improve usability and protect certain internal information — the client doesn’t need to know exactly how the graph is structured.

Example of a predefined graph name:

http-server

When the NYRA app starts, any predefined graphs that have auto_start set to true will run immediately.

Graph Definition

A graph—whether flexible or predefined—is defined in the same way:

{
  "nodes": [
    // Definition of nodes
  ],
  "connections": [
    // Definition of connections
  ]
}

Key points:

If there is only one app, you may omit the app field in each node. Otherwise, you must specify it.
The nodes array describes nodes in the graph (extensions, extension groups, etc.).
Each node can appear only once. Duplicating the same node triggers errors.

Example Node: Extension Group

{
  "type": "extension_group",
  "name": "default_extension_group",
  "addon": "default_extension_group",
  "app": "msgpack://127.0.0.1:8001/",
  "property": {
    "root_key": "player",
    "extra_keys": [
      "playerName"
    ]
  }
}

property is optional.

Example Node: Extension

{
  "type": "extension",
  "name": "simple_http_server_cpp",
  "addon": "simple_http_server_cpp",
  "extension_group": "default_extension_group",
  "app": "msgpack://127.0.0.1:8001/",
  "property": {
    "root_key": "player",
    "extra_keys": [
      "playerName"
    ]
  }
}

property is optional.
addon is also optional.
- If addon is given, the extension is instantiated by that add-on.
- If addon is omitted, the extension is created by the corresponding extension group. Usually, such an extension doesn’t need to be explicitly listed unless you want to specify its property.

The `connections` Field

connections specify how nodes in the graph connect to one another. For each connection:

extension or extension_group must be the name of a node already listed in nodes.
A complete example:

{
  "nodes": [
    {
      "type": "extension_group",
      "name": "default_extension_group",
      "addon": "default_extension_group",
      "app": "msgpack://127.0.0.1:8001/"
    },
    {
      "type": "extension",
      "name": "simple_http_server_cpp",
      "addon": "simple_http_server_cpp",
      "extension_group": "default_extension_group",
      "property": {
        "root_key": "player",
        "extra_keys": ["playerName"]
      }
    }
  ],
  "connections": [
    {
      "app": "msgpack://127.0.0.1:8001/",
      "extension": "simple_http_server_cpp",
      "cmd": [
        {
          "name": "start",
          "dest": [
            {
              "app": "msgpack://127.0.0.1:8001/",
              "extension": "gateway"
            }
          ]
        },
        {
          "name": "stop",
          "dest": [
            {
              "app": "msgpack://127.0.0.1:8001/",
              "extension": "gateway"
            }
          ]
        }
      ]
    },
    {
      "app": "msgpack://127.0.0.1:8001/",
      "extension": "gateway",
      "cmd": [
        {
          "name": "push_status_online",
          "dest": [
            {
              "app": "msgpack://127.0.0.1:8001/",
              "extension": "uap"
            }
          ]
        }
      ]
    }
  ]
}

Definition of a Predefined Graph

You place the complete graph definition under the predefined_graphs field in the NYRA app’s properties. Each entry can have:

name
auto_start
singleton
The actual nodes and connections.

Example:

"predefined_graphs": [
  {
    "name": "default",
    "auto_start": true,
    "singleton": true,
    "nodes": [
      {
        "type": "extension_group",
        "name": "default_extension_group",
        "addon": "default_extension_group",
        "app": "msgpack://127.0.0.1:8001/"
      },
      {
        "type": "extension",
        "name": "simple_http_server_cpp",
        "addon": "simple_http_server_cpp",
        "extension_group": "default_extension_group",
        "property": {
          "root_key": "player",
          "extra_keys": [
            "playerName"
          ]
        }
      }
    ],
    "connections": [
      {
        "app": "msgpack://127.0.0.1:8001/",
        "extension": "simple_http_server_cpp",
        "cmd": [
          {
            "name": "start",
            "dest": [
              {
                "app": "msgpack://127.0.0.1:8001/",
                "extension": "gateway"
              }
            ]
          },
          {
            "name": "stop",
            "dest": [
              {
                "app": "msgpack://127.0.0.1:8001/",
                "extension": "gateway"
              }
            ]
          }
        ]
      },
      {
        "app": "msgpack://127.0.0.1:8001/",
        "extension": "gateway",
        "cmd": [
          {
            "name": "push_status_online",
            "dest": [
              {
                "app": "msgpack://127.0.0.1:8001/",
                "extension": "uap"
              }
            ]
          }
        ]
      }
    ]
  }
]

Definition of the `start_graph` Command

You can also embed the entire graph definition within a start_graph command by placing it under _nyra in your JSON. Attributes like type, seq_id, etc. can also be included.

Example:

{
  "_nyra": {
    "type": "start_graph",
    "seq_id": "55",
    "nodes": [
      {
        "type": "extension_group",
        "name": "default_extension_group",
        "addon": "default_extension_group",
        "app": "msgpack://127.0.0.1:8001/"
      },
      {
        "type": "extension",
        "name": "simple_http_server_cpp",
        "addon": "simple_http_server_cpp",
        "extension_group": "default_extension_group",
        "property": {
          "root_key": "player",
          "extra_keys": ["playerName"]
        }
      }
    ],
    "connections": [
      {
        "app": "msgpack://127.0.0.1:8001/",
        "extension": "simple_http_server_cpp",
        "cmd": [
          {
            "name": "start",
            "dest": [
              {
                "app": "msgpack://127.0.0.1:8001/",
                "extension": "gateway"
              }
            ]
          },
          {
            "name": "stop",
            "dest": [
              {
                "app": "msgpack://127.0.0.1:8001/",
                "extension": "gateway"
              }
            ]
          }
        ]
      },
      {
        "extension": "gateway",
        "cmd": [
          {
            "name": "push_status_online",
            "dest": [
              {
                "extension": "uap"
              }
            ]
          }
        ]
      }
    ]
  }
}

Specification for Graph Definition

nodes field:
- Mandatory in a graph definition.
- connections is optional but recommended for inter-node communication.
Validation of Node app field:
- Must never be set to localhost.
- In a single-app graph, you typically omit the app field.
- In a multi-app graph, the value of app must match the _nyra::uri in each app’s property.

Node Uniqueness: Each node in nodes represents one extension instance (within a specific group, on a specific app, possibly created by an add-on). It must be unique by (app, extension_group, name). Duplicates cause errors.

Invalid example (same extension name in the same group but different add-ons):

{
  "nodes": [
    {
      "type": "extension",
      "name": "some_ext",
      "addon": "addon_1",
      "extension_group": "test"
    },
    {
      "type": "extension",
      "name": "some_ext",
      "addon": "addon_2",
      "extension_group": "test"
    }
  ]
}

Connections Must Refer to Valid Nodes: Any extension instance mentioned in connections (as source or destination) must be defined in nodes.

Invalid example (because ext_2 is not in nodes):

{
  "nodes": [
    {
      "type": "extension",
      "name": "ext_1",
      "addon": "addon_1",
      "extension_group": "some_group"
    }
  ],
  "connections": [
    {
      "extension": "ext_1",
      "cmd": [
        {
          "name": "hello",
          "dest": [
            {
              "extension": "ext_2"
            }
          ]
        }
      ]
    }
  ]
}

Consolidate Connection Definitions: All messages from the same source extension must be listed together in one section of connections. Splitting them up can cause confusion or errors.

Incorrect:

{
  "connections": [
    {
      "extension": "ext_1",
      "cmd": [
        {
          "name": "hello",
          "dest": [{"extension": "ext_2"}]
        }
      ]
    },
    {
      "extension": "ext_1",
      "data": [
        {
          "name": "hello",
          "dest": [{"extension": "ext_2"}]
        }
      ]
    }
  ]
}

Correct:

{
  "connections": [
    {
      "extension": "ext_1",
      "cmd": [
        {
          "name": "hello",
          "dest": [{"extension": "ext_2"}]
        }
      ],
      "data": [
        {
          "name": "hello",
          "dest": [{"extension": "ext_2"}]
        }
      ]
    }
  ]
}

Consolidate Destinations for Each Message: If a message named hello needs multiple destinations, list them under one entry. Duplicating the same message name within the same type (e.g., cmd) is invalid.

Incorrect:

{
  "connections": [
    {
      "extension": "ext_1",
      "cmd": [
        {
          "name": "hello",
          "dest": [{"extension": "ext_2"}]
        },
        {
          "name": "hello",
          "dest": [{"extension": "ext_3"}]
        }
      ]
    }
  ]
}

Correct:

{
  "connections": [
    {
      "extension": "ext_1",
      "cmd": [
        {
          "name": "hello",
          "dest": [
            {"extension": "ext_2"},
            {"extension": "ext_3"}
          ]
        }
      ]
    }
  ]
}

Note: Messages sharing a name but assigned to different types (e.g., one is cmd, another is data) do not conflict.

For more details or examples, consult the check graph command in the NYRA manager tools.

PreviousBuild System NextCloud Store

Last updated 9 months ago