protocol

Documentation

Overview

Package protocol defines the shared interface between the gohttpd host and its plugins.

Both the host and plugin binaries import this package. The GoHttpPlugin interface is the contract that plugins must implement. The host communicates with plugins via hashicorp/go-plugin's net/rpc protocol, calling methods defined in this interface.

Architecture

A plugin is a single long-running process. It can serve multiple HTTP services simultaneously, each identified by a (ServerName, Path) pair. The host calls Serve() for each server/path combination that references the plugin, and the plugin starts an internal HTTP server for each one, returning the listening port. The host then reverse-proxies matching requests to that port.

Host                          Plugin (separate process)
────                          ──────────────────────
plugin.NewClient()            plugin.Serve()
rpcClient.Dispense()          → GoHttpPluginPlugin.Server()
goHttpPlugin.Meta()           → returns name + version
goHttpPlugin.Start()          → initializes plugin resources
goHttpPlugin.Serve(srv,path,cfg) → starts HTTP server, returns port
goHttpPlugin.UnServe(srv,path)   → stops HTTP server
goHttpPlugin.ShutDown()       → releases plugin resources

Once a plugin's HTTP server is running, the host creates a reverse proxy (httputil.ReverseProxy) to the plugin's port and routes matching requests to it.

Index

• type GoHttpPlugin
• type GoHttpPluginPlugin
  • func (p *GoHttpPluginPlugin) Client(broker *plugin.MuxBroker, client *rpc.Client) (interface{}, error)
  • func (p *GoHttpPluginPlugin) Server(broker *plugin.MuxBroker) (interface{}, error)
• type GoHttpPluginRPCClient
  • func (c *GoHttpPluginRPCClient) Meta() (PluginMeta, error)
  • func (c *GoHttpPluginRPCClient) Serve(ServerName, Path string, Config map[string]interface{}) (int, error)
  • func (c *GoHttpPluginRPCClient) ShutDown() error
  • func (c *GoHttpPluginRPCClient) Start() error
  • func (c *GoHttpPluginRPCClient) UnServe(ServerName, Path string) error
• type GoHttpPluginRPCServer
  • func (s *GoHttpPluginRPCServer) Meta(args *MetaArgs, reply *MetaReply) error
  • func (s *GoHttpPluginRPCServer) Serve(args *ServeArgs, reply *ServeReply) error
  • func (s *GoHttpPluginRPCServer) ShutDown(args *ShutDownArgs, reply *ShutDownReply) error
  • func (s *GoHttpPluginRPCServer) Start(args *StartArgs, reply *StartReply) error
  • func (s *GoHttpPluginRPCServer) UnServe(args *UnServeArgs, reply *UnServeReply) error
• type MetaArgs
• type MetaReply
• type PluginMeta
• type ServeArgs
• type ServeReply
• type ShutDownArgs
• type ShutDownReply
• type StartArgs
• type StartReply
• type UnServeArgs
• type UnServeReply

Types

type GoHttpPlugin

type GoHttpPlugin interface {
	// Meta returns plugin metadata (name and version).
	// Called once during plugin loading.
	Meta() (PluginMeta, error)

	// Start initializes the plugin's own resources.
	// Called once after Meta() during plugin loading.
	Start() error

	// ShutDown releases the plugin's own resources.
	// Called during plugin shutdown.
	ShutDown() error

	// Serve starts an internal HTTP server for the given server/path combination
	// with the given configuration. The plugin should bind to "127.0.0.1:0"
	// (random available port) and return the actual port number. The config map
	// is the PluginOptions from HttpPath.
	// Returns the port the HTTP server is listening on.
	Serve(ServerName, Path string, Config map[string]interface{}) (int, error)

	// UnServe stops the internal HTTP server for the given server/path combination.
	// Called when the corresponding route is removed or its config changes.
	UnServe(ServerName, Path string) error
}

GoHttpPlugin is the interface that all plugins must implement. It is the contract between the gohttpd host and plugin processes, communicated over net/rpc via hashicorp/go-plugin.

The plugin is a single long-running process. Meta, Start, and ShutDown manage the plugin's own lifecycle. Serve and UnServe start/stop individual HTTP services within the plugin, each identified by a (ServerName, Path) pair. This allows one plugin to serve multiple server/path combinations with different configurations simultaneously.

type GoHttpPluginPlugin

type GoHttpPluginPlugin struct {
	Impl GoHttpPlugin
}

GoHttpPluginPlugin is the adapter that makes GoHttpPlugin usable with hashicorp/go-plugin. It implements plugin.Plugin and is registered in the go-plugin PluginSet under the name "gohttp-plugin".

Both the host and plugin use this type:

• Plugin side: Impl is set to the real implementation
• Host side: Impl is nil (the Client method returns an RPC client)

