forge

README

Translations: English | 简体中文

Forge

Forge is an independent, pre-release fork of go-kratos/kratos. It explores deliberate breaking changes, faster standard-library-based internals, and a smaller long-term dependency surface. It is not affiliated with or endorsed by the go-kratos maintainers.

The project currently tracks v0 development and does not provide a stable API or compatibility guarantee. Read COMPATIBILITY.md before migrating and UPSTREAM.md for the source baseline and synchronization policy.

Features

• API-first development with Protobuf and generated HTTP/gRPC code.
• Unified transport layer for HTTP and gRPC.
• Protocol-neutral asynchronous message contract with optional broker adapters.
• Standard-library http.ServeMux routing with method patterns, path values, and Google AIP template support.
• Composable middleware for recovery, logging, validation, tracing, metrics, auth, and more.
• Pluggable registry, configuration, and encoding components.
• Standard-library log/slog based logging with OpenTelemetry extensions in contrib packages.
• Consistent metadata, errors, validation, OpenAPI, and code-generation workflows.
• A contrib ecosystem for optional integrations such as registries, config stores, middleware, encodings, and observability.

Installation

Requirements

• Go 1.27 RC (currently 1.27rc3; go.mod requires it, so Go 1.26 cannot build Forge)
• protoc
• protoc-gen-go
• Buf or an equivalent protoc workflow

Add Forge

go get github.com/sylphylabs/forge@main

Forge intentionally does not ship a project-scaffolding CLI. Project creation, dependency upgrades, and execution use the standard Go toolchain.

Build the atomic Forge Protobuf generators from this checkout until the corresponding Buf plugins are published. Install ./protoc-gen-go-message only when a service consumes asynchronous messages:

cd cmd
GOWORK=off go install ./protoc-gen-go-errors ./protoc-gen-go-http ./protoc-gen-go-message ./protoc-gen-go-middleware

Generate and Run

Use the repository's Buf or protoc configuration to generate code, then run the service directly:

buf generate
go generate ./...
go run ./cmd/server -conf ./configs

Usage Example

package main

import (
	"github.com/sylphylabs/forge"
	"github.com/sylphylabs/forge/transport/grpc"
	"github.com/sylphylabs/forge/transport/http"
)

func main() {
	httpSrv := http.NewServer(http.WithAddress(":8000"))
	grpcSrv := grpc.NewServer(grpc.WithAddress(":9000"))

	app := forge.New(
		forge.WithName("helloworld"),
		forge.WithVersion("v1.0.0"),
		forge.WithServer(httpSrv, grpcSrv),
	)
	if err := app.Run(); err != nil {
		panic(err)
	}
}

Upstream Baseline

Forge started from Kratos v3. Existing Kratos users should treat the module-path change and all future Forge releases as an explicit migration, not as an in-place Forge upgrade.

Further Reading

• Usage guides — errors, observability, middleware, application
• Guidance for coding agents
• Compatibility contract
• Migration from Kratos v3
• Documentation index
• Upstream baseline and synchronization policy
• Performance modernization
• Upstream adoption ledger
• Contribution guide
• Upstream Kratos documentation (reference only; behavior may differ)

Development

make test
make lint

See DEVELOPMENT.md for multi-module checks and Go 1.27 RC validation.

Security

Use a private GitHub security advisory in the Forge repository. Do not report Forge-specific vulnerabilities to the upstream Kratos project.

Acknowledgments

Forge preserves the complete Kratos Git history and original MIT copyright notice. The upstream Kratos project and its contributors created the foundation of this codebase.

The following projects influenced the original Forge design:

• go-kit/kit
• go-micro
• google/go-cloud
• go-zero
• beego

License

Forge is open-sourced software licensed under the MIT license.

Documentation

Overview

Package forge manages the lifecycle of a set of transport servers as one application.

New builds an App from options: identity (WithID, WithName, WithVersion, WithMetadata), the servers to run (WithServer), an optional service registry (WithRegistrar), and lifecycle hooks (WithBeforeStart, WithAfterStart, WithBeforeStop, WithAfterStop). App.Run starts every server, registers the instance, and blocks until a stop signal arrives or App.Stop is called; on the way out it deregisters, drains the servers within WithStopTimeout, and runs the AfterStop hooks within WithAfterStopTimeout. Run joins every error it observed rather than reporting only the first.

