ripgen

README

RIPGen

A RPC lib that mostly generates code.

Focus is on:

• simplicity
• private APIs (controlling both sides)
• type checking over language barrier

Targets:

• go interface: creates go interfaces used by other generators
• go handler: creates a go server
• go client: creates a go client
• go decorator: decorate api calls, allows for: auhorisation, logging, transaction, profiling...
• go testfacade: readable API tests
• ts client: calls server side endpoints and maps data to js types

Example project

Declaration

The declaration consists of a list of query and mutation definitions and optionally data types.

Queries are calls that only read state and always return some data. They must not modify any state.

Mutations change state and should only return information belonging to that mutation.

query getFooById(id int, count int, order string): [int]

The given declaration will generate Interfaces and code that allows it to call the defined method remotely.

GetFooByID(id int, count int, order string) ([]int, error) { ... }

A method with above signature will be generated for the client and this signature will be called for the server.

async getFooById (id: number, count: number, order: string,): Promise<Array<number>> { ... }

Typescript client with above signature will be generated.

DataTypes

Scalars

Scalars in the meaning of non compound types are:

• int
• float
• time
• bool
• enum
• string

The enum type has it's possible values defined in comma separated pairs of name "value":

`enum (default "", foo, bar, none "n")`

If no string value is given it's string representation equals to the name.

Arrays

Arrays are defined by surounding it's element type by square brackets:

[string] // an array if strings

Maps

Maps keys are always of string type. They are defined by surounding it's value type by curly braces:

{int} // a map of string->int

Objects

Objects have multiple named fields where each one can have it's own type. They are also defined using curly braces but they have multiple field name -> value pairs:

{
  count  int
  name   string
  active bool
}

Field names must always be lower case.

Nullables

Data types can be nullable, meaning that their possible values ad well as null or undefined is a valid state. The default is non nullable and nullability canbe marked by appending a questionmark.

[string?]? // is an array of strings that can be null and can contain null values

Usually it's best to only allow null values when there is a good reason to do so.

Type declarations

Object types used as an Object property must be declared separately as a type:

type Foo {
    name string
}

query getFoos(): {
    foos  [Foo]
    total int
}

Custom types must always be uppercase, attributes lowercase.

External types

type Time external

Declares a type from the implementing language. In Go it could be time.Time in Typescript Date. To send it over the network it needs to be serialized as a string.

Doc comments

Comments are only allowed in front of type/call declarations or after object field declarations: They will be written into the generated type declarations so IDEs provide doc tooltips.

// Documentation for type
type Foo {
    field string // Comment for field, only single line allowed
    age int      // The age of the foo
}

// will return all foos
query getFoos(): [Foo]

Documentation

Index

• Variables
• func CatchAllErrorHandler() func(r *http.Request, err error) (int, []byte, http.Header)
• func ConsoleLogErrorHandler(next func(r *http.Request, err error) (int, []byte, http.Header)) func(r *http.Request, err error) (int, []byte, http.Header)
• func NewBadRequest(err error) error
• func ParseDetailed(sources []Source) (*model.Model, []error)
• func RipErrorHandler(next func(r *http.Request, err error) (int, []byte, http.Header)) func(r *http.Request, err error) (int, []byte, http.Header)
• type BadRequestError
  • func (e *BadRequestError) Cause() error
  • func (e *BadRequestError) Error() string
  • func (e *BadRequestError) Unwrap() error
• type Generator
  • func NewGenerator(source []Source, options ...Option) (*Generator, error)
  • func (g *Generator) Debug() ([]byte, error)
  • func (g *Generator) Go(iPkg, extPkg string, externals map[string]string) *GoGenerator
  • func (g *Generator) TypescriptClient(targetFile string, params TSParams) error
  • func (g *Generator) TypescriptMapper(targetFile string, params TSParams) error
  • func (g *Generator) TypescriptTypes(targetFile string, params TSParams) error
