Runtime Linking

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 unidirectional, having both a source and a target, and specifying the relevant WASI interfaces.

From the component's point of view, code only refers to an interface, e.g. wasi-keyvalue. This is because components do not know about (nor should they) which specific provider is on the other side of a link.

From a 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 provider can remember that component's identity and use it for subsequent dispatches. As a result, the only information a provider needs is the component's identity. This identity is typically used for managing specific resources on behalf of the component, such as database connections, open TCP sockets, etc.

Exploring a link definition

Runtime links are defined in wadm manifests. Here is an example of a definition for a link from a component to a provider:

yaml

- type: link
  properties:
    target: kvredis
    namespace: wasi
    package: keyvalue
    interfaces:
      - atomic
      - eventual
    target_config:
      - name: redis-connect-local
        properties:
          URL: redis://127.0.0.1:6379

In addition to a target, the link definition has properties including...

• namespace, which in the example above refers to wasi
• package, which specifies the particular interface group used
• interfaces, which lists specific interfaces from wasi-keyvalue
• target_config, defining configuration data to pass to a provider

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 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

"Order of operations" doesn't matter in runtime linking: while configuring an application, low-level commands to set links and start resources can arrive in any order. Additionally, all providers must treat messages to set/remove links as idempotent.