Humus
Humus is an opinionated Go framework for building services on
bedrock: HTTP and REST APIs, gRPC
services, jobs, Kafka and RabbitMQ consumers, and Kubernetes controllers. A
service is an Init that returns its Services, and humus.Main runs them
with telemetry, health and graceful shutdown built in, on defaults that fit
inside Kubernetes. humustest.Start runs the same service in a test.
Install
go get github.com/z5labs/[email protected]
A service
Init builds the service: here, a job that greets the name its environment
gives it, once.
func Init(ctx context.Context, s *humus.Setup) ([]humus.Service, error) {
name, err := config.Env(s.Process.Environment, "HELLO_NAME").Read(ctx)
if err != nil {
return nil, err
}
out := s.Process.Stdout
greet := func(context.Context) error {
_, err := fmt.Fprintf(out, "Hello, %s!\n", name)
return err
}
return []humus.Service{job.NewService(s, greet)}, nil
}
main hands it to humus.Main, which runs its Services until they return,
then exits with their status.
func main() {
humus.Main(Init)
}
The whole service, with its imports and its tests, is
example/job/hello.
Service types
Each service type has a docs section, a walkthrough of a production-ready
service, and that service's code.
Documentation
Getting started takes you
from an empty folder to a running, tested service. The
documentation site covers the rest, from
the App lifecycle to every service type.
Releases
humus is several Go modules: the root github.com/z5labs/humus, and the
nested grpc, queue/kafka, queue/rabbitmq and kube modules. Every
humus module is released with the same version on every release, whether or
not it changed, so one version names a set of modules that work together.
Each example, at example/<type>/<name> under its service type's folder,
is a module of its own too, and is never released.
Require the same version of every humus module you use:
go get github.com/z5labs/[email protected] github.com/z5labs/humus/[email protected]
A release updates every humus version the docs name, here and on the
documentation site, so they install the latest release. A pre-release leaves
them as they are.
The release workflow and how to run it are described in
.github/workflows/release.yaml.
Questions and proposals
Use GitHub Discussions: ask
questions in Q&A,
report bugs in Bugs,
and propose changes in
General.
Claude Code cloud sessions
This repository's stories are worked by the
backlog plugin,
which .claude/settings.json enables. A
Claude Code cloud session
ignores the plugins a repository enables, and its image's golangci-lint can be
too old to lint this repository's Go. Two scripts fix that, and both run as
SessionStart hooks:
install-plugins.sh declares the plugins
in the session's user settings, and
install-golangci-lint.sh installs
golangci-lint at the version
.github/workflows/build.yaml pins.
A hook runs after Claude Code has started, when the session's plugins are
already chosen. It only writes the settings, and a cloud session cannot run
the /reload-plugins its message suggests, so the hook alone cannot be relied
on to load the plugins there. golangci-lint needs no reload, so its hook is
enough for verify. A cloud session also drops the permissions.allow rules
in .claude/settings.json, because it never shows the workspace trust dialog,
and keeps only the deny rules.
cloud-setup.sh covers all three before
Claude Code starts. It copies the repository's permissions into user
settings, which need no trust, and then runs both scripts. Give this
repository a cloud environment of its own, and make this its setup script.
Open the environment menu in the session's title bar, then Edit:
bash /home/user/humus/.claude/hooks/cloud-setup.sh || true
A new session then has the plugins and the permissions from the first prompt.
The environment needs to be this repository's own because the environment,
not the repository, keeps what the setup script did. The script runs on the
environment's first session, and later sessions start from a
snapshot
of the disk without running it, so an environment shared with another
repository keeps whichever repository's setup built the snapshot. The
snapshot is rebuilt when the setup script or the allowed hosts change, or
after about seven days, so a change to cloud-setup.sh reaches new sessions
then. In between, the hooks keep the golangci-lint pin and the plugin settings
current.
cloud-setup.sh is for a cloud environment, not a laptop: it writes the
repository's permission list into user settings, which apply to every
repository Claude Code opens.
golangci-lint is downloaded from github.com, which redirects to
release-assets.githubusercontent.com. The default Trusted network level
reaches both.
License
Released under the MIT License.
