Function name syntax

This section explains how to map the exported function names from the component's WIT definition to fully qualified names to be passed to the invocation API or CLI when invoking workers.

Functions and interfaces

The component has a WIT package, specified in the top of its WIT definition.

For example if the component was generated using golem-cli new without specifying a custom package name, it will be:

package golem:component

This package name can optionally specify a package version as well, such as:

package golem:component@0.3.2

The WIT definition should contain a single world (otherwise the world to be used have to be specified for the tools used during compilation). The name of this world does not matter for Golem - it won't be part of the function's fully qualified name.

For example it can be:

world my-component-world {
  // ...
}

This world can either export

• one or more interface
• or one or more functions directly

The following example demonstrates both:

package golem:component;
 
interface api {
  record product-item {
    product-id: string,
    name: string,
    price: float32,
    quantity: u32,
  }
 
  add-item: func(item: product-item) -> ();
  remove-item: func(product-id: string) -> ();
}
 
world my-component-world {
  export api;
  export dump: func() -> result<string, string>;
}

The name of the interface(s) and function(s) are completely user defined, there are no rules to follow other than the syntax rules of WIT itself.

In the above example we have 3 exported functions and we can refer to them with the following fully qualified names, consisting of the package name and the exported path:

• golem:component/api.{add-item}
• golem:component/api.{remove-item}
• golem:component.{dump}

Note that the syntax is the same as the one used for the use statements in the WIT file.

Resources

WIT specifications also allow the definition of resources. These are constructed via special constructors, have methods, and can also have associated static functions. Golem supports exporting resources, enabling an alternative of having a separate worker for each entity. When exporting resources, a single worker may own an arbitrary number of instances of the exported resource, and the method invocations's first parameter must be the resource handle returned by the invoked constructor.

There is a special naming syntax provided by Golem that makes it more convenient to invoke resource constructors and methods. Take the following example:

package golem:component;
 
interface api {
  resource counter {
    constructor(name: string);
    inc-by: func(value: u64);
    get-value: func() -> u64;
 
    merge-counters: static func(counter1: counter, counter2: counter, name: string) -> counter;
  }
}
 
world my-world {
  export api;
}

For this WIT specification, the following function names are valid when using Golem's invocation API or CLI:

• golem:component/api.{counter.new} - refers to the above defined constructor
• golem:component/api.{counter.inc-by}
• golem:component/api.{counter.get-value}
• golem:component/api.{counter.merge-counters}
• golem:component/api.{counter.drop} - special function that drops the instance while the worker continues running

Implicit resource creation

With the above described naming conventions it is possible to manually create instances of resources, and then use the returned resource handle to invoke methods on them.

There is an easier way to work with resources in Golem, that assumes that a given resource instance is associated with the constructor parameters it is created with. This way it is possible to target a specific instance just by using the function name, and the resource instance will be automatically selected or created if it does not exist yet.

To use this feature, pass the target constructor parameters in the function name's resource name part in parentheses. For example, with the above defined counter resource we can immediately create and a new counter and increment it by calling:

• golem:component/api.{counter("my-counter").inc-by}

This will create a new counter instance with the name my-counter and increment it. If the counter with the name my-counter already exists, it will be used.

The syntax for passing inlined parameters to the constructor is using the WebAssembly Value Encoding (opens in a new tab).