Skip to content
Gortexa

Components

Every framework package is importable directly after go get. Fetch the module:

Terminal window
go get github.com/yshengliao/gortexa@v0.27.0

This section lists the public components by category — each with its purpose, import path and a minimal usage snippet. All snippets are compile-verified against v0.27.0.

  • Core: kernel, config, interceptor, auth, apperr — assembly, config, the interceptor chain, JWT and the error model.
  • HTTP & MCP: httpcompat, mcp — the grpc-gateway HTTP/JSON layer and the MCP bridge.
  • Batteries: mq, cache, storage, client — messaging, caching, the database pool and outbound clients.
  • Observability & health: health, observability — three-state health and OTLP logs/traces/metrics.

For a bare minimal app (no gateway or MCP), see Use as a module.

Note: a project created by gortexa create already contains the framework source, and must never also go get the framework. This section is for using the framework as a plain library, without the scaffold.

Full wiring

Section titled “Full wiring”

cmd/server/main.go in the framework repo is the canonical example of assembling every component into a service, in this order:

  1. config.MustBuild(...) — fail-loud config load.
  2. observability.SetupLogs / SetupTracing / SetupMetrics — each returns a ShutdownFunc; observability.NewGovernanceMetrics().
  3. auth.NewVerifier(...).
  4. interceptor.NewSet(interceptor.Config{...}).
  5. kernel.New(WithConfig, WithLogger, WithInterceptors, WithStatsHandler(observability.ServerStatsHandler()), WithHTTPWrap(...), WithShutdownHook×3).
  6. register services on app.GRPCServer(); app.Health().Register(...).
  7. conn := app.Loopback() → httpcompat.NewServeMux → app.SetGateway(...).
  8. mcp.ServiceDescriptors(...) → mcp.NewBridge(conn, descs, apperr.Default, cfg.Observ) → app.SetMCPHandler(bridge.Handler()).
  9. app.Run(ctx).

app.Loopback() must be called after kernel.New and before Run; both the gateway and the MCP bridge dial it, so they share the one interceptor chain.

testutil — test helpers (test-only)

Section titled “testutil — test helpers (test-only)”

In-process test helpers: a bufconn gRPC server wired with the full interceptor chain, golden-file comparison, and goroutine-leak assertions.

import "github.com/yshengliao/gortexa/testutil"


conn := testutil.NewTestServer(t, func(s *grpc.Server) {
  pb.RegisterThingServiceServer(s, myService)
}, testutil.WithAuthSecret(secret))
// testutil.Golden(t, name, got) compares against testdata/<name>.golden
// set GORTEXA_UPDATE_GOLDEN to rewrite golden files (there is no -update flag)