sidecar

package
v0.22.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 18 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

View Source
var (

	// EventReady is a sidecar answering, started here (socket) or already
	// running at a URL (owned false).
	EventReady = logkit.DefineEvent("sidecar.ready", "A sidecar is ready for calls.", "name", "url", "socket", "owned")
)

A sidecar's log events, as the host sees it (docs/designs/logs.md).

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 RemoveSocket added in v0.16.0

func RemoveSocket(path string)

RemoveSocket removes a socket made by SocketPath, and its directory.

func SocketPath added in v0.16.0

func SocketPath(name string) (string, error)

SocketPath is where a spawned sidecar listens: <name>.sock, in a directory of its own that it makes in the temp dir. The temp dir, because a Unix socket's path is capped at about a hundred bytes (sun_path), which a deep home folder can exceed. A directory of its own, with a random name and readable by this user only, because the temp dir is shared with every user on the host: at a path another user could guess, they could take the address first, and the sidecar would fail to start, or anfra would send its requests to them. Its supervisor removes it with RemoveSocket.

func Unpack added in v0.21.0

func Unpack(name string, embedded []byte) (string, error)

Unpack writes the embedded binary name to anfra's folder, as Binary does, and returns its path: for a sidecar whose binary Binary's one variable can't choose.

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

	// CanalLakeSocket is where canal-lake listens, for a spawned canal-query to
	// reach it (CANAL_LAKE_SOCKET); empty, when the query cache is off. canal-lake
	// may start later: canal-query connects for each query.
	CanalLakeSocket 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
	// Dir is the folder it runs in; empty, anfra's own.
	Dir 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(ctx context.Context, 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.

ctx carries the trace its log record joins, as slog.Handler.Handle's does: it is not for cancellation, and does not bound the sidecar's life, which lasts until Close (exec.Command, not exec.CommandContext).

func (*Process) Close

func (p *Process) Close(ctx context.Context)

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

ctx carries the trace its log record joins, as slog.Handler.Handle's does: it is not for cancellation, so a sidecar closed after Ctrl-C still gets its 3s.

func (*Process) Done added in v0.21.0

func (p *Process) Done() <-chan struct{}

Done is closed once the sidecar has exited, stopped by Close or not.

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 anfracanal is the anfra-canal binary: canal's services in one, each run with its name as the first argument (anfra-canal query).
Package anfracanal is the anfra-canal binary: canal's services in one, each run with its name as the first argument (anfra-canal query).
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 canallake is the canal-lake sidecar, which stores the query cache's results as Parquet files: its supervisor.
Package canallake is the canal-lake sidecar, which stores the query cache's results as Parquet files: its supervisor.
Package canalquery is the canal-query sidecar, the SQL execution engine: its supervisor, which spawns one (anfra-canal's query service, see anfracanal) 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 (anfra-canal's query service, see anfracanal) 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