⚙ Spec

ranna is using so called Specs. These are the sepcifications used to define the environment in which the provided code will be executed inside a sandbox.

Spec Model

Languages which support running code from files with one command line execution use the entrypoint spec definition.

# An example of a spec definition for the language Go.
# This example uses the "entrypoint" specification
# for code execution.
golang:
  # The Docker image to be used as base environment
  # containing necessary toolchains.
  image:      'golang:alpine'
  # Specifies the command used to invoke the code 
  # execution. The command is getting appended by 
  # the filename and assembled arguments.
  entrypoint: 'go run'
  # The file name of the main file where the code 
  # will be injected into. This must be specified 
  # even though when cmd is set. In this case, 
  # the file mentioned there must match the file 
  # name, of course.
  filename:   'main.go'
  # A meta tag delivered via the REST API to give
  # information which language is supported by
  # the spec.
  language:   'go'
  # Example code runnable with this spec. This is 
  # just delivered via the spec API endpoint to
  # be shown in the web interface.
  example: |-
    package main
    import "fmt"
    func main() {
    	fmt.Println("Hello world!")
    }
  # When provided, code which requires "boilerplate"
  # code can be executed "inline" which wraps the
  # provided imports and code lines into the 
  # "boilerplate" template code.
  inline:
    # The regular expression pattern to detect
    # imports in provided inline code.
    import_regex: '(?m)^import "[\w/]+"$|^import \((\n?\t?(\s+)?"[\w/]+";?)+\n?\)$'
    # The "boilerplate" template.
    # $${IMPORTS} is replaced with import strings
    # matching the given `import_regex` pattern.
    # $${CODE} is replaced with the provided request
    # code without the imports.
    template: |-
      package main
      $${IMPORTS}
      func main() {$${CODE}}

All languages which require pre-compilation of code files and then execution of the result binaries use the cmd spec definition.

# An example of a spec definition for the language C++
# using GCC as compiler.
# This example uses the "cmd" specification
# for code execution.
cpp:
  image:      'frolvlad/alpine-gxx:latest'
  # When set it overrides the entrypoint value and does 
  # not append the file name. This is required for 
  # compilers not supporting JIT compiling or run-like 
  # commands. Arguments will be appended to the cmd though.
  cmd:        '/bin/ash -c "c++ --static main.cpp -o main && ./main"'
  filename:   'main.cpp'
  language:   'c++'
  example: |-
    #include <stdio.h>
    int main() {
        printf("Hello world!\n");
        return 0;
    }
  inline:
    import_regex: '^#include ["<][\w/.]+[">]$'
    template: |-
      $${IMPORTS}
      int main() {
        $${CODE}
        return 0;
      }

Spec Map

Specs are defined in a SpecMap with the language specified in the execution request as key and the assigned spec as value. Currently, the spec map is provided either via a local JSON or YAML file, which defaultly sits in spec/spec.yaml or spec/spec.json. You can define your own spec definitions or just use the provided SpecMap.

If you want, you can also add some more specs to this file via pull request. 😉