stone_skipper is a process-launching server that runs the commands registered in the configuration file for the corresponding incoming HTTP requests. It works asynchronously and can initiate multiple processes without blocking while waiting for their completion, even when running with a single thread.
stone_skipper is implemented as a FastCGI service, so you'll require a compatible HTTP server to use it. NGINX can be used with a following configuration:
server {
listen 8088;
server_name localhost;
index /~;
location / {
try_files $uri $uri/ @fcgi;
}
location @fcgi {
fastcgi_pass unix:/tmp/stone_skipper.sock;
#or using a TCP socket
#fastcgi_pass localhost:9000;
include fastcgi_params;
fastcgi_keep_conn off;
}
}
After enabling this configuration, stone_skipper can be launched using the following command:
stone_skipper -fcgiAddress=/tmp/stone_skipper.sock
stone_skipper creates an empty default configuration file stone_skipper/stone_skipper.cfg in your system config directory. The path to another config file can be set in the command line using the following format:
stone_skipper -fcgiAddress=stone_skipper.sock -config=/home/user/stone_skipper.cfg
The configuration file is written in shoal format:
#tasks:
###
route = /greet/{{name}}
command = echo "Hello {{name}}"
###
route = /farewell/
process = farewell.sh --name {{name}}
tasks is a list of process launching tasks, where each task consists of a route parameter that specifies the incoming request's path triggering the action, and either a command or process parameter that specifies the command to launch. When using command, the command is executed in the shell, while process launches it directly.
The route parameter can define a wildcard parameter that matches one or more characters. The result of a match can be used in the command or process parameters. For example, with the earlier provided configuration, a request to /greet/world would launch the echo "Hello world" command.
Query parameters from the request can also be used in the command and process parameters. In the example configuration, the second task enables the usage of the request /farewell/?name=moon to start the farewell.sh --name moon process.
| Parameters: | |
-fcgiAddress=<fcgiHost> |
socket for FastCGI connection (either a file path, or 'ipAddress:port' string) |
-log=<path> |
log file path (optional) |
-config=<path> |
config file path (optional) |
-shell=<string> |
shell command (optional) |
-threads=<int> |
number of threads (optional) |
| Flags: | |
--help |
show usage info and exit |
--version |
show version info and exit |
To build stone_skipper, you will need a C++20-compliant compiler, CMake, and the Boost.Process library installed on your
system.
git clone https://github.com/kamchatka-volcano/stone_skipper.git
cd stone_skipper
cmake -S . -B build
cmake --build build
Boost dependencies can be resolved using vcpkg by running the build with
this command:
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg path>/scripts/buildsystems/vcpkg.cmake
cd stone_skipper
cmake -S . -B build -DENABLE_TESTS=ON
cmake --build build
cd build/tests && ctest
Download lunchtoast executable, build stone_skipper and start NGINX with functional_tests/nginx_*.conf config file.
Launch tests with the following command:
- Linux command:
lunchtoast functional_tests
- Windows command:
lunchtoast.exe functional_tests -shell="msys2 -c"
To run functional tests on Windows, it's recommended to use the bash shell from the msys2 project. After installing
it, add the following script msys2.cmd to your system PATH:
@echo off
setlocal
IF NOT DEFINED MSYS2_PATH_TYPE set MSYS2_PATH_TYPE=inherit
set CHERE_INVOKING=1
C:\\msys64\\usr\\bin\\bash.exe -leo pipefail %*stone_skipper is licensed under the MS-PL license