api

type ArgumentScanner ¶

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

ArgumentScanner can scan arguments via a formatting pattern. Either %v, %[n]v or FieldName

func NewArgumentScanner(args []reflect.Value) ArgumentScanner

func (scanner *ArgumentScanner) Scan(format string) (reflect.Value, error)

type Auth ¶

type Auth[Conn any] interface {
	// AssertHeader is called before the request is processed it
	// should confirm the identify of the caller. The context
	// returned will be passed to the function being called.
	Authenticate(Conn, Function) (context.Context, error)

	// AssertAccess is called after arguments have been passed
	// and before the function is called. It should assert that
	// the identified caller is allowed to access the function.
	Authorize(Conn, Function, []reflect.Value) error

	// Redact is called on any errors raised by the function, it
	// can be used to log and/or report this error, or to redact
	// any sensitive information from the error before it is
	// returned to the caller.
	Redact(context.Context, error) error
}

Auth returns an error if the given Conn is not allowed to access the given function. Used to implement authentication and authorisation for API calls.

type Error ¶

type Error[T any] struct {
	// contains filtered or unexported fields
}

Error can be used to specify an enumerated set of error values that can be returned by an API endpoint. It behaves like a xyz.Switch that implements [error].

func (e Error) Error() string

type Exporter ¶

type Exporter[Host any, Options any] interface {
	Export(Structure, Options) (Host, error)
}

Exporter that can export a runtime.link API structure using the specified 'Options' configuration.

type Function ¶

type Function struct {
	Name string
	Docs string
	Tags reflect.StructTag
	Type reflect.Type

	Root Structure // root structure this function belongs to.
	Path []string  // namespace path from root to reach this function.
	// contains filtered or unexported fields
}

Function is a runtime reflection representation of a runtime.link function.

func (fn Function) Call(ctx context.Context, args []reflect.Value) ([]reflect.Value, error)

func (fn Function) Copy() Function

func (fn Function) In(i int) reflect.Type

func (fn Function) Is(ptr any) bool

func (fn Function) Make(impl any)

func (fn Function) MakeError(err error)

func (fn Function) NumIn() int

func (fn Function) NumOut() int

func (fn Function) Return(results []reflect.Value, err error) []reflect.Value

type Host ¶

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

Host used to document host tags that identify the location of the link layer's target.

type Linker ¶

type Linker[Host any, Conn any] interface {
	Link(Structure, Host, Conn) error
}

Linker that can link a runtime.link API structure up to a 'Host' implementation using the specified 'Connection' configuration.

type Register ¶

type Register[I any, V any] struct{}

Register an implementation of an interface, if I is an [error] and V is an Error-type then each nested error value will be registered as a scenario, else V will be documented as a possible instance of I.

type Scenario ¶

type Scenario struct {
	Name string
	Kind string
	Text string
	Tags reflect.StructTag
	Test func(error) bool
}

Scenario documents an out-of-band signal supported by the API that requires actioning by the client, this could be an error, a redirection or a status.

type Specification ¶

type Specification struct{}

Specification should be embedded in all runtime.link API structures.

type Structure ¶

type Structure struct {
	Name string
	Docs string
	Tags reflect.StructTag

	Host reflect.StructTag // host tag determined by GOOS.

	// Functions or endpoints of the API, that can be called.
	Functions []Function

	// Scenarios documents out-of-band signals that can be returned
	// by the API, these are typically errors, redirections or
	// status codes.
	Scenarios []Scenario

	// Namespace enables structures to be nested.
	Namespace map[string]Structure

	// Instances map interface types, to a list of fields that
	// have been registered as implementations of that interface.
	Instances map[reflect.Type][]reflect.StructField
}

Structure is the runtime reflection representation for a runtime.link API structure. In Go source, these are represented using Go structs with at least one function field. These runtime.link API structures can be be nested in order to organise functions into sensible namespaces.

For example:

type Example struct {
	HelloWorld func() string `tag:"value"
		returns "Hello World"`

	Math struct {
		Add func(a, b int) int `tag:"value"
			returns a + b`
	}
}

Each function field can have struct tags that specify how a particular link layer should link to, or host the function. The tags can contain any number of newlines, each subsequent line after the first will be treated as documentation for the function (tabs are stripped from each line).

func StructureOf(val any) Structure

func (s Structure) MakeError(err error)