Skip to main content

Stof 0.11.4: Rust, JavaScript, and Python

CJ Cummings
Creator and maintainer of Stof, co-founder & CEO of Limitr

More and more of the logic in an app is written by someone other than the app's developers. A model drafts a pricing rule or an agent tool. A customer sets up their own scoring, routing, or approval rules. Your app has to run that logic on every request, inside the process, without giving it the keys to everything else.

That's the job Stof does. The logic arrives as a document: JSON with functions. Your app loads it, hands it the few functions it may call, sets a time and memory limit, and calls it. The document can't reach anything else.

Stof 0.11.4 makes that the same job in all three languages Stof runs in. Rust is where it's built, JavaScript runs it through WebAssembly, and with this release Python is first-class too: a prebuilt wheel for every platform, and the bugs that made Python hosts awkward are fixed.

npm i @formata/stof@latest # TypeScript / JavaScript
pip install -U stof # Python
cargo add stof # Rust

The stof command line is now prebuilt for macOS, Linux, and Windows, so it no longer needs Rust:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dev-formata-io/stof-cli/releases/latest/download/stof-cli-installer.sh | sh

On Windows, and for other ways to install, see Install.

One document, any host​

Here's a customer's pricing rule. It calls one function the app gives it, App.plan, and nothing else:

price.stof
fn price(customer: str, tokens: int) -> float {
const rate = App.plan(customer) == 'enterprise' ? 0.002 : 0.004;
tokens * rate
}

The app side is the same four steps in each language:

import { StofDoc } from '@formata/stof';

const doc = await StofDoc.new();
doc.lib('App', 'plan', (id: string) => plans.get(id) ?? 'starter'); // all it can call
doc.setMaxExecutionTime(50); // ms
doc.parse(policy);

await doc.call('price', 'acme', 1200); // 2.4

Rust works the same way, with Graph and Runtime::call. Using Stof in Your App shows every step in all three languages: pick yours on any example, and the docs follow. The document doesn't change between them, and neither does its answer. A rule written once can be checked in a Python service, run in a Node.js API, and previewed in the browser.

Python, first-class​

A wheel for every platform. pip install stof now finds a prebuilt wheel on Linux (x86_64 and ARM), macOS (Intel and Apple silicon), and Windows, for every Python from 3.8 on, including versions that aren't out yet. The wheels use Python's stable ABI, so there's one per platform instead of one per Python version, and nothing compiles on install. Stof also stopped linking the system's OpenSSL (it uses rustls with your OS's certificates), so the Linux wheels install on any glibc Linux from 2014 on.

Host functions belong to each document. Before 0.11.4, Python kept doc.lib(...) functions in one table per thread, keyed by name. Two documents that registered the same name both called whichever was registered last, so per-customer functions crossed between customers. Now each document keeps its own, the way the JavaScript and Rust packages do:

acme, globex = Doc(), Doc()
acme.lib('App', 'plan', lambda: 'enterprise')
globex.lib('App', 'plan', lambda: 'starter')

for doc in (acme, globex):
doc.parse("fn plan() -> str { App.plan() }")

print(acme.call('plan'), globex.call('plan')) # enterprise starter

Any thread. For the same reason, a document called from a thread other than the one that registered its functions couldn't find them, which broke web servers with worker threads. A document's functions now go wherever the document goes. (Calls on one document still run one at a time, so guard a shared document with a lock, or give each thread its own.)

Faster. The Python package uses mimalloc under Stof's memory-counting allocator. Through Limitr's Python SDK, that made pricing checks 16 to 25% faster and loading the engine up to a fifth faster. Memory limits count exactly as before.

Faster everywhere​

The runtime does the same work with fewer allocations. Measured in CPU instructions, function calls take about 21% fewer, loops about 12% fewer, and Limitr's pricing checks about 14% fewer. Nothing about behavior changed; every test suite passes, Limitr's included.

For a sense of scale, measured from Python on a small Linux machine: a small document parses in about 0.2 ms, and a call takes 3 to 5 µs. That's in-process, with no server and no cold start. Performance has the numbers and tips for keeping things fast.

Arrow functions are closures​

This is the one change in behavior, and it's a fix. An arrow function used to keep the variables it captured on the function itself, so the latest evaluation replaced them for every copy. Arrows made in a loop all saw the last iteration, and a function returning an arrow gave every arrow the last call's arguments. Now each evaluation keeps its own variables, like closures in JavaScript, Python, or Rust:

closures.stofPlayground ↗
fn adder(n: int) -> fn {
  (x: int): int => x + n
}

#[main]
fn main() {
  const add1 = self.adder(1);
  const add10 = self.adder(10);
  pln(add1(5), add10(5));      // 6, 15

  const handlers = [];
  for (const i in 3) handlers.push_back((): int => i);
  pln(handlers.map((h: fn): int => h.call()));   // [0, 1, 2]
}
Output

An arrow also looks in its own variables before the variables of whatever function calls it, so what an arrow means doesn't depend on where it's called. If your code relied on a caller's variable replacing one the arrow captured, it now sees the captured one. Exported documents store an arrow as the function alone, as before, so digests and seals don't change. See Arrows Keep Their Variables.

Fixes​

  • A sealed part's time limit always lands outside it. When a confined part ran out of time, the error was caught outside it as it should be, but about once in 64 a second time-limit error could fire while unwinding and go past the caller's try to your app. It failed safe (the part had stopped), but now the error is caught where it should be, every time.
  • A corrupt package no longer crashes the host. Unzipping a package with an unreadable entry panicked; now that entry is skipped. Packages also build with only the zip codecs Stof uses, which removes some C code from every build.

stof-cli 0.14.4 is built on this release, with mimalloc too, and its memory limits now count everything a document allocates. It's also the first release with prebuilt binaries and one-line installers, so the CLI and the language server behind the VS Code extension no longer need a Rust toolchain.

The changelog has every detail. If you're running logic someone else wrote, in any of the three languages, I'd love to hear how. Find us on Discord or GitHub.