v1.6.2MITgo 1.18+github.com/xgodev/boost

Enterprise Go services.
Built fast.

Boot, config, logs, 58 factories, middleware, health and code generation in one framework. You write the business logic.

$go get github.com/xgodev/boost

Get started

58factories 46libraries 107plugins 221releases since 2024

A complete service: one route, a service, a repository and two datastores. The generated files and the run are the real output.

github.com/acme/shop

internal/

app/

api/rest/

handler/stock/reserver/

pkg/

domain/

service/stock/reserver/

local/

repository/stock/

datastore/stock/

memory/

mongodb/

you writeinternal/app/api/rest/handler/stock/reserver/handler.go

// Package reserver serves POST /stock/:sku/reserve.
package reserver

import (
	"net/http"

	"github.com/acme/shop/internal/pkg/domain/service/stock/reserver"
	"github.com/labstack/echo/v4"
)

// Handler reserves one unit of an item.
type Handler struct {
	svc reserver.Service
}

// New provides the handler to the generated rest door.
// @Provide(index=0)
func New(svc reserver.Service) *Handler {
	return &Handler{svc: svc}
}

// Handle reserves one unit of the sku in the path.
// @REST(method=POST, path=/stock/:sku/reserve)
func (h *Handler) Handle(c echo.Context) error {
	if err := h.svc.Reserve(c.Request().Context(), c.Param("sku")); err != nil {
		return err
	}
	return c.NoContent(http.StatusNoContent)
}

you writeinternal/app/api/rest/plugins.go

// Package rest holds what the rest server of app api needs besides its
// handlers.
package rest

import (
	boostecho "github.com/xgodev/boost/factory/contrib/labstack/echo/v4"
	"github.com/xgodev/boost/factory/contrib/labstack/echo/v4/plugins/extra/error_handler"
)

// Plugins turns boost errors into HTTP statuses: a Conflict answers 409.
// @Provide(index=0)
func Plugins() []boostecho.Plugin {
	return []boostecho.Plugin{error_handler.Register}
}

you writeinternal/pkg/domain/service/stock/reserver/local/service.go

// Package local reserves stock in process, on the stock repository.
package local

import (
	"context"

	"github.com/acme/shop/internal/pkg/domain/repository/stock"
	"github.com/acme/shop/internal/pkg/domain/service/stock/reserver"
)

type service struct {
	repo stock.Repository
}

// New provides the service, wrapped in the log and prometheus middlewares.
// @Provide(index=0)
// @Middleware(log, prometheus)
func New(repo stock.Repository) reserver.Service {
	return &service{repo: repo}
}

func (s *service) Reserve(ctx context.Context, sku string) error {
	return s.repo.Take(ctx, sku)
}

you writeinternal/pkg/domain/service/stock/reserver/service.go

// Package reserver reserves one unit of an item.
package reserver

import "context"

// Service reserves stock.
type Service interface {
	Reserve(ctx context.Context, sku string) error
}

you writeinternal/pkg/domain/repository/stock/repository.go

// Package stock is the persistence of the units in stock.
package stock

import "context"

// Repository keeps the units in stock of each item.
type Repository interface {
	// Take removes one unit of sku; a sold-out sku is a Conflict.
	Take(ctx context.Context, sku string) error
}

you writeinternal/pkg/datastore/stock/memory/datastore.go

// Package memory keeps the stock in memory: the default, no infra needed.
package memory

import (
	"context"
	"sync"

	"github.com/acme/shop/internal/pkg/domain/repository/stock"
	"github.com/xgodev/boost/model/errors"
)

type datastore struct {
	mu    sync.Mutex
	units map[string]int
}

// New provides the stock wired when no other is configured.
// @Provide(index=0)
// @Default
func New() stock.Repository {
	return &datastore{units: map[string]int{"tshirt": 3}}
}

func (d *datastore) Take(_ context.Context, sku string) error {
	d.mu.Lock()
	defer d.mu.Unlock()
	if d.units[sku] == 0 {
		return errors.Conflictf("%s is sold out", sku)
	}
	d.units[sku]--
	return nil
}

you writeinternal/pkg/datastore/stock/mongodb/config.go

package mongodb

// Options configures the mongo stock; inject generates its config keys.
// @Config
type Options struct {
	Collection string `default:"stock" desc:"collection of the units in stock"`
}

you writeinternal/pkg/datastore/stock/mongodb/datastore.go

