sherpa

README

Sherpa

Sherpa is a Go library for creating a sherpa API.

This library makes it trivial to export Go functions as a sherap API with an http.Handler.

Your API will automatically be documented: cmd/sherpadoc reads your Go source, and exports function and type comments as API documentation.

See the documentation.

Examples

A public sherpa API: https://www.sherpadoc.org/#https://www.sherpadoc.org/example/

That web application is sherpaweb. It shows documentation for any sherpa API but also includes an API called Example for demo purposes.

Ding is a more elaborate web application built with this library.

About

Written by Mechiel Lukkien, mechiel@ueber.net. Bug fixes, patches, comments are welcome. MIT-licensed, see LICENSE. cmd/sherpadoc/gopath.go originates from the Go project, see LICENSE-go for its BSD-style license.

todo

• finish the type information. perhaps add more specific types (int64, int32, and unsigned variants, instead of just "int").

• better error messages in sherpadoc

• handler: write tests

• sherpadoc: write tests

• client: write tests

• sherpadoc: find out which go constructs people want to use that aren't yet implemented by sherpadoc

• when reading types from other packages (imported packages), we only look at GOPATH. vendor and modules are not taking into account, but we should.

Documentation

Overview

Package sherpa exports your Go functions as fully documented sherpa web API's.

Sherpa is similar to JSON-RPC, but discoverable and self-documenting. Read more at https://www.ueber.net/who/mjl/sherpa/.

Use sherpa.NewHandler to export Go functions using a http.Handler. An example of how to use NewHandler can be found in https://bitbucket.org/mjl/sherpaweb/

Index

• Constants
• func NewHandler(path string, version string, api interface{}, doc *Doc, opts *HandlerOpts) (http.Handler, error)
• type Collector
• type Doc
• type Error
  • func (e *Error) Error() string
• type FieldDoc
• type FunctionDoc
• type HandlerOpts
• type InternalServerError
  • func (e *InternalServerError) Error() string
• type JSON
• type Param
• type TypeDoc

Constants

const (
	SherpaBadResponse = "sherpa:badResponse" // Bad response from server, e.g. JSON response body could not be parsed.
	SherpaHTTPError   = "sherpa:http"        // Unexpected http response status code from server.
	SherpaNoAPI       = "sherpa:noAPI"       //  No API was found at this URL.
)

Errors generated by clients

const (
	SherpaBadRequest = "sherpa:badRequest" // Error parsing JSON request body.
	SherpaBadParams  = "sherpa:badParams"  // Wrong number of parameters in function call.
)

Errors generated by servers

const (
	SherpaBadFunction = "sherpa:badFunction" // Function does not exist at server.
)

Errors generated by both clients and servers

const SherpaVersion = 0

SherpaVersion is the version of the Sherpa protocol this package implements. Sherpa is at version 0, still in development and may change.

Functions

func NewHandler

func NewHandler(path string, version string, api interface{}, doc *Doc, opts *HandlerOpts) (http.Handler, error)

NewHandler returns a new http.Handler that serves all Sherpa API-related requests.

Path is the path this API is available at.

Version should be a semantic version.

API should by a struct. It represents the root section. All methods of a section are exported as sherpa functions. All fields must be other sections (structs) whose methods are also exported. recursively. Method names must start with an uppercase character to be exported, but their exported names start with a lowercase character.

Doc is sherpa documentation as generated by sherpadoc.

Opts allows further configuration of the handler.

Methods on the exported sections are exported as Sherpa functions. If the first parameter of a method is a context.Context, the context from the HTTP request is passed. This lets you abort work if the HTTP request underlying the function call disappears.

Parameters and return values for exported functions are automatically converted from/to JSON. If the last element of a return value (if any) is an error, that error field is taken to indicate whether the call succeeded. Exported functions can also panic with an *Error or *InternalServerError to indicate a failed function call. Returning an error with a Code starting with "server" indicates an implementation error, which will be logged through the collector.

Variadic functions can be called, but in the call (from the client), the variadic parameters must be passed in as an array.

This handler strips "path" from the request.

