Runtime Linking

Under Construction

🚧 This page is under active renovation for wasmCloud 1.0. Some details may not be aligned with v1.0 during the alpha period. 🚧

Overview

A runtime link is a declared connection from a component to a provider, a provider to a component, or a component to a component. Link definitions are a tuple composed of the component's identity, the provider's identity, and a link name. (If not provided, link names default to default.) There are three different consumers of this relationship:

• the component
• the provider
• the host runtime

From a component's perspective

From the component's point of view, code written using an interface only refers to a contract ID, e.g. wasmcloud:keyvalue (and optionally, a link name, e.g. default). This is because components do not know about (nor should they) which specific provider is responsible for fulfilling the contract. The choice of which provider satisfies a contract for a component is a choice that is always made at runtime.

From a provider's perspective

From the capability provider's point of view, it only ever dispatches messages to—or receives messages from—components. When a link is established for a particular component, the capability provider can remember that component's identity and use it for subsequent dispatches. As a result, the only information a capability provider needs is the component's identity. This identity typically used for managing specific resources on behalf of the component, such as database connections, open TCP sockets, etc.

From the host's perspective

From the wasmCloud host's point of view, it must know the following information when establishing a link between capability provider and a component:

• The component's identity. When a request is dispatched to a component, the host receives the RPC message and passes it to the appropriate component
• The contract ID (e.g. wasmcloud:keyvalue or wasmcloud:httpserver)
• The capability provider's identity. When a component makes a request, the host handles dispatching the RPC message to the appropriate provider
• The link name of the provider, which is defined at provider start-time.

To illustrate the need for link names to disambiguate providers, consider the following scenario:

Assume that we have two capability providers in the lattice that implement the wasmcloud:keyvalue contract: a Redis capability provider with the link name default, an in-memory cache provider running with the link name cache, and a Vault key-value provider with the link name secrets. If the link connecting a component and provider only contained the contract ID, the host runtime would not have enough information to determine where to route the component's request.

Designed for Flexibility at Runtime

Links are first-class citizens of a lattice. A link can be declared (or removed) before or after any of the parties of that link are running. Each time a capability provider is started, it is provided with a list of pre-existing links. Additionally, the provider is notified whenever a new link is declared, or an existing link is removed.

The ability to update links at runtime is a powerful feature of wasmCloud. There are several scenarios where this is useful, including:

• swapping to an alternate capability provider implementation, such as an in-memory cache vs. an external data store
• upgrading a provider, or failing over to a backup provider
• routing requests to a provider running with specific characteristics, such as locality or configuration

note

This design has a couple interesting implications. The first is that "order of operations" does not matter: while configuring an application, low-level commands to set links and start resources can arrive in any order. The second is that all capability providers must treat messages to set/remove links as idempotent.