// Package mongodb keeps the stock in MongoDB, on boost's mongo factory.
package mongodb

import (
	"context"

	"github.com/acme/shop/internal/pkg/domain/repository/stock"
	mongofact "github.com/xgodev/boost/factory/contrib/go.mongodb.org/mongo-driver/v2"
	"github.com/xgodev/boost/model/errors"
	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
)

type datastore struct {
	coll *mongo.Collection
}

// New connects through boost's mongo factory (boost.factory.mongo.*).
// @Provide(index=0)
func New(ctx context.Context, o *Options) (stock.Repository, error) {
	conn, err := mongofact.NewConn(ctx)
	if err != nil {
		return nil, err
	}
	return &datastore{coll: conn.Database.Collection(o.Collection)}, nil
}

func (d *datastore) Take(ctx context.Context, sku string) error {
	res, err := d.coll.UpdateOne(ctx,
		bson.M{"_id": sku, "units": bson.M{"$gt": 0}},
		bson.M{"$inc": bson.M{"units": -1}})
	if err != nil {
		return err
	}
	if res.MatchedCount == 0 {
		return errors.Conflictf("%s is sold out", sku)
	}
	return nil
}

you writedoc.go

// Package shop is the example app of the boost site.
package shop

//go:generate go run github.com/xgodev/boost/builder/cmd/builder

cmd/api/

gen/

builder/

api/

middleware/…/local/

implementation/…/stock/

internal/

app/

api/rest/

handler/stock/reserver/

pkg/

domain/service/…/local/

datastore/stock/

generatedcmd/api/main.go

// Code generated by builder; DO NOT EDIT.

// Command api runs app api: the doors builder generates in
// github.com/acme/shop/gen/builder/api.
package main

import (
	app "github.com/acme/shop/gen/builder/api"
	"github.com/xgodev/boost"
	fxfact "github.com/xgodev/boost/factory/contrib/go.uber.org/fx/v1"
)

func main() {
	boost.Start()

	fxfact.NewApp(app.Modules()...).Run()
}

generatedgen/builder/api/modules.go

// Code generated by builder; DO NOT EDIT.

package api

import (
	"go.uber.org/fx"

	mw_local_54c3d838 "github.com/acme/shop/gen/builder/middleware/internal_/pkg/domain/service/stock/reserver/local"
	multiserverfx "github.com/xgodev/boost/fx/modules/extra/multiserver"
)

// Modules returns the doors of app api and the multiserver that runs its servers:
//
//	fxfact.NewApp(api.Modules()...).Run()
func Modules() []fx.Option {
	return []fx.Option{
		RestModule(),
		mw_local_54c3d838.DecorateNew(),
		multiserverfx.Module(),
	}
}

generatedgen/builder/api/rest_module.go

// Code generated by builder; DO NOT EDIT.

package api

import (
	"sync"

	"go.uber.org/fx"

	gen_rest_54b9e997 "github.com/acme/shop/gen/internal/app/api/rest"
	gen_reserver_5a8b66f7 "github.com/acme/shop/gen/internal/app/api/rest/handler/stock/reserver"
	src_reserver_5a8b66f7 "github.com/acme/shop/internal/app/api/rest/handler/stock/reserver"
	boostecho "github.com/xgodev/boost/factory/contrib/labstack/echo/v4"
	echofx "github.com/xgodev/boost/fx/modules/factory/contrib/labstack/echo/v4"
)

var restOnce sync.Once

// RestModule serves the REST routes of server rest on echo.
// It returns an empty option after the first call.
func RestModule() fx.Option {
	options := fx.Options()

	restOnce.Do(func() {
		options = fx.Module("api.rest",
			echofx.Module(),
			gen_reserver_5a8b66f7.NewModule(),
			gen_rest_54b9e997.PluginsModule(),
			fx.Invoke(func(srv *boostecho.Server, h0 *src_reserver_5a8b66f7.Handler) {
				srv.Add("POST", "/stock/:sku/reserve", h0.Handle)
			}),
		)
	})

	return options
}

generatedgen/builder/middleware/internal_/pkg/domain/service/stock/reserver/local/new_middleware.go

// Code generated by builder; DO NOT EDIT.

package local

