elephantine

package module
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2024 License: MIT Imports: 34 Imported by: 5

README

Elephantine

Go Reference

Shared functionality for Elephant systems. It's most likely not something anyone outside of Elephant would be interested in.

Documentation

Index

Constants

View Source 
const (
	// LogKeyLogLevel is the log level that an application was configured
	// with.
	LogKeyLogLevel = "log_level"
	// LogKeyError is an error message.
	LogKeyError = "err"
	// LogKeyErrorCode is an error code.
	LogKeyErrorCode = "err_code"
	// LogKeyErrorMeta is a JSON object with error metadata.
	LogKeyErrorMeta = "err_meta"
	// LogKeyCountMetric was planned to be used to increment a given metric
	// when used. TODO: not implemented yet, should it be removed?
	LogKeyCountMetric = "count_metric"
	// LogKeyDocumentUUID is the UUID of a document.
	LogKeyDocumentUUID = "document_uuid"
	// LogKeyDocumentVersion is the version of a document.
	LogKeyDocumentVersion = "document_version"
	// LogKeyDocumentStatus is the status of a document.
	LogKeyDocumentStatus = "document_status"
	// LogKeyDocumentStatus is the id of a document status.
	LogKeyDocumentStatusID = "document_status_id"
	// LogKeyTransaction is the name of a transaction, usually used to
	// identify a transaction that has failed.
	LogKeyTransaction = "transaction"
	// LogKeyOCSource is used to identify a source document from OC by UUID.
	LogKeyOCSource = "oc_source"
	// LogKeyOCVersion is the version of the OC document.
	LogKeyOCVersion = "oc_version"
	// LogKeyOCEvent is the type of an OC event- or content-log event.
	LogKeyOCEvent = "oc_event"
	// LogKeyChannel identifies a notification channel.
	LogKeyChannel = "channel"
	// LogKeyMessage can be used to log a unexpected message.
	LogKeyMessage = "message"
	// LogKeyDelay can be used to communicate the delay when logging
	// information about retry attempts and backoff delays.
	LogKeyDelay = "delay"
	// LogKeyBucket is used to log a S3 bucket name.
	LogKeyBucket = "bucket"
	// LogKeyObjectKey is used to log a S3 object key.
	LogKeyObjectKey = "object_key"
	// LogKeyComponent is used to communicate what application subcomponent
	// the log entry is from.
	LogKeyComponent = "component"
	// LogKeyCount is used to communicate a count.
	LogKeyCount = "count"
	// LogKeyEventID is the ID of an event.
	LogKeyEventID = "event_id"
	// LogKeyEventType is the type of an event.
	LogKeyEventType = "event_type"
	// LogKeyJobLock is the name of a job lock.
	LogKeyJobLock = "job_lock"
	// LogKeyJobLockID is the ID of a job lock.
	LogKeyJobLockID = "job_lock_id"
	// LogKeyState is the name of a state, like "held", "lost" or "accepted".
	LogKeyState = "state"
	// LogKeyIndex is the name of a search index, like an Open Search index.
	LogKeyIndex = "index"
	// LogKeyRoute is used to name a route or path.
	LogKeyRoute = "route"
	// LogKeyService is used to specify an RPC service.
	LogKeyService = "service"
	// LogKeyMethod is used to specify an RPC method.
	LogKeyMethod = "method"
	// LogKeySubject is the sub of an authenticated client.
	LogKeySubject = "sub"
	// LogKeyScopes are the scopes of the authenticated client.
	LogKeyScopes = "scopes"
	// LogKeyStatusCode is the HTTP status code used for a response.
	LogKeyStatusCode = "status_code"
	// LogKeyName is the name of a resource.
	LogKeyName = "name"
)

Log attribute keys used throughout the application.

View Source 
const (
	EnvServiceAccountToken         = "SERVICE_ACCOUNT_TOKEN"
	DefaultServiceAccountTokenPath = "/var/run/secrets/kubernetes.io/serviceaccount/token"
	EnvVaultAuthRole               = "VAULT_AUTH_ROLE"
	DefaultAuthRole                = "deploy"
)

Variables

View Source 
var ErrNoAuthorization = errors.New("no authorization provided")

ErrNoAuthorization is used to communicate that authorization was completely missing, rather than being invalid, expired, or malformed.

Functions

func CORSMiddleware added in v0.11.0 

func CORSMiddleware(opts CORSOptions, handler http.Handler) http.Handler

func GetLogMetadata added in v0.5.0 

func GetLogMetadata(ctx context.Context) map[string]any

GetLogMetadata returns the log metatada map for the context.

func HTTPErrorFromResponse 

func HTTPErrorFromResponse(res *http.Response) error

HTTPErrorFromResponse creates a HTTPError from a response struct. This will consume and create a copy of the response body, so don't use it in a scenario where you expect really large error response bodies.

If we fail to copy the response body the error will be joined with the HTTPError.

func IsHTTPErrorWithStatus 

func IsHTTPErrorWithStatus(err error, status int) bool

IsHTTPErrorWithStatus checks if the error (or any error in its tree) is a HTTP error with the given status code.

func IsTwirpErrorCode added in v0.4.0 

func IsTwirpErrorCode(err error, code twirp.ErrorCode) bool

IsTwirpErrorCode checks if any error in the tree is a twirp.Error with the given error code.

func ListenAndServeContext 

func ListenAndServeContext(
	ctx context.Context, server *http.Server,
	shutdownTimeout time.Duration,
) error

ListenAndServeContext will call ListenAndServe() for the provided server and then Shutdown() if the context is cancelled.

Check `errors.Is(err, http.ErrServerClosed)` to differentiate between a graceful server close and other errors.

func LogMetadataMiddleware added in v0.9.6 

func LogMetadataMiddleware(next http.Handler) http.Handler

LogMetadataMiddleware wraps an http.Handler with a middleware that adds a log metadata map to the request context.

func LoggingHooks added in v0.5.0 

func LoggingHooks(
	logger *slog.Logger, scopesFunc func(context.Context) string,
) *twirp.ServerHooks

LoggingHooks creaes a twirp.ServerHooks that will set log metadata for the twirp service and method name, and log error responses.

func MarshalFile added in v0.8.2 

func MarshalFile(path string, o interface{}) (outErr error)

MarshalToFile is a utility function for marshalling a data structore to JSON and write it to a fil. The JSON will be pretty printed.

func NewTwirpMetricsHooks added in v0.4.0 

func NewTwirpMetricsHooks(opts ...TwirpMetricOptionFunc) (*twirp.ServerHooks, error)

NewTwirpMetricsHooks creates new twirp hooks enabling prometheus metrics.

func RHandleFunc 

func RHandleFunc(
	fn func(http.ResponseWriter, *http.Request, httprouter.Params) error,
) httprouter.Handle

RHandleFunc creates a httprouter.Handle from a function that can return an error. If the error is a HTTPError the information it carries will be used for the error response. Otherwise it will be treated as a internal server eror and the error message will be sent as the response.

func ResolveParameter 

func ResolveParameter(
	ctx context.Context, c *cli.Context, src ParameterSource, name string,
) (string, error)

ResolveParameter loads the parameter from the parameter source if "[name]-parameter" has been set for the cli.Context, otherwise the value of "[name]" will be returned.

func SafeClose added in v0.6.2 

func SafeClose(logger *slog.Logger, name string, c io.Closer)

SafeClose can be used with defer to defer the Close of a resource without ignoring the error.

func ScopePrefixRegexp added in v0.12.0 

func ScopePrefixRegexp(prefix string) *regexp.Regexp

func SetAuthInfo added in v0.6.0 

func SetAuthInfo(ctx context.Context, info *AuthInfo) context.Context

SetAuthInfo creates a child context with the given authentication information.

func SetLogMetadata added in v0.5.0 

func SetLogMetadata(ctx context.Context, key string, value any)

SetLogMetadata sets a log metadata value on the context if it has a log metadata map.

func SetUpLogger 

func SetUpLogger(logLevel string, w io.Writer) *slog.Logger

SetUpLogger creates a default JSON logger and sets it as the global logger.

func TwirpErrorToHTTPStatusCode added in v0.8.4 

func TwirpErrorToHTTPStatusCode(err error) int

TwirpErrorToHTTPStatusCode returns the HTTP status code for the given error. If the error is nil 200 will be returned, if the error isn't a twirp.Error 500 will be returned.

func UnmarshalFile 

func UnmarshalFile(path string, o interface{}) (outErr error)

UnmarshalFile is a utility function for reading and unmarshalling a file containing JSON. The parsing will be strict and disallow unknown fields.

func UnmarshalHTTPResource 

func UnmarshalHTTPResource(resURL string, o interface{}) (outErr error)

UnmarshalHTTPResource is a utility function for reading and unmarshalling a HTTP resource. Uses the default HTTP client.

func WithLogMetadata added in v0.5.0 

func WithLogMetadata(ctx context.Context) context.Context

WithLogMetadata creates a child context with a log metadata map.

Types

type AuthInfo added in v0.6.0 

type AuthInfo struct {
	Claims JWTClaims
}

AuthInfo is used to add authentication information to a request context.

func GetAuthInfo added in v0.6.0 

func GetAuthInfo(ctx context.Context) (*AuthInfo, bool)

GetAuthInfo returns the authentication information for the given context.

type AuthInfoParser added in v0.12.0 

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

func NewJWKSAuthInfoParser added in v0.12.0 

func NewJWKSAuthInfoParser(ctx context.Context, jwksUrl string, opts AuthInfoParserOptions) (*AuthInfoParser, error)

func NewStaticAuthInfoParser added in v0.12.0 

func NewStaticAuthInfoParser(key ecdsa.PublicKey, opts AuthInfoParserOptions) *AuthInfoParser

func (*AuthInfoParser) AuthInfoFromHeader added in v0.12.0 

func (p *AuthInfoParser) AuthInfoFromHeader(authorization string) (*AuthInfo, error)

AuthInfoFromHeader extracts the AuthInfo from a HTTP Authorization header. This is a placeholder implementation with a static JWT signing key that only will work with tokens that have the `iss: test` claim.

func (*AuthInfoParser) Valid added in v0.12.0 

func (p *AuthInfoParser) Valid(c JWTClaims) error

Valid validates the jwt.RegisteredClaims.

type AuthInfoParserOptions added in v0.12.0 

type AuthInfoParserOptions struct {
	Audience    string
	Issuer      string
	ScopePrefix string
}

type CORSOptions added in v0.11.0 

type CORSOptions struct {
	AllowInsecure          bool
	AllowInsecureLocalhost bool
	Hosts                  []string
	AllowedMethods         []string
	AllowedHeaders         []string
	MaxAgeSeconds          int
}

type GracefulShutdown added in v0.4.0 

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

GracefulShutdown is a helper that can be used to listen for SIGINT and SIGTERM to gracefully shut down your application.

SIGTERM will trigger a stop, followed by quit after the specified timeout. SIGINT will trigger a immediate quit.

func NewGracefulShutdown added in v0.4.0 

func NewGracefulShutdown(logger *slog.Logger, timeout time.Duration) *GracefulShutdown

NewGracefulShutdown creates a new GracefulShutdown that will wait for `timeout` between "stop" and "quit".

func NewManualGracefulShutdown added in v0.9.1 

func NewManualGracefulShutdown(logger *slog.Logger, timeout time.Duration) *GracefulShutdown

NewManualGracefulShutdown creates a GracefulShutdown instance that doesn't listen to OS signals.

func (*GracefulShutdown) CancelOnQuit added in v0.4.0 

func (gs *GracefulShutdown) CancelOnQuit(ctx context.Context) context.Context

CancelOnQuit returns a child context that will be cancelled when quit is triggered.

func (*GracefulShutdown) CancelOnStop added in v0.4.0 

func (gs *GracefulShutdown) CancelOnStop(ctx context.Context) context.Context

CancelOnStop returns a child context that will be cancelled when stop is triggered.

func (*GracefulShutdown) ShouldQuit added in v0.4.0 

func (gs *GracefulShutdown) ShouldQuit() <-chan struct{}

ShouldQuit returns a channel that will be closed when quit is triggered.

func (*GracefulShutdown) ShouldStop added in v0.4.0 

func (gs *GracefulShutdown) ShouldStop() <-chan struct{}

ShouldStop returns a channel that will be closed when stop is triggered.

func (*GracefulShutdown) Stop added in v0.4.0 

func (gs *GracefulShutdown) Stop()

Stop triggers a stop, which will trigger quit after the configured timeout.

type HTTPClientInstrumentation added in v0.4.0 

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

HTTPClientInstrumentation provides a way to instrument HTTP clients.

func NewHTTPClientIntrumentation added in v0.4.0 

func NewHTTPClientIntrumentation(
	registerer prometheus.Registerer,
) (*HTTPClientInstrumentation, error)

NewHTTPClientIntrumentation registers a set of HTTP client metrics with the provided registerer.

func (*HTTPClientInstrumentation) Client added in v0.4.0 

func (ci *HTTPClientInstrumentation) Client(name string, client *http.Client) error

Client instruments the HTTP client transport with the standard promhttp metrics. The client_requests_total, client_in_flight_requests, and client_request_duration_seconds metrics will be labelled with the client name.

type HTTPError 

type HTTPError struct {
	Status     string
	StatusCode int
	Header     http.Header
	Body       io.Reader
}

HTTPError can be used to describe a non-OK response. Either as an error value in a client that got an error response from a server, or in a server implementation to communicate what the error response to a client should be.

func HTTPErrorf 

func HTTPErrorf(statusCode int, format string, a ...any) *HTTPError

HTTPErrorf creates a HTTPError using a format string.

func NewHTTPError 

func NewHTTPError(statusCode int, message string) *HTTPError

NewHTTPError creates a new HTTPError with the given status code and response message.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

Error implements the error interface.

type HealthServer 

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

HealthServer exposes health endpoints, metrics, and PPROF endpoints.

A HealthServer should never be publicly exposed, as that both could expose sensitive information and could be used to DDOS your application.

Example output for a request to `GET /health/ready`: 

{
  "api_liveness": {
    "ok": false,
    "error": "api liveness endpoint returned non-ok status: 404 Not Found"
  },
  "postgres": {
    "ok": true
  },
  "s3": {
    "ok": true
  }
}

func NewHealthServer 

func NewHealthServer(logger *slog.Logger, addr string) *HealthServer

NewHealthServer creates a new health server that will listen to the provided address.

func NewTestHealthServer added in v0.9.3 

func NewTestHealthServer(logger *slog.Logger) *HealthServer

func (*HealthServer) AddReadyFunction 

func (s *HealthServer) AddReadyFunction(name string, fn ReadyFunc)

AddReadyFunction adds a function that will be called when a client requests "/health/ready".

func (*HealthServer) Close 

func (s *HealthServer) Close() error

Close stops the health server.

func (*HealthServer) ListenAndServe 

func (s *HealthServer) ListenAndServe(ctx context.Context) error

ListenAndServe starts the health server, shutting it down if the context gets cancelled.

type JWTClaims added in v0.6.0 

type JWTClaims struct {
	jwt.RegisteredClaims

	Name  string   `json:"sub_name"`
	Scope string   `json:"scope"`
	Units []string `json:"units,omitempty"`
}

JWTClaims defines the claims that the elephant services understand.

func (JWTClaims) HasAnyScope added in v0.6.0 

func (c JWTClaims) HasAnyScope(names ...string) bool

HasScope returns true if the Scope claim contains any of the named scopes.

func (JWTClaims) HasScope added in v0.6.0 

func (c JWTClaims) HasScope(name string) bool

HasScope returns true if the Scope claim contains the named scope.

type LazySSM 

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

NewLazySSM is a SSM-backed ParameterSource implementation for ResolveParameter().

func NewLazySSM 

func NewLazySSM() *LazySSM

NewLazySSM creates a new SSM ParameterSource.

func (*LazySSM) GetParameterValue 

func (l *LazySSM) GetParameterValue(ctx context.Context, name string) (string, error)

GetParameterValue implements ParameterSource.

type ParameterSource 

type ParameterSource interface {
	GetParameterValue(ctx context.Context, name string) (string, error)
}

ParameterSource should be implemented to support loading of configuration paramaters that should be resolved at run time rather than given as environment variables or flags for the application. This is useful for loading secrets.

func GetParameterSource 

func GetParameterSource(name string) (ParameterSource, error)

GetParameterSource returns a named parameter source.

type ReadyFunc 

type ReadyFunc func(ctx context.Context) error

ReadyFunc is a function that will be called to determine if a service is ready to recieve traffic. It should return a descriptive error that helps with debugging if the underlying check fails.

func LivenessReadyCheck added in v0.6.3 

func LivenessReadyCheck(endpoint string) ReadyFunc

LivenessReadyCheck returns a ReadyFunc that verifies that an endpoint aswers to GET requests with 200 OK.

type TwirpMetricOptionFunc added in v0.4.0 

type TwirpMetricOptionFunc func(opts *TwirpMetricsOptions)

func WithTwirpMetricsCustomerFunc added in v0.9.5 

func WithTwirpMetricsCustomerFunc(fn func(ctx context.Context) string) TwirpMetricOptionFunc

WithTwirpMetricsCustomerFunc sets a function that can be used to return the customer label value for a context.

func WithTwirpMetricsRegisterer added in v0.4.0 

func WithTwirpMetricsRegisterer(reg prometheus.Registerer) TwirpMetricOptionFunc

WithTwirpMetricsRegisterer uses a custom registerer for Twirp metrics.

func WithTwirpMetricsStaticTestLatency added in v0.4.0 

func WithTwirpMetricsStaticTestLatency(latency time.Duration) TwirpMetricOptionFunc

WithTwirpMetricsStaticTestLatency configures the RPC metrics to report a static duration.

type TwirpMetricsOptions added in v0.4.0 

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

type Vault added in v0.9.0 

type Vault struct {
	Client *vault.Client
	// contains filtered or unexported fields
}

Vault is a helper for setting up a Vault client, also implements ParameterSource.

func NewVault added in v0.9.0 

func NewVault() (*Vault, error)

NewVault creates a vault client that can be used as a ParameterSource.

func (*Vault) GetParameterValue added in v0.9.0 

func (v *Vault) GetParameterValue(ctx context.Context, name string) (string, error)

GetParameterValue implements ParameterSource.

func (*Vault) KeepAlive added in v0.9.0 

func (v *Vault) KeepAlive() error

KeepAlive is used to keep the lease on the vault login active, not necessary if you're just reading secrets on startup. Returns an error if the lease is lost or fails to renew. Returns immediately without an error if a token was used to authenticate directly with vault.

func (*Vault) Stop added in v0.9.0 

func (v *Vault) Stop()

Stop the keepalive loop.

Source Files

View all Source files

Directories

Path Synopsis
pg
postgres

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.