Services the size of functions.

01 · proc.Context

A context is a supervised tree.

proc.Context opens a supervised context on the parent ctx. Every proc.Go schedules a proc — a func(context.Context) error — onto it, and proc.Wait blocks until they finish. The tree lives on the ctx, so cancellation, deadlines, and values flow the way Go code already expects.

ctx, cancel := proc.Context(ctx)
defer cancel()
proc.Go(ctx, pollInventory)
proc.Go(ctx, pruneSessions)
proc.Go(ctx, reportMetrics)
return proc.Wait(ctx)

02 · proc.Wait

proc.Wait observes the first failure.

A bare proc.Go is fail-fast. A failure — a non-nil error, or a panic, recovered and wrapped — cancels its siblings through the shared context, and the first failure is what Wait returns once every proc has finished. Errors propagate the errgroup way, and a panic fails the proc.Context, not the program.

proc.Go(ctx, migrate)
proc.Go(ctx, preload)
proc.Go(ctx, inspect) // fails
err := proc.Wait(ctx) // inspect's error

03 · proc.Keep

Keep restarts on error.

proc.Keep lifts a body into a restart loop — the long-lived service shape. Any non-nil return or recovered panic re-invokes the body, under exponential backoff once failures cluster. A clean nil return means the proc is done, and the loop exits: nil is death, on purpose.

proc.Go(ctx, watchQueue, proc.Keep())

04 · proc.Solo

Solo runs exactly one, cluster-wide.

proc.Solo is Keep plus a cluster-wide claim: at most one peer runs the body at a time. The claim rides the same broker the messages do — there is no separate coordination service to operate. When the holding peer dies, its claim lapses and another peer picks the body up.

proc.Go(ctx, deliverMail, proc.Solo("mailer"))

proc.Go(
	ctx, deliverMail, proc.Solo("mailer"),
)

The body's ctx is claim-scoped. Losing the claim cancels it, so a deposed holder winds down instead of racing its successor.

The claim is broker state, not host state. Kill every peer at once and the first one back picks the work up again — scaling to zero is not a special case.

05 · proc.Many

Many is Solo, times N.

proc.Many("resize", 4) claims four slots across the cluster, each one a Solo under the names resize-1 through resize-4. The slots share the cohort resize — a cohort is the group a channel load-balances across, and supervisors set it from their name — so a Recv inside the body splits the channel across the whole pool.

proc.Go(ctx, resizeImages, proc.Many("resize", 4))

proc.Go(
	ctx, resizeImages, proc.Many("resize", 4),
)

proc.Each is the complement: one copy on every peer rather than N across the cluster — the http daemon from the opening example.

06 · proc.Send / proc.Recv

Messages arrive in order, at least once.

Send publishes a typed value to a named channel. Recv yields each claimed message into an ordinary range loop, and the loop's control flow settles it — reaching the end of the body acks — commits the message; break, return, or panic naks — rejects it, and the broker redelivers. Delivery is at-least-once, FIFO within a channel and cohort.

for ctx, o := range proc.Recv[Order](ctx, "orders") {
	process(ctx, o)
}

for ctx, o := range proc.Recv[Order](
	ctx, "orders",
) {
	process(ctx, o)
}

A consumer that dies mid-message loses nothing. The message returns to the channel and is delivered again, in order; an idempotent handler makes the duplicate harmless.

07 · proc.Chan

One proc, many inboxes.

One goroutine, several typed message streams, handled in one place so the state they touch stays consistent — Go’s own select, with durable settlement on every arm. proc.Chan turns a channel into a plain Go <-chan for select — and hands you the settlement: you call Ack or Nak on every delivery yourself.

proc.Go(ctx, func(ctx context.Context) error {
	select {
	case d := <-proc.Chan[Order](ctx, "orders"):
		add(ctx, d.Value)
		d.Ack(ctx)
	case d := <-proc.Chan[Cancel](ctx, "cancels"):
		drop(ctx, d.Value)
		d.Ack(ctx)
	case <-ctx.Done():
		return nil
	}
	return proc.ErrContinue
}, proc.Solo("inbox"))

proc.Go(ctx, func(
	ctx context.Context,
) error {
	select {
	case d := <-proc.Chan[Order](
		ctx, "orders",
	):
		add(ctx, d.Value)
		d.Ack(ctx)
	case d := <-proc.Chan[Cancel](
		ctx, "cancels",
	):
		drop(ctx, d.Value)
		d.Ack(ctx)
	case <-ctx.Done():
		return nil
	}
	return proc.ErrContinue
}, proc.Solo("inbox"))

