transport

func CopyChannel ¶ added in v0.2026213.2047

func CopyChannel(dst interface{ Send(*pb.ChannelFrame) error }, src interface {
	Recv() (*pb.ChannelFrame, error)
}) error

CopyChannel relays frames until EOF or cancellation. It is intentionally a byte-preserving transport primitive; it does not inspect agent or terminal payloads.

func DialProcessProvider ¶

func DialProcessProvider(ctx context.Context, process spec.Process, opts DialOptions) (*grpc.ClientConn, pb.ProviderClient, error)

DialProcessProvider opens gRPC over a process supplied by a deployment executor. This is the placement-neutral sibling of DialProvider: the same protocol runs over local exec, SSH, containers, VMs, and recursively nested venues without teaching the gRPC layer about any of them.

func DialProvider ¶

func DialProvider(ctx context.Context, target spec.TargetSpec, opts DialOptions) (*grpc.ClientConn, pb.ProviderClient, error)

DialProvider opens gRPC over a local-exec or SSH stdio process. The SSH remote argv is fixed to `charly __agent-target serve --stdio`; nested target hops are carried as TargetSpec on the first Provider.Channel frame and are resolved by the responsible Charly node.

func IsServeMode ¶ added in v0.2026213.2047

func IsServeMode() bool

IsServeMode reports whether this process was launched by charly as a go-plugin gRPC SERVER (the handshake magic-cookie env is present) rather than invoked directly as a CLI. charly sets the cookie ONLY when it execs a plugin to connect over gRPC (LocalTransport, for a verb/kind/deploy/step/builder capability); a COMMAND plugin fork/exec'd as a CLI passthrough (charly's syscall.Exec command dispatch strips the cookie) sees it absent and runs in CLI mode. The single switch a dual-mode plugin's main() pivots on.

func Main ¶ added in v0.2026213.2047

func Main(providerSrv pb.ProviderServer, metaSrv pb.PluginMetaServer, cli func(args []string) int)

Main is the dual-mode entry point a plugin's main() delegates to. In SERVE mode (charly launched it over go-plugin gRPC) it serves the plugin's Provider + PluginMeta (its verb/kind/deploy/step/builder capabilities). Otherwise the plugin was fork/exec'd by charly's COMMAND dispatch (or run by hand) and owns real terminal stdio/TTY: cli runs the command's work with os.Args[1:], its int return becoming the process exit code.

func main() { transport.Main(&provider{}, &meta{}, cliMain) }

func OpenProviderChannel ¶ added in v0.2026213.2047

func OpenProviderChannel(ctx context.Context, client pb.ProviderClient, open *pb.ChannelFrame) (pb.Provider_ChannelClient, error)

OpenProviderChannel starts a generated Provider.Channel stream and sends its mandatory open frame. The returned stream is ready for concurrent Send/Recv, as supported by gRPC.

func PluginMap ¶ added in v0.2026213.2047

func PluginMap(providerSrv pb.ProviderServer, metaSrv pb.PluginMetaServer) plugin.PluginSet

PluginMap builds the go-plugin PluginSet for the dispense key. Server side passes the two service impls; the client side (charly connecting) passes nil,nil and receives a *Conn from the dispense.

func ReceiveChannelOpen ¶ added in v0.2026213.2047

func ReceiveChannelOpen(stream ProviderChannel) (*pb.ChannelFrame, error)

ReceiveChannelOpen reads and validates the mandatory first frame. The request id, provider class/word, and operation are required so every later frame can be correlated without inspecting runtime-specific payloads.

func RelayChannel ¶ added in v0.2026213.2047

func RelayChannel(upstream ProviderChannel, downstream interface {
	ProviderChannel
	CloseSend() error
}) error

RelayChannel connects a controller-side ProviderChannel to a downstream gRPC channel with ordered half-close semantics. Provider output is the evidence writer: once that direction ends, no later frame can mutate controller state and the relay may return. If controller input ends first, CloseSend delivers the protocol EOF and the relay drains provider output before returning. This prevents a completed command from racing its successor's durable cursor.

Cancellation ownership: when the provider-output direction finishes first, RelayChannel returns while the input-copy goroutine may still be blocked in upstream.Recv(). The CALLER owns upstream's lifecycle — after return, cancel the context upstream carries (or close upstream) to release that goroutine.

func Serve ¶ added in v0.2026213.2047

func Serve(providerSrv pb.ProviderServer, metaSrv pb.PluginMetaServer)

Serve exposes a plugin's Provider + PluginMeta services over go-plugin gRPC and blocks serving. The host reaps it on exit by killing the client connection (providerRegistry.Close → client.Kill, sending the gRPC Shutdown that stops this server); go-plugin's server has no parent-death detection of its own, so watchParentDeath is the backstop that self-terminates this process if the host dies without reaping (crash / SIGKILL / os.Exit) — preventing orphaned `__plugin serve` processes. The serve half of Main (a verb/kind/deploy/step/ builder plugin with no CLI mode may call it directly):

func main() { transport.Serve(&myProvider{}, &myMeta{}) }

func ServeStdio ¶

func ServeStdio(stdin io.ReadCloser, stdout io.WriteCloser, register func(*grpc.Server), opts ...grpc.ServerOption) error

ServeStdio runs a gRPC server on one full-duplex stdio connection. stdout is exclusively HTTP/2 protocol data; diagnostics belong on stderr.

func StdioCommand ¶

func StdioCommand(target spec.TargetSpec, opts DialOptions) ([]string, error)

StdioCommand validates the generic route and returns an argv with no shell interpolation. Hops after the first grpc marker—including tmux, another SSH node, or an exec/container hop—are nested routing data, not special cases.

func StdioFiles ¶

func StdioFiles() (io.ReadCloser, io.WriteCloser)

StdioFiles is the production adapter used by the hidden target command.