Runtime Linking

Overview

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

• the actor
• the capability provider
• the host runtime

From an Actor's Perspective

From the actor'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 actors do not know about (nor should they) which specific capability provider is responsible for fulfilling the contract. The choice of which provider satisfies a contract for an actor is a choice that is always made at runtime.

From a Capability Provider's Perspective

From the capability provider's point of view, it only ever dispatches messages to actors or receives messages from actors. When a link is established for a particular actor, the capability provider can remember that actor's identity and use it for subsequent dispatches. As a result, the only information a capability provider needs is the actor's identity. This identity typically used for managing specific resources on behalf of the actor, 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 an actor:

• The actor's identity. When a request is dispatched to an actor, the host receives the RPC message and passes it to the appropriate actor
• The contract ID (e.g. wasmcloud:keyvalue or wasmcloud:httpserver)
• The capability provider's identity. When an actor makes a request, the host handles dispatching the RPC message to the appropriate capability provider
• The link name of the capability 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 an actor and provider only contained the contract ID, the host runtime would not have enough information to determine where to route the actor'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.