Documentation

Index

Constants

View Source
const (
	// DefaultBackend is the value given when a particular route is not part
	// of a known, named backend.
	DefaultBackend = "default"
)
View Source
const (
	// ExtensionKey is used to identify OpenAPI extension blocks
	// that are relevant to this project.
	ExtensionKey = "x-transportd"
)
View Source
const (
	// RuntimeExtensionKey is used to identify the runtime configuration
	// extension block at the top level of an OpenAPI specification.
	RuntimeExtensionKey = "x-runtime"
)

Variables

View Source
var (
	// ContextKeyOpenAPISpec is a key used for placing the raw openapi3.Swagger object
	// pointer into the context.  If it is needed in a component that defines a transportd
	// plugin, the object can be retrieved from the context passed to the "New" function by:
	// ctx.Value(transportd.ContextKeyOpenAPISpec).(*openapi3.Swagger)
	ContextKeyOpenAPISpec = contextKey("OpenAPISpec")
)

Functions

func EnforceRelativeLocation

func EnforceRelativeLocation(resp *http.Response) error

    EnforceRelativeLocation prevents redirection from the backend as the result of 3xx codes from improperly redirecting clients around the proxy. This is related to https://github.com/golang/go/issues/14237.

    func ErrorToStatusCode

    func ErrorToStatusCode(err error) int

      ErrorToStatusCode There can be many reasons why we couldn't get a proper response from the upstream server. This includes timeouts, inability to connect, or the client canceling a request. This cannot all be captured with one status code. This method will convert golang errors to descriptive status codes. context.Canceled: Something likely happened on the client side that canceled the request (such as a timeout), return 499 context.DeadlineExceeded: Likely a timeout here in the proxy, return 504 Default: 502

      func Help

      func Help(ctx context.Context, components ...NewComponent) (string, error)

        Help outputs a formatted string to help with discovering available settings and options.

        func New

        func New(ctx context.Context, specification []byte, components ...NewComponent) (*runhttp.Runtime, error)

          New generates a configured HTTP runtime. To use as a library, call the NewTransport method instead.

          func NewRuntime

          func NewRuntime(ctx context.Context, s settings.Source, h http.Handler) (*runhttp.Runtime, error)

            NewRuntime generates a runhttp.Runtime instance that will host the given handler. This method is used to handle the top-level x-runtime block.

            func NewTransport

            func NewTransport(ctx context.Context, specification []byte, components ...NewComponent) (http.RoundTripper, error)

              NewTransport constructs a smart HTTP client from the given specification and set of plugins. For running a service, use the New method instead.

              func PathParamsFromContext

              func PathParamsFromContext(ctx context.Context) map[string]string

                PathParamsFromContext fetches the matching URL params.

                func PathParamsToContext

                func PathParamsToContext(ctx context.Context, params map[string]string) context.Context

                  PathParamsToContext inserts the matching URL params.

                  func RouteFromContext

                  func RouteFromContext(ctx context.Context) *openapi3filter.Route

                    RouteFromContext fetches the active OpenAPI route.

                    func RouteToContext

                    func RouteToContext(ctx context.Context, route *openapi3filter.Route) context.Context

                      RouteToContext inserts the active OpenAPI route.

                      func RuntimeSourceFromExtension

                      func RuntimeSourceFromExtension(s []byte) (settings.Source, error)

                        RuntimeSourceFromExtension is a one-off change from the SourceFromExtension method that handles the runhttp configuration block. This is needed because the runhttp component has a predefined root of "runtime" that we need to adapt the source to match.

                        func SourceFromExtension

                        func SourceFromExtension(s []byte) (settings.Source, error)

                          SourceFromExtension generates a settings.Source from any given OpenAPI extension block. The resulting Source tree has a root that matches the ExtensionKey.

                          Types

                          type Backend

                          type Backend interface {
                          	http.RoundTripper
                          	Host() *url.URL
                          	Count() int
                          	TTL() time.Duration
                          }

                            Backend is an extension of http.RoundTripper that give access to relevant features such as the host rewrite data or the connection TTL.

                            type BackendRegistry

                            type BackendRegistry interface {
                            	Load(ctx context.Context, backend string) Backend
                            	Store(ctx context.Context, backend string, rt Backend)
                            }

                              BackendRegistry manages a set of base http.RoundTripper implementations that are composed with other tools in order to create clients.

                              func NewBaseTransports

                              func NewBaseTransports(ctx context.Context, s settings.Source) (BackendRegistry, error)

                                NewBaseTransports generates a mapping of backend names to http.RoundTripper instances. This method is used to handle the top-level x-transportd block and configure a set of base http.RoundTripper instances with some core connection pooling settings applied.

                                type ClientFactory

                                type ClientFactory struct {
                                	Bases      BackendRegistry
                                	Components []NewComponent
                                }

                                  ClientFactory exposes a Client constructor method that is bound to a given sregistry and set of plugin components.

                                  func (*ClientFactory) New

                                  func (f *ClientFactory) New(ctx context.Context, s settings.Source, path string, method string) (http.RoundTripper, error)

                                    New generates a decorated http.RoundTripper for the given path and method. This method is used to handle the per-operation x-transportd blocks.

                                    type ClientRegistry

                                    type ClientRegistry interface {
                                    	Load(ctx context.Context, path string, method string) http.RoundTripper
                                    	Store(ctx context.Context, path string, method string, rt http.RoundTripper)
                                    }

                                      ClientRegistry manages a set of configured http.RoundTripper implementations that will be used to make requests.

                                      type ClientTransport

                                      type ClientTransport struct {
                                      	Registry ClientRegistry
                                      	Router   *openapi3filter.Router
                                      }

                                        ClientTransport maps incoming requests to a configured client.

                                        func (*ClientTransport) RoundTrip

                                        func (r *ClientTransport) RoundTrip(req *http.Request) (*http.Response, error)

                                          RoundTrip performs a client lookup and uses the result to execute the request.

                                          If a client is not found then a NotFound response it returned unless there is a route for the path "unknown" and the method "unknown".

                                          If a client is found then the Route is injected into the request context for later use.

                                          type EnvProcessor

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

                                            EnvProcessor transforms documents by interpolating environment variables.

                                            func NewEnvProcessor

                                            func NewEnvProcessor() *EnvProcessor

                                              NewEnvProcessor prepares the EnvProcessor and returns it.

                                              func (*EnvProcessor) Process

                                              func (y *EnvProcessor) Process(source []byte) ([]byte, error)

                                                Process replaces ${} values with values from the environment.

                                                type HTTPError

                                                type HTTPError struct {
                                                	// Code is the HTTP status code.
                                                	Code int `json:"code"`
                                                	// Status is the HTTP status string.
                                                	Status string `json:"status"`
                                                	// Reason is the debug data.
                                                	Reason string `json:"reason"`
                                                }

                                                  HTTPError is the canonical shape for all internally generated HTTP error responses. All components should emit this shape, with an application/json content type, any time the component would return an internally crafted response. External developers are encouraged to embed this code in your project rather than importing it to avoid an unnecessary reference.

                                                  The purpose of standardizing on this structure is to enable users of this project to add a default response schema for output validation. For the same reasons, we recommend that projects behind this proxy also use this structure for errors.

                                                  type MultiResponseModifier

                                                  type MultiResponseModifier []func(*http.Response) error

                                                    MultiResponseModifier enables composition of ModifyResponse functions.

                                                    func (MultiResponseModifier) ModifyResponse

                                                    func (mrs MultiResponseModifier) ModifyResponse(resp *http.Response) error

                                                      ModifyResponse satisfies the signature of the same name in the ReverseProxy.

                                                      type NewComponent

                                                      type NewComponent func(ctx context.Context, backend string, path string, method string) (interface{}, error)

                                                        NewComponent is the signature all component plugins must implement. It is a constructor function that will be given the current backend and path for which the system is generating the component. The resulting value must implement the Component interface from the 'settings' project.

                                                        type StaticBackendRegistry

                                                        type StaticBackendRegistry struct {
                                                        	Transports map[string]Backend
                                                        }

                                                          StaticBackendRegistry is an implementation of BackendRegistry that operates on a static mapping. This implementation exists, largely, in order to control for case insensitivity in the map.

                                                          func NewStaticBackendRegistry

                                                          func NewStaticBackendRegistry() *StaticBackendRegistry

                                                            NewStaticBackendRegistry initializes a StaticBackendRegistry.

                                                            func (*StaticBackendRegistry) Load

                                                            func (r *StaticBackendRegistry) Load(_ context.Context, backend string) Backend

                                                              Load the transport base for a backend. Result may be nil if unset.

                                                              func (*StaticBackendRegistry) Store

                                                              func (r *StaticBackendRegistry) Store(_ context.Context, backend string, rt Backend)

                                                                Store a base transport for a backend.

                                                                type StaticClientRegistry

                                                                type StaticClientRegistry struct {
                                                                	Transports map[string]map[string]http.RoundTripper
                                                                }

                                                                  StaticClientRegistry is an implementation of ClientRegisty that operates on a static mapping. This exists, largely, to protect consumers from case insensitivity issues.

                                                                  func NewStaticClientRegistry

                                                                  func NewStaticClientRegistry() *StaticClientRegistry

                                                                    NewStaticClientRegistry intializes the StaticClientRegistry.

                                                                    func (*StaticClientRegistry) Load

                                                                      Load a client for the path and method. The result may be nil if a client was never stored.

                                                                      func (*StaticClientRegistry) Store

                                                                      func (r *StaticClientRegistry) Store(_ context.Context, path string, method string, rt http.RoundTripper)

                                                                        Store a client for the path and method.

                                                                        Directories

                                                                        Path Synopsis