fxutil

Documentation

Overview

Package fxutil provides utilities for interacting with fx.

Index

• func FxAgentBase() fx.Option
• func FxLifecycleAdapter() fx.Option
• func FxLoggingOption() fx.Option
• func GetAndFilterGroup[S ~[]E, E any](group S) S
• func OneShot(oneShotFunc interface{}, opts ...fx.Option) error
• func ProvideComponentConstructor(compCtorFunc interface{}) fx.Option
• func ProvideOptional[T any]() fx.Option
• func Run(opts ...fx.Option) error
• func TemporaryAppTimeouts() fx.Option
• func UnwrapIfErrArgumentsFailed(err error) error
• type BundleOptions
  • func Bundle(opts ...fx.Option) BundleOptions
• type Module
  • func Component(opts ...fx.Option) Module

Functions

func FxAgentBase

func FxAgentBase() fx.Option

FxAgentBase returns all of our adapters from compdef types to fx types

func FxLifecycleAdapter

func FxLifecycleAdapter() fx.Option

FxLifecycleAdapter creates an fx.Option to adapt from compdef.Lifecycle to fx.Lifecycle

func FxLoggingOption

func FxLoggingOption() fx.Option

FxLoggingOption creates an fx.Option to configure the Fx logger, either to do nothing (the default) or to log to the console (when TRACE_FX is set).

func GetAndFilterGroup

func GetAndFilterGroup[S ~[]E, E any](group S) S

GetAndFilterGroup filters 'zero' values from an FX group.

A 'zero' value, nil in most cases, can be injected into a group whem a component declares returning a element for that group but don't actually creates the element. This is common pattern with component that can be disabled or partially enabled.

This should be called in every component's constructor that requires an FX group as a dependency.

func OneShot

func OneShot(oneShotFunc interface{}, opts ...fx.Option) error

OneShot runs the given function in an fx.App using the supplied options. The function's arguments are supplied by Fx and can be any provided type. The function must return `error` or nothing.

The resulting app starts all components, then invokes the function, then immediately shuts down. This is typically used for command-line tools like `agent status`.

func ProvideComponentConstructor

func ProvideComponentConstructor(compCtorFunc interface{}) fx.Option

ProvideComponentConstructor takes as input a Component constructor function that uses plain (non-fx aware) structs as its argument and return value, and returns an fx.Provide'd Option that will properly include that Component into the fx constructor graph.

For example, given:

type Provides struct {
    My MyComponent
}
type Requires struct {
    Dep MyDependency
}
func NewComponent(reqs Requires) Provides { ... }

then:

ProvideComponentConstructor(NewComponent)

will create these anonymous types:

type FxAwareProvides struct {
    fx.Out
    My MyComponent
}
type FxAwareRequires struct {
    fx.In
    Dep MyDependency
}

and then Provide those types into fx's dependency graph

func ProvideOptional

func ProvideOptional[T any]() fx.Option

ProvideOptional takes a type parameter and fx.Provide's a NewOption wrapper for that type

func Run

func Run(opts ...fx.Option) error

Run runs an fx.App using the supplied options, returning any errors.

This differs from fx.App#Run in that it returns errors instead of exiting the process.

func TemporaryAppTimeouts

func TemporaryAppTimeouts() fx.Option

TemporaryAppTimeouts returns new fx Start/Stop timeout options, defaulting to 5 minutes.

The start timeout can be overridden with the DD_FX_START_TIMEOUT_SECONDS environment variable. The stop timeout can be overridden with the DD_FX_STOP_TIMEOUT_SECONDS environment variable.

Before fx the Agent did not have any start/stop timeouts, it would hang indefinitely. As we have have been adding more fx.Hooks we began hitting flaky tests with expired fx timeouts. We use a large timeout value by default to minimize the chance that customers will be impacted by the timeout. However, note that most platforms service managers send SIGKILL after a timeout

• upstart default is 5 seconds
• see pkg/util/winutil/servicemain/servicemain.go:Service.HardStopTimeout

We can revisit this once we can better characterize the agent start/stop behavior and be intentional about timeout values

func UnwrapIfErrArgumentsFailed

func UnwrapIfErrArgumentsFailed(err error) error

UnwrapIfErrArgumentsFailed unwrap the error if the error was returned by an FX invoke method otherwise return the error.

Types

type BundleOptions

type BundleOptions struct {
	fx.Option
	Options []fx.Option
}

BundleOptions is a fx.Module for Bundle with an exported field "Options" to list options

func Bundle

func Bundle(opts ...fx.Option) BundleOptions

Bundle is a simple wrapper around fx.Module that automatically determines the bundle name.

type Module

type Module struct {
	fx.Option
	Options []fx.Option
}

Module is a fx.Module for Component with an exported field "Options" to list options

func Component

func Component(opts ...fx.Option) Module

Component is a simple wrapper around fx.Module that automatically determines the component name.