grpc

Forge gRPC: a gRPC server for Go apps built on Forge

Forge gRPC is the gRPC extension for Forge, the Go backend framework. It runs a grpc-go server next to your HTTP server and ties it to the app's lifecycle, with the standard gRPC health checking protocol, server reflection for tools like grpcurl, TLS and mutual TLS, keepalive and message size limits, request logging, OpenTelemetry spans and metrics, and graceful shutdown. You hand it your generated services with WithService or WithServiceRegistrar, and it registers them before the server starts.

Documentation · Quick start · Registering services · Features · Health checks · TLS · Tracing and metrics · Clients · Configuration · FAQ

Quick start

You need Go 1.26 or later. Add Forge and the extension to your module:

go get github.com/xraph/forge@latest
go get github.com/xraph/forge/extensions/grpc@latest

Save this as main.go. It starts a gRPC server on port 50051 with health checks and reflection, and adds a health checker for one dependency:

package main

import (
	"context"
	"log"

	"github.com/xraph/forge"
	grpcext "github.com/xraph/forge/extensions/grpc"
)

type dbCheck struct{}

func (dbCheck) Check(ctx context.Context) error {
	return nil // ping your database here
}

func main() {
	app := forge.NewApp(forge.AppConfig{
		Name:        "billing",
		HTTPAddress: ":8080",
		Extensions: []forge.Extension{
			grpcext.NewExtension(
				grpcext.WithAddress(":50051"),
				grpcext.WithReflection(true),
				grpcext.WithHealthCheck(true),
				grpcext.WithServiceRegistrar(func(app forge.App, s grpcext.GRPC) error {
					s.RegisterHealthChecker("billing.db", dbCheck{})

					return nil
				}),
			),
		},
	})

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

The package is named grpc, so the example imports it as grpcext to keep it apart from google.golang.org/grpc. Run it with go mod tidy && go run ., then talk to it with grpcurl:

grpcurl -plaintext localhost:50051 list
# grpc.health.v1.Health
# grpc.reflection.v1.ServerReflection
# grpc.reflection.v1alpha.ServerReflection

grpcurl -plaintext -d '{"service":"billing.db"}' localhost:50051 grpc.health.v1.Health/Check
# { "status": "SERVING" }

When you stop the app, the server stops taking new calls and waits for the ones in flight. If the app's shutdown timeout runs out first, it stops hard and cancels what's left.

Registering your own services

Pass your services to the extension when you create it. WithService takes the generated descriptor and your implementation:

grpcext.NewExtension(
	grpcext.WithAddress(":50051"),
	grpcext.WithService(&pb.Greeter_ServiceDesc, &greeter{}),
)

If the implementation needs something from the container, or you want an interceptor or a health checker next to it, use WithServiceRegistrar. Your function gets the app and the server, and the extension calls it once, while it builds the server inside app.Start:

grpcext.WithServiceRegistrar(func(app forge.App, s grpcext.GRPC) error {
	db, err := forge.Inject[*sql.DB](app.Container())
	if err != nil {
		return err
	}

	s.AddUnaryInterceptor(authInterceptor)
	s.RegisterHealthChecker("greeter", greeterCheck{db: db})

	return s.RegisterService(&pb.Greeter_ServiceDesc, &greeter{db: db})
}),

A registrar that returns an error fails app.Start with that error wrapped. So does a service the server can't take, which comes back as ErrInvalidService: an implementation that doesn't satisfy the descriptor's server interface, or a service name that's already registered. The health and reflection services count when they're on. grpc-go would end the process for either one at Start, so the extension checks them when you register.

The registrar runs inside the constructor of the gRPC service, so it can resolve anything you provided on the container before app.Start and anything an earlier extension registered. Resolving grpcext.GRPC or *grpcext.GRPCService from inside it is a circular dependency. WithConfig replaces the whole config, registrars included, so put WithService and WithServiceRegistrar after it.

From another extension or a hook

The server doesn't listen until the very end of app.Start. The extension starts it from a PhaseAfterStart hook with priority math.MinInt, so it runs after every other hook, and until then you can register from anywhere that reaches the container. An extension that lists grpc in its dependencies resolves the server in its Register or its Start:

func (e *Extension) Register(app forge.App) error {
	if err := e.BaseExtension.Register(app); err != nil {
		return err
	}

	srv, err := forge.Inject[grpcext.GRPC](app.Container())
	if err != nil {
		return err
	}

	return srv.RegisterService(&pb.Ledger_ServiceDesc, e.ledger)
}

A PhaseAfterRegister hook works too, and so does a PhaseAfterStart hook at any higher priority. Once app.Start returns, the server is serving and RegisterService returns ErrRegisterAfterStart. The flip side is that nothing can dial the server from inside app.Start: an extension's Start or an after-start hook runs before the port is open. If the port is taken or the TLS files don't load, app.Start fails with the error from that last hook.

grpc-go can't add a service to a server that's already serving, which is why all of this has to happen first. Here's what each call does on either side of the server's start:

Don't call a generated pb.RegisterXxxServer on GetServer(). It's nil until Start, and on a serving server grpc-go stops the process with grpc: Server.RegisterService after Server.Serve. Use RegisterService(&pb.Xxx_ServiceDesc, impl) instead.

If you'd like to own the server's start and stop yourself, grpcext.NewGRPCServer(cfg, app.Logger(), app.Metrics()) gives you one outside the extension, and you call Start and GracefulStop on it. Create it after forge.NewApp, because it reads the OpenTelemetry globals NewApp installs when it starts.

The grpc-advanced example registers a greeter, an auth interceptor and a health checker through WithServiceRegistrar.

Features

Health checks

With enable_health_check on (the default), the server answers the gRPC health checking protocol. A checker is anything with Check(ctx context.Context) error, registered under a service name with RegisterHealthChecker. You can add one at any time, since checkers are looked up on each call.

Watch sends the current status, runs the checker again every five seconds and sends a new message whenever the answer changes. When the server stops it sends NOT_SERVING and closes the stream, so a watching probe never holds up shutdown. List returns the empty name and every service that has a checker, each with its current status.

The extension's own Health method only reports whether the extension has started. It doesn't call your checkers.

TLS and mTLS

grpcext.NewExtension(
	grpcext.WithTLS("server.crt", "server.key", ""),
)

// Mutual TLS: require and verify client certificates against ca.crt.
grpcext.NewExtension(
	grpcext.WithTLS("server.crt", "server.key", "ca.crt"),
	grpcext.WithClientAuth(true),
)

Config validation fails at startup if TLS is on without a certificate and key, or client auth is on without a CA file. If the files are set but can't be loaded (a wrong path, a bad PEM, a CA file with no certificates in it), the server doesn't start and app.Start returns failed to load TLS credentials with the cause. It never falls back to plaintext.

Logging, tracing and metrics

enable_logging, enable_metrics and enable_tracing are all on by default. Logging writes a debug line when a call starts and ends, and an error line with the method, duration and error when it fails.

Spans

With enable_tracing on, every served call gets a server span named after the method (billing.Invoices/Get), made by otelgrpc. It carries the OpenTelemetry semconv v1.43 attributes:

A traceparent in the incoming metadata makes the span a child of the caller's trace. Server-side error codes such as INTERNAL mark the span as an error. Client-error codes such as NOT_FOUND don't. Health and reflection calls get no span, the same way Forge's HTTP tracing skips /_/.

The call's context also carries trace_id and span_id, as it does for HTTP requests, so a logger built from it stamps both on every line. The server uses the OpenTelemetry globals that forge.New installs, and reads them when it starts. Your app's tracing config (endpoint, sampling) is what sends the spans anywhere, see observability.

If you already added your own otelgrpc server handler, remove it. You'd get two spans per call.

Leave OTEL_SEMCONV_STABILITY_OPT_IN unset. If it holds rpc/old or rpc/dup, otelgrpc puts the older attributes on the span (rpc.service, a short rpc.method and a numeric status code), while rpc_server_call_duration_seconds keeps the v1.43 labels. Spans and metrics stop lining up.

Metrics

Every served call lands in one histogram, rpc.server.call.duration, recorded through the app's Forge metrics registry. Prometheus exports it as rpc_server_call_duration_seconds:

The buckets run from 5ms to 10s. Health and reflection calls aren't recorded. A stream records the whole call, from open to close. A handler that returns a bare context.Canceled or context.DeadlineExceeded is recorded as CANCELLED or DEADLINE_EXCEEDED, which is what the client sees. With enable_metrics off nothing is recorded.

Two cases differ from the span. A call to a service or method the server doesn't have gets a span with UNIMPLEMENTED but no observation, because grpc-go rejects it before any interceptor runs. And a unary call whose handler succeeds but whose response fails to send is recorded as OK, while the wire and the span say otherwise.

The labels are the same keys and values that sit on the span, so a slow bucket and its trace line up. Two queries to start with:

# Calls per second, by method
sum by (rpc_method) (rate(rpc_server_call_duration_seconds_count[5m]))

# Failures per second, by method
sum by (rpc_method) (rate(rpc_server_call_duration_seconds_count{rpc_response_status_code!="OK"}[5m]))

The older forge_grpc_* series are gone. Nothing is emitted under the old names, so dashboards and alerts that use them go blank until you move them:

Two label changes bite if you relabeled. The status code is the canonical name (NOT_FOUND), not the Go spelling (NotFound) the old code label held, and rpc_method has no leading slash, where the old method label had one.

GetStats() is unchanged. It returns the start time, RPC counts and active streams, and GetServices() lists registered services and their methods, with flags for client and server streaming.

Tracing outbound calls

ClientDialOptions() returns dial options that put a client span on every outbound call and send the trace context to the next service:

conn, err := grpc.NewClient("billing:50051",
	append(forgegrpc.ClientDialOptions(), grpc.WithTransportCredentials(creds))...)

Import the extension as forgegrpc "github.com/xraph/forge/extensions/grpc" here, to keep it apart from grpc-go. If you use conduit, Services.GRPC adds this handler for you, so don't pass ClientDialOptions() into it. gRPC appends stats handlers rather than replacing them, and a second one gives every call a second client span. Both read the OpenTelemetry globals when you call them, so call them after forge.New.

Configuration

The extension reads extensions.grpc from your config, falling back to grpc. Options you pass in code override the file.

extensions:
  grpc:
    address: ":50051"
    max_recv_msg_size: 4194304
    max_send_msg_size: 4194304
    max_concurrent_streams: 0     # 0 means no limit
    connection_timeout: 120s
    keepalive:
      time: 2h
      timeout: 20s
      enforcement_policy: true
      min_time: 5m
      permit_without_stream: false
    enable_tls: false
    tls_cert_file: ""
    tls_key_file: ""
    tls_ca_file: ""
    client_auth: false
    enable_health_check: true
    enable_reflection: true
    enable_metrics: true
    enable_tracing: true
    enable_logging: true

keepalive.time also sets the server's maximum idle time for a connection, and twice that value is the maximum connection age, with keepalive.timeout as the grace period. With the defaults, an idle connection closes after two hours and any connection is recycled after four.

WithConfig replaces the whole config and WithRequireConfig(true) makes a missing config section an error at startup. WithService and WithServiceRegistrar have no key: a registrar is code, and the file can't set or remove one. The container holds *grpcext.GRPCService (also under the name grpc) and the grpcext.GRPC interface, backed by the same server.

Documentation

FAQ

How do I add a gRPC server to a Go app built on Forge?

Add grpcext.NewExtension() to your app's Extensions and it listens on :50051 with health checks and reflection on. Add your services with grpcext.WithService(&pb.Xxx_ServiceDesc, impl), as registering your own services shows.

Does Forge gRPC support the gRPC health checking protocol?

Yes. It registers grpc.health.v1.Health, so Kubernetes gRPC probes and grpc_health_probe work against it. Register a checker per service name to report NOT_SERVING when a dependency is down.

How do I enable gRPC server reflection for grpcurl?

It's on by default. Turn it off with WithReflection(false) or enable_reflection: false.

Can I use mutual TLS?

Yes. Pass the CA file as the third argument to WithTLS and add WithClientAuth(true), and the server requires a client certificate signed by that CA.

Contributing

The extension is its own Go module inside the Forge repository. Test it from its directory:

cd extensions/grpc
GOWORK=off go test -race ./...
GOWORK=off golangci-lint run ./...

AGENTS.md has the full build, lint and release rules for the repository, and CONTRIBUTING.md has the contribution guidelines.

License

Forge gRPC is part of Forge and is available under the Apache License 2.0.