A Suite bundles options that belong together — an integration and its hooks — so an application adopts them with a single WithSuite call. Handlers and hooks recover the application's identity from the context via FromContext.

The package dictates no project layout and ships no scaffolding CLI. See docs/agent/application.md for the usage contract and docs/design/application-lifecycle.md for the lifecycle rationale.

Example (FromContext)

Example_fromContext mirrors the guide's identity snippet: inside a handler or hook, recover application identity from the context.

package main

import (
	"context"
	"fmt"

	"github.com/sylphylabs/forge"
)

func main() {
	app := forge.New(forge.WithName("helloworld"))
	ctx := forge.NewContext(context.Background(), app)

	if info, ok := forge.FromContext(ctx); ok {
		fmt.Println(info.Name())
		_ = info.Endpoints()
	}
}

Output:
helloworld

Example (Lifecycle)

Example_lifecycle mirrors "Lifecycle": hooks and the three independent timeouts are all construction options.

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/sylphylabs/forge"
	"github.com/sylphylabs/forge/registry"

	forgehttp "github.com/sylphylabs/forge/transport/http"
)

// noopRegistrar stands in for a registry integration (contrib/registry/...).
type noopRegistrar struct{}

func (noopRegistrar) Register(context.Context, *registry.ServiceInstance) error   { return nil }
func (noopRegistrar) Deregister(context.Context, *registry.ServiceInstance) error { return nil }

// pool stands in for the guide's application-owned resource whose lifecycle
// the hooks manage.
type pool struct{}

func (pool) Ping(context.Context) error { return nil }
func (pool) Close() error               { return nil }

func main() {
	httpSrv := forgehttp.NewServer(forgehttp.WithAddress("127.0.0.1:0"))
	var reg noopRegistrar
	var dbPool pool

	app := forge.New(
		forge.WithName("helloworld"),
		forge.WithServer(httpSrv),
		forge.WithRegistrar(reg),
		forge.WithRegistrarTimeout(5*time.Second),
		forge.WithStopTimeout(15*time.Second),
		forge.WithAfterStopTimeout(5*time.Second),
		forge.WithBeforeStart(func(ctx context.Context) error { return dbPool.Ping(ctx) }),
		forge.WithAfterStop(func(_ context.Context) error { return dbPool.Close() }),
	)

	_ = app
	fmt.Println("constructed")
}

Output:
constructed

Example (MinimalService)

Example_minimalService mirrors "Minimal service". It has no Output comment, so `go test` compiles it without running it: the guide's version blocks in Run until a stop signal arrives.

package main

import (
	"github.com/sylphylabs/forge"

	forgegrpc "github.com/sylphylabs/forge/transport/grpc"

	forgehttp "github.com/sylphylabs/forge/transport/http"
)

func main() {
	httpSrv := forgehttp.NewServer(forgehttp.WithAddress(":8000"))
	grpcSrv := forgegrpc.NewServer(forgegrpc.WithAddress(":9000"))

	app := forge.New(
		forge.WithName("helloworld"),
		forge.WithVersion("v1.0.0"),
		forge.WithServer(httpSrv, grpcSrv),
	)
	if err := app.Run(); err != nil {
		panic(err)
	}
}

Example (Suite)

package main

import (
	"context"
	"fmt"

	"github.com/sylphylabs/forge"
)

// pool stands in for the guide's application-owned resource whose lifecycle
// the hooks manage.
type pool struct{}

func (pool) Ping(context.Context) error { return nil }
func (pool) Close() error               { return nil }

// closingSuite mirrors the guide's tracing suite: an integration bundles its
// options — here an AfterStop hook that shuts the integration down — so an
// application adopts them in one WithSuite call. The guide's version closes
// an OpenTelemetry TracerProvider; the shape is the same for any resource.
type closingSuite struct{ closer interface{ Close() error } }

func (s closingSuite) Options() []forge.Option {
	return []forge.Option{
		forge.WithAfterStop(func(_ context.Context) error {
			return s.closer.Close()
		}),
	}
}

func main() {
	app := forge.New(
		forge.WithName("helloworld"),
		forge.WithSuite(closingSuite{closer: pool{}}),
	)

	_ = app
	fmt.Println("constructed")
}

Output:
constructed

Index