Chan is the power-user primitive. Recv acks by control flow and cannot leak a message; with Chan a dropped delivery stays in flight until the scope ends. The channel is never closed — when the context ends it simply goes quiet, so the ctx.Done() arm is the select's one exit. Reach for Chan when a proc needs several channels; prefer Recv everywhere else.

Note the shape: one message per invocation, and Keep owns the loop — returning proc.ErrContinue asks for the next invocation without counting as a failure. The restart reaps every consumer the invocation minted, so the Chan calls can sit inline in the select.

08 · proc.Query / proc.Serve

RPC through messages.

proc.Serve runs the dispatch loop for a channel — each arriving query invokes the handler, and the reply lands in the requester's inbox. proc.Query sends one query and blocks for the reply. Both ride the same Send and Recv underneath, so there is no second RPC system to operate — and because a query is just a message in a queue, the server does not need to be up the instant it is sent. A restart or a blip delays the reply instead of failing it.

double := proc.ServerFunc[int, int](
	func(_ context.Context, n int) (int, error) {
		return n * 2, nil
	},
)
proc.Go(ctx, func(ctx context.Context) error {
	return proc.Serve(ctx, "double", double)
}, proc.Solo("double"))

reply, ok := proc.Query[int, int](ctx, "double", 21)
if ok {
	fmt.Println(reply) // Output: 42
}

double := proc.ServerFunc[int, int](
	func(_ context.Context, n int) (
		int, error,
	) {
		return n * 2, nil
	},
)
proc.Go(ctx, func(
	ctx context.Context,
) error {
	return proc.Serve(ctx, "double", double)
}, proc.Solo("double"))

reply, ok := proc.Query[int, int](
	ctx, "double", 21,
)
if ok {
	fmt.Println(reply) // Output: 42
}

Serve is at-least-once, and so is the reply. A handler that dies before its ack runs again on redelivery, and a crash mid-reply can deliver the answer twice — so handlers stay idempotent, and requesters treat a duplicate reply as the same news.

09 · proc.Go

Durable execution through durable messaging.

Long-running, multi-step work is procs connected by channels. Each step Recvs its input, does one unit of work, and Sends the result onward. Every hop is durable — a step that crashes or deploys mid-message naks it, restarts, and the pipeline resumes exactly where it stopped.

proc.Go(ctx, step1, proc.Solo("step1"))
proc.Go(ctx, step2, proc.Solo("step2"))
proc.Go(ctx, step3, proc.Solo("step3"))

This is durable execution with no separate engine to operate — the broker you already run is the engine. The state of the pipeline is the messages in flight, and the substrate already persists those.

10 · proc.Load

A cluster-wide cron in one body.

Periodic work in a distributed system asks for three things at once — exactly one runner, durable schedule state, and sane behavior through crashes. Each maps to one primitive. Solo gates the runner. Load and Send keep the last-run timestamp in the substrate. ErrContinue hands the loop to Keep, so the body is one tick.

proc.Go(ctx, func(ctx context.Context) error {
	last, ok := proc.Load[time.Time](
		ctx, "cron/backup/last",
	)
	if !ok {
		return nil
	}
	next := schedule.Next(last)
	select {
	case <-ctx.Done():
		return nil
	case <-time.After(time.Until(next)):
	}
	defer proc.Send(ctx, "cron/backup/last", next)
	return cmp.Or(runBackup(ctx), proc.ErrContinue)
}, proc.Solo("cron/backup"))

proc.Go(ctx, func(
	ctx context.Context,
) error {
	last, ok := proc.Load[time.Time](
		ctx, "cron/backup/last",
	)
	if !ok {
		return nil
	}
	next := schedule.Next(last)
	select {
	case <-ctx.Done():
		return nil
	case <-time.After(time.Until(next)):
	}
	defer proc.Send(
		ctx, "cron/backup/last", next,
	)
	return cmp.Or(
		runBackup(ctx), proc.ErrContinue,
	)
}, proc.Solo("cron/backup"))

The deferred Send records the tick only if the work ran. A crash mid-run leaves the timestamp untouched, so the next holder re-runs the missed tick — at least once, never zero.

11 · proc.Save

A channel is also a value.

Load reads the latest message on a channel; Save appends one — but only if the caller has seen the current head. Together they make every channel a durable KV cell with optimistic concurrency. Two writers cannot silently overwrite each other; the loser learns, re-reads, and retries.

