Speedy, the binary, options & Configuration
Speedy has several options to instruct how it should work during runtime. Simplest way to get to know speedy options is to run it without any arguments. This will print the following as built-in help.
speedy # Should run either in evaluation or licensed mode
speedy # Mandatory parameters missing, showing help
Usage: ./speedy [option]=[value] ...
Parameters:
-a analytics
log analytics to database (default false)
-e evaluation
run speedy in evaluation mode (default false)
-f certificate
full certificate file to use for TLS
-i ip address
ip address of remote database (default "127.0.0.1")
-j javascript engine
javascript engine to use (goja, otto) (default "goja")
-k private key
private key for the SSL certificate
-l license
speedy license file with complete path
e.g. /path/to/speedy.lic
-m password
password supply mode (file or prompt) (default "file")
-o port
port number of remote database (default "5432")
-p port
port on which speedy receives requests (default "3023")
-r production
production mode protects GET on definitions (default true)
-s database
name of the database to connect with
-t test
self-test Speedy (default false)
-u username
username for connecting to databaseMinimum expected options, to run speedy are -s, -u and -e or -l. Each of which respectively stands for database schema, database username and evaluation mode or licensed mode if one has a valid license. As of this article speedy supports only, but legendary PostgreSQL, hence it assumes localhost and 5432 to be the default IP and port for it.
Database options and support, speedy supports PostgreSql (only). When not explicitly mentioned, speedy assumes that both database and it are running on the same VM/machine. Hence, it will attempt to make connection locally over 127.0.0.1:5432. This default behaviour can be changed incase the database is running on a remote machine via -i=<remote-ip-address>and -o=<remote-port-number>. Apart from these, the schema name and postgres username are mandatory, and these are supplied using -u=<username>, and -s=<schema-name>.
Evaluation mode, Speedy can be run in evaluation mode free of cost forever. This mode is given to help developers to tryout and develop using speedy without any strings attached. In evaluation mode Speedy pings the home server to report its existence, without reporting any telemetry about the instance itself. Little Bit will know that there exists an instance of speedy somewhere on the planet. As per the licensing terms running 100s of instance of speedy in evaluation mode is prohibited, might attract legal focus in such cases. Evaluation mode can be invoked by using -e=true and in evaluation mode speedy will honour only five requests per minute.
Licensed mode, enables the admin/user to apply and unlock limitations from Speedy with a license file. A license must be purchased ahead to apply it on one or several servers. To apply a license use the switch -l=/path/to/licence/file, where full path and file name is passed as value to the switch.
Certificates and TLS support, that is, support for TLS (aka HTTPS) out of the box can be achieved using two arguments, -f and -k. To provide TLS support with speedy, it should be provided with fill certificate file (aka fullchain.pem in LetsEncrypt terms); and the private key file privkey.pem in LetsEncrypt terms. A full chain certificate or its equivalent can be passed using -f=/path/to/the/fullchain.pem and private-key file using -k=/path/to/the/privkey.pem. These two options are interdependent and won’t work without one another.
Production mode, is an additional security added to Speedy to prevent anyone from querying the definitions of REST, and Functions. This helps in production a lot, by preventing anyone else laying hands on the definitions. It is recommended to enable this flag in production. To enable just use the switch -r=true to enable the protection.
Speedy port, by default is set to 3023, and this can be changed using -p option. Usage is very simple, -p=<any-valid-portnumber>.
JavaScript engine, out of the box Speedy supports two types of JS engines to write business logic, namely, otto (https://bit.ly/3FKzhCX) and goja (https://bit.ly/3DwEU58). The default engine is set to goja as our benchmarks found it to be 4x — 8x faster than otto. This can be changed with -j=otto, if otto is preferred. Speedy does optimisation during runtime by caching the compiled code, so that second invocation of the same JS code runs 6x — 8x faster. By default, the compiled code is cached for 30 minutes, and evicted from cache if not accessed again.
Speedy self-test mode; helps in testing the whole setup is doing just fine before getting ahead of deployment. It is highly recommended to run speedywith self-testoption atleast once before going live on any setup. This ensures that speedy works as expected, using several startup tests. Self-test can be triggered using -t option, usage is -t=true.
Logging web traffic for analytics; can be accomplished through -a option. By default this is turned off, as most of the production deployments use some type of log analysing solution, which would pick the speedy logs written to file system. A word of caution here is, enabling log analytics will have impact on the performance, as analytics is written into a database table, and for a fact writing to a database is 4x slower than flushing to a file. If your deployment does not have any logging solution then we recommend you use this as last resort, to enable pass -a=true and to disable -a=false or simply remove -a from the argument list.
Speedy runtime configurations
Speedy offers minimal configurations that influence its behaviour during runtime. There are only three configurations that are exposed to the administrators they are REST_CACHE_ENTRY_TENURE, REST_DB_CONNECTIONS, JS_EXEC_TIMEOUT_SECS and REST_GEOSYNC_INTERVAL. Out of these four, the last one futuristic, which is used for geo-synchronisation of database across regions. This is equivalent to that of replication, but in a lot faster way. This feature is not offered yet.
REST_CACHE_ENTRY_TENURE, is used for deciding the eviction time for any key-value placed inside kv store. By default, this is set to 30 minutes, and the value must be given in minutes. Changing this configuration to a very large value like couple of hours, will have impact on the amount of data being held in RAM. On machines where RAM is limited this value should be reduced, and can be increased on those where RAM is plenty.
REST_DB_CONNECTIONS, is used by speedy to determine the level of parallisation it can establish with the database. Higher the number, higher is its ability to concurrently process more requests, involving the database. It is recommended that administrators use this with caution and should consider whether database itself supports it. On a beefy (multi-core and high RAM capacity) machines this number can be increased very generously. Remember to first increase the concurrency factor on the database first before modifying this configuration, otherwise, speedy will have connection failures, and might need a restart of the service. By default this value is set to 30.
JS_EXEC_TIMEOUT_SECS, is the knob given to admins of Speedy to control the execution timeout of a script that is being executed by it. Speedy allows definition and functions to be defined in JavaScript so that custom business logic is coded in it to extend the REST capability beyond. By default this value is set to 3 seconds, and it cannot be forced to be lower than this.
Changing Configurations
To change these settings/configurations use the following postman or curl commands. To list all the configurations use the following curl command.
curl --location --request GET 'localhost:3023/config'
To modify a configuration, simply use the curl or postman to do so. Here are few examples.
curl -X POST 'localhost:3023/config' \
-H 'Content-Type: application/json' \
-d '{
"name" : "REST_DB_CONNECTIONS",
"value" : "30"
}'
Warning: apart from these exposed configurations, speedy uses other configurations internally, and those start with _ (underscore). Changing them could have catastrophic effect on speedy itself and might render your instance crippled, along with eligibility for support.