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 ¶
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
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 Unreachable ¶
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.
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 ¶
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.
Source Files
¶
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. |