kit

Documentation

Overview

Package kit provides a code generator to generate endpoints and http handlers for an interface. For the code generator to work, the following requirements should be met:

• Interface methods do not contain function types, channel types or anonymous structs as parameter or return values.
• The source file that contains the interface should not import any types that are used in the interface definition using ".", i.e. (import them without a prefix/qualifier).
• Every interface method has a context.Context as the first parameter.
• Every interface method has 1 or 2 return values, where the last one is always "error".

Index

• type EndpointSpecification
• type EndpointSpecifications
  • func (e EndpointSpecifications) IsValid() error
• type HttpParamType
• type HttpSpec
  • func (spec HttpSpec) IsValid() error
• type KitGenSpecification
  • func SpecFromAnnotations(i parse.Interface, m parse.Module, a annotations.InterfaceAnnotation) (KitGenSpecification, error)
  • func (spec KitGenSpecification) ContainsDuplicateEndpointName() error
  • func (spec KitGenSpecification) IsValid() error
• type KitGenerator
  • func NewKitGenerator(spec KitGenSpecification) *KitGenerator
  • func (g *KitGenerator) Generate() (result []gen.GenResult, err error)

Types

type EndpointSpecification

type EndpointSpecification struct {
	// name of this endpoint, defaults to the name of the method
	Name string `json:"name"`

	// specifies how the http handler for this endpoint is generated
	HttpSpec HttpSpec `json:"http"`
}

Specification to create a single endpoint for an inteface method.

type EndpointSpecifications

type EndpointSpecifications struct {
	// the interface method to generate endpoints for
	Method parse.Method

	EndpointSpecs []EndpointSpecification `json:"endpoints"`

	// How the values from the interface method are obtained from an http request,
	// only used if http handlers are generated.
	// Since we expect the first parameter of an interface method to be a "context.Context", the length of this slice
	// should equal len(Method.Params) - 1.
	// TODO we could let every endpoint for this method define their own http params, which would result in multiple http decode funcs, but this is not necessary for now.
	HttpParams []HttpParamType `json:"httpParams"`
}

Defines the endpoints created for a single interface method. We can generate multiple endpoints for the same interface method, e.g. to use different permission/authentication middlewares or different http urls.

func (EndpointSpecifications) IsValid

func (e EndpointSpecifications) IsValid() error

type HttpParamType

type HttpParamType string

HttpParamType represents how the parameters of an interface method should be obtained from a http request. E.g. by parsing the request body as json or extracting the parameter from the url path or query parameters.

const HttpTypeJson HttpParamType = "json"

const HttpTypeQuery HttpParamType = "query"

const HttpTypeUrl HttpParamType = "url"

type HttpSpec

type HttpSpec struct {
	// url
	Path string `json:"path"`
	// http method, e.g. "GET", "POST", ...
	Method string `json:"method"`
	// http code for the response on success
	SuccessCode int `json:"successCode"`
}

Defines how a http handler is generated for an endpoint.

func (HttpSpec) IsValid

func (spec HttpSpec) IsValid() error

type KitGenSpecification

type KitGenSpecification struct {
	//the interface for which code should be generated
	Interface parse.Interface
	//go module the interface belongs to
	Module parse.Module

	// if false, nothing will be generated
	GenerateEndpoints bool
	// if false, will not generate http handlers for endpoints
	GenerateHttp bool

	// package name used for generated endpoints
	// can be a full package path or relative to the module name
	// If empty will not generate endpoints.
	EndpointPackage string `json:"endpointPackage"`
	// full path of the package that will contain the generated endpoint code
	// we need this to later import this package to e.g. generate http handlers
	EndpointPackageFullPath string
	// output file for endpoint code
	EndpointOutput string `json:"endpointOutput"`
	// Package name used for generated http handlers.
	// If empty will not generate anything.
	HttpPackage         string `json:"httpPackage"`
	HttpPackageFullPath string
	// output file for http code
	HttpOutput string `json:"httpOutput"`

	// each element specifies the endpoints to generate for an interface method
	Endpoints []EndpointSpecifications
}

KitGenSpecification defines what the code generator should generate. It is typically constructed by reading source code annotations on e.g. an interface or method and configuration from the command line or a configuration file.

func SpecFromAnnotations

func SpecFromAnnotations(i parse.Interface, m parse.Module, a annotations.InterfaceAnnotation) (KitGenSpecification, error)

func (KitGenSpecification) ContainsDuplicateEndpointName

func (spec KitGenSpecification) ContainsDuplicateEndpointName() error

func (KitGenSpecification) IsValid

func (spec KitGenSpecification) IsValid() error

Checks if a given specification is valid. A specification is not valid if one of the following conditions is not satisfied:

• there cannot be two endpoints with the same name
• any interface method (for which at least one endpoint is defined) must have a context.Context value as first parameter
• any interface method (for which at least one endpoint is defined) must have at most two return values and last return value must be of type error
• if http code is generated, endpoints should have http method, path and success code set

type KitGenerator

type KitGenerator struct {
	Spec KitGenSpecification
	// contains filtered or unexported fields
}

func NewKitGenerator

func NewKitGenerator(spec KitGenSpecification) *KitGenerator

func (*KitGenerator) Generate

func (g *KitGenerator) Generate() (result []gen.GenResult, err error)