sherpa: bitbucket.org/mjl/sherpa Index | Files | Directories

package sherpa

import "bitbucket.org/mjl/sherpa"

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

Package Files

codes.go collector.go doc.go docs.go handler.go isclosed.go sherpajs.go

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.

func NewHandler Uses

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.

type Collector Uses

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 Uses

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 Uses

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 Uses

func (e *Error) Error() string

type FieldDoc Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (e *InternalServerError) Error() string

type JSON Uses

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 Uses

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 Uses

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

TypeDoc is used as parameter or return value.

Directories

PathSynopsis
client
cmd/sherpaclientSherpaclient calls Sherpa API functions and prints Sherpa API documentation from the command-line.
cmd/sherpadocSherpadoc parses Go code and outputs sherpa documentation in JSON.

Package sherpa imports 14 packages (graph) and is imported by 7 packages. Updated 2019-02-15. Refresh now. Tools for package owners.