Proto.Actoralpha
Run Motoko actors as Proto.Actor cluster grains, with state in Postgres.
Each actor key is a Proto.Actor virtual actor (grain) in the cluster. The cluster places it and delivers its messages one at a time; its state is stored in Postgres.
You also need the moxzi SDK and hosts bundles; see Actor platforms.
Prerequisites#
- Go 1.22 or later
- Docker, for Postgres (or your own database with
DATABASE_URL)
Create and run a project#
moxzi host new protoactor hellocd hello
ONCE=1 ./run.shactor.mo -> actor.wasm + actor.did (245563 bytes, 1 file(s), 50 steps, 0.60s)
Counter/1.inc() -> [1]Run it a second time. The host is a new process, and the actor's state comes back from the platform's store:
ONCE=1 ./run.shactor.mo -> actor.wasm + actor.did (245563 bytes, 1 file(s), 50 steps, 0.64s)
Counter/1.inc() -> [2]ONCE=1 exits after the demo. Without it, the host keeps running on port 8090 (set PORT to change it), and you can call any key:
curl -X POST localhost:8090/actors/Counter/2/method/inc \
-H 'content-type: application/json' -d '[]'--example ledger and --example saga work on Proto.Actor too; see Examples.
The project#
| Path | Contents |
|---|---|
actor.mo | The Counter actor type. Each key Counter/ID is a separate actor |
host/ | moxzi's Proto.Actor adapter. It's yours to change |
run.sh | Builds the actor and the host, starts what Proto.Actor needs, and runs the demo |
Change actor.mo and run ./run.sh again. New keys use the new code. Existing keys keep their code until they're upgraded; host/README.md describes upgrades.
How it maps#
| Handled by | |
|---|---|
| One message at a time per key | The Proto.Actor grain |
| Placement | The Proto.Actor cluster |
| Actor state | Postgres, in a Docker container named moxzi-hello-pg on port 55432 that run.sh starts and leaves running. Set DATABASE_URL to use your own database, or PG_PORT to use another port |
| Durable timers | A _timers table in Postgres, checked every 200 ms. Each timer fires once even with several hosts |
Remove the database container with docker rm -f moxzi-hello-pg when you're done.
Configuration#
| Variable | Default | Effect |
|---|---|---|
PORT | 8090 | The host's HTTP port |
MOXZI_HOST_TOKEN | random | Token for the host's control endpoints (/_moxzi/*) |
DATABASE_URL | a local container | Postgres connection string |
PG_PORT | 55432 | Port for the local Postgres container. All projects use the same default, so only one can run at a time |