Tutorial 01 / 10 minutes

Make your first process.

If you’ve ever had one stuck goroutine or one bad request knock over a whole Go service, this is for you. In ten minutes you’ll install Goer, run a tiny program that crashes on purpose and keeps going anyway, and read the two short files that make that happen. By the end you’ll know what a process is and how to start your own.

Here’s a picture to hold on to. It’s made up, but it helps. Imagine a small shop with one order counter. Customers drop notes in a tray. One clerk reads them, one at a time, and writes in a ledger nobody else is allowed to touch. In Goer that clerk is a process, the tray is its mailbox, and the ledger is its state.

1. Install the tool and get the examples

The goer command builds and runs Goer programs. It sits on top of the normal go command, so install Go first if you haven’t. Then grab the build for your computer from the download page, unpack it, and put goer somewhere on your PATH. Check it worked:

goer version

The examples live in the Goer repository itself, so clone it and work from the top folder:

git clone https://gitlab.com/earnest-ventures/goer.git
cd goer

2. Run the counter

goer run ./examples/counter

That one command compiles the process code, builds the example, starts everything, and keeps it running until you press Ctrl-C. Twice a second the example sends the counter a message. Most of them add one. Every seventh one tells it to crash on purpose. This is a recording of what you’ll see:

See that? It crashed, and then it just kept counting. Nothing else in the program had to know or care. That’s the whole point, and the next two sections show you the two files behind it.

3. Read the process: the clerk’s rule book

The process is written in imgo, a cut-down version of Go that Goer compiles itself. An imgo file looks like ordinary Go with one extra line at the top: //go:build goer. That line tells the normal Go compiler to skip the file and tells goer to pick it up. Press run on this one if you like; it works right here.

//go:build goer && goer_source

package counter

type State struct{ Count int }
type Tick struct{}
type Boom struct{}
type Msg interface{}

func CounterInit() State { return State{} }

func Counter(s State, m Msg) State {
	switch m.(type) {
	case Tick:
		s.Count = s.Count + 1
	case Boom:
		panic("counter asked to crash")
	}
	return s
}

Read it like the clerk’s rule book:

Now look at what isn’t there. No goroutines. No locks. No channels. No pointers. imgo has no way to reach into another process’s memory, so you don’t have to be careful about it. It just can’t happen.

And that panic in the Boom case? That’s the clerk throwing their hands up and walking out. The next tutorial is about what happens next.

4. Read the Go side: hiring the clerk

The second file is regular Go. Its job is to start the process and send it messages.

// Package counter is a minimal Goer application: it is run with
//
//	goer run ./examples/counter
//
// There is no func main here. The package exposes Main(*goer.System), and the
// goer CLI owns process lifecycle — NewSystem, signal handling, Shutdown.
package counter

import (
	"fmt"
	"time"

	"goer"
	"goer/imgo"
	"goer/msg"
)

// Start adds the counter process to an existing Goer system. A package can
// expose this kind of explicit wiring function without starting global state
// from init.
func Start(sys *goer.System) error {
	behaviour, init, err := imgo.Executor(GoerModule, "Counter", nil)
	if err != nil {
		return err
	}

	c := sys.Spawn(
		"counter",
		goer.Init(init),
		goer.Behavior(behaviour),
		goer.RestartOnCrash,
	)

	go func() {
		t := time.NewTicker(500 * time.Millisecond)
		defer t.Stop()
		n := 0
		for range t.C {
			n++
			if n%7 == 0 {
				_ = c.Tell(&msg.Spec{Type: "Boom"}) // supervisor restarts it
				continue
			}
			_ = c.Tell(&msg.Spec{Type: "Tick"})
			fmt.Printf("tick %d — supervised restarts: %d\n", n, sys.Restarts())
		}
	}()

	return nil
}

// Main makes the example runnable with `goer run ./examples/counter`.
func Main(sys *goer.System) error { return Start(sys) }

Four lines do the real work:

The Start function is there to be polite. It lets another program import the counter and add it to its own system, without the counter starting anything behind its back.

5. Make your own

A Goer app is just a Go package with a Main function. Make a package, put your process code next to it in a //go:build goer file, and connect the two in Main:

package mysystem

import (
    "goer"
    "goer/imgo"
)

func Main(sys *goer.System) error {
    behaviour, init, err := imgo.Executor(GoerModule, "Counter", nil)
    if err != nil {
        return err
    }
    sys.Spawn("counter", goer.Init(init), goer.Behavior(behaviour), goer.RestartOnCrash)
    return nil
}

goer run ./mysystem

If Main returns nil, the system stays up until you stop it. If it returns an error, the program exits with that error. And if you’d rather write a normal package main, that still works. The tool leaves it alone.

What you just built

One process that owns one piece of data. Messages that ask it to do things. A runtime that gives it somewhere to run and someone to watch over it.

That’s the shape. Everything else in Goer builds on it.