benzene-go

A Go port of Benzene, a middleware-based library for hexagonal (ports-and-adapters) architecture: a pipeline of middleware wraps calls to "ports" (interfaces representing external boundaries - DB, HTTP, queues, etc), dispatched by topic to a registered handler.

This repo is conformant with the main repo's language-neutral specification - see conformance/ for the fixtures this port runs against. The spec, not this README, is the source of truth for cross-language behavior; when the two disagree, the spec wins and this repo has a bug.

Quickstart

package main

import (
	"context"
	"net/http"

	benzene "github.com/daniellepelley/benzene-go"
	"github.com/daniellepelley/benzene-go/httpbinding"
)

type greetRequest struct {
	Name string `json:"name"`
}

type greetResponse struct {
	Greeting string `json:"greeting"`
}

func greetHandler(_ context.Context, req greetRequest) benzene.Result[greetResponse] {
	return benzene.Ok(greetResponse{Greeting: "Hello, " + req.Name + "!"})
}

func main() {
	registry := benzene.NewRegistry()
	benzene.Register(registry, benzene.NewTopic("greet"), benzene.Handler[greetRequest, greetResponse](greetHandler))

	builder := &benzene.ApplicationBuilder{
		Registry:  registry,
		Container: benzene.NewContainer(),
		Pipeline:  benzene.NewPipeline(benzene.RouterMiddleware(registry)),
	}

	routes := []httpbinding.Route{{Method: http.MethodPost, Path: "/greet", Topic: benzene.NewTopic("greet")}}
	http.ListenAndServe(":8080", httpbinding.Handler(builder, routes))
}

See examples/helloworld/ for a complete version of this with dependency injection, a health check, and both HTTP entry points wired through the three-phase App lifecycle.

Packages

Every non-test-only package sits at 100% coverage, or just under it where the gap is a defensively-unreachable branch (documented at the call site - e.g. a json.Marshal failure on a type that can't actually fail to marshal). Run go test ./... -cover to see current numbers.

Deploying to a cloud provider

Each examples/*-helloworld directory's README documents the concrete deploy steps and states what was and wasn't verified in this repo's own CI sandbox. Each also has a matching GitHub Actions workflow (deploy-*.yml, one per example) that runs that same deploy on every push to main touching it - each is gated on its provider's credential secret being set, so the job shows as skipped (not failed) until you add the secrets/variables listed in that example's own README. None have been run for real from this repo (no live cloud credentials in this sandbox) - only the code, cross-compilation, and unit tests have been verified here.

Modules

This is a multi-module repo - see RELEASING.md for the full explanation (and for how Go's decentralized module distribution works at all, if you're coming from an ecosystem with a central package registry like NuGet). Short version: everything is one module except awssqs, awssns, awseventbridge, kafka, diagnostics, grpcbinding, examples/aws-sqs-helloworld, and examples/aws-sns-helloworld, which have their own go.mod because they need real third-party dependencies the rest of the repo shouldn't carry. go.work ties them together for local development.

Scope

This port covers core-concepts.md and wire-contracts.md end to end (pipeline, DI, health checks, HTTP binding + client, conformance, AWS/Azure/GCP deployment, SQS/SNS/Pub-Sub/Kafka/ gRPC bindings, CloudEvents) but does not yet have: gRPC's client-streaming/server-streaming/ duplex-streaming shapes (grpcbinding covers unary RPCs only - a documented scope decision, not an oversight; see its package doc), or a source-generator/codegen equivalent to the C# attribute-scanning sugar (per porting-guide.md, explicit registration is the framework contract in every language; attribute scanning is .NET-specific idiom, not something every port needs).

See ROADMAP.md for the fuller picture: what's next with zero new dependencies, what's next pending a dependency decision, and what's deliberately not being ported at all (and why). For how this project compares to the other ways of building cloud-portable services in Go (Dapr, Go CDK, Watermill, Encore) and when you'd pick each, see docs/comparison.md.

Benzene Mesh

Benzene Mesh - a fleet-wide, multi-cloud view of every service, its topics/schemas, health, and live traffic stats, derived from running services rather than declared in a catalog - is designed in docs/design/ (mesh.md, with a static mockup of the Fleet Overview screen and the research and positioning behind it). All phases of its delivery plan are complete: the mesh and meshd packages and the examples/mesh-helloworld demo above implement it, and the wire contracts are promoted and merged as the main repo's docs/specification/mesh.md - now the normative text. The main repo's .NET implementation (Benzene.Mesh.Wire + Benzene.Mesh.Collector) is the primary implementation of that contract; this port is a fully conforming implementation - the contract was originally extracted from it, the vendored mesh-*.json fixtures in conformance/ pin it and pass, and the two implementations have hosted each other's services in live cross-language fleets.

Both implementations also follow the spec's default service standard (the main repo's docs/specification/design-principles.md): framework-provided HTTP surfaces mount under a well-known /benzene/ prefix - here httpbinding.EnvelopePath (/benzene/invoke), httpbinding.HealthPath (/benzene/health), and meshd.ViewPath (/benzene/fleet-ui) - so they read as infrastructure rather than domain endpoints, with every path overridable per service. The same document records the wider "opinionated but optional" strategy the port already embodies: message handlers, like everything else, are the steer, never a requirement.

Developing

go build ./...
go vet ./...
gofmt -l .              # should print nothing
go test ./... -race -cover

CI (.github/workflows/ci.yml) runs all of the above on every push/PR to main.

License

MIT - see LICENSE.