func bump(ctx context.Context) error {
	for {
		n, ok := proc.Load[int](ctx, "counter")
		if !ok {
			return nil
		}
		saved, ok := proc.Save(ctx, "counter", n+1)
		if !ok || saved {
			return nil
		}
	}
}

func bump(ctx context.Context) error {
	for {
		n, ok := proc.Load[int](
			ctx, "counter",
		)
		if !ok {
			return nil
		}
		saved, ok := proc.Save(
			ctx, "counter", n+1,
		)
		if !ok || saved {
			return nil
		}
	}
}

Conflict is a normal-flow signal, not an error. And Load is at-most-once by design — it advances past whatever it reads — which is the other half of the delivery spectrum, there when a problem calls for it.

12 · proc.Broker

Distributed in production. Local on your laptop.

The broker is the only thing that changes. With the in-memory broker, every proc — the per-peer daemons, the singletons, the whole pool — runs in one process under go run, including the claims. Swap in a durable broker and the same binary spreads across the cluster by supervisor shape — Each on every peer, Solo on exactly one, Many filling its slots.

var broker proc.Deriver = new(mem.Broker)
if os.Getenv("PGHOST") != "" {
	pool, err := pgxpool.New(ctx, "")
	if err != nil {
		log.Fatal(err)
	}
	broker = &procpgx.Broker{Pool: pool}
}
ctx, cancel := proc.Context(ctx, broker)

var broker proc.Deriver = new(mem.Broker)
if os.Getenv("PGHOST") != "" {
	pool, err := pgxpool.New(ctx, "")
	if err != nil {
		log.Fatal(err)
	}
	broker = &procpgx.Broker{Pool: pool}
}
ctx, cancel := proc.Context(
	ctx, broker,
)

Brokers sit behind proc.Deriver, a four-method interface. Postgres is supported today via lesiw.io/procpgx; NATS JetStream and Redis are under consideration.

13 · proc.Epoch

New code proves itself before old code is gone.

Every peer stamps its build with an epoch — by default the commit timestamp, read from the binary's VCS metadata, with an override for explicit stamps.

e=$(date -u +%s)
go build -ldflags="-X lesiw.io/proc.Epoch=$e" .

e=$(date -u +%s)
go build \
	-ldflags="-X lesiw.io/proc.Epoch=$e" .

During a rolling deploy the cluster sees both epochs at once. The moment a majority of connected peers reports the new one — membership is connection, so the denominator is whoever is heartbeating — every Solo migrates onto new-epoch peers — the new build takes over the singletons while the old build is still running beside it. A Solo that regresses on the new build fails fast, under supervision, before the rollout finishes.

ctx, cancel := proc.Context(ctx,
	proc.WithTripwire(time.Minute),
	&procpgx.Broker{Pool: pool},
)

WithTripwire arms the window: for its duration after startup, a supervised body's error surfaces through Wait instead of restarting, so a bad rollout halts loudly rather than crash-looping quietly.

14 · Partitions

A partitioned peer fences itself.

Every peer heartbeats through the broker. A peer that loses its transport stops hearing back, and past a threshold it assumes the cluster can no longer see it — so it cancels its own procs, before the cluster re-grants its claims. A deposed singleton never races its successor.

Inside the fenced peer, bodies see plain ctx-cancel — the same signal a deploy or a shutdown delivers.

for ctx, job := range proc.Recv[Job](ctx, "jobs") {
	handle(ctx, job)
}

for ctx, job := range proc.Recv[Job](
	ctx, "jobs",
) {
	handle(ctx, job)
}

Code that honors its ctx is already partition-correct; why a context ended is the supervisor's business, not the body's.

15 · One system of record

The broker is the state.

There is no membership protocol beside it — no seed URLs, no gossip, no bootstrap order. A peer that can reach the broker is a member; a peer that cannot, is not. Messages, claims, membership, and schedule state live in one durable system.

Transient failure is the substrate's problem. A flaky connection, a broker restart, a dropped packet — retried internally, invisible above. Your code sees two signals: messages, and cancellation.

Scaling to zero follows from the same fact. Peers hold no state, so an empty cluster is a quiet one; the messages wait in the broker, and the first peer back picks up where everything left off.

Get started

Start on the laptop.

go get lesiw.io/proc

Open a proc.Context with the in-memory broker, schedule bodies with proc.Go, and proc.Wait. When it is time for a cluster, import a durable broker and change that one line.

Coming from Erlang or CSP? The appendix works the classic problems in proc.