plugin

Documentation

Index

• func AllocatePort() (*net.TCPAddr, error)
• func Start[Impl any, Iface any, Config any](ctx context.Context, name string, create Constructor[Impl, Config], ...)
• type ConnectHandlerFactory
• type Constructor
• type Option
  • func WithEnvars(envars ...string) Option
  • func WithExtraClient[Client rpc.Pingable[Req, Resp, RespPtr], Req any, Resp any, ...](out *Client, makeClient rpc.ClientFactory[Client, Req, Resp, RespPtr]) Option
  • func WithStartTimeout(timeout time.Duration) Option
• type PingableClient
• type Plugin
  • func Spawn[Client rpc.Pingable[Req, Resp, RespPtr], Req any, Resp any, ...](ctx context.Context, defaultLevel log.Level, name, dir, exe string, ...) (plugin *Plugin[Client, Req, Resp, RespPtr], cmdCtx context.Context, err error)
• type StartOption
  • func RegisterAdditionalHandler[Impl any](path string, handler http.Handler) StartOption[Impl]
  • func RegisterAdditionalServer[Impl any, Iface any](servicePath string, register ConnectHandlerFactory[Iface]) StartOption[Impl]

Functions

func AllocatePort

func AllocatePort() (*net.TCPAddr, error)

func Start

func Start[Impl any, Iface any, Config any](
	ctx context.Context,
	name string,
	create Constructor[Impl, Config],
	servicePath string,
	register ConnectHandlerFactory[Iface],
	options ...StartOption[Impl],
)

Start a gRPC server plugin listening on the socket specified by the environment variable FTL_BIND.

This function does not return.

"Config" is Kong configuration to pass to "create". "create" is called to create the implementation of the service. "register" is called to register the service with the gRPC server and is typically a generated function.

Types

type ConnectHandlerFactory

type ConnectHandlerFactory[Iface any] func(Iface, ...connect.HandlerOption) (string, http.Handler)

ConnectHandlerFactory is a type alias for a function that creates a new Connect request handler.

This will typically just be the generated NewXYZHandler function.

type Constructor

type Constructor[Impl any, Config any] func(context.Context, Config) (context.Context, Impl, error)

Constructor is a function that creates a new plugin server implementation.

type Option

type Option func(*pluginOptions) error

Option used when creating a plugin.

func WithEnvars

func WithEnvars(envars ...string) Option

WithEnvars sets the environment variables to pass to the plugin.

func WithExtraClient

func WithExtraClient[Client rpc.Pingable[Req, Resp, RespPtr], Req any, Resp any, RespPtr rpc.PingResponse[Resp]](out *Client, makeClient rpc.ClientFactory[Client, Req, Resp, RespPtr]) Option

WithExtraClient connects to an additional gRPC service in the same plugin.

The client instance is written to "out".

func WithStartTimeout

func WithStartTimeout(timeout time.Duration) Option

WithStartTimeout sets the timeout for the language-specific drive plugin to start.

type PingableClient

type PingableClient interface {
	Ping(ctx context.Context, req *connect.Request[ftlv1.PingRequest]) (*connect.Response[ftlv1.PingResponse], error)
}

PingableClient is a gRPC client that can be pinged.

type Plugin

type Plugin[Client rpc.Pingable[Req, Resp, RespPtr], Req any, Resp any, RespPtr rpc.PingResponse[Resp]] struct {
	Cmd      *exec.Cmd
	Endpoint *url.URL // The endpoint the plugin is listening on.
	Client   Client
}

func Spawn

func Spawn[Client rpc.Pingable[Req, Resp, RespPtr], Req any, Resp any, RespPtr rpc.PingResponse[Resp]](
	ctx context.Context,
	defaultLevel log.Level,
	name, dir, exe string,
	makeClient rpc.ClientFactory[Client, Req, Resp, RespPtr],
	options ...Option,
) (plugin *Plugin[Client, Req, Resp, RespPtr], cmdCtx context.Context, err error)

Spawn a new sub-process plugin.

Plugins are gRPC servers that listen on a socket passed in an envar.

If the subprocess is a Go plugin, it should call Start to start the gRPC server.

"cmdCtx" will be cancelled when the plugin stops.

The envars passed to the plugin are:

FTL_BIND - the endpoint URI to listen on
FTL_WORKING_DIR - the path to a working directory that the plugin can write state to, if required.

type StartOption

type StartOption[Impl any] func(*startOptions[Impl])

StartOption is an option for Start.

func RegisterAdditionalHandler

func RegisterAdditionalHandler[Impl any](path string, handler http.Handler) StartOption[Impl]

RegisterAdditionalHandler allows a plugin to serve additional HTTP handlers.

func RegisterAdditionalServer

func RegisterAdditionalServer[Impl any, Iface any](servicePath string, register ConnectHandlerFactory[Iface]) StartOption[Impl]

RegisterAdditionalServer allows a plugin to serve additional gRPC services.

"Impl" must be an implementation of "Iface.