Starlarky VGS edition of Google's safe and hermetically sealed Starlark language
* [Description](#description)
* [Project overview](#project-overview)
* [Libstarlark](#libstarlark)
* [Larky](#larky)
* [Runlarky](#runlarky)
* [Pylarky](#pylarky)
* [Developer setup](#developer-setup)
* [Depoyment process](#deployment-process)
## Description
Starlarky is VGS in-house edition of [Bazel](https://bazel.build/)'s hermetically-sealed language created by Google called [Starlark](https://github.com/bazelbuild/starlark).
This language is used to run "unsafe" user-submitted code without exposing service at whole to possible attack and/or vulnerabilities.
Starlark has Python-like syntax and is created to support same structure of additional libraries.
Key differences between Starlark and Python can be found [here](https://docs.bazel.build/versions/master/skylark/language.html#differences-with-python)
## Project overview
Starlarky is presented as a monorepo with different modules
### Libstarlark
_Libstarlark_ is a maven module, that contains Starlark compiler from [bazelbuild](https://github.com/bazelbuild/bazel/tree/master/src/main/java/net/starlark/java)
This module is being periodically updated from bazelbuild via this [script](https://github.com/verygoodsecurity/starlarky/blob/master/bin/update-starlark.py)
to maintain relevancy.
See more at Libstarlarky [README](https://github.com/verygoodsecurity/starlarky/blob/master/libstarlark/README.md)
To build run this command:
```bash
mvn versions:set -DnewVersion= -pl libstarlark (optional)
mvn clean package -pl libstarlark
```
### Larky
_Larky_ is a maven module, that contains VGS additions to Starlark language.
Some additions ispired and taken from [Copybara](https://github.com/google/copybara/)
Here are some of them:
- JSR223 script engine
- Annotations to define additional libraries
- Extension [modules](https://github.com/verygoodsecurity/starlarky/blob/master/larky/src/main/java/com/verygood/security/larky/modules/README.md)
To build run this command:
```bash
mvn versions:set -DnewVersion= -pl larky (optional)
mvn versions:set-property -Dproperty=libstarlark.version -DnewVersion= -pl larky
mvn clean package -pl larky
```
### Runlarky
_Runlarky_ is an example Larky invocation application
It builds as a Quarkus executable and gives ability to run Larky with input parameters.
To build run this command:
```bash
mvn versions:set -DnewVersion= -pl runlarky (optional)
mvn versions:set-property -Dproperty=starlarky.version -DnewVersion= -pl runlarky
mvn clean package -pl runlarky -Pnative
```
This would build `larky-runner` executable in `runlarky/target` directory, that can be run from terminal
### Pylarky
_Pylarky_ is pip lib-wrapper for runlarky to make larky calls conveniently from Python.
### Building and Running Tests
```bash
docker-compose build
docker-compose run local bash /src/build-and-test-java.sh
docker-compose run local bash /src/build-and-test-python.sh
```
### Run individual larky stdlib test
```bash
mvn -Dtest='StdLibTest*' -Dlarky.stdlib_test=test_bytes.star org.apache.maven.plugins:maven-surefire-plugin:3.0.0-M5:test -pl larky
```
## Developer setup
In addition to having Maven installed, it must be configured to retrieve artifacts from Github.
1) Generate an access token using [Github's instructions](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). The token needs `read:packages` scopes.
2) You must enable SSO for verygoodsecurity
3) Place the token in your `~/.m2/settings.xml` file. For example (look for `github-username` and `github-api-key` to be replaced with your values):
```
githubgithub-usernamegithub-api-key
```
## Deployment process
To rollout a new verion of libstarlark/larky/larky-api create a new tag
```
git tag x.x.x
git push origin x.x.x
```
Than, after CircleCI build, publish the draft release
