sherpa

README

Sherpa

Sherpa is a Go library for creating a sherpa API.

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

Your API will automatically be documented: github.com/mjl-/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.

todo

• add a toggle for enabling calls by GET request. turn off by default for functions with parameters, people might be making requests with sensitive information in query strings...
• include a sherpaweb-like page that displays the documentation
• consider adding input & output validation and timestamp conversion to plain js lib
• consider using interfaces with functions (instead of direct structs) for server implementations. haven't needed it yet, but could be useful for mocking an api that you want to talk to.
• think about way to keep unknown fields. perhaps use a json lib that collects unknown keys in a map (which has to be added to the object for which you want to keep such keys).
• sherpajs: make a versionied, minified variant, with license line
• tool for comparing two jsons for compatibility, listing added sections/functions/types/fields
• be more helpful around errors that functions can generate. perhaps adding a mechanism for listing which errors can occur in the api json.
• handler: write tests
• client: write tests

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://github.com/mjl-/sherpaweb/

Index

• Constants
• func NewHandler(path string, version string, api interface{}, doc *sherpadoc.Section, ...) (http.Handler, error)
• type Collector
• type Error
  • func (e *Error) Error() string
• type HandlerOpts
• type Int64s
  • func (i Int64s) Int() int64
  • func (i *Int64s) MarshalJSON() ([]byte, error)
  • func (i *Int64s) UnmarshalJSON(buf []byte) error
• type InternalServerError
  • func (e *InternalServerError) Error() string
• type JSON
• type Raw
• type Uint64s
  • func (i Uint64s) Int() uint64
  • func (i *Uint64s) MarshalJSON() ([]byte, error)
  • func (i *Uint64s) UnmarshalJSON(buf []byte) error

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 = 1

SherpaVersion is the version of the Sherpa protocol this package implements. Sherpa is at version 1.

Functions

func NewHandler

func NewHandler(path string, version string, api interface{}, doc *sherpadoc.Section, 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 by default (but see HandlerOpts.AdjustFunctionNames).

Doc is documentation for the top-level sherpa section, 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.

	// Call of function, how long it took, and in case of failure, the error code.
	FunctionCall(name string, durationSec float64, errorCode string)
}

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 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 HandlerOpts

type HandlerOpts struct {
	// Holds functions for collecting metrics about function calls and other incoming
	// HTTP requests. May be nil.
	Collector Collector

	// If enabled, incoming sherpa function calls will ignore unrecognized fields in
	// struct parameters, instead of failing.
	LaxParameterParsing bool

	// If empty, only the first character of function names are lower cased. For
	// "lowerWord", the first string of capitals is lowercased, for "none", the
	// function name is left as is.
	AdjustFunctionNames string

	// Don't send any CORS headers, and respond to OPTIONS requests with 405 "bad
	// method".
	NoCORS bool
}

HandlerOpts are options for creating a new handler.

type Int64s

type Int64s int64

Int64s is an int64 that can be read as either a JSON string or JSON number, to be used in sherpa function parameters for compatibility with JavaScript. For struct fields, use the "json:,string" struct tag instead.

func (Int64s) Int

func (i Int64s) Int() int64

Int returns the int64 value.

func (*Int64s) MarshalJSON

func (i *Int64s) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON-string-encoding of the int64.

func (*Int64s) UnmarshalJSON

func (i *Int64s) UnmarshalJSON(buf []byte) error

UnmarshalJSON parses JSON into the int64. Both a string encoding as a number encoding are allowed. JavaScript clients must use the string encoding because the number encoding loses precision at 1<<53.

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"`
	SherpadocVersion int      `json:"sherpadocVersion"`
}

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

type Raw

type Raw []byte

Raw signals a raw JSON response. If a handler panics with this type, the raw bytes are sent (with regular response headers). Can be used to skip the json encoding from the handler, eg for caching, or when you read a properly formatted JSON document from a file or database. By using panic to signal a raw JSON response, the return types stay intact for sherpadoc to generate documentation from.

type Uint64s

type Uint64s uint64

Uint64s is an uint64 that can be read as either a JSON string or JSON number, to be used in sherpa function parameters for compatibility with JavaScript. For struct fields, use the "json:,string" struct tag instead.

func (Uint64s) Int

func (i Uint64s) Int() uint64

Int returns the uint64 value.

func (*Uint64s) MarshalJSON

func (i *Uint64s) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON-string-encoding of the uint64.

func (*Uint64s) UnmarshalJSON

func (i *Uint64s) UnmarshalJSON(buf []byte) error

UnmarshalJSON parses JSON into the uint64. Both a string encoding as a number encoding are allowed. JavaScript clients must use the string encoding because the number encoding loses precision at 1<<53.