npoint

Overview ¶

Package npoint is a general purpose lightweight non-opinionated web server framework that provides a concise way to handle errors and inject dependencies into http endpoint handlers.

Why ¶

Composite endpoints: endpoints are assembled from a collection of handlers.

Before/after actions: the middleware handler type wraps the rest of the handler chain so that it can both inject items that are used downstream and process return values.

Dependency injection: injectors, static injectors, and fallible injectors can all be used to provide data and code to downstream handlers. Downstream handlers request what they need by including appropriate types in their argument lists. Injectors are invoked only if their outputs are consumed.

Code juxtaposition: when using pre-registered services, endpoint binding can be registered next to the code that implements the endpoint even if the endpoints are implemented in multiple files and/or packages.

Delayed initialization: initializers for pre-registered services are only executed when the service is started and bound to an http server. This allow code to define such endpoints to depend on resources that may not be present unless the service is started.

Reduced refactoring cost: handlers and endpoints declare their inputs and outputs in the argument lists and return lists. Handlers only need to know about their own inputs and outputs. The endpoint framework carries the data to where it is needed. It does so with a minimum of copies and without recursive searches (see context.Context). Type checking is done at service start time (or endpoint binding time when binding to services that are already running).

Lower overhead indirect passing: when using context.Context to pass values indirectly, the Go type system cannot be used to verify types at compile time or startup time. Endpoint verifies types at startup time allowing code that receives indirectly-passed data simpler. As much as possible, work is done at initialization time rather than endpoint invocation time.

Basics ¶

To use the npoint package, create services first. After that the endpoints can be registered to the service and the service can be started.

A simpler way to use endpoint is to use the CreateEndpoint function. It converts a list of handlers into an http.HandlerFunc. This bypasses service creation and endpoint registration. See https://github.com/muir/npoint/blob/master/README.md for an example.

Terminology ¶

Service is a collection of endpoints that can be started together and may share a handler collection.

Handler is a function that is used to help define an endpoint.

Handler collection is a group of handlers.

Downstream handlers are handlers that are to the right of the current handler in the list of handlers. They will be invoked after the current handler.

Upstream handlers are handlers that are to the left of the current handler in the list of handlers. They will have already been invoked by the time the current handler is invoked.

Services ¶

A service allows a group of related endpoints to be started together. Each service may have a set of common handlers that are shared among all the endpoints registered with that service.

Services come in four flavors: started or pre-registered; with Mux or with without.

Pre-registered services are not initialized until they are Start()ed. This allows them to depend upon resources that may not may not be available without causing a startup panic unless they're started without their required resources. It also allows endpoints to be registered in init() functions next to the definition of the endpoint.

Handlers ¶

The handlers are defined using the nject framework: See https://github.com/muir/nject/blob/master/README.md

A list of handlers will be invoked from left-to-right. The first handler in the list is invoked first and the last one (the endpoint) is invoked last. The handlers do not directly call each other -- rather the framework manages the invocations. Data provided by one handler can be used by any handler to its right and then as the handlers return, the data returned can be used by any handler to its left. The data provided and required is identified by its type. Since Go makes it easy to make aliases of types, it is easy to make types distinct. When there is not an exact match of types, the framework will use the closest (in distance) value that can convert to the required type.

Each handler function is distinguished by its position in the handler list and by its primary signature: its arguments and return values. In Go, types may be named or unnamed. Unnamed function types are part of primary signature. Named function types are not part of the primary signature.

These are the types that are recognized as valid handlers: Static Injectors, Injectors, Endpoints, and Middleware.

Injectors are only invoked if their output is consumed or they have no output. Middleware handlers are (currently) always invoked.

Injectors ¶

There are three kinds of injectors: static injectors, injectors, and fallible injectors.

Injectors and static injectors have the following type signature:

func(input value(s)) output values(s)

None of the input or output parameters may be un-named functions. That describes nearly every function in Go. Handlers that match a more specific type signature are that type, rather than being an injector or static injector.

Injectors whose output values are not used by a downstream handler are dropped from the handler chain. They are not invoked. Injectors that have no output values are a special case and they are always retained in the handler chain.

Static injectors are called exactly once per endpoint. They are called when the endpoint is started or when the endpoint is registered -- whichever comes last.

Values returned by static injectors will be shared by all invocations of the endpoint.

Injectors are called once per endpoint invocation (or more if they are downstream from a middleware handler that calls inner() more than once).

Injectors a distingued from static injectors by either their position in the handler list or by the parameters that they take. If they take http.ResponseWriter or *http.Request, then they're not static. Anything that is downstream of a non-static injector or middleware handler is also not static.

Fallible injectors are injectors whose first return values is of type nject.TerminalError:

func(input value(s)) (nject.TerminalError, output values(s))

If a non-nil value is returned as the nject.TerminalError from a fallible injector, none of the downstream handlers will be called. The handler chain returns from that point with the nject.TerminalError as a return value. Since all return values must be consumed by a middleware handler, fallible injectors must come downstream from a middleware handler that takes nject.TerminalError as a returned value. If a fallible injector returns nil for the nject.TerminalError, the other output values are made available for downstream handlers to consume. The other output values are not considered return values and are not available to be consumed by upstream middleware handlers.

Some examples:

func staticInjector(i int, s string) int { return i+7 }

func injector(r *http.Request) string { return r.FormValue("x") }

func fallibleInjector(i int) nject.TerminalError {
	if i > 10 {
		return fmt.Errorf("limit exceeded")
	}
	return nil
}

Middleware handlers ¶

Middleware handlers wrap the handlers downstream in a inner() function that they may call. The type signature of a middleware handler is a function that receives an function as its first parameter. That function must be of an anonymous type:

// middleware handler
func(innerfunc, input value(s)) return value(s)

// innerfunc
func(output value(s)) returned value(s)

For example:

func middleware(inner func(string) int, i int) int {
	j := inner(fmt.Sprintf("%d", i)
	return j * 2
}

When this middleware function runs, it is responsible for invoking the rest of the handler chain. It does this by calling inner(). The parameters to inner are available as inputs to downstream handlers. The value(s) returned by inner come from the return values of downstream middleware handlers and the endpoint handler.

Middleware handlers can call inner() zero or more times.

The values returned by middleware handlers must be consumed by another upstream middlware handler.

Endpoint Handlers ¶

Endpoint handlers are simply the last handler in the handler chain. They look like regular Go functions. Their input parameters come from other handlers. Their return values (if any) must be consumed by an upstream middleware handler.

func(input value(s)) return values(s)

Panics ¶

Endpoint will panic during endpoint registration if the provided handlers do not constitute a valid chain. For example, if a some handler requires a FooType but there is no upstream handler that provides a FooType then the handler list is invalid and endpoint will panic.

Endpoint should not panic after initialization.