GreyCat Server

Introduction

To empower digital twin, GreyCat is not only a Runtime but also a Server.

Any function can be exposed to remote procedure call (RPC) by adding an @expose pragma

@expose
fn compute(p: int): int {
    return 3 + 5 + p;
}
fn main() {
    println(compute(2));
}

This minimal code snippet already defines a server (–user=1 deactivates security, more on this later)

greycat serve --user=1
# 10
# INFO  2023-05-25T08:34:21.719127+00:00 GreyCat is serving on port: 8080
# WARN  2023-05-25T08:34:21.719174+00:00 Impersonate mode with user 1

GreyCat server can be queried through an HTTP API.

The parameters for the endpoint can be url encoded:

curl -X POST -d "[100]" http://localhost:8080/project::compute
> 108

Or the parameters for the endpoint can be JSON encoded:

curl -X POST --json "[100]" http://localhost:8080/project::compute
> 108

Functions and error handling

fn sub_process() {
    throw "stop here";
}
@expose
fn computeWithSub(p: int): int {
    sub_process();
    return 3 + 5 + p;
}
fn main() {
    var res = compute(2);
    println(res);
}

In this example sub_process and compute share the error handling management, leading to the following error stack

greycat run

{
  "_type": "core.Error",
  "code": { "_type": "core.ErrorCode", "field": "throw" },
  "value": "stop here",
  "stack": [
    "sub_process (project.gcl:65:23)",
    "compute (project.gcl:69:18)",
    "main (project.gcl:73:26)"
  ]
}

Function entrypoint == Transaction

Every exception thrown activates a rollback mechanism, leaving the temporal graph unchanged

var counter: node<int?>;

@expose
fn inc_count() {
    println(*counter);
    counter.set((counter.resolve() ?? 0) + 1);
    throw "my bad";
}

This is illustrated in this example, where many calls do not alter the counter due to the following exception

greycat run inc_count
# null
# {"_type":"core.Error","code":{"_type":"core.ErrorCode","field":"throw"},"value":"my bad","stack":["inc_count (project.gcl:70:20)"]}

greycat run inc_count
# null
# {"_type":"core.Error","code":{"_type":"core.ErrorCode","field":"throw"},"value":"my bad","stack":["inc_count (project.gcl:70:20)"]}

Exposed functions are for short computation!

As many API oriented framework, GreyCat adds a timeout to remote function calls (default of 30s, configurable)

@expose
fn heavy_computation() {
    while (true) {
        // noop
    }
}

any call through HTTP API will then result in a timeout exception (therefore rollback)

greycat serve --user=1

curl -X POST http://localhost:8080/project/heavy_computation
# {"_type":"core.Error","code":{"_type":"core.ErrorCode","field":"timeout"},"stack":["heavy_computation (project.gcl:67:15)"]}

timeout is similar for write and read function entrypoint, this enhances the server against multi-user experience

Long running functions? Task is the answer!

An in depth explanation can be found here

Env variables

GreyCat supports a wide range of environment variables that can either be defined on the cli or in an .env file

Runtime info

The runtime module provides a RuntimeInfo object which contains all important information about the currently running GreyCat server

Store Stat