A Vely application can run as a web application or a command line program, or both - such as when some requests can be either fulfilled through web interface or the command line. Note that Vely produces two separate executables: a FastCGI
server one and a command-line one - they are different because command-line program does not need the FastCGI library and thus is smaller.
The name of the command-line executable is the same as the application name, and its path is (assuming <app name> is the application name):
/var/lib/vv/bld/<app name>/<app name>
A command line program works the same way as a FastCGI executable, and the output is the same, except that it is directed to stdout (standard output) and stderr (standard error).
To specify the exit code of a command line program, use exit-code
. To exit the program, use exit-request
, or otherwise the program will exit when it reaches the end of a request
Executing a request
A command line program must obtain its request URL via environment variables, for example if the application name is "stock", here is how to execute a request "add-stock" with input-param
eters "name" having a value of "ABC" and "price" a value of "300":
Note that you if specify parameters as part of the path, you could write the above the same way as in a URL:
Including a request body
You can include a request body when executing a command-line program. It is always included as the standard input (stdin) to the program.
You must provide the length of this input (as CONTENT_LENGTH environment variable), the type of input (as CONTENT_TYPE), as well as REQUEST_METHOD (such as POST, PUT, PATCH, GET or DELETE).
Here is an example of using a request body to make a POST request on the command line - the application name is "json" and request name is "process". File "prices.json" is sent as request body:
export CONTENT_LENGTH=$(stat -c%s prices.json)
cat prices.json | /var/lib/vv/bld/ordering/ordering
Note that you can also include any other headers as environment variables by using the "HTTP_" convention, where custom headers are capitalized with use of underscore for dashes and prefixed with "HTTP_", for example header "Vely-Header" would be set as:
export HTTP_VELY_HEADER="some value"
Suppressing HTTP header output for the entire application
If you wish to suppress the output of HTTP headers for all requests, set environment variable VV_SILENT_HEADER to "yes" before executing the program:
This will suppress the effect of out-header
, or for any other case where headers are output. This has the same effect as silent-header
, the only difference is that it applies to the entire application.
URL-encoding the input
Any data in QUERY_STRING or PATH_INFO must be formatted to be a valid URL; for example, data that contains special characters (like "&" or "?") must be URL-encoded, for instance:
In this case, field "data" has value of "a?b", where special character "?" is encoded as "%3F".
To make sure all your input parameters are properly URL-encoded, use Vely's v1 code processor:
$($(vv -l)/v1 -urlencode '<your data>')
For instance, to encode "a?=b" as a parameter:
export QUERY_STRING="act=show&data=$($(vv -l)/v1 -urlencode 'a?=b')"
You can also use a command line program with CGI
(Common Gateway Interface). Note that CGI programs generally exhibit much lower performance; use CGI only when warranted by a specific situation.