soma.cell

Metrics / health endpoint. Every request bumps a request counter;

GET /health returns status + uptime-style fields, GET /metrics the tallies.

A Soma program from the web part of the verified corpus: 63 lines, cells Metrics, MetricsTest. It passes soma check with soma 3.2.4.

How it is built

The cell Metrics declares 4 signals in its face: request(method: String, path: String, body: String) -> Map, hit(route: String) -> Int, health() -> Map and report() -> Map; keeps 1 memory slot: counters (Map<String, Int>, persistent and consistent). Handlers: hit (line 17), health (line 24), report (line 28) and request (line 36).

The file also holds 1 test cell (MetricsTest) with 3 assertions, run by soma test.

Generated from soma describe on this file.

The source

soma.toml

[package]
name = "web-corpus"
version = "0.1.0"
entry = "todo_state.cell"

[verify]
cells = ["TodoService"]
deadlock_free = true
eventually = ["Done", "Cancelled"]

metrics_api.cell

// Metrics / health endpoint. Every request bumps a request counter;
// GET /health returns status + uptime-style fields, GET /metrics the tallies.

cell Metrics {
    face {
        signal request(method: String, path: String, body: String) -> Map
        signal hit(route: String) -> Int
        signal health() -> Map
        signal report() -> Map
        promise all_persistent
    }

    memory {
        counters: Map<String, Int> [persistent, consistent]
    }

    on hit(route: String) {
        let c = counters.get(route)
        if c == () { c = 0 }
        counters.set(route, c + 1)
        return c + 1
    }

    on health() {
        return map("status", "ok", "checks", map("db", "up", "bus", "up"))
    }

    on report() {
        let total = 0
        for k in counters.keys {
            total = total + counters.get(k)
        }
        return map("routes", counters.len(), "total_hits", total)
    }

    on request(method: String, path: String, body: String) {
        hit(path)
        let req = map("method", method, "path", path)
        match req {
            {method: "GET", path: "/health"}  -> health()
            {method: "GET", path: "/metrics"} -> report()
            _                                 -> response(404, map("error", "no route"))
        }
    }
}

cell test MetricsTest {
    rules {
        assert health().status == "ok"
        assert health().checks.db == "up"
        assert _load() == "3|5"
    }

    on _load() {
        hit("/x")
        hit("/x")
        hit("/y")
        hit("/y")
        hit("/z")
        return concat(to_string(report().routes), concat("|", to_string(report().total_hits)))
    }
}

What the toolchain says

Run on a fresh copy of the program at build time; the outputs are pasted unedited.

$ soma check metrics_api.cell
✓ All checks passed.
$ soma test metrics_api.cell
test MetricsTest ...
  ✓ assert health().status == "ok"
  ✓ assert health().checks.db == "up"
  ✓ assert _load() == "3|5"

3 tests: 3 passed, 0 failed
$ soma verify metrics_api.cell
Verifying metrics_api.cell...
No state machine in this program: nothing to prove beyond `soma check` (invariants and lifecycles are what verify proves).
note: the soma.toml beside this file declares [verify] properties; none applies here (no state machine)
VERIFY OK (vacuous — no state machine)

Builtins used

concat, map, response, to_string

Source file: /corpus/web/metrics_api.cell · examples/corpus/web/metrics_api.cell