• func AppProbe(info AppInfo) diagnosis.ProbeFunc
• func NewContext(ctx context.Context, s AppInfo) context.Context
• type App
  • func New(opts ...Option) *App
  • func (a *App) Endpoints() []string
  • func (a *App) Healthz() bool
  • func (a *App) ID() string
  • func (a *App) Metadata() map[string]string
  • func (a *App) Name() string
  • func (a *App) Run() error
  • func (a *App) Stop() error
  • func (a *App) Version() string
• type AppInfo
  • func FromContext(ctx context.Context) (s AppInfo, ok bool)
• type AppSnapshot
• type Option
  • func WithAfterStart(fn func(context.Context) error) Option
  • func WithAfterStop(fn func(context.Context) error) Option
  • func WithAfterStopTimeout(t time.Duration) Option
  • func WithBeforeStart(fn func(context.Context) error) Option
  • func WithBeforeStop(fn func(context.Context) error) Option
  • func WithContext(ctx context.Context) Option
  • func WithEndpoint(endpoints ...*url.URL) Option
  • func WithID(id string) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithMetadata(md map[string]string) Option
  • func WithName(name string) Option
  • func WithRegistrar(r registry.Registrar) Option
  • func WithRegistrarTimeout(t time.Duration) Option
  • func WithServer(srv ...transport.Server) Option
  • func WithSignal(sigs ...os.Signal) Option
  • func WithStopTimeout(t time.Duration) Option
  • func WithSuite(s Suite) Option
  • func WithVersion(version string) Option
• type Suite

Examples

• Package (FromContext)
• Package (Lifecycle)
• Package (MinimalService)
• Package (Suite)

Functions

func AppProbe

func AppProbe(info AppInfo) diagnosis.ProbeFunc

AppProbe returns a probe that reports info's identity as an AppSnapshot.

The probe reads info when it runs, not when it is built, so a snapshot taken after App.Run has started the servers includes the endpoints they bound. Register it under a name of your choosing — "app" by convention:

reg := diagnosis.NewRegistry()
app := forge.New(forge.WithName("checkout"), ...)
reg.Register("app", forge.AppProbe(app))

AppProbe panics if info is nil; a probe wired to nothing is a construction bug, surfaced at the offending line rather than as an error in every dump.

func NewContext

func NewContext(ctx context.Context, s AppInfo) context.Context

NewContext returns a new Context that carries value.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is an application components lifecycle manager.

func New

func New(opts ...Option) *App

New create an application lifecycle manager.

func (*App) Endpoints

func (a *App) Endpoints() []string

Endpoints returns endpoints.

func (*App) Healthz

func (a *App) Healthz() bool

Healthz reports whether every server that exposes readiness through transport.Healthzer can accept new work. Servers without the capability make no claim and do not affect the result. App itself satisfies transport.Healthzer, so it can feed a health endpoint directly.

func (*App) ID

func (a *App) ID() string

ID returns app instance id.

func (*App) Metadata

func (a *App) Metadata() map[string]string

Metadata returns service metadata.

func (*App) Name

func (a *App) Name() string

Name returns service name.

func (*App) Run

func (a *App) Run() error

Run starts the application and blocks until it stops. It builds the registry instance, runs the BeforeStart hooks, starts every configured server, registers the instance with the registrar when one is configured, and then runs the AfterStart hooks. It returns when the application stops — because App.Stop was called, an exit signal from the WithSignal option arrived, or a server or hook failed. On the way out it runs the BeforeStop hooks, deregisters the instance, shuts the servers down within WithStopTimeout, and finally runs the AfterStop hooks within WithAfterStopTimeout. The returned error joins every failure observed along the way.

func (*App) Stop

func (a *App) Stop() error

Stop gracefully stops the application.

func (*App) Version

func (a *App) Version() string

Version returns app version.

type AppInfo

type AppInfo interface {
	ID() string
	Name() string
	Version() string
	Metadata() map[string]string
	Endpoints() []string
}

AppInfo is application context value.

func FromContext

func FromContext(ctx context.Context) (s AppInfo, ok bool)

FromContext returns the Transport value stored in ctx, if any.

type AppSnapshot