import (
	"go.uber.org/fx"

	context "context"
	src_reserver_399f2048 "github.com/acme/shop/internal/pkg/domain/service/stock/reserver"
	middleware "github.com/xgodev/boost/extra/middleware"
	fmiddleware "github.com/xgodev/boost/factory/local/extra/middleware"
	prometheusmw "github.com/xgodev/boost/factory/local/extra/middleware/plugins/contrib/prometheus/client_golang/v1"
	logmw "github.com/xgodev/boost/factory/local/extra/middleware/plugins/local/wrapper/log"
	contextfx "github.com/xgodev/boost/fx/modules/core/context"
)

// DecorateNew decorates the reserver.Service that local.New provides:
// every consumer in the app receives a newDecorator, which runs the middlewares
// log, prometheus around each method; config can disable each one.
func DecorateNew() fx.Option {
	return fx.Options(
		contextfx.Module(),
		fx.Decorate(decorateNew),
	)
}

// decorateNew builds the wrappers of every method of reserver.Service once.
func decorateNew(ctx context.Context, next src_reserver_399f2048.Service) (src_reserver_399f2048.Service, error) {
	d := &newDecorator{next: next}
	var err error

	d.reserveWrapper, err = fmiddleware.NewErrorWrapperWithOptions(ctx, &fmiddleware.Options{Name: "reserver.service.reserve"},
		logmw.NewError,
		prometheusmw.NewError,
	)
	if err != nil {
		return nil, err
	}

	return d, nil
}

// newDecorator implements reserver.Service: each method runs next's in its wrapper.
type newDecorator struct {
	next           src_reserver_399f2048.Service
	reserveWrapper *middleware.ErrorWrapper
}

// Reserve runs next.Reserve in the middlewares of reserver.service.reserve.
func (d *newDecorator) Reserve(ctx context.Context, a1 string) error {
	return d.reserveWrapper.Exec(ctx, "reserver.service.reserve",
		func(ctx context.Context) error {
			return d.next.Reserve(ctx, a1)
		},
		func(_ context.Context, err error) error {
			return err
		},
	)
}

generatedgen/implementation/internal_/pkg/domain/repository/stock/repository_implementation.go

// Code generated by inject; DO NOT EDIT.

package stock

import (
	"sync"

	"github.com/xgodev/boost/model/errors"
	"github.com/xgodev/boost/wrapper/config"
	"go.uber.org/fx"

	gen_memory_6a1a5ba1 "github.com/acme/shop/gen/internal/pkg/datastore/stock/memory"
	gen_mongodb_1bacb721 "github.com/acme/shop/gen/internal/pkg/datastore/stock/mongodb"
)

// repositoryImplementationKey chooses the implementation of github.com/acme/shop/internal/pkg/domain/repository/stock.Repository.
const repositoryImplementationKey = "internal.pkg.domain.repository.stock.implementation"

func init() {
	config.Add(repositoryImplementationKey, "memory", "implementation of github.com/acme/shop/internal/pkg/domain/repository/stock.Repository: memory, mongodb")
}

// RepositoryImplementation returns the name of the implementation of
// github.com/acme/shop/internal/pkg/domain/repository/stock.Repository that RepositoryImplementationModule wires.
func RepositoryImplementation() string {
	return config.String(repositoryImplementationKey)
}

var repositoryImplementationOnce sync.Once

// RepositoryImplementationModule wires the implementation of github.com/acme/shop/internal/pkg/domain/repository/stock.Repository
// named by internal.pkg.domain.repository.stock.implementation (memory, mongodb; default memory) and only that one.
// An unknown name fails the boot. It returns an empty option after the first
// call, so every consumer can include it.
func RepositoryImplementationModule() fx.Option {
	options := fx.Options()

	repositoryImplementationOnce.Do(func() {
		switch name := RepositoryImplementation(); name {
		case "memory":
			options = gen_memory_6a1a5ba1.NewModule()
		case "mongodb":
			options = gen_mongodb_1bacb721.NewModule()
		default:
			options = fx.Error(errors.NotValidf("%s: unknown implementation %q; valid: %s", repositoryImplementationKey, name, "memory, mongodb"))
		}
	})

	return options
}

generatedgen/internal/app/api/rest/handler/stock/reserver/new_module.go

// Code generated by inject; DO NOT EDIT.

package reserver

import (
	"sync"

	"go.uber.org/fx"

	gen_local_9afcd4bd "github.com/acme/shop/gen/internal/pkg/domain/service/stock/reserver/local"
	src_reserver_5a8b66f7 "github.com/acme/shop/internal/app/api/rest/handler/stock/reserver"
)

