# Components

Source: https://gortexa.sheng.page/en/components/

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

```bash
go get github.com/yshengliao/gortexa@v0.28.3
```

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.28.3.

- [Core](https://gortexa.sheng.page/en/components/core/): `kernel`, `config`, `interceptor`, `auth`, `apperr` — assembly, config, the interceptor chain, JWT and the error model.
- [HTTP & MCP](https://gortexa.sheng.page/en/components/http-mcp/): `httpcompat`, `mcp` — the grpc-gateway HTTP/JSON layer and the MCP bridge.
- [Batteries](https://gortexa.sheng.page/en/components/batteries/): `mq`, `cache`, `storage`, `client` — messaging, caching, the database pool and outbound clients.
- [Observability & health](https://gortexa.sheng.page/en/components/observability/): `health`, `observability` — three-state health and OTLP logs/traces/metrics.

For a bare minimal app (no gateway or MCP), see [Use as a module](https://gortexa.sheng.page/en/quickstart/#use-as-a-module-no-scaffold).

Note: this section is for using the framework as a plain library, without the scaffold. A project created by `gortexa create` already carries a copy of the framework source; since v0.28.0 such a project can also `go get` the framework without a descriptor clash, but that links two copies of the framework code — see the note at the end of [Use as a module](https://gortexa.sheng.page/en/quickstart/#use-as-a-module-no-scaffold) for the trade-off.

## 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, err := 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)

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

```go
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)
```