type AppSnapshot struct {
	// ID is the application instance id.
	ID string `json:"id"`
	// Name is the service name.
	Name string `json:"name"`
	// Version is the application version.
	Version string `json:"version"`
	// Metadata is the service metadata, if any.
	Metadata map[string]string `json:"metadata,omitempty"`
	// Endpoints lists the endpoints the application currently advertises.
	// Empty before the application has started its servers.
	Endpoints []string `json:"endpoints,omitempty"`
}

AppSnapshot is the value reported by an AppProbe: the application's identity as it stands at the moment the probe runs.

type Option

type Option func(o *options)

Option is an application option.

Options come in two shapes. Scalar options (WithID, WithName, WithVersion, WithContext, WithLogger, WithRegistrar, and the timeouts) set a single field: when the same option appears more than once, the one applied last wins. Collection options (WithServer, WithEndpoint, WithSignal, WithMetadata, and the lifecycle hooks) accumulate: every application of the option adds to what earlier applications contributed, so independent option lists — for example two Suite values — compose without overwriting each other.

func WithAfterStart

func WithAfterStart(fn func(context.Context) error) Option

WithAfterStart registers a func to run after the app starts.

func WithAfterStop

func WithAfterStop(fn func(context.Context) error) Option

WithAfterStop registers a func to run after the app stops.

func WithAfterStopTimeout

func WithAfterStopTimeout(t time.Duration) Option

WithAfterStopTimeout sets the total time allowed for all AfterStop hooks. A non-positive duration disables the deadline.

func WithBeforeStart

func WithBeforeStart(fn func(context.Context) error) Option

WithBeforeStart registers a func to run before the app starts.

func WithBeforeStop

func WithBeforeStop(fn func(context.Context) error) Option

WithBeforeStop registers a func to run before the app stops.

func WithContext

func WithContext(ctx context.Context) Option

WithContext sets the service context.

func WithEndpoint

func WithEndpoint(endpoints ...*url.URL) Option

WithEndpoint appends endpoints to the service endpoints.

func WithID

func WithID(id string) Option

WithID sets the service id.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the service logger.

func WithMetadata

func WithMetadata(md map[string]string) Option

WithMetadata merges md into the service metadata. Keys from later applications win over earlier ones.

func WithName

func WithName(name string) Option

WithName sets the service name.

func WithRegistrar

func WithRegistrar(r registry.Registrar) Option

WithRegistrar sets the service registrar.

func WithRegistrarTimeout

func WithRegistrarTimeout(t time.Duration) Option

WithRegistrarTimeout sets the registrar timeout.

func WithServer

func WithServer(srv ...transport.Server) Option

WithServer appends transport servers to the application.

func WithSignal

func WithSignal(sigs ...os.Signal) Option

WithSignal appends exit signals to the set the application stops on. When no WithSignal option is given, the application stops on SIGTERM, SIGQUIT, and SIGINT.

func WithStopTimeout

func WithStopTimeout(t time.Duration) Option

WithStopTimeout sets the app stop timeout.

func WithSuite

func WithSuite(s Suite) Option

WithSuite expands a Suite into a single Option. The suite's options apply in place, exactly where the returned Option appears in the caller's option list, in the order Options returned them. Each option keeps its usual semantics whether it came from a suite or was written directly: scalar options such as WithName, WithVersion, WithID, WithContext, and WithLogger set a single field and the one applied last wins, while collection options such as WithServer, WithEndpoint, WithMetadata, and the lifecycle hooks accumulate, so independent suites contributing to the same collection all take effect.

WithSuite calls Options once, immediately, so a suite is read at the point it is wired, not when the application is constructed. It panics right away if s is nil or if Options returns a nil element; a broken wiring fails at the offending line during construction rather than surfacing later.

func WithVersion

func WithVersion(version string) Option

WithVersion sets the service version.

type Suite

type Suite interface {
	// Options returns the options this suite contributes, in the order they
	// should apply. Every element must be non-nil.
	Options() []Option
}

Suite bundles application options that belong together. An integration — a service registry plus its lifecycle hooks, a logging setup plus the metadata it reads — implements Suite once, and an application adopts the whole bundle with a single WithSuite call instead of repeating each option.

A Suite carries no state of its own inside the application: everything it contributes goes through the returned options, so two applications may hold differently configured instances of the same Suite type without sharing anything. Suites compose: the slice returned by Options may itself contain options produced by WithSuite, and independent suites written without knowledge of each other stack in a single option list.