var NewOnce sync.Once

// NewModule registers github.com/acme/shop/internal/app/api/rest/handler/stock/reserver.New and the modules it depends on.
// It returns an empty option after the first call, so a constructor shared by
// several modules is registered only once.
func NewModule() fx.Option {
	options := fx.Options()

	NewOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/app/api/rest/handler/stock/reserver.New",
			gen_local_9afcd4bd.NewModule(),
			fx.Provide(src_reserver_5a8b66f7.New),
		)
	})

	return options
}

generatedgen/internal/app/api/rest/plugins_module.go

// Code generated by inject; DO NOT EDIT.

package rest

import (
	"sync"

	"go.uber.org/fx"

	src_rest_54b9e997 "github.com/acme/shop/internal/app/api/rest"
)

var PluginsOnce sync.Once

// PluginsModule registers github.com/acme/shop/internal/app/api/rest.Plugins and the modules it depends on.
// It returns an empty option after the first call, so a constructor shared by
// several modules is registered only once.
func PluginsModule() fx.Option {
	options := fx.Options()

	PluginsOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/app/api/rest.Plugins",
			fx.Provide(src_rest_54b9e997.Plugins),
		)
	})

	return options
}

generatedgen/internal/pkg/domain/service/stock/reserver/local/new_module.go

// Code generated by inject; DO NOT EDIT.

package local

import (
	"sync"

	"go.uber.org/fx"

	impl_stock_f8e11fb6 "github.com/acme/shop/gen/implementation/internal_/pkg/domain/repository/stock"
	src_local_9afcd4bd "github.com/acme/shop/internal/pkg/domain/service/stock/reserver/local"
)

var NewOnce sync.Once

// NewModule registers github.com/acme/shop/internal/pkg/domain/service/stock/reserver/local.New and the modules it depends on.
// It returns an empty option after the first call, so a constructor shared by
// several modules is registered only once.
func NewModule() fx.Option {
	options := fx.Options()

	NewOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/pkg/domain/service/stock/reserver/local.New",
			impl_stock_f8e11fb6.RepositoryImplementationModule(),
			fx.Provide(src_local_9afcd4bd.New),
		)
	})

	return options
}

generatedgen/internal/pkg/datastore/stock/memory/new_module.go

// Code generated by inject; DO NOT EDIT.

package memory

import (
	"sync"

	"go.uber.org/fx"

	src_memory_6a1a5ba1 "github.com/acme/shop/internal/pkg/datastore/stock/memory"
)

var NewOnce sync.Once

// NewModule registers github.com/acme/shop/internal/pkg/datastore/stock/memory.New and the modules it depends on.
// It returns an empty option after the first call, so a constructor shared by
// several modules is registered only once.
func NewModule() fx.Option {
	options := fx.Options()

	NewOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/pkg/datastore/stock/memory.New",
			fx.Provide(src_memory_6a1a5ba1.New),
		)
	})

	return options
}

generatedgen/internal/pkg/datastore/stock/mongodb/new_module.go

// Code generated by inject; DO NOT EDIT.

package mongodb

import (
	"sync"

	"go.uber.org/fx"

	src_mongodb_1bacb721 "github.com/acme/shop/internal/pkg/datastore/stock/mongodb"
)

var NewOnce sync.Once

// NewModule registers github.com/acme/shop/internal/pkg/datastore/stock/mongodb.New and the modules it depends on.
// It returns an empty option after the first call, so a constructor shared by
// several modules is registered only once.
func NewModule() fx.Option {
	options := fx.Options()

	NewOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/pkg/datastore/stock/mongodb.New",
			OptionsModule(),
			fx.Provide(src_mongodb_1bacb721.New),
		)
	})

	return options
}

generatedgen/internal/pkg/datastore/stock/mongodb/options_module.go

// Code generated by inject; DO NOT EDIT.

package mongodb

import (
	"sync"

	"github.com/xgodev/boost/wrapper/config"
	"go.uber.org/fx"

	src_mongodb_1bacb721 "github.com/acme/shop/internal/pkg/datastore/stock/mongodb"
)

// optionsRoot is the config key holding github.com/acme/shop/internal/pkg/datastore/stock/mongodb.Options.
const optionsRoot = "internal.pkg.datastore.stock.mongodb"

func init() {
	// env INTERNAL_PKG_DATASTORE_STOCK_MONGODB_COLLECTION
	config.Add(optionsRoot+".collection", "stock", "collection of the units in stock")
}

