embed

package
v0.0.28 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 9, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package embed lets mecatui host its OWN mecated server in-process when no external one is running, so a single `mecatui` binary "just works" with no separately-spawned daemon and no TCP port.

It assembles the harness via the SHARED composition layer (internal/app) — the exact same engine, tools, permission policy, and service the standalone mecated binary builds — and serves it over a per-process UNIX socket in a private temp directory. The TUI then dials that socket as an ordinary gRPC client, so the ui/theme/client packages stay pure: they never learn the server is in-process.

Architectural boundary: this package — like cmd/mecatui/client and the cmd/mecatui main — is the ONLY place in the TUI tree allowed to import contracts/gen, grpc, internal/app, internal/adapter/*, and the server adapter. The render packages (ui, theme) and the client package import none of it.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type PerfConfig

type PerfConfig struct {
	// Enabled turns the whole perf surface on. The zero value (false) means no
	// telemetry, no admin listener, no flight recorder, no watchdog.
	Enabled bool
	// Addr is an explicit loopback TCP listen address for the admin mux. When
	// empty, the admin surface uses a private UNIX socket beside the embedded
	// gRPC socket; MCP instead uses ephemeral 127.0.0.1 TCP because the current
	// streaming-HTTP MCP client transport cannot dial HTTP over UNIX.
	Addr string
	// MCP mounts the read-only perf MCP server (internal/adapter/mcpperf) at /mcp on
	// the embedded admin mux, so an agent can introspect THIS process's
	// runtime/latency/profile state over MCP. Only meaningful with Enabled.
	// Explicit addresses are loopback-only; with no address MCP uses ephemeral
	// loopback TCP. A slow-turn ring is wired into the embedded engine's sink.
	MCP bool
	// GoroutineWarnThreshold arms the live goroutine-leak watchdog (decision 10):
	// a background sampler logs slog.Warn whenever runtime.NumGoroutine() exceeds
	// this count. 0 (default) disables the alarm; the runtime collector still
	// exports the goroutine count as a /metrics series regardless.
	GoroutineWarnThreshold int
	// GoroutineWarnInterval is how often the watchdog samples NumGoroutine. <= 0
	// falls back to the watchdog's own 30s default.
	GoroutineWarnInterval time.Duration
	// Logger receives the perf-surface startup/teardown lines and the watchdog
	// alarms. Nil falls back to slog.Default().
	Logger *slog.Logger
}

PerfConfig is the opt-in perf-observability configuration for the embedded server (decision 7 in docs/adr/0018-perf-observability.md). It is OFF by default (the zero value): mecatui hosts a bare gRPC socket with no telemetry, exactly as before. When Enabled, Start arms the SAME runtime-introspection surface mecated exposes — pprof, expvar, the runtime/RSS snapshot, and the execution FlightRecorder — on a loopback HTTP listener, plus the domain-metrics EventSink wired into the embedded engine so turn/tool/latency series render at /metrics.

The motivating incident (a render-starvation + memory-growth freeze in a since-removed tool) was a mecatui process freeze, so goroutines, RSS, pprof, and the flight recorder are exactly the instruments it needed — hence covering the embedded server, not just the standalone daemon.

type Server

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

Server is a mecated server hosted in the current process, listening on a UNIX socket. Close it to stop serving and release the socket, temp dir, and any composition-owned resources (the MCP manager) plus, when perf is enabled, the admin listener, the watchdog, the flight recorder, and the telemetry providers. It is safe to call Close once.

func Start

func Start(ctx context.Context, cfg app.Config, perf PerfConfig) (*Server, error)

Start builds the harness from cfg via internal/app and serves it over a fresh UNIX socket in a private temp directory. The returned Server's Target() is a gRPC dial string a client can connect to immediately (the listener is open before Start returns; serving runs on a background goroutine).

When perf.Enabled, Start ALSO installs the perf-observability surface (decision 7): it builds a telemetry MeterProvider + prometheus registry via the same telemetry.Setup path mecated uses, wires the domain-metrics EventSink into the embedded engine, registers the runtime collector + process-RSS gauge, arms the process-singleton FlightRecorder, optionally arms the goroutine watchdog, and serves the admin mux (/metrics, /debug/pprof/*, /debug/vars, /debug/flightrecorder) on a loopback HTTP listener. All of it is torn down by Server.Close, so an enabled perf surface never leaks a listener, a watchdog goroutine, or the flight recorder's runtime-trace subscription.

ctx governs the lifetime of composition-owned background work (MCP manager, memory consolidation) AND the perf watchdog; cancelling it does NOT stop the gRPC or admin servers — call Close for that. On any setup error Start cleans up everything it created before returning, so the caller never leaks a socket, temp dir, or telemetry resource.

func (*Server) AdminAddr

func (s *Server) AdminAddr() string

AdminAddr returns the resolved admin listener address: a private socket path for UNIX or host:port for TCP. It is empty when perf is disabled.

func (*Server) AdminNetwork added in v0.0.22

func (s *Server) AdminNetwork() string

AdminNetwork returns "unix" for the collision-free default or "tcp" for an explicit TCP address and for the streaming-HTTP MCP fallback.

func (*Server) Close

func (s *Server) Close() error

Close stops the gRPC server with a bounded graceful-stop window, tears down composition-owned resources with a separate bounded window, and (when perf was enabled) the admin listener, the watchdog, the flight recorder, and the telemetry providers, then removes the socket and its temp directory. It is safe to call once.

func (*Server) RecorderArmed

func (s *Server) RecorderArmed() bool

RecorderArmed reports whether THIS server armed (and therefore owns + will stop) the process FlightRecorder. It is false when perf is disabled, when the recorder failed to start, or when this server coalesced onto a recorder another owner armed — including a second perf-enabled run in the same process after the first run stopped the process-singleton (the sync.Once cannot be re-armed). Tests use it to decide whether /debug/flightrecorder will serve a live snapshot.

func (*Server) Target

func (s *Server) Target() string

Target returns the gRPC dial string for the hosted server (a "unix://" target).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL