relay

Documentation

Overview

Package relay contains the Relay application component that combines all of the internal components and implements HTTP endpoints.

This package is not in internal/ so that the exported Relay type can be used by external code to embed Relay functionality into a customized application. See docs/in-app.md.

Index

• func IsNotReady(err error) bool
• func IsPayloadFilterNotFound(err error) bool
• func IsUnrecognizedEnvironment(err error) bool
• type ClientFactoryFunc
• type EnvironmentLookup
  • func NewEnvironmentLookup() *EnvironmentLookup
  • func (e *EnvironmentLookup) DeleteEnvironment(params sdkauth.ScopedCredential) (relayenv.EnvContext, bool)
  • func (e *EnvironmentLookup) Environments() (envs []relayenv.EnvContext)
  • func (e *EnvironmentLookup) InsertEnvironment(env relayenv.EnvContext)
  • func (e *EnvironmentLookup) Lookup(params sdkauth.ScopedCredential) (relayenv.EnvContext, bool)
  • func (e *EnvironmentLookup) MapRequestParams(params sdkauth.ScopedCredential, env relayenv.EnvContext)
  • func (e *EnvironmentLookup) UnmapRequestParams(params sdkauth.ScopedCredential)
• type Relay
  • func NewRelay(c config.Config, loggers ldlog.Loggers, clientFactory ClientFactoryFunc) (*Relay, error)
  • func (r *Relay) Close() error

Functions

func IsNotReady

func IsNotReady(err error) bool

func IsPayloadFilterNotFound

func IsPayloadFilterNotFound(err error) bool

func IsUnrecognizedEnvironment

func IsUnrecognizedEnvironment(err error) bool

Types

type ClientFactoryFunc

type ClientFactoryFunc func(sdkKey config.SDKKey, config ld.Config) (*ld.LDClient, error)

ClientFactoryFunc is a function that can be used with NewRelay to specify custom behavior when Relay needs to create a Go SDK client instance.

type EnvironmentLookup

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

EnvironmentLookup is responsible for maintaining a mapping between incoming requests from SDKs, and outbound connections to LaunchDarkly.

Complexity is present for two reasons:

1. A configured LaunchDarkly connection can be authenticated in one or more ways: SDK key, mobile key, client-side environment ID. This component must be able to accept any of these credentials and find the correct environment.
2. Payload filtering results in extra bookkeeping: if a payload filter is specified for a project, then Relay must maintain individual streaming connections for each variant of environments within that project (unfiltered, filter X, filter Y...). These environments share all the same credentials and most of the configuration, but are fundamentally different due to the filter key tacked onto the request URL.

Because of these two issues, the lookup is based on a composite key: the combination of a credential and a filter. If there is no filter, then the filter component is an empty string.

As an example, assume two environments are configured (envA and envB). Both are authenticated with an SDK key, mobile key, and environment ID.

The map has 6 entries:

#1 {envA SDK key, ""}    ----v
#2 {envA mobile key, ""} --> envA[filter=""]
#3 {envA env-ID, ""}     ----^

#4 {envB SDK key, ""}    ----v
#5 {envB mobile key, ""} --> envB[filter=""]
#6 {envB env-ID, ""}     ----^

Assume both environments belong to the same project, and then a filter "foo" is added to this project. Here's a diff, for a total of 12 entries:

+#7 {envA SDK key, "foo"}     ----v
+#8 {envA mobile key, "foo"}  --> envA[filter="foo"]
+#9 {envA env ID, "foo"}      ----^

+#10 {envB SDK key, "foo"}    ----v
+#11 {envB mobile key, "foo"} --> envB[filter="foo"]
+#12 {envB env-ID, "foo"}     ----^

The relationship between envA[filter=""] and envA[filter="foo"] is that both environments share the exact same credentials, but the objects themselves represent distinct connections.

As shown, given N environments in a project, and M filters for that project, then N*(M+1) environment connections are maintained: N=2, M=1, count = 2*(1+1) = 4.

func NewEnvironmentLookup

func NewEnvironmentLookup() *EnvironmentLookup

NewEnvironmentLookup instantiates an empty instance of EnvironmentLookup. Calls into EnvironmentLookup are thread safe.

func (*EnvironmentLookup) DeleteEnvironment

func (e *EnvironmentLookup) DeleteEnvironment(params sdkauth.ScopedCredential) (relayenv.EnvContext, bool)

DeleteEnvironment searches for an environment identified by the client request params, deletes it, and then removes all other credential mappings. If an environment was deleted, returns true; otherwise, returns false and the first value is undefined.

func (*EnvironmentLookup) Environments

func (e *EnvironmentLookup) Environments() (envs []relayenv.EnvContext)

Environments returns a list of all managed environment connections. Environments are only removed by DeleteEnvironment/DeleteEnvironment; removing credential mappings do not affect the environment itself.

func (*EnvironmentLookup) InsertEnvironment

func (e *EnvironmentLookup) InsertEnvironment(env relayenv.EnvContext)

InsertEnvironment creates a mapping from the given environment's credentials (and optional filter key) to that environment, which can later be looked up using Lookup. Only credentials that are defined are mapped (credential.Defined() must return true for each).

func (*EnvironmentLookup) Lookup

func (e *EnvironmentLookup) Lookup(params sdkauth.ScopedCredential) (relayenv.EnvContext, bool)

Lookup searches for a mapping from connection parameters to a suitable environment connection. If a connection is found, returns true; otherwise, returns false and the first value is undefined.

func (*EnvironmentLookup) MapRequestParams

func (e *EnvironmentLookup) MapRequestParams(params sdkauth.ScopedCredential, env relayenv.EnvContext)

MapRequestParams creates a mapping from connection parameters to an environment connection. It can be used if a new credential/filter is introduced which wasn't present when the environment was originally inserted using InsertEnvironment.

func (*EnvironmentLookup) UnmapRequestParams

func (e *EnvironmentLookup) UnmapRequestParams(params sdkauth.ScopedCredential)

UnmapRequestParams removes a mapping from connection parameters to an environment.

type Relay

type Relay struct {
	http.Handler
	// contains filtered or unexported fields
}

Relay represents the overall Relay Proxy application.

It can also be referenced externally in order to embed Relay Proxy functionality into a customized application; see docs/in-app.md.

This type deliberately exports no methods other than ServeHTTP and Close. Everything else is an implementation detail which is subject to change.

func NewRelay

func NewRelay(c config.Config, loggers ldlog.Loggers, clientFactory ClientFactoryFunc) (*Relay, error)

NewRelay creates a new Relay given a configuration and a method to create a client.

If any metrics exporters are enabled in c.MetricsConfig, it also registers those in OpenCensus.

The clientFactory parameter can be nil and is only needed if you want to customize how Relay creates the Go SDK client instance.

func (*Relay) Close

func (r *Relay) Close() error

Close shuts down components created by the Relay Proxy.

This includes dropping all connections to the LaunchDarkly services and to SDK clients, closing database connections if any, and stopping all Relay port listeners, goroutines, and OpenCensus exporters.