xcweaver

README

Service Weaver

Service Weaver is a programming framework for writing, deploying, and managing distributed applications. You can run, test, and debug a Service Weaver application locally on your machine, and then deploy it to the cloud with a single command.

$ go run .                      # Run locally.
$ weaver gke deploy weaver.toml # Run in the cloud.

Visit https://serviceweaver.dev to learn more about Service Weaver.

Installation and Getting Started

Visit https://serviceweaver.dev/docs.html for installation instructions and information on getting started.

Contributing

Please read our contribution guide for details on how to contribute.

Documentation

Overview

Package xcweaver provides the interface for building single-image distributed programs.

A program is composed of a set of Go interfaces called components. Components are recognized by "xcweaver generate" (typically invoked via "go generate"). "xcweaver generate" generates code that allows a component to be invoked over the network. This flexibility allows Service Weaver to decompose the program execution across many processes and machines.

Index

• Constants
• Variables
• func GetLineage(ctx context.Context) ([]byte, error)
• func InstrumentHandler(label string, handler http.Handler) http.Handler
• func InstrumentHandlerFunc(label string, f func(http.ResponseWriter, *http.Request)) http.Handler
• func Run[T any, P PointerToMain[T]](ctx context.Context, app func(context.Context, *T) error) error
• func Transfer(ctx context.Context, lineage []byte) (context.Context, error)
• type Antipode
  • func (a Antipode) Barrier(ctx context.Context) error
  • func (a Antipode) Consume(ctx context.Context, exchange string, key string, stop chan struct{}) (<-chan AntipodeObject, error)
  • func (a Antipode) Read(ctx context.Context, table string, key string) (string, []byte, error)
  • func (a Antipode) String() string
  • func (a Antipode) Write(ctx context.Context, table string, key string, value string) (context.Context, error)
• type AntipodeObject
• type AutoMarshal
  • func (AutoMarshal) WeaverMarshal(*codegen.Encoder)
  • func (AutoMarshal) WeaverUnmarshal(*codegen.Decoder)
• type Implements
  • func (i Implements[T]) Logger(ctx context.Context) *slog.Logger
  • func (i Implements[T]) Weaver() WeaverInfo
• type InstanceOf
• type Listener
  • func (l *Listener) ProxyAddr() string
  • func (l Listener) String() string
• type Main
• type NotRetriable
• type PointerToMain
• type Ref
  • func (r Ref[T]) Get() T
• type RoutedBy
• type Unrouted
• type WeaverInfo
• type WithConfig
  • func (wc *WithConfig[T]) Config() *T
• type WithRouter

Examples

• InstrumentHandler

Constants

const HealthzURL = "/debug/xcweaver/healthz"

HealthzURL is the URL path on which Service Weaver performs health checks. Every application HTTP server must register a handler for this URL path, e.g.:

mux := http.NewServeMux()
mux.HandleFunc(xcweaver.HealthzURL, func(http.ResponseWriter, *http.Request) {
    // ...
})

As a convenience, Service Weaver registers HealthzHandler under this URL path in the default ServerMux, i.e.:

http.HandleFunc(xcweaver.HealthzURL, xcweaver.HealthzHandler)

Variables

var (
	ErrNotFound = errors.New("key not found")
)

var HealthzHandler = func(w http.ResponseWriter, _ *http.Request) {
	fmt.Fprintf(w, "OK")
}

HealthzHandler is a health-check handler that returns an OK status for all incoming HTTP requests.

var RemoteCallError = errors.New("Service Weaver remote call error")

RemoteCallError indicates that a remote component method call failed to execute properly. This can happen, for example, because of a failed machine or a network partition. Here's an illustrative example:

// Call the foo.Foo method.
err := foo.Foo(ctx)
if errors.Is(err, xcweaver.RemoteCallError) {
    // foo.Foo did not execute properly.
} else if err != nil {
    // foo.Foo executed properly, but returned an error.
} else {
    // foo.Foo executed properly and did not return an error.
}

Note that if a method call returns an error with an embedded RemoteCallError, it does NOT mean that the method never executed. The method may have executed partially or fully. Thus, you must be careful retrying method calls that result in a RemoteCallError. Ensuring that all methods are either read-only or idempotent is one way to ensure safe retries, for example.

Functions

func GetLineage

func GetLineage(ctx context.Context) ([]byte, error)

func InstrumentHandler

func InstrumentHandler(label string, handler http.Handler) http.Handler

InstrumentHandler instruments the provided HTTP handler to collect sampled traces and metrics of HTTP request executions. Each trace and metric is labelled with the supplied label. The following metrics are collected:

• serviceweaver_http_request_count: Total number of requests.
• serviceweaver_http_error_count: Total number of 4XX and 5XX replies.
• serviceweaver_http_request_latency_micros: Execution latency in microseconds.
• serviceweaver_http_request_bytes_received: Total number of request bytes.
• serviceweaver_http_request_bytes_returned: Total number of response bytes

Example

var mux http.ServeMux
mux.Handle("/foo", InstrumentHandler("foo", http.HandlerFunc(func(http.ResponseWriter, *http.Request) { /*...*/ })))
mux.Handle("/bar", InstrumentHandler("bar", http.HandlerFunc(func(http.ResponseWriter, *http.Request) { /*...*/ })))
http.ListenAndServe(":9000", &mux)

func InstrumentHandlerFunc

func InstrumentHandlerFunc(label string, f func(http.ResponseWriter, *http.Request)) http.Handler

InstrumentHandlerFunc is identical to InstrumentHandler but takes a function instead of an http.Handler.

func Run

func Run[T any, P PointerToMain[T]](ctx context.Context, app func(context.Context, *T) error) error

Run runs app as a Service Weaver application.

The application is composed of a set of components that include xcweaver.Main as well as any components transitively needed by xcweaver.Main. An instance that implement xcweaver.Main is automatically created by xcweaver.Run and passed to app. Note: other replicas in which xcweaver.Run is called may also create instances of xcweaver.Main.

The type T must be a struct type that contains an embedded `xcweaver.Implements[xcweaver.Main]` field. A value of type T is created, initialized (by calling its Init method if any), and a pointer to the value is passed to app. app contains the main body of the application; it will typically run HTTP servers, etc.

If this process is hosting the `xcweaver.Main` component, Run will call app and will return when app returns. If this process is hosting other components, Run will start those components and never return. Most callers of Run will not do anything (other than possibly logging any returned error) after Run returns.

func main() {
    if err := xcweaver.Run(context.Background(), app); err != nil {
        log.Fatal(err)
    }
}

func Transfer

func Transfer(ctx context.Context, lineage []byte) (context.Context, error)

Types

type Antipode

type Antipode struct {
	Datastore_type antipode.Datastore_type
	Datastore_ID   string
}

func (Antipode) Barrier

func (a Antipode) Barrier(ctx context.Context) error

func (Antipode) Consume

func (a Antipode) Consume(ctx context.Context, exchange string, key string, stop chan struct{}) (<-chan AntipodeObject, error)

func (Antipode) Read

func (a Antipode) Read(ctx context.Context, table string, key string) (string, []byte, error)

func (Antipode) String

func (a Antipode) String() string

func (Antipode) Write

func (a Antipode) Write(ctx context.Context, table string, key string, value string) (context.Context, error)

TO-DO Test this method with values as string, bool, int and struct

type AntipodeObject

type AntipodeObject struct {
	Version string
	Lineage []byte
}

Change for another name?

type AutoMarshal

type AutoMarshal struct{}

AutoMarshal is a type that can be embedded within a struct to indicate that "xcweaver 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 {
    xcweaver.AutoMarshal
    x, y int
}

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

Note, however, that AutoMarshal cannot magically make any type serializable. For example, "xcweaver 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 {
    xcweaver.AutoMarshal
    f func()   // functions are not serializable
    c chan int // chans are not serializable
}

func (AutoMarshal) WeaverMarshal

func (AutoMarshal) WeaverMarshal(*codegen.Encoder)

func (AutoMarshal) WeaverUnmarshal

func (AutoMarshal) WeaverUnmarshal(*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 {
    xcweaver.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 (Implements[T]) Logger

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

Logger returns a logger that associates its log entries with this component. Log entries are labeled with any OpenTelemetry trace id and span id in the provided context.

func (Implements[T]) Weaver

func (i Implements[T]) Weaver() WeaverInfo

Weaver returns runtime information about the deployed application.

type InstanceOf

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

InstanceOf[T] is the interface implemented by a struct that embeds xcweaver.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, Service Weaver automatically initializes the Listener and makes it suitable for receiving network traffic. For example:

type myComponentImpl struct {
    xcweaver.Implements[MyComponent]
    myListener      xcweaver.Listener
    myOtherListener xcweaver.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 `xcweaver:"name"` struct tag to their listener fields, e.g.:

type myComponentImpl struct {
    xcweaver.Implements[MyComponent]
    myListener      xcweaver.Listener
    myOtherListener xcweaver.Listener `xcweaver:"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 `xcweaver:"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 (*Listener) ProxyAddr

func (l *Listener) ProxyAddr() string

ProxyAddr returns the dialable address of the proxy that forwards traffic to this listener, or returns the empty string if there is no such proxy.

func (Listener) String

func (l Listener) String() string

String returns the address clients should dial to connect to the listener; this will be the proxy address if available, otherwise the <host>:<port> for this listener.

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 xcweaver.Implements[xcweaver.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. Service Weaver will automatically fill such a field with a handle to the corresponding component.

func (Ref[T]) Get

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

Get returns a handle to the component of type T.

type RoutedBy

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

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

type Unrouted

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

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

type WeaverInfo

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

WeaverInfo holds runtime information about a deployed application.

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 Service Weaver 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 {
    xcweaver.Implements[Cache]
    xcweaver.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 (*WithConfig[T]) Config

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

Config returns the configuration information for the component that embeds this xcweaver.WithConfig.

Any fields in T that were not present in the application config file will have their default values.

Any fields in the application config file that are not present in T will be flagged as an error at application startup.

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 xcweaver.WithRouter in the component implementation.

type lruCache struct {
	xcweaver.Implements[Cache]
	xcweaver.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{xcweaver.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. Service Weaver 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.