sidecar

package
v0.14.2 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package sidecar is the framework anfra's sidecars are run with: the Config a host gives them, the lifecycle of one it spawns (Process), how its binary is found (Binary), and how a sidecar that does not answer is classified (Unreachable). The sidecars themselves live in the packages under this one, a package per sidecar — its supervisor, its client and its wire types — so what one speaks stays its own.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Binary

func Binary(name, env string, embedded []byte) (string, error)

Binary returns a path to the sidecar name's executable. Release builds embed it (embedded, extracted to a content-addressed cache dir); dev builds embed nothing, and take it from the environment variable env.

func Unreachable

func Unreachable(ctx context.Context, sidecar string, err error) error

Unreachable classifies a failure to reach a sidecar at all — the request never got a response — as sidecar_unavailable. A caller that gave up first is not an outage: its cancellation or deadline is returned as it is, for the host to treat as its own.

Types

type Config

type Config struct {
	// RepoID is passed to the sidecar as ANFRA_REPO_ID, which tags the sidecar's
	// logs and nothing else. It is deliberately not a cache or isolation identity:
	// a sidecar may serve many repos, so each request names its own repo (see
	// anfranode.CompileToSQLRequest.RepoID) and the sidecar refuses requests that
	// don't.
	RepoID           string
	CompileCachePath string    // anfra-node's AML compile cache dir (per-repo); passed as ANFRA_COMPILE_CACHE_PATH
	StderrWriter     io.Writer // sidecar stderr sink (the log stream); defaults to os.Stderr
	StdoutWriter     io.Writer // sidecar stdout sink (banners/incidental); defaults to io.Discard
	Logger           *slog.Logger
	// EnablePooling turns on canal-query connection pooling. Only useful when the
	// sidecar is long-lived (the pool is reused across requests under `anfra
	// serve`); ignored by anfra-node.
	EnablePooling bool

	// NodeURL / CanalQueryURL address sidecars this process does not own, as in a
	// docker-compose / k8s deployment. When set, the supervisor resolves no
	// binary, starts no process, and Close is a no-op. Empty means spawn one.
	NodeURL       string
	CanalQueryURL string

	// WrapTransport, if set, wraps each sidecar client's transport once the
	// sidecar is ready — e.g. with otelhttp, so a host traces the calls and
	// propagates its trace into the sidecar. It receives the client's own
	// transport, so the engine's settings (the Unix socket dialer, pooling) are
	// kept; sidecar names the sidecar ("anfra-node", "canal-query"). Readiness
	// polling is not wrapped: it would trace every poll.
	WrapTransport func(sidecar string, rt http.RoundTripper) http.RoundTripper
}

Config is shared by the sidecar supervisors: how to tag and forward their output, and where per-repo state lives.

func (Config) Log

func (c Config) Log() *slog.Logger

Log returns the configured logger, or the default. The spawn path gets one from the started process; the external path has no process to ask.

func (Config) Wrap

func (c Config) Wrap(sidecar string, hc *http.Client)

Wrap applies WrapTransport to a ready sidecar's client.

type ProcSpec

type ProcSpec struct {
	Name string
	Path string
	Args []string
	// ExtraEnv is what the supervisor sets, over anything inherited or
	// forwarded (childEnv).
	ExtraEnv []string
	// DefaultEnv is what the supervisor sets unless anfra's environment sets it
	// for this sidecar, through EnvPrefix.
	DefaultEnv []string
	// EnvPrefix forwards <EnvPrefix><NAME>=value from anfra's environment as
	// NAME=value, to this sidecar only: e.g. ANFRA_CANAL_QUERY_ENV_.
	EnvPrefix string
	Stdout    io.Writer // child stdout sink; defaults to io.Discard
	Stderr    io.Writer // child stderr sink (the log stream); defaults to os.Stderr
	Logger    *slog.Logger
	PipeStdin bool // wire a stdin pipe so the child can use stdin-EOF as a parent-death signal (Node does; canal doesn't)
}

ProcSpec is how to spawn a sidecar.

type Process

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

Process is the shared lifecycle of any spawned sidecar: orphan-prevention (process group + Pdeathsig) and stdio forwarded into the host log sink. Protocol/readiness live in each sidecar's own package.

func StartProcess

func StartProcess(spec ProcSpec) (*Process, error)

StartProcess spawns the sidecar spec describes. It does not wait for it to be ready: that is the sidecar's protocol, its own package's to check.

func (*Process) Close

func (p *Process) Close()

Close stops the sidecar: SIGTERM, then SIGKILL to its process group if it has not exited within 3s.

func (*Process) Logger

func (p *Process) Logger() *slog.Logger

Logger is the supervisor's logger (defaulted in StartProcess), so supervisors can log their own events without re-defaulting.

Directories

Path Synopsis
Package anfranode is the anfra-node sidecar, the AML/AQL engine: its supervisor, which spawns one or connects to an external one, and its JSON-RPC client.
Package anfranode is the anfra-node sidecar, the AML/AQL engine: its supervisor, which spawns one or connects to an external one, and its JSON-RPC client.
Package canalquery is the canal-query sidecar, the SQL execution engine: its supervisor, which spawns one or connects to an external one, and its client.
Package canalquery is the canal-query sidecar, the SQL execution engine: its supervisor, which spawns one or connects to an external one, and its client.

Jump to

Keyboard shortcuts

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