This section describes the Baresoil programming model at a more detailed technical level. Readers who prefer a more hands-on approach may prefer to skip to the walkthrough of a minimal example app instead.
A Baresoil application consists of a server component and a client component. Both are optional, but at least one is required.
index.htmlat the root of the domain, and then mapping URL paths to files. The top-level URL path
/__bs__/is reserved for system use.
Generally, both client and server components are required for webapps and hybrid mobile apps. If the server directory is empty, then the project becomes a simple static website. If the client directory is empty, the project becomes an API-only service.
Once an application has been deployed to Baresoil, it is available at a user-selected subdomain of the top-level domain
baresoil.cloud (if the demo server is being used; otherwise, use your own top-level domain).
A client is any device that establishes a
WebSockets are now, , and allow easy, TCP-like, two-way communication between client and server, while tunneling over existing HTTP(s) infrastructure. They allow a range of client/server programming models to be used over the same shared channel, such as remote procedure calls and server-sent events.
The following is a partial list of possible client types:
baresoilcommand is an example of this.
In other words, the web-hosted "client" portion of Baresoil projects is merely a convenience for webapps.
Once connected, clients send and receive line-delimited JSON messages in UTF-8 encoding, using a small, open protocol. This format is chosen to maximize compatibility with clients written in different languages, since JSON parsing and UTF-8 support are both commonly supported features. Individual messages are automatically compressed at the WebSocket layer, when standards-compliant WebSocket client libraries are used.
This also means that simple tools likecan be used to directly send and receive messages from a Baresoil server.
Once a client application connects to the
/__bs__/live WebSocket endpoint of your subdomain, Baresoil creates a lightweight, security-restricted virtual machine called a sandbox to serve that client, and only that client. The sequence of steps taken for each new client is the following:
Each sandbox is created only for the lifetime of a single client connection. Once the client disconnects, the sandbox is destroyed.
Under the hood, the sandbox is an enhanced, with limited CPU and memory resources, and a privilege-free sandbox. Outgoing HTTP and HTTPS network access, however, is permitted. The container includes multiple current versions of node.js, as well as other preinstalled software that can be spawned as child processes.
The SandboxDriver program is designed to allow server-side code that is concise, flexible, and easy to write. It is based around a collection of server-side handler functions, which are node.js functions that are executed at the server. The results of evaluating the functions are then passed back to the client.
All function evaluations for a single client connection occur inside the same process, so handler functions are free to interact with each other in any way required, and to use process-global variables if required (for example).
Once invoked, it performs the following steps to "launch" your server program once it is invoked.
$websocketon the start of new WebSocket connections, or
$httpto process HTTP PUT/POST/DELETE requests.
The source code foris part of the baresoil-server repository. The file main.js is the entry point invoked by the runtime.
The default SandboxDriver can be replaced by an alternative written in any other language, or by an opaque binary, by setting the server.driver key in baresoil.json to the command line to execute.
Next: Read a walkthrough tutorial of a simple application.