func (*GoHttpPluginPlugin) Client

func (p *GoHttpPluginPlugin) Client(broker *plugin.MuxBroker, client *rpc.Client) (interface{}, error)

Client implements plugin.Plugin. It returns an RPC client that implements GoHttpPlugin by calling the remote plugin. Called inside the host process.

func (*GoHttpPluginPlugin) Server

func (p *GoHttpPluginPlugin) Server(broker *plugin.MuxBroker) (interface{}, error)

Server implements plugin.Plugin. It returns the RPC server that wraps the real GoHttpPlugin implementation. Called inside the plugin process.

type GoHttpPluginRPCClient

type GoHttpPluginRPCClient struct {
	// contains filtered or unexported fields
}

GoHttpPluginRPCClient implements GoHttpPlugin by making net/rpc calls to the plugin process. This runs inside the host process.

func (*GoHttpPluginRPCClient) Meta

func (c *GoHttpPluginRPCClient) Meta() (PluginMeta, error)

Meta calls the remote plugin's Meta method via RPC.

func (*GoHttpPluginRPCClient) Serve

func (c *GoHttpPluginRPCClient) Serve(ServerName, Path string, Config map[string]interface{}) (int, error)

Serve calls the remote plugin's Serve method via RPC.

func (*GoHttpPluginRPCClient) ShutDown

func (c *GoHttpPluginRPCClient) ShutDown() error

ShutDown calls the remote plugin's ShutDown method via RPC.

func (*GoHttpPluginRPCClient) Start

func (c *GoHttpPluginRPCClient) Start() error

Start calls the remote plugin's Start method via RPC.

func (*GoHttpPluginRPCClient) UnServe

func (c *GoHttpPluginRPCClient) UnServe(ServerName, Path string) error

UnServe calls the remote plugin's UnServe method via RPC.

type GoHttpPluginRPCServer

type GoHttpPluginRPCServer struct {
	Impl GoHttpPlugin
}

GoHttpPluginRPCServer wraps a GoHttpPlugin implementation and exposes it via net/rpc. This runs inside the plugin process.

func (*GoHttpPluginRPCServer) Meta

func (s *GoHttpPluginRPCServer) Meta(args *MetaArgs, reply *MetaReply) error

Meta is the RPC wrapper for GoHttpPlugin.Meta().

func (*GoHttpPluginRPCServer) Serve

func (s *GoHttpPluginRPCServer) Serve(args *ServeArgs, reply *ServeReply) error

Serve is the RPC wrapper for GoHttpPlugin.Serve().

func (*GoHttpPluginRPCServer) ShutDown

func (s *GoHttpPluginRPCServer) ShutDown(args *ShutDownArgs, reply *ShutDownReply) error

ShutDown is the RPC wrapper for GoHttpPlugin.ShutDown().

func (*GoHttpPluginRPCServer) Start

func (s *GoHttpPluginRPCServer) Start(args *StartArgs, reply *StartReply) error

Start is the RPC wrapper for GoHttpPlugin.Start().

func (*GoHttpPluginRPCServer) UnServe

func (s *GoHttpPluginRPCServer) UnServe(args *UnServeArgs, reply *UnServeReply) error

UnServe is the RPC wrapper for GoHttpPlugin.UnServe().

type MetaArgs

type MetaArgs struct{}

MetaArgs is the RPC argument for the Meta method (no arguments).

type MetaReply

type MetaReply struct {
	Meta PluginMeta
}

MetaReply is the RPC reply for the Meta method.

type PluginMeta

type PluginMeta struct {
	// Name is the unique plugin name, used in HttpPath.PluginName config.
	Name string
	// Version is the plugin version string (informational).
	Version string
}

PluginMeta carries plugin identity information returned by Meta().

type ServeArgs

type ServeArgs struct {
	ServerName string
	Path       string
	Config     map[string]interface{}
}

ServeArgs is the RPC argument for the Serve method.

type ServeReply

type ServeReply struct {
	Port int
}

ServeReply is the RPC reply for the Serve method.

type ShutDownArgs

type ShutDownArgs struct{}

ShutDownArgs is the RPC argument for the ShutDown method (no arguments).

type ShutDownReply

type ShutDownReply struct{}

ShutDownReply is the RPC reply for the ShutDown method (no return value).

type StartArgs

type StartArgs struct{}

StartArgs is the RPC argument for the Start method (no arguments).

type StartReply

type StartReply struct{}

StartReply is the RPC reply for the Start method (no return value).

type UnServeArgs

type UnServeArgs struct {
	ServerName string
	Path       string
}

UnServeArgs is the RPC argument for the UnServe method.

type UnServeReply

type UnServeReply struct{}

UnServeReply is the RPC reply for the UnServe method (no return value).