loom

Loom

Loom is a design-first Go framework that turns one API definition into service interfaces, HTTP, gRPC, and JSON-RPC transports, type-safe clients, CLIs, and OpenAPI 3.2 contracts with an optional OpenAPI 3.1 compatibility target.

Quick start · Documentation · Go reference · Ask DeepWiki

Why Loom?

• Contracts you can build against. Loom emits OpenAPI 3.2.0 by default from one shared contract model. Set Meta("openapi:version", "3.1") to make the same renderer omit 3.2-only members while keeping the canonical output paths. Representative contracts are parsed with libopenapi, linted with Redocly, and compiled through Hey API and oapi-codegen in consumer smoke tests.
• One design, multiple transports. The same service model drives HTTP, gRPC, and JSON-RPC servers and clients. SSE and WebSocket endpoints publish explicit message and handshake metadata under x-loom-async.
• Framework-owned API behavior. Validation, authentication, CORS, RFC 9457 problem responses, streaming, and transport observability are modeled once instead of being rebuilt around every handler.
• Repeatable generation. loom gen stages and validates the complete output before replacing generated files. Humans and coding agents follow the same design → generate → implement workflow.

How it works

Design files are the source of truth. Generated files live under gen/; your business logic stays in ordinary, non-generated Go files.

Loom and Goa

Loom was derived from Goa and retains its design-first model: describe the service in a Go DSL, generate the transport layer, and implement the resulting service interface.

Loom is intended for teams that specifically need:

• OpenAPI 3.2 with a version-gated 3.1 compatibility target as a tested machine-facing contract;
• reusable contract components, request/response schema separation, and explicit async metadata;
• RFC 9457 HTTP errors and framework-owned session, CORS, streaming, and observability behavior;
• transactional code generation and compile-time generator extensions.

Goa remains the original project with the larger established community. If Loom's contract and transport guarantees are not requirements, Goa may be the better fit. Loom is actively diverging and does not promise source compatibility with every Goa release.

Quick start

Loom requires the Go version declared in go.mod, currently Go 1.27 or later.

Install the CLI and create a module:

go install github.com/CaliLuke/loom/cmd/loom@v1.10.0-alpha.5

mkdir hello && cd hello
go mod init example.com/hello
go get github.com/CaliLuke/loom@v1.10.0-alpha.5
mkdir design

Create design/design.go:

package design

import . "github.com/CaliLuke/loom/dsl"

var _ = Service("hello", func() {
	Method("greet", func() {
		Payload(func() {
			Field(1, "name", String, "Name to greet")
			Required("name")
		})
		Result(String)

		HTTP(func() {
			GET("/hello/{name}")
		})
	})
})

Generate the service and starter implementation:

loom gen example.com/hello/design
loom example example.com/hello/design
go mod tidy

loom example writes consumer-owned stubs. Each stub returns loom.Fault until you replace it, so an unfinished route cannot report success.

In the generated starter file hello.go, replace the Greet method with:

func (s *hellosrvc) Greet(ctx context.Context, p *hello.GreetPayload) (string, error) {
	log.Printf(ctx, "hello.greet")
	return "Hello, " + p.Name + "!", nil
}

Run the service:

go run ./cmd/hello --http-port=8000

Then call it from another terminal:

$ curl http://localhost:8000/hello/Ada
"Hello, Ada!"

The same generation run creates a type-safe client and gen/http/openapi.{json,yaml}. Continue with the guided quickstart or explore the generated-code workflow.

Documentation

• Design: DSL reference and code generation
• Transports: HTTP, gRPC, and JSON-RPC
• Operations: error handling, interceptors, and production guidance
• Agent-assisted development: Loom skill

Project expectations

Loom is a code-generation framework: adopting it means keeping the design as the source of truth, regenerating after design changes, and committing generated code. If you prefer handwritten transport handlers or a schema-first workflow based on existing OpenAPI or Protocol Buffer files, Loom is probably not the right abstraction.

For releases and project activity, see GitHub Releases and GitHub Issues. Contributions are welcome; start with CONTRIBUTING.md.

License

Loom is available under the MIT License.