• type GoGenerator
  • func (g *GoGenerator) Client(clientFolder string) error
  • func (g *GoGenerator) Decorator(decoratorFolder string) error
  • func (g *GoGenerator) Interface(interfaceFolder string) error
  • func (g *GoGenerator) Profiler(profilerFolder string) error
  • func (g *GoGenerator) Server(handlerFolder string) error
  • func (g *GoGenerator) TestFacade(facadeFolder string) error
• type Option
  • func OptionAcronym(a string) Option
  • func OptionAcronymPlural(a string) Option
• type Source
• type TSParams

Variables

var DefaultErrorHandler = ConsoleLogErrorHandler(RipErrorHandler(CatchAllErrorHandler()))

Functions

func CatchAllErrorHandler

func CatchAllErrorHandler() func(r *http.Request, err error) (int, []byte, http.Header)

CatchAllErrorHandler returns for all errors an internal server error.

func ConsoleLogErrorHandler

func ConsoleLogErrorHandler(
	next func(r *http.Request, err error) (int, []byte, http.Header),
) func(r *http.Request, err error) (int, []byte, http.Header)

ConsoleLogErrorHandler forwards all error handling to next and prints the resulting errors to the console using log statements.

func NewBadRequest

func NewBadRequest(err error) error

func ParseDetailed

func ParseDetailed(sources []Source) (*model.Model, []error)

func RipErrorHandler

func RipErrorHandler(
	next func(r *http.Request, err error) (int, []byte, http.Header),
) func(r *http.Request, err error) (int, []byte, http.Header)

RipErrorHandler handles all errors produced by ripgen and forwards other errors to the next error handler.

Types

type BadRequestError

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

func (*BadRequestError) Cause

func (e *BadRequestError) Cause() error

Cause allows for github.com/pkg/errors.Cause(...)

func (*BadRequestError) Error

func (e *BadRequestError) Error() string

func (*BadRequestError) Unwrap

func (e *BadRequestError) Unwrap() error

Unwrap allows for go1.13+ errors.Unwrap(...), errors.Is(...) and errors.As(...)

type Generator

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

func NewGenerator

func NewGenerator(source []Source, options ...Option) (*Generator, error)

func (*Generator) Debug

func (g *Generator) Debug() ([]byte, error)

func (*Generator) Go

func (g *Generator) Go(iPkg, extPkg string, externals map[string]string) *GoGenerator

func (*Generator) TypescriptClient

func (g *Generator) TypescriptClient(targetFile string, params TSParams) error

func (*Generator) TypescriptMapper

func (g *Generator) TypescriptMapper(targetFile string, params TSParams) error

func (*Generator) TypescriptTypes

func (g *Generator) TypescriptTypes(targetFile string, params TSParams) error

type GoGenerator

type GoGenerator struct {
	// InterfacePkg is the full package name where the interface definition is generated to.
	InterfacePkg string
	// ExternalPkg is the full package name where the parse/serialize and construct methods
	// for the different external types are located.
	ExternalPkg string
	// Externals is the mapping of the external names to go data types.
	Externals map[string]string
	// contains filtered or unexported fields
}

func (*GoGenerator) Client

func (g *GoGenerator) Client(clientFolder string) error

func (*GoGenerator) Decorator

func (g *GoGenerator) Decorator(decoratorFolder string) error

func (*GoGenerator) Interface

func (g *GoGenerator) Interface(interfaceFolder string) error

func (*GoGenerator) Profiler

func (g *GoGenerator) Profiler(profilerFolder string) error

func (*GoGenerator) Server

func (g *GoGenerator) Server(handlerFolder string) error

func (*GoGenerator) TestFacade

func (g *GoGenerator) TestFacade(facadeFolder string) error

type Option

type Option interface {
	// contains filtered or unexported methods
}

func OptionAcronym

func OptionAcronym(a string) Option

func OptionAcronymPlural

func OptionAcronymPlural(a string) Option

type Source

type Source struct {
	Source []byte
	Name   string
}

type TSParams

type TSParams struct {
	Externals            map[string]string
	Imports              []string
	SingleParamMutations bool
}