Capy on Bearer

Capy is the language for Bearer application units. A Capy unit uses the .capy suffix. Bearer compiles each unit to WebAssembly and runs it for a request.

Project home: https://capy-bearer.openfu.com/

Bearer uses native C++ for its build and runtime implementation. C++ is not a supported application-unit language.

Install editor tools

Download capy-language-0.3.0.vsix and install it through VS Code's Extensions → … → Install from VSIX. It includes the language client and native compilers for Linux x86-64 and Apple Silicon macOS. For Remote SSH, connect first and install it in the SSH workspace extension host. No compiler-path setting or Bearer service is needed on these platforms.

For a standalone Linux compiler, download and unpack capy-editor-tools-0.3.0.tar.gz, then run its python3 install_editor_tools.py. The offline installer verifies checksums and installs under your home directory without root access or service changes. Checksums and corresponding source accompany the release.

See editor installation and artifact builds for supported platforms, existing-setting migration, bundle generation, provenance, and release boundaries. Generated artifacts are in dist/; the builder, offline dependencies and tests are maintained in this repository.

Start a page

Create site/hello.capy:

function RENDER(request : dval) {
    var name := string(request.query.name, {fallback: "guest"})
    request.out.headers["Content-Type"] = "text/plain; charset=utf-8"
    print("Hello, ", name, "!\n")
}

RENDER handles an HTTP request. It receives one copied dval request snapshot. Read request data from fields such as request.query, request.form, and request.body.

Use these handler forms for public entry points:

function RENDER(request : dval) {
    print("HTTP response\n")
}

function CLI(request : dval) {
    print("local command\n")
}

function WS(request : dval) {
    ws_send(string(request.body), false)
}

CLI runs only through the local CLI socket. Do not expose that socket through a web server. WS receives WebSocket data in request.body. Read message metadata from request.websocket.

Every Bearer handler takes exactly one request : dval parameter and returns no application value. See the Capy language specification for all handler forms and language rules.

Build

Build the WebAssembly core, then the native Bearer runtime:

bash scripts/build_core_wasm.sh
bash scripts/build_linux.sh

The build requires:

• clang++, build tools, and Linux development headers for dl, threads, sockets, and backtraces
• PCRE2 development headers and library
• OpenSSL development headers and library
• MySQL development tools, including mysql_config
• Wasmtime C API and C++ headers, plus libwasmtime.so, at /opt/wasmtime or WASMTIME_HOME
• WASI SDK tools at /opt/wasi-sdk or WASI_SDK, including clang++ and wasm-ld

Bearer vendors SQLite and miniz. You do not need system SQLite or zlib packages for those libraries.

The native runtime binary is bin/bearer_fastcgi.linux.bin. The core build writes bin/wasm/core.wasm.

Run and deploy

Bearer runs behind nginx or Apache. The web server serves static files and sends .capy requests to Bearer's FastCGI socket. It sends WebSocket upgrades to Bearer's HTTP and WebSocket listener.

Read docs/setup.md for installation, configuration, service management, nginx, Apache, and verification steps.

Learn Capy

• Capy language specification
• Capy guide
• Generated Capy API signatures
• Runtime tests

Run the documentation checks after changing Capy documentation:

python3 scripts/check_capy_doc_examples.py --self-test
python3 scripts/check_capy_doc_examples.py
scripts/test_capy_guide_examples.sh

The guide test needs a running local Bearer service. It compiles guide snippets and checks one rendered example from each guide page.