Humus

A modular Go framework for building production-ready services with standardized observability, health checks, and graceful shutdown.

Humus is built on top of Bedrock and provides opinionated patterns for three types of applications:

Service Types

REST/HTTP Services

Build OpenAPI-compliant web applications with automatic schema generation, built-in health endpoints, and flexible request/response handling.

Get Started with REST →

gRPC Services

Create gRPC microservices with automatic OpenTelemetry instrumentation, health service registration, and seamless integration with the gRPC ecosystem.

Get Started with gRPC →

Job Services

Build one-off job executors for batch processing, migrations, or scheduled tasks with the same observability and lifecycle management as long-running services.

Get Started with Jobs →

Key Features

Batteries Included Observability

  • Automatic OpenTelemetry SDK initialization for traces, metrics, and logs
  • Integrated structured logging with slog
  • Zero-configuration instrumentation for HTTP and gRPC

Production Ready

  • Graceful shutdown with OS signal handling
  • Standardized health check patterns
  • Panic recovery middleware
  • YAML-based configuration with templating support

Developer Friendly

  • Minimal boilerplate with Builder + Runner pattern
  • Automatic OpenAPI schema generation from Go types
  • Type-safe request/response handling
  • Comprehensive examples and documentation

Quick Example

package main

import (
    "context"
    "net/http"

    "github.com/z5labs/humus/rest"
)

type Config struct {
    rest.Config `config:",squash"`
}

func main() {
    rest.Run(rest.YamlSource("config.yaml"), Init)
}

func Init(ctx context.Context, cfg Config) (*rest.Api, error) {
    handler := rest.ProducerFunc[string](func(ctx context.Context) (*string, error) {
        msg := "Hello, World!"
        return &msg, nil
    })

    api := rest.NewApi(
        "My Service",
        "v1.0.0",
        rest.Handle(
            http.MethodGet,
            rest.BasePath("/hello"),
            rest.ProduceJson(handler),
        ),
    )
    return api, nil
}

Next Steps

Resources