var optionsOnce sync.Once

// OptionsModule provides the Options of github.com/acme/shop/internal/pkg/datastore/stock/mongodb,
// filled from the config keys under internal.pkg.datastore.stock.mongodb.
// It returns an empty option after the first call, so every consumer can
// include it.
func OptionsModule() fx.Option {
	options := fx.Options()

	optionsOnce.Do(func() {
		options = fx.Module("github.com/acme/shop/internal/pkg/datastore/stock/mongodb.Options",
			fx.Provide(func() (*src_mongodb_1bacb721.Options, error) {
				return config.NewOptionsWithPath[src_mongodb_1bacb721.Options](optionsRoot)
			}),
		)
	})

	return options
}

generatedgen/module.go

// Code generated by inject; DO NOT EDIT.

package gen

import (
	"go.uber.org/fx"

	impl_stock_f8e11fb6 "github.com/acme/shop/gen/implementation/internal_/pkg/domain/repository/stock"
	gen_rest_54b9e997 "github.com/acme/shop/gen/internal/app/api/rest"
	gen_reserver_5a8b66f7 "github.com/acme/shop/gen/internal/app/api/rest/handler/stock/reserver"
	gen_mongodb_1bacb721 "github.com/acme/shop/gen/internal/pkg/datastore/stock/mongodb"
	gen_local_9afcd4bd "github.com/acme/shop/gen/internal/pkg/domain/service/stock/reserver/local"
)

// Module registers every module generated by inject.
func Module() fx.Option {
	return fx.Options(
		gen_rest_54b9e997.PluginsModule(),
		gen_reserver_5a8b66f7.NewModule(),
		impl_stock_f8e11fb6.RepositoryImplementationModule(),
		gen_mongodb_1bacb721.OptionsModule(),
		gen_local_9afcd4bd.NewModule(),
	)
}

$ go generate ./...
5:35PM INF scanning ~/shop (module github.com/acme/shop)
5:35PM INF generated 6 inject modules and 1 apps in ~/shop/gen, mains in ~/shop/cmd

$ go run ./cmd/api &
5:36PM INF starting Echo Server. https://echo.labstack.com/

# memory is the @Default datastore: 3 t-shirts in stock
$ for i in 1 2 3 4; do curl -s -w ' %{http_code}\n' -X POST localhost:8080/stock/tshirt/reserve; done
 204
 204
 204
{"httpStatusCode":409,"errorCode":"409","message":"tshirt is sold out"}
 409

# same binary on MongoDB, through boost's mongo factory:
# INTERNAL_PKG_DOMAIN_REPOSITORY_STOCK_IMPLEMENTATION=mongodb

github.com/xgodev/boost · bootstrap

One boot. Everything ready after it.

boost.Start() runs first. When it returns, config is loaded and the logger is set, so every factory reads its own keys and logs the same way.

01boost.Start()Reads flags, env vars and config files.
02configEvery key declared once, with a default and a description.
03logzap, zerolog or logrus behind one wrapper.
04factoryOne constructor per component, plugins applied.
05fxGenerated modules wire the dependency graph.
06serveREST, gRPC, MCP or an event function.

One key, three ways to set it

Keys live under boost.factory.<component>.* and reach the app from wherever you deploy.

keyboost.factory.zap.console.level

envBOOST_FACTORY_ZAP_CONSOLE_LEVEL=DEBUG

flag--boost.factory.zap.console.level=DEBUG

// cmd/api/main.go, written by go generate
func main() {
	boost.Start()

	fxfact.NewApp(app.Modules()...).Run()
}

packages

Every piece has one job.

Factories build, wrappers abstract, generators remove the wiring. Use one package or all of them.

factory/contrib/labstack/echo/v4

Factories

One constructor per component. You never instantiate the SDK by hand: the factory reads its config keys, applies the plugins you list and returns the ready client.

srv, _ := echo.NewServer(ctx,
	cors.Register,
	requestid.Register,
	gzip.Register,
	log.Register,
	health.Register,
)
srv.GET("/stock/:sku", Get)
srv.Serve(ctx)

58factories

46upstream libraries

107plugins

…/echo/v4/plugins

Plugins

Behaviour you opt into per factory, applied in the order you list it.

corsrequestidgziploghealthrecoverbodylimitprometheusoteldatadogswaggosemaphore

wrapper/{log,config,cache,publisher}

