Vely architecture

18.4.0 released Sep 25, 2023

Vely architecture

Architecture overview

A Vely program works as a request-reply processor. It can be either an application server or a command-line program that processes GET, POST, PUT, PATCH, DELETE or any other HTTP requests.

Application server

When it is an application server, it runs as FastCGI (FCGI) server processes that clients access through a variety of ways:

via reverse proxies (typically web servers like Apache or Nginx),
FastCGI-API, which allows any application in virtually any programming language to access it,
FastCGI-command-line-client, to send a request and receive a reply from command line, suitable for scripting and testing.

Any number of such Vely FCGI processes can run, including a dynamic number determined by the request load (ranging from 0 resident processes to any maximum number specified). Each Vely FCGI process handles one request at a time, and any number of such processes work in parallel, which means code and libraries used do not have to be thread-safe.

A Vely program can contain some or all application layers, including

presentation (eg. building a web page),
application logic,
data (eg. database) layers.

These layers can run in a single server, or on multiple ones, depending on your application's architecture.

Command-line program

When a Vely application runs in the command-line, a request is handled by a single execution of a compiled program. This option may be suitable for batch jobs, for use in shell scripts, for testing/mocking, as well as any other situation where it is more useful or convenient to execute a command-line program. Note that a command-line program can double as CGI (Common Gateway Interface) programs as well; this option may be suitable when high performance is not needed, or for other reasons.

Built-in statements

A Vely program can access database, internet/network, file system and other computing resources by means of functional and declarative Vely statements. These statements are the building blocks of applications, as they provide solutions to most commonly used tasks.

Execution flowchart

Each request-URL by default states the application name and a request name, which is the source file handling it. So, "/app-name/my-request" means that application name is "app-name" and that "request_name()" function defined in file "request_name.vely" will execute. A request executes in this order:

Before the very first request, optional startup code executes (see startup-handler).
When a request is present, an optional before-request handler executes (see before-request-handler).
Next, Vely's request dispatcher will route the request to a function with the same name (in the example below, it's "void request_name()") that must reside in a file with the same name (i.e. "request_name.vely"); this is a request handler.
Finally, an optional after-request handler will execute (see after-request-handler). This concludes request processing.

Note that any .vely file name that starts with an underscore is a non-request file, that is, it doesn't process any requests and its code is used in other .vely files.

Distributed computing

Requests can be executed on remote servers via call-server and call-web; call-server is suitable for fast remote calls on local or secure networks; call-web makes a call to a remote web service, typically by using SSL/TSL secure connections.

With call-server, you can execute remote requests in parallel, and get results, error messages and exit status in a single command. This makes it easy to distribute and parallelize your application logic and/or build application tiers on a local or any number of remote machines, without having to write any multi-threaded code.

Performance

Vely applications are native executables by design. This approach avoids performance loss associated with other schemes, such as byte-code, interpreters and similar. Consequently, small memory footprint is achieved with minimal code overhead and by using on-demand dynamic libraries whenever possible; less memory consumption and higher performance allow for better scaling in high-demand environments.

Server processes generally stay up across any number of requests, increasing response time. The balance between the number of processes and the memory usage during high request loads can be achieved with adaptive feature of vf, Vely's FastCGI process manager. Since Vely processes running in parallel are single-threaded, programming with Vely does not present challenges of thread-based programming and increases run-time stability.

Database access

Vely provides access to a number of popular databases, such as MariaDB/mySQL, PostgreSQL and SQLite. (see database-config-file). It supports use of prepared database queries with true automatic unlimited reuse across any number of requests; database connections are persistent and stay connected for the life of the server process.

Proven libraries

Vely uses well-known and widely used Free Open Source libraries like cURL, OpenSSL, crypto, FastCGI, standard database-connectivity libraries from MariaDB, PostgreSQL, SQLite etc., for compliance, performance and reliability.

Stability

Vely statement-APIs are designed for safety, ease of use, encapsulation, and simple and declarative abstraction of tasks required, making it easier to write stable code. Handling of allocated memory includes memory tracking and automatic freeing, preventing memory leaks which can be fatal to long running processes; similarly, files open with file-handling statements are automatically closed at the end of each request, serving the same purpose. Request-processing and process daemon-izing infrastructure is included.

From source code to executable

All Vely code is in .vely files, which contain C code with Vely used within. To create an executable program, vv utility will preprocess .vely files into 100% C code, and link it. Linkage uses various libraries (database, internet etc.), and those are dynamically linked only if needed, keeping the executable the smallest possible. When code changes, Vely FCGI manager (vf) will restart the server (optional).

Vely programs are built in a single command-line step, and ready to use immediately (see vv). Flexible architecture means the exact same source code can run both as a server application (such as web application back-end) and a command-line program.