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 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 []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.
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. |