mx

type AutoMarshal ¶

type AutoMarshal struct{}

AutoMarshal is a type that can be embedded within a struct to indicate that "mx generate" should generate serialization methods for the struct.

Named struct types are not serializable by default. However, they can trivially be made serializable by embedding AutoMarshal. For example:

type Pair struct {
    mx.AutoMarshal
    x, y int
}

The AutoMarshal embedding instructs "mx generate" to generate serialization methods for the struct, Pair in this example.

Note, however, that AutoMarshal cannot magically make any type serializable. For example, "mx generate" will raise an error for the following code because the NotSerializable struct is fundamentally not serializable.

// ERROR: NotSerializable cannot be made serializable.
type NotSerializable struct {
    mx.AutoMarshal
    f func()   // functions are not serializable
    c chan int // chans are not serializable
}

func (AutoMarshal) MXMarshal(*codegen.Encoder)

func (AutoMarshal) MXUnmarshal(*codegen.Decoder)

type Implements ¶

type Implements[T any] struct {
	// contains filtered or unexported fields
}

Implements[T] is a type that is be embedded inside a component implementation struct to indicate that the struct implements a component of type T. For example, consider a Cache component.

type Cache interface {
    Get(ctx context.Context, key string) (string, error)
    Put(ctx context.Context, key, value string) error
}

A concrete type that implements the Cache component is written as follows:

type lruCache struct {
    mx.Implements[Cache]
    ...
}

Because Implements is embedded inside the component implementation, methods of Implements are available as methods of the component implementation type and can be invoked directly. For example, given an instance c of type lruCache, we can call c.Logger().

func (i Implements[T]) Logger(ctx context.Context) *slog.Logger

func (i Implements[T]) MX() MXInfo

type InstanceOf ¶

type InstanceOf[T any] interface {
	// contains filtered or unexported methods
}

InstanceOf[T] is the interface implemented by a struct that embeds mx.Implements[T].

type Listener ¶

type Listener struct {
	net.Listener // underlying listener
	// contains filtered or unexported fields
}

Listener is a network listener that can be placed as a field inside a component implementation struct. Once placed, MX automatically initializes the Listener and makes it suitable for receiving network traffic. For example:

type myComponentImpl struct {
    mx.Implements[MyComponent]
    myListener      mx.Listener
    myOtherListener mx.Listener
}

By default, all listeners listen on address ":0". This behavior can be modified by passing options for individual listeners in the application config. For example, to specify local addresses for the above two listeners, the user can add the following lines to the application config file:

[listeners]
myListener      = {local_address = "localhost:9000"}
myOtherListener = {local_address = "localhost:9001"}

Listeners are identified by their field names in the component implementation structs (e.g., myListener and myOtherListener). If the user wishes to assign different names to their listeners, they may do so by adding a `mx:"name"` struct tag to their listener fields, e.g.:

type myComponentImpl struct {
    mx.Implements[MyComponent]
    myListener      mx.Listener
    myOtherListener mx.Listener `mx:"mylistener2"`
}

Listener names must be valid Go identifier names. Listener names must be unique inside a given application binary, regardless of which components they are specified in. For example, it is illegal to declare a Listener field "foo" in two different component implementation structs, unless one is renamed using the `mx:"name"` struct tag.

HTTP servers constructed using this listener are expected to perform health checks on the reserved HealthzURL path. (Note that this URL path is configured to never receive any user traffic.)

func (l *Listener) ProxyAddr() string

func (l Listener) String() string

type MXInfo ¶

type MXInfo struct {
	// Unique identifier for the application deployment.
	DeploymentID string
}

MXInfo holds runtime information about a deployed application.

type Main ¶

type Main interface{}

Main is the interface implemented by an application's main component.

type NotRetriable ¶

type NotRetriable interface{}

type PointerToMain ¶

type PointerToMain[T any] interface {
	*T
	InstanceOf[Main]
}

PointerToMain is a type constraint that asserts *T is an instance of Main (i.e. T is a struct that embeds mx.Implements[mx.Main]).

type Ref ¶

type Ref[T any] struct {
	// contains filtered or unexported fields
}

Ref[T] is a field that can be placed inside a component implementation struct. T must be a component type. MX will automatically fill such a field with a handle to the corresponding component.

func (r Ref[T]) Get() T

type RoutedBy ¶

type RoutedBy[T any] interface {
	// contains filtered or unexported methods
}

RoutedBy[T] is the interface implemented by a struct that embeds mx.RoutedBy[T].

type Unrouted ¶

type Unrouted interface {
	// contains filtered or unexported methods
}

Unrouted is the interface implemented by instances that don't embed mx.WithRouter[T].

type WithConfig ¶

type WithConfig[T any] struct {
	// contains filtered or unexported fields
}

WithConfig[T] is a type that can be embedded inside a component implementation. The MX runtime will take per-component configuration information found in the application config file and use it to initialize the contents of T.

Example ¶

Consider a cache component where the cache size should be configurable. Define a struct that includes the size, associate it with the component implementation, and use it inside the component methods.

type cacheConfig struct
    Size int
}

type cache struct {
    mx.Implements[Cache]
    mx.WithConfig[cacheConfig]
    // ...
}

func (c *cache) Init(context.Context) error {
    // Use c.Config().Size...
    return nil
}

The application config file can specify these values as keys under the full component path.

["example.com/mypkg/Cache"]
Size = 1000

Field Names ¶

You can use `toml` struct tags to specify the name that should be used for a field in a config file. For example, we can change the cacheConfig struct to the following:

type cacheConfig struct
    Size int `toml:"my_custom_name"`
}

And change the config file accordingly:

["example.com/mypkg/Cache"]
my_custom_name = 1000

func (wc *WithConfig[T]) Config() *T

type WithRouter ¶

type WithRouter[T any] struct{}

WithRouter[T] is a type that can be embedded inside a component implementation struct to indicate that calls to a method M on the component must be routed according to the the value returned by T.M().

Example ¶

For example, consider a Cache component that maintains an in-memory cache.

type Cache interface {
    Get(ctx context.Context, key string) (string, error)
    Put(ctx context.Context, key, value string) error
}

We can create a router for the Cache component like this.

type cacheRouter struct{}
func (cacheRouter) Get(_ context.Context, key string) string { return key }
func (cacheRouter) Put(_ context.Context, key, value string) string { return key }

To associate a router with its component, embed mx.WithRouter in the component implementation.

type lruCache struct {
	mx.Implements[Cache]
	mx.WithRouter[cacheRouter]
}

For every component method that needs to be routed (e.g., Get and Put), the associated router should implement an equivalent method (i.e., same name and argument types) whose return type is the routing key. When a component's routed method is invoked, its corresponding router method is invoked to produce a routing key. Method invocations that produce the same key are routed to the same replica.

Routing Keys ¶

A routing key can be any integer (e.g., int, int32), float (i.e. float32, float64), or string; or a struct where all fields are integers, floats, or strings. A struct may also embed AutoMarshal. For example, the following are valid routing keys.

int
int32
float32
float63
string
struct{}
struct{x int}
struct{x int; y string}
struct{mx.AutoMarshal; x int; y string}

Every router method must return the same routing key type. The following, for example, is invalid:

// ERROR: Get returns a string, but Put returns an int.
func (cacheRouter) Get(_ context.Context, key string) string { return key }
func (cacheRouter) Put(_ context.Context, key, value string) int { return 42 }

Semantics ¶

NOTE that routing is done on a best-effort basis. MX will try to route method invocations with the same key to the same replica, but this is not guaranteed. As a corollary, you should never depend on routing for correctness. Only use routing to increase performance in the common case.