What is VoidMerge?

Void Merge is a powerful and simple to use web and application development framework.

• Stores, distributes, and validates app-defined structured data
• Facilitates peer-to-peer communications
• Built-in web hosting
• RESTful API for developing applications

The vm Utility

Install the vm command-line utility to work with VoidMerge.

• vm serve runs a VoidMerge server instance.
• The other commands let you administrate a running server instance.

Installing the vm Utility

Option 1: Install from crates.io

1. First, Get Rust (https://rustup.rs/).
2. Second, Install the vm utility with cargo:

cargo install voidmerge --bin vm

Use this command like other local commands:

vm --help

Option 2: Use a docker image

docker pull ghcr.io/voidmerge/voidmerge-vm:latest

Use this command through docker:

docker run -it ghcr.io/voidmerge/voidmerge-vm:latest vm --help

Note: if you're running 'vm serve' in docker, you'll likely need to add additional options to the command to bind a volume and expose the port of the server.

Context

A VoidMerge "context" can be thought of as a database. Multiple data types can be stored in a single context. Those datatypes could be thought of as tables.

System Types

There are some system types that are predefined in VoidMerge, and the type names all start with "sys":

• "syslogic" - The validation logic for the context
• "sysenv" - Global environment information available in all validation logic
• "sysweb" - Stores an individual file for the built-in static web server

Logic

In VoidMerge, "Logic" is the code that defines how data is handled, and whether it is valid and will be accepted, or invalid and will be rejected.

Simple Starter Logic

The simplest logic definition allows all data, and looks like this:

VM({
  call: "register",
  code(_i) {
    return { result: "valid" };
  }
});

Let's break this down. First, the global VM function:

The VM global function

VM(
  /* .. */
);

This is the main entrypoint provided in the execution context of the VoidMerge logic. It can do multiple things, including providing access to system APIs, but what we care about at the moment is registering the validation logic for VoidMerge structured data.

Call type "register"

VM({
  call: "register",
  /* .. */
});

We always pass an object to the VM function. By setting the "call" property to "register", we are telling VoidMerge that we are registering validation logic.

Finally, the code function itself

VM({
  /* .. */
  code(_i) {
    return { result: "valid" };
  }
});

The "code" function takes an input parameter, which we are ignoring here, and returns a validation result. In this case, we are returning that the data is valid, thus it will be allowed / stored.

Meta Storage and Validation

Logic is stored in a VoidMerge context the same as any other data. It is stored with the "syslogic" type.

Env

In VoidMerge, "Env" is global metadata associated with a VoidMerge context.

Example VoidMerge Env

{
  "public": {
    "servers": ["http://127.0.0.1:8080"],
    "examplePublicEnv": "hello"
  },
  "private": {
    "ctxadminPubkeys": [],
    "examplePrivateEnv": "world"
  }
}

Public

The "public" data will be available on the "status" call of the VM server which is not authenticated. It helps clients know how to connect / bootstrap into the network. Do not share any privileged information in this section.

Private

The "private" data will only be available to clients that have authenticated.

In logic

In the logic code, the env data is available on the input parameter object as the property env.

VM({
  call: "register",
  code(i) {
    if (
      i.env.public.examplePublicEnv !== "hello"
      || i.env.private.examplePrivateEnv !== "world"
    ) {
      throw new Error("Invalid Env Data");
    }

    return { result: "valid" };
  }
});

Meta Storage and Validation

Logic is stored in a VoidMerge context the same as any other data. It is stored with the "sysenv" type.

Usage Example

Take a look at the example1 start script in the monorepo:

https://github.com/voidmerge/voidmerge/blob/main/ts/example1/package.json

This runs the "serve-and-push-app" testing convenience command in the vm utility.

Note the args that:

• set up a system admin token
• then use that token for pushing the app
• push the sysenv from a json file
• push the syslogic from a js file
• and finally push all the static web files as sysweb entries for the web server

After running this command, you can navigate locally to http://127.0.0.1:8080 to experience the application.