Wrappers

Swap zap for zerolog by changing one line in main. App code only ever calls the wrapper.

log.FromContext(ctx).
	Infof("reserved %s", sku)

extra/middleware

Middleware

Wraps any call in log, cache, hystrix, datadog, prometheus or fallback. With @Middleware the decorator is generated and the method body stays clean.

log

prometheus

hystrix

Service.Reserve()

@Middleware(log, prometheus, hystrix) · first is outermost

inject

Inject

@Provide, @Inject and @Invoke become one fx module per function and a root Module().

@Defaultmemory.New | mongodb.Newstock.Repository

↓

@Middlewarelocal.New(repo)reserver.Service

↓

@Providereserver.New(svc)*Handler

↓

@RESTHandler.HandlePOST /stock/:sku/reserve

cycles and missing providers fail at go generate, not in production
two providers of the same value are rejected

annotation

Annotation

Reads // @Name(key=value) from doc comments into typed structs. Every generator here is built on it.

var r struct {
	Path string `attr:"path"`
}
ann.Decode(&r)

builder

Builder

An annotation says which door serves the handler. The builder writes the door, the app modules and main.

@RESTecho route

@GRPCgRPC service

@Functionazure functions · cloudevents · kafka · kafka-go · lambda · nats · pubsub

@MCPMCP tool

@Middlewaregenerated decorator

@Defaultimplementation picked by config

bootstrap/function

Functions

One event handler, six transports. Change the adapter in config; the handler stays the same.

func(ctx, in cloudevents.Event)
	(*cloudevents.Event, error)

factory/contrib/modelcontextprotocol/go-sdk/v1/{server,client}

MCP

Your use cases become tools that agents call over MCP, and your service calls other MCP servers. Server and client are factories like the rest: config keys, plugins, and the server runs beside echo and gRPC. Mark a handler with @MCP and the builder registers it as a tool.

server · HTTPserver · STDIOclient · HTTPclient · COMMANDlogotel

srv, _ := server.NewServer(ctx, mcplog.Register, otel.Register)
mcp.AddTool(srv.Instance(), &mcp.Tool{
	Name:        "reserve",
	Description: "holds items for an order",
}, reserve)
srv.Serve(ctx)

builder · inject · annotation

From annotation to binary in two commands.

You write handlers, services and annotations. Everything that repeats between services is generated, checked and rewritten on every run.

Annotate
Mark constructors with @Provide, handlers with a door, services with @Middleware, the default implementation with @Default, options with @Config.
Generate
Inject and builder run in one pass. A broken graph stops here and leaves your output untouched.
go generate ./...
Run
Each app gets its own main, with the servers and plugins it declared.
go run ./cmd/api

generatedoutputrewritten on every run

cmd/api/main.go                // boost.Start(), then app api
gen/
├── builder/
│   ├── api/
│   │   ├── modules.go         // the doors of app api
│   │   └── rest_module.go     // @REST POST /stock/:sku/reserve
│   └── middleware/…/local/
│       └── new_middleware.go  // @Middleware(log, prometheus)
├── implementation/…/stock/
│   └── repository_implementation.go
│                              // @Default: memory | mongodb
├── internal/
│   ├── app/…                  // one module per @Provide,
│   └── pkg/…                  // @Config: same tree as yours
└── module.go                  // every inject module

backward compatibility

Upgrade boost.
Keep your code.

A minor release never asks you to rewrite a service. That is a rule of the project, enforced on every pull request.

Public API is a contract

A component's public API does not break without a major version bump and a written reason. Any observable change ships with a test first.

SDK majors live side by side

Factory paths carry the upstream major. Moving to a new SDK is an import you choose, not a forced migration.

factory/contrib/go.mongodb.org/mongo-driver/v1   // keeps working
factory/contrib/go.mongodb.org/mongo-driver/v2   // new SDK major

A gate that only moves forward

Every PR is compared to develop: format, lint, build and tests can stay the same or get better, never worse.

go.modyour service

 module github.com/acme/shop

 require (
-	github.com/xgodev/boost v1.1.1+	github.com/xgodev/boost v1.6.2 )

$ go build ./... && go test ./...
ok  github.com/acme/shop/...

1 line changed in go.mod0 lines changed in your code

2024-07v1.1.0v1.1.1v1.6.2

factory/contrib

There's a factory for that.

