plugin

Documentation

Overview

Package plugin contains the implementations needed to make the built binary act as a plugin.

A plugin is implemented as an RPC server and the host acts as the client, sending analysis requests to the plugin. Note that the server-client relationship here is the opposite of the communication that takes place during the checking phase.

Implementation details are hidden in go-plugin. This package is essentially a wrapper for go-plugin.

Usage

A simple plugin can look like this:

package main

import (
    _ "embed" //nolint

    "github.com/terraform-docs/terraform-docs/plugin"
    "github.com/terraform-docs/terraform-docs/print"
    "github.com/terraform-docs/terraform-docs/template"
    "github.com/terraform-docs/terraform-docs/terraform"
)

func main() {
    plugin.Serve(&plugin.ServeOpts{
        Name:    "template",
        Version: "0.1.0",
        Printer: printerFunc,
    })
}

//go:embed sections.tmpl
var tplCustom []byte

// printerFunc the function being executed by the plugin client.
func printerFunc(config *print.Config, module *terraform.Module) (string, error) {
    tpl := template.New(config,
        &template.Item{Name: "custom", Text: string(tplCustom)},
    )

    rendered, err := tpl.Render("custom", module)
    if err != nil {
        return "", err
    }

    return rendered, nil
}

Index

• func NewClient(opts *ClientOpts) *goplugin.Client
• func Serve(opts *ServeOpts)
• type Client
  • func (c *Client) Execute(args *ExecuteArgs) (string, error)
  • func (c *Client) Name() (string, error)
  • func (c *Client) Version() (string, error)
• type ClientOpts
• type ExecuteArgs
• type ServeOpts
• type Server
  • func (s *Server) Execute(args *ExecuteArgs, resp *string) error
  • func (s *Server) Name(args interface{}, resp *string) error
  • func (s *Server) Version(args interface{}, resp *string) error

Functions

func NewClient

func NewClient(opts *ClientOpts) *goplugin.Client

NewClient is a wrapper of plugin.NewClient.

func Serve

func Serve(opts *ServeOpts)

Serve is a wrapper of plugin.Serve. This is entrypoint of all plugins.

Types

type Client

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

Client is an RPC Client for the host.

func (*Client) Execute

func (c *Client) Execute(args *ExecuteArgs) (string, error)

Execute calls the server-side Execute method and returns generated output.

func (*Client) Name

func (c *Client) Name() (string, error)

Name calls the server-side Name method and returns its version.

func (*Client) Version

func (c *Client) Version() (string, error)

Version calls the server-side Version method and returns its version.

type ClientOpts

type ClientOpts struct {
	Cmd *exec.Cmd
}

ClientOpts is an option for initializing a Client.

type ExecuteArgs

type ExecuteArgs struct {
	Module *terraform.Module
	Config *print.Config
}

ExecuteArgs is the collection of arguments being sent by terraform-docs core while executing the plugin command.

type ServeOpts

type ServeOpts struct {
	Name    string
	Version string
	Printer printFunc
}

ServeOpts is an option for serving a plugin.

type Server

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

Server is an RPC Server acting as a plugin.

func (*Server) Execute

func (s *Server) Execute(args *ExecuteArgs, resp *string) error

Execute returns the generated output.

func (*Server) Name

func (s *Server) Name(args interface{}, resp *string) error

Name returns the version of the plugin.

func (*Server) Version

func (s *Server) Version(args interface{}, resp *string) error

Version returns the version of the plugin.