Hey ^^.

I recently got the idea to implement so-called code environment templates into ranna to allow code execution without having to provide the whole boilerplate (package, imports, main function) that surrounds the expression to evaluate. I also made up my mind on how this could possibly be implemented in the current solution to create as little friction as possible.

Specification implementation

First of all, spec.yml entries receive an additional field called template:

golang:
  image: 'golang:alpine'
  entrypoint: 'go run'
  filename: 'main.go'
  example: |-
    package main
    import "fmt"
    func main() {
    	fmt.Println("Hello world!")
    }
  template: |-
    package main
    import "fmt"
    func main() {
    	$${CODE}
    }

$${CODE} gets replaced with the user-provided expression before passing the whole construct down to the execution runtime.

API implementation

The POST /v1/exec request body receives an additional field called inline_expression (boolean). If this field is set to true, the contents of the code field get inserted in the desired template. If the specification of the targetted language does not support inline templating (the template field is omitted), an error is returned. The inline_expression field is set to false by default to not break existing API clients.

{
  "language": "go",
  "code": "fmt.Println(\"Cool! Inline expressions!\")",
  "inline_expression": true,
  "arguments": [],
  "environment": {}
}

Please let me know what you think of this idea and my suggested example on how to implement it! If you would like to implement this into ranna, I'd love to help with a PR.

I have sorted the spec file and formatted it uniformly. The languages "names" are now sorted alphabetically and everything is formatted the same. I do this in an extra PR to avoid merge conflicts with the other two PRs.

This allows stuff like

// The 'fmt' package allows us to print something to our console:
import "fmt"
fmt.Println(123)

// We can also pass in other nested expressions:
import "strings"
fmt.Println(strings.ToLower("HELLO, WORLD!"))

In this PR I have added the Racket programming language. Because I'm working with the school with it right now, ranna offers itself for a short test and share. Since it is probably in the interest of the project, I would also like to add this programming language to the project.

The commands I could execute with Docker I have tested all but I'm not sure if it all works in ranna Working Dir. Therefore please test once.

If you try to execute this script in Ranna and select golang as the Language, it doesn't highlight any word.

package main

import "fmt"

func main() {
    fmt.Println("Hello World.")
}

Alongside the REST API, the ranna engine should also be accessible via a WebSocket API which gives real-time log output and runtime information.

The communication is based on operations and events encoded in JSON objects.

Operations

Operations are specified as enumerable operation codes and can get passed arguments in form of a key-value pair map. You can also optionally pass a nonce value which will be also set on corresponding events related to the operation.

Example

{
  "op": 1,
  "nonce": 23216,
  "args": {
    "language": "go",
    "code": "package main; import \"fmt\"; func main() {fmt.Println(\"Hello world!\")}"
  }
}

Operation Codes

| Code | Name | Description | |-------|--------|--------------| | 0 | PING | Pings the WebSocket API. | | 1 | EXEC | Invoke a code execution. | | 2 | KILL | Kill a running operation. |

Events

Events carry enumerable event codes which specify the type of event as well as a payload with the events data. Also, when the event was invoked corresponding to a previous operation which has been passed a nonce, the event will also carry the passed nonce.

Example

{
  "code": 2,
  "nonce": 23216,
  "data": {
    "runid": "as98234sa",
    "stdout": "Hello world!"
  }
}

Event Codes

| Code | Name | Description | |-------|--------|--------------| | 0 | PONG | Response event to the PING operation. | | 1 | ERROR | An error event. | | 2 | SPAWN | Indicates a spawned execution instance. It also carries a unique ID of the execution created. | | 3 | LOG | Indicates a log output from a running execution. It carries the unique execution ID as well as the STDERR or STDOUT value. | | 4 | STOP | Indicates the controlled finish of a execution run. | | 5 | KILL | Indicates that the run has been killed. |

With the release of the new Java LTS version I also want to add the new version to this project. For this I added Java 17 to the specs and linked the "java" spec to the new version.

When executing short commands using the ash spec, the result will mostly be empty.

This is probably a timing issue, because this is working completely fine.

Add aliases to spec in form of spec pointers. This would look like following in the spec configuration:

openjdk-11:
  image:      'openjdk:11'
  entrypoint: 'java'
  filename:   'Main.java'

java:
  use:        'openjdk-11'

My proposal is to check if the given php code is inline or not and then handle it accordingly. Either by ignoring it/throwing an error or adding the necessary parts.