58 factories over the 46 libraries your services already run on. Each one arrives configured, with plugins for traces, metrics and health checks, so your team writes the business logic, not the plumbing.

Also: chi · Fiber · Resty · fasthttp · drpc · HTTP/2 · kafka-go · Goka · Go CDK Pub/Sub · BigCache · FreeCache · BuntDB · memdb · Bigtable · FTP · Azure Blob · Hystrix · zap · zerolog · logrus · fx · Cobra · ants.

All 46 libraries, with the upstream major each factory wraps

Web, RPC & MCP

Echoecho/v4 · v5
chichi/v5
Fiberfiber/v2
gRPC server · clientgrpc/v1
MCP server · clientgo-sdk/v1
HTTP/2 serverx/net/v0
GraphQLgraphql-go/v0
Restyresty/v2
fasthttp clientfasthttp/v1
drpc server · clientdrpc/v1

Messaging

Kafka (Confluent)confluent-kafka-go/v2
Kafka (segmentio)kafka-go/v0
NATSnats.go/v1
Google Pub/Subpubsub/v1 · v2
Go CDK Pub/Subgocloud.dev/v0
CloudEventssdk-go/v2
Gokagoka/v1
SQS · SNS · Kinesisaws-sdk-go-v2

Data

MongoDBmongo-driver/v1 · v2
PostgreSQLpgx/v5
Oraclegodror/v0
Cassandragocql/v1 · v2
Elasticsearchgo-elasticsearch/v8 · v9
BigQuery · Bigtable · Firestore · API clientcloud.google.com
FTPftp/v0
Azure Blob Storageazure-sdk-for-go/v1

Cache

Redisgo-redis/v9
BigCachebigcache/v3
FreeCachefreecache/v1
BuntDBbuntdb/v1
memdbmemdb/v1

Observability

OpenTelemetryotel/v1
Datadogdd-trace-go/v1
Prometheusclient_golang/v1
Hystrixhystrix-go/v0

Logging & platform

zap · zerolog · logruswrapper/log
fxfx/v1
Cobracobra/v1
Kubernetesclient-go/v0
Vaultvaultgo/v0
ants worker poolants/v2

Why a factory, not just the SDK

Any SDK connects in five lines. Running it in a company takes the rest: config per environment, auth, checks, logs, metrics, traces. That part is the same in every service, so boost writes it once.

boost.factory.<name>.*

Configured, not coded

Every option is a config key with a default, read from file or environment: boost.factory.mongo.uri is BOOST_FACTORY_MONGO_URI. One binary for every environment.

what you skip

The plumbing comes built

Defaults, auth, connect and ping, structured logs through wrapper/log. What a platform team rewrites for every SDK in every service is already there.

plugins/

78 plugins to plug in

OpenTelemetry, Prometheus, Datadog, health checks, retry, request id, CORS, gzip. Pass the plugin to the factory; switch it off with a key.

by handMongoDB, in every service

Read URI, user and password from the environment, with defaults
Build the client options and the authentication
Connect and ping before taking traffic
Trace every command with OpenTelemetry
Count commands and errors in Prometheus
Register a health check
Log commands when you need to debug
Then again for Kafka, Redis, gRPC, the HTTP client…

with boostfactory/contrib/go.mongodb.org/mongo-driver/v2

conn, err := mongo.NewConn(ctx,
	mongootel.Register,   // traces
	mongoprom.Register,   // metrics
	mongohealth.Register, // health check
)

$ export BOOST_FACTORY_MONGO_URI=mongodb://db:27017/shop
$ export BOOST_FACTORY_MONGO_AUTH_USERNAME=shop
$ export BOOST_FACTORY_MONGO_PLUGINS_PROMETHEUS_ENABLED=false

Same shape for every factory: New…(ctx, plugins...) and keys under boost.factory.<name>.

claude-plugin@xgodev

Coding agents that follow the rules.

The plugin teaches Claude Code boost's Iron Laws and the project layout, and runs the comparative quality gate before every push.

>/plugin marketplace add xgodev/claude-plugin

>/plugin install claude-plugin@xgodev

boost.Start() firstConfig and log exist only after it.
Log only through wrapper/loglog.FromContext(ctx), never a third-party logger in app code.
Config only through wrapper/configNo os.Getenv; keys under boost.factory.<x>.*.
One factory per componentNever instantiate the upstream SDK directly.
Backward compatiblePublic API breaks only with a major bump and a reason.

go.mod

Start with one line.