gor

A persistent Grain Runtime for Go. It is embeddable, runs as one Silo, and is designed for deterministic simulation testing.

Status: Single Silo features are implemented and usable. Cluster features are an optional preview. Detailed progress: ROADMAP.md

What this is

A Go library that makes a Grain with a GrainId, State, serialized Calls, and restart recovery your programming unit. You write Go interfaces and structs. gor handles Activation, Call ordering, persistence, and Reminders. A future Cluster is an optional extension, not the main line.

gor is a Go port of the Orleans runtime model. The Go API uses Go forms, but the product terms and runtime meaning follow Orleans. The main design rules are in the design documents:

• The programming model uses compile-time types.
• The generator creates Grain Reference implementations from Go interfaces. See design/codegen.md.
• One Silo is a first-class product. It needs no sidecar or remote service.
• Deterministic simulation testing is an architectural constraint. See design/testing.md.

Quick Start

Requires Go 1.25 or later. Start the device shadow example from the repository root:

go run ./examples/shadow/cmd/shadow

In another terminal, report and read one device:

curl -i -X POST http://localhost:8080/devices/device-1/reports \
  -H 'Content-Type: application/json' \
  -d '{"workshop_id":"assembly","state":"temperature=20"}'
curl http://localhost:8080/devices/device-1/shadow

The release test builds this command and verifies this HTTP flow. See the complete example guide for State, Reminders, and restart behavior.

What it does not do

gor does not provide these in 0.1.0; the boundaries are in docs/vision.md:

• No source or binary compatibility promise with Orleans.
• No Call Filters.
• No reentrant or interleaved Grain Calls.
• No Cluster operation tools or unbounded scale.

Documentation

• docs/vision.md describes the product direction.
• docs/programming-model.md defines the public model and API.
• design/ contains technical designs.
• research/ contains measured evidence.
• ROADMAP.md tracks implementation and release work.
• examples/shadow/ is a runnable device shadow service.

Development

make test        # unit tests
make sim         # deterministic simulation tests
make gen         # generator end-to-end tests
make net         # transport tests over real TCP
make lint        # vet + staticcheck
make external    # clean consumer and process restart proof

testing/synctest is the foundation of the deterministic test strategy.

License

MIT, see LICENSE.