Types

type Collector

type Collector interface {
	ProtocolError() // Invalid request at protocol-level, e.g. wrong mimetype or request body.
	BadFunction()   // Function does not exist.
	JavaScript()    // Sherpa.js is requested.
	JSON()          // Sherpa.json is requested.

	// Function "name" is called, and whether that caused an
	// "error" at all, and a "serverError" in particular, and how
	// long the call took.
	FunctionCall(name string, error bool, serverError bool, durationSec float64)
}

Collector facilitates collection of metrics. Functions are called by the library as such events or errors occur. See https://github.com/irias/sherpa-prometheus-collector for an implementation for prometheus.

type Doc

type Doc struct {
	Title     string         `json:"title"`     // Name of an API section.
	Text      string         `json:"text"`      // Explanation of the API in markdown.
	Functions []*FunctionDoc `json:"functions"` // Documentation for each function exported in this API.
	Sections  []*Doc         `json:"sections"`  // Subsections, each with their own documentation.
	Types     []TypeDoc      `json:"types"`     // Types used in section or multiple subsections.

	// Version of sherpadoc format. The first version did not
	// have this field. Version 1 is the first sherpadoc with a
	// version field. Version 1 is the first with type information.
	// Only the top-level section should have a version. If
	// subsections have versions, they must be ignored.
	Version int `json:"version,omitempty"`
}

Doc represents documentation about a Sherpa API, as returned by the "_docs" function.

type Error

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

Error returned by a function called through a sherpa API. Message is a human-readable error message. Code is optional, it can be used to handle errors programmatically.

func (*Error) Error

func (e *Error) Error() string

type FieldDoc

type FieldDoc struct {
	Name string   `json:"name"`
	Type []string `json:"type"`
	Text string   `json:"text"`
}

FieldDoc is a single field of a compound type. The type can reference another named type.

type FunctionDoc

type FunctionDoc struct {
	Name   string  `json:"name"` // Name of the function.
	Text   string  `json:"text"` // Markdown, describing the function, its parameters, return types and possible errors.
	Params []Param `json:"params"`
	Return []Param `json:"return"`
}

FunctionDoc contains the documentation for a single function. Text should be in markdown. The first line should be a synopsis showing parameters including types, and the return types.

type HandlerOpts

type HandlerOpts struct {
	Collector           Collector // Holds functions for collecting metrics about function calls and other incoming HTTP requests. May be nil.
	LaxParameterParsing bool      // If enabled, incoming sherpa function calls will ignore unrecognized fields in struct parameters, instead of failing.
}

HandlerOpts are options for creating a new handler.

type InternalServerError

type InternalServerError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

InternalServerError is an error that propagates as an HTTP internal server error (HTTP status 500), instead of returning a regular HTTP status 200 OK with the error message in the response body. Useful for making Sherpa endpoints that can be monitored by simple HTTP monitoring tools.

func (*InternalServerError) Error

func (e *InternalServerError) Error() string

type JSON

type JSON struct {
	ID            string   `json:"id"`
	Title         string   `json:"title"`
	Functions     []string `json:"functions"`
	BaseURL       string   `json:"baseurl"`
	Version       string   `json:"version"`
	SherpaVersion int      `json:"sherpaVersion"`
}

JSON holds all fields for a request to sherpa.json.

type Param

type Param struct {
	Name string   `json:"name"`
	Type []string `json:"type"`
}

Param is the name and type of a function parameter or return value. Param is the name and type of a function parameter or return value. Type is an array of tokens describing the type. Production rules:

basictype := "boolean" | "int" | "float" | "string"
array := "[]"
map := "{}"
identifier := [a-zA-Z][a-zA-Z0-9]*
type := "nullable"? ("any" | basictype | identifier | array type | map type)

It is not possible to have inline structs in parameters. Those must be encoded as a named type.

type TypeDoc

type TypeDoc struct {
	Name   string     `json:"name"`
	Fields []FieldDoc `json:"fields"`
	Text   string     `json:"text"`
}

TypeDoc is used as parameter or return value.