glue

README

Glue

Note
Segment has paused maintenance on this project, but may return it to an active status in the future. Issues and pull requests from external contributors are not being considered, although internal contributions may appear from time to time. The project remains available under its open source license for anyone to use.

Glue generates client code for your Go RPC server. It currently supports

• net/rpc
• gorilla/rpc

Installation

go get github.com/segmentio/glue/cmd/glue

Then, glue should be available at $GOPATH/bin/glue (ideally, in your $PATH).

Usage

glue -name=Service -service=Math [path] will traverse the provided path (or working directory if none is provided) and generate clients for RPC methods (pointed at Math.*) declared on type Service.

Given the following is in a *.go file in your working directory,

package math

//go:generate glue -name Service -service Math
type Service struct{}

type SumArg struct {
	Values []int
}

type SumReply struct {
	Sum int
}

func (s *Service) Sum(arg SumArg, reply *SumReply) error {
	for _, v := range arg.Values {
		reply.Sum += v
	}

	return nil
}

go generate would output the following to clients/Service.go

package client

import (
	"github.com/segmentio/glue/example/stl/math"
)

type Client interface {
	Call(method string, args interface{}, reply interface{}) error
}

func NewMathClient(rpcClient Client) *Math {
	c := new(Math)
	c.RPC = rpcClient
	return c
}

type Math struct {
	RPC Client
}

func (c *Math) Sum(args math.SumArg) (*math.SumReply, error) {
	reply := new(math.SumReply)
	err := c.RPC.Call("Math.Sum", args, reply)
	return reply, err
}

Gorilla

If you use gorilla/rpc, you're in luck! Just specify -gorilla.

Options

Output

Glue always outputs code with client package. By default, this is in ./client, but you can change the output directory via -out.

To output code to STDOUT instead of files, supply -print.

FAQ

How do I use Glue with RPC implementation X?

Glue is modular. If you'd like support for another popular (or interesting, well-maintained) RPC implementation, open a PR to add a new Glue provider/.

Unfortunately, Go doesn't allow dynamic loading of packages so if you'd like Glue to support an internal or experimental RPC framework, fork Glue and supply another provider in cmd/glue/main.go.

Documentation

Index

• type Directions
• type Visitor
  • func NewVisitor(cfg VisitorConfig) *Visitor
  • func (p *Visitor) Go() map[string][]*types.Func
  • func (p *Visitor) Visit(node ast.Node) ast.Visitor
• type VisitorConfig
• type Walker
  • func (w *Walker) Walk(directions Directions) error

Types

type Directions

type Directions struct {
	// Path determines the source code path to walk along. It's required
	Path string
	// Name is the name of the RPC declaration (e.g. `type MathService struct{}`).
	Name string
	// Service is the name of the RPC service. (e.g. `Math` in `Math.Sum`)
	Service string
}

Directions tell the Walker where to walk and what to pay attention to along the way.

type Visitor

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

Visitor traverses a Go package's AST, visits declarations that satisfy the structure of an RPC service, and extracts their RPC methods.

func NewVisitor

func NewVisitor(cfg VisitorConfig) *Visitor

NewVisitor creates a Visitor.

func (*Visitor) Go

func (p *Visitor) Go() map[string][]*types.Func

Go starts Visitor's trip around the supplied package. Upon return, it sends a mapping of receiver identifiers to RPC methods.

func (*Visitor) Visit

func (p *Visitor) Visit(node ast.Node) ast.Visitor

Visit extracts functions from RPC declarations. It satisfies go/ast.Visitor.

type VisitorConfig

type VisitorConfig struct {
	// Pkg contains metadata for the target package.
	Pkg *loader.PackageInfo
	// Provider determines which RPC methods are suitable.
	Provider provider.Provider
	// Declaration is the name of the target RPC declaration (method receiver).
	Declaration string
}

VisitorConfig is used to create a Visitor.

type Walker

type Walker struct {
	// Provider answers RPC-implementation-specific (e.g. stl, gorilla, etc.) questions.
	Provider provider.Provider
	Writer   writer.Writer
}

A Walker walks along supplied directions, visits server RPC code, and generates RPC client code along the way with the help of others.

func (*Walker) Walk

func (w *Walker) Walk(directions Directions) error

Walk is the logical entrypoint for Glue. It walks the source code and asks